Class UserAgentComponent

awscli/botocore/useragent.py:178–236

Component of a Botocore User-Agent header string in the standard format. 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 tr

class UserAgentComponent(NamedTuple):
    """
    Component of a Botocore User-Agent header string in the standard format.

    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.
    """

    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."""
        clean_prefix = sanitize_user_agent_string_component(
            self.prefix, allow_hash=True
        )
        clean_name = sanitize_user_agent_string_component(
            self.name, allow_hash=False
        )
        if self.value is None or self.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."
            )