Add files using upload-large-folder tool

lib/python3.12/site-packages/absl/__init__.py

@@ -0,0 +1,15 @@
+# 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.
+
+__version__ = '2.4.0'

lib/python3.12/site-packages/absl/app.py

@@ -0,0 +1,539 @@
+# 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.
+
+"""Generic entry point for Abseil Python applications.
+
+To use this module, define a ``main`` function with a single ``argv`` argument
+and call ``app.run(main)``. For example::
+
+    def main(argv):
+      if len(argv) > 1:
+        raise app.UsageError('Too many command-line arguments.')
+
+    if __name__ == '__main__':
+      app.run(main)
+"""
+
+import collections
+import errno
+import importlib
+import os
+import pdb
+import sys
+import textwrap
+import traceback
+
+from absl import command_name
+from absl import flags
+from absl import logging
+
+try:
+  import faulthandler
+except ImportError:
+  faulthandler = None
+
+FLAGS = flags.FLAGS
+
+flags.DEFINE_boolean(
+    'run_with_pdb',
+    False,
+    'Set to true for debug mode. PDB is used by default; $PYTHONBREAKPOINT '
+    '(https://docs.python.org/3/using/cmdline.html#envvar-PYTHONBREAKPOINT) '
+    'can be used to specify a custom debugger.',
+)
+flags.DEFINE_boolean(
+    'pdb_post_mortem',
+    False,
+    'Set to true to handle uncaught exceptions with the post mortem debugger. '
+    'PDB is used by default; $PYTHONBREAKPOINT '
+    '(https://docs.python.org/3/using/cmdline.html#envvar-PYTHONBREAKPOINT) '
+    'can be used to specify a custom one.',
+)
+flags.DEFINE_alias('pdb', 'pdb_post_mortem')
+flags.DEFINE_boolean('run_with_profiling', False,
+                     'Set to true for profiling the script. '
+                     'Execution will be slower, and the output format might '
+                     'change over time.')
+flags.DEFINE_string('profile_file', None,
+                    'Dump profile information to a file (for python -m '
+                    'pstats). Implies --run_with_profiling.')
+flags.DEFINE_boolean('use_cprofile_for_profiling', True,
+                     'Use cProfile instead of the profile module for '
+                     'profiling. This has no effect unless '
+                     '--run_with_profiling is set.')
+flags.DEFINE_boolean('only_check_args', False,
+                     'Set to true to validate args and exit.',
+                     allow_hide_cpp=True)
+
+
+def _get_debugger_module_with_function(function_name):
+  """Provides the `$PYTHONBREAKPOINT` module if it contains `function_name`.
+
+  Falls back to `pdb` otherwise.
+
+  Args:
+    function_name: The name of the function required.
+
+  Returns:
+    A debugger module providing `function_name`.
+  """
+  python_breakpoint = os.getenv('PYTHONBREAKPOINT')
+  # The special value '0' for `$PYTHONBREAKPOINT` means "do not use a debugger".
+  # We don't respect it (if the user explicitly asks to debug) but shouldn't try
+  # to import a module with this name.
+  if python_breakpoint and python_breakpoint != '0':
+    debugger_module_import = python_breakpoint.rsplit('.', 1)[0]
+    try:
+      debugger_module = importlib.import_module(debugger_module_import)
+    except ImportError:
+      logging.warning(
+          (
+              'Could not import $PYTHONBREAKPOINT debugger module %r, '
+              'falling back to PDB'
+          ),
+          debugger_module_import,
+      )
+    else:
+      if hasattr(debugger_module, function_name):
+        return debugger_module
+      logging.warning(
+          '$PYTHONBREAKPOINT debugger %r has no function %r, '
+          'falling back to PDB',
+          debugger_module_import,
+          function_name,
+      )
+  return pdb
+
+
+# If main() exits via an abnormal exception, call into these
+# handlers before exiting.
+EXCEPTION_HANDLERS = []
+
+
+class Error(Exception):
+  pass
+
+
+class UsageError(Error):
+  """Exception raised when the arguments supplied by the user are invalid.
+
+  Raise this when the arguments supplied are invalid from the point of
+  view of the application. For example when two mutually exclusive
+  flags have been supplied or when there are not enough non-flag
+  arguments. It is distinct from flags.Error which covers the lower
+  level of parsing and validating individual flags.
+  """
+
+  def __init__(self, message, exitcode=1):
+    super().__init__(message)
+    self.exitcode = exitcode
+
+
+class HelpFlag(flags.BooleanFlag):
+  """Special boolean flag that displays usage and raises SystemExit."""
+  NAME = 'help'
+  SHORT_NAME = '?'
+
+  def __init__(self):
+    super().__init__(
+        self.NAME,
+        False,
+        'show this help',
+        short_name=self.SHORT_NAME,
+        allow_hide_cpp=True,
+    )
+
+  def parse(self, arg):
+    if self._parse(arg):
+      usage(shorthelp=True, writeto_stdout=True)
+      # Advertise --helpfull on stdout, since usage() was on stdout.
+      print()
+      print('Try --helpfull to get a list of all flags.')
+      sys.exit(1)
+
+
+class HelpshortFlag(HelpFlag):
+  """--helpshort is an alias for --help."""
+  NAME = 'helpshort'
+  SHORT_NAME = None
+
+
+class HelpfullFlag(flags.BooleanFlag):
+  """Display help for flags in the main module and all dependent modules."""
+
+  def __init__(self):
+    super().__init__('helpfull', False, 'show full help', allow_hide_cpp=True)
+
+  def parse(self, arg):
+    if self._parse(arg):
+      usage(writeto_stdout=True)
+      sys.exit(1)
+
+
+class HelpXMLFlag(flags.BooleanFlag):
+  """Similar to HelpfullFlag, but generates output in XML format."""
+
+  def __init__(self):
+    super().__init__(
+        'helpxml',
+        False,
+        'like --helpfull, but generates XML output',
+        allow_hide_cpp=True,
+    )
+
+  def parse(self, arg):
+    if self._parse(arg):
+      flags.FLAGS.write_help_in_xml_format(sys.stdout)
+      sys.exit(1)
+
+
+def parse_flags_with_usage(args):
+  """Tries to parse the flags, print usage, and exit if unparsable.
+
+  Args:
+    args: [str], a non-empty list of the command line arguments including
+        program name.
+
+  Returns:
+    [str], a non-empty list of remaining command line arguments after parsing
+    flags, including program name.
+  """
+  try:
+    return FLAGS(args)
+  except flags.Error as error:
+    message = str(error)
+    if '\n' in message:
+      final_message = 'FATAL Flags parsing error:\n%s\n' % textwrap.indent(
+          message, '  ')
+    else:
+      final_message = 'FATAL Flags parsing error: %s\n' % message
+    sys.stderr.write(final_message)
+    sys.stderr.write('Pass --helpshort or --helpfull to see help on flags.\n')
+    sys.exit(1)
+
+
+_define_help_flags_called = False
+
+
+def define_help_flags():
+  """Registers help flags. Idempotent."""
+  # Use a global to ensure idempotence.
+  global _define_help_flags_called
+
+  if not _define_help_flags_called:
+    flags.DEFINE_flag(HelpFlag())
+    flags.DEFINE_flag(HelpshortFlag())  # alias for --help
+    flags.DEFINE_flag(HelpfullFlag())
+    flags.DEFINE_flag(HelpXMLFlag())
+    _define_help_flags_called = True
+
+
+def _register_and_parse_flags_with_usage(
+    argv=None,
+    flags_parser=parse_flags_with_usage,
+):
+  """Registers help flags, parses arguments and shows usage if appropriate.
+
+  This also calls sys.exit(0) if flag --only_check_args is True.
+
+  Args:
+    argv: [str], a non-empty list of the command line arguments including
+      program name, sys.argv is used if None.
+    flags_parser: Callable[[List[str]], Any], the function used to parse flags.
+      The return value of this function is passed to `main` untouched. It must
+      guarantee FLAGS is parsed after this function is called.
+
+  Returns:
+    The return value of `flags_parser`. When using the default `flags_parser`,
+    it returns the following:
+    [str], a non-empty list of remaining command line arguments after parsing
+    flags, including program name.
+
+  Raises:
+    Error: Raised when flags_parser is called, but FLAGS is not parsed.
+    SystemError: Raised when it's called more than once.
+  """
+  # fmt: on
+  if _register_and_parse_flags_with_usage.done:
+    raise SystemError('Flag registration can be done only once.')
+
+  define_help_flags()
+
+  original_argv = sys.argv if argv is None else argv
+  args_to_main = flags_parser(original_argv)
+  if not FLAGS.is_parsed():
+    raise Error('FLAGS must be parsed after flags_parser is called.')
+
+  # Exit when told so.
+  if FLAGS.only_check_args:
+    sys.exit(0)
+  # Immediately after flags are parsed, bump verbosity to INFO if the flag has
+  # not been set.
+  if FLAGS['verbosity'].using_default_value:
+    FLAGS.verbosity = 0
+  _register_and_parse_flags_with_usage.done = True
+
+  return args_to_main
+
+_register_and_parse_flags_with_usage.done = False
+
+
+def _run_main(main, argv):
+  """Calls main, optionally with a debugger or profiler."""
+  if FLAGS.run_with_pdb:
+    sys.exit(_get_debugger_module_with_function('runcall').runcall(main, argv))
+  elif FLAGS.run_with_profiling or FLAGS.profile_file:
+    # Avoid import overhead since most apps (including performance-sensitive
+    # ones) won't be run with profiling.
+    # pylint: disable=g-import-not-at-top
+    import atexit
+    if FLAGS.use_cprofile_for_profiling:
+      import cProfile as profile
+    else:
+      import profile
+    profiler = profile.Profile()
+    if FLAGS.profile_file:
+      atexit.register(profiler.dump_stats, FLAGS.profile_file)
+    else:
+      atexit.register(profiler.print_stats)
+    sys.exit(profiler.runcall(main, argv))
+  else:
+    sys.exit(main(argv))
+
+
+def _call_exception_handlers(exception):
+  """Calls any installed exception handlers."""
+  for handler in EXCEPTION_HANDLERS:
+    try:
+      if handler.wants(exception):
+        handler.handle(exception)
+    except:  # pylint: disable=bare-except
+      try:
+        # We don't want to stop for exceptions in the exception handlers but
+        # we shouldn't hide them either.
+        logging.error(traceback.format_exc())
+      except:  # pylint: disable=bare-except
+        # In case even the logging statement fails, ignore.
+        pass
+
+
+def run(
+    main,
+    argv=None,
+    flags_parser=parse_flags_with_usage,
+):
+  """Begins executing the program.
+
+  Args:
+    main: The main function to execute. It takes an single argument "argv",
+        which is a list of command line arguments with parsed flags removed.
+        The return value is passed to `sys.exit`, and so for example
+        a return value of 0 or None results in a successful termination, whereas
+        a return value of 1 results in abnormal termination.
+        For more details, see https://docs.python.org/3/library/sys#sys.exit
+    argv: A non-empty list of the command line arguments including program name,
+        sys.argv is used if None.
+    flags_parser: Callable[[List[str]], Any], the function used to parse flags.
+        The return value of this function is passed to `main` untouched.
+        It must guarantee FLAGS is parsed after this function is called.
+        Should be passed as a keyword-only arg which will become mandatory in a
+        future release.
+  - Parses command line flags with the flag module.
+  - If there are any errors, prints usage().
+  - Calls main() with the remaining arguments.
+  - If main() raises a UsageError, prints usage and the error message.
+  """
+  # fmt: on
+  try:
+    args = _run_init(
+        sys.argv if argv is None else argv,
+        flags_parser,
+    )
+    while _init_callbacks:
+      callback = _init_callbacks.popleft()
+      callback()
+    try:
+      _run_main(main, args)
+    except UsageError as error:
+      usage(shorthelp=True, detailed_error=error, exitcode=error.exitcode)
+    except:
+      exc = sys.exc_info()[1]
+      # Don't try to post-mortem debug successful SystemExits, since those
+      # mean there wasn't actually an error. In particular, the test framework
+      # raises SystemExit(False) even if all tests passed.
+      if isinstance(exc, SystemExit) and not exc.code:
+        raise
+
+      # Check the tty so that we don't hang waiting for input in an
+      # non-interactive scenario.
+      if FLAGS.pdb_post_mortem and sys.stdout.isatty():
+        traceback.print_exc()
+        print()
+        print(' *** Entering post-mortem debugging ***')
+        print()
+        _get_debugger_module_with_function('post_mortem').post_mortem()
+      raise
+  except Exception as e:
+    _call_exception_handlers(e)
+    raise
+
+# Callbacks which have been deferred until after _run_init has been called.
+_init_callbacks = collections.deque()
+
+
+def call_after_init(callback):
+  """Calls the given callback only once ABSL has finished initialization.
+
+  If ABSL has already finished initialization when ``call_after_init`` is
+  called then the callback is executed immediately, otherwise `callback` is
+  stored to be executed after ``app.run`` has finished initializing (aka. just
+  before the main function is called).
+
+  If called after ``app.run``, this is equivalent to calling ``callback()`` in
+  the caller thread. If called before ``app.run``, callbacks are run
+  sequentially (in an undefined order) in the same thread as ``app.run``.
+
+  Args:
+    callback: a callable to be called once ABSL has finished initialization.
+      This may be immediate if initialization has already finished. It
+      takes no arguments and returns nothing.
+  """
+  if _run_init.done:
+    callback()
+  else:
+    _init_callbacks.append(callback)
+
+
+def _run_init(
+    argv,
+    flags_parser,
+):
+  """Does one-time initialization and re-parses flags on rerun."""
+  if _run_init.done:
+    return flags_parser(argv)
+  command_name.make_process_name_useful()
+  # Set up absl logging handler.
+  logging.use_absl_handler()
+  args = _register_and_parse_flags_with_usage(
+      argv=argv,
+      flags_parser=flags_parser,
+  )
+  if faulthandler:
+    try:
+      faulthandler.enable()
+    except Exception:  # pylint: disable=broad-except
+      # Some tests verify stderr output very closely, so don't print anything.
+      # Disabled faulthandler is a low-impact error.
+      pass
+  _run_init.done = True
+  return args
+
+
+_run_init.done = False
+
+
+def usage(shorthelp=False, writeto_stdout=False, detailed_error=None,
+          exitcode=None):
+  """Writes __main__'s docstring to stderr with some help text.
+
+  Args:
+    shorthelp: bool, if True, prints only flags from the main module,
+        rather than all flags.
+    writeto_stdout: bool, if True, writes help message to stdout,
+        rather than to stderr.
+    detailed_error: str, additional detail about why usage info was presented.
+    exitcode: optional integer, if set, exits with this status code after
+        writing help.
+  """
+  if writeto_stdout:
+    stdfile = sys.stdout
+  else:
+    stdfile = sys.stderr
+
+  doc = sys.modules['__main__'].__doc__
+  if not doc:
+    doc = '\nUSAGE: %s [flags]\n' % sys.argv[0]
+    doc = flags.text_wrap(doc, indent='       ', firstline_indent='')
+  else:
+    # Replace all '%s' with sys.argv[0], and all '%%' with '%'.
+    num_specifiers = doc.count('%') - 2 * doc.count('%%')
+    try:
+      doc %= (sys.argv[0],) * num_specifiers
+    except (OverflowError, TypeError, ValueError):
+      # Just display the docstring as-is.
+      pass
+  if shorthelp:
+    flag_str = FLAGS.main_module_help()
+  else:
+    flag_str = FLAGS.get_help()
+  try:
+    stdfile.write(doc)
+    if flag_str:
+      stdfile.write('\nflags:\n')
+      stdfile.write(flag_str)
+    stdfile.write('\n')
+    if detailed_error is not None:
+      stdfile.write('\n%s\n' % detailed_error)
+  except OSError as e:
+    # We avoid printing a huge backtrace if we get EPIPE, because
+    # "foo.par --help | less" is a frequent use case.
+    if e.errno != errno.EPIPE:
+      raise
+  if exitcode is not None:
+    sys.exit(exitcode)
+
+
+class ExceptionHandler:
+  """Base exception handler from which other may inherit."""
+
+  def wants(self, exc):
+    """Returns whether this handler wants to handle the exception or not.
+
+    This base class returns True for all exceptions by default. Override in
+    subclass if it wants to be more selective.
+
+    Args:
+      exc: Exception, the current exception.
+    """
+    del exc  # Unused.
+    return True
+
+  def handle(self, exc):
+    """Do something with the current exception.
+
+    Args:
+      exc: Exception, the current exception
+
+    This method must be overridden.
+    """
+    raise NotImplementedError()
+
+
+def install_exception_handler(handler):
+  """Installs an exception handler.
+
+  Args:
+    handler: ExceptionHandler, the exception handler to install.
+
+  Raises:
+    TypeError: Raised when the handler was not of the correct type.
+
+  All installed exception handlers will be called if main() exits via
+  an abnormal exception, i.e. not one of SystemExit, KeyboardInterrupt,
+  FlagsError or UsageError.
+  """
+  if not isinstance(handler, ExceptionHandler):
+    raise TypeError('handler of type %s does not inherit from ExceptionHandler'
+                    % type(handler))
+  EXCEPTION_HANDLERS.append(handler)

