Document all 8 upload_file() and download_file() methods

boto3/s3/inject.py

@@ -53,6 +53,18 @@ def bucket_load(self, *args, **kwargs):
 
 def upload_file(self, Filename, Bucket, Key, ExtraArgs=None,
                 Callback=None, Config=None):
+    """Upload a file to an S3 object.
+
+    Usage::
+
+        import boto3
+        s3 = boto3.resource('s3')
+        s3.meta.client.upload_file('/tmp/hello.txt', 'mybucket', 'hello.txt')
+
+    Similar behavior as S3Transfer's upload_file() method,
+    except that parameters are capitalized. Detailed examples can be found at
+    :ref:`S3Transfer's Usage <ref_s3transfer_usage>`.
+    """
     transfer = S3Transfer(self, Config)
     return transfer.upload_file(
         filename=Filename, bucket=Bucket, key=Key,
@@ -61,6 +73,18 @@ def upload_file(self, Filename, Bucket, Key, ExtraArgs=None,
 
 def download_file(self, Bucket, Key, Filename, ExtraArgs=None,
                   Callback=None, Config=None):
+    """Download an S3 object to a file.
+
+    Usage::
+
+        import boto3
+        s3 = boto3.resource('s3')
+        s3.meta.client.download_file('mybucket', 'hello.txt', '/tmp/hello.txt')
+
+    Similar behavior as S3Transfer's download_file() method,
+    except that parameters are capitalized. Detailed examples can be found at
+    :ref:`S3Transfer's Usage <ref_s3transfer_usage>`.
+    """
     transfer = S3Transfer(self, Config)
     return transfer.download_file(
         bucket=Bucket, key=Key, filename=Filename,
@@ -69,31 +93,75 @@ def download_file(self, Bucket, Key, Filename, ExtraArgs=None,
 
 def bucket_upload_file(self, Filename, Key,
                        ExtraArgs=None, Callback=None, Config=None):
-    """Upload a file to an S3 object."""
+    """Upload a file to an S3 object.
+
+    Usage::
+
+        import boto3
+        s3 = boto3.resource('s3')
+        s3.Bucket('mybucket').upload_file('/tmp/hello.txt', 'hello.txt')
+
+    Similar behavior as S3Transfer's upload_file() method,
+    except that parameters are capitalized. Detailed examples can be found at
+    :ref:`S3Transfer's Usage <ref_s3transfer_usage>`.
+    """
     return self.meta.client.upload_file(
         Filename=Filename, Bucket=self.name, Key=Key,
         ExtraArgs=ExtraArgs, Callback=Callback, Config=Config)
 
 
 def bucket_download_file(self, Key, Filename,
                          ExtraArgs=None, Callback=None, Config=None):
-    """Download an S3 object to a file."""
+    """Download an S3 object to a file.
+
+    Usage::
+
+        import boto3
+        s3 = boto3.resource('s3')
+        s3.Bucket('mybucket').download_file('hello.txt', '/tmp/hello.txt')
+
+    Similar behavior as S3Transfer's download_file() method,
+    except that parameters are capitalized. Detailed examples can be found at
+    :ref:`S3Transfer's Usage <ref_s3transfer_usage>`.
+    """
     return self.meta.client.download_file(
         Bucket=self.name, Key=Key, Filename=Filename,
         ExtraArgs=ExtraArgs, Callback=Callback, Config=Config)
 
 
 def object_upload_file(self, Filename,
                        ExtraArgs=None, Callback=None, Config=None):
-    """Upload a file to an S3 object."""
+    """Upload a file to an S3 object.
+
+    Usage::
+
+        import boto3
+        s3 = boto3.resource('s3')
+        s3.Object('mybucket', 'hello.txt').upload_file('/tmp/hello.txt')
+
+    Similar behavior as S3Transfer's upload_file() method,
+    except that parameters are capitalized. Detailed examples can be found at
+    :ref:`S3Transfer's Usage <ref_s3transfer_usage>`.
+    """
     return self.meta.client.upload_file(
         Filename=Filename, Bucket=self.bucket_name, Key=self.key,
         ExtraArgs=ExtraArgs, Callback=Callback, Config=Config)
 
 
 def object_download_file(self, Filename,
                          ExtraArgs=None, Callback=None, Config=None):
-    """Download an S3 object to a file."""
+    """Download an S3 object to a file.
+
+    Usage::
+
+        import boto3
+        s3 = boto3.resource('s3')
+        s3.Object('mybucket', 'hello.txt').download_file('/tmp/hello.txt')
+
+    Similar behavior as S3Transfer's download_file() method,
+    except that parameters are capitalized. Detailed examples can be found at
+    :ref:`S3Transfer's Usage <ref_s3transfer_usage>`.
+    """
     return self.meta.client.download_file(
         Bucket=self.bucket_name, Key=self.key, Filename=Filename,
         ExtraArgs=ExtraArgs, Callback=Callback, Config=Config)

boto3/s3/transfer.py

@@ -38,6 +38,8 @@
 time.
 
 
+.. _ref_s3transfer_usage:
+
 Usage
 =====
 
@@ -606,6 +608,11 @@ def __init__(self, client, config=None, osutil=None):
 
     def upload_file(self, filename, bucket, key,
                     callback=None, extra_args=None):
+        """Upload a file to an S3 object.
+
+        Variants have also been injected into S3 client, Bucket and Object.
+        You don't have to use S3Transfer.upload_file() directly.
+        """
         if extra_args is None:
             extra_args = {}
         self._validate_all_known_args(extra_args, self.ALLOWED_UPLOAD_ARGS)
@@ -636,11 +643,12 @@ def download_file(self, bucket, key, filename, extra_args=None,
                       callback=None):
         """Download an S3 object to a file.
 
-        This method will issue a ``head_object`` request to determine
-        the size of the S3 object.  This is used to determine if the
-        object is downloaded in parallel.
-
+        Variants have also been injected into S3 client, Bucket and Object.
+        You don't have to use S3Transfer.download_file() directly.
         """
+        # This method will issue a ``head_object`` request to determine
+        # the size of the S3 object.  This is used to determine if the
+        # object is downloaded in parallel.
         if extra_args is None:
             extra_args = {}
         self._validate_all_known_args(extra_args, self.ALLOWED_DOWNLOAD_ARGS)