Add files using upload-large-folder tool

.venv/lib/python3.13/site-packages/absl/flags/__init__.py

@@ -0,0 +1,220 @@
+# Copyright 2017 The Abseil Authors.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+"""This package is used to define and parse command line flags.
+
+This package defines a *distributed* flag-definition policy: rather than
+an application having to define all flags in or near main(), each Python
+module defines flags that are useful to it.  When one Python module
+imports another, it gains access to the other's flags.  (This is
+implemented by having all modules share a common, global registry object
+containing all the flag information.)
+
+Flags are defined through the use of one of the DEFINE_xxx functions.
+The specific function used determines how the flag is parsed, checked,
+and optionally type-converted, when it's seen on the command line.
+"""
+
+import sys
+
+from absl.flags import _argument_parser
+from absl.flags import _defines
+from absl.flags import _exceptions
+from absl.flags import _flag
+from absl.flags import _flagvalues
+from absl.flags import _helpers
+from absl.flags import _validators
+
+__all__ = (
+    'DEFINE',
+    'DEFINE_flag',
+    'DEFINE_string',
+    'DEFINE_boolean',
+    'DEFINE_bool',
+    'DEFINE_float',
+    'DEFINE_integer',
+    'DEFINE_enum',
+    'DEFINE_enum_class',
+    'DEFINE_list',
+    'DEFINE_spaceseplist',
+    'DEFINE_multi',
+    'DEFINE_multi_string',
+    'DEFINE_multi_integer',
+    'DEFINE_multi_float',
+    'DEFINE_multi_enum',
+    'DEFINE_multi_enum_class',
+    'DEFINE_alias',
+    # Flag validators.
+    'register_validator',
+    'validator',
+    'register_multi_flags_validator',
+    'multi_flags_validator',
+    'mark_flag_as_required',
+    'mark_flags_as_required',
+    'mark_flags_as_mutual_exclusive',
+    'mark_bool_flags_as_mutual_exclusive',
+    # Flag modifiers.
+    'set_default',
+    'override_value',
+    # Key flag related functions.
+    'declare_key_flag',
+    'adopt_module_key_flags',
+    'disclaim_key_flags',
+    # Module exceptions.
+    'Error',
+    'CantOpenFlagFileError',
+    'DuplicateFlagError',
+    'IllegalFlagValueError',
+    'UnrecognizedFlagError',
+    'UnparsedFlagAccessError',
+    'ValidationError',
+    'FlagNameConflictsWithMethodError',
+    # Public classes.
+    'Flag',
+    'BooleanFlag',
+    'EnumFlag',
+    'EnumClassFlag',
+    'MultiFlag',
+    'MultiEnumClassFlag',
+    'FlagHolder',
+    'FlagValues',
+    'ArgumentParser',
+    'BooleanParser',
+    'EnumParser',
+    'EnumClassParser',
+    'ArgumentSerializer',
+    'FloatParser',
+    'IntegerParser',
+    'BaseListParser',
+    'ListParser',
+    'ListSerializer',
+    'EnumClassListSerializer',
+    'CsvListSerializer',
+    'WhitespaceSeparatedListParser',
+    'EnumClassSerializer',
+    # Helper functions.
+    'get_help_width',
+    'text_wrap',
+    'flag_dict_to_args',
+    'doc_to_help',
+    # The global FlagValues instance.
+    'FLAGS',
+)
+
+# Initialize the FLAGS_MODULE as early as possible.
+# It's only used by adopt_module_key_flags to take SPECIAL_FLAGS into account.
+_helpers.FLAGS_MODULE = sys.modules[__name__]
+
+# Add current module to disclaimed module ids.
+_helpers.disclaim_module_ids.add(id(sys.modules[__name__]))
+
+# DEFINE functions. They are explained in more details in the module doc string.
+# pylint: disable=invalid-name
+DEFINE = _defines.DEFINE
+DEFINE_flag = _defines.DEFINE_flag
+DEFINE_string = _defines.DEFINE_string
+DEFINE_boolean = _defines.DEFINE_boolean
+DEFINE_bool = DEFINE_boolean  # Match C++ API.
+DEFINE_float = _defines.DEFINE_float
+DEFINE_integer = _defines.DEFINE_integer
+DEFINE_enum = _defines.DEFINE_enum
+DEFINE_enum_class = _defines.DEFINE_enum_class
+DEFINE_list = _defines.DEFINE_list
+DEFINE_spaceseplist = _defines.DEFINE_spaceseplist
+DEFINE_multi = _defines.DEFINE_multi
+DEFINE_multi_string = _defines.DEFINE_multi_string
+DEFINE_multi_integer = _defines.DEFINE_multi_integer
+DEFINE_multi_float = _defines.DEFINE_multi_float
+DEFINE_multi_enum = _defines.DEFINE_multi_enum
+DEFINE_multi_enum_class = _defines.DEFINE_multi_enum_class
+DEFINE_alias = _defines.DEFINE_alias
+# pylint: enable=invalid-name
+
+# Flag validators.
+register_validator = _validators.register_validator
+validator = _validators.validator
+register_multi_flags_validator = _validators.register_multi_flags_validator
+multi_flags_validator = _validators.multi_flags_validator
+mark_flag_as_required = _validators.mark_flag_as_required
+mark_flags_as_required = _validators.mark_flags_as_required
+mark_flags_as_mutual_exclusive = _validators.mark_flags_as_mutual_exclusive
+mark_bool_flags_as_mutual_exclusive = _validators.mark_bool_flags_as_mutual_exclusive
+
+# Flag modifiers.
+set_default = _defines.set_default
+override_value = _defines.override_value
+
+# Key flag related functions.
+declare_key_flag = _defines.declare_key_flag
+adopt_module_key_flags = _defines.adopt_module_key_flags
+disclaim_key_flags = _defines.disclaim_key_flags
+
+# Module exceptions.
+# pylint: disable=invalid-name
+Error = _exceptions.Error
+CantOpenFlagFileError = _exceptions.CantOpenFlagFileError
+DuplicateFlagError = _exceptions.DuplicateFlagError
+IllegalFlagValueError = _exceptions.IllegalFlagValueError
+UnrecognizedFlagError = _exceptions.UnrecognizedFlagError
+UnparsedFlagAccessError = _exceptions.UnparsedFlagAccessError
+ValidationError = _exceptions.ValidationError
+FlagNameConflictsWithMethodError = _exceptions.FlagNameConflictsWithMethodError
+
+# Public classes.
+Flag = _flag.Flag
+BooleanFlag = _flag.BooleanFlag
+EnumFlag = _flag.EnumFlag
+EnumClassFlag = _flag.EnumClassFlag
+MultiFlag = _flag.MultiFlag
+MultiEnumClassFlag = _flag.MultiEnumClassFlag
+FlagHolder = _flagvalues.FlagHolder
+FlagValues = _flagvalues.FlagValues
+ArgumentParser = _argument_parser.ArgumentParser
+BooleanParser = _argument_parser.BooleanParser
+EnumParser = _argument_parser.EnumParser
+EnumClassParser = _argument_parser.EnumClassParser
+ArgumentSerializer = _argument_parser.ArgumentSerializer
+FloatParser = _argument_parser.FloatParser
+IntegerParser = _argument_parser.IntegerParser
+BaseListParser = _argument_parser.BaseListParser
+ListParser = _argument_parser.ListParser
+ListSerializer = _argument_parser.ListSerializer
+EnumClassListSerializer = _argument_parser.EnumClassListSerializer
+CsvListSerializer = _argument_parser.CsvListSerializer
+WhitespaceSeparatedListParser = _argument_parser.WhitespaceSeparatedListParser
+EnumClassSerializer = _argument_parser.EnumClassSerializer
+# pylint: enable=invalid-name
+
+# Helper functions.
+get_help_width = _helpers.get_help_width
+text_wrap = _helpers.text_wrap
+flag_dict_to_args = _helpers.flag_dict_to_args
+doc_to_help = _helpers.doc_to_help
+
+# Special flags.
+_helpers.SPECIAL_FLAGS = FlagValues()
+
+DEFINE_string(
+    'flagfile', '',
+    'Insert flag definitions from the given file into the command line.',
+    _helpers.SPECIAL_FLAGS)  # pytype: disable=wrong-arg-types
+
+DEFINE_string('undefok', '',
+              'comma-separated list of flag names that it is okay to specify '
+              'on the command line even if the program does not define a flag '
+              'with that name.  IMPORTANT: flags in this list that have '
+              'arguments MUST use the --flag=value format.',
+              _helpers.SPECIAL_FLAGS)  # pytype: disable=wrong-arg-types
+
+#: The global FlagValues instance.
+FLAGS = _flagvalues.FLAGS

.venv/lib/python3.13/site-packages/absl/flags/_argument_parser.py

@@ -0,0 +1,632 @@
+# Copyright 2017 The Abseil Authors.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Contains base classes used to parse and convert arguments.
+
+Do NOT import this module directly. Import the flags package and use the
+aliases defined at the package level instead.
+"""
+
+import collections
+from collections.abc import Iterable, Sequence
+import csv
+import enum
+import io
+import string
+from typing import Any, Generic, TypeVar
+from xml.dom import minidom
+
+from absl.flags import _helpers
+
+_T = TypeVar('_T')
+_ET = TypeVar('_ET', bound=enum.Enum)
+_N = TypeVar('_N', int, float)
+
+
+class _ArgumentParserCache(type):
+  """Metaclass used to cache and share argument parsers among flags."""
+
+  _instances: dict[Any, Any] = {}
+
+  def __call__(cls, *args, **kwargs):
+    """Returns an instance of the argument parser cls.
+
+    This method overrides behavior of the __new__ methods in
+    all subclasses of ArgumentParser (inclusive). If an instance
+    for cls with the same set of arguments exists, this instance is
+    returned, otherwise a new instance is created.
+
+    If any keyword arguments are defined, or the values in args
+    are not hashable, this method always returns a new instance of
+    cls.
+
+    Args:
+      *args: Positional initializer arguments.
+      **kwargs: Initializer keyword arguments.
+
+    Returns:
+      An instance of cls, shared or new.
+    """
+    if kwargs:
+      return type.__call__(cls, *args, **kwargs)
+    else:
+      instances = cls._instances
+      key = (cls,) + tuple(args)
+      try:
+        return instances[key]
+      except KeyError:
+        # No cache entry for key exists, create a new one.
+        return instances.setdefault(key, type.__call__(cls, *args))
+      except TypeError:
+        # An object in args cannot be hashed, always return
+        # a new instance.
+        return type.__call__(cls, *args)
+
+
+class ArgumentParser(Generic[_T], metaclass=_ArgumentParserCache):
+  """Base class used to parse and convert arguments.
+
+  The :meth:`parse` method checks to make sure that the string argument is a
+  legal value and convert it to a native type.  If the value cannot be
+  converted, it should throw a ``ValueError`` exception with a human
+  readable explanation of why the value is illegal.
+
+  Subclasses should also define a syntactic_help string which may be
+  presented to the user to describe the form of the legal values.
+
+  Argument parser classes must be stateless, since instances are cached
+  and shared between flags. Initializer arguments are allowed, but all
+  member variables must be derived from initializer arguments only.
+  """
+
+  syntactic_help: str = ''
+
+  def parse(self, argument: str) -> _T | None:
+    """Parses the string argument and returns the native value.
+
+    By default it returns its argument unmodified.
+
+    Args:
+      argument: string argument passed in the commandline.
+
+    Raises:
+      ValueError: Raised when it fails to parse the argument.
+      TypeError: Raised when the argument has the wrong type.
+
+    Returns:
+      The parsed value in native type.
+    """
+    if not isinstance(argument, str):
+      raise TypeError('flag value must be a string, found "{}"'.format(
+          type(argument)))
+    return argument  # type: ignore[return-value]
+
+  def flag_type(self) -> str:
+    """Returns a string representing the type of the flag."""
+    return 'string'
+
+  def _custom_xml_dom_elements(
+      self, doc: minidom.Document
+  ) -> list[minidom.Element]:
+    """Returns a list of minidom.Element to add additional flag information.
+
+    Args:
+      doc: minidom.Document, the DOM document it should create nodes from.
+    """
+    del doc  # Unused.
+    return []
+
+
+class ArgumentSerializer(Generic[_T]):
+  """Base class for generating string representations of a flag value."""
+
+  def serialize(self, value: _T) -> str:
+    """Returns a serialized string of the value."""
+    return str(value)
+
+
+class NumericParser(ArgumentParser[_N]):
+  """Parser of numeric values.
+
+  Parsed value may be bounded to a given upper and lower bound.
+  """
+
+  lower_bound: _N | None
+  upper_bound: _N | None
+
+  def is_outside_bounds(self, val: _N) -> bool:
+    """Returns whether the value is outside the bounds or not."""
+    return ((self.lower_bound is not None and val < self.lower_bound) or
+            (self.upper_bound is not None and val > self.upper_bound))
+
+  def parse(self, argument: str | _N) -> _N:
+    """See base class."""
+    val = self.convert(argument)
+    if self.is_outside_bounds(val):
+      raise ValueError('%s is not %s' % (val, self.syntactic_help))
+    return val
+
+  def _custom_xml_dom_elements(
+      self, doc: minidom.Document
+  ) -> list[minidom.Element]:
+    elements = []
+    if self.lower_bound is not None:
+      elements.append(_helpers.create_xml_dom_element(
+          doc, 'lower_bound', self.lower_bound))
+    if self.upper_bound is not None:
+      elements.append(_helpers.create_xml_dom_element(
+          doc, 'upper_bound', self.upper_bound))
+    return elements
+
+  def convert(self, argument: str | _N) -> _N:
+    """Returns the correct numeric value of argument.
+
+    Subclass must implement this method, and raise TypeError if argument is not
+    string or has the right numeric type.
+
+    Args:
+      argument: string argument passed in the commandline, or the numeric type.
+
+    Raises:
+      TypeError: Raised when argument is not a string or the right numeric type.
+      ValueError: Raised when failed to convert argument to the numeric value.
+    """
+    raise NotImplementedError
+
+
+class FloatParser(NumericParser[float]):
+  """Parser of floating point values.
+
+  Parsed value may be bounded to a given upper and lower bound.
+  """
+  number_article = 'a'
+  number_name = 'number'
+  syntactic_help = ' '.join((number_article, number_name))
+
+  def __init__(
+      self,
+      lower_bound: float | None = None,
+      upper_bound: float | None = None,
+  ) -> None:
+    super().__init__()
+    self.lower_bound = lower_bound
+    self.upper_bound = upper_bound
+    sh = self.syntactic_help
+    if lower_bound is not None and upper_bound is not None:
+      sh = ('%s in the range [%s, %s]' % (sh, lower_bound, upper_bound))
+    elif lower_bound == 0:
+      sh = 'a non-negative %s' % self.number_name
+    elif upper_bound == 0:
+      sh = 'a non-positive %s' % self.number_name
+    elif upper_bound is not None:
+      sh = '%s <= %s' % (self.number_name, upper_bound)
+    elif lower_bound is not None:
+      sh = '%s >= %s' % (self.number_name, lower_bound)
+    self.syntactic_help = sh
+
+  def convert(self, argument: int | float | str) -> float:
+    """Returns the float value of argument."""
+    if (
+        (isinstance(argument, int) and not isinstance(argument, bool))
+        or isinstance(argument, float)
+        or isinstance(argument, str)
+    ):
+      return float(argument)
+    else:
+      raise TypeError(
+          'Expect argument to be a string, int, or float, found {}'.format(
+              type(argument)))
+
+  def flag_type(self) -> str:
+    """See base class."""
+    return 'float'
+
+
+class IntegerParser(NumericParser[int]):
+  """Parser of an integer value.
+
+  Parsed value may be bounded to a given upper and lower bound.
+  """
+  number_article = 'an'
+  number_name = 'integer'
+  syntactic_help = ' '.join((number_article, number_name))
+
+  def __init__(
+      self, lower_bound: int | None = None, upper_bound: int | None = None
+  ) -> None:
+    super().__init__()
+    self.lower_bound = lower_bound
+    self.upper_bound = upper_bound
+    sh = self.syntactic_help
+    if lower_bound is not None and upper_bound is not None:
+      sh = ('%s in the range [%s, %s]' % (sh, lower_bound, upper_bound))
+    elif lower_bound == 1:
+      sh = 'a positive %s' % self.number_name
+    elif upper_bound == -1:
+      sh = 'a negative %s' % self.number_name
+    elif lower_bound == 0:
+      sh = 'a non-negative %s' % self.number_name
+    elif upper_bound == 0:
+      sh = 'a non-positive %s' % self.number_name
+    elif upper_bound is not None:
+      sh = '%s <= %s' % (self.number_name, upper_bound)
+    elif lower_bound is not None:
+      sh = '%s >= %s' % (self.number_name, lower_bound)
+    self.syntactic_help = sh
+
+  def convert(self, argument: int | str) -> int:
+    """Returns the int value of argument."""
+    if isinstance(argument, int) and not isinstance(argument, bool):
+      return argument
+    elif isinstance(argument, str):
+      base = 10
+      if len(argument) > 2 and argument[0] == '0':
+        if argument[1] == 'o':
+          base = 8
+        elif argument[1] == 'x':
+          base = 16
+      return int(argument, base)
+    else:
+      raise TypeError('Expect argument to be a string or int, found {}'.format(
+          type(argument)))
+
+  def flag_type(self) -> str:
+    """See base class."""
+    return 'int'
+
+
+class BooleanParser(ArgumentParser[bool]):
+  """Parser of boolean values."""
+
+  def parse(self, argument: str | int) -> bool:
+    """See base class."""
+    if isinstance(argument, str):
+      if argument.lower() in ('true', 't', '1'):
+        return True
+      elif argument.lower() in ('false', 'f', '0'):
+        return False
+      else:
+        raise ValueError('Non-boolean argument to boolean flag', argument)
+    elif isinstance(argument, int):
+      # Only allow bool or integer 0, 1.
+      # Note that float 1.0 == True, 0.0 == False.
+      bool_value = bool(argument)
+      if argument == bool_value:
+        return bool_value
+      else:
+        raise ValueError('Non-boolean argument to boolean flag', argument)
+
+    raise TypeError('Non-boolean argument to boolean flag', argument)
+
+  def flag_type(self) -> str:
+    """See base class."""
+    return 'bool'
+
+
+class EnumParser(ArgumentParser[str]):
+  """Parser of a string enum value (a string value from a given set)."""
+
+  def __init__(
+      self, enum_values: Iterable[str], case_sensitive: bool = True
+  ) -> None:
+    """Initializes EnumParser.
+
+    Args:
+      enum_values: [str], a non-empty list of string values in the enum.
+      case_sensitive: bool, whether or not the enum is to be case-sensitive.
+
+    Raises:
+      ValueError: When enum_values is empty.
+    """
+    if not enum_values:
+      raise ValueError(f'enum_values cannot be empty, found "{enum_values}"')
+    if isinstance(enum_values, str):
+      raise ValueError(f'enum_values cannot be a str, found "{enum_values}"')
+    super().__init__()
+    self.enum_values = list(enum_values)
+    self.case_sensitive = case_sensitive
+
+  def parse(self, argument: str) -> str:
+    """Determines validity of argument and returns the correct element of enum.
+
+    Args:
+      argument: str, the supplied flag value.
+
+    Returns:
+      The first matching element from enum_values.
+
+    Raises:
+      ValueError: Raised when argument didn't match anything in enum.
+    """
+    if self.case_sensitive:
+      if argument not in self.enum_values:
+        raise ValueError('value should be one of <%s>' %
+                         '|'.join(self.enum_values))
+      else:
+        return argument
+    else:
+      if argument.upper() not in [value.upper() for value in self.enum_values]:
+        raise ValueError('value should be one of <%s>' %
+                         '|'.join(self.enum_values))
+      else:
+        return [value for value in self.enum_values
+                if value.upper() == argument.upper()][0]
+
+  def flag_type(self) -> str:
+    """See base class."""
+    return 'string enum'
+
+
+class EnumClassParser(ArgumentParser[_ET]):
+  """Parser of an Enum class member."""
+
+  def __init__(
+      self, enum_class: type[_ET], case_sensitive: bool = True
+  ) -> None:
+    """Initializes EnumParser.
+
+    Args:
+      enum_class: class, the Enum class with all possible flag values.
+      case_sensitive: bool, whether or not the enum is to be case-sensitive. If
+        False, all member names must be unique when case is ignored.
+
+    Raises:
+      TypeError: When enum_class is not a subclass of Enum.
+      ValueError: When enum_class is empty.
+    """
+    if not issubclass(enum_class, enum.Enum):
+      raise TypeError(f'{enum_class} is not a subclass of Enum.')
+    if not enum_class.__members__:
+      raise ValueError('enum_class cannot be empty, but "{}" is empty.'
+                       .format(enum_class))
+    if not case_sensitive:
+      members = collections.Counter(
+          name.lower() for name in enum_class.__members__)
+      duplicate_keys = {
+          member for member, count in members.items() if count > 1
+      }
+      if duplicate_keys:
+        raise ValueError(
+            'Duplicate enum values for {} using case_sensitive=False'.format(
+                duplicate_keys))
+
+    super().__init__()
+    self.enum_class = enum_class
+    self._case_sensitive = case_sensitive
+    if case_sensitive:
+      self._member_names = tuple(enum_class.__members__)
+    else:
+      self._member_names = tuple(
+          name.lower() for name in enum_class.__members__)
+
+  @property
+  def member_names(self) -> Sequence[str]:
+    """The accepted enum names, in lowercase if not case sensitive."""
+    return self._member_names
+
+  def parse(self, argument: _ET | str) -> _ET:
+    """Determines validity of argument and returns the correct element of enum.
+
+    Args:
+      argument: str or Enum class member, the supplied flag value.
+
+    Returns:
+      The first matching Enum class member in Enum class.
+
+    Raises:
+      ValueError: Raised when argument didn't match anything in enum.
+    """
+    if isinstance(argument, self.enum_class):
+      return argument  # pytype: disable=bad-return-type
+    elif not isinstance(argument, str):
+      raise ValueError(
+          '{} is not an enum member or a name of a member in {}'.format(
+              argument, self.enum_class))
+    key = EnumParser(
+        self._member_names, case_sensitive=self._case_sensitive).parse(argument)
+    if self._case_sensitive:
+      return self.enum_class[key]
+    else:
+      # If EnumParser.parse() return a value, we're guaranteed to find it
+      # as a member of the class
+      return next(value for name, value in self.enum_class.__members__.items()
+                  if name.lower() == key.lower())
+
+  def flag_type(self) -> str:
+    """See base class."""
+    return 'enum class'
+
+
+class ListSerializer(Generic[_T], ArgumentSerializer[list[_T]]):
+
+  def __init__(self, list_sep: str) -> None:
+    self.list_sep = list_sep
+
+  def serialize(self, value: list[_T]) -> str:
+    """See base class."""
+    return self.list_sep.join([str(x) for x in value])
+
+
+class EnumClassListSerializer(ListSerializer[_ET]):
+  """A serializer for :class:`MultiEnumClass` flags.
+
+  This serializer simply joins the output of `EnumClassSerializer` using a
+  provided separator.
+  """
+
+  _element_serializer: 'EnumClassSerializer'
+
+  def __init__(self, list_sep: str, **kwargs) -> None:
+    """Initializes EnumClassListSerializer.
+
+    Args:
+      list_sep: String to be used as a separator when serializing
+      **kwargs: Keyword arguments to the `EnumClassSerializer` used to serialize
+        individual values.
+    """
+    super().__init__(list_sep)
+    self._element_serializer = EnumClassSerializer(**kwargs)
+
+  def serialize(self, value: _ET | list[_ET]) -> str:
+    """See base class."""
+    if isinstance(value, list):
+      return self.list_sep.join(
+          self._element_serializer.serialize(x) for x in value)
+    else:
+      return self._element_serializer.serialize(value)
+
+
+class CsvListSerializer(ListSerializer[str]):
+
+  def serialize(self, value: list[str]) -> str:
+    """Serializes a list as a CSV string or unicode."""
+    output = io.StringIO()
+    writer = csv.writer(output, delimiter=self.list_sep)
+    writer.writerow([str(x) for x in value])
+    serialized_value = output.getvalue().strip()
+
+    # We need the returned value to be pure ascii or Unicodes so that
+    # when the xml help is generated they are usefully encodable.
+    return str(serialized_value)
+
+
+class EnumClassSerializer(ArgumentSerializer[_ET]):
+  """Class for generating string representations of an enum class flag value."""
+
+  def __init__(self, lowercase: bool) -> None:
+    """Initializes EnumClassSerializer.
+
+    Args:
+      lowercase: If True, enum member names are lowercased during serialization.
+    """
+    self._lowercase = lowercase
+
+  def serialize(self, value: _ET) -> str:
+    """Returns a serialized string of the Enum class value."""
+    as_string = str(value.name)
+    return as_string.lower() if self._lowercase else as_string
+
+
+class BaseListParser(ArgumentParser):
+  """Base class for a parser of lists of strings.
+
+  To extend, inherit from this class; from the subclass ``__init__``, call::
+
+      super().__init__(token, name)
+
+  where token is a character used to tokenize, and name is a description
+  of the separator.
+  """
+
+  def __init__(self, token: str | None = None, name: str | None = None) -> None:
+    assert name
+    super().__init__()
+    self._token = token
+    self._name = name
+    self.syntactic_help = 'a %s separated list' % self._name
+
+  def parse(self, argument: str) -> list[str]:
+    """See base class."""
+    if isinstance(argument, list):
+      return argument
+    elif not argument:
+      return []
+    else:
+      return [s.strip() for s in argument.split(self._token)]
+
+  def flag_type(self) -> str:
+    """See base class."""
+    return '%s separated list of strings' % self._name
+
+
+class ListParser(BaseListParser):
+  """Parser for a comma-separated list of strings."""
+
+  def __init__(self) -> None:
+    super().__init__(',', 'comma')
+
+  def parse(self, argument: str | list[str]) -> list[str]:
+    """Parses argument as comma-separated list of strings."""
+    if isinstance(argument, list):
+      return argument
+    elif not argument:
+      return []
+    else:
+      try:
+        return [s.strip() for s in list(csv.reader([argument], strict=True))[0]]
+      except csv.Error as e:
+        # Provide a helpful report for case like
+        #   --listflag="$(printf 'hello,\nworld')"
+        # IOW, list flag values containing naked newlines.  This error
+        # was previously "reported" by allowing csv.Error to
+        # propagate.
+        raise ValueError('Unable to parse the value %r as a %s: %s'
+                         % (argument, self.flag_type(), e))
+
+  def _custom_xml_dom_elements(
+      self, doc: minidom.Document
+  ) -> list[minidom.Element]:
+    elements = super()._custom_xml_dom_elements(doc)
+    elements.append(_helpers.create_xml_dom_element(
+        doc, 'list_separator', repr(',')))
+    return elements
+
+
+class WhitespaceSeparatedListParser(BaseListParser):
+  """Parser for a whitespace-separated list of strings."""
+
+  def __init__(self, comma_compat: bool = False) -> None:
+    """Initializer.
+
+    Args:
+      comma_compat: bool, whether to support comma as an additional separator.
+          If False then only whitespace is supported.  This is intended only for
+          backwards compatibility with flags that used to be comma-separated.
+    """
+    self._comma_compat = comma_compat
+    name = 'whitespace or comma' if self._comma_compat else 'whitespace'
+    super().__init__(None, name)
+
+  def parse(self, argument: str | list[str]) -> list[str]:
+    """Parses argument as whitespace-separated list of strings.
+
+    It also parses argument as comma-separated list of strings if requested.
+
+    Args:
+      argument: string argument passed in the commandline.
+
+    Returns:
+      [str], the parsed flag value.
+    """
+    if isinstance(argument, list):
+      return argument
+    elif not argument:
+      return []
+    else:
+      if self._comma_compat:
+        argument = argument.replace(',', ' ')
+      return argument.split()
+
+  def _custom_xml_dom_elements(
+      self, doc: minidom.Document
+  ) -> list[minidom.Element]:
+    elements = super()._custom_xml_dom_elements(doc)
+    separators = list(string.whitespace)
+    if self._comma_compat:
+      separators.append(',')
+    separators.sort()
+    for sep_char in separators:
+      elements.append(_helpers.create_xml_dom_element(
+          doc, 'list_separator', repr(sep_char)))
+    return elements

.venv/lib/python3.13/site-packages/absl/flags/_defines.py

@@ -0,0 +1,1702 @@
+# Copyright 2017 The Abseil Authors.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+"""This modules contains flags DEFINE functions.
+
+Do NOT import this module directly. Import the flags package and use the
+aliases defined at the package level instead.
+"""
+
+from collections.abc import Iterable
+import enum
+import sys
+import types
+from typing import Any, Literal, TypeVar, overload
+
+from absl.flags import _argument_parser
+from absl.flags import _exceptions
+from absl.flags import _flag
+from absl.flags import _flagvalues
+from absl.flags import _helpers
+from absl.flags import _validators
+
+_helpers.disclaim_module_ids.add(id(sys.modules[__name__]))
+
+_T = TypeVar('_T')
+_ET = TypeVar('_ET', bound=enum.Enum)
+
+
+def _register_bounds_validator_if_needed(parser, name, flag_values):
+  """Enforces lower and upper bounds for numeric flags.
+
+  Args:
+    parser: NumericParser (either FloatParser or IntegerParser), provides lower
+      and upper bounds, and help text to display.
+    name: str, name of the flag
+    flag_values: FlagValues.
+  """
+  if parser.lower_bound is not None or parser.upper_bound is not None:
+
+    def checker(value):
+      if value is not None and parser.is_outside_bounds(value):
+        message = '%s is not %s' % (value, parser.syntactic_help)
+        raise _exceptions.ValidationError(message)
+      return True
+
+    _validators.register_validator(name, checker, flag_values=flag_values)
+
+
+@overload
+def DEFINE(  # pylint: disable=invalid-name
+    parser: _argument_parser.ArgumentParser[_T],
+    name: str,
+    default: Any,
+    help: str | None,  # pylint: disable=redefined-builtin
+    flag_values: _flagvalues.FlagValues = ...,
+    serializer: _argument_parser.ArgumentSerializer[_T] | None = ...,
+    module_name: str | None = ...,
+    required: Literal[True] = ...,
+    **args: Any
+) -> _flagvalues.FlagHolder[_T]:
+  ...
+
+
+@overload
+def DEFINE(  # pylint: disable=invalid-name
+    parser: _argument_parser.ArgumentParser[_T],
+    name: str,
+    default: Any | None,
+    help: str | None,  # pylint: disable=redefined-builtin
+    flag_values: _flagvalues.FlagValues = ...,
+    serializer: _argument_parser.ArgumentSerializer[_T] | None = ...,
+    module_name: str | None = ...,
+    required: bool = ...,
+    **args: Any
+) -> _flagvalues.FlagHolder[_T | None]:
+  ...
+
+
+def DEFINE(  # pylint: disable=invalid-name
+    parser,
+    name,
+    default,
+    help,  # pylint: disable=redefined-builtin
+    flag_values=_flagvalues.FLAGS,
+    serializer=None,
+    module_name=None,
+    required=False,
+    **args):
+  """Registers a generic Flag object.
+
+  NOTE: in the docstrings of all DEFINE* functions, "registers" is short
+  for "creates a new flag and registers it".
+
+  Auxiliary function: clients should use the specialized ``DEFINE_<type>``
+  function instead.
+
+  Args:
+    parser: :class:`ArgumentParser`, used to parse the flag arguments.
+    name: str, the flag name.
+    default: The default value of the flag.
+    help: str, the help message.
+    flag_values: :class:`FlagValues`, the FlagValues instance with which the
+      flag will be registered. This should almost never need to be overridden.
+    serializer: :class:`ArgumentSerializer`, the flag serializer instance.
+    module_name: str, the name of the Python module declaring this flag. If not
+      provided, it will be computed using the stack trace of this call.
+    required: bool, is this a required flag. This must be used as a keyword
+      argument.
+    **args: dict, the extra keyword args that are passed to ``Flag.__init__``.
+
+  Returns:
+    a handle to defined flag.
+  """
+  return DEFINE_flag(
+      _flag.Flag(parser, serializer, name, default, help, **args),
+      flag_values,
+      module_name,
+      required=True if required else False,
+  )
+
+
+@overload
+def DEFINE_flag(  # pylint: disable=invalid-name
+    flag: _flag.Flag[_T],
+    flag_values: _flagvalues.FlagValues = ...,
+    module_name: str | None = ...,
+    required: Literal[True] = ...,
+) -> _flagvalues.FlagHolder[_T]:
+  ...
+
+
+@overload
+def DEFINE_flag(  # pylint: disable=invalid-name
+    flag: _flag.Flag[_T],
+    flag_values: _flagvalues.FlagValues = ...,
+    module_name: str | None = ...,
+    required: bool = ...,
+) -> _flagvalues.FlagHolder[_T | None]:
+  ...
+
+
+def DEFINE_flag(  # pylint: disable=invalid-name
+    flag,
+    flag_values=_flagvalues.FLAGS,
+    module_name=None,
+    required=False):
+  """Registers a :class:`Flag` object with a :class:`FlagValues` object.
+
+  By default, the global :const:`FLAGS` ``FlagValue`` object is used.
+
+  Typical users will use one of the more specialized DEFINE_xxx
+  functions, such as :func:`DEFINE_string` or :func:`DEFINE_integer`.  But
+  developers who need to create :class:`Flag` objects themselves should use
+  this function to register their flags.
+
+  Args:
+    flag: :class:`Flag`, a flag that is key to the module.
+    flag_values: :class:`FlagValues`, the ``FlagValues`` instance with which the
+      flag will be registered. This should almost never need to be overridden.
+    module_name: str, the name of the Python module declaring this flag. If not
+      provided, it will be computed using the stack trace of this call.
+    required: bool, is this a required flag. This must be used as a keyword
+      argument.
+
+  Returns:
+    a handle to defined flag.
+  """
+  if required and flag.default is not None:
+    raise ValueError(
+        'Required flag --%s needs to have None as default' % flag.name
+    )
+  # Copying the reference to flag_values prevents pychecker warnings.
+  fv = flag_values
+  fv[flag.name] = flag
+  # Tell flag_values who's defining the flag.
+  if module_name:
+    module = sys.modules.get(module_name)
+  else:
+    module, module_name = _helpers.get_calling_module_object_and_name()
+  flag_values.register_flag_by_module(module_name, flag)
+  flag_values.register_flag_by_module_id(id(module), flag)
+  if required:
+    _validators.mark_flag_as_required(flag.name, fv)
+  ensure_non_none_value = (flag.default is not None) or required
+  return _flagvalues.FlagHolder(
+      fv, flag, ensure_non_none_value=ensure_non_none_value)
+
+
+def set_default(flag_holder: _flagvalues.FlagHolder[_T], value: _T) -> None:
+  """Changes the default value of the provided flag object.
+
+  The flag's current value is also updated if the flag is currently using
+  the default value, i.e. not specified in the command line, and not set
+  by FLAGS.name = value.
+
+  Args:
+    flag_holder: FlagHolder, the flag to modify.
+    value: The new default value.
+
+  Raises:
+    IllegalFlagValueError: Raised when value is not valid.
+  """
+  flag_holder._flagvalues.set_default(flag_holder.name, value)  # pylint: disable=protected-access
+
+
+def override_value(flag_holder: _flagvalues.FlagHolder[_T], value: _T) -> None:
+  """Overrides the value of the provided flag.
+
+  This value takes precedent over the default value and, when called after flag
+  parsing, any value provided at the command line.
+
+  Args:
+    flag_holder: FlagHolder, the flag to modify.
+    value: The new value.
+
+  Raises:
+    IllegalFlagValueError: The value did not pass the flag parser or validators.
+  """
+  fv = flag_holder._flagvalues  # pylint: disable=protected-access
+  # Ensure the new value satisfies the flag's parser while avoiding side
+  # effects of calling parse().
+  parsed = fv[flag_holder.name]._parse(value)  # pylint: disable=protected-access
+  if parsed != value:
+    raise _exceptions.IllegalFlagValueError(
+        'flag %s: parsed value %r not equal to original %r'
+        % (flag_holder.name, parsed, value)
+    )
+  setattr(fv, flag_holder.name, value)
+
+
+def _internal_declare_key_flags(
+    flag_names: list[str],
+    flag_values: _flagvalues.FlagValues = _flagvalues.FLAGS,
+    key_flag_values: _flagvalues.FlagValues | None = None,
+) -> None:
+  """Declares a flag as key for the calling module.
+
+  Internal function.  User code should call declare_key_flag or
+  adopt_module_key_flags instead.
+
+  Args:
+    flag_names: [str], a list of names of already-registered Flag objects.
+    flag_values: :class:`FlagValues`, the FlagValues instance with which the
+      flags listed in flag_names have registered (the value of the flag_values
+      argument from the ``DEFINE_*`` calls that defined those flags). This
+      should almost never need to be overridden.
+    key_flag_values: :class:`FlagValues`, the FlagValues instance that (among
+      possibly many other things) keeps track of the key flags for each module.
+      Default ``None`` means "same as flag_values".  This should almost never
+      need to be overridden.
+
+  Raises:
+    UnrecognizedFlagError: Raised when the flag is not defined.
+  """
+  key_flag_values = key_flag_values or flag_values
+
+  module = _helpers.get_calling_module()
+
+  for flag_name in flag_names:
+    key_flag_values.register_key_flag_for_module(module, flag_values[flag_name])
+
+
+def declare_key_flag(
+    flag_name: str | _flagvalues.FlagHolder,
+    flag_values: _flagvalues.FlagValues = _flagvalues.FLAGS,
+) -> None:
+  """Declares one flag as key to the current module.
+
+  Key flags are flags that are deemed really important for a module.
+  They are important when listing help messages; e.g., if the
+  --helpshort command-line flag is used, then only the key flags of the
+  main module are listed (instead of all flags, as in the case of
+  --helpfull).
+
+  Sample usage::
+
+      flags.declare_key_flag('flag_1')
+
+  Args:
+    flag_name: str | :class:`FlagHolder`, the name or holder of an already
+      declared flag. (Redeclaring flags as key, including flags implicitly key
+      because they were declared in this module, is a no-op.)
+      Positional-only parameter.
+    flag_values: :class:`FlagValues`, the FlagValues instance in which the
+      flag will be declared as a key flag. This should almost never need to be
+      overridden.
+
+  Raises:
+    ValueError: Raised if flag_name not defined as a Python flag.
+  """
+  flag_name, flag_values = _flagvalues.resolve_flag_ref(flag_name, flag_values)
+  if flag_name in _helpers.SPECIAL_FLAGS:
+    # Take care of the special flags, e.g., --flagfile, --undefok.
+    # These flags are defined in SPECIAL_FLAGS, and are treated
+    # specially during flag parsing, taking precedence over the
+    # user-defined flags.
+    _internal_declare_key_flags([flag_name],
+                                flag_values=_helpers.SPECIAL_FLAGS,
+                                key_flag_values=flag_values)
+    return
+  try:
+    _internal_declare_key_flags([flag_name], flag_values=flag_values)
+  except KeyError:
+    raise ValueError('Flag --%s is undefined. To set a flag as a key flag '
+                     'first define it in Python.' % flag_name)
+
+
+def adopt_module_key_flags(
+    module: Any, flag_values: _flagvalues.FlagValues = _flagvalues.FLAGS
+) -> None:
+  """Declares that all flags key to a module are key to the current module.
+
+  Args:
+    module: module, the module object from which all key flags will be declared
+      as key flags to the current module.
+    flag_values: :class:`FlagValues`, the FlagValues instance in which the
+      flags will be declared as key flags. This should almost never need to be
+      overridden.
+
+  Raises:
+    Error: Raised when given an argument that is a module name (a string),
+        instead of a module object.
+  """
+  if not isinstance(module, types.ModuleType):
+    raise _exceptions.Error('Expected a module object, not %r.' % (module,))
+  _internal_declare_key_flags(
+      [f.name for f in flag_values.get_key_flags_for_module(module.__name__)],
+      flag_values=flag_values)
+  # If module is this flag module, take _helpers.SPECIAL_FLAGS into account.
+  if module == _helpers.FLAGS_MODULE:
+    _internal_declare_key_flags(
+        # As we associate flags with get_calling_module_object_and_name(), the
+        # special flags defined in this module are incorrectly registered with
+        # a different module.  So, we can't use get_key_flags_for_module.
+        # Instead, we take all flags from _helpers.SPECIAL_FLAGS (a private
+        # FlagValues, where no other module should register flags).
+        [_helpers.SPECIAL_FLAGS[name].name for name in _helpers.SPECIAL_FLAGS],
+        flag_values=_helpers.SPECIAL_FLAGS,
+        key_flag_values=flag_values)
+
+
+def disclaim_key_flags() -> None:
+  """Declares that the current module will not define any more key flags.
+
+  Normally, the module that calls the DEFINE_xxx functions claims the
+  flag to be its key flag.  This is undesirable for modules that
+  define additional DEFINE_yyy functions with its own flag parsers and
+  serializers, since that module will accidentally claim flags defined
+  by DEFINE_yyy as its key flags.  After calling this function, the
+  module disclaims flag definitions thereafter, so the key flags will
+  be correctly attributed to the caller of DEFINE_yyy.
+
+  After calling this function, the module will not be able to define
+  any more flags.  This function will affect all FlagValues objects.
+  """
+  globals_for_caller = sys._getframe(1).f_globals  # pylint: disable=protected-access
+  module = _helpers.get_module_object_and_name(globals_for_caller)
+  if module is not None:
+    _helpers.disclaim_module_ids.add(id(module.module))
+
+
+@overload
+def DEFINE_string(  # pylint: disable=invalid-name
+    name: str,
+    default: str | None,
+    help: str | None,  # pylint: disable=redefined-builtin
+    flag_values: _flagvalues.FlagValues = ...,
+    *,
+    required: Literal[True],
+    **args: Any
+) -> _flagvalues.FlagHolder[str]:
+  ...
+
+
+@overload
+def DEFINE_string(  # pylint: disable=invalid-name
+    name: str,
+    default: None,
+    help: str | None,  # pylint: disable=redefined-builtin
+    flag_values: _flagvalues.FlagValues = ...,
+    required: bool = ...,
+    **args: Any
+) -> _flagvalues.FlagHolder[str | None]:
+  ...
+
+
+@overload
+def DEFINE_string(  # pylint: disable=invalid-name
+    name: str,
+    default: str,
+    help: str | None,  # pylint: disable=redefined-builtin
+    flag_values: _flagvalues.FlagValues = ...,
+    required: bool = ...,
+    **args: Any
+) -> _flagvalues.FlagHolder[str]:
+  ...
+
+
+def DEFINE_string(  # pylint: disable=invalid-name
+    name,
+    default,
+    help,  # pylint: disable=redefined-builtin
+    flag_values=_flagvalues.FLAGS,
+    required=False,
+    **args
+):
+  """Registers a flag whose value can be any string."""
+  parser = _argument_parser.ArgumentParser[str]()
+  serializer = _argument_parser.ArgumentSerializer[str]()
+  return DEFINE(
+      parser,
+      name,
+      default,
+      help,
+      flag_values,
+      serializer,
+      required=True if required else False,
+      **args,
+  )
+
+
+@overload
+def DEFINE_boolean(  # pylint: disable=invalid-name
+    name: str,
+    default: None | str | bool | int,
+    help: str | None,  # pylint: disable=redefined-builtin
+    flag_values: _flagvalues.FlagValues = ...,
+    module_name: str | None = ...,
+    *,
+    required: Literal[True],
+    **args: Any
+) -> _flagvalues.FlagHolder[bool]:
+  ...
+
+
+@overload
+def DEFINE_boolean(  # pylint: disable=invalid-name
+    name: str,
+    default: None,
+    help: str | None,  # pylint: disable=redefined-builtin
+    flag_values: _flagvalues.FlagValues = ...,
+    module_name: str | None = ...,
+    required: bool = ...,
+    **args: Any
+) -> _flagvalues.FlagHolder[bool | None]:
+  ...
+
+
+@overload
+def DEFINE_boolean(  # pylint: disable=invalid-name
+    name: str,
+    default: str | bool | int,
+    help: str | None,  # pylint: disable=redefined-builtin
+    flag_values: _flagvalues.FlagValues = ...,
+    module_name: str | None = ...,
+    required: bool = ...,
+    **args: Any
+) -> _flagvalues.FlagHolder[bool]:
+  ...
+
+
+def DEFINE_boolean(  # pylint: disable=invalid-name
+    name,
+    default,
+    help,  # pylint: disable=redefined-builtin
+    flag_values=_flagvalues.FLAGS,
+    module_name=None,
+    required=False,
+    **args
+):
+  """Registers a boolean flag.
+
+  Such a boolean flag does not take an argument.  If a user wants to
+  specify a false value explicitly, the long option beginning with 'no'
+  must be used: i.e. --noflag
+
+  This flag will have a value of None, True or False.  None is possible
+  if default=None and the user does not specify the flag on the command
+  line.
+
+  Args:
+    name: str, the flag name.
+    default: bool|str|None, the default value of the flag.
+    help: str, the help message.
+    flag_values: :class:`FlagValues`, the FlagValues instance with which the
+      flag will be registered. This should almost never need to be overridden.
+    module_name: str, the name of the Python module declaring this flag. If not
+      provided, it will be computed using the stack trace of this call.
+    required: bool, is this a required flag. This must be used as a keyword
+      argument.
+    **args: dict, the extra keyword args that are passed to ``Flag.__init__``.
+
+  Returns:
+    a handle to defined flag.
+  """
+  return DEFINE_flag(  # pytype: disable=bad-return-type
+      _flag.BooleanFlag(name, default, help, **args),
+      flag_values,
+      module_name,
+      required=True if required else False,
+  )
+
+
+@overload
+def DEFINE_float(  # pylint: disable=invalid-name
+    name: str,
+    default: None | float | str,
+    help: str | None,  # pylint: disable=redefined-builtin
+    lower_bound: float | None = ...,
+    upper_bound: float | None = ...,
+    flag_values: _flagvalues.FlagValues = ...,
+    *,
+    required: Literal[True],
+    **args: Any
+) -> _flagvalues.FlagHolder[float]:
+  ...
+
+
+@overload
+def DEFINE_float(  # pylint: disable=invalid-name
+    name: str,
+    default: None,
+    help: str | None,  # pylint: disable=redefined-builtin
+    lower_bound: float | None = ...,
+    upper_bound: float | None = ...,
+    flag_values: _flagvalues.FlagValues = ...,
+    required: bool = ...,
+    **args: Any
+) -> _flagvalues.FlagHolder[float | None]:
+  ...
+
+
+@overload
+def DEFINE_float(  # pylint: disable=invalid-name
+    name: str,
+    default: float | str,
+    help: str | None,  # pylint: disable=redefined-builtin
+    lower_bound: float | None = ...,
+    upper_bound: float | None = ...,
+    flag_values: _flagvalues.FlagValues = ...,
+    required: bool = ...,
+    **args: Any
+) -> _flagvalues.FlagHolder[float]:
+  ...
+
+
+def DEFINE_float(  # pylint: disable=invalid-name
+    name,
+    default,
+    help,  # pylint: disable=redefined-builtin
+    lower_bound=None,
+    upper_bound=None,
+    flag_values=_flagvalues.FLAGS,
+    required=False,
+    **args
+):
+  """Registers a flag whose value must be a float.
+
+  If ``lower_bound`` or ``upper_bound`` are set, then this flag must be
+  within the given range.
+
+  Args:
+    name: str, the flag name.
+    default: float|str|None, the default value of the flag.
+    help: str, the help message.
+    lower_bound: float, min value of the flag.
+    upper_bound: float, max value of the flag.
+    flag_values: :class:`FlagValues`, the FlagValues instance with which the
+      flag will be registered. This should almost never need to be overridden.
+    required: bool, is this a required flag. This must be used as a keyword
+      argument.
+    **args: dict, the extra keyword args that are passed to :func:`DEFINE`.
+
+  Returns:
+    a handle to defined flag.
+  """
+  parser = _argument_parser.FloatParser(lower_bound, upper_bound)
+  serializer = _argument_parser.ArgumentSerializer()
+  result = DEFINE(
+      parser,
+      name,
+      default,
+      help,  # pylint: disable=redefined-builtin
+      flag_values,
+      serializer,
+      required=True if required else False,
+      **args,
+  )
+  _register_bounds_validator_if_needed(parser, name, flag_values=flag_values)
+  return result
+
+
+@overload
+def DEFINE_integer(  # pylint: disable=invalid-name
+    name: str,
+    default: None | int | str,
+    help: str | None,  # pylint: disable=redefined-builtin
+    lower_bound: int | None = ...,
+    upper_bound: int | None = ...,
+    flag_values: _flagvalues.FlagValues = ...,
+    *,
+    required: Literal[True],
+    **args: Any
+) -> _flagvalues.FlagHolder[int]:
+  ...
+
+
+@overload
+def DEFINE_integer(  # pylint: disable=invalid-name
+    name: str,
+    default: None,
+    help: str | None,  # pylint: disable=redefined-builtin
+    lower_bound: int | None = ...,
+    upper_bound: int | None = ...,
+    flag_values: _flagvalues.FlagValues = ...,
+    required: bool = ...,
+    **args: Any
+) -> _flagvalues.FlagHolder[int | None]:
+  ...
+
+
+@overload
+def DEFINE_integer(  # pylint: disable=invalid-name
+    name: str,
+    default: int | str,
+    help: str | None,  # pylint: disable=redefined-builtin
+    lower_bound: int | None = ...,
+    upper_bound: int | None = ...,
+    flag_values: _flagvalues.FlagValues = ...,
+    required: bool = ...,
+    **args: Any
+) -> _flagvalues.FlagHolder[int]:
+  ...
+
+
+def DEFINE_integer(  # pylint: disable=invalid-name
+    name,
+    default,
+    help,  # pylint: disable=redefined-builtin
+    lower_bound=None,
+    upper_bound=None,
+    flag_values=_flagvalues.FLAGS,
+    required=False,
+    **args
+):
+  """Registers a flag whose value must be an integer.
+
+  If ``lower_bound``, or ``upper_bound`` are set, then this flag must be
+  within the given range.
+
+  Args:
+    name: str, the flag name.
+    default: int|str|None, the default value of the flag.
+    help: str, the help message.
+    lower_bound: int, min value of the flag.
+    upper_bound: int, max value of the flag.
+    flag_values: :class:`FlagValues`, the FlagValues instance with which the
+      flag will be registered. This should almost never need to be overridden.
+    required: bool, is this a required flag. This must be used as a keyword
+      argument.
+    **args: dict, the extra keyword args that are passed to :func:`DEFINE`.
+
+  Returns:
+    a handle to defined flag.
+  """
+  parser = _argument_parser.IntegerParser(lower_bound, upper_bound)
+  serializer = _argument_parser.ArgumentSerializer()
+  result = DEFINE(
+      parser,
+      name,
+      default,
+      help,  # pylint: disable=redefined-builtin
+      flag_values,
+      serializer,
+      required=True if required else False,
+      **args,
+  )
+  _register_bounds_validator_if_needed(parser, name, flag_values=flag_values)
+  return result
+
+
+@overload
+def DEFINE_enum(  # pylint: disable=invalid-name
+    name: str,
+    default: str | None,
+    enum_values: Iterable[str],
+    help: str | None,  # pylint: disable=redefined-builtin
+    flag_values: _flagvalues.FlagValues = ...,
+    module_name: str | None = ...,
+    *,
+    required: Literal[True],
+    **args: Any
+) -> _flagvalues.FlagHolder[str]:
+  ...
+
+
+@overload
+def DEFINE_enum(  # pylint: disable=invalid-name
+    name: str,
+    default: None,
+    enum_values: Iterable[str],
+    help: str | None,  # pylint: disable=redefined-builtin
+    flag_values: _flagvalues.FlagValues = ...,
+    module_name: str | None = ...,
+    required: bool = ...,
+    **args: Any
+) -> _flagvalues.FlagHolder[str | None]:
+  ...
+
+
+@overload
+def DEFINE_enum(  # pylint: disable=invalid-name
+    name: str,
+    default: str,
+    enum_values: Iterable[str],
+    help: str | None,  # pylint: disable=redefined-builtin
+    flag_values: _flagvalues.FlagValues = ...,
+    module_name: str | None = ...,
+    required: bool = ...,
+    **args: Any
+) -> _flagvalues.FlagHolder[str]:
+  ...
+
+
+def DEFINE_enum(  # pylint: disable=invalid-name
+    name,
+    default,
+    enum_values,
+    help,  # pylint: disable=redefined-builtin
+    flag_values=_flagvalues.FLAGS,
+    module_name=None,
+    required=False,
+    **args
+):
+  """Registers a flag whose value can be any string from enum_values.
+
+  Instead of a string enum, prefer `DEFINE_enum_class`, which allows
+  defining enums from an `enum.Enum` class.
+
+  Args:
+    name: str, the flag name.
+    default: str|None, the default value of the flag.
+    enum_values: [str], a non-empty list of strings with the possible values for
+      the flag.
+    help: str, the help message.
+    flag_values: :class:`FlagValues`, the FlagValues instance with which the
+      flag will be registered. This should almost never need to be overridden.
+    module_name: str, the name of the Python module declaring this flag. If not
+      provided, it will be computed using the stack trace of this call.
+    required: bool, is this a required flag. This must be used as a keyword
+      argument.
+    **args: dict, the extra keyword args that are passed to ``Flag.__init__``.
+
+  Returns:
+    a handle to defined flag.
+  """
+  result = DEFINE_flag(
+      _flag.EnumFlag(name, default, help, enum_values, **args),
+      flag_values,
+      module_name,
+      required=True if required else False,
+  )
+  return result
+
+
+@overload
+def DEFINE_enum_class(  # pylint: disable=invalid-name
+    name: str,
+    default: None | _ET | str,
+    enum_class: type[_ET],
+    help: str | None,  # pylint: disable=redefined-builtin
+    flag_values: _flagvalues.FlagValues = ...,
+    module_name: str | None = ...,
+    case_sensitive: bool = ...,
+    *,
+    required: Literal[True],
+    **args: Any
+) -> _flagvalues.FlagHolder[_ET]:
+  ...
+
+
+@overload
+def DEFINE_enum_class(  # pylint: disable=invalid-name
+    name: str,
+    default: None,
+    enum_class: type[_ET],
+    help: str | None,  # pylint: disable=redefined-builtin
+    flag_values: _flagvalues.FlagValues = ...,
+    module_name: str | None = ...,
+    case_sensitive: bool = ...,
+    required: bool = ...,
+    **args: Any
+) -> _flagvalues.FlagHolder[_ET | None]:
+  ...
+
+
+@overload
+def DEFINE_enum_class(  # pylint: disable=invalid-name
+    name: str,
+    default: _ET | str,
+    enum_class: type[_ET],
+    help: str | None,  # pylint: disable=redefined-builtin
+    flag_values: _flagvalues.FlagValues = ...,
+    module_name: str | None = ...,
+    case_sensitive: bool = ...,
+    required: bool = ...,
+    **args: Any
+) -> _flagvalues.FlagHolder[_ET]:
+  ...
+
+
+def DEFINE_enum_class(  # pylint: disable=invalid-name
+    name,
+    default,
+    enum_class,
+    help,  # pylint: disable=redefined-builtin
+    flag_values=_flagvalues.FLAGS,
+    module_name=None,
+    case_sensitive=False,
+    required=False,
+    **args
+):
+  """Registers a flag whose value can be the name of enum members.
+
+  Args:
+    name: str, the flag name.
+    default: Enum|str|None, the default value of the flag.
+    enum_class: class, the Enum class with all the possible values for the flag.
+    help: str, the help message.
+    flag_values: :class:`FlagValues`, the FlagValues instance with which the
+      flag will be registered. This should almost never need to be overridden.
+    module_name: str, the name of the Python module declaring this flag. If not
+      provided, it will be computed using the stack trace of this call.
+    case_sensitive: bool, whether to map strings to members of the enum_class
+      without considering case.
+    required: bool, is this a required flag. This must be used as a keyword
+      argument.
+    **args: dict, the extra keyword args that are passed to ``Flag.__init__``.
+
+  Returns:
+    a handle to defined flag.
+  """
+  # NOTE: pytype fails if this is a direct return.
+  result = DEFINE_flag(
+      _flag.EnumClassFlag(
+          name, default, help, enum_class, case_sensitive=case_sensitive, **args
+      ),
+      flag_values,
+      module_name,
+      required=True if required else False,
+  )
+  return result
+
+
+@overload
+def DEFINE_list(  # pylint: disable=invalid-name
+    name: str,
+    default: None | Iterable[str] | str,
+    help: str,  # pylint: disable=redefined-builtin
+    flag_values: _flagvalues.FlagValues = ...,
+    *,
+    required: Literal[True],
+    **args: Any
+) -> _flagvalues.FlagHolder[list[str]]:
+  ...
+
+
+@overload
+def DEFINE_list(  # pylint: disable=invalid-name
+    name: str,
+    default: None,
+    help: str,  # pylint: disable=redefined-builtin
+    flag_values: _flagvalues.FlagValues = ...,
+    required: bool = ...,
+    **args: Any
+) -> _flagvalues.FlagHolder[list[str] | None]:
+  ...
+
+
+@overload
+def DEFINE_list(  # pylint: disable=invalid-name
+    name: str,
+    default: Iterable[str] | str,
+    help: str,  # pylint: disable=redefined-builtin
+    flag_values: _flagvalues.FlagValues = ...,
+    required: bool = ...,
+    **args: Any
+) -> _flagvalues.FlagHolder[list[str]]:
+  ...
+
+
+def DEFINE_list(  # pylint: disable=invalid-name
+    name,
+    default,
+    help,  # pylint: disable=redefined-builtin
+    flag_values=_flagvalues.FLAGS,
+    required=False,
+    **args
+):
+  """Registers a flag whose value is a comma-separated list of strings.
+
+  The flag value is parsed with a CSV parser.
+
+  Args:
+    name: str, the flag name.
+    default: list|str|None, the default value of the flag.
+    help: str, the help message.
+    flag_values: :class:`FlagValues`, the FlagValues instance with which the
+      flag will be registered. This should almost never need to be overridden.
+    required: bool, is this a required flag. This must be used as a keyword
+      argument.
+    **args: Dictionary with extra keyword args that are passed to the
+      ``Flag.__init__``.
+
+  Returns:
+    a handle to defined flag.
+  """
+  parser = _argument_parser.ListParser()
+  serializer = _argument_parser.CsvListSerializer(',')
+  return DEFINE(
+      parser,
+      name,
+      default,
+      help,
+      flag_values,
+      serializer,
+      required=True if required else False,
+      **args,
+  )
+
+
+@overload
+def DEFINE_spaceseplist(  # pylint: disable=invalid-name
+    name: str,
+    default: None | Iterable[str] | str,
+    help: str,  # pylint: disable=redefined-builtin
+    comma_compat: bool = ...,
+    flag_values: _flagvalues.FlagValues = ...,
+    *,
+    required: Literal[True],
+    **args: Any
+) -> _flagvalues.FlagHolder[list[str]]:
+  ...
+
+
+@overload
+def DEFINE_spaceseplist(  # pylint: disable=invalid-name
+    name: str,
+    default: None,
+    help: str,  # pylint: disable=redefined-builtin
+    comma_compat: bool = ...,
+    flag_values: _flagvalues.FlagValues = ...,
+    required: bool = ...,
+    **args: Any
+) -> _flagvalues.FlagHolder[list[str] | None]:
+  ...
+
+
+@overload
+def DEFINE_spaceseplist(  # pylint: disable=invalid-name
+    name: str,
+    default: Iterable[str] | str,
+    help: str,  # pylint: disable=redefined-builtin
+    comma_compat: bool = ...,
+    flag_values: _flagvalues.FlagValues = ...,
+    required: bool = ...,
+    **args: Any
+) -> _flagvalues.FlagHolder[list[str]]:
+  ...
+
+
+def DEFINE_spaceseplist(  # pylint: disable=invalid-name
+    name,
+    default,
+    help,  # pylint: disable=redefined-builtin
+    comma_compat=False,
+    flag_values=_flagvalues.FLAGS,
+    required=False,
+    **args
+):
+  """Registers a flag whose value is a whitespace-separated list of strings.
+
+  Any whitespace can be used as a separator.
+
+  Args:
+    name: str, the flag name.
+    default: list|str|None, the default value of the flag.
+    help: str, the help message.
+    comma_compat: bool - Whether to support comma as an additional separator. If
+      false then only whitespace is supported.  This is intended only for
+      backwards compatibility with flags that used to be comma-separated.
+    flag_values: :class:`FlagValues`, the FlagValues instance with which the
+      flag will be registered. This should almost never need to be overridden.
+    required: bool, is this a required flag. This must be used as a keyword
+      argument.
+    **args: Dictionary with extra keyword args that are passed to the
+      ``Flag.__init__``.
+
+  Returns:
+    a handle to defined flag.
+  """
+  parser = _argument_parser.WhitespaceSeparatedListParser(
+      comma_compat=comma_compat)
+  serializer = _argument_parser.ListSerializer(' ')
+  return DEFINE(
+      parser,
+      name,
+      default,
+      help,
+      flag_values,
+      serializer,
+      required=True if required else False,
+      **args,
+  )
+
+
+@overload
+def DEFINE_multi(  # pylint: disable=invalid-name
+    parser: _argument_parser.ArgumentParser[_T],
+    serializer: _argument_parser.ArgumentSerializer[_T],
+    name: str,
+    default: Iterable[_T],
+    help: str,  # pylint: disable=redefined-builtin
+    flag_values: _flagvalues.FlagValues = ...,
+    module_name: str | None = ...,
+    *,
+    required: Literal[True],
+    **args: Any
+) -> _flagvalues.FlagHolder[list[_T]]:
+  ...
+
+
+@overload
+def DEFINE_multi(  # pylint: disable=invalid-name
+    parser: _argument_parser.ArgumentParser[_T],
+    serializer: _argument_parser.ArgumentSerializer[_T],
+    name: str,
+    default: None | _T,
+    help: str,  # pylint: disable=redefined-builtin
+    flag_values: _flagvalues.FlagValues = ...,
+    module_name: str | None = ...,
+    *,
+    required: Literal[True],
+    **args: Any
+) -> _flagvalues.FlagHolder[list[_T]]:
+  ...
+
+
+@overload
+def DEFINE_multi(  # pylint: disable=invalid-name
+    parser: _argument_parser.ArgumentParser[_T],
+    serializer: _argument_parser.ArgumentSerializer[_T],
+    name: str,
+    default: None,
+    help: str,  # pylint: disable=redefined-builtin
+    flag_values: _flagvalues.FlagValues = ...,
+    module_name: str | None = ...,
+    required: bool = ...,
+    **args: Any
+) -> _flagvalues.FlagHolder[list[_T] | None]:
+  ...
+
+
+@overload
+def DEFINE_multi(  # pylint: disable=invalid-name
+    parser: _argument_parser.ArgumentParser[_T],
+    serializer: _argument_parser.ArgumentSerializer[_T],
+    name: str,
+    default: Iterable[_T],
+    help: str,  # pylint: disable=redefined-builtin
+    flag_values: _flagvalues.FlagValues = ...,
+    module_name: str | None = ...,
+    required: bool = ...,
+    **args: Any
+) -> _flagvalues.FlagHolder[list[_T]]:
+  ...
+
+
+@overload
+def DEFINE_multi(  # pylint: disable=invalid-name
+    parser: _argument_parser.ArgumentParser[_T],
+    serializer: _argument_parser.ArgumentSerializer[_T],
+    name: str,
+    default: _T,
+    help: str,  # pylint: disable=redefined-builtin
+    flag_values: _flagvalues.FlagValues = ...,
+    module_name: str | None = ...,
+    required: bool = ...,
+    **args: Any
+) -> _flagvalues.FlagHolder[list[_T]]:
+  ...
+
+
+def DEFINE_multi(  # pylint: disable=invalid-name
+    parser,
+    serializer,
+    name,
+    default,
+    help,  # pylint: disable=redefined-builtin
+    flag_values=_flagvalues.FLAGS,
+    module_name=None,
+    required=False,
+    **args
+):
+  """Registers a generic MultiFlag that parses its args with a given parser.
+
+  Auxiliary function.  Normal users should NOT use it directly.
+
+  Developers who need to create their own 'Parser' classes for options
+  which can appear multiple times can call this module function to
+  register their flags.
+
+  Args:
+    parser: ArgumentParser, used to parse the flag arguments.
+    serializer: ArgumentSerializer, the flag serializer instance.
+    name: str, the flag name.
+    default: Union[Iterable[T], str, None], the default value of the flag. If
+      the value is text, it will be parsed as if it was provided from the
+      command line. If the value is a non-string iterable, it will be iterated
+      over to create a shallow copy of the values. If it is None, it is left
+      as-is.
+    help: str, the help message.
+    flag_values: :class:`FlagValues`, the FlagValues instance with which the
+      flag will be registered. This should almost never need to be overridden.
+    module_name: A string, the name of the Python module declaring this flag. If
+      not provided, it will be computed using the stack trace of this call.
+    required: bool, is this a required flag. This must be used as a keyword
+      argument.
+    **args: Dictionary with extra keyword args that are passed to the
+      ``Flag.__init__``.
+
+  Returns:
+    a handle to defined flag.
+  """
+  result = DEFINE_flag(
+      _flag.MultiFlag(parser, serializer, name, default, help, **args),
+      flag_values,
+      module_name,
+      required=True if required else False,
+  )
+  return result
+
+
+@overload
+def DEFINE_multi_string(  # pylint: disable=invalid-name
+    name: str,
+    default: None | Iterable[str] | str,
+    help: str,  # pylint: disable=redefined-builtin
+    flag_values: _flagvalues.FlagValues = ...,
+    *,
+    required: Literal[True],
+    **args: Any
+) -> _flagvalues.FlagHolder[list[str]]:
+  ...
+
+
+@overload
+def DEFINE_multi_string(  # pylint: disable=invalid-name
+    name: str,
+    default: None,
+    help: str,  # pylint: disable=redefined-builtin
+    flag_values: _flagvalues.FlagValues = ...,
+    required: bool = ...,
+    **args: Any
+) -> _flagvalues.FlagHolder[list[str] | None]:
+  ...
+
+
+@overload
+def DEFINE_multi_string(  # pylint: disable=invalid-name
+    name: str,
+    default: Iterable[str] | str,
+    help: str,  # pylint: disable=redefined-builtin
+    flag_values: _flagvalues.FlagValues = ...,
+    required: bool = ...,
+    **args: Any
+) -> _flagvalues.FlagHolder[list[str]]:
+  ...
+
+
+def DEFINE_multi_string(  # pylint: disable=invalid-name
+    name,
+    default,
+    help,  # pylint: disable=redefined-builtin
+    flag_values=_flagvalues.FLAGS,
+    required=False,
+    **args
+):
+  """Registers a flag whose value can be a list of any strings.
+
+  Use the flag on the command line multiple times to place multiple
+  string values into the list.  The 'default' may be a single string
+  (which will be converted into a single-element list) or a list of
+  strings.
+
+
+  Args:
+    name: str, the flag name.
+    default: Union[Iterable[str], str, None], the default value of the flag; see
+      :func:`DEFINE_multi`.
+    help: str, the help message.
+    flag_values: :class:`FlagValues`, the FlagValues instance with which the
+      flag will be registered. This should almost never need to be overridden.
+    required: bool, is this a required flag. This must be used as a keyword
+      argument.
+    **args: Dictionary with extra keyword args that are passed to the
+      ``Flag.__init__``.
+
+  Returns:
+    a handle to defined flag.
+  """
+  parser = _argument_parser.ArgumentParser()
+  serializer = _argument_parser.ArgumentSerializer()
+  return DEFINE_multi(
+      parser,
+      serializer,
+      name,
+      default,
+      help,  # pylint: disable=redefined-builtin
+      flag_values,
+      required=True if required else False,
+      **args,
+  )
+
+
+@overload
+def DEFINE_multi_integer(  # pylint: disable=invalid-name
+    name: str,
+    default: None | Iterable[int] | int | str,
+    help: str,  # pylint: disable=redefined-builtin
+    lower_bound: int | None = ...,
+    upper_bound: int | None = ...,
+    flag_values: _flagvalues.FlagValues = ...,
+    *,
+    required: Literal[True],
+    **args: Any
+) -> _flagvalues.FlagHolder[list[int]]:
+  ...
+
+
+@overload
+def DEFINE_multi_integer(  # pylint: disable=invalid-name
+    name: str,
+    default: None,
+    help: str,  # pylint: disable=redefined-builtin
+    lower_bound: int | None = ...,
+    upper_bound: int | None = ...,
+    flag_values: _flagvalues.FlagValues = ...,
+    required: bool = ...,
+    **args: Any
+) -> _flagvalues.FlagHolder[list[int] | None]:
+  ...
+
+
+@overload
+def DEFINE_multi_integer(  # pylint: disable=invalid-name
+    name: str,
+    default: Iterable[int] | int | str,
+    help: str,  # pylint: disable=redefined-builtin
+    lower_bound: int | None = ...,
+    upper_bound: int | None = ...,
+    flag_values: _flagvalues.FlagValues = ...,
+    required: bool = ...,
+    **args: Any
+) -> _flagvalues.FlagHolder[list[int]]:
+  ...
+
+
+def DEFINE_multi_integer(  # pylint: disable=invalid-name
+    name,
+    default,
+    help,  # pylint: disable=redefined-builtin
+    lower_bound=None,
+    upper_bound=None,
+    flag_values=_flagvalues.FLAGS,
+    required=False,
+    **args
+):
+  """Registers a flag whose value can be a list of arbitrary integers.
+
+  Use the flag on the command line multiple times to place multiple
+  integer values into the list.  The 'default' may be a single integer
+  (which will be converted into a single-element list) or a list of
+  integers.
+
+  Args:
+    name: str, the flag name.
+    default: Union[Iterable[int], str, None], the default value of the flag; see
+      `DEFINE_multi`.
+    help: str, the help message.
+    lower_bound: int, min values of the flag.
+    upper_bound: int, max values of the flag.
+    flag_values: :class:`FlagValues`, the FlagValues instance with which the
+      flag will be registered. This should almost never need to be overridden.
+    required: bool, is this a required flag. This must be used as a keyword
+      argument.
+    **args: Dictionary with extra keyword args that are passed to the
+      ``Flag.__init__``.
+
+  Returns:
+    a handle to defined flag.
+  """
+  parser = _argument_parser.IntegerParser(lower_bound, upper_bound)
+  serializer = _argument_parser.ArgumentSerializer()
+  return DEFINE_multi(
+      parser,
+      serializer,
+      name,
+      default,
+      help,  # pylint: disable=redefined-builtin
+      flag_values,
+      required=True if required else False,
+      **args,
+  )
+
+
+@overload
+def DEFINE_multi_float(  # pylint: disable=invalid-name
+    name: str,
+    default: None | Iterable[float] | float | str,
+    help: str,  # pylint: disable=redefined-builtin
+    lower_bound: float | None = ...,
+    upper_bound: float | None = ...,
+    flag_values: _flagvalues.FlagValues = ...,
+    *,
+    required: Literal[True],
+    **args: Any
+) -> _flagvalues.FlagHolder[list[float]]:
+  ...
+
+
+@overload
+def DEFINE_multi_float(  # pylint: disable=invalid-name
+    name: str,
+    default: None,
+    help: str,  # pylint: disable=redefined-builtin
+    lower_bound: float | None = ...,
+    upper_bound: float | None = ...,
+    flag_values: _flagvalues.FlagValues = ...,
+    required: bool = ...,
+    **args: Any
+) -> _flagvalues.FlagHolder[list[float] | None]:
+  ...
+
+
+@overload
+def DEFINE_multi_float(  # pylint: disable=invalid-name
+    name: str,
+    default: Iterable[float] | float | str,
+    help: str,  # pylint: disable=redefined-builtin
+    lower_bound: float | None = ...,
+    upper_bound: float | None = ...,
+    flag_values: _flagvalues.FlagValues = ...,
+    required: bool = ...,
+    **args: Any
+) -> _flagvalues.FlagHolder[list[float]]:
+  ...
+
+
+def DEFINE_multi_float(  # pylint: disable=invalid-name
+    name,
+    default,
+    help,  # pylint: disable=redefined-builtin
+    lower_bound=None,
+    upper_bound=None,
+    flag_values=_flagvalues.FLAGS,
+    required=False,
+    **args
+):
+  """Registers a flag whose value can be a list of arbitrary floats.
+
+  Use the flag on the command line multiple times to place multiple
+  float values into the list.  The 'default' may be a single float
+  (which will be converted into a single-element list) or a list of
+  floats.
+
+  Args:
+    name: str, the flag name.
+    default: Union[Iterable[float], str, None], the default value of the flag;
+      see `DEFINE_multi`.
+    help: str, the help message.
+    lower_bound: float, min values of the flag.
+    upper_bound: float, max values of the flag.
+    flag_values: :class:`FlagValues`, the FlagValues instance with which the
+      flag will be registered. This should almost never need to be overridden.
+    required: bool, is this a required flag. This must be used as a keyword
+      argument.
+    **args: Dictionary with extra keyword args that are passed to the
+      ``Flag.__init__``.
+
+  Returns:
+    a handle to defined flag.
+  """
+  parser = _argument_parser.FloatParser(lower_bound, upper_bound)
+  serializer = _argument_parser.ArgumentSerializer()
+  return DEFINE_multi(
+      parser,
+      serializer,
+      name,
+      default,
+      help,
+      flag_values,
+      required=True if required else False,
+      **args,
+  )
+
+
+@overload
+def DEFINE_multi_enum(  # pylint: disable=invalid-name
+    name: str,
+    default: None | Iterable[str] | str,
+    enum_values: Iterable[str],
+    help: str,  # pylint: disable=redefined-builtin
+    flag_values: _flagvalues.FlagValues = ...,
+    *,
+    required: Literal[True],
+    **args: Any
+) -> _flagvalues.FlagHolder[list[str]]:
+  ...
+
+
+@overload
+def DEFINE_multi_enum(  # pylint: disable=invalid-name
+    name: str,
+    default: None,
+    enum_values: Iterable[str],
+    help: str,  # pylint: disable=redefined-builtin
+    flag_values: _flagvalues.FlagValues = ...,
+    required: bool = ...,
+    **args: Any
+) -> _flagvalues.FlagHolder[list[str] | None]:
+  ...
+
+
+@overload
+def DEFINE_multi_enum(  # pylint: disable=invalid-name
+    name: str,
+    default: Iterable[str] | str,
+    enum_values: Iterable[str],
+    help: str,  # pylint: disable=redefined-builtin
+    flag_values: _flagvalues.FlagValues = ...,
+    required: bool = ...,
+    **args: Any
+) -> _flagvalues.FlagHolder[list[str]]:
+  ...
+
+
+def DEFINE_multi_enum(  # pylint: disable=invalid-name
+    name,
+    default,
+    enum_values,
+    help,  # pylint: disable=redefined-builtin
+    flag_values=_flagvalues.FLAGS,
+    case_sensitive=True,
+    required=False,
+    **args
+):
+  """Registers a flag whose value can be a list strings from enum_values.
+
+  Use the flag on the command line multiple times to place multiple
+  enum values into the list.  The 'default' may be a single string
+  (which will be converted into a single-element list) or a list of
+  strings.
+
+  Args:
+    name: str, the flag name.
+    default: Union[Iterable[str], str, None], the default value of the flag; see
+      `DEFINE_multi`.
+    enum_values: [str], a non-empty list of strings with the possible values for
+      the flag.
+    help: str, the help message.
+    flag_values: :class:`FlagValues`, the FlagValues instance with which the
+      flag will be registered. This should almost never need to be overridden.
+    case_sensitive: Whether or not the enum is to be case-sensitive.
+    required: bool, is this a required flag. This must be used as a keyword
+      argument.
+    **args: Dictionary with extra keyword args that are passed to the
+      ``Flag.__init__``.
+
+  Returns:
+    a handle to defined flag.
+  """
+  parser = _argument_parser.EnumParser(enum_values, case_sensitive)
+  serializer = _argument_parser.ArgumentSerializer()
+  return DEFINE_multi(
+      parser,
+      serializer,
+      name,
+      default,
+      '<%s>: %s' % ('|'.join(enum_values), help),
+      flag_values,
+      required=True if required else False,
+      **args,
+  )
+
+
+@overload
+def DEFINE_multi_enum_class(  # pylint: disable=invalid-name
+    name: str,
+    # This is separate from `Union[None, _ET, Iterable[str], str]` to avoid a
+    # Pytype issue inferring the return value to
+    # FlagHolder[List[Union[_ET, enum.Enum]]] when an iterable of concrete enum
+    # subclasses are used.
+    default: Iterable[_ET],
+    enum_class: type[_ET],
+    help: str,  # pylint: disable=redefined-builtin
+    flag_values: _flagvalues.FlagValues = ...,
+    module_name: str | None = ...,
+    *,
+    required: Literal[True],
+    **args: Any
+) -> _flagvalues.FlagHolder[list[_ET]]:
+  ...
+
+
+@overload
+def DEFINE_multi_enum_class(  # pylint: disable=invalid-name
+    name: str,
+    default: None | _ET | Iterable[str] | str,
+    enum_class: type[_ET],
+    help: str,  # pylint: disable=redefined-builtin
+    flag_values: _flagvalues.FlagValues = ...,
+    module_name: str | None = ...,
+    *,
+    required: Literal[True],
+    **args: Any
+) -> _flagvalues.FlagHolder[list[_ET]]:
+  ...
+
+
+@overload
+def DEFINE_multi_enum_class(  # pylint: disable=invalid-name
+    name: str,
+    default: None,
+    enum_class: type[_ET],
+    help: str,  # pylint: disable=redefined-builtin
+    flag_values: _flagvalues.FlagValues = ...,
+    module_name: str | None = ...,
+    required: bool = ...,
+    **args: Any
+) -> _flagvalues.FlagHolder[list[_ET] | None]:
+  ...
+
+
+@overload
+def DEFINE_multi_enum_class(  # pylint: disable=invalid-name
+    name: str,
+    # This is separate from `Union[None, _ET, Iterable[str], str]` to avoid a
+    # Pytype issue inferring the return value to
+    # FlagHolder[List[Union[_ET, enum.Enum]]] when an iterable of concrete enum
+    # subclasses are used.
+    default: Iterable[_ET],
+    enum_class: type[_ET],
+    help: str,  # pylint: disable=redefined-builtin
+    flag_values: _flagvalues.FlagValues = ...,
+    module_name: str | None = ...,
+    required: bool = ...,
+    **args: Any
+) -> _flagvalues.FlagHolder[list[_ET]]:
+  ...
+
+
+@overload
+def DEFINE_multi_enum_class(  # pylint: disable=invalid-name
+    name: str,
+    default: _ET | Iterable[str] | str,
+    enum_class: type[_ET],
+    help: str,  # pylint: disable=redefined-builtin
+    flag_values: _flagvalues.FlagValues = ...,
+    module_name: str | None = ...,
+    required: bool = ...,
+    **args: Any
+) -> _flagvalues.FlagHolder[list[_ET]]:
+  ...
+
+
+def DEFINE_multi_enum_class(  # pylint: disable=invalid-name
+    name,
+    default,
+    enum_class,
+    help,  # pylint: disable=redefined-builtin
+    flag_values=_flagvalues.FLAGS,
+    module_name=None,
+    case_sensitive=False,
+    required=False,
+    **args
+):
+  """Registers a flag whose value can be a list of enum members.
+
+  Use the flag on the command line multiple times to place multiple
+  enum values into the list.
+
+  Args:
+    name: str, the flag name.
+    default: Union[Iterable[Enum], Iterable[str], Enum, str, None], the default
+      value of the flag; see `DEFINE_multi`; only differences are documented
+      here. If the value is a single Enum, it is treated as a single-item list
+      of that Enum value. If it is an iterable, text values within the iterable
+      will be converted to the equivalent Enum objects.
+    enum_class: class, the Enum class with all the possible values for the flag.
+    help: str, the help message.
+    flag_values: :class:`FlagValues`, the FlagValues instance with which the
+      flag will be registered. This should almost never need to be overridden.
+    module_name: A string, the name of the Python module declaring this flag. If
+      not provided, it will be computed using the stack trace of this call.
+    case_sensitive: bool, whether to map strings to members of the enum_class
+      without considering case.
+    required: bool, is this a required flag. This must be used as a keyword
+      argument.
+    **args: Dictionary with extra keyword args that are passed to the
+      ``Flag.__init__``.
+
+  Returns:
+    a handle to defined flag.
+  """
+  # NOTE: pytype fails if this is a direct return.
+  result = DEFINE_flag(
+      _flag.MultiEnumClassFlag(
+          name,
+          default,
+          help,
+          enum_class,
+          case_sensitive=case_sensitive,
+          **args,
+      ),
+      flag_values,
+      module_name,
+      required=True if required else False,
+  )
+  return result
+
+
+def DEFINE_alias(  # pylint: disable=invalid-name
+    name: str,
+    original_name: str,
+    flag_values: _flagvalues.FlagValues = _flagvalues.FLAGS,
+    module_name: str | None = None,
+) -> _flagvalues.FlagHolder[Any]:
+  """Defines an alias flag for an existing one.
+
+  Args:
+    name: str, the flag name.
+    original_name: str, the original flag name.
+    flag_values: :class:`FlagValues`, the FlagValues instance with which the
+      flag will be registered. This should almost never need to be overridden.
+    module_name: A string, the name of the module that defines this flag.
+
+  Returns:
+    a handle to defined flag.
+
+  Raises:
+    flags.FlagError:
+      UnrecognizedFlagError: if the referenced flag doesn't exist.
+      DuplicateFlagError: if the alias name has been used by some existing flag.
+  """
+  if original_name not in flag_values:
+    raise _exceptions.UnrecognizedFlagError(original_name)
+  flag = flag_values[original_name]
+
+  class _FlagAlias(_flag.Flag):
+    """Overrides Flag class so alias value is copy of original flag value."""
+
+    def parse(self, argument):
+      flag.parse(argument)
+      self.present += 1
+
+    def _parse_from_default(self, value):
+      # The value was already parsed by the aliased flag, so there is no
+      # need to call the parser on it a second time.
+      # Additionally, because of how MultiFlag parses and merges values,
+      # it isn't possible to delegate to the aliased flag and still get
+      # the correct values.
+      return value
+
+    @property
+    def value(self):
+      return flag.value
+
+    @value.setter
+    def value(self, value):
+      flag.value = value
+
+  help_msg = 'Alias for --%s.' % flag.name
+  # If alias_name has been used, flags.DuplicatedFlag will be raised.
+  return DEFINE_flag(
+      _FlagAlias(
+          flag.parser,
+          flag.serializer,
+          name,
+          flag.default,
+          help_msg,
+          boolean=flag.boolean), flag_values, module_name)

.venv/lib/python3.13/site-packages/absl/flags/_exceptions.py

@@ -0,0 +1,107 @@
+# Copyright 2017 The Abseil Authors.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Exception classes in ABSL flags library.
+
+Do NOT import this module directly. Import the flags package and use the
+aliases defined at the package level instead.
+"""
+
+import sys
+
+from absl.flags import _helpers
+
+
+_helpers.disclaim_module_ids.add(id(sys.modules[__name__]))
+
+
+class Error(Exception):
+  """The base class for all flags errors."""
+
+
+class CantOpenFlagFileError(Error):
+  """Raised when flagfile fails to open.
+
+  E.g. the file doesn't exist, or has wrong permissions.
+  """
+
+
+class DuplicateFlagError(Error):
+  """Raised if there is a flag naming conflict."""
+
+  @classmethod
+  def from_flag(cls, flagname, flag_values, other_flag_values=None):
+    """Creates a DuplicateFlagError by providing flag name and values.
+
+    Args:
+      flagname: str, the name of the flag being redefined.
+      flag_values: :class:`FlagValues`, the FlagValues instance containing the
+        first definition of flagname.
+      other_flag_values: :class:`FlagValues`, if it is not None, it should be
+        the FlagValues object where the second definition of flagname occurs.
+        If it is None, we assume that we're being called when attempting to
+        create the flag a second time, and we use the module calling this one
+        as the source of the second definition.
+
+    Returns:
+      An instance of DuplicateFlagError.
+    """
+    first_module = flag_values.find_module_defining_flag(
+        flagname, default='<unknown>')
+    if other_flag_values is None:
+      second_module = _helpers.get_calling_module()
+    else:
+      second_module = other_flag_values.find_module_defining_flag(
+          flagname, default='<unknown>')
+    flag_summary = flag_values[flagname].help
+    msg = ("The flag '%s' is defined twice. First from %s, Second from %s.  "
+           "Description from first occurrence: %s") % (
+               flagname, first_module, second_module, flag_summary)
+    return cls(msg)
+
+
+class IllegalFlagValueError(Error):
+  """Raised when the flag command line argument is illegal."""
+
+
+class UnrecognizedFlagError(Error):
+  """Raised when a flag is unrecognized.
+
+  Attributes:
+    flagname: str, the name of the unrecognized flag.
+    flagvalue: The value of the flag, empty if the flag is not defined.
+  """
+
+  def __init__(self, flagname, flagvalue='', suggestions=None):
+    self.flagname = flagname
+    self.flagvalue = flagvalue
+    if suggestions:
+      # Space before the question mark is intentional to not include it in the
+      # selection when copy-pasting the suggestion from (some) terminals.
+      tip = '. Did you mean: %s ?' % ', '.join(suggestions)
+    else:
+      tip = ''
+    super().__init__("Unknown command line flag '%s'%s" % (flagname, tip))
+
+
+class UnparsedFlagAccessError(Error):
+  """Raised when accessing the flag value from unparsed :class:`FlagValues`."""
+
+
+class ValidationError(Error):
+  """Raised when flag validator constraint is not satisfied."""
+
+
+class FlagNameConflictsWithMethodError(Error):
+  """Raised when a flag name conflicts with :class:`FlagValues` methods."""

.venv/lib/python3.13/site-packages/absl/flags/_flag.py

@@ -0,0 +1,566 @@
+# Copyright 2017 The Abseil Authors.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Contains Flag class - information about single command-line flag.
+
+Do NOT import this module directly. Import the flags package and use the
+aliases defined at the package level instead.
+"""
+
+from collections.abc import Iterable
+import copy
+import enum
+import functools
+from typing import Any, Generic, TypeVar
+from xml.dom import minidom
+
+from absl.flags import _argument_parser
+from absl.flags import _exceptions
+from absl.flags import _helpers
+
+_T = TypeVar('_T')
+_ET = TypeVar('_ET', bound=enum.Enum)
+
+
+@functools.total_ordering
+class Flag(Generic[_T]):
+  """Information about a command-line flag.
+
+  Attributes:
+    name: the name for this flag
+    default: the default value for this flag
+    default_unparsed: the unparsed default value for this flag.
+    default_as_str: default value as repr'd string, e.g., "'true'"
+      (or None)
+    value: the most recent parsed value of this flag set by :meth:`parse`
+    help: a help string or None if no help is available
+    short_name: the single letter alias for this flag (or None)
+    boolean: if 'true', this flag does not accept arguments
+    present: true if this flag was parsed from command line flags
+    parser: an :class:`~absl.flags.ArgumentParser` object
+    serializer: an ArgumentSerializer object
+    allow_override: the flag may be redefined without raising an error,
+      and newly defined flag overrides the old one.
+    allow_override_cpp: use the flag from C++ if available the flag
+      definition is replaced by the C++ flag after init
+    allow_hide_cpp: use the Python flag despite having a C++ flag with
+      the same name (ignore the C++ flag)
+    using_default_value: the flag value has not been set by user
+    allow_overwrite: the flag may be parsed more than once without
+      raising an error, the last set value will be used
+    allow_using_method_names: whether this flag can be defined even if
+      it has a name that conflicts with a FlagValues method.
+    validators: list of the flag validators.
+
+  The only public method of a ``Flag`` object is :meth:`parse`, but it is
+  typically only called by a :class:`~absl.flags.FlagValues` object.  The
+  :meth:`parse` method is a thin wrapper around the
+  :meth:`ArgumentParser.parse()<absl.flags.ArgumentParser.parse>` method.  The
+  parsed value is saved in ``.value``, and the ``.present`` attribute is
+  updated.  If this flag was already present, an Error is raised.
+
+  :meth:`parse` is also called during ``__init__`` to parse the default value
+  and initialize the ``.value`` attribute.  This enables other python modules to
+  safely use flags even if the ``__main__`` module neglects to parse the
+  command line arguments.  The ``.present`` attribute is cleared after
+  ``__init__`` parsing.  If the default value is set to ``None``, then the
+  ``__init__`` parsing step is skipped and the ``.value`` attribute is
+  initialized to None.
+
+  Note: The default value is also presented to the user in the help
+  string, so it is important that it be a legal value for this flag.
+  """
+
+  # NOTE: pytype doesn't find defaults without this.
+  default: _T | None
+  default_as_str: str | None
+  default_unparsed: _T | None | str
+
+  parser: _argument_parser.ArgumentParser[_T]
+
+  def __init__(
+      self,
+      parser: _argument_parser.ArgumentParser[_T],
+      serializer: _argument_parser.ArgumentSerializer[_T] | None,
+      name: str,
+      default: _T | None | str,
+      help_string: str | None,
+      short_name: str | None = None,
+      boolean: bool = False,
+      allow_override: bool = False,
+      allow_override_cpp: bool = False,
+      allow_hide_cpp: bool = False,
+      allow_overwrite: bool = True,
+      allow_using_method_names: bool = False,
+  ) -> None:
+    self.name = name
+
+    if not help_string:
+      help_string = '(no help available)'
+
+    self.help = help_string
+    self.short_name = short_name
+    self.boolean = boolean
+    self.present = 0
+    self.parser = parser  # type: ignore[annotation-type-mismatch]
+    self.serializer = serializer
+    self.allow_override = allow_override
+    self.allow_override_cpp = allow_override_cpp
+    self.allow_hide_cpp = allow_hide_cpp
+    self.allow_overwrite = allow_overwrite
+    self.allow_using_method_names = allow_using_method_names
+
+    self.using_default_value = True
+    self._value: _T | None = None
+    self.validators: list[Any] = []
+    if self.allow_hide_cpp and self.allow_override_cpp:
+      raise _exceptions.Error(
+          "Can't have both allow_hide_cpp (means use Python flag) and "
+          'allow_override_cpp (means use C++ flag after InitGoogle)')
+
+    self._set_default(default)
+
+  @property
+  def value(self) -> _T | None:
+    return self._value
+
+  @value.setter
+  def value(self, value: _T | None):
+    self._value = value
+
+  def __hash__(self):
+    return hash(id(self))
+
+  def __eq__(self, other):
+    return self is other
+
+  def __lt__(self, other):
+    if isinstance(other, Flag):
+      return id(self) < id(other)
+    return NotImplemented
+
+  def __bool__(self):
+    raise TypeError('A Flag instance would always be True. '
+                    'Did you mean to test the `.value` attribute?')
+
+  def __getstate__(self):
+    raise TypeError("can't pickle Flag objects")
+
+  def __copy__(self):
+    raise TypeError('%s does not support shallow copies. '
+                    'Use copy.deepcopy instead.' % type(self).__name__)
+
+  def __deepcopy__(self, memo: dict[int, Any]) -> 'Flag[_T]':
+    result = object.__new__(type(self))
+    result.__dict__ = copy.deepcopy(self.__dict__, memo)
+    return result
+
+  def _get_parsed_value_as_string(self, value: _T | None) -> str | None:
+    """Returns parsed flag value as string."""
+    if value is None:
+      return None
+    if self.serializer:
+      return repr(self.serializer.serialize(value))
+    if self.boolean:
+      if value:
+        return repr('true')
+      else:
+        return repr('false')
+    return repr(str(value))
+
+  def parse(self, argument: str | _T) -> None:
+    """Parses string and sets flag value.
+
+    Args:
+      argument: str or the correct flag value type, argument to be parsed.
+    """
+    if self.present and not self.allow_overwrite:
+      raise _exceptions.IllegalFlagValueError(
+          'flag --%s=%s: already defined as %s' % (
+              self.name, argument, self.value))
+    self.value = self._parse(argument)
+    self.present += 1
+
+  def _parse(self, argument: str | _T) -> _T | None:
+    """Internal parse function.
+
+    It returns the parsed value, and does not modify class states.
+
+    Args:
+      argument: str or the correct flag value type, argument to be parsed.
+
+    Returns:
+      The parsed value.
+    """
+    try:
+      return self.parser.parse(argument)  # type: ignore[arg-type]
+    except (TypeError, ValueError, OverflowError) as e:
+      # Recast as IllegalFlagValueError.
+      raise _exceptions.IllegalFlagValueError(
+          'flag --%s=%s: %s' % (self.name, argument, e))
+
+  def unparse(self) -> None:
+    self.value = self.default
+    self.using_default_value = True
+    self.present = 0
+
+  def serialize(self) -> str:
+    """Serializes the flag."""
+    return self._serialize(self.value)
+
+  def _serialize(self, value: _T | None) -> str:
+    """Internal serialize function."""
+    if value is None:
+      return ''
+    if self.boolean:
+      if value:
+        return '--%s' % self.name
+      else:
+        return '--no%s' % self.name
+    else:
+      if not self.serializer:
+        raise _exceptions.Error(
+            'Serializer not present for flag %s' % self.name)
+      return '--%s=%s' % (self.name, self.serializer.serialize(value))
+
+  def _set_default(self, value: _T | None | str) -> None:
+    """Changes the default value (and current value too) for this Flag."""
+    self.default_unparsed = value
+    if value is None:
+      self.default = None
+    else:
+      self.default = self._parse_from_default(value)
+    self.default_as_str = self._get_parsed_value_as_string(self.default)
+    if self.using_default_value:
+      self.value = self.default
+
+  # This is split out so that aliases can skip regular parsing of the default
+  # value.
+  def _parse_from_default(self, value: str | _T) -> _T | None:
+    return self._parse(value)
+
+  def flag_type(self) -> str:
+    """Returns a str that describes the type of the flag.
+
+    NOTE: we use strings, and not the types.*Type constants because
+    our flags can have more exotic types, e.g., 'comma separated list
+    of strings', 'whitespace separated list of strings', etc.
+    """
+    return self.parser.flag_type()
+
+  def _create_xml_dom_element(
+      self, doc: minidom.Document, module_name: str, is_key: bool = False
+  ) -> minidom.Element:
+    """Returns an XML element that contains this flag's information.
+
+    This is information that is relevant to all flags (e.g., name,
+    meaning, etc.).  If you defined a flag that has some other pieces of
+    info, then please override _ExtraXMLInfo.
+
+    Please do NOT override this method.
+
+    Args:
+      doc: minidom.Document, the DOM document it should create nodes from.
+      module_name: str,, the name of the module that defines this flag.
+      is_key: boolean, True iff this flag is key for main module.
+
+    Returns:
+      A minidom.Element instance.
+    """
+    element = doc.createElement('flag')
+    if is_key:
+      element.appendChild(_helpers.create_xml_dom_element(doc, 'key', 'yes'))
+    element.appendChild(_helpers.create_xml_dom_element(
+        doc, 'file', module_name))
+    # Adds flag features that are relevant for all flags.
+    element.appendChild(_helpers.create_xml_dom_element(doc, 'name', self.name))
+    if self.short_name:
+      element.appendChild(_helpers.create_xml_dom_element(
+          doc, 'short_name', self.short_name))
+    if self.help:
+      element.appendChild(_helpers.create_xml_dom_element(
+          doc, 'meaning', self.help))
+    # The default flag value can either be represented as a string like on the
+    # command line, or as a Python object.  We serialize this value in the
+    # latter case in order to remain consistent.
+    if self.serializer and not isinstance(self.default, str):
+      if self.default is not None:
+        default_serialized = self.serializer.serialize(self.default)
+      else:
+        default_serialized = ''
+    else:
+      default_serialized = self.default  # type: ignore[assignment]
+    element.appendChild(_helpers.create_xml_dom_element(
+        doc, 'default', default_serialized))
+    value_serialized = self._serialize_value_for_xml(self.value)
+    element.appendChild(_helpers.create_xml_dom_element(
+        doc, 'current', value_serialized))
+    element.appendChild(_helpers.create_xml_dom_element(
+        doc, 'type', self.flag_type()))
+    # Adds extra flag features this flag may have.
+    for e in self._extra_xml_dom_elements(doc):
+      element.appendChild(e)
+    return element
+
+  def _serialize_value_for_xml(self, value: _T | None) -> Any:
+    """Returns the serialized value, for use in an XML help text."""
+    return value
+
+  def _extra_xml_dom_elements(
+      self, doc: minidom.Document
+  ) -> list[minidom.Element]:
+    """Returns extra info about this flag in XML.
+
+    "Extra" means "not already included by _create_xml_dom_element above."
+
+    Args:
+      doc: minidom.Document, the DOM document it should create nodes from.
+
+    Returns:
+      A list of minidom.Element.
+    """
+    # Usually, the parser knows the extra details about the flag, so
+    # we just forward the call to it.
+    return self.parser._custom_xml_dom_elements(doc)  # pylint: disable=protected-access
+
+
+class BooleanFlag(Flag[bool]):
+  """Basic boolean flag.
+
+  Boolean flags do not take any arguments, and their value is either
+  ``True`` (1) or ``False`` (0).  The false value is specified on the command
+  line by prepending the word ``'no'`` to either the long or the short flag
+  name.
+
+  For example, if a Boolean flag was created whose long name was
+  ``'update'`` and whose short name was ``'x'``, then this flag could be
+  explicitly unset through either ``--noupdate`` or ``--nox``.
+  """
+
+  def __init__(
+      self,
+      name: str,
+      default: bool | None | str,
+      help: str | None,  # pylint: disable=redefined-builtin
+      short_name: str | None = None,
+      **args
+  ) -> None:
+    p = _argument_parser.BooleanParser()
+    super().__init__(p, None, name, default, help, short_name, True, **args)
+
+
+class EnumFlag(Flag[str]):
+  """Basic enum flag; its value can be any string from list of enum_values."""
+
+  parser: _argument_parser.EnumParser
+
+  def __init__(
+      self,
+      name: str,
+      default: str | None,
+      help: str | None,  # pylint: disable=redefined-builtin
+      enum_values: Iterable[str],
+      short_name: str | None = None,
+      case_sensitive: bool = True,
+      **args
+  ):
+    p = _argument_parser.EnumParser(enum_values, case_sensitive)
+    g: _argument_parser.ArgumentSerializer[str]
+    g = _argument_parser.ArgumentSerializer()
+    super().__init__(p, g, name, default, help, short_name, **args)
+    self.parser = p
+    self.help = '<%s>: %s' % ('|'.join(p.enum_values), self.help)
+
+  def _extra_xml_dom_elements(
+      self, doc: minidom.Document
+  ) -> list[minidom.Element]:
+    elements = []
+    for enum_value in self.parser.enum_values:
+      elements.append(_helpers.create_xml_dom_element(
+          doc, 'enum_value', enum_value))
+    return elements
+
+
+class EnumClassFlag(Flag[_ET]):
+  """Basic enum flag; its value is an enum class's member."""
+
+  parser: _argument_parser.EnumClassParser
+
+  def __init__(
+      self,
+      name: str,
+      default: _ET | None | str,
+      help: str | None,  # pylint: disable=redefined-builtin
+      enum_class: type[_ET],
+      short_name: str | None = None,
+      case_sensitive: bool = False,
+      **args
+  ):
+    p = _argument_parser.EnumClassParser(
+        enum_class, case_sensitive=case_sensitive
+    )
+    g: _argument_parser.EnumClassSerializer[_ET]
+    g = _argument_parser.EnumClassSerializer(lowercase=not case_sensitive)
+    super().__init__(p, g, name, default, help, short_name, **args)
+    self.parser = p
+    self.help = '<%s>: %s' % ('|'.join(p.member_names), self.help)
+
+  def _extra_xml_dom_elements(
+      self, doc: minidom.Document
+  ) -> list[minidom.Element]:
+    elements = []
+    for enum_value in self.parser.enum_class.__members__.keys():
+      elements.append(_helpers.create_xml_dom_element(
+          doc, 'enum_value', enum_value))
+    return elements
+
+
+class MultiFlag(Generic[_T], Flag[list[_T]]):
+  """A flag that can appear multiple time on the command-line.
+
+  The value of such a flag is a list that contains the individual values
+  from all the appearances of that flag on the command-line.
+
+  See the __doc__ for Flag for most behavior of this class.  Only
+  differences in behavior are described here:
+
+    * The default value may be either a single value or an iterable of values.
+      A single value is transformed into a single-item list of that value.
+
+    * The value of the flag is always a list, even if the option was
+      only supplied once, and even if the default value is a single
+      value
+  """
+
+  def __init__(self, *args, **kwargs):
+    super().__init__(*args, **kwargs)
+    self.help += ';\n    repeat this option to specify a list of values'
+
+  def parse(self, arguments: str | _T | Iterable[_T]):  # pylint: disable=arguments-renamed
+    """Parses one or more arguments with the installed parser.
+
+    Args:
+      arguments: a single argument or a list of arguments (typically a
+        list of default values); a single argument is converted
+        internally into a list containing one item.
+    """
+    new_values = self._parse(arguments)
+    if self.present:
+      assert self.value is not None
+      self.value.extend(new_values)
+    else:
+      self.value = new_values
+    self.present += len(new_values)
+
+  def _parse(self, arguments: str | _T | Iterable[_T]) -> list[_T]:  # pylint: disable=arguments-renamed
+    arguments_list: list[str | _T]
+
+    if isinstance(arguments, str):
+      arguments_list = [arguments]
+
+    elif isinstance(arguments, Iterable):
+      arguments_list = list(arguments)
+
+    else:
+      # Default value may be a list of values.  Most other arguments
+      # will not be, so convert them into a single-item list to make
+      # processing simpler below.
+      arguments_list = [arguments]
+
+    return [super(MultiFlag, self)._parse(item) for item in arguments_list]  # type: ignore
+
+  def _serialize(self, value: list[_T] | None) -> str:
+    """See base class."""
+    if not self.serializer:
+      raise _exceptions.Error(
+          'Serializer not present for flag %s' % self.name)
+    if value is None:
+      return ''
+
+    serialized_items = [
+        super(MultiFlag, self)._serialize(value_item)  # type: ignore[arg-type]
+        for value_item in value
+    ]
+
+    return '\n'.join(serialized_items)
+
+  def flag_type(self):
+    """See base class."""
+    return 'multi ' + self.parser.flag_type()
+
+  def _extra_xml_dom_elements(
+      self, doc: minidom.Document
+  ) -> list[minidom.Element]:
+    elements = []
+    if hasattr(self.parser, 'enum_values'):
+      for enum_value in self.parser.enum_values:  # pytype: disable=attribute-error
+        elements.append(_helpers.create_xml_dom_element(
+            doc, 'enum_value', enum_value))
+    return elements
+
+
+class MultiEnumClassFlag(MultiFlag[_ET]):  # pytype: disable=not-indexable
+  """A multi_enum_class flag.
+
+  See the __doc__ for MultiFlag for most behaviors of this class.  In addition,
+  this class knows how to handle enum.Enum instances as values for this flag
+  type.
+  """
+
+  parser: _argument_parser.EnumClassParser[_ET]  # type: ignore[assignment]
+
+  def __init__(
+      self,
+      name: str,
+      default: None | Iterable[_ET] | _ET | Iterable[str] | str,
+      help_string: str,
+      enum_class: type[_ET],
+      case_sensitive: bool = False,
+      **args
+  ):
+    p = _argument_parser.EnumClassParser(
+        enum_class, case_sensitive=case_sensitive)
+    g: _argument_parser.EnumClassListSerializer
+    g = _argument_parser.EnumClassListSerializer(
+        list_sep=',', lowercase=not case_sensitive)
+    super().__init__(p, g, name, default, help_string, **args)
+    # NOTE: parser should be typed EnumClassParser[_ET] but the constructor
+    # restricts the available interface to ArgumentParser[str].
+    self.parser = p
+    # NOTE: serializer should be non-Optional but this isn't inferred.
+    self.serializer = g
+    self.help = (
+        '<%s>: %s;\n    repeat this option to specify a list of values' %
+        ('|'.join(p.member_names), help_string or '(no help available)'))
+
+  def _extra_xml_dom_elements(
+      self, doc: minidom.Document
+  ) -> list[minidom.Element]:
+    elements = []
+    for enum_value in self.parser.enum_class.__members__.keys():  # pytype: disable=attribute-error
+      elements.append(_helpers.create_xml_dom_element(
+          doc, 'enum_value', enum_value))
+    return elements
+
+  def _serialize_value_for_xml(self, value):
+    """See base class."""
+    if value is not None:
+      if not self.serializer:
+        raise _exceptions.Error(
+            'Serializer not present for flag %s' % self.name
+        )
+      value_serialized = self.serializer.serialize(value)
+    else:
+      value_serialized = ''
+    return value_serialized

.venv/lib/python3.13/site-packages/absl/flags/_flagvalues.py

@@ -0,0 +1,1552 @@
+# Copyright 2017 The Abseil Authors.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+"""Defines the FlagValues class - registry of 'Flag' objects.
+
+Do NOT import this module directly. Import the flags package and use the
+aliases defined at the package level instead.
+"""
+
+from collections.abc import Callable, Iterable, Iterator, Sequence
+import copy
+from importlib import abc
+import logging
+import os
+import sys
+from typing import Any, Generic, TextIO, TypeVar
+from xml.dom import minidom
+
+from absl.flags import _exceptions
+from absl.flags import _flag
+from absl.flags import _helpers
+from absl.flags import _validators_classes
+from absl.flags._flag import Flag
+
+# Add flagvalues module to disclaimed module ids.
+_helpers.disclaim_module_ids.add(id(sys.modules[__name__]))
+
+_T = TypeVar('_T')
+_T_co = TypeVar('_T_co', covariant=True)  # pytype: disable=not-supported-yet
+
+
+class ReloadDetector(abc.MetaPathFinder):
+  """Helper class for detecting reloads."""
+
+  def __init__(self):
+    self.reloading_modules = set()
+
+  def find_spec(self, fullname, path, target=None):
+    if fullname in sys.modules:  # Indicates a reload.
+      self.reloading_modules.add(fullname)
+    return None
+
+
+reload_detector = ReloadDetector()
+
+# Register the hook by inserting it right before the last path finder.
+# This should play nicely with lazy imports.
+sys.meta_path.insert(-1, reload_detector)
+
+
+class FlagValues:
+  """Registry of :class:`~absl.flags.Flag` objects.
+
+  A :class:`FlagValues` can then scan command line arguments, passing flag
+  arguments through to the 'Flag' objects that it owns.  It also
+  provides easy access to the flag values.  Typically only one
+  :class:`FlagValues` object is needed by an application:
+  :const:`FLAGS`.
+
+  This class is heavily overloaded:
+
+  :class:`Flag` objects are registered via ``__setitem__``::
+
+       FLAGS['longname'] = x   # register a new flag
+
+  The ``.value`` attribute of the registered :class:`~absl.flags.Flag` objects
+  can be accessed as attributes of this :class:`FlagValues` object, through
+  ``__getattr__``.  Both the long and short name of the original
+  :class:`~absl.flags.Flag` objects can be used to access its value::
+
+       FLAGS.longname  # parsed flag value
+       FLAGS.x  # parsed flag value (short name)
+
+  Command line arguments are scanned and passed to the registered
+  :class:`~absl.flags.Flag` objects through the ``__call__`` method.  Unparsed
+  arguments, including ``argv[0]`` (e.g. the program name) are returned::
+
+       argv = FLAGS(sys.argv)  # scan command line arguments
+
+  The original registered :class:`~absl.flags.Flag` objects can be retrieved
+  through the use of the dictionary-like operator, ``__getitem__``::
+
+       x = FLAGS['longname']   # access the registered Flag object
+
+  The ``str()`` operator of a :class:`absl.flags.FlagValues` object provides
+  help for all of the registered :class:`~absl.flags.Flag` objects.
+  """
+
+  _HAS_DYNAMIC_ATTRIBUTES = True
+
+  # A note on collections.abc.Mapping:
+  # FlagValues defines __getitem__, __iter__, and __len__. It makes perfect
+  # sense to let it be a collections.abc.Mapping class. However, we are not
+  # able to do so. The mixin methods, e.g. keys, values, are not uncommon flag
+  # names. Those flag values would not be accessible via the FLAGS.xxx form.
+
+  __dict__: dict[str, Any]
+
+  def __init__(self):
+    # Since everything in this class is so heavily overloaded, the only
+    # way of defining and using fields is to access __dict__ directly.
+
+    # Dictionary: flag name (string) -> Flag object.
+    self.__dict__['__flags'] = {}
+
+    # Set: name of hidden flag (string).
+    # Holds flags that should not be directly accessible from Python.
+    self.__dict__['__hiddenflags'] = set()
+
+    # Dictionary: module name (string) -> list of Flag objects that are defined
+    # by that module.
+    self.__dict__['__flags_by_module'] = {}
+    # Dictionary: module id (int) -> list of Flag objects that are defined by
+    # that module.
+    self.__dict__['__flags_by_module_id'] = {}
+    # Dictionary: module name (string) -> list of Flag objects that are
+    # key for that module.
+    self.__dict__['__key_flags_by_module'] = {}
+
+    # Bool: True if flags were parsed.
+    self.__dict__['__flags_parsed'] = False
+
+    # Bool: True if unparse_flags() was called.
+    self.__dict__['__unparse_flags_called'] = False
+
+    # None or Method(name, value) to call from __setattr__ for an unknown flag.
+    self.__dict__['__set_unknown'] = None
+
+    # A set of banned flag names. This is to prevent users from accidentally
+    # defining a flag that has the same name as a method on this class.
+    # Users can still allow defining the flag by passing
+    # allow_using_method_names=True in DEFINE_xxx functions.
+    self.__dict__['__banned_flag_names'] = frozenset(dir(FlagValues))
+
+    # Bool: Whether to use GNU style scanning.
+    self.__dict__['__use_gnu_getopt'] = True
+
+    # Bool: Whether use_gnu_getopt has been explicitly set by the user.
+    self.__dict__['__use_gnu_getopt_explicitly_set'] = False
+
+    # Function: Takes a flag name as parameter, returns a tuple
+    # (is_retired, type_is_bool).
+    self.__dict__['__is_retired_flag_func'] = None
+
+  def set_gnu_getopt(self, gnu_getopt: bool = True) -> None:
+    """Sets whether or not to use GNU style scanning.
+
+    GNU style allows mixing of flag and non-flag arguments. See
+    http://docs.python.org/library/getopt.html#getopt.gnu_getopt
+
+    Args:
+      gnu_getopt: bool, whether or not to use GNU style scanning.
+    """
+    self.__dict__['__use_gnu_getopt'] = gnu_getopt
+    self.__dict__['__use_gnu_getopt_explicitly_set'] = True
+
+  def is_gnu_getopt(self) -> bool:
+    return self.__dict__['__use_gnu_getopt']
+
+  def _flags(self) -> dict[str, Flag]:
+    return self.__dict__['__flags']
+
+  def flags_by_module_dict(self) -> dict[str, list[Flag]]:
+    """Returns the dictionary of module_name -> list of defined flags.
+
+    Returns:
+      A dictionary.  Its keys are module names (strings).  Its values
+      are lists of Flag objects.
+    """
+    return self.__dict__['__flags_by_module']
+
+  def flags_by_module_id_dict(self) -> dict[int, list[Flag]]:
+    """Returns the dictionary of module_id -> list of defined flags.
+
+    Returns:
+      A dictionary.  Its keys are module IDs (ints).  Its values
+      are lists of Flag objects.
+    """
+    return self.__dict__['__flags_by_module_id']
+
+  def key_flags_by_module_dict(self) -> dict[str, list[Flag]]:
+    """Returns the dictionary of module_name -> list of key flags.
+
+    Returns:
+      A dictionary.  Its keys are module names (strings).  Its values
+      are lists of Flag objects.
+    """
+    return self.__dict__['__key_flags_by_module']
+
+  def register_flag_by_module(self, module_name: str, flag: Flag) -> None:
+    """Records the module that defines a specific flag.
+
+    We keep track of which flag is defined by which module so that we
+    can later sort the flags by module.
+
+    Args:
+      module_name: str, the name of a Python module.
+      flag: Flag, the Flag instance that is key to the module.
+    """
+    flags_by_module = self.flags_by_module_dict()
+    flags_by_module.setdefault(module_name, []).append(flag)
+
+  def register_flag_by_module_id(self, module_id: int, flag: Flag) -> None:
+    """Records the module that defines a specific flag.
+
+    Args:
+      module_id: int, the ID of the Python module.
+      flag: Flag, the Flag instance that is key to the module.
+    """
+    flags_by_module_id = self.flags_by_module_id_dict()
+    flags_by_module_id.setdefault(module_id, []).append(flag)
+
+  def register_key_flag_for_module(self, module_name: str, flag: Flag) -> None:
+    """Specifies that a flag is a key flag for a module.
+
+    Args:
+      module_name: str, the name of a Python module.
+      flag: Flag, the Flag instance that is key to the module.
+    """
+    key_flags_by_module = self.key_flags_by_module_dict()
+    # The list of key flags for the module named module_name.
+    key_flags = key_flags_by_module.setdefault(module_name, [])
+    # Add flag, but avoid duplicates.
+    if flag not in key_flags:
+      key_flags.append(flag)
+
+  def _flag_is_registered(self, flag_obj: Flag) -> bool:
+    """Checks whether a Flag object is registered under long name or short name.
+
+    Args:
+      flag_obj: Flag, the Flag instance to check for.
+
+    Returns:
+      bool, True iff flag_obj is registered under long name or short name.
+    """
+    flag_dict = self._flags()
+    # Check whether flag_obj is registered under its long name.
+    name = flag_obj.name
+    if name in flag_dict and flag_dict[name] == flag_obj:
+      return True
+    # Check whether flag_obj is registered under its short name.
+    short_name = flag_obj.short_name
+    if (
+        short_name is not None
+        and short_name in flag_dict
+        and flag_dict[short_name] == flag_obj
+    ):
+      return True
+    return False
+
+  def _cleanup_unregistered_flag_from_module_dicts(
+      self, flag_obj: Flag
+  ) -> None:
+    """Cleans up unregistered flags from all module -> [flags] dictionaries.
+
+    If flag_obj is registered under either its long name or short name, it
+    won't be removed from the dictionaries.
+
+    Args:
+      flag_obj: Flag, the Flag instance to clean up for.
+    """
+    if self._flag_is_registered(flag_obj):
+      return
+    # Materialize dict values to list to avoid concurrent modification.
+    for flags_in_module in [
+        *self.flags_by_module_dict().values(),
+        *self.flags_by_module_id_dict().values(),
+        *self.key_flags_by_module_dict().values(),
+    ]:
+      # While (as opposed to if) takes care of multiple occurrences of a
+      # flag in the list for the same module.
+      while flag_obj in flags_in_module:
+        flags_in_module.remove(flag_obj)
+
+  def get_flags_for_module(self, module: str | Any) -> list[Flag]:
+    """Returns the list of flags defined by a module.
+
+    Args:
+      module: module|str, the module to get flags from.
+
+    Returns:
+      [Flag], a new list of Flag instances.  Caller may update this list as
+      desired: none of those changes will affect the internals of this
+      FlagValue instance.
+    """
+    if not isinstance(module, str):
+      module = module.__name__
+    if module == '__main__':
+      module = sys.argv[0]
+
+    return list(self.flags_by_module_dict().get(module, []))
+
+  def get_key_flags_for_module(self, module: str | Any) -> list[Flag]:
+    """Returns the list of key flags for a module.
+
+    Args:
+      module: module|str, the module to get key flags from.
+
+    Returns:
+      [Flag], a new list of Flag instances.  Caller may update this list as
+      desired: none of those changes will affect the internals of this
+      FlagValue instance.
+    """
+    if not isinstance(module, str):
+      module = module.__name__
+    if module == '__main__':
+      module = sys.argv[0]
+
+    # Any flag is a key flag for the module that defined it.  NOTE:
+    # key_flags is a fresh list: we can update it without affecting the
+    # internals of this FlagValues object.
+    key_flags = self.get_flags_for_module(module)
+
+    # Take into account flags explicitly declared as key for a module.
+    for flag in self.key_flags_by_module_dict().get(module, []):
+      if flag not in key_flags:
+        key_flags.append(flag)
+    return key_flags
+
+  # TODO(yileiyang): Restrict default to Optional[str].
+  def find_module_defining_flag(
+      self, flagname: str, default: _T | None = None
+  ) -> str | _T | None:
+    """Return the name of the module defining this flag, or default.
+
+    Args:
+      flagname: str, name of the flag to lookup.
+      default: Value to return if flagname is not defined. Defaults to None.
+
+    Returns:
+      The name of the module which registered the flag with this name.
+      If no such module exists (i.e. no flag with this name exists),
+      we return default.
+    """
+    registered_flag = self._flags().get(flagname)
+    if registered_flag is None:
+      return default
+    for module, flags in self.flags_by_module_dict().items():
+      for flag in flags:
+        # It must compare the flag with the one in _flags. This is because a
+        # flag might be overridden only for its long name (or short name),
+        # and only its short name (or long name) is considered registered.
+        if (
+            flag.name == registered_flag.name
+            and flag.short_name == registered_flag.short_name
+        ):
+          return module
+    return default
+
+  # TODO(yileiyang): Restrict default to Optional[str].
+  def find_module_id_defining_flag(
+      self, flagname: str, default: _T | None = None
+  ) -> int | _T | None:
+    """Return the ID of the module defining this flag, or default.
+
+    Args:
+      flagname: str, name of the flag to lookup.
+      default: Value to return if flagname is not defined. Defaults to None.
+
+    Returns:
+      The ID of the module which registered the flag with this name.
+      If no such module exists (i.e. no flag with this name exists),
+      we return default.
+    """
+    registered_flag = self._flags().get(flagname)
+    if registered_flag is None:
+      return default
+    for module_id, flags in self.flags_by_module_id_dict().items():
+      for flag in flags:
+        # It must compare the flag with the one in _flags. This is because a
+        # flag might be overridden only for its long name (or short name),
+        # and only its short name (or long name) is considered registered.
+        if (
+            flag.name == registered_flag.name
+            and flag.short_name == registered_flag.short_name
+        ):
+          return module_id
+    return default
+
+  def _register_unknown_flag_setter(
+      self, setter: Callable[[str, Any], None]
+  ) -> None:
+    """Allow set default values for undefined flags.
+
+    Args:
+      setter: Method(name, value) to call to __setattr__ an unknown flag. Must
+        raise NameError or ValueError for invalid name/value.
+    """
+    self.__dict__['__set_unknown'] = setter
+
+  def _set_unknown_flag(self, name: str, value: _T) -> _T:
+    """Returns value if setting flag |name| to |value| returned True.
+
+    Args:
+      name: str, name of the flag to set.
+      value: Value to set.
+
+    Returns:
+      Flag value on successful call.
+
+    Raises:
+      UnrecognizedFlagError
+      IllegalFlagValueError
+    """
+    setter = self.__dict__['__set_unknown']
+    if setter:
+      try:
+        setter(name, value)
+        return value
+      except (TypeError, ValueError):  # Flag value is not valid.
+        raise _exceptions.IllegalFlagValueError(
+            f'"{value}" is not valid for --{name}'
+        )
+      except NameError:  # Flag name is not valid.
+        pass
+    raise _exceptions.UnrecognizedFlagError(name, value)
+
+  def append_flag_values(self, flag_values: 'FlagValues') -> None:
+    """Appends flags registered in another FlagValues instance.
+
+    Args:
+      flag_values: FlagValues, the FlagValues instance from which to copy flags.
+    """
+    for flag_name, flag in flag_values._flags().items():  # pylint: disable=protected-access
+      # Each flags with short_name appears here twice (once under its
+      # normal name, and again with its short name).  To prevent
+      # problems (DuplicateFlagError) with double flag registration, we
+      # perform a check to make sure that the entry we're looking at is
+      # for its normal name.
+      if flag_name == flag.name:
+        try:
+          self[flag_name] = flag
+        except _exceptions.DuplicateFlagError:
+          raise _exceptions.DuplicateFlagError.from_flag(
+              flag_name, self, other_flag_values=flag_values
+          )
+
+  def remove_flag_values(
+      self, flag_values: 'FlagValues | Iterable[str]'
+  ) -> None:
+    """Remove flags that were previously appended from another FlagValues.
+
+    Args:
+      flag_values: FlagValues, the FlagValues instance containing flags to
+        remove.
+    """
+    for flag_name in flag_values:
+      self.__delattr__(flag_name)
+
+  def __setitem__(self, name: str, flag: Flag) -> None:
+    """Registers a new flag variable."""
+    fl = self._flags()
+    if not isinstance(flag, _flag.Flag):
+      raise _exceptions.IllegalFlagValueError(
+          f'Expect Flag instances, found type {type(flag)}. '
+          "Maybe you didn't mean to use FlagValue.__setitem__?"
+      )
+    if not isinstance(name, str):
+      raise _exceptions.Error('Flag name must be a string')
+    if not name:
+      raise _exceptions.Error('Flag name cannot be empty')
+    if ' ' in name:
+      raise _exceptions.Error('Flag name cannot contain a space')
+    self._check_method_name_conflicts(name, flag)
+    if name in fl and not flag.allow_override and not fl[name].allow_override:
+      module, module_name = _helpers.get_calling_module_object_and_name()
+      if self.find_module_defining_flag(name) == module_name and (
+          id(module) != self.find_module_id_defining_flag(name)
+          or module_name in reload_detector.reloading_modules
+      ):
+        # If the flag has already been defined by a module with the same name,
+        # but a different ID, we can stop here because it indicates that the
+        # module is simply being imported a subsequent time.
+        # In case the module is being reloaded (using `importlib.reload`), it'll
+        # have the same ID, so we detect it using reload_detector.
+        return
+      raise _exceptions.DuplicateFlagError.from_flag(name, self)
+    # If a new flag overrides an old one, we need to cleanup the old flag's
+    # modules if it's not registered.
+    flags_to_cleanup = set()
+    short_name: str | None = flag.short_name
+    if short_name is not None:
+      if (
+          short_name in fl
+          and not flag.allow_override
+          and not fl[short_name].allow_override
+      ):
+        raise _exceptions.DuplicateFlagError.from_flag(short_name, self)
+      if short_name in fl and fl[short_name] != flag:
+        flags_to_cleanup.add(fl[short_name])
+      fl[short_name] = flag
+    if (
+        name not in fl  # new flag
+        or fl[name].using_default_value
+        or not flag.using_default_value
+    ):
+      if name in fl and fl[name] != flag:
+        flags_to_cleanup.add(fl[name])
+      fl[name] = flag
+    for f in flags_to_cleanup:
+      self._cleanup_unregistered_flag_from_module_dicts(f)
+
+  def __dir__(self) -> list[str]:
+    """Returns list of names of all defined flags.
+
+    Useful for TAB-completion in ipython.
+
+    Returns:
+      [str], a list of names of all defined flags.
+    """
+    return sorted(self._flags())
+
+  def __getitem__(self, name: str) -> Flag:
+    """Returns the Flag object for the flag --name."""
+    return self._flags()[name]
+
+  def _hide_flag(self, name):
+    """Marks the flag --name as hidden."""
+    self.__dict__['__hiddenflags'].add(name)
+
+  def __getattr__(self, name: str) -> Any:
+    """Retrieves the 'value' attribute of the flag --name."""
+    flag_entry = self._flags().get(name)
+    if flag_entry is None:
+      raise AttributeError(name)
+    if name in self.__dict__['__hiddenflags']:
+      raise AttributeError(name)
+
+    if self.__dict__['__flags_parsed'] or flag_entry.present:
+      return flag_entry.value
+    else:
+      raise _exceptions.UnparsedFlagAccessError(
+          'Trying to access flag --%s before flags were parsed.' % name
+      )
+
+  def __setattr__(self, name: str, value: _T) -> _T:
+    """Sets the 'value' attribute of the flag --name."""
+    self._set_attributes(**{name: value})
+    return value
+
+  def _set_attributes(self, **attributes: Any) -> None:
+    """Sets multiple flag values together, triggers validators afterwards."""
+    fl = self._flags()
+    known_flag_vals = {}
+    known_flag_used_defaults = {}
+    try:
+      for name, value in attributes.items():
+        if name in self.__dict__['__hiddenflags']:
+          raise AttributeError(name)
+        flag_entry = fl.get(name)
+        if flag_entry is not None:
+          orig = flag_entry.value
+          flag_entry.value = value
+          known_flag_vals[name] = orig
+        else:
+          self._set_unknown_flag(name, value)
+      for name in known_flag_vals:
+        self._assert_validators(fl[name].validators)
+        known_flag_used_defaults[name] = fl[name].using_default_value
+        fl[name].using_default_value = False
+    except:
+      for name, orig in known_flag_vals.items():
+        fl[name].value = orig
+      for name, orig in known_flag_used_defaults.items():
+        fl[name].using_default_value = orig
+      # NOTE: We do not attempt to undo unknown flag side effects because we
+      # cannot reliably undo the user-configured behavior.
+      raise
+
+  def validate_all_flags(self) -> None:
+    """Verifies whether all flags pass validation.
+
+    Raises:
+      AttributeError: Raised if validators work with a non-existing flag.
+      IllegalFlagValueError: Raised if validation fails for at least one
+          validator.
+    """
+    all_validators = set()
+    for flag in self._flags().values():
+      all_validators.update(flag.validators)
+    self._assert_validators(all_validators)
+
+  def _assert_validators(
+      self, validators: Iterable[_validators_classes.Validator]
+  ) -> None:
+    """Asserts if all validators in the list are satisfied.
+
+    It asserts validators in the order they were created.
+
+    Args:
+      validators: Iterable(validators.Validator), validators to be verified.
+
+    Raises:
+      AttributeError: Raised if validators work with a non-existing flag.
+      IllegalFlagValueError: Raised if validation fails for at least one
+          validator.
+    """
+    messages = []
+    bad_flags: set[str] = set()
+    for validator in sorted(
+        validators, key=lambda validator: validator.insertion_index
+    ):
+      try:
+        if isinstance(validator, _validators_classes.SingleFlagValidator):
+          if validator.flag_name in bad_flags:
+            continue
+        elif isinstance(validator, _validators_classes.MultiFlagsValidator):
+          if bad_flags & set(validator.flag_names):
+            continue
+        validator.verify(self)
+      except _exceptions.ValidationError as e:
+        if isinstance(validator, _validators_classes.SingleFlagValidator):
+          bad_flags.add(validator.flag_name)
+        elif isinstance(validator, _validators_classes.MultiFlagsValidator):
+          bad_flags.update(set(validator.flag_names))
+        message = validator.print_flags_with_values(self)
+        messages.append('%s: %s' % (message, str(e)))
+    if messages:
+      raise _exceptions.IllegalFlagValueError('\n'.join(messages))
+
+  def __delattr__(self, flag_name: str) -> None:
+    """Deletes a previously-defined flag from a flag object.
+
+    This method makes sure we can delete a flag by using
+
+      del FLAGS.<flag_name>
+
+    E.g.,
+
+      flags.DEFINE_integer('foo', 1, 'Integer flag.')
+      del flags.FLAGS.foo
+
+    If a flag is also registered by its the other name (long name or short
+    name), the other name won't be deleted.
+
+    Args:
+      flag_name: str, the name of the flag to be deleted.
+
+    Raises:
+      AttributeError: Raised when there is no registered flag named flag_name.
+    """
+    fl = self._flags()
+    flag_entry = fl.get(flag_name)
+    if flag_entry is None:
+      raise AttributeError(flag_name)
+    del fl[flag_name]
+
+    self._cleanup_unregistered_flag_from_module_dicts(flag_entry)
+
+  def set_default(self, name: str, value: Any) -> None:
+    """Changes the default value of the named flag object.
+
+    The flag's current value is also updated if the flag is currently using
+    the default value, i.e. not specified in the command line, and not set
+    by FLAGS.name = value.
+
+    Args:
+      name: str, the name of the flag to modify.
+      value: The new default value.
+
+    Raises:
+      UnrecognizedFlagError: Raised when there is no registered flag named name.
+      IllegalFlagValueError: Raised when value is not valid.
+    """
+    fl = self._flags()
+    flag_entry = fl.get(name)
+    if flag_entry is None:
+      self._set_unknown_flag(name, value)
+      return
+    flag_entry._set_default(value)  # pylint: disable=protected-access
+    self._assert_validators(flag_entry.validators)
+
+  def __contains__(self, name: str) -> bool:
+    """Returns True if name is a value (flag) in the dict."""
+    return name in self._flags()
+
+  def __len__(self) -> int:
+    return len(self.__dict__['__flags'])
+
+  def __iter__(self) -> Iterator[str]:
+    return iter(self._flags())
+
+  def __call__(
+      self, argv: Sequence[str], known_only: bool = False
+  ) -> list[str]:
+    """Parses flags from argv; stores parsed flags into this FlagValues object.
+
+    All unparsed arguments are returned.
+
+    Args:
+       argv: a tuple/list of strings.
+       known_only: bool, if True, parse and remove known flags; return the rest
+         untouched. Unknown flags specified by --undefok are not returned.
+
+    Returns:
+       The list of arguments not parsed as options, including argv[0].
+
+    Raises:
+       Error: Raised on any parsing error.
+       TypeError: Raised on passing wrong type of arguments.
+       ValueError: Raised on flag value parsing error.
+    """
+    if isinstance(argv, (str, bytes)):
+      raise TypeError(
+          'argv should be a tuple/list of strings, not bytes or string.'
+      )
+    if not argv:
+      raise ValueError(
+          'argv cannot be an empty list, and must contain the program name as '
+          'the first element.'
+      )
+
+    # This pre parses the argv list for --flagfile=<> options.
+    program_name = argv[0]
+    args = self.read_flags_from_files(argv[1:], force_gnu=False)
+
+    # Parse the arguments.
+    unknown_flags, unparsed_args = self._parse_args(args, known_only)
+
+    # Handle unknown flags by raising UnrecognizedFlagError.
+    # Note some users depend on us raising this particular error.
+    for name, value in unknown_flags:
+      suggestions = _helpers.get_flag_suggestions(name, list(self))
+      raise _exceptions.UnrecognizedFlagError(
+          name, value, suggestions=suggestions
+      )
+
+    self.mark_as_parsed()
+    self.validate_all_flags()
+    return [program_name] + unparsed_args
+
+  def __getstate__(self) -> Any:
+    raise TypeError("can't pickle FlagValues")
+
+  def __copy__(self) -> Any:
+    raise TypeError(
+        'FlagValues does not support shallow copies. '
+        'Use absl.testing.flagsaver or copy.deepcopy instead.'
+    )
+
+  def __deepcopy__(self, memo) -> Any:
+    result = object.__new__(type(self))
+    result.__dict__.update(copy.deepcopy(self.__dict__, memo))
+    return result
+
+  def _set_is_retired_flag_func(self, is_retired_flag_func):
+    """Sets a function for checking retired flags.
+
+    Do not use it. This is a private absl API used to check retired flags
+    registered by the absl C++ flags library.
+
+    Args:
+      is_retired_flag_func: Callable(str) -> (bool, bool), a function takes flag
+        name as parameter, returns a tuple (is_retired, type_is_bool).
+    """
+    self.__dict__['__is_retired_flag_func'] = is_retired_flag_func
+
+  def _parse_args(
+      self, args: list[str], known_only: bool
+  ) -> tuple[list[tuple[str, Any]], list[str]]:
+    """Helper function to do the main argument parsing.
+
+    This function goes through args and does the bulk of the flag parsing.
+    It will find the corresponding flag in our flag dictionary, and call its
+    .parse() method on the flag value.
+
+    Args:
+      args: [str], a list of strings with the arguments to parse.
+      known_only: bool, if True, parse and remove known flags; return the rest
+        untouched. Unknown flags specified by --undefok are not returned.
+
+    Returns:
+      A tuple with the following:
+          unknown_flags: List of (flag name, arg) for flags we don't know about.
+          unparsed_args: List of arguments we did not parse.
+
+    Raises:
+       Error: Raised on any parsing error.
+       ValueError: Raised on flag value parsing error.
+    """
+    unparsed_names_and_args: list[tuple[str | None, str]] = []
+    undefok: set[str] = set()
+    retired_flag_func = self.__dict__['__is_retired_flag_func']
+
+    flag_dict = self._flags()
+    args_it = iter(args)
+    del args
+    for arg in args_it:
+      value = None
+
+      def get_value() -> str:
+        try:
+          return next(args_it) if value is None else value  # pylint: disable=cell-var-from-loop
+        except StopIteration:
+          raise _exceptions.Error('Missing value for flag ' + arg) from None  # pylint: disable=cell-var-from-loop
+
+      if not arg.startswith('-'):
+        # A non-argument: default is break, GNU is skip.
+        unparsed_names_and_args.append((None, arg))
+        if self.is_gnu_getopt():
+          continue
+        else:
+          break
+
+      if arg == '--':
+        if known_only:
+          unparsed_names_and_args.append((None, arg))
+        break
+
+      # At this point, arg must start with '-'.
+      if arg.startswith('--'):
+        arg_without_dashes = arg[2:]
+      else:
+        arg_without_dashes = arg[1:]
+
+      if '=' in arg_without_dashes:
+        name, value = arg_without_dashes.split('=', 1)
+      else:
+        name, value = arg_without_dashes, None
+
+      if not name:
+        # The argument is all dashes (including one dash).
+        unparsed_names_and_args.append((None, arg))
+        if self.is_gnu_getopt():
+          continue
+        else:
+          break
+
+      # --undefok is a special case.
+      if name == 'undefok':
+        value = get_value()
+        undefok.update(v.strip() for v in value.split(','))
+        undefok.update('no' + v.strip() for v in value.split(','))
+        continue
+
+      flag = flag_dict.get(name)
+      if flag is not None:
+        if flag.boolean and value is None:
+          value = 'true'
+        else:
+          value = get_value()
+      elif name.startswith('no') and len(name) > 2:
+        # Boolean flags can take the form of --noflag, with no value.
+        noflag = flag_dict.get(name[2:])
+        if noflag is not None and noflag.boolean:
+          if value is not None:
+            raise ValueError(arg + ' does not take an argument')
+          flag = noflag
+          value = 'false'
+
+      if retired_flag_func and flag is None:
+        is_retired, is_bool = retired_flag_func(name)
+
+        # If we didn't recognize that flag, but it starts with
+        # "no" then maybe it was a boolean flag specified in the
+        # --nofoo form.
+        if not is_retired and name.startswith('no'):
+          is_retired, is_bool = retired_flag_func(name[2:])
+          is_retired = is_retired and is_bool
+
+        if is_retired:
+          if not is_bool and value is None:
+            # This happens when a non-bool retired flag is specified
+            # in format of "--flag value".
+            get_value()
+          logging.error(
+              'Flag "%s" is retired and should no longer be specified. See '
+              'https://abseil.io/tips/90.',
+              name,
+          )
+          continue
+
+      if flag is not None:
+        # LINT.IfChange
+        flag.parse(value)
+        flag.using_default_value = False
+        # LINT.ThenChange(../testing/flagsaver.py:flag_override_parsing)
+      else:
+        unparsed_names_and_args.append((name, arg))
+
+    unknown_flags = []
+    unparsed_args = []
+    for arg_name, arg in unparsed_names_and_args:
+      if arg_name is None:
+        # Positional arguments.
+        unparsed_args.append(arg)
+      elif arg_name in undefok:
+        # Remove undefok flags.
+        continue
+      else:
+        # This is an unknown flag.
+        if known_only:
+          unparsed_args.append(arg)
+        else:
+          unknown_flags.append((arg_name, arg))
+
+    unparsed_args.extend(list(args_it))
+    return unknown_flags, unparsed_args
+
+  def is_parsed(self) -> bool:
+    """Returns whether flags were parsed."""
+    return self.__dict__['__flags_parsed']
+
+  def mark_as_parsed(self) -> None:
+    """Explicitly marks flags as parsed.
+
+    Use this when the caller knows that this FlagValues has been parsed as if
+    a ``__call__()`` invocation has happened.  This is only a public method for
+    use by things like appcommands which do additional command like parsing.
+    """
+    self.__dict__['__flags_parsed'] = True
+
+  def unparse_flags(self) -> None:
+    """Unparses all flags to the point before any FLAGS(argv) was called."""
+    for f in self._flags().values():
+      f.unparse()
+    # We log this message before marking flags as unparsed to avoid a
+    # problem when the logging library causes flags access.
+    logging.info('unparse_flags() called; flags access will now raise errors.')
+    self.__dict__['__flags_parsed'] = False
+    self.__dict__['__unparse_flags_called'] = True
+
+  def flag_values_dict(self) -> dict[str, Any]:
+    """Returns a dictionary that maps flag names to flag values."""
+    return {name: flag.value for name, flag in list(self._flags().items())}
+
+  def __str__(self):
+    """Returns a help string for all known flags."""
+    return self.get_help()
+
+  def get_help(
+      self, prefix: str = '', include_special_flags: bool = True
+  ) -> str:
+    """Returns a help string for all known flags.
+
+    Args:
+      prefix: str, per-line output prefix.
+      include_special_flags: bool, whether to include description of
+        SPECIAL_FLAGS, i.e. --flagfile and --undefok.
+
+    Returns:
+      str, formatted help message.
+    """
+    flags_by_module = self.flags_by_module_dict()
+    if flags_by_module:
+      modules = sorted(flags_by_module)
+      # Print the help for the main module first, if possible.
+      main_module = sys.argv[0]
+      if main_module in modules:
+        modules.remove(main_module)
+        modules = [main_module] + modules
+      return self._get_help_for_modules(modules, prefix, include_special_flags)
+    else:
+      output_lines: list[str] = []
+      # Just print one long list of flags.
+      values = list(self._flags().values())
+      if include_special_flags:
+        values.extend(_helpers.SPECIAL_FLAGS._flags().values())  # pylint: disable=protected-access
+      self._render_flag_list(values, output_lines, prefix)
+      return '\n'.join(output_lines)
+
+  def _get_help_for_modules(self, modules, prefix, include_special_flags):
+    """Returns the help string for a list of modules.
+
+    Private to absl.flags package.
+
+    Args:
+      modules: List[str], a list of modules to get the help string for.
+      prefix: str, a string that is prepended to each generated help line.
+      include_special_flags: bool, whether to include description of
+        SPECIAL_FLAGS, i.e. --flagfile and --undefok.
+    """
+    output_lines = []
+    for module in modules:
+      self._render_our_module_flags(module, output_lines, prefix)
+    if include_special_flags:
+      self._render_module_flags(
+          'absl.flags',
+          _helpers.SPECIAL_FLAGS._flags().values(),  # pylint: disable=protected-access  # pytype: disable=attribute-error
+          output_lines,
+          prefix,
+      )
+    return '\n'.join(output_lines)
+
+  def _render_module_flags(self, module, flags, output_lines, prefix=''):
+    """Returns a help string for a given module."""
+    if not isinstance(module, str):
+      module = module.__name__
+    output_lines.append('\n%s%s:' % (prefix, module))
+    self._render_flag_list(flags, output_lines, prefix + '  ')
+
+  def _render_our_module_flags(self, module, output_lines, prefix=''):
+    """Returns a help string for a given module."""
+    flags = self.get_flags_for_module(module)
+    if flags:
+      self._render_module_flags(module, flags, output_lines, prefix)
+
+  def _render_our_module_key_flags(self, module, output_lines, prefix=''):
+    """Returns a help string for the key flags of a given module.
+
+    Args:
+      module: module|str, the module to render key flags for.
+      output_lines: [str], a list of strings.  The generated help message lines
+        will be appended to this list.
+      prefix: str, a string that is prepended to each generated help line.
+    """
+    key_flags = self.get_key_flags_for_module(module)
+    if key_flags:
+      self._render_module_flags(module, key_flags, output_lines, prefix)
+
+  def module_help(self, module: Any) -> str:
+    """Describes the key flags of a module.
+
+    Args:
+      module: module|str, the module to describe the key flags for.
+
+    Returns:
+      str, describing the key flags of a module.
+    """
+    helplist: list[str] = []
+    self._render_our_module_key_flags(module, helplist)
+    return '\n'.join(helplist)
+
+  def main_module_help(self) -> str:
+    """Describes the key flags of the main module.
+
+    Returns:
+      str, describing the key flags of the main module.
+    """
+    return self.module_help(sys.argv[0])
+
+  def _render_flag_list(self, flaglist, output_lines, prefix='  '):
+    fl = self._flags()
+    special_fl = _helpers.SPECIAL_FLAGS._flags()  # pylint: disable=protected-access  # pytype: disable=attribute-error
+    flaglist = [(flag.name, flag) for flag in flaglist]
+    flaglist.sort()
+    flagset = {}
+    for name, flag in flaglist:
+      # It's possible this flag got deleted or overridden since being
+      # registered in the per-module flaglist.  Check now against the
+      # canonical source of current flag information, the _flags.
+      if fl.get(name, None) != flag and special_fl.get(name, None) != flag:
+        # a different flag is using this name now
+        continue
+      # only print help once
+      if flag in flagset:
+        continue
+      flagset[flag] = 1
+      flaghelp = ''
+      if flag.short_name:
+        flaghelp += '-%s,' % flag.short_name
+      if flag.boolean:
+        flaghelp += '--[no]%s:' % flag.name
+      else:
+        flaghelp += '--%s:' % flag.name
+      flaghelp += ' '
+      if flag.help:
+        flaghelp += flag.help
+      flaghelp = _helpers.text_wrap(
+          flaghelp, indent=prefix + '  ', firstline_indent=prefix
+      )
+      if flag.default_as_str:
+        flaghelp += '\n'
+        flaghelp += _helpers.text_wrap(
+            '(default: %s)' % flag.default_as_str, indent=prefix + '  '
+        )
+      if flag.parser.syntactic_help:
+        flaghelp += '\n'
+        flaghelp += _helpers.text_wrap(
+            '(%s)' % flag.parser.syntactic_help, indent=prefix + '  '
+        )
+      output_lines.append(flaghelp)
+
+  def get_flag_value(self, name: str, default: Any) -> Any:  # pylint: disable=invalid-name
+    """Returns the value of a flag (if not None) or a default value.
+
+    Args:
+      name: str, the name of a flag.
+      default: Default value to use if the flag value is None.
+
+    Returns:
+      Requested flag value or default.
+    """
+
+    value = self.__getattr__(name)
+    if value is not None:  # Can't do if not value, b/c value might be '0' or ""
+      return value
+    else:
+      return default
+
+  def _is_flag_file_directive(self, flag_string):
+    """Checks whether flag_string contain a --flagfile=<foo> directive."""
+    if isinstance(flag_string, str):
+      if flag_string.startswith('--flagfile='):
+        return 1
+      elif flag_string == '--flagfile':
+        return 1
+      elif flag_string.startswith('-flagfile='):
+        return 1
+      elif flag_string == '-flagfile':
+        return 1
+      else:
+        return 0
+    return 0
+
+  def _extract_filename(self, flagfile_str):
+    """Returns filename from a flagfile_str of form -[-]flagfile=filename.
+
+    The cases of --flagfile foo and -flagfile foo shouldn't be hitting
+    this function, as they are dealt with in the level above this
+    function.
+
+    Args:
+      flagfile_str: str, the flagfile string.
+
+    Returns:
+      str, the filename from a flagfile_str of form -[-]flagfile=filename.
+
+    Raises:
+      Error: Raised when illegal --flagfile is provided.
+    """
+    if flagfile_str.startswith('--flagfile='):
+      return os.path.expanduser((flagfile_str[(len('--flagfile=')) :]).strip())
+    elif flagfile_str.startswith('-flagfile='):
+      return os.path.expanduser((flagfile_str[(len('-flagfile=')) :]).strip())
+    else:
+      raise _exceptions.Error('Hit illegal --flagfile type: %s' % flagfile_str)
+
+  def _get_flag_file_lines(self, filename, parsed_file_stack=None):
+    """Returns the useful (!=comments, etc) lines from a file with flags.
+
+    Args:
+      filename: str, the name of the flag file.
+      parsed_file_stack: [str], a list of the names of the files that we have
+        recursively encountered at the current depth. MUTATED BY THIS FUNCTION
+        (but the original value is preserved upon successfully returning from
+        function call).
+
+    Returns:
+      List of strings. See the note below.
+
+    NOTE(springer): This function checks for a nested --flagfile=<foo>
+    tag and handles the lower file recursively. It returns a list of
+    all the lines that _could_ contain command flags. This is
+    EVERYTHING except whitespace lines and comments (lines starting
+    with '#' or '//').
+    """
+    # For consistency with the cpp version, ignore empty values.
+    if not filename:
+      return []
+    if parsed_file_stack is None:
+      parsed_file_stack = []
+    # We do a little safety check for reparsing a file we've already encountered
+    # at a previous depth.
+    if filename in parsed_file_stack:
+      sys.stderr.write(
+          'Warning: Hit circular flagfile dependency. Ignoring flagfile: %s\n'
+          % (filename,)
+      )
+      return []
+    else:
+      parsed_file_stack.append(filename)
+
+    line_list = []  # All line from flagfile.
+    flag_line_list = []  # Subset of lines w/o comments, blanks, flagfile= tags.
+    try:
+      file_obj = open(filename)
+    except OSError as e_msg:
+      raise _exceptions.CantOpenFlagFileError(
+          'ERROR:: Unable to open flagfile: %s' % e_msg
+      )
+
+    with file_obj:
+      line_list = file_obj.readlines()
+
+    # This is where we check each line in the file we just read.
+    for line in line_list:
+      if line.isspace():
+        pass
+      # Checks for comment (a line that starts with '#').
+      elif line.startswith('#') or line.startswith('//'):
+        pass
+      # Checks for a nested "--flagfile=<bar>" flag in the current file.
+      # If we find one, recursively parse down into that file.
+      elif self._is_flag_file_directive(line):
+        sub_filename = self._extract_filename(line)
+        included_flags = self._get_flag_file_lines(
+            sub_filename, parsed_file_stack=parsed_file_stack
+        )
+        flag_line_list.extend(included_flags)
+      else:
+        # Any line that's not a comment or a nested flagfile should get
+        # copied into 2nd position.  This leaves earlier arguments
+        # further back in the list, thus giving them higher priority.
+        flag_line_list.append(line.strip())
+
+    parsed_file_stack.pop()
+    return flag_line_list
+
+  def read_flags_from_files(
+      self, argv: Sequence[str], force_gnu: bool = True
+  ) -> list[str]:
+    """Processes command line args, but also allow args to be read from file.
+
+    Args:
+      argv: [str], a list of strings, usually sys.argv[1:], which may contain
+        one or more flagfile directives of the form --flagfile="./filename".
+        Note that the name of the program (sys.argv[0]) should be omitted.
+      force_gnu: bool, if False, --flagfile parsing obeys the
+        FLAGS.is_gnu_getopt() value. If True, ignore the value and always follow
+        gnu_getopt semantics.
+
+    Returns:
+      A new list which has the original list combined with what we read
+      from any flagfile(s).
+
+    Raises:
+      IllegalFlagValueError: Raised when --flagfile is provided with no
+          argument.
+
+    This function is called by FLAGS(argv).
+    It scans the input list for a flag that looks like:
+    --flagfile=<somefile>. Then it opens <somefile>, reads all valid key
+    and value pairs and inserts them into the input list in exactly the
+    place where the --flagfile arg is found.
+
+    Note that your application's flags are still defined the usual way
+    using absl.flags DEFINE_flag() type functions.
+
+    Notes (assuming we're getting a commandline of some sort as our input):
+
+    * For duplicate flags, the last one we hit should "win".
+    * Since flags that appear later win, a flagfile's settings can be "weak"
+        if the --flagfile comes at the beginning of the argument sequence,
+        and it can be "strong" if the --flagfile comes at the end.
+    * A further "--flagfile=<otherfile.cfg>" CAN be nested in a flagfile.
+        It will be expanded in exactly the spot where it is found.
+    * In a flagfile, a line beginning with # or // is a comment.
+    * Entirely blank lines _should_ be ignored.
+    """
+    rest_of_args = argv
+    new_argv = []
+    while rest_of_args:
+      current_arg = rest_of_args[0]
+      rest_of_args = rest_of_args[1:]
+      if self._is_flag_file_directive(current_arg):
+        # This handles the case of -(-)flagfile foo.  In this case the
+        # next arg really is part of this one.
+        if current_arg == '--flagfile' or current_arg == '-flagfile':
+          if not rest_of_args:
+            raise _exceptions.IllegalFlagValueError(
+                '--flagfile with no argument'
+            )
+          flag_filename = os.path.expanduser(rest_of_args[0])
+          rest_of_args = rest_of_args[1:]
+        else:
+          # This handles the case of (-)-flagfile=foo.
+          flag_filename = self._extract_filename(current_arg)
+        new_argv.extend(self._get_flag_file_lines(flag_filename))
+      else:
+        new_argv.append(current_arg)
+        # Stop parsing after '--', like getopt and gnu_getopt.
+        if current_arg == '--':
+          break
+        # Stop parsing after a non-flag, like getopt.
+        if not current_arg.startswith('-'):
+          if not force_gnu and not self.__dict__['__use_gnu_getopt']:
+            break
+        else:
+          if (
+              '=' not in current_arg
+              and rest_of_args
+              and not rest_of_args[0].startswith('-')
+          ):
+            # If this is an occurrence of a legitimate --x y, skip the value
+            # so that it won't be mistaken for a standalone arg.
+            fl = self._flags()
+            name = current_arg.lstrip('-')
+            if name in fl and not fl[name].boolean:
+              current_arg = rest_of_args[0]
+              rest_of_args = rest_of_args[1:]
+              new_argv.append(current_arg)
+
+    if rest_of_args:
+      new_argv.extend(rest_of_args)
+
+    return new_argv
+
+  def flags_into_string(self) -> str:
+    """Returns a string with the flags assignments from this FlagValues object.
+
+    This function ignores flags whose value is None.  Each flag
+    assignment is separated by a newline.
+
+    NOTE: MUST mirror the behavior of the C++ CommandlineFlagsIntoString
+    from https://github.com/gflags/gflags.
+
+    Returns:
+      str, the string with the flags assignments from this FlagValues object.
+      The flags are ordered by (module_name, flag_name).
+    """
+    module_flags = sorted(self.flags_by_module_dict().items())
+    s = ''
+    for unused_module_name, flags in module_flags:
+      flags = sorted(flags, key=lambda f: f.name)
+      for flag in flags:
+        if flag.value is not None:
+          s += flag.serialize() + '\n'
+    return s
+
+  def append_flags_into_file(self, filename: str) -> None:
+    """Appends all flags assignments from this FlagInfo object to a file.
+
+    Output will be in the format of a flagfile.
+
+    NOTE: MUST mirror the behavior of the C++ AppendFlagsIntoFile
+    from https://github.com/gflags/gflags.
+
+    Args:
+      filename: str, name of the file.
+    """
+    with open(filename, 'a') as out_file:
+      out_file.write(self.flags_into_string())
+
+  def write_help_in_xml_format(self, outfile: TextIO | None = None) -> None:
+    """Outputs flag documentation in XML format.
+
+    NOTE: We use element names that are consistent with those used by
+    the C++ command-line flag library, from
+    https://github.com/gflags/gflags.
+    We also use a few new elements (e.g., <key>), but we do not
+    interfere / overlap with existing XML elements used by the C++
+    library.  Please maintain this consistency.
+
+    Args:
+      outfile: File object we write to.  Default None means sys.stdout.
+    """
+    doc = minidom.Document()
+    all_flag = doc.createElement('AllFlags')
+    doc.appendChild(all_flag)
+
+    all_flag.appendChild(
+        _helpers.create_xml_dom_element(
+            doc, 'program', os.path.basename(sys.argv[0])
+        )
+    )
+
+    usage_doc = sys.modules['__main__'].__doc__
+    if not usage_doc:
+      usage_doc = '\nUSAGE: %s [flags]\n' % sys.argv[0]
+    else:
+      usage_doc = usage_doc.replace('%s', sys.argv[0])
+    all_flag.appendChild(
+        _helpers.create_xml_dom_element(doc, 'usage', usage_doc)
+    )
+
+    # Get list of key flags for the main module.
+    key_flags = self.get_key_flags_for_module(sys.argv[0])
+
+    flags_by_module = self.flags_by_module_dict()
+    # Sort flags by declaring module name and next by flag name.
+    for module_name in sorted(flags_by_module.keys()):
+      flag_list = [(f.name, f) for f in flags_by_module[module_name]]
+      flag_list.sort()
+      for unused_flag_name, flag in flag_list:
+        is_key = flag in key_flags
+        all_flag.appendChild(
+            flag._create_xml_dom_element(  # pylint: disable=protected-access
+                doc, module_name, is_key=is_key
+            )
+        )
+
+    outfile = outfile or sys.stdout
+    outfile.write(
+        doc.toprettyxml(indent='  ', encoding='utf-8').decode('utf-8')
+    )
+    outfile.flush()
+
+  def _check_method_name_conflicts(self, name: str, flag: Flag):
+    if flag.allow_using_method_names:
+      return
+    short_name = flag.short_name
+    flag_names = {name} if short_name is None else {name, short_name}
+    for flag_name in flag_names:
+      if flag_name in self.__dict__['__banned_flag_names']:
+        raise _exceptions.FlagNameConflictsWithMethodError(
+            'Cannot define a flag named "{name}". It conflicts with a method '
+            'on class "{class_name}". To allow defining it, use '
+            'allow_using_method_names and access the flag value with '
+            "FLAGS['{name}'].value. FLAGS.{name} returns the method, "
+            'not the flag value.'.format(
+                name=flag_name, class_name=type(self).__name__
+            )
+        )
+
+
+FLAGS = FlagValues()
+
+
+class FlagHolder(Generic[_T_co]):
+  """Holds a defined flag.
+
+  This facilitates a cleaner api around global state. Instead of::
+
+      flags.DEFINE_integer('foo', ...)
+      flags.DEFINE_integer('bar', ...)
+
+      def method():
+        # prints parsed value of 'bar' flag
+        print(flags.FLAGS.foo)
+        # runtime error due to typo or possibly bad coding style.
+        print(flags.FLAGS.baz)
+
+  it encourages code like::
+
+      _FOO_FLAG = flags.DEFINE_integer('foo', ...)
+      _BAR_FLAG = flags.DEFINE_integer('bar', ...)
+
+      def method():
+        print(_FOO_FLAG.value)
+        print(_BAR_FLAG.value)
+
+  since the name of the flag appears only once in the source code.
+  """
+
+  value: _T_co
+
+  def __init__(
+      self,
+      flag_values: FlagValues,
+      flag: Flag[_T_co],
+      ensure_non_none_value: bool = False,
+  ):
+    """Constructs a FlagHolder instance providing typesafe access to flag.
+
+    Args:
+      flag_values: The container the flag is registered to.
+      flag: The flag object for this flag.
+      ensure_non_none_value: Is the value of the flag allowed to be None.
+    """
+    self._flagvalues = flag_values
+    # We take the entire flag object, but only keep the name. Why?
+    # - We want FlagHolder[T] to be generic container
+    # - flag_values contains all flags, so has no reference to T.
+    # - typecheckers don't like to see a generic class where none of the ctor
+    #   arguments refer to the generic type.
+    self._name = flag.name
+    # We intentionally do NOT check if the default value is None.
+    # This allows future use of this for "required flags with None default"
+    self._ensure_non_none_value = ensure_non_none_value
+
+  def __eq__(self, other):
+    raise TypeError(
+        "unsupported operand type(s) for ==: '{0}' and '{1}' "
+        "(did you mean to use '{0}.value' instead?)".format(
+            type(self).__name__, type(other).__name__
+        )
+    )
+
+  def __bool__(self):
+    raise TypeError(
+        "bool() not supported for instances of type '{0}' "
+        "(did you mean to use '{0}.value' instead?)".format(type(self).__name__)
+    )
+
+  __nonzero__ = __bool__
+
+  @property
+  def name(self) -> str:
+    return self._name
+
+  @property  # type: ignore[no-redef]
+  def value(self) -> _T_co:
+    """Returns the value of the flag.
+
+    If ``_ensure_non_none_value`` is ``True``, then return value is not
+    ``None``.
+
+    Raises:
+      UnparsedFlagAccessError: if flag parsing has not finished.
+      IllegalFlagValueError: if value is None unexpectedly.
+    """
+    val = getattr(self._flagvalues, self._name)
+    if self._ensure_non_none_value and val is None:
+      raise _exceptions.IllegalFlagValueError(
+          'Unexpected None value for flag %s' % self._name
+      )
+    return val
+
+  @property
+  def default(self) -> _T_co:
+    """Returns the default value of the flag."""
+    return self._flagvalues[self._name].default  # type: ignore[return-value]
+
+  @property
+  def present(self) -> bool:
+    """Returns True if the flag was parsed from command-line flags."""
+    return bool(self._flagvalues[self._name].present)
+
+  def serialize(self) -> str:
+    """Returns a serialized representation of the flag."""
+    return self._flagvalues[self._name].serialize()
+
+
+def resolve_flag_ref(
+    flag_ref: str | FlagHolder, flag_values: FlagValues
+) -> tuple[str, FlagValues]:
+  """Helper to validate and resolve a flag reference argument."""
+  if isinstance(flag_ref, FlagHolder):
+    new_flag_values = flag_ref._flagvalues  # pylint: disable=protected-access
+    if flag_values != FLAGS and flag_values != new_flag_values:
+      raise ValueError(
+          'flag_values must not be customized when operating on a FlagHolder'
+      )
+    return flag_ref.name, new_flag_values
+  return flag_ref, flag_values
+
+
+def resolve_flag_refs(
+    flag_refs: Sequence[str | FlagHolder], flag_values: FlagValues
+) -> tuple[list[str], FlagValues]:
+  """Helper to validate and resolve flag reference list arguments."""
+  fv = None
+  names = []
+  for ref in flag_refs:
+    if isinstance(ref, FlagHolder):
+      newfv = ref._flagvalues  # pylint: disable=protected-access
+      name = ref.name
+    else:
+      newfv = flag_values
+      name = ref
+    if fv and fv != newfv:
+      raise ValueError(
+          'multiple FlagValues instances used in invocation. '
+          'FlagHolders must be registered to the same FlagValues instance as '
+          'do flag names, if provided.'
+      )
+    fv = newfv
+    names.append(name)
+  if fv is None:
+    raise ValueError('flag_refs argument must not be empty')
+  return names, fv

.venv/lib/python3.13/site-packages/absl/flags/_helpers.py

@@ -0,0 +1,403 @@
+# Copyright 2017 The Abseil Authors.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Internal helper functions for Abseil Python flags library."""
+
+from collections.abc import Iterable, Sequence
+import re
+import shutil
+import sys
+import textwrap
+import types
+from typing import Any, NamedTuple
+from xml.dom import minidom
+
+
+_DEFAULT_HELP_WIDTH = 80  # Default width of help output.
+# Minimal "sane" width of help output. We assume that any value below 40 is
+# unreasonable.
+_MIN_HELP_WIDTH = 40
+
+# Define the allowed error rate in an input string to get suggestions.
+#
+# We lean towards a high threshold because we tend to be matching a phrase,
+# and the simple algorithm used here is geared towards correcting word
+# spellings.
+#
+# For manual testing, consider "<command> --list" which produced a large number
+# of spurious suggestions when we used "least_errors > 0.5" instead of
+# "least_erros >= 0.5".
+_SUGGESTION_ERROR_RATE_THRESHOLD = 0.50
+
+# Characters that cannot appear or are highly discouraged in an XML 1.0
+# document. (See http://www.w3.org/TR/REC-xml/#charsets or
+# https://en.wikipedia.org/wiki/Valid_characters_in_XML#XML_1.0)
+_ILLEGAL_XML_CHARS_REGEX = re.compile(
+    '[\x00-\x08\x0b\x0c\x0e-\x1f\x7f-\x84\x86-\x9f\ud800-\udfff\ufffe\uffff]'
+)
+
+# This is a set of module ids for the modules that disclaim key flags.
+# This module is explicitly added to this set so that we never consider it to
+# define key flag.
+disclaim_module_ids: set[int] = {id(sys.modules[__name__])}
+
+
+# Define special flags here so that help may be generated for them.
+# NOTE: Please do NOT use SPECIAL_FLAGS from outside flags module.
+# Initialized inside flagvalues.py.
+# NOTE: This cannot be annotated as its actual FlagValues type since this would
+# create a circular dependency.
+SPECIAL_FLAGS: Any = None
+
+
+# This points to the flags module, initialized in flags/__init__.py.
+# This should only be used in adopt_module_key_flags to take SPECIAL_FLAGS into
+# account.
+FLAGS_MODULE: types.ModuleType | None = None
+
+
+class _ModuleObjectAndName(NamedTuple):
+  """Module object and name.
+
+  Fields:
+  - module: object, module object.
+  - module_name: str, module name.
+  """
+  module: types.ModuleType
+  module_name: str
+
+
+def get_module_object_and_name(
+    globals_dict: dict[str, Any],
+) -> _ModuleObjectAndName | None:
+  """Returns the module that defines a global environment, and its name.
+
+  Args:
+    globals_dict: A dictionary that should correspond to an environment
+      providing the values of the globals.
+
+  Returns:
+    _ModuleObjectAndName - pair of module object & module name.
+    Returns None if the module could not be identified.
+  """
+  try:
+    name = globals_dict['__name__']
+    module = sys.modules[name]
+  except KeyError:
+    return None
+  # Pick a more informative name for the main module.
+  return _ModuleObjectAndName(
+      module, sys.argv[0] if name == '__main__' else name
+  )
+
+
+def get_calling_module_object_and_name() -> _ModuleObjectAndName:
+  """Returns the module that's calling into this module.
+
+  We generally use this function to get the name of the module calling a
+  DEFINE_foo... function.
+
+  Returns:
+    The module object that called into this one.
+
+  Raises:
+    AssertionError: Raised when no calling module could be identified.
+  """
+  for depth in range(1, sys.getrecursionlimit()):
+    # sys._getframe is the right thing to use here, as it's the best
+    # way to walk up the call stack.
+    globals_for_frame = sys._getframe(depth).f_globals  # pylint: disable=protected-access
+    module = get_module_object_and_name(globals_for_frame)
+    if module is not None and id(module.module) not in disclaim_module_ids:
+      return module
+  raise AssertionError('No module was found')
+
+
+def get_calling_module() -> str:
+  """Returns the name of the module that's calling into this module."""
+  return get_calling_module_object_and_name().module_name
+
+
+def create_xml_dom_element(
+    doc: minidom.Document, name: str, value: Any
+) -> minidom.Element:
+  """Returns an XML DOM element with name and text value.
+
+  Args:
+    doc: minidom.Document, the DOM document it should create nodes from.
+    name: str, the tag of XML element.
+    value: object, whose string representation will be used
+        as the value of the XML element. Illegal or highly discouraged xml 1.0
+        characters are stripped.
+
+  Returns:
+    An instance of minidom.Element.
+  """
+  s = str(value)
+  if isinstance(value, bool):
+    # Display boolean values as the C++ flag library does: no caps.
+    s = s.lower()
+  # Remove illegal xml characters.
+  s = _ILLEGAL_XML_CHARS_REGEX.sub('', s)
+
+  e = doc.createElement(name)
+  e.appendChild(doc.createTextNode(s))
+  return e
+
+
+def get_help_width() -> int:
+  """Returns the integer width of help lines that is used in TextWrap."""
+  size = shutil.get_terminal_size(fallback=(_DEFAULT_HELP_WIDTH, 1))
+  return size.columns
+
+
+def get_flag_suggestions(
+    attempt: str, longopt_list: Sequence[str]
+) -> list[str]:
+  """Returns helpful similar matches for an invalid flag."""
+  # Don't suggest on very short strings, or if no longopts are specified.
+  if len(attempt) <= 2 or not longopt_list:
+    return []
+
+  option_names = [v.split('=')[0] for v in longopt_list]
+
+  # Find close approximations in flag prefixes.
+  # This also handles the case where the flag is spelled right but ambiguous.
+  distances = [(_damerau_levenshtein(attempt, option[0:len(attempt)]), option)
+               for option in option_names]
+  # t[0] is distance, and sorting by t[1] allows us to have stable output.
+  distances.sort()
+
+  least_errors, _ = distances[0]
+  # Don't suggest excessively bad matches.
+  if least_errors >= _SUGGESTION_ERROR_RATE_THRESHOLD * len(attempt):
+    return []
+
+  suggestions = []
+  for errors, name in distances:
+    if errors == least_errors:
+      suggestions.append(name)
+    else:
+      break
+  return suggestions
+
+
+def _damerau_levenshtein(a, b):
+  """Returns Damerau-Levenshtein edit distance from a to b."""
+  memo = {}
+
+  def distance(x, y):
+    """Recursively defined string distance with memoization."""
+    if (x, y) in memo:
+      return memo[x, y]
+    if not x:
+      d = len(y)
+    elif not y:
+      d = len(x)
+    else:
+      d = min(
+          distance(x[1:], y) + 1,  # correct an insertion error
+          distance(x, y[1:]) + 1,  # correct a deletion error
+          distance(x[1:], y[1:]) + (x[0] != y[0]))  # correct a wrong character
+      if len(x) >= 2 and len(y) >= 2 and x[0] == y[1] and x[1] == y[0]:
+        # Correct a transposition.
+        t = distance(x[2:], y[2:]) + 1
+        if d > t:
+          d = t
+
+    memo[x, y] = d
+    return d
+  return distance(a, b)
+
+
+def text_wrap(
+    text: str,
+    length: int | None = None,
+    indent: str = '',
+    firstline_indent: str | None = None,
+) -> str:
+  """Wraps a given text to a maximum line length and returns it.
+
+  It turns lines that only contain whitespace into empty lines, keeps new lines,
+  and expands tabs using 4 spaces.
+
+  Args:
+    text: Text to wrap.
+    length: Maximum length of a line, includes indentation. If this is `None`
+      then use `get_help_width()`.
+    indent: Indent for all but first line.
+    firstline_indent: Indent for first line. If `None`, fall back to `indent`.
+
+  Returns:
+    The wrapped text.
+
+  Raises:
+    ValueError: Raised if indent or firstline_indent not shorter than length.
+  """
+  # Get defaults where callee used None
+  if length is None:
+    length = get_help_width()
+  if indent is None:
+    indent = ''
+  if firstline_indent is None:
+    firstline_indent = indent
+
+  if len(indent) >= length:
+    raise ValueError('Length of indent exceeds length')
+  if len(firstline_indent) >= length:
+    raise ValueError('Length of first line indent exceeds length')
+
+  text = text.expandtabs(4)
+
+  result = []
+  # Create one wrapper for the first paragraph and one for subsequent
+  # paragraphs that does not have the initial wrapping.
+  wrapper = textwrap.TextWrapper(
+      width=length, initial_indent=firstline_indent, subsequent_indent=indent)
+  subsequent_wrapper = textwrap.TextWrapper(
+      width=length, initial_indent=indent, subsequent_indent=indent)
+
+  # textwrap does not have any special treatment for newlines. From the docs:
+  # "...newlines may appear in the middle of a line and cause strange output.
+  # For this reason, text should be split into paragraphs (using
+  # str.splitlines() or similar) which are wrapped separately."
+  for paragraph in (p.strip() for p in text.splitlines()):
+    if paragraph:
+      result.extend(wrapper.wrap(paragraph))
+    else:
+      result.append('')  # Keep empty lines.
+    # Replace initial wrapper with wrapper for subsequent paragraphs.
+    wrapper = subsequent_wrapper
+
+  return '\n'.join(result)
+
+
+def flag_dict_to_args(
+    flag_map: dict[str, Any], multi_flags: set[str] | None = None
+) -> Iterable[str]:
+  """Convert a dict of values into process call parameters.
+
+  This method is used to convert a dictionary into a sequence of parameters
+  for a binary that parses arguments using this module.
+
+  Args:
+    flag_map: dict, a mapping where the keys are flag names (strings).
+        values are treated according to their type:
+
+        * If value is ``None``, then only the name is emitted.
+        * If value is ``True``, then only the name is emitted.
+        * If value is ``False``, then only the name prepended with 'no' is
+          emitted.
+        * If value is a string then ``--name=value`` is emitted.
+        * If value is a collection, this will emit
+          ``--name=value1,value2,value3``, unless the flag name is in
+          ``multi_flags``, in which case this will emit
+          ``--name=value1 --name=value2 --name=value3``.
+        * Everything else is converted to string an passed as such.
+
+    multi_flags: set, names (strings) of flags that should be treated as
+        multi-flags.
+  Yields:
+    sequence of string suitable for a subprocess execution.
+  """
+  for key, value in flag_map.items():
+    if value is None:
+      yield '--%s' % key
+    elif isinstance(value, bool):
+      if value:
+        yield '--%s' % key
+      else:
+        yield '--no%s' % key
+    elif isinstance(value, (bytes, str)):
+      # We don't want strings to be handled like python collections.
+      yield '--%s=%s' % (key, value)  # type: ignore[str-bytes-safe]
+    else:
+      # Now we attempt to deal with collections.
+      try:
+        if multi_flags and key in multi_flags:
+          for item in value:
+            yield '--%s=%s' % (key, str(item))
+        else:
+          yield '--%s=%s' % (key, ','.join(str(item) for item in value))
+      except TypeError:
+        # Default case.
+        yield '--%s=%s' % (key, value)
+
+
+def trim_docstring(docstring: str) -> str:
+  """Removes indentation from triple-quoted strings.
+
+  This is the function specified in PEP 257 to handle docstrings:
+  https://www.python.org/dev/peps/pep-0257/.
+
+  Args:
+    docstring: str, a python docstring.
+
+  Returns:
+    str, docstring with indentation removed.
+  """
+  if not docstring:
+    return ''
+
+  # If you've got a line longer than this you have other problems...
+  max_indent = 1 << 29
+
+  # Convert tabs to spaces (following the normal Python rules)
+  # and split into a list of lines:
+  lines = docstring.expandtabs().splitlines()
+
+  # Determine minimum indentation (first line doesn't count):
+  indent = max_indent
+  for line in lines[1:]:
+    stripped = line.lstrip()
+    if stripped:
+      indent = min(indent, len(line) - len(stripped))
+  # Remove indentation (first line is special):
+  trimmed = [lines[0].strip()]
+  if indent < max_indent:
+    for line in lines[1:]:
+      trimmed.append(line[indent:].rstrip())
+  # Strip off trailing and leading blank lines:
+  while trimmed and not trimmed[-1]:
+    trimmed.pop()
+  while trimmed and not trimmed[0]:
+    trimmed.pop(0)
+  # Return a single string:
+  return '\n'.join(trimmed)
+
+
+def doc_to_help(doc: str) -> str:
+  """Takes a __doc__ string and reformats it as help."""
+
+  # Get rid of starting and ending white space. Using lstrip() or even
+  # strip() could drop more than maximum of first line and right space
+  # of last line.
+  doc = doc.strip()
+
+  # Get rid of all empty lines.
+  whitespace_only_line = re.compile('^[ \t]+$', re.M)
+  doc = whitespace_only_line.sub('', doc)
+
+  # Cut out common space at line beginnings.
+  doc = trim_docstring(doc)
+
+  # Just like this module's comment, comments tend to be aligned somehow.
+  # In other words they all start with the same amount of white space.
+  # 1) keep double new lines;
+  # 2) keep ws after new lines if not empty line;
+  # 3) all other new lines shall be changed to a space;
+  # Solution: Match new lines between non white space and replace with space.
+  doc = re.sub(r'(?<=\S)\n(?=\S)', ' ', doc, flags=re.M)
+
+  return doc

.venv/lib/python3.13/site-packages/absl/flags/_validators.py

@@ -0,0 +1,353 @@
+# Copyright 2017 The Abseil Authors.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Module to enforce different constraints on flags.
+
+Flags validators can be registered using following functions / decorators::
+
+    flags.register_validator
+    @flags.validator
+    flags.register_multi_flags_validator
+    @flags.multi_flags_validator
+
+Three convenience functions are also provided for common flag constraints::
+
+    flags.mark_flag_as_required
+    flags.mark_flags_as_required
+    flags.mark_flags_as_mutual_exclusive
+    flags.mark_bool_flags_as_mutual_exclusive
+
+See their docstring in this module for a usage manual.
+
+Do NOT import this module directly. Import the flags package and use the
+aliases defined at the package level instead.
+"""
+
+import warnings
+
+from absl.flags import _exceptions
+from absl.flags import _flagvalues
+from absl.flags import _validators_classes
+
+
+def register_validator(flag_name,
+                       checker,
+                       message='Flag validation failed',
+                       flag_values=_flagvalues.FLAGS):
+  """Adds a constraint, which will be enforced during program execution.
+
+  The constraint is validated when flags are initially parsed, and after each
+  change of the corresponding flag's value.
+
+  Args:
+    flag_name: str | FlagHolder, name or holder of the flag to be checked.
+        Positional-only parameter.
+    checker: callable, a function to validate the flag.
+
+        * input - A single positional argument: The value of the corresponding
+          flag (string, boolean, etc.  This value will be passed to checker
+          by the library).
+        * output - bool, True if validator constraint is satisfied.
+          If constraint is not satisfied, it should either ``return False`` or
+          ``raise flags.ValidationError(desired_error_message)``.
+
+    message: str, error text to be shown to the user if checker returns False.
+        If checker raises flags.ValidationError, message from the raised
+        error will be shown.
+    flag_values: flags.FlagValues, optional FlagValues instance to validate
+        against.
+
+  Raises:
+    AttributeError: Raised when flag_name is not registered as a valid flag
+        name.
+    ValueError: Raised when flag_values is non-default and does not match the
+        FlagValues of the provided FlagHolder instance.
+  """
+  flag_name, flag_values = _flagvalues.resolve_flag_ref(flag_name, flag_values)
+  v = _validators_classes.SingleFlagValidator(flag_name, checker, message)
+  _add_validator(flag_values, v)
+
+
+def validator(flag_name, message='Flag validation failed',
+              flag_values=_flagvalues.FLAGS):
+  """A function decorator for defining a flag validator.
+
+  Registers the decorated function as a validator for flag_name, e.g.::
+
+      @flags.validator('foo')
+      def _CheckFoo(foo):
+        ...
+
+  See :func:`register_validator` for the specification of checker function.
+
+  Args:
+    flag_name: str | FlagHolder, name or holder of the flag to be checked.
+        Positional-only parameter.
+    message: str, error text to be shown to the user if checker returns False.
+        If checker raises flags.ValidationError, message from the raised
+        error will be shown.
+    flag_values: flags.FlagValues, optional FlagValues instance to validate
+        against.
+  Returns:
+    A function decorator that registers its function argument as a validator.
+  Raises:
+    AttributeError: Raised when flag_name is not registered as a valid flag
+        name.
+  """
+
+  def decorate(function):
+    register_validator(flag_name, function,
+                       message=message,
+                       flag_values=flag_values)
+    return function
+  return decorate
+
+
+def register_multi_flags_validator(flag_names,
+                                   multi_flags_checker,
+                                   message='Flags validation failed',
+                                   flag_values=_flagvalues.FLAGS):
+  """Adds a constraint to multiple flags.
+
+  The constraint is validated when flags are initially parsed, and after each
+  change of the corresponding flag's value.
+
+  Args:
+    flag_names: [str | FlagHolder], a list of the flag names or holders to be
+        checked. Positional-only parameter.
+    multi_flags_checker: callable, a function to validate the flag.
+
+        * input - dict, with keys() being flag_names, and value for each key
+            being the value of the corresponding flag (string, boolean, etc).
+        * output - bool, True if validator constraint is satisfied.
+            If constraint is not satisfied, it should either return False or
+            raise flags.ValidationError.
+
+    message: str, error text to be shown to the user if checker returns False.
+        If checker raises flags.ValidationError, message from the raised
+        error will be shown.
+    flag_values: flags.FlagValues, optional FlagValues instance to validate
+        against.
+
+  Raises:
+    AttributeError: Raised when a flag is not registered as a valid flag name.
+    ValueError: Raised when multiple FlagValues are used in the same
+        invocation. This can occur when FlagHolders have different `_flagvalues`
+        or when str-type flag_names entries are present and the `flag_values`
+        argument does not match that of provided FlagHolder(s).
+  """
+  flag_names, flag_values = _flagvalues.resolve_flag_refs(
+      flag_names, flag_values)
+  v = _validators_classes.MultiFlagsValidator(
+      flag_names, multi_flags_checker, message)
+  _add_validator(flag_values, v)
+
+
+def multi_flags_validator(flag_names,
+                          message='Flag validation failed',
+                          flag_values=_flagvalues.FLAGS):
+  """A function decorator for defining a multi-flag validator.
+
+  Registers the decorated function as a validator for flag_names, e.g.::
+
+      @flags.multi_flags_validator(['foo', 'bar'])
+      def _CheckFooBar(flags_dict):
+        ...
+
+  See :func:`register_multi_flags_validator` for the specification of checker
+  function.
+
+  Args:
+    flag_names: [str | FlagHolder], a list of the flag names or holders to be
+        checked. Positional-only parameter.
+    message: str, error text to be shown to the user if checker returns False.
+        If checker raises flags.ValidationError, message from the raised
+        error will be shown.
+    flag_values: flags.FlagValues, optional FlagValues instance to validate
+        against.
+
+  Returns:
+    A function decorator that registers its function argument as a validator.
+
+  Raises:
+    AttributeError: Raised when a flag is not registered as a valid flag name.
+  """
+
+  def decorate(function):
+    register_multi_flags_validator(flag_names,
+                                   function,
+                                   message=message,
+                                   flag_values=flag_values)
+    return function
+
+  return decorate
+
+
+def mark_flag_as_required(flag_name, flag_values=_flagvalues.FLAGS):
+  """Ensures that flag is not None during program execution.
+
+  Registers a flag validator, which will follow usual validator rules.
+  Important note: validator will pass for any non-``None`` value, such as
+  ``False``, ``0`` (zero), ``''`` (empty string) and so on.
+
+  If your module might be imported by others, and you only wish to make the flag
+  required when the module is directly executed, call this method like this::
+
+      if __name__ == '__main__':
+        flags.mark_flag_as_required('your_flag_name')
+        app.run()
+
+  Args:
+    flag_name: str | FlagHolder, name or holder of the flag.
+        Positional-only parameter.
+    flag_values: flags.FlagValues, optional :class:`~absl.flags.FlagValues`
+        instance where the flag is defined.
+  Raises:
+    AttributeError: Raised when flag_name is not registered as a valid flag
+        name.
+    ValueError: Raised when flag_values is non-default and does not match the
+        FlagValues of the provided FlagHolder instance.
+  """
+  flag_name, flag_values = _flagvalues.resolve_flag_ref(flag_name, flag_values)
+  if flag_values[flag_name].default is not None:
+    warnings.warn(
+        'Flag --%s has a non-None default value; therefore, '
+        'mark_flag_as_required will pass even if flag is not specified in the '
+        'command line!' % flag_name,
+        stacklevel=2)
+  register_validator(
+      flag_name,
+      lambda value: value is not None,
+      message=f'Flag --{flag_name} must have a value other than None.',
+      flag_values=flag_values,
+  )
+
+
+def mark_flags_as_required(flag_names, flag_values=_flagvalues.FLAGS):
+  """Ensures that flags are not None during program execution.
+
+  If your module might be imported by others, and you only wish to make the flag
+  required when the module is directly executed, call this method like this::
+
+      if __name__ == '__main__':
+        flags.mark_flags_as_required(['flag1', 'flag2', 'flag3'])
+        app.run()
+
+  Args:
+    flag_names: Sequence[str | FlagHolder], names or holders of the flags.
+    flag_values: flags.FlagValues, optional FlagValues instance where the flags
+        are defined.
+  Raises:
+    AttributeError: If any of flag name has not already been defined as a flag.
+  """
+  for flag_name in flag_names:
+    mark_flag_as_required(flag_name, flag_values)
+
+
+def mark_flags_as_mutual_exclusive(flag_names, required=False,
+                                   flag_values=_flagvalues.FLAGS):
+  """Ensures that only one flag among flag_names is not None.
+
+  Important note: This validator checks if flag values are ``None``, and it does
+  not distinguish between default and explicit values. Therefore, this validator
+  does not make sense when applied to flags with default values other than None,
+  including other false values (e.g. ``False``, ``0``, ``''``, ``[]``). That
+  includes multi flags with a default value of ``[]`` instead of None.
+
+  Args:
+    flag_names: [str | FlagHolder], names or holders of flags.
+        Positional-only parameter.
+    required: bool. If true, exactly one of the flags must have a value other
+        than None. Otherwise, at most one of the flags can have a value other
+        than None, and it is valid for all of the flags to be None.
+    flag_values: flags.FlagValues, optional FlagValues instance where the flags
+        are defined.
+
+  Raises:
+    ValueError: Raised when multiple FlagValues are used in the same
+        invocation. This can occur when FlagHolders have different `_flagvalues`
+        or when str-type flag_names entries are present and the `flag_values`
+        argument does not match that of provided FlagHolder(s).
+  """
+  flag_names, flag_values = _flagvalues.resolve_flag_refs(
+      flag_names, flag_values)
+  for flag_name in flag_names:
+    if flag_values[flag_name].default is not None:
+      warnings.warn(
+          'Flag --{} has a non-None default value. That does not make sense '
+          'with mark_flags_as_mutual_exclusive, which checks whether the '
+          'listed flags have a value other than None.'.format(flag_name),
+          stacklevel=2)
+
+  def validate_mutual_exclusion(flags_dict):
+    flag_count = sum(1 for val in flags_dict.values() if val is not None)
+    if flag_count == 1 or (not required and flag_count == 0):
+      return True
+    raise _exceptions.ValidationError(
+        '{} one of ({}) must have a value other than None.'.format(
+            'Exactly' if required else 'At most', ', '.join(flag_names)))
+
+  register_multi_flags_validator(
+      flag_names, validate_mutual_exclusion, flag_values=flag_values)
+
+
+def mark_bool_flags_as_mutual_exclusive(flag_names, required=False,
+                                        flag_values=_flagvalues.FLAGS):
+  """Ensures that only one flag among flag_names is True.
+
+  Args:
+    flag_names: [str | FlagHolder], names or holders of flags.
+        Positional-only parameter.
+    required: bool. If true, exactly one flag must be True. Otherwise, at most
+        one flag can be True, and it is valid for all flags to be False.
+    flag_values: flags.FlagValues, optional FlagValues instance where the flags
+        are defined.
+
+  Raises:
+    ValueError: Raised when multiple FlagValues are used in the same
+        invocation. This can occur when FlagHolders have different `_flagvalues`
+        or when str-type flag_names entries are present and the `flag_values`
+        argument does not match that of provided FlagHolder(s).
+  """
+  flag_names, flag_values = _flagvalues.resolve_flag_refs(
+      flag_names, flag_values)
+  for flag_name in flag_names:
+    if not flag_values[flag_name].boolean:
+      raise _exceptions.ValidationError(
+          'Flag --{} is not Boolean, which is required for flags used in '
+          'mark_bool_flags_as_mutual_exclusive.'.format(flag_name))
+
+  def validate_boolean_mutual_exclusion(flags_dict):
+    flag_count = sum(bool(val) for val in flags_dict.values())
+    if flag_count == 1 or (not required and flag_count == 0):
+      return True
+    raise _exceptions.ValidationError(
+        '{} one of ({}) must be True.'.format(
+            'Exactly' if required else 'At most', ', '.join(flag_names)))
+
+  register_multi_flags_validator(
+      flag_names, validate_boolean_mutual_exclusion, flag_values=flag_values)
+
+
+def _add_validator(fv, validator_instance):
+  """Register new flags validator to be checked.
+
+  Args:
+    fv: flags.FlagValues, the FlagValues instance to add the validator.
+    validator_instance: validators.Validator, the validator to add.
+  Raises:
+    KeyError: Raised when validators work with a non-existing flag.
+  """
+  for flag_name in validator_instance.get_flags_names():
+    fv[flag_name].validators.append(validator_instance)

.venv/lib/python3.13/site-packages/absl/flags/_validators_classes.py

@@ -0,0 +1,172 @@
+# Copyright 2021 The Abseil Authors.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Defines *private* classes used for flag validators.
+
+Do NOT import this module. DO NOT use anything from this module. They are
+private APIs.
+"""
+
+from absl.flags import _exceptions
+
+
+class Validator:
+  """Base class for flags validators.
+
+  Users should NOT overload these classes, and use flags.Register...
+  methods instead.
+  """
+
+  # Used to assign each validator an unique insertion_index
+  validators_count = 0
+
+  def __init__(self, checker, message):
+    """Constructor to create all validators.
+
+    Args:
+      checker: function to verify the constraint.
+          Input of this method varies, see SingleFlagValidator and
+          multi_flags_validator for a detailed description.
+      message: str, error message to be shown to the user.
+    """
+    self.checker = checker
+    self.message = message
+    Validator.validators_count += 1
+    # Used to assert validators in the order they were registered.
+    self.insertion_index = Validator.validators_count
+
+  def verify(self, flag_values):
+    """Verifies that constraint is satisfied.
+
+    flags library calls this method to verify Validator's constraint.
+
+    Args:
+      flag_values: flags.FlagValues, the FlagValues instance to get flags from.
+    Raises:
+      Error: Raised if constraint is not satisfied.
+    """
+    param = self._get_input_to_checker_function(flag_values)
+    if not self.checker(param):
+      raise _exceptions.ValidationError(self.message)
+
+  def get_flags_names(self):
+    """Returns the names of the flags checked by this validator.
+
+    Returns:
+      [string], names of the flags.
+    """
+    raise NotImplementedError('This method should be overloaded')
+
+  def print_flags_with_values(self, flag_values):
+    raise NotImplementedError('This method should be overloaded')
+
+  def _get_input_to_checker_function(self, flag_values):
+    """Given flag values, returns the input to be given to checker.
+
+    Args:
+      flag_values: flags.FlagValues, containing all flags.
+    Returns:
+      The input to be given to checker. The return type depends on the specific
+      validator.
+    """
+    raise NotImplementedError('This method should be overloaded')
+
+
+class SingleFlagValidator(Validator):
+  """Validator behind register_validator() method.
+
+  Validates that a single flag passes its checker function. The checker function
+  takes the flag value and returns True (if value looks fine) or, if flag value
+  is not valid, either returns False or raises an Exception.
+  """
+
+  def __init__(self, flag_name, checker, message):
+    """Constructor.
+
+    Args:
+      flag_name: string, name of the flag.
+      checker: function to verify the validator.
+          input  - value of the corresponding flag (string, boolean, etc).
+          output - bool, True if validator constraint is satisfied.
+              If constraint is not satisfied, it should either return False or
+              raise flags.ValidationError(desired_error_message).
+      message: str, error message to be shown to the user if validator's
+          condition is not satisfied.
+    """
+    super().__init__(checker, message)
+    self.flag_name = flag_name
+
+  def get_flags_names(self):
+    return [self.flag_name]
+
+  def print_flags_with_values(self, flag_values):
+    return 'flag --%s=%s' % (self.flag_name, flag_values[self.flag_name].value)
+
+  def _get_input_to_checker_function(self, flag_values):
+    """Given flag values, returns the input to be given to checker.
+
+    Args:
+      flag_values: flags.FlagValues, the FlagValues instance to get flags from.
+    Returns:
+      object, the input to be given to checker.
+    """
+    return flag_values[self.flag_name].value
+
+
+class MultiFlagsValidator(Validator):
+  """Validator behind register_multi_flags_validator method.
+
+  Validates that flag values pass their common checker function. The checker
+  function takes flag values and returns True (if values look fine) or,
+  if values are not valid, either returns False or raises an Exception.
+  """
+
+  def __init__(self, flag_names, checker, message):
+    """Constructor.
+
+    Args:
+      flag_names: [str], containing names of the flags used by checker.
+      checker: function to verify the validator.
+          input  - dict, with keys() being flag_names, and value for each
+              key being the value of the corresponding flag (string, boolean,
+              etc).
+          output - bool, True if validator constraint is satisfied.
+              If constraint is not satisfied, it should either return False or
+              raise flags.ValidationError(desired_error_message).
+      message: str, error message to be shown to the user if validator's
+          condition is not satisfied
+    """
+    super().__init__(checker, message)
+    self.flag_names = flag_names
+
+  def _get_input_to_checker_function(self, flag_values):
+    """Given flag values, returns the input to be given to checker.
+
+    Args:
+      flag_values: flags.FlagValues, the FlagValues instance to get flags from.
+    Returns:
+      dict, with keys() being self.flag_names, and value for each key
+      being the value of the corresponding flag (string, boolean, etc).
+    """
+    return {key: flag_values[key].value for key in self.flag_names}
+
+  def print_flags_with_values(self, flag_values):
+    prefix = 'flags '
+    flags_with_values = []
+    for key in self.flag_names:
+      flags_with_values.append('%s=%s' % (key, flag_values[key].value))
+    return prefix + ', '.join(flags_with_values)
+
+  def get_flags_names(self):
+    return self.flag_names

.venv/lib/python3.13/site-packages/absl/flags/argparse_flags.py

@@ -0,0 +1,390 @@
+# Copyright 2018 The Abseil Authors.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""This module provides argparse integration with absl.flags.
+
+``argparse_flags.ArgumentParser`` is a drop-in replacement for
+:class:`argparse.ArgumentParser`. It takes care of collecting and defining absl
+flags in :mod:`argparse`.
+
+Here is a simple example::
+
+    # Assume the following absl.flags is defined in another module:
+    #
+    #     from absl import flags
+    #     flags.DEFINE_string('echo', None, 'The echo message.')
+    #
+    parser = argparse_flags.ArgumentParser(
+        description='A demo of absl.flags and argparse integration.')
+    parser.add_argument('--header', help='Header message to print.')
+
+    # The parser will also accept the absl flag `--echo`.
+    # The `header` value is available as `args.header` just like a regular
+    # argparse flag. The absl flag `--echo` continues to be available via
+    # `absl.flags.FLAGS` if you want to access it.
+    args = parser.parse_args()
+
+    # Example usages:
+    # ./program --echo='A message.' --header='A header'
+    # ./program --header 'A header' --echo 'A message.'
+
+
+Here is another example demonstrates subparsers::
+
+    parser = argparse_flags.ArgumentParser(description='A subcommands demo.')
+    parser.add_argument('--header', help='The header message to print.')
+
+    subparsers = parser.add_subparsers(help='The command to execute.')
+
+    roll_dice_parser = subparsers.add_parser(
+        'roll_dice', help='Roll a dice.',
+        # By default, absl flags can also be specified after the sub-command.
+        # To only allow them before sub-command, pass
+        # `inherited_absl_flags=None`.
+        inherited_absl_flags=None)
+    roll_dice_parser.add_argument('--num_faces', type=int, default=6)
+    roll_dice_parser.set_defaults(command=roll_dice)
+
+    shuffle_parser = subparsers.add_parser('shuffle', help='Shuffle inputs.')
+    shuffle_parser.add_argument(
+        'inputs', metavar='I', nargs='+', help='Inputs to shuffle.')
+    shuffle_parser.set_defaults(command=shuffle)
+
+    args = parser.parse_args(argv[1:])
+    args.command(args)
+
+    # Example usages:
+    # ./program --echo='A message.' roll_dice --num_faces=6
+    # ./program shuffle --echo='A message.' 1 2 3 4
+
+
+There are several differences between :mod:`absl.flags` and
+:mod:`~absl.flags.argparse_flags`:
+
+1. Flags defined with absl.flags are parsed differently when using the
+   argparse parser. Notably:
+
+   1) absl.flags allows both single-dash and double-dash for any flag, and
+      doesn't distinguish them; argparse_flags only allows double-dash for
+      flag's regular name, and single-dash for flag's ``short_name``.
+   2) Boolean flags in absl.flags can be specified with ``--bool``,
+      ``--nobool``, as well as ``--bool=true/false`` (though not recommended);
+      in argparse_flags, it only allows ``--bool``, ``--nobool``.
+
+2. Help related flag differences:
+
+   1) absl.flags does not define help flags, absl.app does that; argparse_flags
+      defines help flags unless passed with ``add_help=False``.
+   2) absl.app supports ``--helpxml``; argparse_flags does not.
+   3) argparse_flags supports ``-h``; absl.app does not.
+"""
+
+import argparse
+import sys
+
+from absl import flags
+
+
+_BUILT_IN_FLAGS = frozenset({
+    'help',
+    'helpshort',
+    'helpfull',
+    'helpxml',
+    'flagfile',
+    'undefok',
+})
+
+
+class ArgumentParser(argparse.ArgumentParser):
+  """Custom ArgumentParser class to support special absl flags."""
+
+  def __init__(self, **kwargs):
+    """Initializes ArgumentParser.
+
+    Args:
+      **kwargs: same as argparse.ArgumentParser, except:
+          1. It also accepts `inherited_absl_flags`: the absl flags to inherit.
+             The default is the global absl.flags.FLAGS instance. Pass None to
+             ignore absl flags.
+          2. The `prefix_chars` argument must be the default value '-'.
+
+    Raises:
+      ValueError: Raised when prefix_chars is not '-'.
+    """
+    prefix_chars = kwargs.get('prefix_chars', '-')
+    if prefix_chars != '-':
+      raise ValueError(
+          'argparse_flags.ArgumentParser only supports "-" as the prefix '
+          'character, found "{}".'.format(prefix_chars))
+
+    # Remove inherited_absl_flags before calling super.
+    self._inherited_absl_flags = kwargs.pop('inherited_absl_flags', flags.FLAGS)
+    # Now call super to initialize argparse.ArgumentParser before calling
+    # add_argument in _define_absl_flags.
+    super().__init__(**kwargs)
+
+    if self.add_help:
+      # -h and --help are defined in super.
+      # Also add the --helpshort and --helpfull flags.
+      self.add_argument(
+          # Action 'help' defines a similar flag to -h/--help.
+          '--helpshort', action='help',
+          default=argparse.SUPPRESS, help=argparse.SUPPRESS)
+      self.add_argument(
+          '--helpfull', action=_HelpFullAction,
+          default=argparse.SUPPRESS, help='show full help message and exit')
+
+    if self._inherited_absl_flags is not None:
+      self.add_argument(
+          '--undefok', default=argparse.SUPPRESS, help=argparse.SUPPRESS)
+      self._define_absl_flags(self._inherited_absl_flags)
+
+  def parse_known_args(self, args=None, namespace=None):
+    if args is None:
+      args = sys.argv[1:]
+    if self._inherited_absl_flags is not None:
+      # Handle --flagfile.
+      # Explicitly specify force_gnu=True, since argparse behaves like
+      # gnu_getopt: flags can be specified after positional arguments.
+      args = self._inherited_absl_flags.read_flags_from_files(
+          args, force_gnu=True)
+
+    undefok_missing = object()
+    undefok = getattr(namespace, 'undefok', undefok_missing)
+
+    namespace, args = super().parse_known_args(args, namespace)
+
+    # For Python <= 2.7.8: https://bugs.python.org/issue9351, a bug where
+    # sub-parsers don't preserve existing namespace attributes.
+    # Restore the undefok attribute if a sub-parser dropped it.
+    if undefok is not undefok_missing:
+      namespace.undefok = undefok
+
+    if self._inherited_absl_flags is not None:
+      # Handle --undefok. At this point, `args` only contains unknown flags,
+      # so it won't strip defined flags that are also specified with --undefok.
+      # For Python <= 2.7.8: https://bugs.python.org/issue9351, a bug where
+      # sub-parsers don't preserve existing namespace attributes. The undefok
+      # attribute might not exist because a subparser dropped it.
+      if hasattr(namespace, 'undefok'):
+        args = _strip_undefok_args(namespace.undefok, args)
+        # absl flags are not exposed in the Namespace object. See Namespace:
+        # https://docs.python.org/3/library/argparse.html#argparse.Namespace.
+        del namespace.undefok
+      self._inherited_absl_flags.mark_as_parsed()
+      try:
+        self._inherited_absl_flags.validate_all_flags()
+      except flags.IllegalFlagValueError as e:
+        self.error(str(e))
+
+    return namespace, args
+
+  def _define_absl_flags(self, absl_flags):
+    """Defines flags from absl_flags."""
+    key_flags = set(absl_flags.get_key_flags_for_module(sys.argv[0]))
+    for name in absl_flags:
+      if name in _BUILT_IN_FLAGS:
+        # Do not inherit built-in flags.
+        continue
+      flag_instance = absl_flags[name]
+      # Each flags with short_name appears in FLAGS twice, so only define
+      # when the dictionary key is equal to the regular name.
+      if name == flag_instance.name:
+        # Suppress the flag in the help short message if it's not a main
+        # module's key flag.
+        suppress = flag_instance not in key_flags
+        self._define_absl_flag(flag_instance, suppress)
+
+  def _define_absl_flag(self, flag_instance, suppress):
+    """Defines a flag from the flag_instance."""
+    flag_name = flag_instance.name
+    short_name = flag_instance.short_name
+    argument_names = ['--' + flag_name]
+    if short_name:
+      argument_names.insert(0, '-' + short_name)
+    if suppress:
+      helptext = argparse.SUPPRESS
+    else:
+      # argparse help string uses %-formatting. Escape the literal %'s.
+      helptext = flag_instance.help.replace('%', '%%')
+    if flag_instance.boolean:
+      # Only add the `no` form to the long name.
+      argument_names.append('--no' + flag_name)
+      self.add_argument(
+          *argument_names, action=_BooleanFlagAction, help=helptext,
+          metavar=flag_instance.name.upper(),
+          flag_instance=flag_instance)
+    else:
+      self.add_argument(
+          *argument_names, action=_FlagAction, help=helptext,
+          metavar=flag_instance.name.upper(),
+          flag_instance=flag_instance)
+
+
+class _FlagAction(argparse.Action):
+  """Action class for Abseil non-boolean flags."""
+
+  def __init__(
+      self,
+      option_strings,
+      dest,
+      help,  # pylint: disable=redefined-builtin
+      metavar,
+      flag_instance,
+      default=argparse.SUPPRESS):
+    """Initializes _FlagAction.
+
+    Args:
+      option_strings: See argparse.Action.
+      dest: Ignored. The flag is always defined with dest=argparse.SUPPRESS.
+      help: See argparse.Action.
+      metavar: See argparse.Action.
+      flag_instance: absl.flags.Flag, the absl flag instance.
+      default: Ignored. The flag always uses dest=argparse.SUPPRESS so it
+          doesn't affect the parsing result.
+    """
+    del dest
+    self._flag_instance = flag_instance
+    super().__init__(
+        option_strings=option_strings,
+        dest=argparse.SUPPRESS,
+        help=help,
+        metavar=metavar,
+    )
+
+  def __call__(self, parser, namespace, values, option_string=None):
+    """See https://docs.python.org/3/library/argparse.html#action-classes."""
+    self._flag_instance.parse(values)
+    self._flag_instance.using_default_value = False
+
+
+class _BooleanFlagAction(argparse.Action):
+  """Action class for Abseil boolean flags."""
+
+  def __init__(
+      self,
+      option_strings,
+      dest,
+      help,  # pylint: disable=redefined-builtin
+      metavar,
+      flag_instance,
+      default=argparse.SUPPRESS):
+    """Initializes _BooleanFlagAction.
+
+    Args:
+      option_strings: See argparse.Action.
+      dest: Ignored. The flag is always defined with dest=argparse.SUPPRESS.
+      help: See argparse.Action.
+      metavar: See argparse.Action.
+      flag_instance: absl.flags.Flag, the absl flag instance.
+      default: Ignored. The flag always uses dest=argparse.SUPPRESS so it
+          doesn't affect the parsing result.
+    """
+    del dest, default
+    self._flag_instance = flag_instance
+    flag_names = [self._flag_instance.name]
+    if self._flag_instance.short_name:
+      flag_names.append(self._flag_instance.short_name)
+    self._flag_names = frozenset(flag_names)
+    super().__init__(
+        option_strings=option_strings,
+        dest=argparse.SUPPRESS,
+        nargs=0,  # Does not accept values, only `--bool` or `--nobool`.
+        help=help,
+        metavar=metavar,
+    )
+
+  def __call__(self, parser, namespace, values, option_string=None):
+    """See https://docs.python.org/3/library/argparse.html#action-classes."""
+    if not isinstance(values, list) or values:
+      raise ValueError('values must be an empty list.')
+    if option_string.startswith('--'):
+      option = option_string[2:]
+    else:
+      option = option_string[1:]
+    if option in self._flag_names:
+      self._flag_instance.parse('true')
+    else:
+      if not option.startswith('no') or option[2:] not in self._flag_names:
+        raise ValueError('invalid option_string: ' + option_string)
+      self._flag_instance.parse('false')
+    self._flag_instance.using_default_value = False
+
+
+class _HelpFullAction(argparse.Action):
+  """Action class for --helpfull flag."""
+
+  def __init__(self, option_strings, dest, default, help):  # pylint: disable=redefined-builtin
+    """Initializes _HelpFullAction.
+
+    Args:
+      option_strings: See argparse.Action.
+      dest: Ignored. The flag is always defined with dest=argparse.SUPPRESS.
+      default: Ignored.
+      help: See argparse.Action.
+    """
+    del dest, default
+    super().__init__(
+        option_strings=option_strings,
+        dest=argparse.SUPPRESS,
+        default=argparse.SUPPRESS,
+        nargs=0,
+        help=help,
+    )
+
+  def __call__(self, parser, namespace, values, option_string=None):
+    """See https://docs.python.org/3/library/argparse.html#action-classes."""
+    # This only prints flags when help is not argparse.SUPPRESS.
+    # It includes user defined argparse flags, as well as main module's
+    # key absl flags. Other absl flags use argparse.SUPPRESS, so they aren't
+    # printed here.
+    parser.print_help()
+
+    absl_flags = parser._inherited_absl_flags  # pylint: disable=protected-access
+    if absl_flags is not None:
+      modules = sorted(absl_flags.flags_by_module_dict())
+      main_module = sys.argv[0]
+      if main_module in modules:
+        # The main module flags are already printed in parser.print_help().
+        modules.remove(main_module)
+      print(absl_flags._get_help_for_modules(  # pylint: disable=protected-access
+          modules, prefix='', include_special_flags=True))
+    parser.exit()
+
+
+def _strip_undefok_args(undefok, args):
+  """Returns a new list of args after removing flags in --undefok."""
+  if undefok:
+    undefok_names = {name.strip() for name in undefok.split(',')}
+    undefok_names |= {'no' + name for name in undefok_names}
+    # Remove undefok flags.
+    args = [arg for arg in args if not _is_undefok(arg, undefok_names)]
+  return args
+
+
+def _is_undefok(arg, undefok_names):
+  """Returns whether we can ignore arg based on a set of undefok flag names."""
+  if not arg.startswith('-'):
+    return False
+  if arg.startswith('--'):
+    arg_without_dash = arg[2:]
+  else:
+    arg_without_dash = arg[1:]
+  if '=' in arg_without_dash:
+    name, _ = arg_without_dash.split('=', 1)
+  else:
+    name = arg_without_dash
+  if name in undefok_names:
+    return True
+  return False

.venv/lib/python3.13/site-packages/absl/logging/__init__.py

@@ -0,0 +1,1335 @@
+# Copyright 2017 The Abseil Authors.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Abseil Python logging module implemented on top of standard logging.
+
+Simple usage::
+
+    from absl import logging
+
+    logging.info('Interesting Stuff')
+    logging.info('Interesting Stuff with Arguments: %d', 42)
+
+    logging.set_verbosity(logging.INFO)
+    logging.log(logging.DEBUG, 'This will *not* be printed')
+    logging.set_verbosity(logging.DEBUG)
+    logging.log(logging.DEBUG, 'This will be printed')
+
+    logging.warning('Worrying Stuff')
+    logging.error('Alarming Stuff')
+    logging.fatal('AAAAHHHHH!!!!')  # Process exits.
+
+Usage note: Do not pre-format the strings in your program code.
+Instead, let the logging module perform argument interpolation.
+This saves cycles because strings that don't need to be printed
+are never formatted.  Note that this module does not attempt to
+interpolate arguments when no arguments are given.  In other words::
+
+    logging.info('Interesting Stuff: %s')
+
+does not raise an exception because logging.info() has only one
+argument, the message string.
+
+"Lazy" evaluation for debugging
+-------------------------------
+
+If you do something like this::
+
+    logging.debug('Thing: %s', thing.ExpensiveOp())
+
+then the ExpensiveOp will be evaluated even if nothing
+is printed to the log. To avoid this, use the level_debug() function::
+
+  if logging.level_debug():
+    logging.debug('Thing: %s', thing.ExpensiveOp())
+
+Per file level logging is supported by logging.vlog() and
+logging.vlog_is_on(). For example::
+
+    if logging.vlog_is_on(2):
+      logging.vlog(2, very_expensive_debug_message())
+
+Notes on Unicode
+----------------
+
+The log output is encoded as UTF-8.  Don't pass data in other encodings in
+bytes() instances -- instead pass unicode string instances when you need to
+(for both the format string and arguments).
+
+Note on critical and fatal:
+Standard logging module defines fatal as an alias to critical, but it's not
+documented, and it does NOT actually terminate the program.
+This module only defines fatal but not critical, and it DOES terminate the
+program.
+
+The differences in behavior are historical and unfortunate.
+"""
+
+import collections
+from collections.abc import Mapping
+import getpass
+import inspect
+import io
+import itertools
+import logging
+import os
+import socket
+import struct
+import sys
+import tempfile
+import threading
+import time
+import timeit
+import traceback
+import warnings
+
+from absl import flags
+from absl.logging import converter
+
+# pylint: disable=g-import-not-at-top
+try:
+  from typing import NoReturn
+except ImportError:
+  pass
+
+# pylint: enable=g-import-not-at-top
+
+FLAGS = flags.FLAGS
+
+
+# Logging levels.
+FATAL = converter.ABSL_FATAL
+ERROR = converter.ABSL_ERROR
+WARNING = converter.ABSL_WARNING
+WARN = converter.ABSL_WARNING  # Deprecated name.
+INFO = converter.ABSL_INFO
+DEBUG = converter.ABSL_DEBUG
+
+# Regex to match/parse log line prefixes.
+ABSL_LOGGING_PREFIX_REGEX = (
+    r'^(?P<severity>[IWEF])'
+    r'(?P<month>\d\d)(?P<day>\d\d) '
+    r'(?P<hour>\d\d):(?P<minute>\d\d):(?P<second>\d\d)'
+    r'\.(?P<microsecond>\d\d\d\d\d\d) +'
+    r'(?P<thread_id>-?\d+) '
+    r'(?P<filename>[a-zA-Z<][\w._<>-]+):(?P<line>\d+)')
+
+
+# Mask to convert integer thread ids to unsigned quantities for logging purposes
+_THREAD_ID_MASK = 2 ** (struct.calcsize('L') * 8) - 1
+
+# Extra property set on the LogRecord created by ABSLLogger when its level is
+# CRITICAL/FATAL.
+_ABSL_LOG_FATAL = '_absl_log_fatal'
+# Extra prefix added to the log message when a non-absl logger logs a
+# CRITICAL/FATAL message.
+_CRITICAL_PREFIX = 'CRITICAL - '
+
+# Used by findCaller to skip callers from */logging/__init__.py.
+_LOGGING_FILE_PREFIX = os.path.join('logging', '__init__.')
+
+# The ABSL logger instance, initialized in _initialize().
+_absl_logger = None
+# The ABSL handler instance, initialized in _initialize().
+_absl_handler = None
+
+
+_CPP_NAME_TO_LEVELS = {
+    'debug': '0',  # Abseil C++ has no DEBUG level, mapping it to INFO here.
+    'info': '0',
+    'warning': '1',
+    'warn': '1',
+    'error': '2',
+    'fatal': '3'
+}
+
+_CPP_LEVEL_TO_NAMES = {
+    '0': 'info',
+    '1': 'warning',
+    '2': 'error',
+    '3': 'fatal',
+}
+
+
+class _VerbosityFlag(flags.Flag):
+  """Flag class for -v/--verbosity."""
+
+  def __init__(self, *args, **kwargs):
+    super().__init__(
+        flags.IntegerParser(), flags.ArgumentSerializer(), *args, **kwargs
+    )
+
+  @property
+  def value(self):
+    return self._value
+
+  @value.setter
+  def value(self, v):
+    self._value = v
+    self._update_logging_levels()
+
+  def _update_logging_levels(self):
+    """Updates absl logging levels to the current verbosity.
+
+    Visibility: module-private
+    """
+    if not _absl_logger:
+      return
+
+    if self._value <= converter.ABSL_DEBUG:
+      standard_verbosity = converter.absl_to_standard(self._value)
+    else:
+      # --verbosity is set to higher than 1 for vlog.
+      standard_verbosity = logging.DEBUG - (self._value - 1)
+
+    # Also update root level when absl_handler is used.
+    if _absl_handler in logging.root.handlers:
+      # Make absl logger inherit from the root logger. absl logger might have
+      # a non-NOTSET value if logging.set_verbosity() is called at import time.
+      _absl_logger.setLevel(logging.NOTSET)
+      logging.root.setLevel(standard_verbosity)
+    else:
+      _absl_logger.setLevel(standard_verbosity)
+
+
+class _LoggerLevelsFlag(flags.Flag):
+  """Flag class for --logger_levels."""
+
+  def __init__(self, *args, **kwargs):
+    super().__init__(
+        _LoggerLevelsParser(), _LoggerLevelsSerializer(), *args, **kwargs
+    )
+
+  @property
+  def value(self):
+    # For lack of an immutable type, be defensive and return a copy.
+    # Modifications to the dict aren't supported and won't have any affect.
+    # While Py3 could use MappingProxyType, that isn't deepcopy friendly, so
+    # just return a copy.
+    return self._value.copy()
+
+  @value.setter
+  def value(self, v):
+    self._value = {} if v is None else v
+    self._update_logger_levels()
+
+  def _update_logger_levels(self):
+    # Visibility: module-private.
+    # This is called by absl.app.run() during initialization.
+    for name, level in self._value.items():
+      logging.getLogger(name).setLevel(level)
+
+
+class _LoggerLevelsParser(flags.ArgumentParser):
+  """Parser for --logger_levels flag."""
+
+  def parse(self, value):
+    if isinstance(value, Mapping):
+      return value
+
+    pairs = [pair.strip() for pair in value.split(',') if pair.strip()]
+
+    # Preserve the order so that serialization is deterministic.
+    levels = collections.OrderedDict()
+    for name_level in pairs:
+      name, level = name_level.split(':', 1)
+      name = name.strip()
+      level = level.strip()
+      levels[name] = level
+    return levels
+
+
+class _LoggerLevelsSerializer:
+  """Serializer for --logger_levels flag."""
+
+  def serialize(self, value):
+    if isinstance(value, str):
+      return value
+    return ','.join(f'{name}:{level}' for name, level in value.items())
+
+
+class _StderrthresholdFlag(flags.Flag):
+  """Flag class for --stderrthreshold."""
+
+  def __init__(self, *args, **kwargs):
+    super().__init__(
+        flags.ArgumentParser(), flags.ArgumentSerializer(), *args, **kwargs
+    )
+
+  @property
+  def value(self):
+    return self._value
+
+  @value.setter
+  def value(self, v):
+    if v in _CPP_LEVEL_TO_NAMES:
+      # --stderrthreshold also accepts numeric strings whose values are
+      # Abseil C++ log levels.
+      cpp_value = int(v)
+      v = _CPP_LEVEL_TO_NAMES[v]  # Normalize to strings.
+    elif v.lower() in _CPP_NAME_TO_LEVELS:
+      v = v.lower()
+      if v == 'warn':
+        v = 'warning'  # Use 'warning' as the canonical name.
+      cpp_value = int(_CPP_NAME_TO_LEVELS[v])
+    else:
+      raise ValueError(
+          '--stderrthreshold must be one of (case-insensitive) '
+          "'debug', 'info', 'warning', 'error', 'fatal', "
+          "or '0', '1', '2', '3', not '%s'" % v)
+
+    self._value = v
+
+
+LOGTOSTDERR = flags.DEFINE_boolean(
+    'logtostderr',
+    False,
+    'Should only log to stderr?',
+    allow_override_cpp=True,
+)
+ALSOLOGTOSTDERR = flags.DEFINE_boolean(
+    'alsologtostderr',
+    False,
+    'also log to stderr?',
+    allow_override_cpp=True,
+)
+LOG_DIR = flags.DEFINE_string(
+    'log_dir',
+    os.getenv('TEST_TMPDIR', ''),
+    'directory to write logfiles into',
+    allow_override_cpp=True,
+)
+VERBOSITY = flags.DEFINE_flag(
+    _VerbosityFlag(
+        'verbosity',
+        -1,
+        (
+            'Logging verbosity level. Messages logged at this level or lower'
+            ' will be included. Set to 1 for debug logging. If the flag was not'
+            ' set or supplied, the value will be changed from the default of -1'
+            ' (warning) to 0 (info) after flags are parsed.'
+        ),
+        short_name='v',
+        allow_hide_cpp=True,
+    )
+)
+LOGGER_LEVELS = flags.DEFINE_flag(
+    _LoggerLevelsFlag(
+        'logger_levels',
+        {},
+        (
+            'Specify log level of loggers. The format is a CSV list of '
+            '`name:level`. Where `name` is the logger name used with '
+            '`logging.getLogger()`, and `level` is a level name  (INFO, DEBUG, '
+            'etc). e.g. `myapp.foo:INFO,other.logger:DEBUG`'
+        ),
+    )
+)
+STDERRTHRESHOLD = flags.DEFINE_flag(
+    _StderrthresholdFlag(
+        'stderrthreshold',
+        'fatal',
+        (
+            'log messages at this level, or more severe, to stderr in '
+            'addition to the logfile.  Possible values are '
+            "'debug', 'info', 'warning', 'error', and 'fatal'.  "
+            'Obsoletes --alsologtostderr. Using --alsologtostderr '
+            'cancels the effect of this flag. Please also note that '
+            'this flag is subject to --verbosity and requires logfile '
+            'not be stderr.'
+        ),
+        allow_hide_cpp=True,
+    )
+)
+SHOWPREFIXFORINFO = flags.DEFINE_boolean(
+    'showprefixforinfo',
+    True,
+    (
+        'If False, do not prepend prefix to info messages '
+        "when it's logged to stderr, "
+        '--verbosity is set to INFO level, '
+        'and python logging is used.'
+    ),
+)
+
+
+def get_verbosity():
+  """Returns the logging verbosity."""
+  return FLAGS['verbosity'].value
+
+
+def set_verbosity(v):
+  """Sets the logging verbosity.
+
+  Causes all messages of level <= v to be logged,
+  and all messages of level > v to be silently discarded.
+
+  Args:
+    v: int|str, the verbosity level as an integer or string. Legal string values
+        are those that can be coerced to an integer as well as case-insensitive
+        'debug', 'info', 'warning', 'error', and 'fatal'.
+  """
+  try:
+    new_level = int(v)
+  except ValueError:
+    new_level = converter.ABSL_NAMES[v.upper()]
+  FLAGS.verbosity = new_level
+
+
+def set_stderrthreshold(s):
+  """Sets the stderr threshold to the value passed in.
+
+  Args:
+    s: str|int, valid strings values are case-insensitive 'debug',
+        'info', 'warning', 'error', and 'fatal'; valid integer values are
+        logging.DEBUG|INFO|WARNING|ERROR|FATAL.
+
+  Raises:
+      ValueError: Raised when s is an invalid value.
+  """
+  if s in converter.ABSL_LEVELS:
+    FLAGS.stderrthreshold = converter.ABSL_LEVELS[s]
+  elif isinstance(s, str) and s.upper() in converter.ABSL_NAMES:
+    FLAGS.stderrthreshold = s
+  else:
+    raise ValueError(
+        'set_stderrthreshold only accepts integer absl logging level '
+        'from -3 to 1, or case-insensitive string values '
+        "'debug', 'info', 'warning', 'error', and 'fatal'. "
+        'But found "{}" ({}).'.format(s, type(s)))
+
+
+def fatal(msg, *args, **kwargs):
+  # type: (Any, Any, Any) -> NoReturn
+  """Logs a fatal message."""
+  log(FATAL, msg, *args, **kwargs)
+
+
+def error(msg, *args, **kwargs):
+  """Logs an error message."""
+  log(ERROR, msg, *args, **kwargs)
+
+
+def warning(msg, *args, **kwargs):
+  """Logs a warning message."""
+  log(WARNING, msg, *args, **kwargs)
+
+
+def warn(msg, *args, **kwargs):
+  """Deprecated, use 'warning' instead."""
+  warnings.warn("The 'warn' function is deprecated, use 'warning' instead",
+                DeprecationWarning, 2)
+  log(WARNING, msg, *args, **kwargs)
+
+
+def info(msg, *args, **kwargs):
+  """Logs an info message."""
+  log(INFO, msg, *args, **kwargs)
+
+
+def debug(msg, *args, **kwargs):
+  """Logs a debug message."""
+  log(DEBUG, msg, *args, **kwargs)
+
+
+def exception(msg, *args, exc_info=True, **kwargs):
+  """Logs an exception, with traceback and message."""
+  error(msg, *args, exc_info=exc_info, **kwargs)
+
+
+def _fast_stack_trace():
+  """A fast stack trace that gets us the minimal information we need.
+
+  Compared to using `get_absl_logger().findCaller(stack_info=True)`, this
+  function is ~100x faster.
+
+  Returns:
+    A tuple of tuples of (filename, line_number, last_instruction_offset).
+  """
+  cur_stack = inspect.currentframe()
+  if cur_stack is None or cur_stack.f_back is None:
+    return tuple()
+  # We drop the first frame, which is this function itself.
+  cur_stack = cur_stack.f_back
+  call_stack = []
+  while cur_stack.f_back:
+    cur_stack = cur_stack.f_back
+    call_stack.append(
+        (cur_stack.f_code.co_filename, cur_stack.f_lineno, cur_stack.f_lasti)
+    )
+  return tuple(call_stack)
+
+
+# Counter to keep track of number of log entries per token.
+_log_counter_per_token = {}
+
+
+def _get_next_log_count_per_token(token):
+  """Wrapper for _log_counter_per_token. Thread-safe.
+
+  Args:
+    token: The token for which to look up the count.
+
+  Returns:
+    The number of times this function has been called with
+    *token* as an argument (starting at 0).
+  """
+  # Can't use a defaultdict because defaultdict isn't atomic, whereas
+  # setdefault is.
+  return next(_log_counter_per_token.setdefault(token, itertools.count()))
+
+
+def log_every_n(level, msg, n, *args, use_call_stack=False, **kwargs):
+  """Logs ``msg % args`` at level 'level' once per 'n' times.
+
+  Logs the 1st call, (N+1)st call, (2N+1)st call,  etc.
+  Not threadsafe.
+
+  Args:
+    level: int, the absl logging level at which to log.
+    msg: str, the message to be logged.
+    n: int, the number of times this should be called before it is logged.
+    *args: The args to be substituted into the msg.
+    use_call_stack: bool, whether to include the call stack when counting the
+      number of times the message is logged.
+    **kwargs: May contain exc_info to add exception traceback to message.
+  """
+  caller_info = get_absl_logger().findCaller()
+  if use_call_stack:
+    # To reduce storage costs, we hash the call stack.
+    caller_info = (*caller_info[0:3], hash(_fast_stack_trace()))
+  count = _get_next_log_count_per_token(caller_info)
+  log_if(level, msg, not (count % n), *args, **kwargs)
+
+
+# Keeps track of the last log time of the given token.
+# Note: must be a dict since set/get is atomic in CPython.
+# Note: entries are never released as their number is expected to be low.
+_log_timer_per_token = {}
+
+
+def _seconds_have_elapsed(token, num_seconds):
+  """Tests if 'num_seconds' have passed since 'token' was requested.
+
+  Not strictly thread-safe - may log with the wrong frequency if called
+  concurrently from multiple threads. Accuracy depends on resolution of
+  'timeit.default_timer()'.
+
+  Always returns True on the first call for a given 'token'.
+
+  Args:
+    token: The token for which to look up the count.
+    num_seconds: The number of seconds to test for.
+
+  Returns:
+    Whether it has been >= 'num_seconds' since 'token' was last requested.
+  """
+  now = timeit.default_timer()
+  then = _log_timer_per_token.get(token, None)
+  if then is None or (now - then) >= num_seconds:
+    _log_timer_per_token[token] = now
+    return True
+  else:
+    return False
+
+
+def log_every_n_seconds(
+    level, msg, n_seconds, *args, use_call_stack=False, **kwargs
+):
+  """Logs ``msg % args`` at level ``level`` iff ``n_seconds`` elapsed since last call.
+
+  Logs the first call, logs subsequent calls if 'n' seconds have elapsed since
+  the last logging call from the same call site (file + line). Not thread-safe.
+
+  Args:
+    level: int, the absl logging level at which to log.
+    msg: str, the message to be logged.
+    n_seconds: float or int, seconds which should elapse before logging again.
+    *args: The args to be substituted into the msg.
+    use_call_stack: bool, whether to include the call stack when counting the
+      number of times the message is logged.
+    **kwargs: May contain exc_info to add exception traceback to message.
+  """
+  caller_info = get_absl_logger().findCaller()
+  if use_call_stack:
+    # To reduce storage costs, we hash the call stack.
+    caller_info = (*caller_info[0:3], hash(_fast_stack_trace()))
+  should_log = _seconds_have_elapsed(caller_info, n_seconds)
+  log_if(level, msg, should_log, *args, **kwargs)
+
+
+def log_first_n(level, msg, n, *args, use_call_stack=False, **kwargs):
+  """Logs ``msg % args`` at level ``level`` only first ``n`` times.
+
+  Not threadsafe.
+
+  Args:
+    level: int, the absl logging level at which to log.
+    msg: str, the message to be logged.
+    n: int, the maximal number of times the message is logged.
+    *args: The args to be substituted into the msg.
+    use_call_stack: bool, whether to include the call stack when counting the
+      number of times the message is logged.
+    **kwargs: May contain exc_info to add exception traceback to message.
+  """
+  caller_info = get_absl_logger().findCaller()
+  if use_call_stack:
+    # To reduce storage costs, we hash the call stack.
+    caller_info = (*caller_info[0:3], hash(_fast_stack_trace()))
+  count = _get_next_log_count_per_token(caller_info)
+  log_if(level, msg, count < n, *args, **kwargs)
+
+
+def log_if(level, msg, condition, *args, **kwargs):
+  """Logs ``msg % args`` at level ``level`` only if condition is fulfilled."""
+  if condition:
+    log(level, msg, *args, **kwargs)
+
+
+def log(level, msg, *args, **kwargs):
+  """Logs ``msg % args`` at absl logging level ``level``.
+
+  If no args are given just print msg, ignoring any interpolation specifiers.
+
+  Args:
+    level: int, the absl logging level at which to log the message
+        (logging.DEBUG|INFO|WARNING|ERROR|FATAL). While some C++ verbose logging
+        level constants are also supported, callers should prefer explicit
+        logging.vlog() calls for such purpose.
+
+    msg: str, the message to be logged.
+    *args: The args to be substituted into the msg.
+    **kwargs: May contain exc_info to add exception traceback to message.
+  """
+  if level > converter.ABSL_DEBUG:
+    # Even though this function supports level that is greater than 1, users
+    # should use logging.vlog instead for such cases.
+    # Treat this as vlog, 1 is equivalent to DEBUG.
+    standard_level = converter.STANDARD_DEBUG - (level - 1)
+  else:
+    if level < converter.ABSL_FATAL:
+      level = converter.ABSL_FATAL
+    standard_level = converter.absl_to_standard(level)
+
+  # Match standard logging's behavior. Before use_absl_handler() and
+  # logging is configured, there is no handler attached on _absl_logger nor
+  # logging.root. So logs go no where.
+  if not logging.root.handlers:
+    logging.basicConfig()
+
+  _absl_logger.log(standard_level, msg, *args, **kwargs)
+
+
+def vlog(level, msg, *args, **kwargs):
+  """Log ``msg % args`` at C++ vlog level ``level``.
+
+  Args:
+    level: int, the C++ verbose logging level at which to log the message,
+        e.g. 1, 2, 3, 4... While absl level constants are also supported,
+        callers should prefer logging.log|debug|info|... calls for such purpose.
+    msg: str, the message to be logged.
+    *args: The args to be substituted into the msg.
+    **kwargs: May contain exc_info to add exception traceback to message.
+  """
+  log(level, msg, *args, **kwargs)
+
+
+def vlog_is_on(level):
+  """Checks if vlog is enabled for the given level in caller's source file.
+
+  Args:
+    level: int, the C++ verbose logging level at which to log the message,
+        e.g. 1, 2, 3, 4... While absl level constants are also supported,
+        callers should prefer level_debug|level_info|... calls for
+        checking those.
+
+  Returns:
+    True if logging is turned on for that level.
+  """
+
+  if level > converter.ABSL_DEBUG:
+    # Even though this function supports level that is greater than 1, users
+    # should use logging.vlog instead for such cases.
+    # Treat this as vlog, 1 is equivalent to DEBUG.
+    standard_level = converter.STANDARD_DEBUG - (level - 1)
+  else:
+    if level < converter.ABSL_FATAL:
+      level = converter.ABSL_FATAL
+    standard_level = converter.absl_to_standard(level)
+  return _absl_logger.isEnabledFor(standard_level)
+
+
+def flush():
+  """Flushes all log files."""
+  get_absl_handler().flush()
+
+
+def level_debug():
+  """Returns True if debug logging is turned on."""
+  return get_verbosity() >= DEBUG
+
+
+def level_info():
+  """Returns True if info logging is turned on."""
+  return get_verbosity() >= INFO
+
+
+def level_warning():
+  """Returns True if warning logging is turned on."""
+  return get_verbosity() >= WARNING
+
+
+level_warn = level_warning  # Deprecated function.
+
+
+def level_error():
+  """Returns True if error logging is turned on."""
+  return get_verbosity() >= ERROR
+
+
+def get_log_file_name(level=INFO):
+  """Returns the name of the log file.
+
+  For Python logging, only one file is used and level is ignored. And it returns
+  empty string if it logs to stderr/stdout or the log stream has no `name`
+  attribute.
+
+  Args:
+    level: int, the absl.logging level.
+
+  Raises:
+    ValueError: Raised when `level` has an invalid value.
+  """
+  if level not in converter.ABSL_LEVELS:
+    raise ValueError(f'Invalid absl.logging level {level}')
+  stream = get_absl_handler().python_handler.stream
+  if (stream == sys.stderr or stream == sys.stdout or
+      not hasattr(stream, 'name')):
+    return ''
+  else:
+    return stream.name
+
+
+def find_log_dir_and_names(program_name=None, log_dir=None):
+  """Computes the directory and filename prefix for log file.
+
+  Args:
+    program_name: str|None, the filename part of the path to the program that is
+      running without its extension.  e.g: if your program is called
+      ``usr/bin/foobar.py`` this method should probably be called with
+      ``program_name='foobar`` However, this is just a convention, you can pass
+      in any string you want, and it will be used as part of the log filename.
+      If you don't pass in anything, the default behavior is as described in the
+      example.  In python standard logging mode, the program_name will be
+      prepended with ``py_`` if it is the ``program_name`` argument is omitted.
+    log_dir: str|None, the desired log directory.
+
+  Returns:
+    (log_dir, file_prefix, symlink_prefix)
+
+  Raises:
+    FileNotFoundError: raised when it cannot find a log directory.
+  """
+  if not program_name:
+    # Strip the extension (foobar.par becomes foobar, and
+    # fubar.py becomes fubar). We do this so that the log
+    # file names are similar to C++ log file names.
+    program_name = os.path.splitext(os.path.basename(sys.argv[0]))[0]
+
+    # Prepend py_ to files so that python code gets a unique file, and
+    # so that C++ libraries do not try to write to the same log files as us.
+    program_name = 'py_%s' % program_name
+
+  actual_log_dir = find_log_dir(log_dir=log_dir)
+
+  try:
+    username = getpass.getuser()
+  except KeyError:
+    # This can happen, e.g. when running under docker w/o passwd file.
+    if hasattr(os, 'getuid'):
+      # Windows doesn't have os.getuid
+      username = str(os.getuid())
+    else:
+      username = 'unknown'
+  hostname = socket.gethostname()
+  file_prefix = '%s.%s.%s.log' % (program_name, hostname, username)
+
+  return actual_log_dir, file_prefix, program_name
+
+
+def find_log_dir(log_dir=None):
+  """Returns the most suitable directory to put log files into.
+
+  Args:
+    log_dir: str|None, if specified, the logfile(s) will be created in that
+      directory.  Otherwise if the --log_dir command-line flag is provided, the
+      logfile will be created in that directory.  Otherwise the logfile will be
+      created in a standard location.
+
+  Raises:
+    FileNotFoundError: raised when it cannot find a log directory.
+  """
+  # Get a list of possible log dirs (will try to use them in order).
+  # NOTE: Google's internal implementation has a special handling for Google
+  # machines, which uses a list of directories. Hence the following uses `dirs`
+  # instead of a single directory.
+  if log_dir:
+    # log_dir was explicitly specified as an arg, so use it and it alone.
+    dirs = [log_dir]
+  elif FLAGS['log_dir'].value:
+    # log_dir flag was provided, so use it and it alone (this mimics the
+    # behavior of the same flag in logging.cc).
+    dirs = [FLAGS['log_dir'].value]
+  else:
+    dirs = [tempfile.gettempdir()]
+
+  # Find the first usable log dir.
+  for d in dirs:
+    if os.path.isdir(d) and os.access(d, os.W_OK):
+      return d
+  raise FileNotFoundError(
+      "Can't find a writable directory for logs, tried %s" % dirs)
+
+
+def get_absl_log_prefix(record):
+  """Returns the absl log prefix for the log record.
+
+  Args:
+    record: logging.LogRecord, the record to get prefix for.
+  """
+  created_tuple = time.localtime(record.created)
+  created_microsecond = int(record.created % 1.0 * 1e6)
+
+  critical_prefix = ''
+  level = record.levelno
+  if _is_non_absl_fatal_record(record):
+    # When the level is FATAL, but not logged from absl, lower the level so
+    # it's treated as ERROR.
+    level = logging.ERROR
+    critical_prefix = _CRITICAL_PREFIX
+  severity = converter.get_initial_for_level(level)
+
+  return '%c%02d%02d %02d:%02d:%02d.%06d %5d %s:%d] %s' % (
+      severity,
+      created_tuple.tm_mon,
+      created_tuple.tm_mday,
+      created_tuple.tm_hour,
+      created_tuple.tm_min,
+      created_tuple.tm_sec,
+      created_microsecond,
+      _get_thread_id(),
+      record.filename,
+      record.lineno,
+      critical_prefix)
+
+
+def skip_log_prefix(func):
+  """Skips reporting the prefix of a given function or name by :class:`~absl.logging.ABSLLogger`.
+
+  This is a convenience wrapper function / decorator for
+  :meth:`~absl.logging.ABSLLogger.register_frame_to_skip`.
+
+  If a callable function is provided, only that function will be skipped.
+  If a function name is provided, all functions with the same name in the
+  file that this is called in will be skipped.
+
+  This can be used as a decorator of the intended function to be skipped.
+
+  Args:
+    func: Callable function or its name as a string.
+
+  Returns:
+    func (the input, unchanged).
+
+  Raises:
+    ValueError: The input is callable but does not have a function code object.
+    TypeError: The input is neither callable nor a string.
+  """
+  if callable(func):
+    func_code = getattr(func, '__code__', None)
+    if func_code is None:
+      raise ValueError('Input callable does not have a function code object.')
+    file_name = func_code.co_filename
+    func_name = func_code.co_name
+    func_lineno = func_code.co_firstlineno
+  elif isinstance(func, str):
+    file_name = get_absl_logger().findCaller()[0]
+    func_name = func
+    func_lineno = None
+  else:
+    raise TypeError('Input is neither callable nor a string.')
+  ABSLLogger.register_frame_to_skip(file_name, func_name, func_lineno)
+  return func
+
+
+def _is_non_absl_fatal_record(log_record):
+  return (log_record.levelno >= logging.FATAL and
+          not log_record.__dict__.get(_ABSL_LOG_FATAL, False))
+
+
+def _is_absl_fatal_record(log_record):
+  return (log_record.levelno >= logging.FATAL and
+          log_record.__dict__.get(_ABSL_LOG_FATAL, False))
+
+
+# Indicates if we still need to warn about pre-init logs going to stderr.
+_warn_preinit_stderr = True
+
+
+class PythonHandler(logging.StreamHandler):
+  """The handler class used by Abseil Python logging implementation."""
+
+  def __init__(self, stream=None, formatter=None):
+    super().__init__(stream)
+    self.setFormatter(formatter or PythonFormatter())
+
+  def start_logging_to_file(self, program_name=None, log_dir=None):
+    """Starts logging messages to files instead of standard error."""
+    FLAGS.logtostderr = False
+
+    actual_log_dir, file_prefix, symlink_prefix = find_log_dir_and_names(
+        program_name=program_name, log_dir=log_dir)
+
+    basename = '%s.INFO.%s.%d' % (
+        file_prefix,
+        time.strftime('%Y%m%d-%H%M%S', time.localtime(time.time())),
+        os.getpid())
+    filename = os.path.join(actual_log_dir, basename)
+
+    self.stream = open(filename, 'a', encoding='utf-8')
+
+    # os.symlink is not available on Windows Python 2.
+    if getattr(os, 'symlink', None):
+      # Create a symlink to the log file with a canonical name.
+      symlink = os.path.join(actual_log_dir, symlink_prefix + '.INFO')
+      try:
+        if os.path.islink(symlink):
+          os.unlink(symlink)
+        os.symlink(os.path.basename(filename), symlink)
+      except OSError:
+        # If it fails, we're sad but it's no error.  Commonly, this
+        # fails because the symlink was created by another user and so
+        # we can't modify it
+        pass
+
+  def use_absl_log_file(self, program_name=None, log_dir=None):
+    """Conditionally logs to files, based on --logtostderr."""
+    if FLAGS['logtostderr'].value:
+      self.stream = sys.stderr
+    else:
+      self.start_logging_to_file(program_name=program_name, log_dir=log_dir)
+
+  def flush(self):
+    """Flushes all log files."""
+    self.acquire()
+    try:
+      if self.stream and hasattr(self.stream, 'flush'):
+        self.stream.flush()
+    except (OSError, ValueError):
+      # A ValueError is thrown if we try to flush a closed file.
+      pass
+    finally:
+      self.release()
+
+  def _log_to_stderr(self, record):
+    """Emits the record to stderr.
+
+    This temporarily sets the handler stream to stderr, calls
+    StreamHandler.emit, then reverts the stream back.
+
+    Args:
+      record: logging.LogRecord, the record to log.
+    """
+    # emit() is protected by a lock in logging.Handler, so we don't need to
+    # protect here again.
+    old_stream = self.stream
+    self.stream = sys.stderr
+    try:
+      super().emit(record)
+    finally:
+      self.stream = old_stream
+
+  def emit(self, record):
+    """Prints a record out to some streams.
+
+    1. If ``FLAGS.logtostderr`` is set, it will print to ``sys.stderr`` ONLY.
+    2. If ``FLAGS.alsologtostderr`` is set, it will print to ``sys.stderr``.
+    3. If ``FLAGS.logtostderr`` is not set, it will log to the stream
+        associated with the current thread.
+
+    Args:
+      record: :class:`logging.LogRecord`, the record to emit.
+    """
+    # People occasionally call logging functions at import time before
+    # our flags may have even been defined yet, let alone even parsed, as we
+    # rely on the C++ side to define some flags for us and app init to
+    # deal with parsing.  Match the C++ library behavior of notify and emit
+    # such messages to stderr.  It encourages people to clean-up and does
+    # not hide the message.
+    level = record.levelno
+    if not FLAGS.is_parsed():  # Also implies "before flag has been defined".
+      global _warn_preinit_stderr
+      if _warn_preinit_stderr:
+        sys.stderr.write(
+            'WARNING: Logging before flag parsing goes to stderr.\n')
+        _warn_preinit_stderr = False
+      self._log_to_stderr(record)
+    elif FLAGS['logtostderr'].value:
+      self._log_to_stderr(record)
+    else:
+      super().emit(record)
+      stderr_threshold = converter.string_to_standard(
+          FLAGS['stderrthreshold'].value)
+      if ((FLAGS['alsologtostderr'].value or level >= stderr_threshold) and
+          self.stream != sys.stderr):
+        self._log_to_stderr(record)
+    # Die when the record is created from ABSLLogger and level is FATAL.
+    if _is_absl_fatal_record(record):
+      self.flush()  # Flush the log before dying.
+
+      # In threaded python, sys.exit() from a non-main thread only
+      # exits the thread in question.
+      os.abort()
+
+  def close(self):
+    """Closes the stream to which we are writing."""
+    self.acquire()
+    try:
+      self.flush()
+      try:
+        # Do not close the stream if it's sys.stderr|stdout. They may be
+        # redirected or overridden to files, which should be managed by users
+        # explicitly.
+        user_managed = sys.stderr, sys.stdout, sys.__stderr__, sys.__stdout__
+        if self.stream not in user_managed and (
+            not hasattr(self.stream, 'isatty') or not self.stream.isatty()):
+          self.stream.close()
+      except ValueError:
+        # A ValueError is thrown if we try to run isatty() on a closed file.
+        pass
+      super().close()
+    finally:
+      self.release()
+
+
+class ABSLHandler(logging.Handler):
+  """Abseil Python logging module's log handler."""
+
+  def __init__(self, python_logging_formatter):
+    super().__init__()
+
+    self._python_handler = PythonHandler(formatter=python_logging_formatter)
+    self.activate_python_handler()
+
+  def format(self, record):
+    return self._current_handler.format(record)
+
+  def setFormatter(self, fmt):
+    self._current_handler.setFormatter(fmt)
+
+  def emit(self, record):
+    self._current_handler.emit(record)
+
+  def flush(self):
+    self._current_handler.flush()
+
+  def close(self):
+    super().close()
+    self._current_handler.close()
+
+  def handle(self, record):
+    rv = self.filter(record)
+    if rv:
+      return self._current_handler.handle(record)
+    return rv
+
+  @property
+  def python_handler(self):
+    return self._python_handler
+
+  def activate_python_handler(self):
+    """Uses the Python logging handler as the current logging handler."""
+    self._current_handler = self._python_handler
+
+  def use_absl_log_file(self, program_name=None, log_dir=None):
+    self._current_handler.use_absl_log_file(program_name, log_dir)
+
+  def start_logging_to_file(self, program_name=None, log_dir=None):
+    self._current_handler.start_logging_to_file(program_name, log_dir)
+
+
+class PythonFormatter(logging.Formatter):
+  """Formatter class used by :class:`~absl.logging.PythonHandler`."""
+
+  def format(self, record):
+    """Appends the message from the record to the results of the prefix.
+
+    Args:
+      record: logging.LogRecord, the record to be formatted.
+
+    Returns:
+      The formatted string representing the record.
+    """
+    if (not FLAGS['showprefixforinfo'].value and
+        FLAGS['verbosity'].value == converter.ABSL_INFO and
+        record.levelno == logging.INFO and
+        _absl_handler.python_handler.stream == sys.stderr):
+      prefix = ''
+    else:
+      prefix = get_absl_log_prefix(record)
+    return prefix + super().format(record)
+
+
+class ABSLLogger(logging.getLoggerClass()):
+  """A logger that will create LogRecords while skipping some stack frames.
+
+  This class maintains an internal list of filenames and method names
+  for use when determining who called the currently executing stack
+  frame.  Any method names from specific source files are skipped when
+  walking backwards through the stack.
+
+  Client code should use the register_frame_to_skip method to let the
+  ABSLLogger know which method from which file should be
+  excluded from the walk backwards through the stack.
+  """
+  _frames_to_skip = set()
+
+  def findCaller(self, stack_info=False, stacklevel=1):
+    """Finds the frame of the calling method on the stack.
+
+    This method skips any frames registered with the
+    ABSLLogger and any methods from this file, and whatever
+    method is currently being used to generate the prefix for the log
+    line.  Then it returns the file name, line number, and method name
+    of the calling method.  An optional fourth item may be returned,
+    callers who only need things from the first three are advised to
+    always slice or index the result rather than using direct unpacking
+    assignment.
+
+    Args:
+      stack_info: bool, when True, include the stack trace as a fourth item
+        returned.  On Python 3 there are always four items returned - the fourth
+        will be None when this is False.  On Python 2 the stdlib base class API
+        only returns three items.  We do the same when this new parameter is
+        unspecified or False for compatibility.
+      stacklevel: int, if greater than 1, that number of frames will be skipped.
+
+    Returns:
+      (filename, lineno, methodname[, sinfo]) of the calling method.
+    """
+    f_to_skip = ABSLLogger._frames_to_skip
+    # Use sys._getframe(2) instead of logging.currentframe(), it's slightly
+    # faster because there is one less frame to traverse.
+    frame = sys._getframe(2)  # pylint: disable=protected-access
+    frame_to_return = None
+
+    while frame:
+      code = frame.f_code
+      if (_LOGGING_FILE_PREFIX not in code.co_filename and
+          (code.co_filename, code.co_name,
+           code.co_firstlineno) not in f_to_skip and
+          (code.co_filename, code.co_name) not in f_to_skip):
+        frame_to_return = frame
+        stacklevel -= 1
+        if stacklevel <= 0:
+          break
+      frame = frame.f_back
+
+    if frame_to_return is not None:
+      sinfo = None
+      if stack_info:
+        out = io.StringIO()
+        out.write('Stack (most recent call last):\n')
+        traceback.print_stack(frame, file=out)
+        sinfo = out.getvalue().rstrip('\n')
+      return (
+          frame_to_return.f_code.co_filename,
+          frame_to_return.f_lineno,
+          frame_to_return.f_code.co_name,
+          sinfo,
+      )
+
+    return None
+
+  def critical(self, msg, *args, **kwargs):
+    """Logs ``msg % args`` with severity ``CRITICAL``."""
+    self.log(logging.CRITICAL, msg, *args, **kwargs)
+
+  def fatal(self, msg, *args, **kwargs):
+    """Logs ``msg % args`` with severity ``FATAL``."""
+    self.log(logging.FATAL, msg, *args, **kwargs)
+
+  def error(self, msg, *args, **kwargs):
+    """Logs ``msg % args`` with severity ``ERROR``."""
+    self.log(logging.ERROR, msg, *args, **kwargs)
+
+  def warn(self, msg, *args, **kwargs):
+    """Logs ``msg % args`` with severity ``WARN``."""
+    warnings.warn("The 'warn' method is deprecated, use 'warning' instead",
+                  DeprecationWarning, 2)
+    self.log(logging.WARN, msg, *args, **kwargs)
+
+  def warning(self, msg, *args, **kwargs):
+    """Logs ``msg % args`` with severity ``WARNING``."""
+    self.log(logging.WARNING, msg, *args, **kwargs)
+
+  def info(self, msg, *args, **kwargs):
+    """Logs ``msg % args`` with severity ``INFO``."""
+    self.log(logging.INFO, msg, *args, **kwargs)
+
+  def debug(self, msg, *args, **kwargs):
+    """Logs ``msg % args`` with severity ``DEBUG``."""
+    self.log(logging.DEBUG, msg, *args, **kwargs)
+
+  def log(self, level, msg, *args, **kwargs):
+    """Logs a message at a certain level substituting in the supplied arguments.
+
+    This method behaves differently in python and c++ modes.
+
+    Args:
+      level: int, the standard logging level at which to log the message.
+      msg: str, the text of the message to log.
+      *args: The arguments to substitute in the message.
+      **kwargs: The keyword arguments to substitute in the message.
+    """
+    if level >= logging.FATAL:
+      # Add property to the LogRecord created by this logger.
+      # This will be used by the ABSLHandler to determine whether it should
+      # treat CRITICAL/FATAL logs as really FATAL.
+      extra = kwargs.setdefault('extra', {})
+      extra[_ABSL_LOG_FATAL] = True
+    super().log(level, msg, *args, **kwargs)
+
+  def handle(self, record):
+    """Calls handlers without checking ``Logger.disabled``.
+
+    Non-root loggers are set to disabled after setup with :func:`logging.config`
+    if it's not explicitly specified. Historically, absl logging will not be
+    disabled by that. To maintaining this behavior, this function skips
+    checking the ``Logger.disabled`` bit.
+
+    This logger can still be disabled by adding a filter that filters out
+    everything.
+
+    Args:
+      record: logging.LogRecord, the record to handle.
+    """
+    if self.filter(record):
+      self.callHandlers(record)
+
+  @classmethod
+  def register_frame_to_skip(cls, file_name, function_name, line_number=None):
+    """Registers a function name to skip when walking the stack.
+
+    The :class:`~absl.logging.ABSLLogger` sometimes skips method calls on the
+    stack to make the log messages meaningful in their appropriate context.
+    This method registers a function from a particular file as one
+    which should be skipped.
+
+    Args:
+      file_name: str, the name of the file that contains the function.
+      function_name: str, the name of the function to skip.
+      line_number: int, if provided, only the function with this starting line
+          number will be skipped. Otherwise, all functions with the same name
+          in the file will be skipped.
+    """
+    if line_number is not None:
+      cls._frames_to_skip.add((file_name, function_name, line_number))
+    else:
+      cls._frames_to_skip.add((file_name, function_name))
+
+
+def _get_thread_id():
+  """Gets id of current thread, suitable for logging as an unsigned quantity.
+
+  If pywrapbase is linked, returns GetTID() for the thread ID to be
+  consistent with C++ logging.  Otherwise, returns the numeric thread id.
+  The quantities are made unsigned by masking with 2*sys.maxint + 1.
+
+  Returns:
+    Thread ID unique to this process (unsigned)
+  """
+  thread_id = threading.get_ident()
+  return thread_id & _THREAD_ID_MASK
+
+
+def get_absl_logger():
+  """Returns the absl logger instance."""
+  assert _absl_logger is not None
+  return _absl_logger
+
+
+def get_absl_handler():
+  """Returns the absl handler instance."""
+  assert _absl_handler is not None
+  return _absl_handler
+
+
+def use_python_logging(quiet=False):
+  """Uses the python implementation of the logging code.
+
+  Args:
+    quiet: No logging message about switching logging type.
+  """
+  get_absl_handler().activate_python_handler()
+  if not quiet:
+    info('Restoring pure python logging')
+
+
+_attempted_to_remove_stderr_stream_handlers = False
+
+
+def use_absl_handler():
+  """Uses the ABSL logging handler for logging.
+
+  This method is called in :func:`app.run()<absl.app.run>` so the absl handler
+  is used in absl apps.
+  """
+  global _attempted_to_remove_stderr_stream_handlers
+  if not _attempted_to_remove_stderr_stream_handlers:
+    # The absl handler logs to stderr by default. To prevent double logging to
+    # stderr, the following code tries its best to remove other handlers that
+    # emit to stderr. Those handlers are most commonly added when
+    # logging.info/debug is called before calling use_absl_handler().
+    handlers = [
+        h for h in logging.root.handlers
+        if isinstance(h, logging.StreamHandler) and h.stream == sys.stderr]
+    for h in handlers:
+      logging.root.removeHandler(h)
+    _attempted_to_remove_stderr_stream_handlers = True
+
+  absl_handler = get_absl_handler()
+  if absl_handler not in logging.root.handlers:
+    logging.root.addHandler(absl_handler)
+    FLAGS['verbosity']._update_logging_levels()  # pylint: disable=protected-access
+    FLAGS['logger_levels']._update_logger_levels()  # pylint: disable=protected-access
+
+
+def _initialize():
+  """Initializes loggers and handlers."""
+  global _absl_logger, _absl_handler
+
+  if _absl_logger:
+    return
+
+  original_logger_class = logging.getLoggerClass()
+  logging.setLoggerClass(ABSLLogger)
+  _absl_logger = logging.getLogger('absl')
+  logging.setLoggerClass(original_logger_class)
+
+  python_logging_formatter = PythonFormatter()
+  _absl_handler = ABSLHandler(python_logging_formatter)
+
+
+_initialize()

.venv/lib/python3.13/site-packages/absl/logging/__init__.pyi

@@ -0,0 +1,278 @@
+# Copyright 2017 The Abseil Authors.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+from collections.abc import Callable
+import logging
+from typing import Any, NoReturn, TypeVar
+
+from absl import flags
+
+# Logging levels.
+FATAL: int
+ERROR: int
+WARNING: int
+WARN: int  # Deprecated name.
+INFO: int
+DEBUG: int
+
+ABSL_LOGGING_PREFIX_REGEX: str
+
+LOGTOSTDERR: flags.FlagHolder[bool]
+ALSOLOGTOSTDERR: flags.FlagHolder[bool]
+LOG_DIR: flags.FlagHolder[str]
+VERBOSITY: flags.FlagHolder[int]
+LOGGER_LEVELS: flags.FlagHolder[dict[str, str]]
+STDERRTHRESHOLD: flags.FlagHolder[str]
+SHOWPREFIXFORINFO: flags.FlagHolder[bool]
+
+def get_verbosity() -> int:
+  ...
+
+def set_verbosity(v: int | str) -> None:
+  ...
+
+def set_stderrthreshold(s: int | str) -> None:
+  ...
+
+# TODO(b/277607978): Provide actual args+kwargs shadowing stdlib's logging functions.
+def fatal(msg: Any, *args: Any, **kwargs: Any) -> NoReturn:
+  ...
+
+def error(msg: Any, *args: Any, **kwargs: Any) -> None:
+  ...
+
+def warning(msg: Any, *args: Any, **kwargs: Any) -> None:
+  ...
+
+def warn(msg: Any, *args: Any, **kwargs: Any) -> None:
+  ...
+
+def info(msg: Any, *args: Any, **kwargs: Any) -> None:
+  ...
+
+def debug(msg: Any, *args: Any, **kwargs: Any) -> None:
+  ...
+
+def exception(msg: Any, *args: Any, **kwargs: Any) -> None:
+  ...
+
+def log_every_n(
+    level: int,
+    msg: Any,
+    n: int,
+    *args: Any,
+    use_call_stack: bool = ...,
+    **kwargs: Any,
+) -> None:
+  ...
+
+def log_every_n_seconds(
+    level: int,
+    msg: Any,
+    n_seconds: float,
+    *args: Any,
+    use_call_stack: bool = ...,
+    **kwargs: Any,
+) -> None:
+  ...
+
+def log_first_n(
+    level: int,
+    msg: Any,
+    n: int,
+    *args: Any,
+    use_call_stack: bool = ...,
+    **kwargs: Any,
+) -> None:
+  ...
+
+def log_if(level: int,
+  msg: Any,
+  condition: Any,
+  *args: Any,
+  **kwargs: Any,
+) -> None:
+  ...
+
+def log(level: int, msg: Any, *args: Any, **kwargs: Any) -> None:
+  ...
+
+def vlog(level: int, msg: Any, *args: Any, **kwargs: Any) -> None:
+  ...
+
+def vlog_is_on(level: int) -> bool:
+  ...
+
+def flush() -> None:
+  ...
+
+def level_debug() -> bool:
+  ...
+
+def level_info() -> bool:
+  ...
+
+def level_warning() -> bool:
+  ...
+
+level_warn = level_warning  # Deprecated function.
+
+def level_error() -> bool:
+  ...
+
+def get_log_file_name(level: int = ...) -> str:
+  ...
+
+def find_log_dir_and_names(
+    program_name: str | None = ..., log_dir: str | None = ...
+) -> tuple[str, str, str]:
+  ...
+
+def find_log_dir(log_dir: str | None = ...) -> str:
+  ...
+
+def get_absl_log_prefix(record: logging.LogRecord) -> str:
+  ...
+
+_SkipLogT = TypeVar('_SkipLogT', str, Callable[..., Any])
+
+def skip_log_prefix(func: _SkipLogT) -> _SkipLogT:
+  ...
+
+_StreamT = TypeVar('_StreamT')
+
+class PythonHandler(logging.StreamHandler[_StreamT]):  # type: ignore[type-var]
+
+  def __init__(
+      self,
+      stream: _StreamT | None = ...,
+      formatter: logging.Formatter | None = ...,
+  ) -> None:
+    ...
+
+  def start_logging_to_file(
+      self, program_name: str | None = ..., log_dir: str | None = ...
+  ) -> None:
+    ...
+
+  def use_absl_log_file(
+      self, program_name: str | None = ..., log_dir: str | None = ...
+  ) -> None:
+    ...
+
+  def flush(self) -> None:
+    ...
+
+  def emit(self, record: logging.LogRecord) -> None:
+    ...
+
+  def close(self) -> None:
+    ...
+
+class ABSLHandler(logging.Handler):
+
+  def __init__(self, python_logging_formatter: PythonFormatter) -> None:
+    ...
+
+  def format(self, record: logging.LogRecord) -> str:
+    ...
+
+  def setFormatter(self, fmt) -> None:
+    ...
+
+  def emit(self, record: logging.LogRecord) -> None:
+    ...
+
+  def flush(self) -> None:
+    ...
+
+  def close(self) -> None:
+    ...
+
+  def handle(self, record: logging.LogRecord) -> bool:
+    ...
+
+  @property
+  def python_handler(self) -> PythonHandler:
+    ...
+
+  def activate_python_handler(self) -> None:
+    ...
+
+  def use_absl_log_file(
+      self, program_name: str | None = ..., log_dir: str | None = ...
+  ) -> None:
+    ...
+
+  def start_logging_to_file(self, program_name=None, log_dir=None) -> None:
+    ...
+
+class PythonFormatter(logging.Formatter):
+
+  def format(self, record: logging.LogRecord) -> str:
+    ...
+
+class ABSLLogger(logging.Logger):
+
+  def findCaller(
+      self, stack_info: bool = ..., stacklevel: int = ...
+  ) -> tuple[str, int, str, str | None]:
+    ...
+
+  def critical(self, msg: Any, *args: Any, **kwargs: Any) -> None:
+    ...
+
+  def fatal(self, msg: Any, *args: Any, **kwargs: Any) -> NoReturn:  # type: ignore[override]
+    ...
+
+  def error(self, msg: Any, *args: Any, **kwargs: Any) -> None:
+    ...
+
+  def warn(self, msg: Any, *args: Any, **kwargs: Any) -> None:
+    ...
+
+  def warning(self, msg: Any, *args: Any, **kwargs: Any) -> None:
+    ...
+
+  def info(self, msg: Any, *args: Any, **kwargs: Any) -> None:
+    ...
+
+  def debug(self, msg: Any, *args: Any, **kwargs: Any) -> None:
+    ...
+
+  def log(self, level: int, msg: Any, *args: Any, **kwargs: Any) -> None:
+    ...
+
+  def handle(self, record: logging.LogRecord) -> None:
+    ...
+
+  @classmethod
+  def register_frame_to_skip(
+      cls, file_name: str, function_name: str, line_number: int | None = ...
+  ) -> None:
+    ...
+
+# NOTE: Returns None before _initialize called but shouldn't occur after import.
+def get_absl_logger() -> ABSLLogger:
+  ...
+
+# NOTE: Returns None before _initialize called but shouldn't occur after import.
+def get_absl_handler() -> ABSLHandler:
+  ...
+
+def use_python_logging(quiet: bool = ...) -> None:
+  ...
+
+def use_absl_handler() -> None:
+  ...

.venv/lib/python3.13/site-packages/absl/logging/converter.py

@@ -0,0 +1,214 @@
+# Copyright 2017 The Abseil Authors.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Module to convert log levels between Abseil Python, C++, and Python standard.
+
+This converter has to convert (best effort) between three different
+logging level schemes:
+
+  * **cpp**: The C++ logging level scheme used in Abseil C++.
+  * **absl**: The absl.logging level scheme used in Abseil Python.
+  * **standard**: The python standard library logging level scheme.
+
+Here is a handy ascii chart for easy mental mapping::
+
+    LEVEL    | cpp |  absl  | standard |
+    ---------+-----+--------+----------+
+    DEBUG    |  0  |    1   |    10    |
+    INFO     |  0  |    0   |    20    |
+    WARNING  |  1  |   -1   |    30    |
+    ERROR    |  2  |   -2   |    40    |
+    CRITICAL |  3  |   -3   |    50    |
+    FATAL    |  3  |   -3   |    50    |
+
+Note: standard logging ``CRITICAL`` is mapped to absl/cpp ``FATAL``.
+However, only ``CRITICAL`` logs from the absl logger (or absl.logging.fatal)
+will terminate the program. ``CRITICAL`` logs from non-absl loggers are treated
+as error logs with a message prefix ``"CRITICAL - "``.
+
+Converting from standard to absl or cpp is a lossy conversion.
+Converting back to standard will lose granularity.  For this reason,
+users should always try to convert to standard, the richest
+representation, before manipulating the levels, and then only to cpp
+or absl if those level schemes are absolutely necessary.
+"""
+
+import logging
+
+STANDARD_CRITICAL = logging.CRITICAL
+STANDARD_ERROR = logging.ERROR
+STANDARD_WARNING = logging.WARNING
+STANDARD_INFO = logging.INFO
+STANDARD_DEBUG = logging.DEBUG
+
+# These levels are also used to define the constants
+# FATAL, ERROR, WARNING, INFO, and DEBUG in the
+# absl.logging module.
+ABSL_FATAL = -3
+ABSL_ERROR = -2
+ABSL_WARNING = -1
+ABSL_WARN = -1  # Deprecated name.
+ABSL_INFO = 0
+ABSL_DEBUG = 1
+
+ABSL_LEVELS = {ABSL_FATAL: 'FATAL',
+               ABSL_ERROR: 'ERROR',
+               ABSL_WARNING: 'WARNING',
+               ABSL_INFO: 'INFO',
+               ABSL_DEBUG: 'DEBUG'}
+
+# Inverts the ABSL_LEVELS dictionary
+ABSL_NAMES = {'FATAL': ABSL_FATAL,
+              'ERROR': ABSL_ERROR,
+              'WARNING': ABSL_WARNING,
+              'WARN': ABSL_WARNING,  # Deprecated name.
+              'INFO': ABSL_INFO,
+              'DEBUG': ABSL_DEBUG}
+
+ABSL_TO_STANDARD = {ABSL_FATAL: STANDARD_CRITICAL,
+                    ABSL_ERROR: STANDARD_ERROR,
+                    ABSL_WARNING: STANDARD_WARNING,
+                    ABSL_INFO: STANDARD_INFO,
+                    ABSL_DEBUG: STANDARD_DEBUG}
+
+# Inverts the ABSL_TO_STANDARD
+STANDARD_TO_ABSL = {v: k for (k, v) in ABSL_TO_STANDARD.items()}
+
+
+def get_initial_for_level(level):
+  """Gets the initial that should start the log line for the given level.
+
+  It returns:
+
+  * ``'I'`` when: ``level < STANDARD_WARNING``.
+  * ``'W'`` when: ``STANDARD_WARNING <= level < STANDARD_ERROR``.
+  * ``'E'`` when: ``STANDARD_ERROR <= level < STANDARD_CRITICAL``.
+  * ``'F'`` when: ``level >= STANDARD_CRITICAL``.
+
+  Args:
+    level: int, a Python standard logging level.
+
+  Returns:
+    The first initial as it would be logged by the C++ logging module.
+  """
+  if level < STANDARD_WARNING:
+    return 'I'
+  elif level < STANDARD_ERROR:
+    return 'W'
+  elif level < STANDARD_CRITICAL:
+    return 'E'
+  else:
+    return 'F'
+
+
+def absl_to_cpp(level):
+  """Converts an absl log level to a cpp log level.
+
+  Args:
+    level: int, an absl.logging level.
+
+  Raises:
+    TypeError: Raised when level is not an integer.
+
+  Returns:
+    The corresponding integer level for use in Abseil C++.
+  """
+  if not isinstance(level, int):
+    raise TypeError(f'Expect an int level, found {type(level)}')
+  if level >= 0:
+    # C++ log levels must be >= 0
+    return 0
+  else:
+    return -level
+
+
+def absl_to_standard(level):
+  """Converts an integer level from the absl value to the standard value.
+
+  Args:
+    level: int, an absl.logging level.
+
+  Raises:
+    TypeError: Raised when level is not an integer.
+
+  Returns:
+    The corresponding integer level for use in standard logging.
+  """
+  if not isinstance(level, int):
+    raise TypeError(f'Expect an int level, found {type(level)}')
+  if level < ABSL_FATAL:
+    level = ABSL_FATAL
+  if level <= ABSL_DEBUG:
+    return ABSL_TO_STANDARD[level]
+  # Maps to vlog levels.
+  return STANDARD_DEBUG - level + 1
+
+
+def string_to_standard(level):
+  """Converts a string level to standard logging level value.
+
+  Args:
+    level: str, case-insensitive ``'debug'``, ``'info'``, ``'warning'``,
+        ``'error'``, ``'fatal'``.
+
+  Returns:
+    The corresponding integer level for use in standard logging.
+  """
+  return absl_to_standard(ABSL_NAMES.get(level.upper()))
+
+
+def standard_to_absl(level):
+  """Converts an integer level from the standard value to the absl value.
+
+  Args:
+    level: int, a Python standard logging level.
+
+  Raises:
+    TypeError: Raised when level is not an integer.
+
+  Returns:
+    The corresponding integer level for use in absl logging.
+  """
+  if not isinstance(level, int):
+    raise TypeError(f'Expect an int level, found {type(level)}')
+  if level < 0:
+    level = 0
+  if level < STANDARD_DEBUG:
+    # Maps to vlog levels.
+    return STANDARD_DEBUG - level + 1
+  elif level < STANDARD_INFO:
+    return ABSL_DEBUG
+  elif level < STANDARD_WARNING:
+    return ABSL_INFO
+  elif level < STANDARD_ERROR:
+    return ABSL_WARNING
+  elif level < STANDARD_CRITICAL:
+    return ABSL_ERROR
+  else:
+    return ABSL_FATAL
+
+
+def standard_to_cpp(level):
+  """Converts an integer level from the standard value to the cpp value.
+
+  Args:
+    level: int, a Python standard logging level.
+
+  Raises:
+    TypeError: Raised when level is not an integer.
+
+  Returns:
+    The corresponding integer level for use in cpp logging.
+  """
+  return absl_to_cpp(standard_to_absl(level))

.venv/lib/python3.13/site-packages/absl/testing/__init__.py

@@ -0,0 +1,13 @@
+# Copyright 2017 The Abseil Authors.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.

.venv/lib/python3.13/site-packages/absl/testing/_bazelize_command.py

@@ -0,0 +1,68 @@
+# Copyright 2017 The Abseil Authors.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Internal helper for running tests on Windows Bazel."""
+
+import os
+
+from absl import flags
+
+FLAGS = flags.FLAGS
+
+
+def get_executable_path(py_binary_name):
+  """Returns the executable path of a py_binary.
+
+  This returns the executable path of a py_binary that is in another Bazel
+  target's data dependencies.
+
+  On Linux/macOS, the path and __file__ has the same root directory.
+  On Windows, bazel builds an .exe file and we need to use the MANIFEST file
+  the location the actual binary.
+
+  Args:
+    py_binary_name: string, the name of a py_binary that is in another Bazel
+        target's data dependencies.
+
+  Raises:
+    RuntimeError: Raised when it cannot locate the executable path.
+  """
+
+  if os.name == 'nt':
+    py_binary_name += '.exe'
+    manifest_file = os.path.join(FLAGS.test_srcdir, 'MANIFEST')
+    workspace_name = os.environ['TEST_WORKSPACE']
+    manifest_entry = f'{workspace_name}/{py_binary_name}'
+    with open(manifest_file) as manifest_fd:
+      for line in manifest_fd:
+        tokens = line.strip().split(' ')
+        if len(tokens) != 2:
+          continue
+        if manifest_entry == tokens[0]:
+          return tokens[1]
+    raise RuntimeError(
+        'Cannot locate executable path for {}, MANIFEST file: {}.'.format(
+            py_binary_name, manifest_file))
+  else:
+    # NOTE: __file__ may be .py or .pyc, depending on how the module was
+    # loaded and executed.
+    path = __file__
+
+    # Use the package name to find the root directory: every dot is
+    # a directory, plus one for ourselves.
+    for _ in range(__name__.count('.') + 1):
+      path = os.path.dirname(path)
+
+    root_directory = path
+    return os.path.join(root_directory, py_binary_name)

.venv/lib/python3.13/site-packages/absl/testing/_pretty_print_reporter.py

@@ -0,0 +1,92 @@
+# Copyright 2018 The Abseil Authors.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""TestResult implementing default output for test execution status."""
+
+import unittest
+
+
+class TextTestResult(unittest.TextTestResult):
+  """TestResult class that provides the default text result formatting."""
+
+  def __init__(self, stream, descriptions, verbosity):
+    # Disable the verbose per-test output from the superclass, since it would
+    # conflict with our customized output.
+    super().__init__(stream, descriptions, 0)
+    self._per_test_output = verbosity > 0
+
+  def _print_status(self, tag, test, reason=None):
+    if self._per_test_output:
+      test_id = test.id()
+      if test_id.startswith('__main__.'):
+        test_id = test_id[len('__main__.'):]
+      if reason:
+        print('[%s] %s - %s' % (tag, test_id, reason), file=self.stream)
+      else:
+        print('[%s] %s' % (tag, test_id), file=self.stream)
+      self.stream.flush()
+
+  def startTest(self, test):
+    super().startTest(test)
+    self._print_status(' RUN      ', test)
+
+  def addSuccess(self, test):
+    super().addSuccess(test)
+    self._print_status('       OK ', test)
+
+  def addError(self, test, err):
+    super().addError(test, err)
+    self._print_status('  FAILED  ', test)
+
+  def addFailure(self, test, err):
+    super().addFailure(test, err)
+    self._print_status('  FAILED  ', test)
+
+  def addSkip(self, test, reason):
+    super().addSkip(test, reason)
+    self._print_status('  SKIPPED ', test, reason)
+
+  def addExpectedFailure(self, test, err):
+    super().addExpectedFailure(test, err)
+    self._print_status('       OK ', test)
+
+  def addUnexpectedSuccess(self, test):
+    super().addUnexpectedSuccess(test)
+    self._print_status('  FAILED  ', test)
+
+
+class TextTestRunner(unittest.TextTestRunner):
+  """A test runner that produces formatted text results."""
+
+  _TEST_RESULT_CLASS = TextTestResult
+
+  # Set this to true at the class or instance level to run tests using a
+  # debug-friendly method (e.g, one that doesn't catch exceptions and interacts
+  # better with debuggers).
+  # Usually this is set using --pdb_post_mortem.
+  run_for_debugging = False
+
+  def run(self, test) -> unittest.TextTestResult:
+    if self.run_for_debugging:
+      return self._run_debug(test)
+    else:
+      return super().run(test)
+
+  def _run_debug(self, test) -> unittest.TextTestResult:
+    test.debug()
+    # Return an empty result to indicate success.
+    return self._makeResult()
+
+  def _makeResult(self):
+    return TextTestResult(self.stream, self.descriptions, self.verbosity)

.venv/lib/python3.13/site-packages/absl/testing/flagsaver.py

@@ -0,0 +1,403 @@
+# Copyright 2017 The Abseil Authors.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Decorator and context manager for saving and restoring flag values.
+
+There are many ways to save and restore.  Always use the most convenient method
+for a given use case.
+
+Here are examples of each method.  They all call ``do_stuff()`` while
+``FLAGS.someflag`` is temporarily set to ``'foo'``::
+
+    from absl.testing import flagsaver
+
+    # Use a decorator which can optionally override flags via arguments.
+    @flagsaver.flagsaver(someflag='foo')
+    def some_func():
+      do_stuff()
+
+    # Use a decorator which can optionally override flags with flagholders.
+    @flagsaver.flagsaver((module.FOO_FLAG, 'foo'), (other_mod.BAR_FLAG, 23))
+    def some_func():
+      do_stuff()
+
+    # Use a decorator which does not override flags itself.
+    @flagsaver.flagsaver
+    def some_func():
+      FLAGS.someflag = 'foo'
+      do_stuff()
+
+    # Use a context manager which can optionally override flags via arguments.
+    with flagsaver.flagsaver(someflag='foo'):
+      do_stuff()
+
+    # Save and restore the flag values yourself.
+    saved_flag_values = flagsaver.save_flag_values()
+    try:
+      FLAGS.someflag = 'foo'
+      do_stuff()
+    finally:
+      flagsaver.restore_flag_values(saved_flag_values)
+
+    # Use the parsing version to emulate users providing the flags.
+    # Note that all flags must be provided as strings (unparsed).
+    @flagsaver.as_parsed(some_int_flag='123')
+    def some_func():
+      # Because the flag was parsed it is considered "present".
+      assert FLAGS.some_int_flag.present
+      do_stuff()
+
+    # flagsaver.as_parsed() can also be used as a context manager just like
+    # flagsaver.flagsaver()
+    with flagsaver.as_parsed(some_int_flag='123'):
+      do_stuff()
+
+    # The flagsaver.as_parsed() interface also supports FlagHolder objects.
+    @flagsaver.as_parsed((module.FOO_FLAG, 'foo'), (other_mod.BAR_FLAG, '23'))
+    def some_func():
+      do_stuff()
+
+    # Using as_parsed with a multi_X flag requires a sequence of strings.
+    @flagsaver.as_parsed(some_multi_int_flag=['123', '456'])
+    def some_func():
+      assert FLAGS.some_multi_int_flag.present
+      do_stuff()
+
+    # If a flag name includes non-identifier characters it can be specified like
+    # so:
+    @flagsaver.as_parsed(**{'i-like-dashes': 'true'})
+    def some_func():
+      do_stuff()
+
+We save and restore a shallow copy of each Flag object's ``__dict__`` attribute.
+This preserves all attributes of the flag, such as whether or not it was
+overridden from its default value.
+
+WARNING: Currently a flag that is saved and then deleted cannot be restored.  An
+exception will be raised.  However if you *add* a flag after saving flag values,
+and then restore flag values, the added flag will be deleted with no errors.
+"""
+
+from collections.abc import Callable, Mapping, Sequence
+import functools
+import inspect
+from typing import Any, TypeVar, overload
+
+from absl import flags
+
+FLAGS = flags.FLAGS
+
+
+# The type of pre/post wrapped functions.
+_CallableT = TypeVar('_CallableT', bound=Callable)
+
+
+@overload
+def flagsaver(func: _CallableT) -> _CallableT:
+  ...
+
+
+@overload
+def flagsaver(
+    *args: tuple[flags.FlagHolder, Any], **kwargs: Any
+) -> '_FlagOverrider':
+  ...
+
+
+def flagsaver(*args, **kwargs):
+  """The main flagsaver interface. See module doc for usage."""
+  return _construct_overrider(_FlagOverrider, *args, **kwargs)  # type: ignore[bad-return-type]
+
+
+@overload
+def as_parsed(
+    *args: tuple[flags.FlagHolder, str | Sequence[str]],
+    **kwargs: str | Sequence[str],
+) -> '_ParsingFlagOverrider':
+  ...
+
+
+@overload
+def as_parsed(func: _CallableT) -> _CallableT:
+  ...
+
+
+def as_parsed(*args, **kwargs):
+  """Overrides flags by parsing strings, saves flag state similar to flagsaver.
+
+  This function can be used as either a decorator or context manager similar to
+  flagsaver.flagsaver(). However, where flagsaver.flagsaver() directly sets the
+  flags to new values, this function will parse the provided arguments as if
+  they were provided on the command line. Among other things, this will cause
+  `FLAGS['flag_name'].present == True`.
+
+  A note on unparsed input: For many flag types, the unparsed version will be
+  a single string. However for multi_x (multi_string, multi_integer, multi_enum)
+  the unparsed version will be a Sequence of strings.
+
+  Args:
+    *args: Tuples of FlagHolders and their unparsed value.
+    **kwargs: The keyword args are flag names, and the values are unparsed
+      values.
+
+  Returns:
+    _ParsingFlagOverrider that serves as a context manager or decorator. Will
+    save previous flag state and parse new flags, then on cleanup it will
+    restore the previous flag state.
+  """
+  return _construct_overrider(_ParsingFlagOverrider, *args, **kwargs)
+
+
+# NOTE: the order of these overload declarations matters. The type checker will
+# pick the first match which could be incorrect.
+@overload
+def _construct_overrider(
+    flag_overrider_cls: type['_ParsingFlagOverrider'],
+    *args: tuple[flags.FlagHolder, str | Sequence[str]],
+    **kwargs: str | Sequence[str],
+) -> '_ParsingFlagOverrider':
+  ...
+
+
+@overload
+def _construct_overrider(
+    flag_overrider_cls: type['_FlagOverrider'], func: _CallableT
+) -> _CallableT:
+  ...
+
+
+@overload
+def _construct_overrider(
+    flag_overrider_cls: type['_FlagOverrider'],
+    *args: tuple[flags.FlagHolder, Any],
+    **kwargs: Any,
+) -> '_FlagOverrider':
+  ...
+
+
+def _construct_overrider(flag_overrider_cls, *args, **kwargs):
+  """Handles the args/kwargs returning an instance of flag_overrider_cls.
+
+  If flag_overrider_cls is _FlagOverrider then values should be native python
+  types matching the python types. Otherwise if flag_overrider_cls is
+  _ParsingFlagOverrider the values should be strings or sequences of strings.
+
+  Args:
+    flag_overrider_cls: The class that will do the overriding.
+    *args: Tuples of FlagHolder and the new flag value.
+    **kwargs: Keword args mapping flag name to new flag value.
+
+  Returns:
+    A _FlagOverrider to be used as a decorator or context manager.
+  """
+  if not args:
+    return flag_overrider_cls(**kwargs)
+  # args can be [func] if used as `@flagsaver` instead of `@flagsaver(...)`
+  if len(args) == 1 and callable(args[0]):
+    if kwargs:
+      raise ValueError(
+          "It's invalid to specify both positional and keyword parameters.")
+    func = args[0]
+    if inspect.isclass(func):
+      raise TypeError('@flagsaver.flagsaver cannot be applied to a class.')
+    return _wrap(flag_overrider_cls, func, {})
+  # args can be a list of (FlagHolder, value) pairs.
+  # In which case they augment any specified kwargs.
+  for arg in args:
+    if not isinstance(arg, tuple) or len(arg) != 2:
+      raise ValueError('Expected (FlagHolder, value) pair, found %r' % (arg,))
+    holder, value = arg
+    if not isinstance(holder, flags.FlagHolder):
+      raise ValueError('Expected (FlagHolder, value) pair, found %r' % (arg,))
+    if holder.name in kwargs:
+      raise ValueError('Cannot set --%s multiple times' % holder.name)
+    kwargs[holder.name] = value
+  return flag_overrider_cls(**kwargs)
+
+
+def save_flag_values(
+    flag_values: flags.FlagValues = FLAGS,
+) -> dict[str, dict[str, Any]]:
+  """Returns copy of flag values as a dict.
+
+  Args:
+    flag_values: FlagValues, the FlagValues instance with which the flag will be
+      saved. This should almost never need to be overridden.
+
+  Returns:
+    Dictionary mapping keys to values. Keys are flag names, values are
+    corresponding ``__dict__`` members. E.g. ``{'key': value_dict, ...}``.
+  """
+  return {name: _copy_flag_dict(flag_values[name]) for name in flag_values}
+
+
+def restore_flag_values(
+    saved_flag_values: Mapping[str, dict[str, Any]],
+    flag_values: flags.FlagValues = FLAGS,
+) -> None:
+  """Restores flag values based on the dictionary of flag values.
+
+  Args:
+    saved_flag_values: {'flag_name': value_dict, ...}
+    flag_values: FlagValues, the FlagValues instance from which the flag will be
+      restored. This should almost never need to be overridden.
+  """
+  new_flag_names = list(flag_values)
+  for name in new_flag_names:
+    saved = saved_flag_values.get(name)
+    if saved is None:
+      # If __dict__ was not saved delete "new" flag.
+      delattr(flag_values, name)
+    else:
+      if flag_values[name].value != saved['_value']:
+        flag_values[name].value = saved['_value']  # Ensure C++ value is set.
+      flag_values[name].__dict__ = saved
+
+
+@overload
+def _wrap(
+    flag_overrider_cls: type['_FlagOverrider'],
+    func: _CallableT,
+    overrides: Mapping[str, Any],
+) -> _CallableT:
+  ...
+
+
+@overload
+def _wrap(
+    flag_overrider_cls: type['_ParsingFlagOverrider'],
+    func: _CallableT,
+    overrides: Mapping[str, str | Sequence[str]],
+) -> _CallableT:
+  ...
+
+
+def _wrap(flag_overrider_cls, func, overrides):
+  """Creates a wrapper function that saves/restores flag values.
+
+  Args:
+    flag_overrider_cls: The class that will be used as a context manager.
+    func: This will be called between saving flags and restoring flags.
+    overrides: Flag names mapped to their values. These flags will be set after
+      saving the original flag state. The type of the values depends on if
+      _FlagOverrider or _ParsingFlagOverrider was specified.
+
+  Returns:
+    A wrapped version of func.
+  """
+
+  @functools.wraps(func)
+  def _flagsaver_wrapper(*args, **kwargs):
+    """Wrapper function that saves and restores flags."""
+    with flag_overrider_cls(**overrides):
+      return func(*args, **kwargs)
+
+  return _flagsaver_wrapper
+
+
+class _FlagOverrider:
+  """Overrides flags for the duration of the decorated function call.
+
+  It also restores all original values of flags after decorated method
+  completes.
+  """
+
+  def __init__(self, **overrides: Any):
+    self._overrides = overrides
+    self._saved_flag_values = None
+
+  def __call__(self, func: _CallableT) -> _CallableT:
+    if inspect.isclass(func):
+      raise TypeError('flagsaver cannot be applied to a class.')
+    return _wrap(self.__class__, func, self._overrides)
+
+  def __enter__(self):
+    self._saved_flag_values = save_flag_values(FLAGS)
+    try:
+      FLAGS._set_attributes(**self._overrides)
+    except:
+      # It may fail because of flag validators.
+      restore_flag_values(self._saved_flag_values, FLAGS)
+      raise
+
+  def __exit__(self, exc_type, exc_value, traceback):
+    restore_flag_values(self._saved_flag_values, FLAGS)
+
+
+class _ParsingFlagOverrider(_FlagOverrider):
+  """Context manager for overriding flags.
+
+  Simulates command line parsing.
+
+  This is simlar to _FlagOverrider except that all **overrides should be
+  strings or sequences of strings, and when context is entered this class calls
+  .parse(value)
+
+  This results in the flags having .present set properly.
+  """
+
+  def __init__(self, **overrides: str | Sequence[str]):
+    for flag_name, new_value in overrides.items():
+      if isinstance(new_value, str):
+        continue
+      if isinstance(new_value, Sequence) and all(
+          isinstance(single_value, str) for single_value in new_value
+      ):
+        continue
+      raise TypeError(
+          f'flagsaver.as_parsed() cannot parse {flag_name}. Expected a single '
+          f'string or sequence of strings but {type(new_value)} was provided.')
+    super().__init__(**overrides)
+
+  def __enter__(self):
+    self._saved_flag_values = save_flag_values(FLAGS)
+    try:
+      for flag_name, unparsed_value in self._overrides.items():
+        # LINT.IfChange(flag_override_parsing)
+        FLAGS[flag_name].parse(unparsed_value)
+        FLAGS[flag_name].using_default_value = False
+        # LINT.ThenChange()
+
+      # Perform the validation on all modified flags. This is something that
+      # FLAGS._set_attributes() does for you in _FlagOverrider.
+      for flag_name in self._overrides:
+        FLAGS._assert_validators(FLAGS[flag_name].validators)
+
+    except KeyError as e:
+      # If a flag doesn't exist, an UnrecognizedFlagError is more specific.
+      restore_flag_values(self._saved_flag_values, FLAGS)
+      raise flags.UnrecognizedFlagError('Unknown command line flag.') from e
+
+    except:
+      # It may fail because of flag validators or general parsing issues.
+      restore_flag_values(self._saved_flag_values, FLAGS)
+      raise
+
+
+def _copy_flag_dict(flag: flags.Flag) -> dict[str, Any]:
+  """Returns a copy of the flag object's ``__dict__``.
+
+  It's mostly a shallow copy of the ``__dict__``, except it also does a shallow
+  copy of the validator list.
+
+  Args:
+    flag: flags.Flag, the flag to copy.
+
+  Returns:
+    A copy of the flag object's ``__dict__``.
+  """
+  copy = flag.__dict__.copy()
+  copy['_value'] = flag.value  # Ensure correct restore for C++ flags.
+  copy['validators'] = list(flag.validators)
+  return copy

.venv/lib/python3.13/site-packages/absl/testing/parameterized.py

@@ -0,0 +1,726 @@
+# Copyright 2017 The Abseil Authors.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Adds support for parameterized tests to Python's unittest TestCase class.
+
+A parameterized test is a method in a test case that is invoked with different
+argument tuples.
+
+A simple example::
+
+    class AdditionExample(parameterized.TestCase):
+      @parameterized.parameters(
+        (1, 2, 3),
+        (4, 5, 9),
+        (1, 1, 3))
+      def testAddition(self, op1, op2, result):
+        self.assertEqual(result, op1 + op2)
+
+Each invocation is a separate test case and properly isolated just
+like a normal test method, with its own setUp/tearDown cycle. In the
+example above, there are three separate testcases, one of which will
+fail due to an assertion error (1 + 1 != 3).
+
+Parameters for individual test cases can be tuples (with positional parameters)
+or dictionaries (with named parameters)::
+
+    class AdditionExample(parameterized.TestCase):
+      @parameterized.parameters(
+        {'op1': 1, 'op2': 2, 'result': 3},
+        {'op1': 4, 'op2': 5, 'result': 9},
+      )
+      def testAddition(self, op1, op2, result):
+        self.assertEqual(result, op1 + op2)
+
+If a parameterized test fails, the error message will show the
+original test name and the parameters for that test.
+
+The id method of the test, used internally by the unittest framework, is also
+modified to show the arguments (but note that the name reported by `id()`
+doesn't match the actual test name, see below). To make sure that test names
+stay the same across several invocations, object representations like::
+
+    >>> class Foo(object):
+    ...  pass
+    >>> repr(Foo())
+    '<__main__.Foo object at 0x23d8610>'
+
+are turned into ``__main__.Foo``. When selecting a subset of test cases to run
+on the command-line, the test cases contain an index suffix for each argument
+in the order they were passed to :func:`parameters` (eg. testAddition0,
+testAddition1, etc.) This naming scheme is subject to change; for more reliable
+and stable names, especially in test logs, use :func:`named_parameters` instead.
+
+Tests using :func:`named_parameters` are similar to :func:`parameters`, except
+only tuples or dicts of args are supported. For tuples, the first parameter arg
+has to be a string (or an object that returns an apt name when converted via
+``str()``). For dicts, a value for the key ``testcase_name`` must be present and
+must be a string (or an object that returns an apt name when converted via
+``str()``)::
+
+    class NamedExample(parameterized.TestCase):
+      @parameterized.named_parameters(
+        ('Normal', 'aa', 'aaa', True),
+        ('EmptyPrefix', '', 'abc', True),
+        ('BothEmpty', '', '', True))
+      def testStartsWith(self, prefix, string, result):
+        self.assertEqual(result, string.startswith(prefix))
+
+    class NamedExample(parameterized.TestCase):
+      @parameterized.named_parameters(
+        {'testcase_name': 'Normal',
+          'result': True, 'string': 'aaa', 'prefix': 'aa'},
+        {'testcase_name': 'EmptyPrefix',
+          'result': True, 'string': 'abc', 'prefix': ''},
+        {'testcase_name': 'BothEmpty',
+          'result': True, 'string': '', 'prefix': ''})
+      def testStartsWith(self, prefix, string, result):
+        self.assertEqual(result, string.startswith(prefix))
+
+Named tests also have the benefit that they can be run individually
+from the command line::
+
+    $ testmodule.py NamedExample.testStartsWithNormal
+    .
+    --------------------------------------------------------------------
+    Ran 1 test in 0.000s
+
+    OK
+
+Parameterized Classes
+=====================
+
+If invocation arguments are shared across test methods in a single
+TestCase class, instead of decorating all test methods
+individually, the class itself can be decorated::
+
+    @parameterized.parameters(
+      (1, 2, 3),
+      (4, 5, 9))
+    class ArithmeticTest(parameterized.TestCase):
+      def testAdd(self, arg1, arg2, result):
+        self.assertEqual(arg1 + arg2, result)
+
+      def testSubtract(self, arg1, arg2, result):
+        self.assertEqual(result - arg1, arg2)
+
+Inputs from Iterables
+=====================
+
+If parameters should be shared across several test cases, or are dynamically
+created from other sources, a single non-tuple iterable can be passed into
+the decorator. This iterable will be used to obtain the test cases::
+
+    class AdditionExample(parameterized.TestCase):
+      @parameterized.parameters(
+        c.op1, c.op2, c.result for c in testcases
+      )
+      def testAddition(self, op1, op2, result):
+        self.assertEqual(result, op1 + op2)
+
+
+Single-Argument Test Methods
+============================
+
+If a test method takes only one argument, the single arguments must not be
+wrapped into a tuple::
+
+    class NegativeNumberExample(parameterized.TestCase):
+      @parameterized.parameters(
+        -1, -3, -4, -5
+      )
+      def testIsNegative(self, arg):
+        self.assertTrue(IsNegative(arg))
+
+
+List/tuple as a Single Argument
+===============================
+
+If a test method takes a single argument of a list/tuple, it must be wrapped
+inside a tuple::
+
+    class ZeroSumExample(parameterized.TestCase):
+      @parameterized.parameters(
+        ([-1, 0, 1], ),
+        ([-2, 0, 2], ),
+      )
+      def testSumIsZero(self, arg):
+        self.assertEqual(0, sum(arg))
+
+
+Cartesian product of Parameter Values as Parameterized Test Cases
+=================================================================
+
+If required to test method over a cartesian product of parameters,
+`parameterized.product` may be used to facilitate generation of parameters
+test combinations::
+
+    class TestModuloExample(parameterized.TestCase):
+      @parameterized.product(
+          num=[0, 20, 80],
+          modulo=[2, 4],
+          expected=[0]
+      )
+      def testModuloResult(self, num, modulo, expected):
+        self.assertEqual(expected, num % modulo)
+
+This results in 6 test cases being created - one for each combination of the
+parameters. It is also possible to supply sequences of keyword argument dicts
+as elements of the cartesian product::
+
+    @parameterized.product(
+        (dict(num=5, modulo=3, expected=2),
+         dict(num=7, modulo=4, expected=3)),
+        dtype=(int, float)
+    )
+    def testModuloResult(self, num, modulo, expected, dtype):
+      self.assertEqual(expected, dtype(num) % modulo)
+
+This results in 4 test cases being created - for each of the two sets of test
+data (supplied as kwarg dicts) and for each of the two data types (supplied as
+a named parameter). Multiple keyword argument dicts may be supplied if required.
+
+Async Support
+=============
+
+If a test needs to call async functions, it can inherit from both
+parameterized.TestCase and another TestCase that supports async calls, such
+as [asynctest](https://github.com/Martiusweb/asynctest)::
+
+  import asynctest
+
+  class AsyncExample(parameterized.TestCase, asynctest.TestCase):
+    @parameterized.parameters(
+      ('a', 1),
+      ('b', 2),
+    )
+    async def testSomeAsyncFunction(self, arg, expected):
+      actual = await someAsyncFunction(arg)
+      self.assertEqual(actual, expected)
+"""
+
+from collections import abc
+import functools
+import inspect
+import itertools
+import re
+import types
+import unittest
+import warnings
+
+from absl.testing import absltest
+
+
+_ADDR_RE = re.compile(r'\<([a-zA-Z0-9_\-\.]+) object at 0x[a-fA-F0-9]+\>')
+_NAMED = object()
+_ARGUMENT_REPR = object()
+_NAMED_DICT_KEY = 'testcase_name'
+
+
+class NoTestsError(Exception):
+  """Raised when parameterized decorators do not generate any tests."""
+
+
+class DuplicateTestNameError(Exception):
+  """Raised when a parameterized test has the same test name multiple times."""
+
+  def __init__(self, test_class_name, new_test_name, original_test_name):
+    super().__init__(
+        'Duplicate parameterized test name in {}: generated test name {!r} '
+        '(generated from {!r}) already exists. Consider using '
+        'named_parameters() to give your tests unique names and/or renaming '
+        'the conflicting test method.'.format(
+            test_class_name, new_test_name, original_test_name
+        )
+    )
+
+
+def _clean_repr(obj):
+  return _ADDR_RE.sub(r'<\1>', repr(obj))
+
+
+def _non_string_or_bytes_iterable(obj):
+  return (isinstance(obj, abc.Iterable) and not isinstance(obj, str) and
+          not isinstance(obj, bytes))
+
+
+def _format_parameter_list(testcase_params):
+  if isinstance(testcase_params, abc.Mapping):
+    return ', '.join('%s=%s' % (argname, _clean_repr(value))
+                     for argname, value in testcase_params.items())
+  elif _non_string_or_bytes_iterable(testcase_params):
+    return ', '.join(map(_clean_repr, testcase_params))
+  else:
+    return _format_parameter_list((testcase_params,))
+
+
+def _async_wrapped(func):
+  @functools.wraps(func)
+  async def wrapper(*args, **kwargs):
+    return await func(*args, **kwargs)
+  return wrapper
+
+
+class _ParameterizedTestIter:
+  """Callable and iterable class for producing new test cases."""
+
+  def __init__(self, test_method, testcases, naming_type, original_name=None):
+    """Returns concrete test functions for a test and a list of parameters.
+
+    The naming_type is used to determine the name of the concrete
+    functions as reported by the unittest framework. If naming_type is
+    _FIRST_ARG, the testcases must be tuples, and the first element must
+    have a string representation that is a valid Python identifier.
+
+    Args:
+      test_method: The decorated test method.
+      testcases: (list of tuple/dict) A list of parameter tuples/dicts for
+          individual test invocations.
+      naming_type: The test naming type, either _NAMED or _ARGUMENT_REPR.
+      original_name: The original test method name. When decorated on a test
+          method, None is passed to __init__ and test_method.__name__ is used.
+          Note test_method.__name__ might be different than the original defined
+          test method because of the use of other decorators. A more accurate
+          value is set by TestGeneratorMetaclass.__new__ later.
+    """
+    self._test_method = test_method
+    self.testcases = testcases
+    self._naming_type = naming_type
+    if original_name is None:
+      original_name = test_method.__name__
+    self._original_name = original_name
+    self.__name__ = _ParameterizedTestIter.__name__
+
+  def __call__(self, *args, **kwargs):
+    raise RuntimeError('You appear to be running a parameterized test case '
+                       'without having inherited from parameterized.'
+                       'TestCase. This is bad because none of '
+                       'your test cases are actually being run. You may also '
+                       'be using another decorator before the parameterized '
+                       'one, in which case you should reverse the order.')
+
+  def __iter__(self):
+    test_method = self._test_method
+    naming_type = self._naming_type
+
+    def make_bound_param_test(testcase_params):
+      @functools.wraps(test_method)
+      def bound_param_test(self):
+        if isinstance(testcase_params, abc.Mapping):
+          return test_method(self, **testcase_params)
+        elif _non_string_or_bytes_iterable(testcase_params):
+          return test_method(self, *testcase_params)
+        else:
+          return test_method(self, testcase_params)
+
+      if naming_type is _NAMED:
+        # Signal the metaclass that the name of the test function is unique
+        # and descriptive.
+        bound_param_test.__x_use_name__ = True
+
+        testcase_name = None
+        if isinstance(testcase_params, abc.Mapping):
+          if _NAMED_DICT_KEY not in testcase_params:
+            raise RuntimeError(
+                'Dict for named tests must contain key "%s"' % _NAMED_DICT_KEY)
+          # Create a new dict to avoid modifying the supplied testcase_params.
+          testcase_name = testcase_params[_NAMED_DICT_KEY]
+          testcase_params = {
+              k: v for k, v in testcase_params.items() if k != _NAMED_DICT_KEY
+          }
+        elif _non_string_or_bytes_iterable(testcase_params):
+          if not isinstance(testcase_params[0], str):
+            raise RuntimeError(
+                'The first element of named test parameters is the test name '
+                'suffix and must be a string')
+          testcase_name = testcase_params[0]
+          testcase_params = testcase_params[1:]
+        else:
+          raise RuntimeError(
+              'Named tests must be passed a dict or non-string iterable.')
+
+        test_method_name = self._original_name
+        # Support PEP-8 underscore style for test naming if used.
+        if (test_method_name.startswith('test_')
+            and testcase_name
+            and not testcase_name.startswith('_')):
+          test_method_name += '_'
+
+        bound_param_test.__name__ = test_method_name + str(testcase_name)
+      elif naming_type is _ARGUMENT_REPR:
+        # If it's a generator, convert it to a tuple and treat them as
+        # parameters.
+        if isinstance(testcase_params, types.GeneratorType):
+          testcase_params = tuple(testcase_params)
+        # The metaclass creates a unique, but non-descriptive method name for
+        # _ARGUMENT_REPR tests using an indexed suffix.
+        # To keep test names descriptive, only the original method name is used.
+        # To make sure test names are unique, we add a unique descriptive suffix
+        # __x_params_repr__ for every test.
+        params_repr = '(%s)' % (_format_parameter_list(testcase_params),)
+        bound_param_test.__x_params_repr__ = params_repr
+      else:
+        raise RuntimeError('%s is not a valid naming type.' % (naming_type,))
+
+      bound_param_test.__doc__ = '%s(%s)' % (
+          bound_param_test.__name__, _format_parameter_list(testcase_params))
+      if test_method.__doc__:
+        bound_param_test.__doc__ += '\n%s' % (test_method.__doc__,)
+      if inspect.iscoroutinefunction(test_method):
+        return _async_wrapped(bound_param_test)
+      return bound_param_test
+
+    return (make_bound_param_test(c) for c in self.testcases)
+
+
+def _modify_class(class_object, testcases, naming_type):
+  assert not getattr(class_object, '_test_params_reprs', None), (
+      'Cannot add parameters to %s. Either it already has parameterized '
+      'methods, or its super class is also a parameterized class.' % (
+          class_object,))
+  # NOTE: _test_params_repr is private to parameterized.TestCase and it's
+  # metaclass; do not use it outside of those classes.
+  class_object._test_params_reprs = test_params_reprs = {}
+  for name, obj in class_object.__dict__.copy().items():
+    if (name.startswith(unittest.TestLoader.testMethodPrefix)
+        and isinstance(obj, types.FunctionType)):
+      delattr(class_object, name)
+      methods = {}
+      _update_class_dict_for_param_test_case(
+          class_object.__name__, methods, test_params_reprs, name,
+          _ParameterizedTestIter(obj, testcases, naming_type, name))
+      for meth_name, meth in methods.items():
+        setattr(class_object, meth_name, meth)
+
+
+def _parameter_decorator(naming_type, testcases):
+  """Implementation of the parameterization decorators.
+
+  Args:
+    naming_type: The naming type.
+    testcases: Testcase parameters.
+
+  Raises:
+    NoTestsError: Raised when the decorator generates no tests.
+
+  Returns:
+    A function for modifying the decorated object.
+  """
+  def _apply(obj):
+    if isinstance(obj, type):
+      _modify_class(obj, testcases, naming_type)
+      return obj
+    else:
+      return _ParameterizedTestIter(obj, testcases, naming_type)
+
+  if (len(testcases) == 1 and
+      not isinstance(testcases[0], tuple) and
+      not isinstance(testcases[0], abc.Mapping)):
+    # Support using a single non-tuple parameter as a list of test cases.
+    # Note that the single non-tuple parameter can't be Mapping either, which
+    # means a single dict parameter case.
+    assert _non_string_or_bytes_iterable(testcases[0]), (
+        'Single parameter argument must be a non-string non-Mapping iterable')
+    testcases = testcases[0]
+
+  if not isinstance(testcases, abc.Sequence):
+    testcases = list(testcases)
+  if not testcases:
+    raise NoTestsError(
+        'parameterized test decorators did not generate any tests. '
+        'Make sure you specify non-empty parameters, '
+        'and do not reuse generators more than once.')
+
+  return _apply
+
+
+def parameters(*testcases):
+  """A decorator for creating parameterized tests.
+
+  See the module docstring for a usage example.
+
+  Args:
+    *testcases: Parameters for the decorated method, either a single
+        iterable, or a list of tuples/dicts/objects (for tests with only one
+        argument).
+
+  Raises:
+    NoTestsError: Raised when the decorator generates no tests.
+
+  Returns:
+     A test generator to be handled by TestGeneratorMetaclass.
+  """
+  return _parameter_decorator(_ARGUMENT_REPR, testcases)
+
+
+def named_parameters(*testcases):
+  """A decorator for creating parameterized tests.
+
+  See the module docstring for a usage example. For every parameter tuple
+  passed, the first element of the tuple should be a string and will be appended
+  to the name of the test method. Each parameter dict passed must have a value
+  for the key "testcase_name", the string representation of that value will be
+  appended to the name of the test method.
+
+  Args:
+    *testcases: Parameters for the decorated method, either a single iterable,
+        or a list of tuples or dicts.
+
+  Raises:
+    NoTestsError: Raised when the decorator generates no tests.
+
+  Returns:
+     A test generator to be handled by TestGeneratorMetaclass.
+  """
+  return _parameter_decorator(_NAMED, testcases)
+
+
+def product(*kwargs_seqs, **testgrid):
+  """A decorator for running tests over cartesian product of parameters values.
+
+  See the module docstring for a usage example. The test will be run for every
+  possible combination of the parameters.
+
+  Args:
+    *kwargs_seqs: Each positional parameter is a sequence of keyword arg dicts;
+      every test case generated will include exactly one kwargs dict from each
+      positional parameter; these will then be merged to form an overall list
+      of arguments for the test case.
+    **testgrid: A mapping of parameter names and their possible values. Possible
+      values should given as either a list or a tuple.
+
+  Raises:
+    NoTestsError: Raised when the decorator generates no tests.
+
+  Returns:
+     A test generator to be handled by TestGeneratorMetaclass.
+  """
+
+  for name, values in testgrid.items():
+    assert isinstance(values, (list, tuple)), (
+        'Values of {} must be given as list or tuple, found {}'.format(
+            name, type(values)))
+
+  prior_arg_names = set()
+  for kwargs_seq in kwargs_seqs:
+    assert ((isinstance(kwargs_seq, (list, tuple))) and
+            all(isinstance(kwargs, dict) for kwargs in kwargs_seq)), (
+                'Positional parameters must be a sequence of keyword arg'
+                'dicts, found {}'
+                .format(kwargs_seq))
+    if kwargs_seq:
+      arg_names = set(kwargs_seq[0])
+      assert all(set(kwargs) == arg_names for kwargs in kwargs_seq), (
+          'Keyword argument dicts within a single parameter must all have the '
+          'same keys, found {}'.format(kwargs_seq))
+      assert not (arg_names & prior_arg_names), (
+          'Keyword argument dict sequences must all have distinct argument '
+          'names, found duplicate(s) {}'
+          .format(sorted(arg_names & prior_arg_names)))
+      prior_arg_names |= arg_names
+
+  assert not (prior_arg_names & set(testgrid)), (
+      'Arguments supplied in kwargs dicts in positional parameters must not '
+      'overlap with arguments supplied as named parameters; found duplicate '
+      'argument(s) {}'.format(sorted(prior_arg_names & set(testgrid))))
+
+  # Convert testgrid into a sequence of sequences of kwargs dicts and combine
+  # with the positional parameters.
+  # So foo=[1,2], bar=[3,4] --> [[{foo: 1}, {foo: 2}], [{bar: 3, bar: 4}]]
+  testgrid = (tuple({k: v} for v in vs) for k, vs in testgrid.items())
+  testgrid = tuple(kwargs_seqs) + tuple(testgrid)
+
+  # Create all possible combinations of parameters as a cartesian product
+  # of parameter values.
+  testcases = [
+      dict(itertools.chain.from_iterable(case.items()
+                                         for case in cases))
+      for cases in itertools.product(*testgrid)
+  ]
+  return _parameter_decorator(_ARGUMENT_REPR, testcases)
+
+
+class TestGeneratorMetaclass(type):
+  """Metaclass for adding tests generated by parameterized decorators."""
+
+  def __new__(cls, class_name, bases, dct):
+    # NOTE: _test_params_repr is private to parameterized.TestCase and it's
+    # metaclass; do not use it outside of those classes.
+    test_params_reprs = dct.setdefault('_test_params_reprs', {})
+    for name, obj in dct.copy().items():
+      if (name.startswith(unittest.TestLoader.testMethodPrefix) and
+          _non_string_or_bytes_iterable(obj)):
+        # NOTE: `obj` might not be a _ParameterizedTestIter in two cases:
+        # 1. a class-level iterable named test* that isn't a test, such as
+        #    a list of something. Such attributes get deleted from the class.
+        #
+        # 2. If a decorator is applied to the parameterized test, e.g.
+        #    @morestuff
+        #    @parameterized.parameters(...)
+        #    def test_foo(...): ...
+        #
+        #   This is OK so long as the underlying parameterized function state
+        #   is forwarded (e.g. using functool.wraps() and **without**
+        #   accessing explicitly accessing the internal attributes.
+        if isinstance(obj, _ParameterizedTestIter):
+          # Update the original test method name so it's more accurate.
+          # The mismatch might happen when another decorator is used inside
+          # the parameterized decrators, and the inner decorator doesn't
+          # preserve its __name__.
+          obj._original_name = name
+        iterator = iter(obj)
+        dct.pop(name)
+        _update_class_dict_for_param_test_case(
+            class_name, dct, test_params_reprs, name, iterator)
+    # If the base class is a subclass of parameterized.TestCase, inherit its
+    # _test_params_reprs too.
+    for base in bases:
+      # Check if the base has _test_params_reprs first, then check if it's a
+      # subclass of parameterized.TestCase. Otherwise when this is called for
+      # the parameterized.TestCase definition itself, this raises because
+      # itself is not defined yet. This works as long as absltest.TestCase does
+      # not define _test_params_reprs.
+      base_test_params_reprs = getattr(base, '_test_params_reprs', None)
+      if base_test_params_reprs and issubclass(base, TestCase):
+        for test_method, test_method_id in base_test_params_reprs.items():
+          # test_method may both exists in base and this class.
+          # This class's method overrides base class's.
+          # That's why it should only inherit it if it does not exist.
+          test_params_reprs.setdefault(test_method, test_method_id)
+
+    return type.__new__(cls, class_name, bases, dct)
+
+
+def _update_class_dict_for_param_test_case(
+    test_class_name, dct, test_params_reprs, name, iterator):
+  """Adds individual test cases to a dictionary.
+
+  Args:
+    test_class_name: The name of the class tests are added to.
+    dct: The target dictionary.
+    test_params_reprs: The dictionary for mapping names to test IDs.
+    name: The original name of the test case.
+    iterator: The iterator generating the individual test cases.
+
+  Raises:
+    DuplicateTestNameError: Raised when a test name occurs multiple times.
+    RuntimeError: If non-parameterized functions are generated.
+  """
+  for idx, func in enumerate(iterator):
+    assert callable(func), 'Test generators must yield callables, got %r' % (
+        func,)
+    if not (getattr(func, '__x_use_name__', None) or
+            getattr(func, '__x_params_repr__', None)):
+      raise RuntimeError(
+          '{}.{} generated a test function without using the parameterized '
+          'decorators. Only tests generated using the decorators are '
+          'supported.'.format(test_class_name, name))
+
+    if getattr(func, '__x_use_name__', False):
+      original_name = func.__name__
+      new_name = original_name
+    else:
+      original_name = name
+      new_name = '%s%d' % (original_name, idx)
+
+    if new_name in dct:
+      raise DuplicateTestNameError(test_class_name, new_name, original_name)
+
+    dct[new_name] = func
+    test_params_reprs[new_name] = getattr(func, '__x_params_repr__', '')
+
+
+class TestCase(absltest.TestCase, metaclass=TestGeneratorMetaclass):
+  """Base class for test cases using the parameters decorator."""
+
+  # visibility: private; do not call outside this class.
+  def _get_params_repr(self):
+    return self._test_params_reprs.get(self._testMethodName, '')
+
+  def __str__(self):
+    params_repr = self._get_params_repr()
+    if params_repr:
+      params_repr = ' ' + params_repr
+    return '{}{} ({})'.format(
+        self._testMethodName, params_repr,
+        unittest.util.strclass(self.__class__))
+
+  def id(self):
+    """Returns the descriptive ID of the test.
+
+    This is used internally by the unittesting framework to get a name
+    for the test to be used in reports.
+
+    Returns:
+      The test id.
+    """
+    base = super().id()
+    params_repr = self._get_params_repr()
+    if params_repr:
+      # We include the params in the id so that, when reported in the
+      # test.xml file, the value is more informative than just "test_foo0".
+      # Use a space to separate them so that it's copy/paste friendly and
+      # easy to identify the actual test id.
+      return f'{base} {params_repr}'
+    else:
+      return base
+
+
+# This function is kept CamelCase because it's used as a class's base class.
+def CoopTestCase(other_base_class) -> type:  # pylint: disable=invalid-name, g-bare-generic
+  """Returns a new base class with a cooperative metaclass base.
+
+  This enables the TestCase to be used in combination
+  with other base classes that have custom metaclasses, such as
+  ``mox.MoxTestBase``.
+
+  Only works with metaclasses that do not override ``type.__new__``.
+
+  Example::
+
+      from absl.testing import parameterized
+
+      class ExampleTest(parameterized.CoopTestCase(OtherTestCase)):
+        ...
+
+  Args:
+    other_base_class: (class) A test case base class.
+
+  Returns:
+    A new class object.
+  """
+  # If the other base class has a metaclass of 'type' then trying to combine
+  # the metaclasses will result in an MRO error. So simply combine them and
+  # return.
+  if type(other_base_class) == type:  # pylint: disable=unidiomatic-typecheck
+    warnings.warn(
+        'CoopTestCase is only necessary when combining with a class that uses'
+        ' a metaclass. Use multiple inheritance like this instead: class'
+        f' ExampleTest(paramaterized.TestCase, {other_base_class.__name__}):',
+        stacklevel=2,
+    )
+
+    class CoopTestCaseBase(other_base_class, TestCase):
+      pass
+
+    return CoopTestCaseBase
+  else:
+
+    class CoopMetaclass(type(other_base_class), TestGeneratorMetaclass):  # type: ignore  # pylint: disable=unused-variable
+      pass
+
+    class CoopTestCaseBase(other_base_class, TestCase, metaclass=CoopMetaclass):  # type: ignore
+      pass
+
+    return CoopTestCaseBase

.venv/lib/python3.13/site-packages/absl/testing/xml_reporter.py

@@ -0,0 +1,570 @@
+# Copyright 2017 The Abseil Authors.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""A Python test reporter that generates test reports in JUnit XML format."""
+
+import datetime
+import re
+import sys
+import threading
+import time
+import traceback
+from typing import Any
+import unittest
+from xml.sax import saxutils
+from absl.testing import _pretty_print_reporter
+
+
+# See http://www.w3.org/TR/REC-xml/#NT-Char
+_bad_control_character_codes = set(range(0, 0x20)) - {0x9, 0xA, 0xD}
+
+
+_control_character_conversions = {
+    chr(i): f'\\x{i:02x}' for i in _bad_control_character_codes
+}
+
+
+_escape_xml_attr_conversions = {
+    '"': '"',
+    "'": ''',
+    '\n': '
',
+    '\t': '	',
+    '\r': '
',
+    ' ': ' '}
+_escape_xml_attr_conversions.update(_control_character_conversions)
+
+
+# When class or module level function fails, unittest/suite.py adds a
+# _ErrorHolder instance instead of a real TestCase, and it has a description
+# like "setUpClass (__main__.MyTestCase)".
+_CLASS_OR_MODULE_LEVEL_TEST_DESC_REGEX = re.compile(r'^(\w+) \((\S+)\)$')
+
+
+# NOTE: while saxutils.quoteattr() theoretically does the same thing; it
+# seems to often end up being too smart for it's own good not escaping properly.
+# This function is much more reliable.
+def _escape_xml_attr(content):
+  """Escapes xml attributes."""
+  # Note: saxutils doesn't escape the quotes.
+  return saxutils.escape(content, _escape_xml_attr_conversions)
+
+
+def _escape_cdata(s):
+  """Escapes a string to be used as XML CDATA.
+
+  CDATA characters are treated strictly as character data, not as XML markup,
+  but there are still certain restrictions on them.
+
+  Args:
+    s: the string to be escaped.
+  Returns:
+    An escaped version of the input string.
+  """
+  for char, escaped in _control_character_conversions.items():
+    s = s.replace(char, escaped)
+  return s.replace(']]>', ']] >')
+
+
+def _iso8601_timestamp(timestamp):
+  """Produces an ISO8601 datetime.
+
+  Args:
+    timestamp: an Epoch based timestamp in seconds.
+
+  Returns:
+    A iso8601 format timestamp if the input is a valid timestamp, None otherwise
+  """
+  if timestamp is None or timestamp < 0:
+    return None
+  return datetime.datetime.fromtimestamp(
+      timestamp, tz=datetime.timezone.utc).isoformat()
+
+
+def _print_xml_element_header(element, attributes, stream, indentation=''):
+  """Prints an XML header of an arbitrary element.
+
+  Args:
+    element: element name (testsuites, testsuite, testcase)
+    attributes: 2-tuple list with (attributes, values) already escaped
+    stream: output stream to write test report XML to
+    indentation: indentation added to the element header
+  """
+  stream.write('%s<%s' % (indentation, element))
+  for attribute in attributes:
+    if (len(attribute) == 2 and attribute[0] is not None and
+        attribute[1] is not None):
+      stream.write(' %s="%s"' % (attribute[0], attribute[1]))
+  stream.write('>\n')
+
+# Copy time.time which ensures the real time is used internally.
+# This prevents bad interactions with tests that stub out time.
+_time_copy = time.time
+
+
+def _safe_str(obj: object) -> str:
+  """Returns a string representation of an object."""
+  try:
+    return str(obj)
+  except Exception:  # pylint: disable=broad-except
+    return '<unprintable %s.%s object>' % (
+        type(obj).__module__,
+        type(obj).__name__,
+    )
+
+
+class _TestCaseResult:
+  """Private helper for _TextAndXMLTestResult that represents a test result.
+
+  Attributes:
+    test: A TestCase instance of an individual test method.
+    name: The name of the individual test method.
+    full_class_name: The full name of the test class.
+    run_time: The duration (in seconds) it took to run the test.
+    start_time: Epoch relative timestamp of when test started (in seconds)
+    errors: A list of error 4-tuples. Error tuple entries are
+        1) a string identifier of either "failure" or "error"
+        2) an exception_type
+        3) an exception_message
+        4) a string version of a sys.exc_info()-style tuple of values
+           ('error', err[0], err[1], self._exc_info_to_string(err))
+           If the length of errors is 0, then the test is either passed or
+           skipped.
+    skip_reason: A string explaining why the test was skipped.
+  """
+
+  def __init__(self, test):
+    self.run_time = -1
+    self.start_time = -1
+    self.skip_reason = None
+    self.errors = []
+    self.test = test
+
+    # Parse the test id to get its test name and full class path.
+    # Unfortunately there is no better way of knowning the test and class.
+    # Worse, unittest uses _ErrorHandler instances to represent class / module
+    # level failures.
+    test_desc = test.id() or str(test)
+    # Check if it's something like "setUpClass (__main__.TestCase)".
+    match = _CLASS_OR_MODULE_LEVEL_TEST_DESC_REGEX.match(test_desc)
+    if match:
+      name = match.group(1)
+      full_class_name = match.group(2)
+    else:
+      class_name = unittest.util.strclass(test.__class__)
+      if isinstance(test, unittest.case._SubTest):
+        # If the test case is a _SubTest, the real TestCase instance is
+        # available as _SubTest.test_case.
+        class_name = unittest.util.strclass(test.test_case.__class__)
+      if test_desc.startswith(class_name + '.'):
+        # In a typical unittest.TestCase scenario, test.id() returns with
+        # a class name formatted using unittest.util.strclass.
+        name = test_desc[len(class_name)+1:]
+        full_class_name = class_name
+      else:
+        # Otherwise make a best effort to guess the test name and full class
+        # path.
+        parts = test_desc.rsplit('.', 1)
+        name = parts[-1]
+        full_class_name = parts[0] if len(parts) == 2 else ''
+    self.name = _escape_xml_attr(name)
+    self.full_class_name = _escape_xml_attr(full_class_name)
+
+  def set_run_time(self, time_in_secs):
+    self.run_time = time_in_secs
+
+  def set_start_time(self, time_in_secs):
+    self.start_time = time_in_secs
+
+  def print_xml_summary(self, stream):
+    """Prints an XML Summary of a TestCase.
+
+    Status and result are populated as per JUnit XML test result reporter.
+    A test that has been skipped will always have a skip reason,
+    as every skip method in Python's unittest requires the reason arg to be
+    passed.
+
+    Args:
+      stream: output stream to write test report XML to
+    """
+
+    if self.skip_reason is None:
+      status = 'run'
+      result = 'completed'
+    else:
+      status = 'notrun'
+      result = 'suppressed'
+
+    test_case_attributes = [
+        ('name', '%s' % self.name),
+        ('status', '%s' % status),
+        ('result', '%s' % result),
+        ('time', '%.3f' % self.run_time),
+        ('classname', self.full_class_name),
+        ('timestamp', _iso8601_timestamp(self.start_time)),
+    ]
+    _print_xml_element_header('testcase', test_case_attributes, stream, '  ')
+    self._print_testcase_details(stream)
+    stream.write('  </testcase>\n')
+
+  def _print_testcase_details(self, stream):
+    for error in self.errors:
+      outcome, exception_type, message, error_msg = error  # pylint: disable=unpacking-non-sequence
+      message = _escape_xml_attr(_safe_str(message))
+      exception_type = _escape_xml_attr(str(exception_type))
+      error_msg = _escape_cdata(error_msg)
+      stream.write('  <%s message="%s" type="%s"><![CDATA[%s]]></%s>\n'
+                   % (outcome, message, exception_type, error_msg, outcome))
+
+
+class _TestSuiteResult:
+  """Private helper for _TextAndXMLTestResult."""
+
+  def __init__(self):
+    self.suites = {}
+    self.failure_counts = {}
+    self.error_counts = {}
+    self.overall_start_time = -1
+    self.overall_end_time = -1
+    self._testsuites_properties = {}
+
+  def add_test_case_result(self, test_case_result):
+    suite_name = type(test_case_result.test).__name__
+    if suite_name == '_ErrorHolder':
+      # _ErrorHolder is a special case created by unittest for class / module
+      # level functions.
+      suite_name = test_case_result.full_class_name.rsplit('.')[-1]
+    if isinstance(test_case_result.test, unittest.case._SubTest):
+      # If the test case is a _SubTest, the real TestCase instance is
+      # available as _SubTest.test_case.
+      suite_name = type(test_case_result.test.test_case).__name__
+
+    self._setup_test_suite(suite_name)
+    self.suites[suite_name].append(test_case_result)
+    for error in test_case_result.errors:
+      # Only count the first failure or error so that the sum is equal to the
+      # total number of *testcases* that have failures or errors.
+      if error[0] == 'failure':
+        self.failure_counts[suite_name] += 1
+        break
+      elif error[0] == 'error':
+        self.error_counts[suite_name] += 1
+        break
+
+  def print_xml_summary(self, stream):
+    overall_test_count = sum(len(x) for x in self.suites.values())
+    overall_failures = sum(self.failure_counts.values())
+    overall_errors = sum(self.error_counts.values())
+    overall_attributes = [
+        ('name', ''),
+        ('tests', '%d' % overall_test_count),
+        ('failures', '%d' % overall_failures),
+        ('errors', '%d' % overall_errors),
+        ('time', '%.3f' % (self.overall_end_time - self.overall_start_time)),
+        ('timestamp', _iso8601_timestamp(self.overall_start_time)),
+    ]
+    _print_xml_element_header('testsuites', overall_attributes, stream)
+    if self._testsuites_properties:
+      stream.write('    <properties>\n')
+      for name, value in sorted(self._testsuites_properties.items()):
+        stream.write('      <property name="%s" value="%s"></property>\n' %
+                     (_escape_xml_attr(name), _escape_xml_attr(str(value))))
+      stream.write('    </properties>\n')
+
+    for suite_name in self.suites:
+      suite = self.suites[suite_name]
+      suite_end_time = max(x.start_time + x.run_time for x in suite)
+      suite_start_time = min(x.start_time for x in suite)
+      failures = self.failure_counts[suite_name]
+      errors = self.error_counts[suite_name]
+      suite_attributes = [
+          ('name', '%s' % suite_name),
+          ('tests', '%d' % len(suite)),
+          ('failures', '%d' % failures),
+          ('errors', '%d' % errors),
+          ('time', '%.3f' % (suite_end_time - suite_start_time)),
+          ('timestamp', _iso8601_timestamp(suite_start_time)),
+      ]
+      _print_xml_element_header('testsuite', suite_attributes, stream)
+
+      # test_case_result entries are not guaranteed to be in any user-friendly
+      # order, especially when using subtests. So sort them.
+      for test_case_result in sorted(suite, key=lambda t: t.name):
+        test_case_result.print_xml_summary(stream)
+      stream.write('</testsuite>\n')
+    stream.write('</testsuites>\n')
+
+  def _setup_test_suite(self, suite_name):
+    """Adds a test suite to the set of suites tracked by this test run.
+
+    Args:
+      suite_name: string, The name of the test suite being initialized.
+    """
+    if suite_name in self.suites:
+      return
+    self.suites[suite_name] = []
+    self.failure_counts[suite_name] = 0
+    self.error_counts[suite_name] = 0
+
+  def set_end_time(self, timestamp_in_secs):
+    """Sets the start timestamp of this test suite.
+
+    Args:
+      timestamp_in_secs: timestamp in seconds since epoch
+    """
+    self.overall_end_time = timestamp_in_secs
+
+  def set_start_time(self, timestamp_in_secs):
+    """Sets the end timestamp of this test suite.
+
+    Args:
+      timestamp_in_secs: timestamp in seconds since epoch
+    """
+    self.overall_start_time = timestamp_in_secs
+
+
+class _TextAndXMLTestResult(_pretty_print_reporter.TextTestResult):
+  """Private TestResult class that produces both formatted text results and XML.
+
+  Used by TextAndXMLTestRunner.
+  """
+
+  _TEST_SUITE_RESULT_CLASS = _TestSuiteResult
+  _TEST_CASE_RESULT_CLASS = _TestCaseResult
+
+  def __init__(self, xml_stream, stream, descriptions, verbosity,
+               time_getter=_time_copy, testsuites_properties=None):
+    super().__init__(stream, descriptions, verbosity)
+    self.xml_stream = xml_stream
+    self.pending_test_case_results = {}
+    self.suite = self._TEST_SUITE_RESULT_CLASS()
+    if testsuites_properties:
+      self.suite._testsuites_properties = testsuites_properties
+    self.time_getter = time_getter
+
+    # This lock guards any mutations on pending_test_case_results.
+    self._pending_test_case_results_lock = threading.RLock()
+
+  def startTest(self, test):
+    self.start_time = self.time_getter()
+    super().startTest(test)
+
+  def stopTest(self, test):
+    # Grabbing the write lock to avoid conflicting with stopTestRun.
+    with self._pending_test_case_results_lock:
+      super().stopTest(test)
+      result = self.get_pending_test_case_result(test)
+      if not result:
+        test_name = test.id() or str(test)
+        sys.stderr.write('No pending test case: %s\n' % test_name)
+        return
+      if getattr(self, 'start_time', None) is None:
+        # startTest may not be called for skipped tests since Python 3.12.1.
+        self.start_time = self.time_getter()
+      test_id = id(test)
+      run_time = self.time_getter() - self.start_time
+      result.set_run_time(run_time)
+      result.set_start_time(self.start_time)
+      self.suite.add_test_case_result(result)
+      del self.pending_test_case_results[test_id]
+
+  def startTestRun(self):
+    self.suite.set_start_time(self.time_getter())
+    super().startTestRun()
+
+  def stopTestRun(self):
+    self.suite.set_end_time(self.time_getter())
+    # All pending_test_case_results will be added to the suite and removed from
+    # the pending_test_case_results dictionary. Grabbing the write lock to avoid
+    # results from being added during this process to avoid duplicating adds or
+    # accidentally erasing newly appended pending results.
+    with self._pending_test_case_results_lock:
+      # Errors in the test fixture (setUpModule, tearDownModule,
+      # setUpClass, tearDownClass) can leave a pending result which
+      # never gets added to the suite.  The runner calls stopTestRun
+      # which gives us an opportunity to add these errors for
+      # reporting here.
+      for test_id in self.pending_test_case_results:
+        result = self.pending_test_case_results[test_id]
+        if getattr(self, 'start_time', None) is not None:
+          run_time = self.suite.overall_end_time - self.start_time
+          result.set_run_time(run_time)
+          result.set_start_time(self.start_time)
+        self.suite.add_test_case_result(result)
+      self.pending_test_case_results.clear()
+
+  def _exc_info_to_string(self, err, test=None):
+    """Converts a sys.exc_info()-style tuple of values into a string.
+
+    This method must be overridden because the method signature in
+    unittest.TestResult changed between Python 2.2 and 2.4.
+
+    Args:
+      err: A sys.exc_info() tuple of values for an error.
+      test: The test method.
+
+    Returns:
+      A formatted exception string.
+    """
+    if test:
+      return super()._exc_info_to_string(err, test)
+    return ''.join(traceback.format_exception(*err))
+
+  def add_pending_test_case_result(self, test, error_summary=None,
+                                   skip_reason=None):
+    """Adds result information to a test case result which may still be running.
+
+    If a result entry for the test already exists, add_pending_test_case_result
+    will add error summary tuples and/or overwrite skip_reason for the result.
+    If it does not yet exist, a result entry will be created.
+    Note that a test result is considered to have been run and passed
+    only if there are no errors or skip_reason.
+
+    Args:
+      test: A test method as defined by unittest
+      error_summary: A 4-tuple with the following entries:
+          1) a string identifier of either "failure" or "error"
+          2) an exception_type
+          3) an exception_message
+          4) a string version of a sys.exc_info()-style tuple of values
+             ('error', err[0], err[1], self._exc_info_to_string(err))
+             If the length of errors is 0, then the test is either passed or
+             skipped.
+      skip_reason: a string explaining why the test was skipped
+    """
+    with self._pending_test_case_results_lock:
+      test_id = id(test)
+      if test_id not in self.pending_test_case_results:
+        self.pending_test_case_results[test_id] = self._TEST_CASE_RESULT_CLASS(
+            test)
+      if error_summary:
+        self.pending_test_case_results[test_id].errors.append(error_summary)
+      if skip_reason:
+        self.pending_test_case_results[test_id].skip_reason = skip_reason
+
+  def delete_pending_test_case_result(self, test):
+    with self._pending_test_case_results_lock:
+      test_id = id(test)
+      del self.pending_test_case_results[test_id]
+
+  def get_pending_test_case_result(self, test):
+    test_id = id(test)
+    return self.pending_test_case_results.get(test_id, None)
+
+  def addSuccess(self, test):
+    super().addSuccess(test)
+    self.add_pending_test_case_result(test)
+
+  def addError(self, test, err):
+    super().addError(test, err)
+    error_summary = ('error', err[0], err[1],
+                     self._exc_info_to_string(err, test=test))
+    self.add_pending_test_case_result(test, error_summary=error_summary)
+
+  def addFailure(self, test, err):
+    super().addFailure(test, err)
+    error_summary = ('failure', err[0], err[1],
+                     self._exc_info_to_string(err, test=test))
+    self.add_pending_test_case_result(test, error_summary=error_summary)
+
+  def addSkip(self, test, reason):
+    super().addSkip(test, reason)
+    self.add_pending_test_case_result(test, skip_reason=reason)
+
+  def addExpectedFailure(self, test, err):
+    super().addExpectedFailure(test, err)
+    if callable(getattr(test, 'recordProperty', None)):
+      test.recordProperty('EXPECTED_FAILURE',
+                          self._exc_info_to_string(err, test=test))
+    self.add_pending_test_case_result(test)
+
+  def addUnexpectedSuccess(self, test):
+    super().addUnexpectedSuccess(test)
+    test_name = test.id() or str(test)
+    error_summary = ('error', '', '',
+                     'Test case %s should have failed, but passed.'
+                     % (test_name))
+    self.add_pending_test_case_result(test, error_summary=error_summary)
+
+  def addSubTest(self, test, subtest, err):  # pylint: disable=invalid-name
+    super().addSubTest(test, subtest, err)
+    if err is not None:
+      if issubclass(err[0], test.failureException):
+        error_summary = ('failure', err[0], err[1],
+                         self._exc_info_to_string(err, test=test))
+      else:
+        error_summary = ('error', err[0], err[1],
+                         self._exc_info_to_string(err, test=test))
+    else:
+      error_summary = None
+    self.add_pending_test_case_result(subtest, error_summary=error_summary)
+
+  def printErrors(self):
+    super().printErrors()
+    self.xml_stream.write('<?xml version="1.0"?>\n')
+    self.suite.print_xml_summary(self.xml_stream)
+
+
+class TextAndXMLTestRunner(unittest.TextTestRunner):
+  """A test runner that produces both formatted text results and XML.
+
+  It prints out the names of tests as they are run, errors as they
+  occur, and a summary of the results at the end of the test run.
+  """
+
+  _TEST_RESULT_CLASS = _TextAndXMLTestResult
+
+  _xml_stream = None
+  _testsuites_properties: dict[Any, Any] = {}
+
+  def __init__(self, xml_stream=None, *args, **kwargs):
+    """Initialize a TextAndXMLTestRunner.
+
+    Args:
+      xml_stream: file-like or None; XML-formatted test results are output
+          via this object's write() method.  If None (the default), the
+          new instance behaves as described in the set_default_xml_stream method
+          documentation below.
+      *args: passed unmodified to unittest.TextTestRunner.__init__.
+      **kwargs: passed unmodified to unittest.TextTestRunner.__init__.
+    """
+    super().__init__(*args, **kwargs)
+    if xml_stream is not None:
+      self._xml_stream = xml_stream
+    # else, do not set self._xml_stream to None -- this allows implicit fallback
+    # to the class attribute's value.
+
+  @classmethod
+  def set_default_xml_stream(cls, xml_stream):
+    """Sets the default XML stream for the class.
+
+    Args:
+      xml_stream: file-like or None; used for instances when xml_stream is None
+          or not passed to their constructors.  If None is passed, instances
+          created with xml_stream=None will act as ordinary TextTestRunner
+          instances; this is the default state before any calls to this method
+          have been made.
+    """
+    cls._xml_stream = xml_stream
+
+  def _makeResult(self):
+    if self._xml_stream is None:
+      return super()._makeResult()
+    else:
+      return self._TEST_RESULT_CLASS(
+          self._xml_stream, self.stream, self.descriptions, self.verbosity,
+          testsuites_properties=self._testsuites_properties)
+
+  @classmethod
+  def set_testsuites_property(cls, key, value):
+    cls._testsuites_properties[key] = value

.venv/lib/python3.13/site-packages/black/resources/black.schema.json

@@ -0,0 +1,161 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://github.com/psf/black/blob/main/src/black/resources/black.schema.json",
+  "$comment": "tool.black table in pyproject.toml",
+  "type": "object",
+  "additionalProperties": false,
+  "properties": {
+    "code": {
+      "type": "string",
+      "description": "Format the code passed in as a string."
+    },
+    "line-length": {
+      "type": "integer",
+      "description": "How many characters per line to allow.",
+      "default": 88
+    },
+    "target-version": {
+      "type": "array",
+      "items": {
+        "enum": [
+          "py33",
+          "py34",
+          "py35",
+          "py36",
+          "py37",
+          "py38",
+          "py39",
+          "py310",
+          "py311",
+          "py312",
+          "py313",
+          "py314"
+        ]
+      },
+      "description": "Python versions that should be supported by Black's output. You should include all versions that your code supports. By default, Black will infer target versions from the project metadata in pyproject.toml. If this does not yield conclusive results, Black will use per-file auto-detection."
+    },
+    "pyi": {
+      "type": "boolean",
+      "description": "Format all input files like typing stubs regardless of file extension. This is useful when piping source on standard input.",
+      "default": false
+    },
+    "ipynb": {
+      "type": "boolean",
+      "description": "Format all input files like Jupyter Notebooks regardless of file extension. This is useful when piping source on standard input.",
+      "default": false
+    },
+    "python-cell-magics": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      },
+      "description": "When processing Jupyter Notebooks, add the given magic to the list of known python-magics (capture, prun, pypy, python, python3, time, timeit). Useful for formatting cells with custom python magics."
+    },
+    "skip-source-first-line": {
+      "type": "boolean",
+      "description": "Skip the first line of the source code.",
+      "default": false
+    },
+    "skip-string-normalization": {
+      "type": "boolean",
+      "description": "Don't normalize string quotes or prefixes.",
+      "default": false
+    },
+    "skip-magic-trailing-comma": {
+      "type": "boolean",
+      "description": "Don't use trailing commas as a reason to split lines.",
+      "default": false
+    },
+    "preview": {
+      "type": "boolean",
+      "description": "Enable potentially disruptive style changes that may be added to Black's main functionality in the next major release.",
+      "default": false
+    },
+    "unstable": {
+      "type": "boolean",
+      "description": "Enable potentially disruptive style changes that have known bugs or are not currently expected to make it into the stable style Black's next major release. Implies --preview.",
+      "default": false
+    },
+    "enable-unstable-feature": {
+      "type": "array",
+      "items": {
+        "enum": [
+          "string_processing",
+          "hug_parens_with_braces_and_square_brackets",
+          "wrap_long_dict_values_in_parens",
+          "multiline_string_handling",
+          "always_one_newline_after_import",
+          "fix_fmt_skip_in_one_liners",
+          "standardize_type_comments",
+          "wrap_comprehension_in",
+          "remove_parens_around_except_types",
+          "normalize_cr_newlines",
+          "fix_module_docstring_detection",
+          "fix_type_expansion_split",
+          "remove_parens_from_assignment_lhs"
+        ]
+      },
+      "description": "Enable specific features included in the `--unstable` style. Requires `--preview`. No compatibility guarantees are provided on the behavior or existence of any unstable features."
+    },
+    "check": {
+      "type": "boolean",
+      "description": "Don't write the files back, just return the status. Return code 0 means nothing would change. Return code 1 means some files would be reformatted. Return code 123 means there was an internal error.",
+      "default": false
+    },
+    "diff": {
+      "type": "boolean",
+      "description": "Don't write the files back, just output a diff to indicate what changes Black would've made. They are printed to stdout so capturing them is simple.",
+      "default": false
+    },
+    "color": {
+      "type": "boolean",
+      "description": "Show (or do not show) colored diff. Only applies when --diff is given.",
+      "default": false
+    },
+    "fast": {
+      "type": "boolean",
+      "description": "By default, Black performs an AST safety check after formatting your code. The --fast flag turns off this check and the --safe flag explicitly enables it. [default: --safe]",
+      "default": false
+    },
+    "required-version": {
+      "type": "string",
+      "description": "Require a specific version of Black to be running. This is useful for ensuring that all contributors to your project are using the same version, because different versions of Black may format code a little differently. This option can be set in a configuration file for consistent results across environments."
+    },
+    "exclude": {
+      "type": "string",
+      "description": "A regular expression that matches files and directories that should be excluded on recursive searches. An empty value means no paths are excluded. Use forward slashes for directories on all platforms (Windows, too). By default, Black also ignores all paths listed in .gitignore. Changing this value will override all default exclusions. [default: /(\\.direnv|\\.eggs|\\.git|\\.hg|\\.ipynb_checkpoints|\\.mypy_cache|\\.nox|\\.pytest_cache|\\.ruff_cache|\\.tox|\\.svn|\\.venv|\\.vscode|__pypackages__|_build|buck-out|build|dist|venv)/]"
+    },
+    "extend-exclude": {
+      "type": "string",
+      "description": "Like --exclude, but adds additional files and directories on top of the default values instead of overriding them."
+    },
+    "force-exclude": {
+      "type": "string",
+      "description": "Like --exclude, but files and directories matching this regex will be excluded even when they are passed explicitly as arguments. This is useful when invoking Black programmatically on changed files, such as in a pre-commit hook or editor plugin."
+    },
+    "include": {
+      "type": "string",
+      "description": "A regular expression that matches files and directories that should be included on recursive searches. An empty value means all files are included regardless of the name. Use forward slashes for directories on all platforms (Windows, too). Overrides all exclusions, including from .gitignore and command line options.",
+      "default": "(\\.pyi?|\\.ipynb)$"
+    },
+    "workers": {
+      "type": "integer",
+      "description": "When Black formats multiple files, it may use a process pool to speed up formatting. This option controls the number of parallel workers. This can also be specified via the BLACK_NUM_WORKERS environment variable. Defaults to the number of CPUs in the system."
+    },
+    "quiet": {
+      "type": "boolean",
+      "description": "Stop emitting all non-critical output. Error messages will still be emitted (which can silenced by 2>/dev/null).",
+      "default": false
+    },
+    "verbose": {
+      "type": "boolean",
+      "description": "Emit messages about files that were not changed or were ignored due to exclusion patterns. If Black is using a configuration file, a message detailing which one it is using will be emitted.",
+      "default": false
+    },
+    "no-cache": {
+      "type": "boolean",
+      "description": "Skip reading and writing the cache, forcing Black to reformat all included files.",
+      "default": false
+    }
+  }
+}