Add example and links for ExtraArgs (#3146)

* add s3 example for downloading object version
boto · Feb 10, 2022 · e2de70f · e2de70f
1 parent f5e1b83
commit e2de70f
Show file tree

Hide file tree

Showing 2 changed files with 47 additions and 15 deletions.
diff --git a/boto3/examples/s3.rst b/boto3/examples/s3.rst
@@ -144,3 +144,20 @@ Boto3 will automatically compute this value for us.
                              SSECustomerAlgorithm='AES256')
     print("Done, response body:")
     print(response['Body'].read())
+
+
+Downloading a specific version of an S3 object
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+This example shows how to download a specific version of an
+S3 object.
+
+.. code-block:: python
+
+    import boto3
+    s3 = boto3.client('s3')
+
+    s3.download_file(
+        "bucket-name", "key-name", "tmp.txt",
+        ExtraArgs={"VersionId": "my-version-id"}
+    )
diff --git a/boto3/s3/inject.py b/boto3/s3/inject.py
@@ -116,7 +116,8 @@ def upload_file(self, Filename, Bucket, Key, ExtraArgs=None,
 
     :type ExtraArgs: dict
     :param ExtraArgs: Extra arguments that may be passed to the
-        client operation.
+        client operation. For allowed upload arguments see
+        boto3.s3.transfer.S3Transfer.ALLOWED_UPLOAD_ARGS.
 
     :type Callback: function
     :param Callback: A method which takes a number of bytes transferred to
@@ -157,7 +158,8 @@ def download_file(self, Bucket, Key, Filename, ExtraArgs=None,
 
     :type ExtraArgs: dict
     :param ExtraArgs: Extra arguments that may be passed to the
-        client operation.
+        client operation. For allowed download arguments see
+        boto3.s3.transfer.S3Transfer.ALLOWED_DOWNLOAD_ARGS.
 
     :type Callback: function
     :param Callback: A method which takes a number of bytes transferred to
@@ -195,7 +197,8 @@ def bucket_upload_file(self, Filename, Key,
 
     :type ExtraArgs: dict
     :param ExtraArgs: Extra arguments that may be passed to the
-        client operation.
+        client operation. For allowed upload arguments see
+        boto3.s3.transfer.S3Transfer.ALLOWED_UPLOAD_ARGS.
 
     :type Callback: function
     :param Callback: A method which takes a number of bytes transferred to
@@ -232,7 +235,8 @@ def bucket_download_file(self, Key, Filename,
 
     :type ExtraArgs: dict
     :param ExtraArgs: Extra arguments that may be passed to the
-        client operation.
+        client operation. For allowed download arguments see
+        boto3.s3.transfer.S3Transfer.ALLOWED_DOWNLOAD_ARGS.
 
     :type Callback: function
     :param Callback: A method which takes a number of bytes transferred to
@@ -266,7 +270,8 @@ def object_upload_file(self, Filename,
 
     :type ExtraArgs: dict
     :param ExtraArgs: Extra arguments that may be passed to the
-        client operation.
+        client operation. For allowed upload arguments see
+        boto3.s3.transfer.S3Transfer.ALLOWED_UPLOAD_ARGS.
 
     :type Callback: function
     :param Callback: A method which takes a number of bytes transferred to
@@ -300,7 +305,8 @@ def object_download_file(self, Filename,
 
     :type ExtraArgs: dict
     :param ExtraArgs: Extra arguments that may be passed to the
-        client operation.
+        client operation. For allowed download arguments see
+        boto3.s3.transfer.S3Transfer.ALLOWED_DOWNLOAD_ARGS.
 
     :type Callback: function
     :param Callback: A method which takes a number of bytes transferred to
@@ -347,7 +353,8 @@ def copy(self, CopySource, Bucket, Key, ExtraArgs=None, Callback=None,
 
     :type ExtraArgs: dict
     :param ExtraArgs: Extra arguments that may be passed to the
-        client operation
+        client operation. For allowed download arguments see
+        boto3.s3.transfer.S3Transfer.ALLOWED_DOWNLOAD_ARGS.
 
     :type Callback: function
     :param Callback: A method which takes a number of bytes transferred to
@@ -410,7 +417,8 @@ def bucket_copy(self, CopySource, Key, ExtraArgs=None, Callback=None,
 
     :type ExtraArgs: dict
     :param ExtraArgs: Extra arguments that may be passed to the
-        client operation
+        client operation. For allowed download arguments see
+        boto3.s3.transfer.S3Transfer.ALLOWED_DOWNLOAD_ARGS.
 
     :type Callback: function
     :param Callback: A method which takes a number of bytes transferred to
@@ -460,7 +468,8 @@ def object_copy(self, CopySource, ExtraArgs=None, Callback=None,
 
     :type ExtraArgs: dict
     :param ExtraArgs: Extra arguments that may be passed to the
-        client operation
+        client operation. For allowed download arguments see
+        boto3.s3.transfer.S3Transfer.ALLOWED_DOWNLOAD_ARGS.
 
     :type Callback: function
     :param Callback: A method which takes a number of bytes transferred to
@@ -512,7 +521,8 @@ def upload_fileobj(self, Fileobj, Bucket, Key, ExtraArgs=None,
 
     :type ExtraArgs: dict
     :param ExtraArgs: Extra arguments that may be passed to the
-        client operation.
+        client operation. For allowed upload arguments see
+        boto3.s3.transfer.S3Transfer.ALLOWED_UPLOAD_ARGS.
 
     :type Callback: function
     :param Callback: A method which takes a number of bytes transferred to
@@ -567,7 +577,8 @@ def bucket_upload_fileobj(self, Fileobj, Key, ExtraArgs=None,
 
     :type ExtraArgs: dict
     :param ExtraArgs: Extra arguments that may be passed to the
-        client operation.
+        client operation. For allowed upload arguments see
+        boto3.s3.transfer.S3Transfer.ALLOWED_UPLOAD_ARGS.
 
     :type Callback: function
     :param Callback: A method which takes a number of bytes transferred to
@@ -607,7 +618,8 @@ def object_upload_fileobj(self, Fileobj, ExtraArgs=None, Callback=None,
 
     :type ExtraArgs: dict
     :param ExtraArgs: Extra arguments that may be passed to the
-        client operation.
+        client operation. For allowed upload arguments see
+        boto3.s3.transfer.S3Transfer.ALLOWED_UPLOAD_ARGS.
 
     :type Callback: function
     :param Callback: A method which takes a number of bytes transferred to
@@ -651,7 +663,8 @@ def download_fileobj(self, Bucket, Key, Fileobj, ExtraArgs=None,
 
     :type ExtraArgs: dict
     :param ExtraArgs: Extra arguments that may be passed to the
-        client operation.
+        client operation. For allowed download arguments see
+        boto3.s3.transfer.S3Transfer.ALLOWED_DOWNLOAD_ARGS.
 
     :type Callback: function
     :param Callback: A method which takes a number of bytes transferred to
@@ -706,7 +719,8 @@ def bucket_download_fileobj(self, Key, Fileobj, ExtraArgs=None,
 
     :type ExtraArgs: dict
     :param ExtraArgs: Extra arguments that may be passed to the
-        client operation.
+        client operation. For allowed download arguments see
+        boto3.s3.transfer.S3Transfer.ALLOWED_DOWNLOAD_ARGS.
 
     :type Callback: function
     :param Callback: A method which takes a number of bytes transferred to
@@ -746,7 +760,8 @@ def object_download_fileobj(self, Fileobj, ExtraArgs=None, Callback=None,
 
     :type ExtraArgs: dict
     :param ExtraArgs: Extra arguments that may be passed to the
-        client operation.
+        client operation. For allowed download arguments see
+        boto3.s3.transfer.S3Transfer.ALLOWED_DOWNLOAD_ARGS.
 
     :type Callback: function
     :param Callback: A method which takes a number of bytes transferred to