lib/python3.12/site-packages/absl/app.pyi

@@ -0,0 +1,89 @@
+from collections.abc import Callable
+from typing import Any, NoReturn, TypeVar, overload
+
+from absl.flags import _flag
+
+_MainArgs = TypeVar('_MainArgs')
+_Exc = TypeVar('_Exc', bound=Exception)
+
+class ExceptionHandler:
+
+  def wants(self, exc: _Exc) -> bool:
+    ...
+
+  def handle(self, exc: _Exc):
+    ...
+
+EXCEPTION_HANDLERS: list[ExceptionHandler] = ...
+
+class HelpFlag(_flag.BooleanFlag):
+  def __init__(self):
+    ...
+
+class HelpshortFlag(HelpFlag):
+  ...
+
+class HelpfullFlag(_flag.BooleanFlag):
+  def __init__(self):
+    ...
+
+class HelpXMLFlag(_flag.BooleanFlag):
+  def __init__(self):
+    ...
+
+def define_help_flags() -> None:
+  ...
+
+@overload
+def usage(shorthelp: bool | int = ...,
+          writeto_stdout: bool | int = ...,
+          detailed_error: Any | None = ...,
+          exitcode: None = ...) -> None:
+  ...
+
+@overload
+def usage(shorthelp: bool | int,
+          writeto_stdout: bool | int,
+          detailed_error: Any | None,
+          exitcode: int) -> NoReturn:
+  ...
+
+@overload
+def usage(shorthelp: bool | int = ...,
+          writeto_stdout: bool | int = ...,
+          detailed_error: Any | None = ...,
+          *,
+          exitcode: int) -> NoReturn:
+  ...
+
+def install_exception_handler(handler: ExceptionHandler) -> None:
+  ...
+
+class Error(Exception):
+  ...
+
+class UsageError(Error):
+  exitcode: int
+
+def parse_flags_with_usage(args: list[str]) -> list[str]:
+  ...
+
+def call_after_init(callback: Callable[[], Any]) -> None:
+  ...
+
+# Without the flag_parser argument, `main` should require a List[str].
+@overload
+def run(
+    main: Callable[[list[str]], Any],
+    argv: list[str] | None = ...,
+) -> NoReturn:
+  ...
+
+@overload
+def run(
+    main: Callable[[_MainArgs], Any],
+    argv: list[str] | None = ...,
+    *,
+    flags_parser: Callable[[list[str]], _MainArgs],
+) -> NoReturn:
+  ...

