update docstring

Author: Jonathan Esterhazy

src/sagemaker/fw_utils.py

@@ -12,15 +12,15 @@
 # language governing permissions and limitations under the License.
 from __future__ import absolute_import
 
+from collections import namedtuple
+
 import os
 import re
+import sagemaker.utils
 import shutil
 import tempfile
-from collections import namedtuple
 from six.moves.urllib.parse import urlparse
 
-import sagemaker.utils
-
 _TAR_SOURCE_FILENAME = 'source.tar.gz'
 
 UploadedCode = namedtuple('UserCode', ['s3_prefix', 'script_name'])
@@ -112,24 +112,32 @@ def validate_source_dir(script, directory):
 
 
 def tar_and_upload_dir(session, bucket, s3_key_prefix, script, directory, dependencies=None):
-    """Pack and upload source files to S3 only if directory is empty or local.
+    """Package source files and upload a compress tar file to S3. The S3 location will be
+    ``s3://<bucket>/s3_key_prefix/sourcedir.tar.gz``.
+
+    If directory is an S3 URI, an UploadedCode object will be returned, but nothing will be
+    uploaded to S3 (this allow reuse of code already in S3).
+
+    If directory is None, the script will be added to the archive at ``./<basename of script>``.
 
-    Note:
-        If the directory points to S3 no action is taken.
+    If directory is not None, the (recursive) contents of the directory will be added to
+    the archive. directory is treated as the base path of the archive, and the script name is
+    assumed to be a filename or relative path inside the directory.
 
     Args:
         session (boto3.Session): Boto session used to access S3.
         bucket (str): S3 bucket to which the compressed file is uploaded.
         s3_key_prefix (str): Prefix for the S3 key.
-        script (str): Script filename.
-        directory (str or None): Directory containing the source file. If it starts with
-                                    "s3://", no action is taken.
-        dependencies (List[str]): A list of paths to directories (absolute or relative)
+        script (str): Script filename or path.
+        directory (str): Optional. Directory containing the source file. If it starts with "s3://",
+            no action is taken.
+        dependencies (List[str]): Optional. A list of paths to directories (absolute or relative)
                                 containing additional libraries that will be copied into
                                 /opt/ml/lib
 
     Returns:
-        sagemaker.fw_utils.UserCode: An object with the S3 bucket and key (S3 prefix) and script name.
+        sagemaker.fw_utils.UserCode: An object with the S3 bucket and key (S3 prefix) and
+            script name.
     """
     if directory and directory.lower().startswith('s3://'):
         return UploadedCode(s3_prefix=directory, script_name=os.path.basename(script))
@@ -141,7 +149,8 @@ def tar_and_upload_dir(session, bucket, s3_key_prefix, script, directory, depend
 
     try:
         source_files = _list_files_to_compress(script, directory) + dependencies
-        tar_file = sagemaker.utils.create_tar_file(source_files, os.path.join(tmp, _TAR_SOURCE_FILENAME))
+        tar_file = sagemaker.utils.create_tar_file(source_files,
+                                                   os.path.join(tmp, _TAR_SOURCE_FILENAME))
 
         session.resource('s3').Object(bucket, key).upload_file(tar_file)
     finally: