From a59b6a09ee9fdcac001cf9e0b13264ef0bde019e Mon Sep 17 00:00:00 2001 From: Ray Luo Date: Sat, 19 Sep 2015 13:03:21 -0700 Subject: [PATCH] Document all 8 upload_file() and download_file() methods --- boto3/s3/inject.py | 76 +++++++++++++++++++++++++++++++++++++++++--- boto3/s3/transfer.py | 16 +++++++--- 2 files changed, 84 insertions(+), 8 deletions(-) diff --git a/boto3/s3/inject.py b/boto3/s3/inject.py index 0793eaa203..02a7a68df1 100644 --- a/boto3/s3/inject.py +++ b/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 `. + """ 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 `. + """ transfer = S3Transfer(self, Config) return transfer.download_file( bucket=Bucket, key=Key, filename=Filename, @@ -69,7 +93,18 @@ 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 `. + """ return self.meta.client.upload_file( Filename=Filename, Bucket=self.name, Key=Key, ExtraArgs=ExtraArgs, Callback=Callback, Config=Config) @@ -77,7 +112,18 @@ def bucket_upload_file(self, Filename, Key, 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 `. + """ return self.meta.client.download_file( Bucket=self.name, Key=Key, Filename=Filename, ExtraArgs=ExtraArgs, Callback=Callback, Config=Config) @@ -85,7 +131,18 @@ def bucket_download_file(self, Key, Filename, 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 `. + """ return self.meta.client.upload_file( Filename=Filename, Bucket=self.bucket_name, Key=self.key, ExtraArgs=ExtraArgs, Callback=Callback, Config=Config) @@ -93,7 +150,18 @@ def object_upload_file(self, Filename, 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 `. + """ return self.meta.client.download_file( Bucket=self.bucket_name, Key=self.key, Filename=Filename, ExtraArgs=ExtraArgs, Callback=Callback, Config=Config) diff --git a/boto3/s3/transfer.py b/boto3/s3/transfer.py index 15f85d9cf3..6ec5ad9e6b 100644 --- a/boto3/s3/transfer.py +++ b/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)