lib/python3.12/site-packages/absl/command_name.py

@@ -0,0 +1,63 @@
+# 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 tiny stand alone library to change the kernel process name on Linux."""
+
+import os
+import sys
+
+# This library must be kept small and stand alone.  It is used by small things
+# that require no extension modules.
+
+
+def make_process_name_useful():
+  """Sets the process name to something better than 'python' if possible."""
+  set_kernel_process_name(os.path.basename(sys.argv[0]))
+
+
+def set_kernel_process_name(name):
+  """Changes the Kernel's /proc/self/status process name on Linux.
+
+  The kernel name is NOT what will be shown by the ps or top command.
+  It is a 15 character string stored in the kernel's process table that
+  is included in the kernel log when a process is OOM killed.
+  The first 15 bytes of name are used.  Non-ASCII unicode is replaced with '?'.
+
+  Does nothing if /proc/self/comm cannot be written or prctl() fails.
+
+  Args:
+    name: bytes|unicode, the Linux kernel's command name to set.
+  """
+  if not isinstance(name, bytes):
+    name = name.encode('ascii', 'replace')
+  try:
+    # This is preferred to using ctypes to try and call prctl() when possible.
+    with open('/proc/self/comm', 'wb') as proc_comm:
+      proc_comm.write(name[:15])
+  except OSError:
+    try:
+      import ctypes  # pylint: disable=g-import-not-at-top
+    except ImportError:
+      return  # No ctypes.
+    try:
+      libc = ctypes.CDLL('libc.so.6')
+    except OSError:
+      return  # No libc.so.6.
+    pr_set_name = ctypes.c_ulong(15)  # linux/prctl.h PR_SET_NAME value.
+    zero = ctypes.c_ulong(0)
+    try:
+      libc.prctl(pr_set_name, name, zero, zero, zero)
+      # Ignore the prctl return value.  Nothing we can do if it errored.
+    except AttributeError:
+      return  # No prctl.

