botocore 1.37.3__py3-none-any.whl → 1.37.4__py3-none-any.whl

botocore/paginate.py

@@ -14,11 +14,14 @@
 import base64
 import json
 import logging
+from functools import partial
 from itertools import tee
 
 import jmespath
 
+from botocore.context import with_current_context
 from botocore.exceptions import PaginationError
+from botocore.useragent import register_feature_id
 from botocore.utils import merge_dicts, set_value_from_jmespath
 
 log = logging.getLogger(__name__)
@@ -353,6 +356,7 @@ class PageIterator:
                 # Yield result directly if it is not a list.
                 yield results
 
+    @with_current_context(partial(register_feature_id, 'PAGINATOR'))
     def _make_request(self, current_kwargs):
         return self._method(**current_kwargs)
 

botocore/session.py

@@ -48,6 +48,7 @@ from botocore.configprovider import (
     SmartDefaultsConfigStoreFactory,
     create_botocore_default_config_mapping,
 )
+from botocore.context import get_context, with_current_context
 from botocore.errorfactory import ClientExceptionsFactory
 from botocore.exceptions import (
     ConfigNotFound,
@@ -834,6 +835,7 @@ class Session:
     def lazy_register_component(self, name, component):
         self._components.lazy_register_component(name, component)
 
+    @with_current_context()
     def create_client(
         self,
         service_name,
@@ -1000,6 +1002,8 @@ class Session:
             config_store=config_store,
         )
 
+        user_agent_creator.set_client_features(get_context().features)
+
         client_creator = botocore.client.ClientCreator(
             loader,
             endpoint_resolver,

botocore/useragent.py

@@ -23,6 +23,7 @@ configuration options:
 
 """
 
+import logging
 import os
 import platform
 from copy import copy
@@ -31,8 +32,12 @@ from typing import NamedTuple, Optional
 
 from botocore import __version__ as botocore_version
 from botocore.compat import HAS_CRT
+from botocore.context import get_context
 
-_USERAGENT_ALLOWED_CHARACTERS = ascii_letters + digits + "!$%&'*+-.^_`|~"
+logger = logging.getLogger(__name__)
+
+
+_USERAGENT_ALLOWED_CHARACTERS = ascii_letters + digits + "!$%&'*+-.^_`|~,"
 _USERAGENT_ALLOWED_OS_NAMES = (
     'windows',
     'linux',
@@ -49,12 +54,38 @@ _USERAGENT_PLATFORM_NAME_MAPPINGS = {'darwin': 'macos'}
 # using their existing values. Uses uppercase "B" with all other characters
 # lowercase.
 _USERAGENT_SDK_NAME = 'Botocore'
+_USERAGENT_FEATURE_MAPPINGS = {
+    'WAITER': 'B',
+    'PAGINATOR': 'C',
+    'S3_TRANSFER': 'G',
+    'ENDPOINT_OVERRIDE': 'N',
+    'SIGV4A_SIGNING': 'S',
+}
+
+
+def register_feature_id(feature_id):
+    """Adds metric value to the current context object's ``features`` set.
+
+    :type feature_id: str
+    :param feature_id: The name of the feature to register. Value must be a key
+        in the ``_USERAGENT_FEATURE_MAPPINGS`` dict.
+    """
+    ctx = get_context()
+    if ctx is None:
+        # Never register features outside the scope of a
+        # ``botocore.context.start_as_current_context`` context manager.
+        # Otherwise, the context variable won't be reset and features will
+        # bleed into all subsequent requests. Return instead of raising an
+        # exception since this function could be invoked in a public interface.
+        return
+    if val := _USERAGENT_FEATURE_MAPPINGS.get(feature_id):
+        ctx.features.add(val)
 
 
 def sanitize_user_agent_string_component(raw_str, allow_hash):
     """Replaces all not allowed characters in the string with a dash ("-").
 
-    Allowed characters are ASCII alphanumerics and ``!$%&'*+-.^_`|~``. If
+    Allowed characters are ASCII alphanumerics and ``!$%&'*+-.^_`|~,``. If
     ``allow_hash`` is ``True``, "#"``" is also allowed.
 
     :type raw_str: str
@@ -71,12 +102,35 @@ def sanitize_user_agent_string_component(raw_str, allow_hash):
     )
 
 
+class UserAgentComponentSizeConfig:
+    """
+    Configures the max size of a built user agent string component and the
+    delimiter used to truncate the string if the size is above the max.
+    """
+
+    def __init__(self, max_size_in_bytes: int, delimiter: str):
+        self.max_size_in_bytes = max_size_in_bytes
+        self.delimiter = delimiter
+        self._validate_input()
+
+    def _validate_input(self):
+        if self.max_size_in_bytes < 1:
+            raise ValueError(
+                f'Invalid `max_size_in_bytes`: {self.max_size_in_bytes}. '
+                'Value must be a positive integer.'
+            )
+
+
 class UserAgentComponent(NamedTuple):
     """
     Component of a Botocore User-Agent header string in the standard format.
 
-    Each component consists of a prefix, a name, and a value. In the string
-    representation these are combined in the format ``prefix/name#value``.
+    Each component consists of a prefix, a name, a value, and a size_config.
+    In the string representation these are combined in the format
+    ``prefix/name#value``.
+
+    ``size_config`` configures the max size and truncation strategy for the
+    built user agent string component.
 
     This class is considered private and is subject to abrupt breaking changes.
     """
@@ -84,6 +138,7 @@ class UserAgentComponent(NamedTuple):
     prefix: str
     name: str
     value: Optional[str] = None
+    size_config: Optional[UserAgentComponentSizeConfig] = None
 
     def to_string(self):
         """Create string like 'prefix/name#value' from a UserAgentComponent."""
@@ -94,11 +149,39 @@ class UserAgentComponent(NamedTuple):
             self.name, allow_hash=False
         )
         if self.value is None or self.value == '':
