From 43ce8ed2bdbfb6f081de4992627d299185a53a70 Mon Sep 17 00:00:00 2001 From: Alessandra Romero <24320222+alexgromero@users.noreply.github.com> Date: Wed, 30 Oct 2024 16:45:08 -0400 Subject: [PATCH] Bucket name doc updates (#3292) --- botocore/config.py | 4 +-- botocore/signers.py | 53 ++++++++++++++++++++----------- docs/source/client_upgrades.rst | 12 +++---- docs/source/topics/paginators.rst | 8 ++--- 4 files changed, 46 insertions(+), 31 deletions(-) diff --git a/botocore/config.py b/botocore/config.py index 587dc95ad8..eee55bb06d 100644 --- a/botocore/config.py +++ b/botocore/config.py @@ -115,10 +115,10 @@ class Config: * ``virtual`` -- Addressing style is always virtual. The name of the bucket must be DNS compatible or an exception will be thrown. - Endpoints will be addressed as such: ``mybucket.s3.amazonaws.com`` + Endpoints will be addressed as such: ``amzn-s3-demo-bucket.s3.amazonaws.com`` * ``path`` -- Addressing style is always by path. Endpoints will be - addressed as such: ``s3.amazonaws.com/mybucket`` + addressed as such: ``s3.amazonaws.com/amzn-s3-demo-bucket`` * ``us_east_1_regional_endpoint`` -- Refers to what S3 endpoint to use when the region is configured to be us-east-1. Values must be a diff --git a/botocore/signers.py b/botocore/signers.py index 89319af10b..14692d16f4 100644 --- a/botocore/signers.py +++ b/botocore/signers.py @@ -576,11 +576,14 @@ def generate_presigned_post( :type conditions: list :param conditions: A list of conditions to include in the policy. Each element can be either a list or a structure. For example: - [ - {"acl": "public-read"}, - {"bucket": "mybucket"}, - ["starts-with", "$key", "mykey"] - ] + + .. code:: python + + [ + {"acl": "public-read"}, + {"bucket": "amzn-s3-demo-bucket"}, + ["starts-with", "$key", "mykey"] + ] :type expires_in: int :param expires_in: The number of seconds the presigned post is valid @@ -595,12 +598,17 @@ def generate_presigned_post( the form fields and respective values to use when submitting the post. For example: - {'url': 'https://mybucket.s3.amazonaws.com - 'fields': {'acl': 'public-read', + .. code:: python + + { + 'url': 'https://amzn-s3-demo-bucket.s3.amazonaws.com', + 'fields': { + 'acl': 'public-read', 'key': 'mykey', 'signature': 'mysignature', - 'policy': 'mybase64 encoded policy'} - } + 'policy': 'mybase64 encoded policy' + } + } """ if fields is None: fields = {} @@ -751,11 +759,13 @@ def generate_presigned_post( :param Conditions: A list of conditions to include in the policy. Each element can be either a list or a structure. For example: - [ - {"acl": "public-read"}, - ["content-length-range", 2, 5], - ["starts-with", "$success_action_redirect", ""] - ] + .. code:: python + + [ + {"acl": "public-read"}, + ["content-length-range", 2, 5], + ["starts-with", "$success_action_redirect", ""] + ] Conditions that are included may pertain to acl, content-length-range, Cache-Control, Content-Type, @@ -764,7 +774,7 @@ def generate_presigned_post( and/or x-amz-meta-. Note that if you include a condition, you must specify - the a valid value in the fields dictionary as well. A value will + a valid value in the fields dictionary as well. A value will not be added automatically to the fields dictionary based on the conditions. @@ -778,12 +788,17 @@ def generate_presigned_post( the form fields and respective values to use when submitting the post. For example: - {'url': 'https://mybucket.s3.amazonaws.com - 'fields': {'acl': 'public-read', + .. code:: python + + { + 'url': 'https://amzn-s3-demo-bucket.s3.amazonaws.com', + 'fields': { + 'acl': 'public-read', 'key': 'mykey', 'signature': 'mysignature', - 'policy': 'mybase64 encoded policy'} - } + 'policy': 'mybase64 encoded policy' + } + } """ bucket = Bucket key = Key diff --git a/docs/source/client_upgrades.rst b/docs/source/client_upgrades.rst index 74adbe22ea..781df3a221 100644 --- a/docs/source/client_upgrades.rst +++ b/docs/source/client_upgrades.rst @@ -21,7 +21,7 @@ Below is an example of the old interface: s3 = session.get_service('s3') endpoint = s3.get_endpoint('us-west-2') list_objects = s3.get_operation('ListObjects') - http, response = list_objects.call(endpoint, Bucket='mybucket') + http, response = list_objects.call(endpoint, Bucket='amzn-s3-demo-bucket') if http.status_code == 200: print("Contents: %s" % response['Contents]) else: @@ -36,7 +36,7 @@ Here's an example of the newer (preferred) client interface: import botocore.session session = botocore.session.get_session() s3 = session.create_client('s3', 'us-west-2') - response = s3.list_objects(Bucket='mybucket') + response = s3.list_objects(Bucket='amzn-s3-demo-bucket') print("Contents: %s" % response['Contents']) @@ -132,22 +132,22 @@ Use a single client to make multiple API calls. endpoint = service.get_endpoint('us-west-2') operation = service.get_operation('ListObjects') head_object = service.get_operation('HeadObject') - parsed = operation.call(endpoint, Bucket='mybucket')[1] + parsed = operation.call(endpoint, Bucket='amzn-s3-demo-bucket')[1] for obj in parsed['Contents']: name = obj['Key'] # Use existing connection be passing in the same endpoint. - print(head_object.call(endpoint, Bucket='mybucket', Key=name)) + print(head_object.call(endpoint, Bucket='amzn-s3-demo-bucket', Key=name)) **New** .. code-block:: python s3 = session.get_client('s3', 'us-west-2') - for obj in s3.list_objects(Bucket='mybucket')['Contents']: + for obj in s3.list_objects(Bucket='amzn-s3-demo-bucket')['Contents']: name = obj['Key'] # Using the same client will reuse any existing HTTP # connections the client was using. - print(s3.head_object(Bucket='mybucket', Key=name)) + print(s3.head_object(Bucket='amzn-s3-demo-bucket', Key=name)) Operation and Method Names diff --git a/docs/source/topics/paginators.rst b/docs/source/topics/paginators.rst index fba76b713a..edab8fe68d 100644 --- a/docs/source/topics/paginators.rst +++ b/docs/source/topics/paginators.rst @@ -33,7 +33,7 @@ underlying API operation. The ``paginate`` method then returns an iterable paginator = client.get_paginator('list_objects') # Create a PageIterator from the Paginator - page_iterator = paginator.paginate(Bucket='my-bucket') + page_iterator = paginator.paginate(Bucket='amzn-s3-demo-bucket') for page in page_iterator: print(page['Contents']) @@ -48,7 +48,7 @@ the pages of API operation results. The ``paginate`` method accepts a pagination:: paginator = client.get_paginator('list_objects') - page_iterator = paginator.paginate(Bucket='my-bucket', + page_iterator = paginator.paginate(Bucket='amzn-s3-demo-bucket', PaginationConfig={'MaxItems': 10}) ``MaxItems`` @@ -83,7 +83,7 @@ to the client:: session = botocore.session.get_session() client = session.create_client('s3', region_name='us-west-2') paginator = client.get_paginator('list_objects') - operation_parameters = {'Bucket': 'my-bucket', + operation_parameters = {'Bucket': 'amzn-s3-demo-bucket', 'Prefix': 'foo/baz'} page_iterator = paginator.paginate(**operation_parameters) for page in page_iterator: @@ -101,7 +101,7 @@ JMESPath expressions that are applied to each page of results through the .. code-block:: python paginator = client.get_paginator('list_objects') - page_iterator = paginator.paginate(Bucket='my-bucket') + page_iterator = paginator.paginate(Bucket='amzn-s3-demo-bucket') filtered_iterator = page_iterator.search("Contents[?Size > `100`][]") for key_data in filtered_iterator: print(key_data)