lib/python3.12/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

lib/python3.12/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

lib/python3.12/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)

lib/python3.12/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."""

lib/python3.12/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

lib/python3.12/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

lib/python3.12/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

lib/python3.12/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)

lib/python3.12/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

lib/python3.12/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

lib/python3.12/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()

lib/python3.12/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:
+  ...

lib/python3.12/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))

lib/python3.12/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.

lib/python3.12/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)

lib/python3.12/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)

lib/python3.12/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

lib/python3.12/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

lib/python3.12/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

lib/python3.12/site-packages/jinja2-3.1.6.dist-info/INSTALLER

@@ -0,0 +1 @@
+pip

lib/python3.12/site-packages/jinja2-3.1.6.dist-info/METADATA

@@ -0,0 +1,84 @@
+Metadata-Version: 2.4
+Name: Jinja2
+Version: 3.1.6
+Summary: A very fast and expressive template engine.
+Maintainer-email: Pallets <contact@palletsprojects.com>
+Requires-Python: >=3.7
+Description-Content-Type: text/markdown
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Environment :: Web Environment
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: BSD License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python
+Classifier: Topic :: Internet :: WWW/HTTP :: Dynamic Content
+Classifier: Topic :: Text Processing :: Markup :: HTML
+Classifier: Typing :: Typed
+License-File: LICENSE.txt
+Requires-Dist: MarkupSafe>=2.0
+Requires-Dist: Babel>=2.7 ; extra == "i18n"
+Project-URL: Changes, https://jinja.palletsprojects.com/changes/
+Project-URL: Chat, https://discord.gg/pallets
+Project-URL: Documentation, https://jinja.palletsprojects.com/
+Project-URL: Donate, https://palletsprojects.com/donate
+Project-URL: Source, https://github.com/pallets/jinja/
+Provides-Extra: i18n
+
+# Jinja
+
+Jinja is a fast, expressive, extensible templating engine. Special
+placeholders in the template allow writing code similar to Python
+syntax. Then the template is passed data to render the final document.
+
+It includes:
+
+-   Template inheritance and inclusion.
+-   Define and import macros within templates.
+-   HTML templates can use autoescaping to prevent XSS from untrusted
+    user input.
+-   A sandboxed environment can safely render untrusted templates.
+-   AsyncIO support for generating templates and calling async
+    functions.
+-   I18N support with Babel.
+-   Templates are compiled to optimized Python code just-in-time and
+    cached, or can be compiled ahead-of-time.
+-   Exceptions point to the correct line in templates to make debugging
+    easier.
+-   Extensible filters, tests, functions, and even syntax.
+
+Jinja's philosophy is that while application logic belongs in Python if
+possible, it shouldn't make the template designer's job difficult by
+restricting functionality too much.
+
+
+## In A Nutshell
+
+```jinja
+{% extends "base.html" %}
+{% block title %}Members{% endblock %}
+{% block content %}
+  <ul>
+  {% for user in users %}
+    <li><a href="{{ user.url }}">{{ user.username }}</a></li>
+  {% endfor %}
+  </ul>
+{% endblock %}
+```
+
+## Donate
+
+The Pallets organization develops and supports Jinja and other popular
+packages. In order to grow the community of contributors and users, and
+allow the maintainers to devote more time to the projects, [please
+donate today][].
+
+[please donate today]: https://palletsprojects.com/donate
+
+## Contributing
+
+See our [detailed contributing documentation][contrib] for many ways to
+contribute, including reporting issues, requesting features, asking or answering
+questions, and making PRs.
+
+[contrib]: https://palletsprojects.com/contributing/
+

lib/python3.12/site-packages/jinja2-3.1.6.dist-info/RECORD

@@ -0,0 +1,57 @@
+jinja2-3.1.6.dist-info/INSTALLER,sha256=zuuue4knoyJ-UwPPXg8fezS7VCrXJQrAP7zeNuwvFQg,4
+jinja2-3.1.6.dist-info/METADATA,sha256=aMVUj7Z8QTKhOJjZsx7FDGvqKr3ZFdkh8hQ1XDpkmcg,2871
+jinja2-3.1.6.dist-info/RECORD,,
+jinja2-3.1.6.dist-info/WHEEL,sha256=_2ozNFCLWc93bK4WKHCO-eDUENDlo-dgc9cU3qokYO4,82
+jinja2-3.1.6.dist-info/entry_points.txt,sha256=OL85gYU1eD8cuPlikifFngXpeBjaxl6rIJ8KkC_3r-I,58
+jinja2-3.1.6.dist-info/licenses/LICENSE.txt,sha256=O0nc7kEF6ze6wQ-vG-JgQI_oXSUrjp3y4JefweCUQ3s,1475
+jinja2/__init__.py,sha256=xxepO9i7DHsqkQrgBEduLtfoz2QCuT6_gbL4XSN1hbU,1928
+jinja2/__pycache__/__init__.cpython-312.pyc,,
+jinja2/__pycache__/_identifier.cpython-312.pyc,,
+jinja2/__pycache__/async_utils.cpython-312.pyc,,
+jinja2/__pycache__/bccache.cpython-312.pyc,,
+jinja2/__pycache__/compiler.cpython-312.pyc,,
+jinja2/__pycache__/constants.cpython-312.pyc,,
+jinja2/__pycache__/debug.cpython-312.pyc,,
+jinja2/__pycache__/defaults.cpython-312.pyc,,
+jinja2/__pycache__/environment.cpython-312.pyc,,
+jinja2/__pycache__/exceptions.cpython-312.pyc,,
+jinja2/__pycache__/ext.cpython-312.pyc,,
+jinja2/__pycache__/filters.cpython-312.pyc,,
+jinja2/__pycache__/idtracking.cpython-312.pyc,,
+jinja2/__pycache__/lexer.cpython-312.pyc,,
+jinja2/__pycache__/loaders.cpython-312.pyc,,
+jinja2/__pycache__/meta.cpython-312.pyc,,
+jinja2/__pycache__/nativetypes.cpython-312.pyc,,
+jinja2/__pycache__/nodes.cpython-312.pyc,,
+jinja2/__pycache__/optimizer.cpython-312.pyc,,
+jinja2/__pycache__/parser.cpython-312.pyc,,
+jinja2/__pycache__/runtime.cpython-312.pyc,,
+jinja2/__pycache__/sandbox.cpython-312.pyc,,
+jinja2/__pycache__/tests.cpython-312.pyc,,
+jinja2/__pycache__/utils.cpython-312.pyc,,
+jinja2/__pycache__/visitor.cpython-312.pyc,,
+jinja2/_identifier.py,sha256=_zYctNKzRqlk_murTNlzrju1FFJL7Va_Ijqqd7ii2lU,1958
+jinja2/async_utils.py,sha256=vK-PdsuorOMnWSnEkT3iUJRIkTnYgO2T6MnGxDgHI5o,2834
+jinja2/bccache.py,sha256=gh0qs9rulnXo0PhX5jTJy2UHzI8wFnQ63o_vw7nhzRg,14061
+jinja2/compiler.py,sha256=9RpCQl5X88BHllJiPsHPh295Hh0uApvwFJNQuutULeM,74131
+jinja2/constants.py,sha256=GMoFydBF_kdpaRKPoM5cl5MviquVRLVyZtfp5-16jg0,1433
+jinja2/debug.py,sha256=CnHqCDHd-BVGvti_8ZsTolnXNhA3ECsY-6n_2pwU8Hw,6297
+jinja2/defaults.py,sha256=boBcSw78h-lp20YbaXSJsqkAI2uN_mD_TtCydpeq5wU,1267
+jinja2/environment.py,sha256=9nhrP7Ch-NbGX00wvyr4yy-uhNHq2OCc60ggGrni_fk,61513
+jinja2/exceptions.py,sha256=ioHeHrWwCWNaXX1inHmHVblvc4haO7AXsjCp3GfWvx0,5071
+jinja2/ext.py,sha256=5PF5eHfh8mXAIxXHHRB2xXbXohi8pE3nHSOxa66uS7E,31875
+jinja2/filters.py,sha256=PQ_Egd9n9jSgtnGQYyF4K5j2nYwhUIulhPnyimkdr-k,55212
+jinja2/idtracking.py,sha256=-ll5lIp73pML3ErUYiIJj7tdmWxcH_IlDv3yA_hiZYo,10555
+jinja2/lexer.py,sha256=LYiYio6br-Tep9nPcupWXsPEtjluw3p1mU-lNBVRUfk,29786
+jinja2/loaders.py,sha256=wIrnxjvcbqh5VwW28NSkfotiDq8qNCxIOSFbGUiSLB4,24055
+jinja2/meta.py,sha256=OTDPkaFvU2Hgvx-6akz7154F8BIWaRmvJcBFvwopHww,4397
+jinja2/nativetypes.py,sha256=7GIGALVJgdyL80oZJdQUaUfwSt5q2lSSZbXt0dNf_M4,4210
+jinja2/nodes.py,sha256=m1Duzcr6qhZI8JQ6VyJgUNinjAf5bQzijSmDnMsvUx8,34579
+jinja2/optimizer.py,sha256=rJnCRlQ7pZsEEmMhsQDgC_pKyDHxP5TPS6zVPGsgcu8,1651
+jinja2/parser.py,sha256=lLOFy3sEmHc5IaEHRiH1sQVnId2moUQzhyeJZTtdY30,40383
+jinja2/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+jinja2/runtime.py,sha256=gDk-GvdriJXqgsGbHgrcKTP0Yp6zPXzhzrIpCFH3jAU,34249
+jinja2/sandbox.py,sha256=Mw2aitlY2I8la7FYhcX2YG9BtUYcLnD0Gh3d29cDWrY,15009
+jinja2/tests.py,sha256=VLsBhVFnWg-PxSBz1MhRnNWgP1ovXk3neO1FLQMeC9Q,5926
+jinja2/utils.py,sha256=rRp3o9e7ZKS4fyrWRbELyLcpuGVTFcnooaOa1qx_FIk,24129
+jinja2/visitor.py,sha256=EcnL1PIwf_4RVCOMxsRNuR8AXHbS1qfAdMOE2ngKJz4,3557

lib/python3.12/site-packages/jinja2-3.1.6.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: flit 3.11.0
+Root-Is-Purelib: true
+Tag: py3-none-any