Merge branch 'release-1.37.0'

* release-1.37.0: Bumping version to 1.37.0 Add changelog entries from botocore Update developer guide to include account ID based endpoints (#4446) Add account ID to boto3 session and client (#4444)
boto · Feb 24, 2025 · 0570a38 · 0570a38
2 parents bbe3a8d + f806af4
commit 0570a38
Show file tree

Hide file tree

Showing 9 changed files with 246 additions and 9 deletions.
diff --git a/.changes/1.37.0.json b/.changes/1.37.0.json
@@ -0,0 +1,32 @@
+[
+  {
+    "category": "``bedrock-agent``",
+    "description": "[``botocore``] This release improves support for newer models in Amazon Bedrock Flows.",
+    "type": "api-change"
+  },
+  {
+    "category": "``bedrock-agent-runtime``",
+    "description": "[``botocore``] Adding support for ReasoningContent fields in Pre-Processing, Post-Processing and Orchestration Trace outputs.",
+    "type": "api-change"
+  },
+  {
+    "category": "``bedrock-runtime``",
+    "description": "[``botocore``] This release adds Reasoning Content support to Converse and ConverseStream APIs",
+    "type": "api-change"
+  },
+  {
+    "category": "``elasticache``",
+    "description": "[``botocore``] Documentation update, adding clarity and rephrasing.",
+    "type": "api-change"
+  },
+  {
+    "category": "``elastic-inference``",
+    "description": "[``botocore``] The elastic-inference client has been removed following the deprecation of the service.",
+    "type": "api-change"
+  },
+  {
+    "category": "Endpoints",
+    "description": "[``botocore``] Generate and use AWS-account-based endpoints for compatible services when the account ID is available. At launch, DynamoDB is the first and only compatible service. The new endpoint URL pattern will be ``https://<account-id>.ddb.<region>.amazonaws.com``. Additional services may be added in the future. See the documentation for details: https://docs.aws.amazon.com/sdkref/latest/guide/feature-account-endpoints.html",
+    "type": "feature"
+  }
+]
diff --git a/CHANGELOG.rst b/CHANGELOG.rst
@@ -2,6 +2,17 @@
 CHANGELOG
 =========
 
+1.37.0
+======
+
+* api-change:``bedrock-agent``: [``botocore``] This release improves support for newer models in Amazon Bedrock Flows.
+* api-change:``bedrock-agent-runtime``: [``botocore``] Adding support for ReasoningContent fields in Pre-Processing, Post-Processing and Orchestration Trace outputs.
+* api-change:``bedrock-runtime``: [``botocore``] This release adds Reasoning Content support to Converse and ConverseStream APIs
+* api-change:``elasticache``: [``botocore``] Documentation update, adding clarity and rephrasing.
+* api-change:``elastic-inference``: [``botocore``] The elastic-inference client has been removed following the deprecation of the service.
+* feature:Endpoints: [``botocore``] Generate and use AWS-account-based endpoints for compatible services when the account ID is available. At launch, DynamoDB is the first and only compatible service. The new endpoint URL pattern will be ``https://<account-id>.ddb.<region>.amazonaws.com``. Additional services may be added in the future. See the documentation for details: https://docs.aws.amazon.com/sdkref/latest/guide/feature-account-endpoints.html
+
+
 1.36.26
 =======
 

diff --git a/boto3/__init__.py b/boto3/__init__.py
@@ -17,7 +17,7 @@
 from boto3.session import Session
 
 __author__ = 'Amazon Web Services'
-__version__ = '1.36.26'
+__version__ = '1.37.0'
 
 
 # The default Boto3 session; autoloaded when needed.

diff --git a/boto3/docs/__init__.py b/boto3/docs/__init__.py
@@ -24,7 +24,7 @@ def generate_docs(root_dir, session):
     text files documenting each service.
 
     :param root_dir: The directory to write the reference files to. Each
-        service's reference documentation is loacated at
+        service's reference documentation is located at
         root_dir/reference/services/service-name.rst
 
     :param session: The boto3 session

diff --git a/boto3/session.py b/boto3/session.py
@@ -16,7 +16,11 @@
 
 import botocore.session
 from botocore.client import Config
-from botocore.exceptions import DataNotFoundError, UnknownServiceError
+from botocore.exceptions import (
+    DataNotFoundError,
+    NoCredentialsError,
+    UnknownServiceError,
+)
 
 import boto3
 import boto3.utils
@@ -44,6 +48,8 @@ class Session:
     :type profile_name: string
     :param profile_name: The name of a profile to use. If not given, then
                          the default profile is used.
+    :type aws_account_id: string
+    :param aws_account_id: AWS account ID
     """
 
     def __init__(
@@ -54,6 +60,7 @@ def __init__(
         region_name=None,
         botocore_session=None,
         profile_name=None,
+        aws_account_id=None,
     ):
         if botocore_session is not None:
             self._session = botocore_session
@@ -74,9 +81,22 @@ def __init__(
         if profile_name is not None:
             self._session.set_config_variable('profile', profile_name)
 
-        if aws_access_key_id or aws_secret_access_key or aws_session_token:
+        creds = (
+            aws_access_key_id,
+            aws_secret_access_key,
+            aws_session_token,
+            aws_account_id,
+        )
+        if any(creds):
+            if self._account_id_set_without_credentials(
+                aws_account_id, aws_access_key_id, aws_secret_access_key
+            ):
+                raise NoCredentialsError()
             self._session.set_credentials(
-                aws_access_key_id, aws_secret_access_key, aws_session_token
+                aws_access_key_id,
+                aws_secret_access_key,
+                aws_session_token,
+                aws_account_id,
             )
 
         if region_name is not None:
@@ -224,6 +244,7 @@ def client(
         aws_secret_access_key=None,
         aws_session_token=None,
         config=None,
+        aws_account_id=None,
     ):
         """
         Create a low-level service client by name.
@@ -291,6 +312,10 @@ def client(
             <https://botocore.amazonaws.com/v1/documentation/api/latest/reference/config.html>`_
             for more details.
 
+        :type aws_account_id: string
+        :param aws_account_id: The account id to use when creating
+            the client.  Same semantics as aws_access_key_id above.
+
         :return: Service client instance
 
         """
@@ -305,6 +330,7 @@ def client(
             aws_secret_access_key=aws_secret_access_key,
             aws_session_token=aws_session_token,
             config=config,
+            aws_account_id=aws_account_id,
         )
 
     def resource(
@@ -527,3 +553,12 @@ def _register_default_handlers(self):
                 event_emitter=self.events,
             ),
         )
+
+    def _account_id_set_without_credentials(
+        self, account_id, access_key, secret_key
+    ):
+        if account_id is None:
+            return False
+        elif access_key is None or secret_key is None:
+            return True
+        return False
diff --git a/docs/source/guide/configuration.rst b/docs/source/guide/configuration.rst
@@ -516,3 +516,129 @@ in the ``~/.aws/config`` file.
 .. _IAM Roles for Amazon EC2: http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/iam-roles-for-amazon-ec2.html
 .. _Using IAM Roles: http://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_use.html
 .. _Sourcing Credentials with an External Process: https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-sourcing-external.html
+
+
+Using Account ID-Based Endpoints
+--------------------------------
+Boto3 supports account ID-based endpoints, which improve performance and scalability by using your AWS account ID to streamline request routing for services that support this feature. When Boto3 resolves credentials containing an account ID, it automatically constructs an account ID-based endpoint instead of a regional endpoint.
+
+Account ID-based endpoints follow this format:
+
+.. code-block:: shell
+
+    https://<account-id>.myservice.<region>.amazonaws.com
+
+
+* ``<account-id>`` is the AWS account ID sourced from your credentials.
+* ``<region>`` is the AWS region where the request is being made.
+
+
+Supported Credential Providers
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Boto3 can automatically construct account ID-based endpoints by sourcing the AWS account ID from the following places:
+
+* Credentials set using the ``boto3.client()`` method
+* Credentials set when creating a ``Session`` object
+* Environment variables
+* Assume role provider
+* Assume role with web identity provider
+* AWS IAM Identity Center credential provider
+* Shared credential file (``~/.aws/credentials``)
+* AWS config file (``~/.aws/config``)
+* Container credential provider
+
+You can read more about these locations in the :ref:`guide_credentials` guide.
+
+
+Configuring Account ID
+~~~~~~~~~~~~~~~~~~~~~~
+
+You can provide an account ID along with your AWS credentials using one of the following:
+
+Passing it as a parameter when creating clients:
+
+.. code-block:: python
+
+    import boto3
+
+    client = boto3.client(
+        'dynamodb',
+        aws_access_key_id=ACCESS_KEY,
+        aws_secret_access_key=SECRET_KEY,
+        aws_account_id=ACCOUNT_ID
+    )
+
+Passing it as a parameter when creating a ``Session`` object:
+
+.. code-block:: python
+
+    import boto3
+
+    session = boto3.Session(
+        aws_access_key_id=ACCESS_KEY,
+        aws_secret_access_key=SECRET_KEY,
+        aws_account_id=ACCOUNT_ID
+    )
+
+Setting an environment variable:
+
+.. code-block:: shell
+
+    export AWS_ACCESS_KEY_ID=<ACCESS_KEY>
+    export AWS_SECRET_ACCESS_KEY=<SECRET_KEY>
+    export AWS_ACCOUNT_ID=<ACCOUNT_ID>
+
+Setting it in the shared credentials or config file:
+
+.. code-block:: ini
+
+    [default]
+    aws_access_key_id=foo
+    aws_secret_access_key=bar
+    aws_account_id=baz
+
+
+Configuring Endpoint Routing Behavior
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The account ID endpoint mode is a setting that can be used to turn off account ID-based endpoint routing if necessary.
+
+Valid values are:
+
+* ``preferred`` – The endpoint should include account ID if available.
+* ``disabled`` – A resolved endpoint doesn't include account ID.
+* ``required`` – The endpoint must include account ID. If the account ID isn't available, the SDK throws an error.
+
+.. note::
+
+    The default behavior in Boto3 is ``preferred``.
+
+
+You can configure the setting using one of the following:
+
+Setting it in the ``Config`` object when creating clients:
+
+.. code-block:: python
+
+    import boto3
+    from botocore.config import Config
+
+    my_config = Config(
+        account_id_endpoint_mode = 'disabled'
+    )
+
+    client = boto3.client('dynamodb', config=my_config)
+
+Setting an environment variable:
+
+.. code-block:: shell
+
+    export AWS_ACCOUNT_ID_ENDPOINT_MODE=disabled
+
+Setting it in the shared credentials or config file:
+
+.. code-block:: ini
+
+    [default]
+    account_id_endpoint_mode=disabled
diff --git a/setup.cfg b/setup.cfg
@@ -3,7 +3,7 @@ universal = 0
 
 [metadata]
 requires_dist =
-    botocore>=1.36.26,<1.37.0
+    botocore>=1.37.0,<1.38.0
     jmespath>=0.7.1,<2.0.0
     s3transfer>=0.11.0,<0.12.0
 

diff --git a/setup.py b/setup.py
@@ -14,7 +14,7 @@
 
 
 requires = [
-    'botocore>=1.36.26,<1.37.0',
+    'botocore>=1.37.0,<1.38.0',
     'jmespath>=0.7.1,<2.0.0',
     's3transfer>=0.11.0,<0.12.0',
 ]

diff --git a/tests/unit/test_session.py b/tests/unit/test_session.py
@@ -13,7 +13,7 @@
 import pytest
 from botocore import loaders
 from botocore.client import Config
-from botocore.exceptions import UnknownServiceError
+from botocore.exceptions import NoCredentialsError, UnknownServiceError
 
 from boto3 import __version__
 from boto3.exceptions import ResourceNotExistsError
@@ -70,17 +70,47 @@ def test_credentials_can_be_set(self):
 
         assert self.bc_session_cls.called
         assert bc_session.set_credentials.called
-        bc_session.set_credentials.assert_called_with('key', 'secret', 'token')
+        bc_session.set_credentials.assert_called_with(
+            'key', 'secret', 'token', None
+        )
+
+    def test_credentials_can_be_set_with_account_id(self):
+        bc_session = self.bc_session_cls.return_value
+
+        # Set values in constructor
+        Session(
+            aws_access_key_id='key',
+            aws_secret_access_key='secret',
+            aws_session_token='token',
+            aws_account_id='account',
+        )
+
+        assert self.bc_session_cls.called
+        assert bc_session.set_credentials.called
+        bc_session.set_credentials.assert_called_with(
+            'key', 'secret', 'token', 'account'
+        )
+
+    def test_account_id_set_without_credentials(self):
+        bc_session = self.bc_session_cls.return_value
+
+        with pytest.raises(NoCredentialsError) as e:
+            Session(aws_account_id='account_id')
+
+        assert not bc_session.set_credentials.called
+        assert 'Unable to locate credentials' in str(e.value)
 
     def test_can_get_credentials(self):
         access_key = 'foo'
         secret_key = 'bar'
         token = 'baz'
+        account_id = 'bin'
 
         creds = mock.Mock()
         creds.access_key = access_key
         creds.secret_key = secret_key
         creds.token = token
+        creds.account_id = account_id
 
         bc_session = self.bc_session_cls.return_value
         bc_session.get_credentials.return_value = creds
@@ -89,12 +119,14 @@ def test_can_get_credentials(self):
             aws_access_key_id=access_key,
             aws_secret_access_key=secret_key,
             aws_session_token=token,
+            aws_account_id=account_id,
         )
 
         credentials = session.get_credentials()
         assert credentials.access_key == access_key
         assert credentials.secret_key == secret_key
         assert credentials.token == token
+        assert credentials.account_id == account_id
 
     def test_profile_can_be_set(self):
         bc_session = self.bc_session_cls.return_value
@@ -240,6 +272,7 @@ def test_create_client_with_args(self):
             region_name='us-west-2',
             api_version=None,
             config=None,
+            aws_account_id=None,
         )
 
     def test_create_resource_with_args(self):