-            return f'{clean_prefix}/{clean_name}'
-        clean_value = sanitize_user_agent_string_component(
-            self.value, allow_hash=True
-        )
-        return f'{clean_prefix}/{clean_name}#{clean_value}'
+            clean_string = f'{clean_prefix}/{clean_name}'
+        else:
+            clean_value = sanitize_user_agent_string_component(
+                self.value, allow_hash=True
+            )
+            clean_string = f'{clean_prefix}/{clean_name}#{clean_value}'
+        if self.size_config is not None:
+            clean_string = self._truncate_string(
+                clean_string,
+                self.size_config.max_size_in_bytes,
+                self.size_config.delimiter,
+            )
+        return clean_string
+
+    def _truncate_string(self, string, max_size, delimiter):
+        """
+        Pop ``delimiter``-separated values until encoded string is less than or
+        equal to ``max_size``.
+        """
+        orig = string
+        while len(string.encode('utf-8')) > max_size:
+            parts = string.split(delimiter)
+            parts.pop()
+            string = delimiter.join(parts)
+
+        if string == '':
+            logger.debug(
+                f"User agent component `{orig}` could not be truncated to "
+                f"`{max_size}` bytes with delimiter "
+                f"`{delimiter}` without losing all contents. "
+                f"Value will be omitted from user agent string."
+            )
+        return string
 
 
 class RawStringUserAgentComponent:
@@ -203,9 +286,9 @@ class UserAgentString:
         self._session_user_agent_extra = None
 
         self._client_config = None
-        self._uses_paginator = None
-        self._uses_waiter = None
-        self._uses_resource = None
+
+        # Component that can be set with ``set_client_features()``
+        self._client_features = None
 
     @classmethod
     def from_environment(cls):
@@ -245,6 +328,16 @@ class UserAgentString:
         self._session_user_agent_extra = session_user_agent_extra
         return self
 
+    def set_client_features(self, features):
+        """
+        Persist client-specific features registered before or during client
+        creation.
+
+        :type features: Set[str]
+        :param features: A set of client-specific features.
+        """
+        self._client_features = features
+
     def with_client_config(self, client_config):
         """
         Create a copy with all original values and client-specific values.
@@ -272,7 +365,7 @@ class UserAgentString:
 
         components = [
             *self._build_sdk_metadata(),
-            RawStringUserAgentComponent('ua/2.0'),
+            RawStringUserAgentComponent('ua/2.1'),
             *self._build_os_metadata(),
             *self._build_architecture_metadata(),
             *self._build_language_metadata(),
@@ -285,7 +378,9 @@ class UserAgentString:
 
         components = modify_components(components)
 
-        return ' '.join([comp.to_string() for comp in components])
+        return ' '.join(
+            [comp.to_string() for comp in components if comp.to_string()]
+        )
 
     def _build_sdk_metadata(self):
         """
@@ -415,12 +510,23 @@ class UserAgentString:
 
     def _build_feature_metadata(self):
         """
-        Build the features components of the User-Agent header string.
+        Build the features component of the User-Agent header string.
 
-        Botocore currently does not report any features. This may change in a
-        future version.
+        Returns a single component with prefix "m" followed by a list of
+        comma-separated metric values.
         """
-        return []
+        ctx = get_context()
+        context_features = set() if ctx is None else ctx.features
+        client_features = self._client_features or set()
+        features = client_features.union(context_features)
+        if not features:
+            return []
+        size_config = UserAgentComponentSizeConfig(1024, ',')
+        return [
+            UserAgentComponent(
+                'm', ','.join(features), size_config=size_config
+            )
+        ]
 
     def _build_config_metadata(self):
         """
@@ -490,6 +596,13 @@ class UserAgentString:
             components.append(self._client_config.user_agent_extra)
         return ' '.join(components)
 
+    def rebuild_and_replace_user_agent_handler(
+        self, operation_name, request, **kwargs
+    ):
+        ua_string = self.to_string()
+        if request.headers.get('User-Agent'):
+            request.headers.replace_header('User-Agent', ua_string)
+
 
 def _get_crt_version():
     """

botocore/waiter.py

@@ -12,10 +12,13 @@
 # language governing permissions and limitations under the License.
 import logging
 import time
+from functools import partial
 
 import jmespath
 
+from botocore.context import with_current_context
 from botocore.docs.docstring import WaiterDocstring
+from botocore.useragent import register_feature_id
 from botocore.utils import get_service_module_name
 
 from . import xform_name
@@ -331,6 +334,7 @@ class Waiter:
         self.name = name
         self.config = config
 
+    @with_current_context(partial(register_feature_id, 'WAITER'))
     def wait(self, **kwargs):
         acceptors = list(self.config.acceptors)
         current_state = 'waiting'

{botocore-1.37.3.dist-info → botocore-1.37.4.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: botocore
-Version: 1.37.3
+Version: 1.37.4
 Summary: Low-level, data-driven core of boto 3.
 Home-page: https://github.com/boto/botocore
 Author: Amazon Web Services