Add files using upload-large-folder tool

.gitattributes

@@ -180,3 +180,4 @@ tuning-competition-baseline/.venv/lib/python3.11/site-packages/torch/_inductor/_
 .venv/lib/python3.11/site-packages/ray/rllib/algorithms/__pycache__/algorithm_config.cpython-311.pyc filter=lfs diff=lfs merge=lfs -text
 .venv/lib/python3.11/site-packages/ray/rllib/env/__pycache__/multi_agent_episode.cpython-311.pyc filter=lfs diff=lfs merge=lfs -text
 .venv/lib/python3.11/site-packages/ray/tune/execution/__pycache__/tune_controller.cpython-311.pyc filter=lfs diff=lfs merge=lfs -text
+.venv/lib/python3.11/site-packages/ray/thirdparty_files/psutil/_psutil_linux.abi3.so filter=lfs diff=lfs merge=lfs -text

.venv/lib/python3.11/site-packages/_pytest/_argcomplete.py

@@ -0,0 +1,117 @@
+"""Allow bash-completion for argparse with argcomplete if installed.
+
+Needs argcomplete>=0.5.6 for python 3.2/3.3 (older versions fail
+to find the magic string, so _ARGCOMPLETE env. var is never set, and
+this does not need special code).
+
+Function try_argcomplete(parser) should be called directly before
+the call to ArgumentParser.parse_args().
+
+The filescompleter is what you normally would use on the positional
+arguments specification, in order to get "dirname/" after "dirn<TAB>"
+instead of the default "dirname ":
+
+   optparser.add_argument(Config._file_or_dir, nargs='*').completer=filescompleter
+
+Other, application specific, completers should go in the file
+doing the add_argument calls as they need to be specified as .completer
+attributes as well. (If argcomplete is not installed, the function the
+attribute points to will not be used).
+
+SPEEDUP
+=======
+
+The generic argcomplete script for bash-completion
+(/etc/bash_completion.d/python-argcomplete.sh)
+uses a python program to determine startup script generated by pip.
+You can speed up completion somewhat by changing this script to include
+  # PYTHON_ARGCOMPLETE_OK
+so the python-argcomplete-check-easy-install-script does not
+need to be called to find the entry point of the code and see if that is
+marked  with PYTHON_ARGCOMPLETE_OK.
+
+INSTALL/DEBUGGING
+=================
+
+To include this support in another application that has setup.py generated
+scripts:
+
+- Add the line:
+    # PYTHON_ARGCOMPLETE_OK
+  near the top of the main python entry point.
+
+- Include in the file calling parse_args():
+    from _argcomplete import try_argcomplete, filescompleter
+  Call try_argcomplete just before parse_args(), and optionally add
+  filescompleter to the positional arguments' add_argument().
+
+If things do not work right away:
+
+- Switch on argcomplete debugging with (also helpful when doing custom
+  completers):
+    export _ARC_DEBUG=1
+
+- Run:
+    python-argcomplete-check-easy-install-script $(which appname)
+    echo $?
+  will echo 0 if the magic line has been found, 1 if not.
+
+- Sometimes it helps to find early on errors using:
+    _ARGCOMPLETE=1 _ARC_DEBUG=1 appname
+  which should throw a KeyError: 'COMPLINE' (which is properly set by the
+  global argcomplete script).
+"""
+
+from __future__ import annotations
+
+import argparse
+from glob import glob
+import os
+import sys
+from typing import Any
+
+
+class FastFilesCompleter:
+    """Fast file completer class."""
+
+    def __init__(self, directories: bool = True) -> None:
+        self.directories = directories
+
+    def __call__(self, prefix: str, **kwargs: Any) -> list[str]:
+        # Only called on non option completions.
+        if os.sep in prefix[1:]:
+            prefix_dir = len(os.path.dirname(prefix) + os.sep)
+        else:
+            prefix_dir = 0
+        completion = []
+        globbed = []
+        if "*" not in prefix and "?" not in prefix:
+            # We are on unix, otherwise no bash.
+            if not prefix or prefix[-1] == os.sep:
+                globbed.extend(glob(prefix + ".*"))
+            prefix += "*"
+        globbed.extend(glob(prefix))
+        for x in sorted(globbed):
+            if os.path.isdir(x):
+                x += "/"
+            # Append stripping the prefix (like bash, not like compgen).
+            completion.append(x[prefix_dir:])
+        return completion
+
+
+if os.environ.get("_ARGCOMPLETE"):
+    try:
+        import argcomplete.completers
+    except ImportError:
+        sys.exit(-1)
+    filescompleter: FastFilesCompleter | None = FastFilesCompleter()
+
+    def try_argcomplete(parser: argparse.ArgumentParser) -> None:
+        argcomplete.autocomplete(parser, always_complete_options=False)
+
+else:
+
+    def try_argcomplete(parser: argparse.ArgumentParser) -> None:
+        pass
+
+    filescompleter = None

.venv/lib/python3.11/site-packages/_pytest/cacheprovider.py

@@ -0,0 +1,626 @@
+# mypy: allow-untyped-defs
+"""Implementation of the cache provider."""
+
+# This plugin was not named "cache" to avoid conflicts with the external
+# pytest-cache version.
+from __future__ import annotations
+
+import dataclasses
+import errno
+import json
+import os
+from pathlib import Path
+import tempfile
+from typing import final
+from typing import Generator
+from typing import Iterable
+
+from .pathlib import resolve_from_str
+from .pathlib import rm_rf
+from .reports import CollectReport
+from _pytest import nodes
+from _pytest._io import TerminalWriter
+from _pytest.config import Config
+from _pytest.config import ExitCode
+from _pytest.config import hookimpl
+from _pytest.config.argparsing import Parser
+from _pytest.deprecated import check_ispytest
+from _pytest.fixtures import fixture
+from _pytest.fixtures import FixtureRequest
+from _pytest.main import Session
+from _pytest.nodes import Directory
+from _pytest.nodes import File
+from _pytest.reports import TestReport
+
+
+README_CONTENT = """\
+# pytest cache directory #
+
+This directory contains data from the pytest's cache plugin,
+which provides the `--lf` and `--ff` options, as well as the `cache` fixture.
+
+**Do not** commit this to version control.
+
+See [the docs](https://docs.pytest.org/en/stable/how-to/cache.html) for more information.
+"""
+
+CACHEDIR_TAG_CONTENT = b"""\
+Signature: 8a477f597d28d172789f06886806bc55
+# This file is a cache directory tag created by pytest.
+# For information about cache directory tags, see:
+#	https://bford.info/cachedir/spec.html
+"""
+
+
+@final
+@dataclasses.dataclass
+class Cache:
+    """Instance of the `cache` fixture."""
+
+    _cachedir: Path = dataclasses.field(repr=False)
+    _config: Config = dataclasses.field(repr=False)
+
+    # Sub-directory under cache-dir for directories created by `mkdir()`.
+    _CACHE_PREFIX_DIRS = "d"
+
+    # Sub-directory under cache-dir for values created by `set()`.
+    _CACHE_PREFIX_VALUES = "v"
+
+    def __init__(
+        self, cachedir: Path, config: Config, *, _ispytest: bool = False
+    ) -> None:
+        check_ispytest(_ispytest)
+        self._cachedir = cachedir
+        self._config = config
+
+    @classmethod
+    def for_config(cls, config: Config, *, _ispytest: bool = False) -> Cache:
+        """Create the Cache instance for a Config.
+
+        :meta private:
+        """
+        check_ispytest(_ispytest)
+        cachedir = cls.cache_dir_from_config(config, _ispytest=True)
+        if config.getoption("cacheclear") and cachedir.is_dir():
+            cls.clear_cache(cachedir, _ispytest=True)
+        return cls(cachedir, config, _ispytest=True)
+
+    @classmethod
+    def clear_cache(cls, cachedir: Path, _ispytest: bool = False) -> None:
+        """Clear the sub-directories used to hold cached directories and values.
+
+        :meta private:
+        """
+        check_ispytest(_ispytest)
+        for prefix in (cls._CACHE_PREFIX_DIRS, cls._CACHE_PREFIX_VALUES):
+            d = cachedir / prefix
+            if d.is_dir():
+                rm_rf(d)
+
+    @staticmethod
+    def cache_dir_from_config(config: Config, *, _ispytest: bool = False) -> Path:
+        """Get the path to the cache directory for a Config.
+
+        :meta private:
+        """
+        check_ispytest(_ispytest)
+        return resolve_from_str(config.getini("cache_dir"), config.rootpath)
+
+    def warn(self, fmt: str, *, _ispytest: bool = False, **args: object) -> None:
+        """Issue a cache warning.
+
+        :meta private:
+        """
+        check_ispytest(_ispytest)
+        import warnings
+
+        from _pytest.warning_types import PytestCacheWarning
+
+        warnings.warn(
+            PytestCacheWarning(fmt.format(**args) if args else fmt),
+            self._config.hook,
+            stacklevel=3,
+        )
+
+    def _mkdir(self, path: Path) -> None:
+        self._ensure_cache_dir_and_supporting_files()
+        path.mkdir(exist_ok=True, parents=True)
+
+    def mkdir(self, name: str) -> Path:
+        """Return a directory path object with the given name.
+
+        If the directory does not yet exist, it will be created. You can use
+        it to manage files to e.g. store/retrieve database dumps across test
+        sessions.
+
+        .. versionadded:: 7.0
+
+        :param name:
+            Must be a string not containing a ``/`` separator.
+            Make sure the name contains your plugin or application
+            identifiers to prevent clashes with other cache users.
+        """
+        path = Path(name)
+        if len(path.parts) > 1:
+            raise ValueError("name is not allowed to contain path separators")
+        res = self._cachedir.joinpath(self._CACHE_PREFIX_DIRS, path)
+        self._mkdir(res)
+        return res
+
+    def _getvaluepath(self, key: str) -> Path:
+        return self._cachedir.joinpath(self._CACHE_PREFIX_VALUES, Path(key))
+
+    def get(self, key: str, default):
+        """Return the cached value for the given key.
+
+        If no value was yet cached or the value cannot be read, the specified
+        default is returned.
+
+        :param key:
+            Must be a ``/`` separated value. Usually the first
+            name is the name of your plugin or your application.
+        :param default:
+            The value to return in case of a cache-miss or invalid cache value.
+        """
+        path = self._getvaluepath(key)
+        try:
+            with path.open("r", encoding="UTF-8") as f:
+                return json.load(f)
+        except (ValueError, OSError):
+            return default
+
+    def set(self, key: str, value: object) -> None:
+        """Save value for the given key.
+
+        :param key:
+            Must be a ``/`` separated value. Usually the first
+            name is the name of your plugin or your application.
+        :param value:
+            Must be of any combination of basic python types,
+            including nested types like lists of dictionaries.
+        """
+        path = self._getvaluepath(key)
+        try:
+            self._mkdir(path.parent)
+        except OSError as exc:
+            self.warn(
+                f"could not create cache path {path}: {exc}",
+                _ispytest=True,
+            )
+            return
+        data = json.dumps(value, ensure_ascii=False, indent=2)
+        try:
+            f = path.open("w", encoding="UTF-8")
+        except OSError as exc:
+            self.warn(
+                f"cache could not write path {path}: {exc}",
+                _ispytest=True,
+            )
+        else:
+            with f:
+                f.write(data)
+
+    def _ensure_cache_dir_and_supporting_files(self) -> None:
+        """Create the cache dir and its supporting files."""
+        if self._cachedir.is_dir():
+            return
+
+        self._cachedir.parent.mkdir(parents=True, exist_ok=True)
+        with tempfile.TemporaryDirectory(
+            prefix="pytest-cache-files-",
+            dir=self._cachedir.parent,
+        ) as newpath:
+            path = Path(newpath)
+
+            # Reset permissions to the default, see #12308.
+            # Note: there's no way to get the current umask atomically, eek.
+            umask = os.umask(0o022)
+            os.umask(umask)
+            path.chmod(0o777 - umask)
+
+            with open(path.joinpath("README.md"), "x", encoding="UTF-8") as f:
+                f.write(README_CONTENT)
+            with open(path.joinpath(".gitignore"), "x", encoding="UTF-8") as f:
+                f.write("# Created by pytest automatically.\n*\n")
+            with open(path.joinpath("CACHEDIR.TAG"), "xb") as f:
+                f.write(CACHEDIR_TAG_CONTENT)
+
+            try:
+                path.rename(self._cachedir)
+            except OSError as e:
+                # If 2 concurrent pytests both race to the rename, the loser
+                # gets "Directory not empty" from the rename. In this case,
+                # everything is handled so just continue (while letting the
+                # temporary directory be cleaned up).
+                # On Windows, the error is a FileExistsError which translates to EEXIST.
+                if e.errno not in (errno.ENOTEMPTY, errno.EEXIST):
+                    raise
+            else:
+                # Create a directory in place of the one we just moved so that
+                # `TemporaryDirectory`'s cleanup doesn't complain.
+                #
+                # TODO: pass ignore_cleanup_errors=True when we no longer support python < 3.10.
+                # See https://github.com/python/cpython/issues/74168. Note that passing
+                # delete=False would do the wrong thing in case of errors and isn't supported
+                # until python 3.12.
+                path.mkdir()
+
+
+class LFPluginCollWrapper:
+    def __init__(self, lfplugin: LFPlugin) -> None:
+        self.lfplugin = lfplugin
+        self._collected_at_least_one_failure = False
+
+    @hookimpl(wrapper=True)
+    def pytest_make_collect_report(
+        self, collector: nodes.Collector
+    ) -> Generator[None, CollectReport, CollectReport]:
+        res = yield
+        if isinstance(collector, (Session, Directory)):
+            # Sort any lf-paths to the beginning.
+            lf_paths = self.lfplugin._last_failed_paths
+
+            # Use stable sort to prioritize last failed.
+            def sort_key(node: nodes.Item | nodes.Collector) -> bool:
+                return node.path in lf_paths
+
+            res.result = sorted(
+                res.result,
+                key=sort_key,
+                reverse=True,
+            )
+
+        elif isinstance(collector, File):
+            if collector.path in self.lfplugin._last_failed_paths:
+                result = res.result
+                lastfailed = self.lfplugin.lastfailed
+
+                # Only filter with known failures.
+                if not self._collected_at_least_one_failure:
+                    if not any(x.nodeid in lastfailed for x in result):
+                        return res
+                    self.lfplugin.config.pluginmanager.register(
+                        LFPluginCollSkipfiles(self.lfplugin), "lfplugin-collskip"
+                    )
+                    self._collected_at_least_one_failure = True
+
+                session = collector.session
+                result[:] = [
+                    x
+                    for x in result
+                    if x.nodeid in lastfailed
+                    # Include any passed arguments (not trivial to filter).
+                    or session.isinitpath(x.path)
+                    # Keep all sub-collectors.
+                    or isinstance(x, nodes.Collector)
+                ]
+
+        return res
+
+
+class LFPluginCollSkipfiles:
+    def __init__(self, lfplugin: LFPlugin) -> None:
+        self.lfplugin = lfplugin
+
+    @hookimpl
+    def pytest_make_collect_report(
+        self, collector: nodes.Collector
+    ) -> CollectReport | None:
+        if isinstance(collector, File):
+            if collector.path not in self.lfplugin._last_failed_paths:
+                self.lfplugin._skipped_files += 1
+
+                return CollectReport(
+                    collector.nodeid, "passed", longrepr=None, result=[]
+                )
+        return None
+
+
+class LFPlugin:
+    """Plugin which implements the --lf (run last-failing) option."""
+
+    def __init__(self, config: Config) -> None:
+        self.config = config
+        active_keys = "lf", "failedfirst"
+        self.active = any(config.getoption(key) for key in active_keys)
+        assert config.cache
+        self.lastfailed: dict[str, bool] = config.cache.get("cache/lastfailed", {})
+        self._previously_failed_count: int | None = None
+        self._report_status: str | None = None
+        self._skipped_files = 0  # count skipped files during collection due to --lf
+
+        if config.getoption("lf"):
+            self._last_failed_paths = self.get_last_failed_paths()
+            config.pluginmanager.register(
+                LFPluginCollWrapper(self), "lfplugin-collwrapper"
+            )
+
+    def get_last_failed_paths(self) -> set[Path]:
+        """Return a set with all Paths of the previously failed nodeids and
+        their parents."""
+        rootpath = self.config.rootpath
+        result = set()
+        for nodeid in self.lastfailed:
+            path = rootpath / nodeid.split("::")[0]
+            result.add(path)
+            result.update(path.parents)
+        return {x for x in result if x.exists()}
+
+    def pytest_report_collectionfinish(self) -> str | None:
+        if self.active and self.config.get_verbosity() >= 0:
+            return f"run-last-failure: {self._report_status}"
+        return None
+
+    def pytest_runtest_logreport(self, report: TestReport) -> None:
+        if (report.when == "call" and report.passed) or report.skipped:
+            self.lastfailed.pop(report.nodeid, None)
+        elif report.failed:
+            self.lastfailed[report.nodeid] = True
+
+    def pytest_collectreport(self, report: CollectReport) -> None:
+        passed = report.outcome in ("passed", "skipped")
+        if passed:
+            if report.nodeid in self.lastfailed:
+                self.lastfailed.pop(report.nodeid)
+                self.lastfailed.update((item.nodeid, True) for item in report.result)
+        else:
+            self.lastfailed[report.nodeid] = True
+
+    @hookimpl(wrapper=True, tryfirst=True)
+    def pytest_collection_modifyitems(
+        self, config: Config, items: list[nodes.Item]
+    ) -> Generator[None]:
+        res = yield
+
+        if not self.active:
+            return res
+
+        if self.lastfailed:
+            previously_failed = []
+            previously_passed = []
+            for item in items:
+                if item.nodeid in self.lastfailed:
+                    previously_failed.append(item)
+                else:
+                    previously_passed.append(item)
+            self._previously_failed_count = len(previously_failed)
+
+            if not previously_failed:
+                # Running a subset of all tests with recorded failures
+                # only outside of it.
+                self._report_status = "%d known failures not in selected tests" % (
+                    len(self.lastfailed),
+                )
+            else:
+                if self.config.getoption("lf"):
+                    items[:] = previously_failed
+                    config.hook.pytest_deselected(items=previously_passed)
+                else:  # --failedfirst
+                    items[:] = previously_failed + previously_passed
+
+                noun = "failure" if self._previously_failed_count == 1 else "failures"
+                suffix = " first" if self.config.getoption("failedfirst") else ""
+                self._report_status = (
+                    f"rerun previous {self._previously_failed_count} {noun}{suffix}"
+                )
+
+            if self._skipped_files > 0:
+                files_noun = "file" if self._skipped_files == 1 else "files"
+                self._report_status += f" (skipped {self._skipped_files} {files_noun})"
+        else:
+            self._report_status = "no previously failed tests, "
+            if self.config.getoption("last_failed_no_failures") == "none":
+                self._report_status += "deselecting all items."
+                config.hook.pytest_deselected(items=items[:])
+                items[:] = []
+            else:
+                self._report_status += "not deselecting items."
+
+        return res
+
+    def pytest_sessionfinish(self, session: Session) -> None:
+        config = self.config
+        if config.getoption("cacheshow") or hasattr(config, "workerinput"):
+            return
+
+        assert config.cache is not None
+        saved_lastfailed = config.cache.get("cache/lastfailed", {})
+        if saved_lastfailed != self.lastfailed:
+            config.cache.set("cache/lastfailed", self.lastfailed)
+
+
+class NFPlugin:
+    """Plugin which implements the --nf (run new-first) option."""
+
+    def __init__(self, config: Config) -> None:
+        self.config = config
+        self.active = config.option.newfirst
+        assert config.cache is not None
+        self.cached_nodeids = set(config.cache.get("cache/nodeids", []))
+
+    @hookimpl(wrapper=True, tryfirst=True)
+    def pytest_collection_modifyitems(self, items: list[nodes.Item]) -> Generator[None]:
+        res = yield
+
+        if self.active:
+            new_items: dict[str, nodes.Item] = {}
+            other_items: dict[str, nodes.Item] = {}
+            for item in items:
+                if item.nodeid not in self.cached_nodeids:
+                    new_items[item.nodeid] = item
+                else:
+                    other_items[item.nodeid] = item
+
+            items[:] = self._get_increasing_order(
+                new_items.values()
+            ) + self._get_increasing_order(other_items.values())
+            self.cached_nodeids.update(new_items)
+        else:
+            self.cached_nodeids.update(item.nodeid for item in items)
+
+        return res
+
+    def _get_increasing_order(self, items: Iterable[nodes.Item]) -> list[nodes.Item]:
+        return sorted(items, key=lambda item: item.path.stat().st_mtime, reverse=True)
+
+    def pytest_sessionfinish(self) -> None:
+        config = self.config
+        if config.getoption("cacheshow") or hasattr(config, "workerinput"):
+            return
+
+        if config.getoption("collectonly"):
+            return
+
+        assert config.cache is not None
+        config.cache.set("cache/nodeids", sorted(self.cached_nodeids))
+
+
+def pytest_addoption(parser: Parser) -> None:
+    group = parser.getgroup("general")
+    group.addoption(
+        "--lf",
+        "--last-failed",
+        action="store_true",
+        dest="lf",
+        help="Rerun only the tests that failed "
+        "at the last run (or all if none failed)",
+    )
+    group.addoption(
+        "--ff",
+        "--failed-first",
+        action="store_true",
+        dest="failedfirst",
+        help="Run all tests, but run the last failures first. "
+        "This may re-order tests and thus lead to "
+        "repeated fixture setup/teardown.",
+    )
+    group.addoption(
+        "--nf",
+        "--new-first",
+        action="store_true",
+        dest="newfirst",
+        help="Run tests from new files first, then the rest of the tests "
+        "sorted by file mtime",
+    )
+    group.addoption(
+        "--cache-show",
+        action="append",
+        nargs="?",
+        dest="cacheshow",
+        help=(
+            "Show cache contents, don't perform collection or tests. "
+            "Optional argument: glob (default: '*')."
+        ),
+    )
+    group.addoption(
+        "--cache-clear",
+        action="store_true",
+        dest="cacheclear",
+        help="Remove all cache contents at start of test run",
+    )
+    cache_dir_default = ".pytest_cache"
+    if "TOX_ENV_DIR" in os.environ:
+        cache_dir_default = os.path.join(os.environ["TOX_ENV_DIR"], cache_dir_default)
+    parser.addini("cache_dir", default=cache_dir_default, help="Cache directory path")
+    group.addoption(
+        "--lfnf",
+        "--last-failed-no-failures",
+        action="store",
+        dest="last_failed_no_failures",
+        choices=("all", "none"),
+        default="all",
+        help="With ``--lf``, determines whether to execute tests when there "
+        "are no previously (known) failures or when no "
+        "cached ``lastfailed`` data was found. "
+        "``all`` (the default) runs the full test suite again. "
+        "``none`` just emits a message about no known failures and exits successfully.",
+    )
+
+
+def pytest_cmdline_main(config: Config) -> int | ExitCode | None:
+    if config.option.cacheshow and not config.option.help:
+        from _pytest.main import wrap_session
+
+        return wrap_session(config, cacheshow)
+    return None
+
+
+@hookimpl(tryfirst=True)
+def pytest_configure(config: Config) -> None:
+    config.cache = Cache.for_config(config, _ispytest=True)
+    config.pluginmanager.register(LFPlugin(config), "lfplugin")
+    config.pluginmanager.register(NFPlugin(config), "nfplugin")
+
+
+@fixture
+def cache(request: FixtureRequest) -> Cache:
+    """Return a cache object that can persist state between testing sessions.
+
+    cache.get(key, default)
+    cache.set(key, value)
+
+    Keys must be ``/`` separated strings, where the first part is usually the
+    name of your plugin or application to avoid clashes with other cache users.
+
+    Values can be any object handled by the json stdlib module.
+    """
+    assert request.config.cache is not None
+    return request.config.cache
+
+
+def pytest_report_header(config: Config) -> str | None:
+    """Display cachedir with --cache-show and if non-default."""
+    if config.option.verbose > 0 or config.getini("cache_dir") != ".pytest_cache":
+        assert config.cache is not None
+        cachedir = config.cache._cachedir
+        # TODO: evaluate generating upward relative paths
+        # starting with .., ../.. if sensible
+
+        try:
+            displaypath = cachedir.relative_to(config.rootpath)
+        except ValueError:
+            displaypath = cachedir
+        return f"cachedir: {displaypath}"
+    return None
+
+
+def cacheshow(config: Config, session: Session) -> int:
+    from pprint import pformat
+
+    assert config.cache is not None
+
+    tw = TerminalWriter()
+    tw.line("cachedir: " + str(config.cache._cachedir))
+    if not config.cache._cachedir.is_dir():
+        tw.line("cache is empty")
+        return 0
+
+    glob = config.option.cacheshow[0]
+    if glob is None:
+        glob = "*"
+
+    dummy = object()
+    basedir = config.cache._cachedir
+    vdir = basedir / Cache._CACHE_PREFIX_VALUES
+    tw.sep("-", f"cache values for {glob!r}")
+    for valpath in sorted(x for x in vdir.rglob(glob) if x.is_file()):
+        key = str(valpath.relative_to(vdir))
+        val = config.cache.get(key, dummy)
+        if val is dummy:
+            tw.line(f"{key} contains unreadable content, will be ignored")
+        else:
+            tw.line(f"{key} contains:")
+            for line in pformat(val).splitlines():
+                tw.line("  " + line)
+
+    ddir = basedir / Cache._CACHE_PREFIX_DIRS
+    if ddir.is_dir():
+        contents = sorted(ddir.rglob(glob))
+        tw.sep("-", f"cache directories for {glob!r}")
+        for p in contents:
+            # if p.is_dir():
+            #    print("%s/" % p.relative_to(basedir))
+            if p.is_file():
+                key = str(p.relative_to(basedir))
+                tw.line(f"{key} is a file of length {p.stat().st_size:d}")
+    return 0

.venv/lib/python3.11/site-packages/_pytest/compat.py

@@ -0,0 +1,351 @@
+# mypy: allow-untyped-defs
+"""Python version compatibility code."""
+
+from __future__ import annotations
+
+import dataclasses
+import enum
+import functools
+import inspect
+from inspect import Parameter
+from inspect import signature
+import os
+from pathlib import Path
+import sys
+from typing import Any
+from typing import Callable
+from typing import Final
+from typing import NoReturn
+
+import py
+
+
+#: constant to prepare valuing pylib path replacements/lazy proxies later on
+#  intended for removal in pytest 8.0 or 9.0
+
+# fmt: off
+# intentional space to create a fake difference for the verification
+LEGACY_PATH = py.path. local
+# fmt: on
+
+
+def legacy_path(path: str | os.PathLike[str]) -> LEGACY_PATH:
+    """Internal wrapper to prepare lazy proxies for legacy_path instances"""
+    return LEGACY_PATH(path)
+
+
+# fmt: off
+# Singleton type for NOTSET, as described in:
+# https://www.python.org/dev/peps/pep-0484/#support-for-singleton-types-in-unions
+class NotSetType(enum.Enum):
+    token = 0
+NOTSET: Final = NotSetType.token
+# fmt: on
+
+
+def is_generator(func: object) -> bool:
+    genfunc = inspect.isgeneratorfunction(func)
+    return genfunc and not iscoroutinefunction(func)
+
+
+def iscoroutinefunction(func: object) -> bool:
+    """Return True if func is a coroutine function (a function defined with async
+    def syntax, and doesn't contain yield), or a function decorated with
+    @asyncio.coroutine.
+
+    Note: copied and modified from Python 3.5's builtin coroutines.py to avoid
+    importing asyncio directly, which in turns also initializes the "logging"
+    module as a side-effect (see issue #8).
+    """
+    return inspect.iscoroutinefunction(func) or getattr(func, "_is_coroutine", False)
+
+
+def is_async_function(func: object) -> bool:
+    """Return True if the given function seems to be an async function or
+    an async generator."""
+    return iscoroutinefunction(func) or inspect.isasyncgenfunction(func)
+
+
+def getlocation(function, curdir: str | os.PathLike[str] | None = None) -> str:
+    function = get_real_func(function)
+    fn = Path(inspect.getfile(function))
+    lineno = function.__code__.co_firstlineno
+    if curdir is not None:
+        try:
+            relfn = fn.relative_to(curdir)
+        except ValueError:
+            pass
+        else:
+            return "%s:%d" % (relfn, lineno + 1)
+    return "%s:%d" % (fn, lineno + 1)
+
+
+def num_mock_patch_args(function) -> int:
+    """Return number of arguments used up by mock arguments (if any)."""
+    patchings = getattr(function, "patchings", None)
+    if not patchings:
+        return 0
+
+    mock_sentinel = getattr(sys.modules.get("mock"), "DEFAULT", object())
+    ut_mock_sentinel = getattr(sys.modules.get("unittest.mock"), "DEFAULT", object())
+
+    return len(
+        [
+            p
+            for p in patchings
+            if not p.attribute_name
+            and (p.new is mock_sentinel or p.new is ut_mock_sentinel)
+        ]
+    )
+
+
+def getfuncargnames(
+    function: Callable[..., object],
+    *,
+    name: str = "",
+    cls: type | None = None,
+) -> tuple[str, ...]:
+    """Return the names of a function's mandatory arguments.
+
+    Should return the names of all function arguments that:
+    * Aren't bound to an instance or type as in instance or class methods.
+    * Don't have default values.
+    * Aren't bound with functools.partial.
+    * Aren't replaced with mocks.
+
+    The cls arguments indicate that the function should be treated as a bound
+    method even though it's not unless the function is a static method.
+
+    The name parameter should be the original name in which the function was collected.
+    """
+    # TODO(RonnyPfannschmidt): This function should be refactored when we
+    # revisit fixtures. The fixture mechanism should ask the node for
+    # the fixture names, and not try to obtain directly from the
+    # function object well after collection has occurred.
+
+    # The parameters attribute of a Signature object contains an
+    # ordered mapping of parameter names to Parameter instances.  This
+    # creates a tuple of the names of the parameters that don't have
+    # defaults.
+    try:
+        parameters = signature(function).parameters
+    except (ValueError, TypeError) as e:
+        from _pytest.outcomes import fail
+
+        fail(
+            f"Could not determine arguments of {function!r}: {e}",
+            pytrace=False,
+        )
+
+    arg_names = tuple(
+        p.name
+        for p in parameters.values()
+        if (
+            p.kind is Parameter.POSITIONAL_OR_KEYWORD
+            or p.kind is Parameter.KEYWORD_ONLY
+        )
+        and p.default is Parameter.empty
+    )
+    if not name:
+        name = function.__name__
+
+    # If this function should be treated as a bound method even though
+    # it's passed as an unbound method or function, remove the first
+    # parameter name.
+    if (
+        # Not using `getattr` because we don't want to resolve the staticmethod.
+        # Not using `cls.__dict__` because we want to check the entire MRO.
+        cls
+        and not isinstance(
+            inspect.getattr_static(cls, name, default=None), staticmethod
+        )
+    ):
+        arg_names = arg_names[1:]
+    # Remove any names that will be replaced with mocks.
+    if hasattr(function, "__wrapped__"):
+        arg_names = arg_names[num_mock_patch_args(function) :]
+    return arg_names
+
+
+def get_default_arg_names(function: Callable[..., Any]) -> tuple[str, ...]:
+    # Note: this code intentionally mirrors the code at the beginning of
+    # getfuncargnames, to get the arguments which were excluded from its result
+    # because they had default values.
+    return tuple(
+        p.name
+        for p in signature(function).parameters.values()
+        if p.kind in (Parameter.POSITIONAL_OR_KEYWORD, Parameter.KEYWORD_ONLY)
+        and p.default is not Parameter.empty
+    )
+
+
+_non_printable_ascii_translate_table = {
+    i: f"\\x{i:02x}" for i in range(128) if i not in range(32, 127)
+}
+_non_printable_ascii_translate_table.update(
+    {ord("\t"): "\\t", ord("\r"): "\\r", ord("\n"): "\\n"}
+)
+
+
+def ascii_escaped(val: bytes | str) -> str:
+    r"""If val is pure ASCII, return it as an str, otherwise, escape
+    bytes objects into a sequence of escaped bytes:
+
+    b'\xc3\xb4\xc5\xd6' -> r'\xc3\xb4\xc5\xd6'
+
+    and escapes strings into a sequence of escaped unicode ids, e.g.:
+
+    r'4\nV\U00043efa\x0eMXWB\x1e\u3028\u15fd\xcd\U0007d944'
+
+    Note:
+       The obvious "v.decode('unicode-escape')" will return
+       valid UTF-8 unicode if it finds them in bytes, but we
+       want to return escaped bytes for any byte, even if they match
+       a UTF-8 string.
+    """
+    if isinstance(val, bytes):
+        ret = val.decode("ascii", "backslashreplace")
+    else:
+        ret = val.encode("unicode_escape").decode("ascii")
+    return ret.translate(_non_printable_ascii_translate_table)
+
+
+@dataclasses.dataclass
+class _PytestWrapper:
+    """Dummy wrapper around a function object for internal use only.
+
+    Used to correctly unwrap the underlying function object when we are
+    creating fixtures, because we wrap the function object ourselves with a
+    decorator to issue warnings when the fixture function is called directly.
+    """
+
+    obj: Any
+
+
+def get_real_func(obj):
+    """Get the real function object of the (possibly) wrapped object by
+    functools.wraps or functools.partial."""
+    start_obj = obj
+    for i in range(100):
+        # __pytest_wrapped__ is set by @pytest.fixture when wrapping the fixture function
+        # to trigger a warning if it gets called directly instead of by pytest: we don't
+        # want to unwrap further than this otherwise we lose useful wrappings like @mock.patch (#3774)
+        new_obj = getattr(obj, "__pytest_wrapped__", None)
+        if isinstance(new_obj, _PytestWrapper):
+            obj = new_obj.obj
+            break
+        new_obj = getattr(obj, "__wrapped__", None)
+        if new_obj is None:
+            break
+        obj = new_obj
+    else:
+        from _pytest._io.saferepr import saferepr
+
+        raise ValueError(
+            f"could not find real function of {saferepr(start_obj)}\nstopped at {saferepr(obj)}"
+        )
+    if isinstance(obj, functools.partial):
+        obj = obj.func
+    return obj
+
+
+def get_real_method(obj, holder):
+    """Attempt to obtain the real function object that might be wrapping
+    ``obj``, while at the same time returning a bound method to ``holder`` if
+    the original object was a bound method."""
+    try:
+        is_method = hasattr(obj, "__func__")
+        obj = get_real_func(obj)
+    except Exception:  # pragma: no cover
+        return obj
+    if is_method and hasattr(obj, "__get__") and callable(obj.__get__):
+        obj = obj.__get__(holder)
+    return obj
+
+
+def getimfunc(func):
+    try:
+        return func.__func__
+    except AttributeError:
+        return func
+
+
+def safe_getattr(object: Any, name: str, default: Any) -> Any:
+    """Like getattr but return default upon any Exception or any OutcomeException.
+
+    Attribute access can potentially fail for 'evil' Python objects.
+    See issue #214.
+    It catches OutcomeException because of #2490 (issue #580), new outcomes
+    are derived from BaseException instead of Exception (for more details
+    check #2707).
+    """
+    from _pytest.outcomes import TEST_OUTCOME
+
+    try:
+        return getattr(object, name, default)
+    except TEST_OUTCOME:
+        return default
+
+
+def safe_isclass(obj: object) -> bool:
+    """Ignore any exception via isinstance on Python 3."""
+    try:
+        return inspect.isclass(obj)
+    except Exception:
+        return False
+
+
+def get_user_id() -> int | None:
+    """Return the current process's real user id or None if it could not be
+    determined.
+
+    :return: The user id or None if it could not be determined.
+    """
+    # mypy follows the version and platform checking expectation of PEP 484:
+    # https://mypy.readthedocs.io/en/stable/common_issues.html?highlight=platform#python-version-and-system-platform-checks
+    # Containment checks are too complex for mypy v1.5.0 and cause failure.
+    if sys.platform == "win32" or sys.platform == "emscripten":
+        # win32 does not have a getuid() function.
+        # Emscripten has a return 0 stub.
+        return None
+    else:
+        # On other platforms, a return value of -1 is assumed to indicate that
+        # the current process's real user id could not be determined.
+        ERROR = -1
+        uid = os.getuid()
+        return uid if uid != ERROR else None
+
+
+# Perform exhaustiveness checking.
+#
+# Consider this example:
+#
+#     MyUnion = Union[int, str]
+#
+#     def handle(x: MyUnion) -> int {
+#         if isinstance(x, int):
+#             return 1
+#         elif isinstance(x, str):
+#             return 2
+#         else:
+#             raise Exception('unreachable')
+#
+# Now suppose we add a new variant:
+#
+#     MyUnion = Union[int, str, bytes]
+#
+# After doing this, we must remember ourselves to go and update the handle
+# function to handle the new variant.
+#
+# With `assert_never` we can do better:
+#
+#     // raise Exception('unreachable')
+#     return assert_never(x)
+#
+# Now, if we forget to handle the new variant, the type-checker will emit a
+# compile-time error, instead of the runtime error we would have gotten
+# previously.
+#
+# This also work for Enums (if you use `is` to compare) and Literals.
+def assert_never(value: NoReturn) -> NoReturn:
+    assert False, f"Unhandled value: {value} ({type(value).__name__})"

.venv/lib/python3.11/site-packages/_pytest/doctest.py

@@ -0,0 +1,755 @@
+# mypy: allow-untyped-defs
+"""Discover and run doctests in modules and test files."""
+
+from __future__ import annotations
+
+import bdb
+from contextlib import contextmanager
+import functools
+import inspect
+import os
+from pathlib import Path
+import platform
+import sys
+import traceback
+import types
+from typing import Any
+from typing import Callable
+from typing import Generator
+from typing import Iterable
+from typing import Pattern
+from typing import Sequence
+from typing import TYPE_CHECKING
+import warnings
+
+from _pytest import outcomes
+from _pytest._code.code import ExceptionInfo
+from _pytest._code.code import ReprFileLocation
+from _pytest._code.code import TerminalRepr
+from _pytest._io import TerminalWriter
+from _pytest.compat import safe_getattr
+from _pytest.config import Config
+from _pytest.config.argparsing import Parser
+from _pytest.fixtures import fixture
+from _pytest.fixtures import TopRequest
+from _pytest.nodes import Collector
+from _pytest.nodes import Item
+from _pytest.outcomes import OutcomeException
+from _pytest.outcomes import skip
+from _pytest.pathlib import fnmatch_ex
+from _pytest.python import Module
+from _pytest.python_api import approx
+from _pytest.warning_types import PytestWarning
+
+
+if TYPE_CHECKING:
+    import doctest
+
+    from typing_extensions import Self
+
+DOCTEST_REPORT_CHOICE_NONE = "none"
+DOCTEST_REPORT_CHOICE_CDIFF = "cdiff"
+DOCTEST_REPORT_CHOICE_NDIFF = "ndiff"
+DOCTEST_REPORT_CHOICE_UDIFF = "udiff"
+DOCTEST_REPORT_CHOICE_ONLY_FIRST_FAILURE = "only_first_failure"
+
+DOCTEST_REPORT_CHOICES = (
+    DOCTEST_REPORT_CHOICE_NONE,
+    DOCTEST_REPORT_CHOICE_CDIFF,
+    DOCTEST_REPORT_CHOICE_NDIFF,
+    DOCTEST_REPORT_CHOICE_UDIFF,
+    DOCTEST_REPORT_CHOICE_ONLY_FIRST_FAILURE,
+)
+
+# Lazy definition of runner class
+RUNNER_CLASS = None
+# Lazy definition of output checker class
+CHECKER_CLASS: type[doctest.OutputChecker] | None = None
+
+
+def pytest_addoption(parser: Parser) -> None:
+    parser.addini(
+        "doctest_optionflags",
+        "Option flags for doctests",
+        type="args",
+        default=["ELLIPSIS"],
+    )
+    parser.addini(
+        "doctest_encoding", "Encoding used for doctest files", default="utf-8"
+    )
+    group = parser.getgroup("collect")
+    group.addoption(
+        "--doctest-modules",
+        action="store_true",
+        default=False,
+        help="Run doctests in all .py modules",
+        dest="doctestmodules",
+    )
+    group.addoption(
+        "--doctest-report",
+        type=str.lower,
+        default="udiff",
+        help="Choose another output format for diffs on doctest failure",
+        choices=DOCTEST_REPORT_CHOICES,
+        dest="doctestreport",
+    )
+    group.addoption(
+        "--doctest-glob",
+        action="append",
+        default=[],
+        metavar="pat",
+        help="Doctests file matching pattern, default: test*.txt",
+        dest="doctestglob",
+    )
+    group.addoption(
+        "--doctest-ignore-import-errors",
+        action="store_true",
+        default=False,
+        help="Ignore doctest collection errors",
+        dest="doctest_ignore_import_errors",
+    )
+    group.addoption(
+        "--doctest-continue-on-failure",
+        action="store_true",
+        default=False,
+        help="For a given doctest, continue to run after the first failure",
+        dest="doctest_continue_on_failure",
+    )
+
+
+def pytest_unconfigure() -> None:
+    global RUNNER_CLASS
+
+    RUNNER_CLASS = None
+
+
+def pytest_collect_file(
+    file_path: Path,
+    parent: Collector,
+) -> DoctestModule | DoctestTextfile | None:
+    config = parent.config
+    if file_path.suffix == ".py":
+        if config.option.doctestmodules and not any(
+            (_is_setup_py(file_path), _is_main_py(file_path))
+        ):
+            return DoctestModule.from_parent(parent, path=file_path)
+    elif _is_doctest(config, file_path, parent):
+        return DoctestTextfile.from_parent(parent, path=file_path)
+    return None
+
+
+def _is_setup_py(path: Path) -> bool:
+    if path.name != "setup.py":
+        return False
+    contents = path.read_bytes()
+    return b"setuptools" in contents or b"distutils" in contents
+
+
+def _is_doctest(config: Config, path: Path, parent: Collector) -> bool:
+    if path.suffix in (".txt", ".rst") and parent.session.isinitpath(path):
+        return True
+    globs = config.getoption("doctestglob") or ["test*.txt"]
+    return any(fnmatch_ex(glob, path) for glob in globs)
+
+
+def _is_main_py(path: Path) -> bool:
+    return path.name == "__main__.py"
+
+
+class ReprFailDoctest(TerminalRepr):
+    def __init__(
+        self, reprlocation_lines: Sequence[tuple[ReprFileLocation, Sequence[str]]]
+    ) -> None:
+        self.reprlocation_lines = reprlocation_lines
+
+    def toterminal(self, tw: TerminalWriter) -> None:
+        for reprlocation, lines in self.reprlocation_lines:
+            for line in lines:
+                tw.line(line)
+            reprlocation.toterminal(tw)
+
+
+class MultipleDoctestFailures(Exception):
+    def __init__(self, failures: Sequence[doctest.DocTestFailure]) -> None:
+        super().__init__()
+        self.failures = failures
+
+
+def _init_runner_class() -> type[doctest.DocTestRunner]:
+    import doctest
+
+    class PytestDoctestRunner(doctest.DebugRunner):
+        """Runner to collect failures.
+
+        Note that the out variable in this case is a list instead of a
+        stdout-like object.
+        """
+
+        def __init__(
+            self,
+            checker: doctest.OutputChecker | None = None,
+            verbose: bool | None = None,
+            optionflags: int = 0,
+            continue_on_failure: bool = True,
+        ) -> None:
+            super().__init__(checker=checker, verbose=verbose, optionflags=optionflags)
+            self.continue_on_failure = continue_on_failure
+
+        def report_failure(
+            self,
+            out,
+            test: doctest.DocTest,
+            example: doctest.Example,
+            got: str,
+        ) -> None:
+            failure = doctest.DocTestFailure(test, example, got)
+            if self.continue_on_failure:
+                out.append(failure)
+            else:
+                raise failure
+
+        def report_unexpected_exception(
+            self,
+            out,
+            test: doctest.DocTest,
+            example: doctest.Example,
+            exc_info: tuple[type[BaseException], BaseException, types.TracebackType],
+        ) -> None:
+            if isinstance(exc_info[1], OutcomeException):
+                raise exc_info[1]
+            if isinstance(exc_info[1], bdb.BdbQuit):
+                outcomes.exit("Quitting debugger")
+            failure = doctest.UnexpectedException(test, example, exc_info)
+            if self.continue_on_failure:
+                out.append(failure)
+            else:
+                raise failure
+
+    return PytestDoctestRunner
+
+
+def _get_runner(
+    checker: doctest.OutputChecker | None = None,
+    verbose: bool | None = None,
+    optionflags: int = 0,
+    continue_on_failure: bool = True,
+) -> doctest.DocTestRunner:
+    # We need this in order to do a lazy import on doctest
+    global RUNNER_CLASS
+    if RUNNER_CLASS is None:
+        RUNNER_CLASS = _init_runner_class()
+    # Type ignored because the continue_on_failure argument is only defined on
+    # PytestDoctestRunner, which is lazily defined so can't be used as a type.
+    return RUNNER_CLASS(  # type: ignore
+        checker=checker,
+        verbose=verbose,
+        optionflags=optionflags,
+        continue_on_failure=continue_on_failure,
+    )
+
+
+class DoctestItem(Item):
+    def __init__(
+        self,
+        name: str,
+        parent: DoctestTextfile | DoctestModule,
+        runner: doctest.DocTestRunner,
+        dtest: doctest.DocTest,
+    ) -> None:
+        super().__init__(name, parent)
+        self.runner = runner
+        self.dtest = dtest
+
+        # Stuff needed for fixture support.
+        self.obj = None
+        fm = self.session._fixturemanager
+        fixtureinfo = fm.getfixtureinfo(node=self, func=None, cls=None)
+        self._fixtureinfo = fixtureinfo
+        self.fixturenames = fixtureinfo.names_closure
+        self._initrequest()
+
+    @classmethod
+    def from_parent(  # type: ignore[override]
+        cls,
+        parent: DoctestTextfile | DoctestModule,
+        *,
+        name: str,
+        runner: doctest.DocTestRunner,
+        dtest: doctest.DocTest,
+    ) -> Self:
+        # incompatible signature due to imposed limits on subclass
+        """The public named constructor."""
+        return super().from_parent(name=name, parent=parent, runner=runner, dtest=dtest)
+
+    def _initrequest(self) -> None:
+        self.funcargs: dict[str, object] = {}
+        self._request = TopRequest(self, _ispytest=True)  # type: ignore[arg-type]
+
+    def setup(self) -> None:
+        self._request._fillfixtures()
+        globs = dict(getfixture=self._request.getfixturevalue)
+        for name, value in self._request.getfixturevalue("doctest_namespace").items():
+            globs[name] = value
+        self.dtest.globs.update(globs)
+
+    def runtest(self) -> None:
+        _check_all_skipped(self.dtest)
+        self._disable_output_capturing_for_darwin()
+        failures: list[doctest.DocTestFailure] = []
+        # Type ignored because we change the type of `out` from what
+        # doctest expects.
+        self.runner.run(self.dtest, out=failures)  # type: ignore[arg-type]
+        if failures:
+            raise MultipleDoctestFailures(failures)
+
+    def _disable_output_capturing_for_darwin(self) -> None:
+        """Disable output capturing. Otherwise, stdout is lost to doctest (#985)."""
+        if platform.system() != "Darwin":
+            return
+        capman = self.config.pluginmanager.getplugin("capturemanager")
+        if capman:
+            capman.suspend_global_capture(in_=True)
+            out, err = capman.read_global_capture()
+            sys.stdout.write(out)
+            sys.stderr.write(err)
+
+    # TODO: Type ignored -- breaks Liskov Substitution.
+    def repr_failure(  # type: ignore[override]
+        self,
+        excinfo: ExceptionInfo[BaseException],
+    ) -> str | TerminalRepr:
+        import doctest
+
+        failures: (
+            Sequence[doctest.DocTestFailure | doctest.UnexpectedException] | None
+        ) = None
+        if isinstance(
+            excinfo.value, (doctest.DocTestFailure, doctest.UnexpectedException)
+        ):
+            failures = [excinfo.value]
+        elif isinstance(excinfo.value, MultipleDoctestFailures):
+            failures = excinfo.value.failures
+
+        if failures is None:
+            return super().repr_failure(excinfo)
+
+        reprlocation_lines = []
+        for failure in failures:
+            example = failure.example
+            test = failure.test
+            filename = test.filename
+            if test.lineno is None:
+                lineno = None
+            else:
+                lineno = test.lineno + example.lineno + 1
+            message = type(failure).__name__
+            # TODO: ReprFileLocation doesn't expect a None lineno.
+            reprlocation = ReprFileLocation(filename, lineno, message)  # type: ignore[arg-type]
+            checker = _get_checker()
+            report_choice = _get_report_choice(self.config.getoption("doctestreport"))
+            if lineno is not None:
+                assert failure.test.docstring is not None
+                lines = failure.test.docstring.splitlines(False)
+                # add line numbers to the left of the error message
+                assert test.lineno is not None
+                lines = [
+                    "%03d %s" % (i + test.lineno + 1, x) for (i, x) in enumerate(lines)
+                ]
+                # trim docstring error lines to 10
+                lines = lines[max(example.lineno - 9, 0) : example.lineno + 1]
+            else:
+                lines = [
+                    "EXAMPLE LOCATION UNKNOWN, not showing all tests of that example"
+                ]
+                indent = ">>>"
+                for line in example.source.splitlines():
+                    lines.append(f"??? {indent} {line}")
+                    indent = "..."
+            if isinstance(failure, doctest.DocTestFailure):
+                lines += checker.output_difference(
+                    example, failure.got, report_choice
+                ).split("\n")
+            else:
+                inner_excinfo = ExceptionInfo.from_exc_info(failure.exc_info)
+                lines += [f"UNEXPECTED EXCEPTION: {inner_excinfo.value!r}"]
+                lines += [
+                    x.strip("\n") for x in traceback.format_exception(*failure.exc_info)
+                ]
+            reprlocation_lines.append((reprlocation, lines))
+        return ReprFailDoctest(reprlocation_lines)
+
+    def reportinfo(self) -> tuple[os.PathLike[str] | str, int | None, str]:
+        return self.path, self.dtest.lineno, f"[doctest] {self.name}"
+
+
+def _get_flag_lookup() -> dict[str, int]:
+    import doctest
+
+    return dict(
+        DONT_ACCEPT_TRUE_FOR_1=doctest.DONT_ACCEPT_TRUE_FOR_1,
+        DONT_ACCEPT_BLANKLINE=doctest.DONT_ACCEPT_BLANKLINE,
+        NORMALIZE_WHITESPACE=doctest.NORMALIZE_WHITESPACE,
+        ELLIPSIS=doctest.ELLIPSIS,
+        IGNORE_EXCEPTION_DETAIL=doctest.IGNORE_EXCEPTION_DETAIL,
+        COMPARISON_FLAGS=doctest.COMPARISON_FLAGS,
+        ALLOW_UNICODE=_get_allow_unicode_flag(),
+        ALLOW_BYTES=_get_allow_bytes_flag(),
+        NUMBER=_get_number_flag(),
+    )
+
+
+def get_optionflags(config: Config) -> int:
+    optionflags_str = config.getini("doctest_optionflags")
+    flag_lookup_table = _get_flag_lookup()
+    flag_acc = 0
+    for flag in optionflags_str:
+        flag_acc |= flag_lookup_table[flag]
+    return flag_acc
+
+
+def _get_continue_on_failure(config: Config) -> bool:
+    continue_on_failure: bool = config.getvalue("doctest_continue_on_failure")
+    if continue_on_failure:
+        # We need to turn off this if we use pdb since we should stop at
+        # the first failure.
+        if config.getvalue("usepdb"):
+            continue_on_failure = False
+    return continue_on_failure
+
+
+class DoctestTextfile(Module):
+    obj = None
+
+    def collect(self) -> Iterable[DoctestItem]:
+        import doctest
+
+        # Inspired by doctest.testfile; ideally we would use it directly,
+        # but it doesn't support passing a custom checker.
+        encoding = self.config.getini("doctest_encoding")
+        text = self.path.read_text(encoding)
+        filename = str(self.path)
+        name = self.path.name
+        globs = {"__name__": "__main__"}
+
+        optionflags = get_optionflags(self.config)
+
+        runner = _get_runner(
+            verbose=False,
+            optionflags=optionflags,
+            checker=_get_checker(),
+            continue_on_failure=_get_continue_on_failure(self.config),
+        )
+
+        parser = doctest.DocTestParser()
+        test = parser.get_doctest(text, globs, name, filename, 0)
+        if test.examples:
+            yield DoctestItem.from_parent(
+                self, name=test.name, runner=runner, dtest=test
+            )
+
+
+def _check_all_skipped(test: doctest.DocTest) -> None:
+    """Raise pytest.skip() if all examples in the given DocTest have the SKIP
+    option set."""
+    import doctest
+
+    all_skipped = all(x.options.get(doctest.SKIP, False) for x in test.examples)
+    if all_skipped:
+        skip("all tests skipped by +SKIP option")
+
+
+def _is_mocked(obj: object) -> bool:
+    """Return if an object is possibly a mock object by checking the
+    existence of a highly improbable attribute."""
+    return (
+        safe_getattr(obj, "pytest_mock_example_attribute_that_shouldnt_exist", None)
+        is not None
+    )
+
+
+@contextmanager
+def _patch_unwrap_mock_aware() -> Generator[None]:
+    """Context manager which replaces ``inspect.unwrap`` with a version
+    that's aware of mock objects and doesn't recurse into them."""
+    real_unwrap = inspect.unwrap
+
+    def _mock_aware_unwrap(
+        func: Callable[..., Any], *, stop: Callable[[Any], Any] | None = None
+    ) -> Any:
+        try:
+            if stop is None or stop is _is_mocked:
+                return real_unwrap(func, stop=_is_mocked)
+            _stop = stop
+            return real_unwrap(func, stop=lambda obj: _is_mocked(obj) or _stop(func))
+        except Exception as e:
+            warnings.warn(
+                f"Got {e!r} when unwrapping {func!r}.  This is usually caused "
+                "by a violation of Python's object protocol; see e.g. "
+                "https://github.com/pytest-dev/pytest/issues/5080",
+                PytestWarning,
+            )
+            raise
+
+    inspect.unwrap = _mock_aware_unwrap
+    try:
+        yield
+    finally:
+        inspect.unwrap = real_unwrap
+
+
+class DoctestModule(Module):
+    def collect(self) -> Iterable[DoctestItem]:
+        import doctest
+
+        class MockAwareDocTestFinder(doctest.DocTestFinder):
+            py_ver_info_minor = sys.version_info[:2]
+            is_find_lineno_broken = (
+                py_ver_info_minor < (3, 11)
+                or (py_ver_info_minor == (3, 11) and sys.version_info.micro < 9)
+                or (py_ver_info_minor == (3, 12) and sys.version_info.micro < 3)
+            )
+            if is_find_lineno_broken:
+
+                def _find_lineno(self, obj, source_lines):
+                    """On older Pythons, doctest code does not take into account
+                    `@property`. https://github.com/python/cpython/issues/61648
+
+                    Moreover, wrapped Doctests need to be unwrapped so the correct
+                    line number is returned. #8796
+                    """
+                    if isinstance(obj, property):
+                        obj = getattr(obj, "fget", obj)
+
+                    if hasattr(obj, "__wrapped__"):
+                        # Get the main obj in case of it being wrapped
+                        obj = inspect.unwrap(obj)
+
+                    # Type ignored because this is a private function.
+                    return super()._find_lineno(  # type:ignore[misc]
+                        obj,
+                        source_lines,
+                    )
+
+            if sys.version_info < (3, 10):
+
+                def _find(
+                    self, tests, obj, name, module, source_lines, globs, seen
+                ) -> None:
+                    """Override _find to work around issue in stdlib.
+
+                    https://github.com/pytest-dev/pytest/issues/3456
+                    https://github.com/python/cpython/issues/69718
+                    """
+                    if _is_mocked(obj):
+                        return  # pragma: no cover
+                    with _patch_unwrap_mock_aware():
+                        # Type ignored because this is a private function.
+                        super()._find(  # type:ignore[misc]
+                            tests, obj, name, module, source_lines, globs, seen
+                        )
+
+            if sys.version_info < (3, 13):
+
+                def _from_module(self, module, object):
+                    """`cached_property` objects are never considered a part
+                    of the 'current module'. As such they are skipped by doctest.
+                    Here we override `_from_module` to check the underlying
+                    function instead. https://github.com/python/cpython/issues/107995
+                    """
+                    if isinstance(object, functools.cached_property):
+                        object = object.func
+
+                    # Type ignored because this is a private function.
+                    return super()._from_module(module, object)  # type: ignore[misc]
+
+        try:
+            module = self.obj
+        except Collector.CollectError:
+            if self.config.getvalue("doctest_ignore_import_errors"):
+                skip(f"unable to import module {self.path!r}")
+            else:
+                raise
+
+        # While doctests currently don't support fixtures directly, we still
+        # need to pick up autouse fixtures.
+        self.session._fixturemanager.parsefactories(self)
+
+        # Uses internal doctest module parsing mechanism.
+        finder = MockAwareDocTestFinder()
+        optionflags = get_optionflags(self.config)
+        runner = _get_runner(
+            verbose=False,
+            optionflags=optionflags,
+            checker=_get_checker(),
+            continue_on_failure=_get_continue_on_failure(self.config),
+        )
+
+        for test in finder.find(module, module.__name__):
+            if test.examples:  # skip empty doctests
+                yield DoctestItem.from_parent(
+                    self, name=test.name, runner=runner, dtest=test
+                )
+
+
+def _init_checker_class() -> type[doctest.OutputChecker]:
+    import doctest
+    import re
+
+    class LiteralsOutputChecker(doctest.OutputChecker):
+        # Based on doctest_nose_plugin.py from the nltk project
+        # (https://github.com/nltk/nltk) and on the "numtest" doctest extension
+        # by Sebastien Boisgerault (https://github.com/boisgera/numtest).
+
+        _unicode_literal_re = re.compile(r"(\W|^)[uU]([rR]?[\'\"])", re.UNICODE)
+        _bytes_literal_re = re.compile(r"(\W|^)[bB]([rR]?[\'\"])", re.UNICODE)
+        _number_re = re.compile(
+            r"""
+            (?P<number>
+              (?P<mantissa>
+                (?P<integer1> [+-]?\d*)\.(?P<fraction>\d+)
+                |
+                (?P<integer2> [+-]?\d+)\.
+              )
+              (?:
+                [Ee]
+                (?P<exponent1> [+-]?\d+)
+              )?
+              |
+              (?P<integer3> [+-]?\d+)
+              (?:
+                [Ee]
+                (?P<exponent2> [+-]?\d+)
+              )
+            )
+            """,
+            re.VERBOSE,
+        )
+
+        def check_output(self, want: str, got: str, optionflags: int) -> bool:
+            if super().check_output(want, got, optionflags):
+                return True
+
+            allow_unicode = optionflags & _get_allow_unicode_flag()
+            allow_bytes = optionflags & _get_allow_bytes_flag()
+            allow_number = optionflags & _get_number_flag()
+
+            if not allow_unicode and not allow_bytes and not allow_number:
+                return False
+
+            def remove_prefixes(regex: Pattern[str], txt: str) -> str:
+                return re.sub(regex, r"\1\2", txt)
+
+            if allow_unicode:
+                want = remove_prefixes(self._unicode_literal_re, want)
+                got = remove_prefixes(self._unicode_literal_re, got)
+
+            if allow_bytes:
+                want = remove_prefixes(self._bytes_literal_re, want)
+                got = remove_prefixes(self._bytes_literal_re, got)
+
+            if allow_number:
+                got = self._remove_unwanted_precision(want, got)
+
+            return super().check_output(want, got, optionflags)
+
+        def _remove_unwanted_precision(self, want: str, got: str) -> str:
+            wants = list(self._number_re.finditer(want))
+            gots = list(self._number_re.finditer(got))
+            if len(wants) != len(gots):
+                return got
+            offset = 0
+            for w, g in zip(wants, gots):
+                fraction: str | None = w.group("fraction")
+                exponent: str | None = w.group("exponent1")
+                if exponent is None:
+                    exponent = w.group("exponent2")
+                precision = 0 if fraction is None else len(fraction)
+                if exponent is not None:
+                    precision -= int(exponent)
+                if float(w.group()) == approx(float(g.group()), abs=10**-precision):
+                    # They're close enough. Replace the text we actually
+                    # got with the text we want, so that it will match when we
+                    # check the string literally.
+                    got = (
+                        got[: g.start() + offset] + w.group() + got[g.end() + offset :]
+                    )
+                    offset += w.end() - w.start() - (g.end() - g.start())
+            return got
+
+    return LiteralsOutputChecker
+
+
+def _get_checker() -> doctest.OutputChecker:
+    """Return a doctest.OutputChecker subclass that supports some
+    additional options:
+
+    * ALLOW_UNICODE and ALLOW_BYTES options to ignore u'' and b''
+      prefixes (respectively) in string literals. Useful when the same
+      doctest should run in Python 2 and Python 3.
+
+    * NUMBER to ignore floating-point differences smaller than the
+      precision of the literal number in the doctest.
+
+    An inner class is used to avoid importing "doctest" at the module
+    level.
+    """
+    global CHECKER_CLASS
+    if CHECKER_CLASS is None:
+        CHECKER_CLASS = _init_checker_class()
+    return CHECKER_CLASS()
+
+
+def _get_allow_unicode_flag() -> int:
+    """Register and return the ALLOW_UNICODE flag."""
+    import doctest
+
+    return doctest.register_optionflag("ALLOW_UNICODE")
+
+
+def _get_allow_bytes_flag() -> int:
+    """Register and return the ALLOW_BYTES flag."""
+    import doctest
+
+    return doctest.register_optionflag("ALLOW_BYTES")
+
+
+def _get_number_flag() -> int:
+    """Register and return the NUMBER flag."""
+    import doctest
+
+    return doctest.register_optionflag("NUMBER")
+
+
+def _get_report_choice(key: str) -> int:
+    """Return the actual `doctest` module flag value.
+
+    We want to do it as late as possible to avoid importing `doctest` and all
+    its dependencies when parsing options, as it adds overhead and breaks tests.
+    """
+    import doctest
+
+    return {
+        DOCTEST_REPORT_CHOICE_UDIFF: doctest.REPORT_UDIFF,
+        DOCTEST_REPORT_CHOICE_CDIFF: doctest.REPORT_CDIFF,
+        DOCTEST_REPORT_CHOICE_NDIFF: doctest.REPORT_NDIFF,
+        DOCTEST_REPORT_CHOICE_ONLY_FIRST_FAILURE: doctest.REPORT_ONLY_FIRST_FAILURE,
+        DOCTEST_REPORT_CHOICE_NONE: 0,
+    }[key]
+
+
+@fixture(scope="session")
+def doctest_namespace() -> dict[str, Any]:
+    """Fixture that returns a :py:class:`dict` that will be injected into the
+    namespace of doctests.
+
+    Usually this fixture is used in conjunction with another ``autouse`` fixture:
+
+    .. code-block:: python
+
+        @pytest.fixture(autouse=True)
+        def add_np(doctest_namespace):
+            doctest_namespace["np"] = numpy
+
+    For more details: :ref:`doctest_namespace`.
+    """
+    return dict()

.venv/lib/python3.11/site-packages/_pytest/helpconfig.py

@@ -0,0 +1,276 @@
+# mypy: allow-untyped-defs
+"""Version info, help messages, tracing configuration."""
+
+from __future__ import annotations
+
+from argparse import Action
+import os
+import sys
+from typing import Generator
+
+from _pytest.config import Config
+from _pytest.config import ExitCode
+from _pytest.config import PrintHelp
+from _pytest.config.argparsing import Parser
+from _pytest.terminal import TerminalReporter
+import pytest
+
+
+class HelpAction(Action):
+    """An argparse Action that will raise an exception in order to skip the
+    rest of the argument parsing when --help is passed.
+
+    This prevents argparse from quitting due to missing required arguments
+    when any are defined, for example by ``pytest_addoption``.
+    This is similar to the way that the builtin argparse --help option is
+    implemented by raising SystemExit.
+    """
+
+    def __init__(self, option_strings, dest=None, default=False, help=None):
+        super().__init__(
+            option_strings=option_strings,
+            dest=dest,
+            const=True,
+            default=default,
+            nargs=0,
+            help=help,
+        )
+
+    def __call__(self, parser, namespace, values, option_string=None):
+        setattr(namespace, self.dest, self.const)
+
+        # We should only skip the rest of the parsing after preparse is done.
+        if getattr(parser._parser, "after_preparse", False):
+            raise PrintHelp
+
+
+def pytest_addoption(parser: Parser) -> None:
+    group = parser.getgroup("debugconfig")
+    group.addoption(
+        "--version",
+        "-V",
+        action="count",
+        default=0,
+        dest="version",
+        help="Display pytest version and information about plugins. "
+        "When given twice, also display information about plugins.",
+    )
+    group._addoption(
+        "-h",
+        "--help",
+        action=HelpAction,
+        dest="help",
+        help="Show help message and configuration info",
+    )
+    group._addoption(
+        "-p",
+        action="append",
+        dest="plugins",
+        default=[],
+        metavar="name",
+        help="Early-load given plugin module name or entry point (multi-allowed). "
+        "To avoid loading of plugins, use the `no:` prefix, e.g. "
+        "`no:doctest`.",
+    )
+    group.addoption(
+        "--traceconfig",
+        "--trace-config",
+        action="store_true",
+        default=False,
+        help="Trace considerations of conftest.py files",
+    )
+    group.addoption(
+        "--debug",
+        action="store",
+        nargs="?",
+        const="pytestdebug.log",
+        dest="debug",
+        metavar="DEBUG_FILE_NAME",
+        help="Store internal tracing debug information in this log file. "
+        "This file is opened with 'w' and truncated as a result, care advised. "
+        "Default: pytestdebug.log.",
+    )
+    group._addoption(
+        "-o",
+        "--override-ini",
+        dest="override_ini",
+        action="append",
+        help='Override ini option with "option=value" style, '
+        "e.g. `-o xfail_strict=True -o cache_dir=cache`.",
+    )
+
+
+@pytest.hookimpl(wrapper=True)
+def pytest_cmdline_parse() -> Generator[None, Config, Config]:
+    config = yield
+
+    if config.option.debug:
+        # --debug | --debug <file.log> was provided.
+        path = config.option.debug
+        debugfile = open(path, "w", encoding="utf-8")
+        debugfile.write(
+            "versions pytest-{}, "
+            "python-{}\ninvocation_dir={}\ncwd={}\nargs={}\n\n".format(
+                pytest.__version__,
+                ".".join(map(str, sys.version_info)),
+                config.invocation_params.dir,
+                os.getcwd(),
+                config.invocation_params.args,
+            )
+        )
+        config.trace.root.setwriter(debugfile.write)
+        undo_tracing = config.pluginmanager.enable_tracing()
+        sys.stderr.write(f"writing pytest debug information to {path}\n")
+
+        def unset_tracing() -> None:
+            debugfile.close()
+            sys.stderr.write(f"wrote pytest debug information to {debugfile.name}\n")
+            config.trace.root.setwriter(None)
+            undo_tracing()
+
+        config.add_cleanup(unset_tracing)
+
+    return config
+
+
+def showversion(config: Config) -> None:
+    if config.option.version > 1:
+        sys.stdout.write(
+            f"This is pytest version {pytest.__version__}, imported from {pytest.__file__}\n"
+        )
+        plugininfo = getpluginversioninfo(config)
+        if plugininfo:
+            for line in plugininfo:
+                sys.stdout.write(line + "\n")
+    else:
+        sys.stdout.write(f"pytest {pytest.__version__}\n")
+
+
+def pytest_cmdline_main(config: Config) -> int | ExitCode | None:
+    if config.option.version > 0:
+        showversion(config)
+        return 0
+    elif config.option.help:
+        config._do_configure()
+        showhelp(config)
+        config._ensure_unconfigure()
+        return 0
+    return None
+
+
+def showhelp(config: Config) -> None:
+    import textwrap
+
+    reporter: TerminalReporter | None = config.pluginmanager.get_plugin(
+        "terminalreporter"
+    )
+    assert reporter is not None
+    tw = reporter._tw
+    tw.write(config._parser.optparser.format_help())
+    tw.line()
+    tw.line(
+        "[pytest] ini-options in the first "
+        "pytest.ini|tox.ini|setup.cfg|pyproject.toml file found:"
+    )
+    tw.line()
+
+    columns = tw.fullwidth  # costly call
+    indent_len = 24  # based on argparse's max_help_position=24
+    indent = " " * indent_len
+    for name in config._parser._ininames:
+        help, type, default = config._parser._inidict[name]
+        if type is None:
+            type = "string"
+        if help is None:
+            raise TypeError(f"help argument cannot be None for {name}")
+        spec = f"{name} ({type}):"
+        tw.write(f"  {spec}")
+        spec_len = len(spec)
+        if spec_len > (indent_len - 3):
+            # Display help starting at a new line.
+            tw.line()
+            helplines = textwrap.wrap(
+                help,
+                columns,
+                initial_indent=indent,
+                subsequent_indent=indent,
+                break_on_hyphens=False,
+            )
+
+            for line in helplines:
+                tw.line(line)
+        else:
+            # Display help starting after the spec, following lines indented.
+            tw.write(" " * (indent_len - spec_len - 2))
+            wrapped = textwrap.wrap(help, columns - indent_len, break_on_hyphens=False)
+
+            if wrapped:
+                tw.line(wrapped[0])
+                for line in wrapped[1:]:
+                    tw.line(indent + line)
+
+    tw.line()
+    tw.line("Environment variables:")
+    vars = [
+        (
+            "CI",
+            "When set (regardless of value), pytest knows it is running in a "
+            "CI process and does not truncate summary info",
+        ),
+        ("BUILD_NUMBER", "Equivalent to CI"),
+        ("PYTEST_ADDOPTS", "Extra command line options"),
+        ("PYTEST_PLUGINS", "Comma-separated plugins to load during startup"),
+        ("PYTEST_DISABLE_PLUGIN_AUTOLOAD", "Set to disable plugin auto-loading"),
+        ("PYTEST_DEBUG", "Set to enable debug tracing of pytest's internals"),
+    ]
+    for name, help in vars:
+        tw.line(f"  {name:<24} {help}")
+    tw.line()
+    tw.line()
+
+    tw.line("to see available markers type: pytest --markers")
+    tw.line("to see available fixtures type: pytest --fixtures")
+    tw.line(
+        "(shown according to specified file_or_dir or current dir "
+        "if not specified; fixtures with leading '_' are only shown "
+        "with the '-v' option"
+    )
+
+    for warningreport in reporter.stats.get("warnings", []):
+        tw.line("warning : " + warningreport.message, red=True)
+
+
+conftest_options = [("pytest_plugins", "list of plugin names to load")]
+
+
+def getpluginversioninfo(config: Config) -> list[str]:
+    lines = []
+    plugininfo = config.pluginmanager.list_plugin_distinfo()
+    if plugininfo:
+        lines.append("registered third-party plugins:")
+        for plugin, dist in plugininfo:
+            loc = getattr(plugin, "__file__", repr(plugin))
+            content = f"{dist.project_name}-{dist.version} at {loc}"
+            lines.append("  " + content)
+    return lines
+
+
+def pytest_report_header(config: Config) -> list[str]:
+    lines = []
+    if config.option.debug or config.option.traceconfig:
+        lines.append(f"using: pytest-{pytest.__version__}")
+
+        verinfo = getpluginversioninfo(config)
+        if verinfo:
+            lines.extend(verinfo)
+
+    if config.option.traceconfig:
+        lines.append("active plugins:")
+        items = config.pluginmanager.list_name_plugin()
+        for name, plugin in items:
+            if hasattr(plugin, "__file__"):
+                r = plugin.__file__
+            else:
+                r = repr(plugin)
+            lines.append(f"    {name:<20}: {r}")
+    return lines

.venv/lib/python3.11/site-packages/_pytest/hookspec.py

@@ -0,0 +1,1333 @@
+# mypy: allow-untyped-defs
+# ruff: noqa: T100
+"""Hook specifications for pytest plugins which are invoked by pytest itself
+and by builtin plugins."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+from typing import Mapping
+from typing import Sequence
+from typing import TYPE_CHECKING
+
+from pluggy import HookspecMarker
+
+from .deprecated import HOOK_LEGACY_PATH_ARG
+
+
+if TYPE_CHECKING:
+    import pdb
+    from typing import Literal
+    import warnings
+
+    from _pytest._code.code import ExceptionInfo
+    from _pytest._code.code import ExceptionRepr
+    from _pytest.compat import LEGACY_PATH
+    from _pytest.config import _PluggyPlugin
+    from _pytest.config import Config
+    from _pytest.config import ExitCode
+    from _pytest.config import PytestPluginManager
+    from _pytest.config.argparsing import Parser
+    from _pytest.fixtures import FixtureDef
+    from _pytest.fixtures import SubRequest
+    from _pytest.main import Session
+    from _pytest.nodes import Collector
+    from _pytest.nodes import Item
+    from _pytest.outcomes import Exit
+    from _pytest.python import Class
+    from _pytest.python import Function
+    from _pytest.python import Metafunc
+    from _pytest.python import Module
+    from _pytest.reports import CollectReport
+    from _pytest.reports import TestReport
+    from _pytest.runner import CallInfo
+    from _pytest.terminal import TerminalReporter
+    from _pytest.terminal import TestShortLogReport
+
+
+hookspec = HookspecMarker("pytest")
+
+# -------------------------------------------------------------------------
+# Initialization hooks called for every plugin
+# -------------------------------------------------------------------------
+
+
+@hookspec(historic=True)
+def pytest_addhooks(pluginmanager: PytestPluginManager) -> None:
+    """Called at plugin registration time to allow adding new hooks via a call to
+    :func:`pluginmanager.add_hookspecs(module_or_class, prefix) <pytest.PytestPluginManager.add_hookspecs>`.
+
+    :param pluginmanager: The pytest plugin manager.
+
+    .. note::
+        This hook is incompatible with hook wrappers.
+
+    Use in conftest plugins
+    =======================
+
+    If a conftest plugin implements this hook, it will be called immediately
+    when the conftest is registered.
+    """
+
+
+@hookspec(historic=True)
+def pytest_plugin_registered(
+    plugin: _PluggyPlugin,
+    plugin_name: str,
+    manager: PytestPluginManager,
+) -> None:
+    """A new pytest plugin got registered.
+
+    :param plugin: The plugin module or instance.
+    :param plugin_name: The name by which the plugin is registered.
+    :param manager: The pytest plugin manager.
+
+    .. note::
+        This hook is incompatible with hook wrappers.
+
+    Use in conftest plugins
+    =======================
+
+    If a conftest plugin implements this hook, it will be called immediately
+    when the conftest is registered, once for each plugin registered thus far
+    (including itself!), and for all plugins thereafter when they are
+    registered.
+    """
+
+
+@hookspec(historic=True)
+def pytest_addoption(parser: Parser, pluginmanager: PytestPluginManager) -> None:
+    """Register argparse-style options and ini-style config values,
+    called once at the beginning of a test run.
+
+    :param parser:
+        To add command line options, call
+        :py:func:`parser.addoption(...) <pytest.Parser.addoption>`.
+        To add ini-file values call :py:func:`parser.addini(...)
+        <pytest.Parser.addini>`.
+
+    :param pluginmanager:
+        The pytest plugin manager, which can be used to install :py:func:`~pytest.hookspec`'s
+        or :py:func:`~pytest.hookimpl`'s and allow one plugin to call another plugin's hooks
+        to change how command line options are added.
+
+    Options can later be accessed through the
+    :py:class:`config <pytest.Config>` object, respectively:
+
+    - :py:func:`config.getoption(name) <pytest.Config.getoption>` to
+      retrieve the value of a command line option.
+
+    - :py:func:`config.getini(name) <pytest.Config.getini>` to retrieve
+      a value read from an ini-style file.
+
+    The config object is passed around on many internal objects via the ``.config``
+    attribute or can be retrieved as the ``pytestconfig`` fixture.
+
+    .. note::
+        This hook is incompatible with hook wrappers.
+
+    Use in conftest plugins
+    =======================
+
+    If a conftest plugin implements this hook, it will be called immediately
+    when the conftest is registered.
+
+    This hook is only called for :ref:`initial conftests <pluginorder>`.
+    """
+
+
+@hookspec(historic=True)
+def pytest_configure(config: Config) -> None:
+    """Allow plugins and conftest files to perform initial configuration.
+
+    .. note::
+        This hook is incompatible with hook wrappers.
+
+    :param config: The pytest config object.
+
+    Use in conftest plugins
+    =======================
+
+    This hook is called for every :ref:`initial conftest <pluginorder>` file
+    after command line options have been parsed. After that, the hook is called
+    for other conftest files as they are registered.
+    """
+
+
+# -------------------------------------------------------------------------
+# Bootstrapping hooks called for plugins registered early enough:
+# internal and 3rd party plugins.
+# -------------------------------------------------------------------------
+
+
+@hookspec(firstresult=True)
+def pytest_cmdline_parse(
+    pluginmanager: PytestPluginManager, args: list[str]
+) -> Config | None:
+    """Return an initialized :class:`~pytest.Config`, parsing the specified args.
+
+    Stops at first non-None result, see :ref:`firstresult`.
+
+    .. note::
+        This hook is only called for plugin classes passed to the
+        ``plugins`` arg when using `pytest.main`_ to perform an in-process
+        test run.
+
+    :param pluginmanager: The pytest plugin manager.
+    :param args: List of arguments passed on the command line.
+    :returns: A pytest config object.
+
+    Use in conftest plugins
+    =======================
+
+    This hook is not called for conftest files.
+    """
+
+
+def pytest_load_initial_conftests(
+    early_config: Config, parser: Parser, args: list[str]
+) -> None:
+    """Called to implement the loading of :ref:`initial conftest files
+    <pluginorder>` ahead of command line option parsing.
+
+    :param early_config: The pytest config object.
+    :param args: Arguments passed on the command line.
+    :param parser: To add command line options.
+
+    Use in conftest plugins
+    =======================
+
+    This hook is not called for conftest files.
+    """
+
+
+@hookspec(firstresult=True)
+def pytest_cmdline_main(config: Config) -> ExitCode | int | None:
+    """Called for performing the main command line action.
+
+    The default implementation will invoke the configure hooks and
+    :hook:`pytest_runtestloop`.
+
+    Stops at first non-None result, see :ref:`firstresult`.
+
+    :param config: The pytest config object.
+    :returns: The exit code.
+
+    Use in conftest plugins
+    =======================
+
+    This hook is only called for :ref:`initial conftests <pluginorder>`.
+    """
+
+
+# -------------------------------------------------------------------------
+# collection hooks
+# -------------------------------------------------------------------------
+
+
+@hookspec(firstresult=True)
+def pytest_collection(session: Session) -> object | None:
+    """Perform the collection phase for the given session.
+
+    Stops at first non-None result, see :ref:`firstresult`.
+    The return value is not used, but only stops further processing.
+
+    The default collection phase is this (see individual hooks for full details):
+
+    1. Starting from ``session`` as the initial collector:
+
+      1. ``pytest_collectstart(collector)``
+      2. ``report = pytest_make_collect_report(collector)``
+      3. ``pytest_exception_interact(collector, call, report)`` if an interactive exception occurred
+      4. For each collected node:
+
+        1. If an item, ``pytest_itemcollected(item)``
+        2. If a collector, recurse into it.
+
+      5. ``pytest_collectreport(report)``
+
+    2. ``pytest_collection_modifyitems(session, config, items)``
+
+      1. ``pytest_deselected(items)`` for any deselected items (may be called multiple times)
+
+    3. ``pytest_collection_finish(session)``
+    4. Set ``session.items`` to the list of collected items
+    5. Set ``session.testscollected`` to the number of collected items
+
+    You can implement this hook to only perform some action before collection,
+    for example the terminal plugin uses it to start displaying the collection
+    counter (and returns `None`).
+
+    :param session: The pytest session object.
+
+    Use in conftest plugins
+    =======================
+
+    This hook is only called for :ref:`initial conftests <pluginorder>`.
+    """
+
+
+def pytest_collection_modifyitems(
+    session: Session, config: Config, items: list[Item]
+) -> None:
+    """Called after collection has been performed. May filter or re-order
+    the items in-place.
+
+    When items are deselected (filtered out from ``items``),
+    the hook :hook:`pytest_deselected` must be called explicitly
+    with the deselected items to properly notify other plugins,
+    e.g. with ``config.hook.pytest_deselected(deselected_items)``.
+
+    :param session: The pytest session object.
+    :param config: The pytest config object.
+    :param items: List of item objects.
+
+    Use in conftest plugins
+    =======================
+
+    Any conftest plugin can implement this hook.
+    """
+
+
+def pytest_collection_finish(session: Session) -> None:
+    """Called after collection has been performed and modified.
+
+    :param session: The pytest session object.
+
+    Use in conftest plugins
+    =======================
+
+    Any conftest plugin can implement this hook.
+    """
+
+
+@hookspec(
+    firstresult=True,
+    warn_on_impl_args={
+        "path": HOOK_LEGACY_PATH_ARG.format(
+            pylib_path_arg="path", pathlib_path_arg="collection_path"
+        ),
+    },
+)
+def pytest_ignore_collect(
+    collection_path: Path, path: LEGACY_PATH, config: Config
+) -> bool | None:
+    """Return ``True`` to ignore this path for collection.
+
+    Return ``None`` to let other plugins ignore the path for collection.
+
+    Returning ``False`` will forcefully *not* ignore this path for collection,
+    without giving a chance for other plugins to ignore this path.
+
+    This hook is consulted for all files and directories prior to calling
+    more specific hooks.
+
+    Stops at first non-None result, see :ref:`firstresult`.
+
+    :param collection_path: The path to analyze.
+    :type collection_path: pathlib.Path
+    :param path: The path to analyze (deprecated).
+    :param config: The pytest config object.
+
+    .. versionchanged:: 7.0.0
+        The ``collection_path`` parameter was added as a :class:`pathlib.Path`
+        equivalent of the ``path`` parameter. The ``path`` parameter
+        has been deprecated.
+
+    Use in conftest plugins
+    =======================
+
+    Any conftest file can implement this hook. For a given collection path, only
+    conftest files in parent directories of the collection path are consulted
+    (if the path is a directory, its own conftest file is *not* consulted - a
+    directory cannot ignore itself!).
+    """
+
+
+@hookspec(firstresult=True)
+def pytest_collect_directory(path: Path, parent: Collector) -> Collector | None:
+    """Create a :class:`~pytest.Collector` for the given directory, or None if
+    not relevant.
+
+    .. versionadded:: 8.0
+
+    For best results, the returned collector should be a subclass of
+    :class:`~pytest.Directory`, but this is not required.
+
+    The new node needs to have the specified ``parent`` as a parent.
+
+    Stops at first non-None result, see :ref:`firstresult`.
+
+    :param path: The path to analyze.
+    :type path: pathlib.Path
+
+    See :ref:`custom directory collectors` for a simple example of use of this
+    hook.
+
+    Use in conftest plugins
+    =======================
+
+    Any conftest file can implement this hook. For a given collection path, only
+    conftest files in parent directories of the collection path are consulted
+    (if the path is a directory, its own conftest file is *not* consulted - a
+    directory cannot collect itself!).
+    """
+
+
+@hookspec(
+    warn_on_impl_args={
+        "path": HOOK_LEGACY_PATH_ARG.format(
+            pylib_path_arg="path", pathlib_path_arg="file_path"
+        ),
+    },
+)
+def pytest_collect_file(
+    file_path: Path, path: LEGACY_PATH, parent: Collector
+) -> Collector | None:
+    """Create a :class:`~pytest.Collector` for the given path, or None if not relevant.
+
+    For best results, the returned collector should be a subclass of
+    :class:`~pytest.File`, but this is not required.
+
+    The new node needs to have the specified ``parent`` as a parent.
+
+    :param file_path: The path to analyze.
+    :type file_path: pathlib.Path
+    :param path: The path to collect (deprecated).
+
+    .. versionchanged:: 7.0.0
+        The ``file_path`` parameter was added as a :class:`pathlib.Path`
+        equivalent of the ``path`` parameter. The ``path`` parameter
+        has been deprecated.
+
+    Use in conftest plugins
+    =======================
+
+    Any conftest file can implement this hook. For a given file path, only
+    conftest files in parent directories of the file path are consulted.
+    """
+
+
+# logging hooks for collection
+
+
+def pytest_collectstart(collector: Collector) -> None:
+    """Collector starts collecting.
+
+    :param collector:
+        The collector.
+
+    Use in conftest plugins
+    =======================
+
+    Any conftest file can implement this hook. For a given collector, only
+    conftest files in the collector's directory and its parent directories are
+    consulted.
+    """
+
+
+def pytest_itemcollected(item: Item) -> None:
+    """We just collected a test item.
+
+    :param item:
+        The item.
+
+    Use in conftest plugins
+    =======================
+
+    Any conftest file can implement this hook. For a given item, only conftest
+    files in the item's directory and its parent directories are consulted.
+    """
+
+
+def pytest_collectreport(report: CollectReport) -> None:
+    """Collector finished collecting.
+
+    :param report:
+        The collect report.
+
+    Use in conftest plugins
+    =======================
+
+    Any conftest file can implement this hook. For a given collector, only
+    conftest files in the collector's directory and its parent directories are
+    consulted.
+    """
+
+
+def pytest_deselected(items: Sequence[Item]) -> None:
+    """Called for deselected test items, e.g. by keyword.
+
+    Note that this hook has two integration aspects for plugins:
+
+    - it can be *implemented* to be notified of deselected items
+    - it must be *called* from :hook:`pytest_collection_modifyitems`
+      implementations when items are deselected (to properly notify other plugins).
+
+    May be called multiple times.
+
+    :param items:
+        The items.
+
+    Use in conftest plugins
+    =======================
+
+    Any conftest file can implement this hook.
+    """
+
+
+@hookspec(firstresult=True)
+def pytest_make_collect_report(collector: Collector) -> CollectReport | None:
+    """Perform :func:`collector.collect() <pytest.Collector.collect>` and return
+    a :class:`~pytest.CollectReport`.
+
+    Stops at first non-None result, see :ref:`firstresult`.
+
+    :param collector:
+        The collector.
+
+    Use in conftest plugins
+    =======================
+
+    Any conftest file can implement this hook. For a given collector, only
+    conftest files in the collector's directory and its parent directories are
+    consulted.
+    """
+
+
+# -------------------------------------------------------------------------
+# Python test function related hooks
+# -------------------------------------------------------------------------
+
+
+@hookspec(
+    firstresult=True,
+    warn_on_impl_args={
+        "path": HOOK_LEGACY_PATH_ARG.format(
+            pylib_path_arg="path", pathlib_path_arg="module_path"
+        ),
+    },
+)
+def pytest_pycollect_makemodule(
+    module_path: Path, path: LEGACY_PATH, parent
+) -> Module | None:
+    """Return a :class:`pytest.Module` collector or None for the given path.
+
+    This hook will be called for each matching test module path.
+    The :hook:`pytest_collect_file` hook needs to be used if you want to
+    create test modules for files that do not match as a test module.
+
+    Stops at first non-None result, see :ref:`firstresult`.
+
+    :param module_path: The path of the module to collect.
+    :type module_path: pathlib.Path
+    :param path: The path of the module to collect (deprecated).
+
+    .. versionchanged:: 7.0.0
+        The ``module_path`` parameter was added as a :class:`pathlib.Path`
+        equivalent of the ``path`` parameter.
+
+        The ``path`` parameter has been deprecated in favor of ``fspath``.
+
+    Use in conftest plugins
+    =======================
+
+    Any conftest file can implement this hook. For a given parent collector,
+    only conftest files in the collector's directory and its parent directories
+    are consulted.
+    """
+
+
+@hookspec(firstresult=True)
+def pytest_pycollect_makeitem(
+    collector: Module | Class, name: str, obj: object
+) -> None | Item | Collector | list[Item | Collector]:
+    """Return a custom item/collector for a Python object in a module, or None.
+
+    Stops at first non-None result, see :ref:`firstresult`.
+
+    :param collector:
+        The module/class collector.
+    :param name:
+        The name of the object in the module/class.
+    :param obj:
+        The object.
+    :returns:
+        The created items/collectors.
+
+    Use in conftest plugins
+    =======================
+
+    Any conftest file can implement this hook. For a given collector, only
+    conftest files in the collector's directory and its parent directories
+    are consulted.
+    """
+
+
+@hookspec(firstresult=True)
+def pytest_pyfunc_call(pyfuncitem: Function) -> object | None:
+    """Call underlying test function.
+
+    Stops at first non-None result, see :ref:`firstresult`.
+
+    :param pyfuncitem:
+        The function item.
+
+    Use in conftest plugins
+    =======================
+
+    Any conftest file can implement this hook. For a given item, only
+    conftest files in the item's directory and its parent directories
+    are consulted.
+    """
+
+
+def pytest_generate_tests(metafunc: Metafunc) -> None:
+    """Generate (multiple) parametrized calls to a test function.
+
+    :param metafunc:
+        The :class:`~pytest.Metafunc` helper for the test function.
+
+    Use in conftest plugins
+    =======================
+
+    Any conftest file can implement this hook. For a given function definition,
+    only conftest files in the functions's directory and its parent directories
+    are consulted.
+    """
+
+
+@hookspec(firstresult=True)
+def pytest_make_parametrize_id(config: Config, val: object, argname: str) -> str | None:
+    """Return a user-friendly string representation of the given ``val``
+    that will be used by @pytest.mark.parametrize calls, or None if the hook
+    doesn't know about ``val``.
+
+    The parameter name is available as ``argname``, if required.
+
+    Stops at first non-None result, see :ref:`firstresult`.
+
+    :param config: The pytest config object.
+    :param val: The parametrized value.
+    :param argname: The automatic parameter name produced by pytest.
+
+    Use in conftest plugins
+    =======================
+
+    Any conftest file can implement this hook.
+    """
+
+
+# -------------------------------------------------------------------------
+# runtest related hooks
+# -------------------------------------------------------------------------
+
+
+@hookspec(firstresult=True)
+def pytest_runtestloop(session: Session) -> object | None:
+    """Perform the main runtest loop (after collection finished).
+
+    The default hook implementation performs the runtest protocol for all items
+    collected in the session (``session.items``), unless the collection failed
+    or the ``collectonly`` pytest option is set.
+
+    If at any point :py:func:`pytest.exit` is called, the loop is
+    terminated immediately.
+
+    If at any point ``session.shouldfail`` or ``session.shouldstop`` are set, the
+    loop is terminated after the runtest protocol for the current item is finished.
+
+    :param session: The pytest session object.
+
+    Stops at first non-None result, see :ref:`firstresult`.
+    The return value is not used, but only stops further processing.
+
+    Use in conftest plugins
+    =======================
+
+    Any conftest file can implement this hook.
+    """
+
+
+@hookspec(firstresult=True)
+def pytest_runtest_protocol(item: Item, nextitem: Item | None) -> object | None:
+    """Perform the runtest protocol for a single test item.
+
+    The default runtest protocol is this (see individual hooks for full details):
+
+    - ``pytest_runtest_logstart(nodeid, location)``
+
+    - Setup phase:
+        - ``call = pytest_runtest_setup(item)`` (wrapped in ``CallInfo(when="setup")``)
+        - ``report = pytest_runtest_makereport(item, call)``
+        - ``pytest_runtest_logreport(report)``
+        - ``pytest_exception_interact(call, report)`` if an interactive exception occurred
+
+    - Call phase, if the setup passed and the ``setuponly`` pytest option is not set:
+        - ``call = pytest_runtest_call(item)`` (wrapped in ``CallInfo(when="call")``)
+        - ``report = pytest_runtest_makereport(item, call)``
+        - ``pytest_runtest_logreport(report)``
+        - ``pytest_exception_interact(call, report)`` if an interactive exception occurred
+
+    - Teardown phase:
+        - ``call = pytest_runtest_teardown(item, nextitem)`` (wrapped in ``CallInfo(when="teardown")``)
+        - ``report = pytest_runtest_makereport(item, call)``
+        - ``pytest_runtest_logreport(report)``
+        - ``pytest_exception_interact(call, report)`` if an interactive exception occurred
+
+    - ``pytest_runtest_logfinish(nodeid, location)``
+
+    :param item: Test item for which the runtest protocol is performed.
+    :param nextitem: The scheduled-to-be-next test item (or None if this is the end my friend).
+
+    Stops at first non-None result, see :ref:`firstresult`.
+    The return value is not used, but only stops further processing.
+
+    Use in conftest plugins
+    =======================
+
+    Any conftest file can implement this hook.
+    """
+
+
+def pytest_runtest_logstart(nodeid: str, location: tuple[str, int | None, str]) -> None:
+    """Called at the start of running the runtest protocol for a single item.
+
+    See :hook:`pytest_runtest_protocol` for a description of the runtest protocol.
+
+    :param nodeid: Full node ID of the item.
+    :param location: A tuple of ``(filename, lineno, testname)``
+        where ``filename`` is a file path relative to ``config.rootpath``
+        and ``lineno`` is 0-based.
+
+    Use in conftest plugins
+    =======================
+
+    Any conftest file can implement this hook. For a given item, only conftest
+    files in the item's directory and its parent directories are consulted.
+    """
+
+
+def pytest_runtest_logfinish(
+    nodeid: str, location: tuple[str, int | None, str]
+) -> None:
+    """Called at the end of running the runtest protocol for a single item.
+
+    See :hook:`pytest_runtest_protocol` for a description of the runtest protocol.
+
+    :param nodeid: Full node ID of the item.
+    :param location: A tuple of ``(filename, lineno, testname)``
+        where ``filename`` is a file path relative to ``config.rootpath``
+        and ``lineno`` is 0-based.
+
+    Use in conftest plugins
+    =======================
+
+    Any conftest file can implement this hook. For a given item, only conftest
+    files in the item's directory and its parent directories are consulted.
+    """
+
+
+def pytest_runtest_setup(item: Item) -> None:
+    """Called to perform the setup phase for a test item.
+
+    The default implementation runs ``setup()`` on ``item`` and all of its
+    parents (which haven't been setup yet). This includes obtaining the
+    values of fixtures required by the item (which haven't been obtained
+    yet).
+
+    :param item:
+        The item.
+
+    Use in conftest plugins
+    =======================
+
+    Any conftest file can implement this hook. For a given item, only conftest
+    files in the item's directory and its parent directories are consulted.
+    """
+
+
+def pytest_runtest_call(item: Item) -> None:
+    """Called to run the test for test item (the call phase).
+
+    The default implementation calls ``item.runtest()``.
+
+    :param item:
+        The item.
+
+    Use in conftest plugins
+    =======================
+
+    Any conftest file can implement this hook. For a given item, only conftest
+    files in the item's directory and its parent directories are consulted.
+    """
+
+
+def pytest_runtest_teardown(item: Item, nextitem: Item | None) -> None:
+    """Called to perform the teardown phase for a test item.
+
+    The default implementation runs the finalizers and calls ``teardown()``
+    on ``item`` and all of its parents (which need to be torn down). This
+    includes running the teardown phase of fixtures required by the item (if
+    they go out of scope).
+
+    :param item:
+        The item.
+    :param nextitem:
+        The scheduled-to-be-next test item (None if no further test item is
+        scheduled). This argument is used to perform exact teardowns, i.e.
+        calling just enough finalizers so that nextitem only needs to call
+        setup functions.
+
+    Use in conftest plugins
+    =======================
+
+    Any conftest file can implement this hook. For a given item, only conftest
+    files in the item's directory and its parent directories are consulted.
+    """
+
+
+@hookspec(firstresult=True)
+def pytest_runtest_makereport(item: Item, call: CallInfo[None]) -> TestReport | None:
+    """Called to create a :class:`~pytest.TestReport` for each of
+    the setup, call and teardown runtest phases of a test item.
+
+    See :hook:`pytest_runtest_protocol` for a description of the runtest protocol.
+
+    :param item: The item.
+    :param call: The :class:`~pytest.CallInfo` for the phase.
+
+    Stops at first non-None result, see :ref:`firstresult`.
+
+    Use in conftest plugins
+    =======================
+
+    Any conftest file can implement this hook. For a given item, only conftest
+    files in the item's directory and its parent directories are consulted.
+    """
+
+
+def pytest_runtest_logreport(report: TestReport) -> None:
+    """Process the :class:`~pytest.TestReport` produced for each
+    of the setup, call and teardown runtest phases of an item.
+
+    See :hook:`pytest_runtest_protocol` for a description of the runtest protocol.
+
+    Use in conftest plugins
+    =======================
+
+    Any conftest file can implement this hook. For a given item, only conftest
+    files in the item's directory and its parent directories are consulted.
+    """
+
+
+@hookspec(firstresult=True)
+def pytest_report_to_serializable(
+    config: Config,
+    report: CollectReport | TestReport,
+) -> dict[str, Any] | None:
+    """Serialize the given report object into a data structure suitable for
+    sending over the wire, e.g. converted to JSON.
+
+    :param config: The pytest config object.
+    :param report: The report.
+
+    Use in conftest plugins
+    =======================
+
+    Any conftest file can implement this hook. The exact details may depend
+    on the plugin which calls the hook.
+    """
+
+
+@hookspec(firstresult=True)
+def pytest_report_from_serializable(
+    config: Config,
+    data: dict[str, Any],
+) -> CollectReport | TestReport | None:
+    """Restore a report object previously serialized with
+    :hook:`pytest_report_to_serializable`.
+
+    :param config: The pytest config object.
+
+    Use in conftest plugins
+    =======================
+
+    Any conftest file can implement this hook. The exact details may depend
+    on the plugin which calls the hook.
+    """
+
+
+# -------------------------------------------------------------------------
+# Fixture related hooks
+# -------------------------------------------------------------------------
+
+
+@hookspec(firstresult=True)
+def pytest_fixture_setup(
+    fixturedef: FixtureDef[Any], request: SubRequest
+) -> object | None:
+    """Perform fixture setup execution.
+
+    :param fixturedef:
+        The fixture definition object.
+    :param request:
+        The fixture request object.
+    :returns:
+        The return value of the call to the fixture function.
+
+    Stops at first non-None result, see :ref:`firstresult`.
+
+    .. note::
+        If the fixture function returns None, other implementations of
+        this hook function will continue to be called, according to the
+        behavior of the :ref:`firstresult` option.
+
+    Use in conftest plugins
+    =======================
+
+    Any conftest file can implement this hook. For a given fixture, only
+    conftest files in the fixture scope's directory and its parent directories
+    are consulted.
+    """
+
+
+def pytest_fixture_post_finalizer(
+    fixturedef: FixtureDef[Any], request: SubRequest
+) -> None:
+    """Called after fixture teardown, but before the cache is cleared, so
+    the fixture result ``fixturedef.cached_result`` is still available (not
+    ``None``).
+
+    :param fixturedef:
+        The fixture definition object.
+    :param request:
+        The fixture request object.
+
+    Use in conftest plugins
+    =======================
+
+    Any conftest file can implement this hook. For a given fixture, only
+    conftest files in the fixture scope's directory and its parent directories
+    are consulted.
+    """
+
+
+# -------------------------------------------------------------------------
+# test session related hooks
+# -------------------------------------------------------------------------
+
+
+def pytest_sessionstart(session: Session) -> None:
+    """Called after the ``Session`` object has been created and before performing collection
+    and entering the run test loop.
+
+    :param session: The pytest session object.
+
+    Use in conftest plugins
+    =======================
+
+    This hook is only called for :ref:`initial conftests <pluginorder>`.
+    """
+
+
+def pytest_sessionfinish(
+    session: Session,
+    exitstatus: int | ExitCode,
+) -> None:
+    """Called after whole test run finished, right before returning the exit status to the system.
+
+    :param session: The pytest session object.
+    :param exitstatus: The status which pytest will return to the system.
+
+    Use in conftest plugins
+    =======================
+
+    Any conftest file can implement this hook.
+    """
+
+
+def pytest_unconfigure(config: Config) -> None:
+    """Called before test process is exited.
+
+    :param config: The pytest config object.
+
+    Use in conftest plugins
+    =======================
+
+    Any conftest file can implement this hook.
+    """
+
+
+# -------------------------------------------------------------------------
+# hooks for customizing the assert methods
+# -------------------------------------------------------------------------
+
+
+def pytest_assertrepr_compare(
+    config: Config, op: str, left: object, right: object
+) -> list[str] | None:
+    """Return explanation for comparisons in failing assert expressions.
+
+    Return None for no custom explanation, otherwise return a list
+    of strings. The strings will be joined by newlines but any newlines
+    *in* a string will be escaped. Note that all but the first line will
+    be indented slightly, the intention is for the first line to be a summary.
+
+    :param config: The pytest config object.
+    :param op: The operator, e.g. `"=="`, `"!="`, `"not in"`.
+    :param left: The left operand.
+    :param right: The right operand.
+
+    Use in conftest plugins
+    =======================
+
+    Any conftest file can implement this hook. For a given item, only conftest
+    files in the item's directory and its parent directories are consulted.
+    """
+
+
+def pytest_assertion_pass(item: Item, lineno: int, orig: str, expl: str) -> None:
+    """Called whenever an assertion passes.
+
+    .. versionadded:: 5.0
+
+    Use this hook to do some processing after a passing assertion.
+    The original assertion information is available in the `orig` string
+    and the pytest introspected assertion information is available in the
+    `expl` string.
+
+    This hook must be explicitly enabled by the ``enable_assertion_pass_hook``
+    ini-file option:
+
+    .. code-block:: ini
+
+        [pytest]
+        enable_assertion_pass_hook=true
+
+    You need to **clean the .pyc** files in your project directory and interpreter libraries
+    when enabling this option, as assertions will require to be re-written.
+
+    :param item: pytest item object of current test.
+    :param lineno: Line number of the assert statement.
+    :param orig: String with the original assertion.
+    :param expl: String with the assert explanation.
+
+    Use in conftest plugins
+    =======================
+
+    Any conftest file can implement this hook. For a given item, only conftest
+    files in the item's directory and its parent directories are consulted.
+    """
+
+
+# -------------------------------------------------------------------------
+# Hooks for influencing reporting (invoked from _pytest_terminal).
+# -------------------------------------------------------------------------
+
+
+@hookspec(
+    warn_on_impl_args={
+        "startdir": HOOK_LEGACY_PATH_ARG.format(
+            pylib_path_arg="startdir", pathlib_path_arg="start_path"
+        ),
+    },
+)
+def pytest_report_header(  # type:ignore[empty-body]
+    config: Config, start_path: Path, startdir: LEGACY_PATH
+) -> str | list[str]:
+    """Return a string or list of strings to be displayed as header info for terminal reporting.
+
+    :param config: The pytest config object.
+    :param start_path: The starting dir.
+    :type start_path: pathlib.Path
+    :param startdir: The starting dir (deprecated).
+
+    .. note::
+
+        Lines returned by a plugin are displayed before those of plugins which
+        ran before it.
+        If you want to have your line(s) displayed first, use
+        :ref:`trylast=True <plugin-hookorder>`.
+
+    .. versionchanged:: 7.0.0
+        The ``start_path`` parameter was added as a :class:`pathlib.Path`
+        equivalent of the ``startdir`` parameter. The ``startdir`` parameter
+        has been deprecated.
+
+    Use in conftest plugins
+    =======================
+
+    This hook is only called for :ref:`initial conftests <pluginorder>`.
+    """
+
+
+@hookspec(
+    warn_on_impl_args={
+        "startdir": HOOK_LEGACY_PATH_ARG.format(
+            pylib_path_arg="startdir", pathlib_path_arg="start_path"
+        ),
+    },
+)
+def pytest_report_collectionfinish(  # type:ignore[empty-body]
+    config: Config,
+    start_path: Path,
+    startdir: LEGACY_PATH,
+    items: Sequence[Item],
+) -> str | list[str]:
+    """Return a string or list of strings to be displayed after collection
+    has finished successfully.
+
+    These strings will be displayed after the standard "collected X items" message.
+
+    .. versionadded:: 3.2
+
+    :param config: The pytest config object.
+    :param start_path: The starting dir.
+    :type start_path: pathlib.Path
+    :param startdir: The starting dir (deprecated).
+    :param items: List of pytest items that are going to be executed; this list should not be modified.
+
+    .. note::
+
+        Lines returned by a plugin are displayed before those of plugins which
+        ran before it.
+        If you want to have your line(s) displayed first, use
+        :ref:`trylast=True <plugin-hookorder>`.
+
+    .. versionchanged:: 7.0.0
+        The ``start_path`` parameter was added as a :class:`pathlib.Path`
+        equivalent of the ``startdir`` parameter. The ``startdir`` parameter
+        has been deprecated.
+
+    Use in conftest plugins
+    =======================
+
+    Any conftest plugin can implement this hook.
+    """
+
+
+@hookspec(firstresult=True)
+def pytest_report_teststatus(  # type:ignore[empty-body]
+    report: CollectReport | TestReport, config: Config
+) -> TestShortLogReport | tuple[str, str, str | tuple[str, Mapping[str, bool]]]:
+    """Return result-category, shortletter and verbose word for status
+    reporting.
+
+    The result-category is a category in which to count the result, for
+    example "passed", "skipped", "error" or the empty string.
+
+    The shortletter is shown as testing progresses, for example ".", "s",
+    "E" or the empty string.
+
+    The verbose word is shown as testing progresses in verbose mode, for
+    example "PASSED", "SKIPPED", "ERROR" or the empty string.
+
+    pytest may style these implicitly according to the report outcome.
+    To provide explicit styling, return a tuple for the verbose word,
+    for example ``"rerun", "R", ("RERUN", {"yellow": True})``.
+
+    :param report: The report object whose status is to be returned.
+    :param config: The pytest config object.
+    :returns: The test status.
+
+    Stops at first non-None result, see :ref:`firstresult`.
+
+    Use in conftest plugins
+    =======================
+
+    Any conftest plugin can implement this hook.
+    """
+
+
+def pytest_terminal_summary(
+    terminalreporter: TerminalReporter,
+    exitstatus: ExitCode,
+    config: Config,
+) -> None:
+    """Add a section to terminal summary reporting.
+
+    :param terminalreporter: The internal terminal reporter object.
+    :param exitstatus: The exit status that will be reported back to the OS.
+    :param config: The pytest config object.
+
+    .. versionadded:: 4.2
+        The ``config`` parameter.
+
+    Use in conftest plugins
+    =======================
+
+    Any conftest plugin can implement this hook.
+    """
+
+
+@hookspec(historic=True)
+def pytest_warning_recorded(
+    warning_message: warnings.WarningMessage,
+    when: Literal["config", "collect", "runtest"],
+    nodeid: str,
+    location: tuple[str, int, str] | None,
+) -> None:
+    """Process a warning captured by the internal pytest warnings plugin.
+
+    :param warning_message:
+        The captured warning. This is the same object produced by :class:`warnings.catch_warnings`,
+        and contains the same attributes as the parameters of :py:func:`warnings.showwarning`.
+
+    :param when:
+        Indicates when the warning was captured. Possible values:
+
+        * ``"config"``: during pytest configuration/initialization stage.
+        * ``"collect"``: during test collection.
+        * ``"runtest"``: during test execution.
+
+    :param nodeid:
+        Full id of the item. Empty string for warnings that are not specific to
+        a particular node.
+
+    :param location:
+        When available, holds information about the execution context of the captured
+        warning (filename, linenumber, function). ``function`` evaluates to <module>
+        when the execution context is at the module level.
+
+    .. versionadded:: 6.0
+
+    Use in conftest plugins
+    =======================
+
+    Any conftest file can implement this hook. If the warning is specific to a
+    particular node, only conftest files in parent directories of the node are
+    consulted.
+    """
+
+
+# -------------------------------------------------------------------------
+# Hooks for influencing skipping
+# -------------------------------------------------------------------------
+
+
+def pytest_markeval_namespace(  # type:ignore[empty-body]
+    config: Config,
+) -> dict[str, Any]:
+    """Called when constructing the globals dictionary used for
+    evaluating string conditions in xfail/skipif markers.
+
+    This is useful when the condition for a marker requires
+    objects that are expensive or impossible to obtain during
+    collection time, which is required by normal boolean
+    conditions.
+
+    .. versionadded:: 6.2
+
+    :param config: The pytest config object.
+    :returns: A dictionary of additional globals to add.
+
+    Use in conftest plugins
+    =======================
+
+    Any conftest file can implement this hook. For a given item, only conftest
+    files in parent directories of the item are consulted.
+    """
+
+
+# -------------------------------------------------------------------------
+# error handling and internal debugging hooks
+# -------------------------------------------------------------------------
+
+
+def pytest_internalerror(
+    excrepr: ExceptionRepr,
+    excinfo: ExceptionInfo[BaseException],
+) -> bool | None:
+    """Called for internal errors.
+
+    Return True to suppress the fallback handling of printing an
+    INTERNALERROR message directly to sys.stderr.
+
+    :param excrepr: The exception repr object.
+    :param excinfo: The exception info.
+
+    Use in conftest plugins
+    =======================
+
+    Any conftest plugin can implement this hook.
+    """
+
+
+def pytest_keyboard_interrupt(
+    excinfo: ExceptionInfo[KeyboardInterrupt | Exit],
+) -> None:
+    """Called for keyboard interrupt.
+
+    :param excinfo: The exception info.
+
+    Use in conftest plugins
+    =======================
+
+    Any conftest plugin can implement this hook.
+    """
+
+
+def pytest_exception_interact(
+    node: Item | Collector,
+    call: CallInfo[Any],
+    report: CollectReport | TestReport,
+) -> None:
+    """Called when an exception was raised which can potentially be
+    interactively handled.
+
+    May be called during collection (see :hook:`pytest_make_collect_report`),
+    in which case ``report`` is a :class:`~pytest.CollectReport`.
+
+    May be called during runtest of an item (see :hook:`pytest_runtest_protocol`),
+    in which case ``report`` is a :class:`~pytest.TestReport`.
+
+    This hook is not called if the exception that was raised is an internal
+    exception like ``skip.Exception``.
+
+    :param node:
+        The item or collector.
+    :param call:
+        The call information. Contains the exception.
+    :param report:
+        The collection or test report.
+
+    Use in conftest plugins
+    =======================
+
+    Any conftest file can implement this hook. For a given node, only conftest
+    files in parent directories of the node are consulted.
+    """
+
+
+def pytest_enter_pdb(config: Config, pdb: pdb.Pdb) -> None:
+    """Called upon pdb.set_trace().
+
+    Can be used by plugins to take special action just before the python
+    debugger enters interactive mode.
+
+    :param config: The pytest config object.
+    :param pdb: The Pdb instance.
+
+    Use in conftest plugins
+    =======================
+
+    Any conftest plugin can implement this hook.
+    """
+
+
+def pytest_leave_pdb(config: Config, pdb: pdb.Pdb) -> None:
+    """Called when leaving pdb (e.g. with continue after pdb.set_trace()).
+
+    Can be used by plugins to take special action just after the python
+    debugger leaves interactive mode.
+
+    :param config: The pytest config object.
+    :param pdb: The Pdb instance.
+
+    Use in conftest plugins
+    =======================
+
+    Any conftest plugin can implement this hook.
+    """

.venv/lib/python3.11/site-packages/_pytest/legacypath.py

@@ -0,0 +1,468 @@
+# mypy: allow-untyped-defs
+"""Add backward compatibility support for the legacy py path type."""
+
+from __future__ import annotations
+
+import dataclasses
+from pathlib import Path
+import shlex
+import subprocess
+from typing import Final
+from typing import final
+from typing import TYPE_CHECKING
+
+from iniconfig import SectionWrapper
+
+from _pytest.cacheprovider import Cache
+from _pytest.compat import LEGACY_PATH
+from _pytest.compat import legacy_path
+from _pytest.config import Config
+from _pytest.config import hookimpl
+from _pytest.config import PytestPluginManager
+from _pytest.deprecated import check_ispytest
+from _pytest.fixtures import fixture
+from _pytest.fixtures import FixtureRequest
+from _pytest.main import Session
+from _pytest.monkeypatch import MonkeyPatch
+from _pytest.nodes import Collector
+from _pytest.nodes import Item
+from _pytest.nodes import Node
+from _pytest.pytester import HookRecorder
+from _pytest.pytester import Pytester
+from _pytest.pytester import RunResult
+from _pytest.terminal import TerminalReporter
+from _pytest.tmpdir import TempPathFactory
+
+
+if TYPE_CHECKING:
+    import pexpect
+
+
+@final
+class Testdir:
+    """
+    Similar to :class:`Pytester`, but this class works with legacy legacy_path objects instead.
+
+    All methods just forward to an internal :class:`Pytester` instance, converting results
+    to `legacy_path` objects as necessary.
+    """
+
+    __test__ = False
+
+    CLOSE_STDIN: Final = Pytester.CLOSE_STDIN
+    TimeoutExpired: Final = Pytester.TimeoutExpired
+
+    def __init__(self, pytester: Pytester, *, _ispytest: bool = False) -> None:
+        check_ispytest(_ispytest)
+        self._pytester = pytester
+
+    @property
+    def tmpdir(self) -> LEGACY_PATH:
+        """Temporary directory where tests are executed."""
+        return legacy_path(self._pytester.path)
+
+    @property
+    def test_tmproot(self) -> LEGACY_PATH:
+        return legacy_path(self._pytester._test_tmproot)
+
+    @property
+    def request(self):
+        return self._pytester._request
+
+    @property
+    def plugins(self):
+        return self._pytester.plugins
+
+    @plugins.setter
+    def plugins(self, plugins):
+        self._pytester.plugins = plugins
+
+    @property
+    def monkeypatch(self) -> MonkeyPatch:
+        return self._pytester._monkeypatch
+
+    def make_hook_recorder(self, pluginmanager) -> HookRecorder:
+        """See :meth:`Pytester.make_hook_recorder`."""
+        return self._pytester.make_hook_recorder(pluginmanager)
+
+    def chdir(self) -> None:
+        """See :meth:`Pytester.chdir`."""
+        return self._pytester.chdir()
+
+    def finalize(self) -> None:
+        return self._pytester._finalize()
+
+    def makefile(self, ext, *args, **kwargs) -> LEGACY_PATH:
+        """See :meth:`Pytester.makefile`."""
+        if ext and not ext.startswith("."):
+            # pytester.makefile is going to throw a ValueError in a way that
+            # testdir.makefile did not, because
+            # pathlib.Path is stricter suffixes than py.path
+            # This ext arguments is likely user error, but since testdir has
+            # allowed this, we will prepend "." as a workaround to avoid breaking
+            # testdir usage that worked before
+            ext = "." + ext
+        return legacy_path(self._pytester.makefile(ext, *args, **kwargs))
+
+    def makeconftest(self, source) -> LEGACY_PATH:
+        """See :meth:`Pytester.makeconftest`."""
+        return legacy_path(self._pytester.makeconftest(source))
+
+    def makeini(self, source) -> LEGACY_PATH:
+        """See :meth:`Pytester.makeini`."""
+        return legacy_path(self._pytester.makeini(source))
+
+    def getinicfg(self, source: str) -> SectionWrapper:
+        """See :meth:`Pytester.getinicfg`."""
+        return self._pytester.getinicfg(source)
+
+    def makepyprojecttoml(self, source) -> LEGACY_PATH:
+        """See :meth:`Pytester.makepyprojecttoml`."""
+        return legacy_path(self._pytester.makepyprojecttoml(source))
+
+    def makepyfile(self, *args, **kwargs) -> LEGACY_PATH:
+        """See :meth:`Pytester.makepyfile`."""
+        return legacy_path(self._pytester.makepyfile(*args, **kwargs))
+
+    def maketxtfile(self, *args, **kwargs) -> LEGACY_PATH:
+        """See :meth:`Pytester.maketxtfile`."""
+        return legacy_path(self._pytester.maketxtfile(*args, **kwargs))
+
+    def syspathinsert(self, path=None) -> None:
+        """See :meth:`Pytester.syspathinsert`."""
+        return self._pytester.syspathinsert(path)
+
+    def mkdir(self, name) -> LEGACY_PATH:
+        """See :meth:`Pytester.mkdir`."""
+        return legacy_path(self._pytester.mkdir(name))
+
+    def mkpydir(self, name) -> LEGACY_PATH:
+        """See :meth:`Pytester.mkpydir`."""
+        return legacy_path(self._pytester.mkpydir(name))
+
+    def copy_example(self, name=None) -> LEGACY_PATH:
+        """See :meth:`Pytester.copy_example`."""
+        return legacy_path(self._pytester.copy_example(name))
+
+    def getnode(self, config: Config, arg) -> Item | Collector | None:
+        """See :meth:`Pytester.getnode`."""
+        return self._pytester.getnode(config, arg)
+
+    def getpathnode(self, path):
+        """See :meth:`Pytester.getpathnode`."""
+        return self._pytester.getpathnode(path)
+
+    def genitems(self, colitems: list[Item | Collector]) -> list[Item]:
+        """See :meth:`Pytester.genitems`."""
+        return self._pytester.genitems(colitems)
+
+    def runitem(self, source):
+        """See :meth:`Pytester.runitem`."""
+        return self._pytester.runitem(source)
+
+    def inline_runsource(self, source, *cmdlineargs):
+        """See :meth:`Pytester.inline_runsource`."""
+        return self._pytester.inline_runsource(source, *cmdlineargs)
+
+    def inline_genitems(self, *args):
+        """See :meth:`Pytester.inline_genitems`."""
+        return self._pytester.inline_genitems(*args)
+
+    def inline_run(self, *args, plugins=(), no_reraise_ctrlc: bool = False):
+        """See :meth:`Pytester.inline_run`."""
+        return self._pytester.inline_run(
+            *args, plugins=plugins, no_reraise_ctrlc=no_reraise_ctrlc
+        )
+
+    def runpytest_inprocess(self, *args, **kwargs) -> RunResult:
+        """See :meth:`Pytester.runpytest_inprocess`."""
+        return self._pytester.runpytest_inprocess(*args, **kwargs)
+
+    def runpytest(self, *args, **kwargs) -> RunResult:
+        """See :meth:`Pytester.runpytest`."""
+        return self._pytester.runpytest(*args, **kwargs)
+
+    def parseconfig(self, *args) -> Config:
+        """See :meth:`Pytester.parseconfig`."""
+        return self._pytester.parseconfig(*args)
+
+    def parseconfigure(self, *args) -> Config:
+        """See :meth:`Pytester.parseconfigure`."""
+        return self._pytester.parseconfigure(*args)
+
+    def getitem(self, source, funcname="test_func"):
+        """See :meth:`Pytester.getitem`."""
+        return self._pytester.getitem(source, funcname)
+
+    def getitems(self, source):
+        """See :meth:`Pytester.getitems`."""
+        return self._pytester.getitems(source)
+
+    def getmodulecol(self, source, configargs=(), withinit=False):
+        """See :meth:`Pytester.getmodulecol`."""
+        return self._pytester.getmodulecol(
+            source, configargs=configargs, withinit=withinit
+        )
+
+    def collect_by_name(self, modcol: Collector, name: str) -> Item | Collector | None:
+        """See :meth:`Pytester.collect_by_name`."""
+        return self._pytester.collect_by_name(modcol, name)
+
+    def popen(
+        self,
+        cmdargs,
+        stdout=subprocess.PIPE,
+        stderr=subprocess.PIPE,
+        stdin=CLOSE_STDIN,
+        **kw,
+    ):
+        """See :meth:`Pytester.popen`."""
+        return self._pytester.popen(cmdargs, stdout, stderr, stdin, **kw)
+
+    def run(self, *cmdargs, timeout=None, stdin=CLOSE_STDIN) -> RunResult:
+        """See :meth:`Pytester.run`."""
+        return self._pytester.run(*cmdargs, timeout=timeout, stdin=stdin)
+
+    def runpython(self, script) -> RunResult:
+        """See :meth:`Pytester.runpython`."""
+        return self._pytester.runpython(script)
+
+    def runpython_c(self, command):
+        """See :meth:`Pytester.runpython_c`."""
+        return self._pytester.runpython_c(command)
+
+    def runpytest_subprocess(self, *args, timeout=None) -> RunResult:
+        """See :meth:`Pytester.runpytest_subprocess`."""
+        return self._pytester.runpytest_subprocess(*args, timeout=timeout)
+
+    def spawn_pytest(self, string: str, expect_timeout: float = 10.0) -> pexpect.spawn:
+        """See :meth:`Pytester.spawn_pytest`."""
+        return self._pytester.spawn_pytest(string, expect_timeout=expect_timeout)
+
+    def spawn(self, cmd: str, expect_timeout: float = 10.0) -> pexpect.spawn:
+        """See :meth:`Pytester.spawn`."""
+        return self._pytester.spawn(cmd, expect_timeout=expect_timeout)
+
+    def __repr__(self) -> str:
+        return f"<Testdir {self.tmpdir!r}>"
+
+    def __str__(self) -> str:
+        return str(self.tmpdir)
+
+
+class LegacyTestdirPlugin:
+    @staticmethod
+    @fixture
+    def testdir(pytester: Pytester) -> Testdir:
+        """
+        Identical to :fixture:`pytester`, and provides an instance whose methods return
+        legacy ``LEGACY_PATH`` objects instead when applicable.
+
+        New code should avoid using :fixture:`testdir` in favor of :fixture:`pytester`.
+        """
+        return Testdir(pytester, _ispytest=True)
+
+
+@final
+@dataclasses.dataclass
+class TempdirFactory:
+    """Backward compatibility wrapper that implements ``py.path.local``
+    for :class:`TempPathFactory`.
+
+    .. note::
+        These days, it is preferred to use ``tmp_path_factory``.
+
+        :ref:`About the tmpdir and tmpdir_factory fixtures<tmpdir and tmpdir_factory>`.
+
+    """
+
+    _tmppath_factory: TempPathFactory
+
+    def __init__(
+        self, tmppath_factory: TempPathFactory, *, _ispytest: bool = False
+    ) -> None:
+        check_ispytest(_ispytest)
+        self._tmppath_factory = tmppath_factory
+
+    def mktemp(self, basename: str, numbered: bool = True) -> LEGACY_PATH:
+        """Same as :meth:`TempPathFactory.mktemp`, but returns a ``py.path.local`` object."""
+        return legacy_path(self._tmppath_factory.mktemp(basename, numbered).resolve())
+
+    def getbasetemp(self) -> LEGACY_PATH:
+        """Same as :meth:`TempPathFactory.getbasetemp`, but returns a ``py.path.local`` object."""
+        return legacy_path(self._tmppath_factory.getbasetemp().resolve())
+
+
+class LegacyTmpdirPlugin:
+    @staticmethod
+    @fixture(scope="session")
+    def tmpdir_factory(request: FixtureRequest) -> TempdirFactory:
+        """Return a :class:`pytest.TempdirFactory` instance for the test session."""
+        # Set dynamically by pytest_configure().
+        return request.config._tmpdirhandler  # type: ignore
+
+    @staticmethod
+    @fixture
+    def tmpdir(tmp_path: Path) -> LEGACY_PATH:
+        """Return a temporary directory (as `legacy_path`_ object)
+        which is unique to each test function invocation.
+        The temporary directory is created as a subdirectory
+        of the base temporary directory, with configurable retention,
+        as discussed in :ref:`temporary directory location and retention`.
+
+        .. note::
+            These days, it is preferred to use ``tmp_path``.
+
+            :ref:`About the tmpdir and tmpdir_factory fixtures<tmpdir and tmpdir_factory>`.
+
+        .. _legacy_path: https://py.readthedocs.io/en/latest/path.html
+        """
+        return legacy_path(tmp_path)
+
+
+def Cache_makedir(self: Cache, name: str) -> LEGACY_PATH:
+    """Return a directory path object with the given name.
+
+    Same as :func:`mkdir`, but returns a legacy py path instance.
+    """
+    return legacy_path(self.mkdir(name))
+
+
+def FixtureRequest_fspath(self: FixtureRequest) -> LEGACY_PATH:
+    """(deprecated) The file system path of the test module which collected this test."""
+    return legacy_path(self.path)
+
+
+def TerminalReporter_startdir(self: TerminalReporter) -> LEGACY_PATH:
+    """The directory from which pytest was invoked.
+
+    Prefer to use ``startpath`` which is a :class:`pathlib.Path`.
+
+    :type: LEGACY_PATH
+    """
+    return legacy_path(self.startpath)
+
+
+def Config_invocation_dir(self: Config) -> LEGACY_PATH:
+    """The directory from which pytest was invoked.
+
+    Prefer to use :attr:`invocation_params.dir <InvocationParams.dir>`,
+    which is a :class:`pathlib.Path`.
+
+    :type: LEGACY_PATH
+    """
+    return legacy_path(str(self.invocation_params.dir))
+
+
+def Config_rootdir(self: Config) -> LEGACY_PATH:
+    """The path to the :ref:`rootdir <rootdir>`.
+
+    Prefer to use :attr:`rootpath`, which is a :class:`pathlib.Path`.
+
+    :type: LEGACY_PATH
+    """
+    return legacy_path(str(self.rootpath))
+
+
+def Config_inifile(self: Config) -> LEGACY_PATH | None:
+    """The path to the :ref:`configfile <configfiles>`.
+
+    Prefer to use :attr:`inipath`, which is a :class:`pathlib.Path`.
+
+    :type: Optional[LEGACY_PATH]
+    """
+    return legacy_path(str(self.inipath)) if self.inipath else None
+
+
+def Session_startdir(self: Session) -> LEGACY_PATH:
+    """The path from which pytest was invoked.
+
+    Prefer to use ``startpath`` which is a :class:`pathlib.Path`.
+
+    :type: LEGACY_PATH
+    """
+    return legacy_path(self.startpath)
+
+
+def Config__getini_unknown_type(self, name: str, type: str, value: str | list[str]):
+    if type == "pathlist":
+        # TODO: This assert is probably not valid in all cases.
+        assert self.inipath is not None
+        dp = self.inipath.parent
+        input_values = shlex.split(value) if isinstance(value, str) else value
+        return [legacy_path(str(dp / x)) for x in input_values]
+    else:
+        raise ValueError(f"unknown configuration type: {type}", value)
+
+
+def Node_fspath(self: Node) -> LEGACY_PATH:
+    """(deprecated) returns a legacy_path copy of self.path"""
+    return legacy_path(self.path)
+
+
+def Node_fspath_set(self: Node, value: LEGACY_PATH) -> None:
+    self.path = Path(value)
+
+
+@hookimpl(tryfirst=True)
+def pytest_load_initial_conftests(early_config: Config) -> None:
+    """Monkeypatch legacy path attributes in several classes, as early as possible."""
+    mp = MonkeyPatch()
+    early_config.add_cleanup(mp.undo)
+
+    # Add Cache.makedir().
+    mp.setattr(Cache, "makedir", Cache_makedir, raising=False)
+
+    # Add FixtureRequest.fspath property.
+    mp.setattr(FixtureRequest, "fspath", property(FixtureRequest_fspath), raising=False)
+
+    # Add TerminalReporter.startdir property.
+    mp.setattr(
+        TerminalReporter, "startdir", property(TerminalReporter_startdir), raising=False
+    )
+
+    # Add Config.{invocation_dir,rootdir,inifile} properties.
+    mp.setattr(Config, "invocation_dir", property(Config_invocation_dir), raising=False)
+    mp.setattr(Config, "rootdir", property(Config_rootdir), raising=False)
+    mp.setattr(Config, "inifile", property(Config_inifile), raising=False)
+
+    # Add Session.startdir property.
+    mp.setattr(Session, "startdir", property(Session_startdir), raising=False)
+
+    # Add pathlist configuration type.
+    mp.setattr(Config, "_getini_unknown_type", Config__getini_unknown_type)
+
+    # Add Node.fspath property.
+    mp.setattr(Node, "fspath", property(Node_fspath, Node_fspath_set), raising=False)
+
+
+@hookimpl
+def pytest_configure(config: Config) -> None:
+    """Installs the LegacyTmpdirPlugin if the ``tmpdir`` plugin is also installed."""
+    if config.pluginmanager.has_plugin("tmpdir"):
+        mp = MonkeyPatch()
+        config.add_cleanup(mp.undo)
+        # Create TmpdirFactory and attach it to the config object.
+        #
+        # This is to comply with existing plugins which expect the handler to be
+        # available at pytest_configure time, but ideally should be moved entirely
+        # to the tmpdir_factory session fixture.
+        try:
+            tmp_path_factory = config._tmp_path_factory  # type: ignore[attr-defined]
+        except AttributeError:
+            # tmpdir plugin is blocked.
+            pass
+        else:
+            _tmpdirhandler = TempdirFactory(tmp_path_factory, _ispytest=True)
+            mp.setattr(config, "_tmpdirhandler", _tmpdirhandler, raising=False)
+
+        config.pluginmanager.register(LegacyTmpdirPlugin, "legacypath-tmpdir")
+
+
+@hookimpl
+def pytest_plugin_registered(plugin: object, manager: PytestPluginManager) -> None:
+    # pytester is not loaded by default and is commonly loaded from a conftest,
+    # so checking for it in `pytest_configure` is not enough.
+    is_pytester = plugin is manager.get_plugin("pytester")
+    if is_pytester and not manager.is_registered(LegacyTestdirPlugin):
+        manager.register(LegacyTestdirPlugin, "legacypath-pytester")

.venv/lib/python3.11/site-packages/_pytest/logging.py

@@ -0,0 +1,955 @@
+# mypy: allow-untyped-defs
+"""Access and control log capturing."""
+
+from __future__ import annotations
+
+from contextlib import contextmanager
+from contextlib import nullcontext
+from datetime import datetime
+from datetime import timedelta
+from datetime import timezone
+import io
+from io import StringIO
+import logging
+from logging import LogRecord
+import os
+from pathlib import Path
+import re
+from types import TracebackType
+from typing import AbstractSet
+from typing import Dict
+from typing import final
+from typing import Generator
+from typing import Generic
+from typing import List
+from typing import Literal
+from typing import Mapping
+from typing import TYPE_CHECKING
+from typing import TypeVar
+
+from _pytest import nodes
+from _pytest._io import TerminalWriter
+from _pytest.capture import CaptureManager
+from _pytest.config import _strtobool
+from _pytest.config import Config
+from _pytest.config import create_terminal_writer
+from _pytest.config import hookimpl
+from _pytest.config import UsageError
+from _pytest.config.argparsing import Parser
+from _pytest.deprecated import check_ispytest
+from _pytest.fixtures import fixture
+from _pytest.fixtures import FixtureRequest
+from _pytest.main import Session
+from _pytest.stash import StashKey
+from _pytest.terminal import TerminalReporter
+
+
+if TYPE_CHECKING:
+    logging_StreamHandler = logging.StreamHandler[StringIO]
+else:
+    logging_StreamHandler = logging.StreamHandler
+
+DEFAULT_LOG_FORMAT = "%(levelname)-8s %(name)s:%(filename)s:%(lineno)d %(message)s"
+DEFAULT_LOG_DATE_FORMAT = "%H:%M:%S"
+_ANSI_ESCAPE_SEQ = re.compile(r"\x1b\[[\d;]+m")
+caplog_handler_key = StashKey["LogCaptureHandler"]()
+caplog_records_key = StashKey[Dict[str, List[logging.LogRecord]]]()
+
+
+def _remove_ansi_escape_sequences(text: str) -> str:
+    return _ANSI_ESCAPE_SEQ.sub("", text)
+
+
+class DatetimeFormatter(logging.Formatter):
+    """A logging formatter which formats record with
+    :func:`datetime.datetime.strftime` formatter instead of
+    :func:`time.strftime` in case of microseconds in format string.
+    """
+
+    def formatTime(self, record: LogRecord, datefmt: str | None = None) -> str:
+        if datefmt and "%f" in datefmt:
+            ct = self.converter(record.created)
+            tz = timezone(timedelta(seconds=ct.tm_gmtoff), ct.tm_zone)
+            # Construct `datetime.datetime` object from `struct_time`
+            # and msecs information from `record`
+            # Using int() instead of round() to avoid it exceeding 1_000_000 and causing a ValueError (#11861).
+            dt = datetime(*ct[0:6], microsecond=int(record.msecs * 1000), tzinfo=tz)
+            return dt.strftime(datefmt)
+        # Use `logging.Formatter` for non-microsecond formats
+        return super().formatTime(record, datefmt)
+
+
+class ColoredLevelFormatter(DatetimeFormatter):
+    """A logging formatter which colorizes the %(levelname)..s part of the
+    log format passed to __init__."""
+
+    LOGLEVEL_COLOROPTS: Mapping[int, AbstractSet[str]] = {
+        logging.CRITICAL: {"red"},
+        logging.ERROR: {"red", "bold"},
+        logging.WARNING: {"yellow"},
+        logging.WARN: {"yellow"},
+        logging.INFO: {"green"},
+        logging.DEBUG: {"purple"},
+        logging.NOTSET: set(),
+    }
+    LEVELNAME_FMT_REGEX = re.compile(r"%\(levelname\)([+-.]?\d*(?:\.\d+)?s)")
+
+    def __init__(self, terminalwriter: TerminalWriter, *args, **kwargs) -> None:
+        super().__init__(*args, **kwargs)
+        self._terminalwriter = terminalwriter
+        self._original_fmt = self._style._fmt
+        self._level_to_fmt_mapping: dict[int, str] = {}
+
+        for level, color_opts in self.LOGLEVEL_COLOROPTS.items():
+            self.add_color_level(level, *color_opts)
+
+    def add_color_level(self, level: int, *color_opts: str) -> None:
+        """Add or update color opts for a log level.
+
+        :param level:
+            Log level to apply a style to, e.g. ``logging.INFO``.
+        :param color_opts:
+            ANSI escape sequence color options. Capitalized colors indicates
+            background color, i.e. ``'green', 'Yellow', 'bold'`` will give bold
+            green text on yellow background.
+
+        .. warning::
+            This is an experimental API.
+        """
+        assert self._fmt is not None
+        levelname_fmt_match = self.LEVELNAME_FMT_REGEX.search(self._fmt)
+        if not levelname_fmt_match:
+            return
+        levelname_fmt = levelname_fmt_match.group()
+
+        formatted_levelname = levelname_fmt % {"levelname": logging.getLevelName(level)}
+
+        # add ANSI escape sequences around the formatted levelname
+        color_kwargs = {name: True for name in color_opts}
+        colorized_formatted_levelname = self._terminalwriter.markup(
+            formatted_levelname, **color_kwargs
+        )
+        self._level_to_fmt_mapping[level] = self.LEVELNAME_FMT_REGEX.sub(
+            colorized_formatted_levelname, self._fmt
+        )
+
+    def format(self, record: logging.LogRecord) -> str:
+        fmt = self._level_to_fmt_mapping.get(record.levelno, self._original_fmt)
+        self._style._fmt = fmt
+        return super().format(record)
+
+
+class PercentStyleMultiline(logging.PercentStyle):
+    """A logging style with special support for multiline messages.
+
+    If the message of a record consists of multiple lines, this style
+    formats the message as if each line were logged separately.
+    """
+
+    def __init__(self, fmt: str, auto_indent: int | str | bool | None) -> None:
+        super().__init__(fmt)
+        self._auto_indent = self._get_auto_indent(auto_indent)
+
+    @staticmethod
+    def _get_auto_indent(auto_indent_option: int | str | bool | None) -> int:
+        """Determine the current auto indentation setting.
+
+        Specify auto indent behavior (on/off/fixed) by passing in
+        extra={"auto_indent": [value]} to the call to logging.log() or
+        using a --log-auto-indent [value] command line or the
+        log_auto_indent [value] config option.
+
+        Default behavior is auto-indent off.
+
+        Using the string "True" or "on" or the boolean True as the value
+        turns auto indent on, using the string "False" or "off" or the
+        boolean False or the int 0 turns it off, and specifying a
+        positive integer fixes the indentation position to the value
+        specified.
+
+        Any other values for the option are invalid, and will silently be
+        converted to the default.
+
+        :param None|bool|int|str auto_indent_option:
+            User specified option for indentation from command line, config
+            or extra kwarg. Accepts int, bool or str. str option accepts the
+            same range of values as boolean config options, as well as
+            positive integers represented in str form.
+
+        :returns:
+            Indentation value, which can be
+            -1 (automatically determine indentation) or
+            0 (auto-indent turned off) or
+            >0 (explicitly set indentation position).
+        """
+        if auto_indent_option is None:
+            return 0
+        elif isinstance(auto_indent_option, bool):
+            if auto_indent_option:
+                return -1
+            else:
+                return 0
+        elif isinstance(auto_indent_option, int):
+            return int(auto_indent_option)
+        elif isinstance(auto_indent_option, str):
+            try:
+                return int(auto_indent_option)
+            except ValueError:
+                pass
+            try:
+                if _strtobool(auto_indent_option):
+                    return -1
+            except ValueError:
+                return 0
+
+        return 0
+
+    def format(self, record: logging.LogRecord) -> str:
+        if "\n" in record.message:
+            if hasattr(record, "auto_indent"):
+                # Passed in from the "extra={}" kwarg on the call to logging.log().
+                auto_indent = self._get_auto_indent(record.auto_indent)
+            else:
+                auto_indent = self._auto_indent
+
+            if auto_indent:
+                lines = record.message.splitlines()
+                formatted = self._fmt % {**record.__dict__, "message": lines[0]}
+
+                if auto_indent < 0:
+                    indentation = _remove_ansi_escape_sequences(formatted).find(
+                        lines[0]
+                    )
+                else:
+                    # Optimizes logging by allowing a fixed indentation.
+                    indentation = auto_indent
+                lines[0] = formatted
+                return ("\n" + " " * indentation).join(lines)
+        return self._fmt % record.__dict__
+
+
+def get_option_ini(config: Config, *names: str):
+    for name in names:
+        ret = config.getoption(name)  # 'default' arg won't work as expected
+        if ret is None:
+            ret = config.getini(name)
+        if ret:
+            return ret
+
+
+def pytest_addoption(parser: Parser) -> None:
+    """Add options to control log capturing."""
+    group = parser.getgroup("logging")
+
+    def add_option_ini(option, dest, default=None, type=None, **kwargs):
+        parser.addini(
+            dest, default=default, type=type, help="Default value for " + option
+        )
+        group.addoption(option, dest=dest, **kwargs)
+
+    add_option_ini(
+        "--log-level",
+        dest="log_level",
+        default=None,
+        metavar="LEVEL",
+        help=(
+            "Level of messages to catch/display."
+            " Not set by default, so it depends on the root/parent log handler's"
+            ' effective level, where it is "WARNING" by default.'
+        ),
+    )
+    add_option_ini(
+        "--log-format",
+        dest="log_format",
+        default=DEFAULT_LOG_FORMAT,
+        help="Log format used by the logging module",
+    )
+    add_option_ini(
+        "--log-date-format",
+        dest="log_date_format",
+        default=DEFAULT_LOG_DATE_FORMAT,
+        help="Log date format used by the logging module",
+    )
+    parser.addini(
+        "log_cli",
+        default=False,
+        type="bool",
+        help='Enable log display during test run (also known as "live logging")',
+    )
+    add_option_ini(
+        "--log-cli-level", dest="log_cli_level", default=None, help="CLI logging level"
+    )
+    add_option_ini(
+        "--log-cli-format",
+        dest="log_cli_format",
+        default=None,
+        help="Log format used by the logging module",
+    )
+    add_option_ini(
+        "--log-cli-date-format",
+        dest="log_cli_date_format",
+        default=None,
+        help="Log date format used by the logging module",
+    )
+    add_option_ini(
+        "--log-file",
+        dest="log_file",
+        default=None,
+        help="Path to a file when logging will be written to",
+    )
+    add_option_ini(
+        "--log-file-mode",
+        dest="log_file_mode",
+        default="w",
+        choices=["w", "a"],
+        help="Log file open mode",
+    )
+    add_option_ini(
+        "--log-file-level",
+        dest="log_file_level",
+        default=None,
+        help="Log file logging level",
+    )
+    add_option_ini(
+        "--log-file-format",
+        dest="log_file_format",
+        default=None,
+        help="Log format used by the logging module",
+    )
+    add_option_ini(
+        "--log-file-date-format",
+        dest="log_file_date_format",
+        default=None,
+        help="Log date format used by the logging module",
+    )
+    add_option_ini(
+        "--log-auto-indent",
+        dest="log_auto_indent",
+        default=None,
+        help="Auto-indent multiline messages passed to the logging module. Accepts true|on, false|off or an integer.",
+    )
+    group.addoption(
+        "--log-disable",
+        action="append",
+        default=[],
+        dest="logger_disable",
+        help="Disable a logger by name. Can be passed multiple times.",
+    )
+
+
+_HandlerType = TypeVar("_HandlerType", bound=logging.Handler)
+
+
+# Not using @contextmanager for performance reasons.
+class catching_logs(Generic[_HandlerType]):
+    """Context manager that prepares the whole logging machinery properly."""
+
+    __slots__ = ("handler", "level", "orig_level")
+
+    def __init__(self, handler: _HandlerType, level: int | None = None) -> None:
+        self.handler = handler
+        self.level = level
+
+    def __enter__(self) -> _HandlerType:
+        root_logger = logging.getLogger()
+        if self.level is not None:
+            self.handler.setLevel(self.level)
+        root_logger.addHandler(self.handler)
+        if self.level is not None:
+            self.orig_level = root_logger.level
+            root_logger.setLevel(min(self.orig_level, self.level))
+        return self.handler
+
+    def __exit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc_val: BaseException | None,
+        exc_tb: TracebackType | None,
+    ) -> None:
+        root_logger = logging.getLogger()
+        if self.level is not None:
+            root_logger.setLevel(self.orig_level)
+        root_logger.removeHandler(self.handler)
+
+
+class LogCaptureHandler(logging_StreamHandler):
+    """A logging handler that stores log records and the log text."""
+
+    def __init__(self) -> None:
+        """Create a new log handler."""
+        super().__init__(StringIO())
+        self.records: list[logging.LogRecord] = []
+
+    def emit(self, record: logging.LogRecord) -> None:
+        """Keep the log records in a list in addition to the log text."""
+        self.records.append(record)
+        super().emit(record)
+
+    def reset(self) -> None:
+        self.records = []
+        self.stream = StringIO()
+
+    def clear(self) -> None:
+        self.records.clear()
+        self.stream = StringIO()
+
+    def handleError(self, record: logging.LogRecord) -> None:
+        if logging.raiseExceptions:
+            # Fail the test if the log message is bad (emit failed).
+            # The default behavior of logging is to print "Logging error"
+            # to stderr with the call stack and some extra details.
+            # pytest wants to make such mistakes visible during testing.
+            raise  # noqa: PLE0704
+
+
+@final
+class LogCaptureFixture:
+    """Provides access and control of log capturing."""
+
+    def __init__(self, item: nodes.Node, *, _ispytest: bool = False) -> None:
+        check_ispytest(_ispytest)
+        self._item = item
+        self._initial_handler_level: int | None = None
+        # Dict of log name -> log level.
+        self._initial_logger_levels: dict[str | None, int] = {}
+        self._initial_disabled_logging_level: int | None = None
+
+    def _finalize(self) -> None:
+        """Finalize the fixture.
+
+        This restores the log levels and the disabled logging levels changed by :meth:`set_level`.
+        """
+        # Restore log levels.
+        if self._initial_handler_level is not None:
+            self.handler.setLevel(self._initial_handler_level)
+        for logger_name, level in self._initial_logger_levels.items():
+            logger = logging.getLogger(logger_name)
+            logger.setLevel(level)
+        # Disable logging at the original disabled logging level.
+        if self._initial_disabled_logging_level is not None:
+            logging.disable(self._initial_disabled_logging_level)
+            self._initial_disabled_logging_level = None
+
+    @property
+    def handler(self) -> LogCaptureHandler:
+        """Get the logging handler used by the fixture."""
+        return self._item.stash[caplog_handler_key]
+
+    def get_records(
+        self, when: Literal["setup", "call", "teardown"]
+    ) -> list[logging.LogRecord]:
+        """Get the logging records for one of the possible test phases.
+
+        :param when:
+            Which test phase to obtain the records from.
+            Valid values are: "setup", "call" and "teardown".
+
+        :returns: The list of captured records at the given stage.
+
+        .. versionadded:: 3.4
+        """
+        return self._item.stash[caplog_records_key].get(when, [])
+
+    @property
+    def text(self) -> str:
+        """The formatted log text."""
+        return _remove_ansi_escape_sequences(self.handler.stream.getvalue())
+
+    @property
+    def records(self) -> list[logging.LogRecord]:
+        """The list of log records."""
+        return self.handler.records
+
+    @property
+    def record_tuples(self) -> list[tuple[str, int, str]]:
+        """A list of a stripped down version of log records intended
+        for use in assertion comparison.
+
+        The format of the tuple is:
+
+            (logger_name, log_level, message)
+        """
+        return [(r.name, r.levelno, r.getMessage()) for r in self.records]
+
+    @property
+    def messages(self) -> list[str]:
+        """A list of format-interpolated log messages.
+
+        Unlike 'records', which contains the format string and parameters for
+        interpolation, log messages in this list are all interpolated.
+
+        Unlike 'text', which contains the output from the handler, log
+        messages in this list are unadorned with levels, timestamps, etc,
+        making exact comparisons more reliable.
+
+        Note that traceback or stack info (from :func:`logging.exception` or
+        the `exc_info` or `stack_info` arguments to the logging functions) is
+        not included, as this is added by the formatter in the handler.
+
+        .. versionadded:: 3.7
+        """
+        return [r.getMessage() for r in self.records]
+
+    def clear(self) -> None:
+        """Reset the list of log records and the captured log text."""
+        self.handler.clear()
+
+    def _force_enable_logging(
+        self, level: int | str, logger_obj: logging.Logger
+    ) -> int:
+        """Enable the desired logging level if the global level was disabled via ``logging.disabled``.
+
+        Only enables logging levels greater than or equal to the requested ``level``.
+
+        Does nothing if the desired ``level`` wasn't disabled.
+
+        :param level:
+            The logger level caplog should capture.
+            All logging is enabled if a non-standard logging level string is supplied.
+            Valid level strings are in :data:`logging._nameToLevel`.
+        :param logger_obj: The logger object to check.
+
+        :return: The original disabled logging level.
+        """
+        original_disable_level: int = logger_obj.manager.disable
+
+        if isinstance(level, str):
+            # Try to translate the level string to an int for `logging.disable()`
+            level = logging.getLevelName(level)
+
+        if not isinstance(level, int):
+            # The level provided was not valid, so just un-disable all logging.
+            logging.disable(logging.NOTSET)
+        elif not logger_obj.isEnabledFor(level):
+            # Each level is `10` away from other levels.
+            # https://docs.python.org/3/library/logging.html#logging-levels
+            disable_level = max(level - 10, logging.NOTSET)
+            logging.disable(disable_level)
+
+        return original_disable_level
+
+    def set_level(self, level: int | str, logger: str | None = None) -> None:
+        """Set the threshold level of a logger for the duration of a test.
+
+        Logging messages which are less severe than this level will not be captured.
+
+        .. versionchanged:: 3.4
+            The levels of the loggers changed by this function will be
+            restored to their initial values at the end of the test.
+
+        Will enable the requested logging level if it was disabled via :func:`logging.disable`.
+
+        :param level: The level.
+        :param logger: The logger to update. If not given, the root logger.
+        """
+        logger_obj = logging.getLogger(logger)
+        # Save the original log-level to restore it during teardown.
+        self._initial_logger_levels.setdefault(logger, logger_obj.level)
+        logger_obj.setLevel(level)
+        if self._initial_handler_level is None:
+            self._initial_handler_level = self.handler.level
+        self.handler.setLevel(level)
+        initial_disabled_logging_level = self._force_enable_logging(level, logger_obj)
+        if self._initial_disabled_logging_level is None:
+            self._initial_disabled_logging_level = initial_disabled_logging_level
+
+    @contextmanager
+    def at_level(self, level: int | str, logger: str | None = None) -> Generator[None]:
+        """Context manager that sets the level for capturing of logs. After
+        the end of the 'with' statement the level is restored to its original
+        value.
+
+        Will enable the requested logging level if it was disabled via :func:`logging.disable`.
+
+        :param level: The level.
+        :param logger: The logger to update. If not given, the root logger.
+        """
+        logger_obj = logging.getLogger(logger)
+        orig_level = logger_obj.level
+        logger_obj.setLevel(level)
+        handler_orig_level = self.handler.level
+        self.handler.setLevel(level)
+        original_disable_level = self._force_enable_logging(level, logger_obj)
+        try:
+            yield
+        finally:
+            logger_obj.setLevel(orig_level)
+            self.handler.setLevel(handler_orig_level)
+            logging.disable(original_disable_level)
+
+    @contextmanager
+    def filtering(self, filter_: logging.Filter) -> Generator[None]:
+        """Context manager that temporarily adds the given filter to the caplog's
+        :meth:`handler` for the 'with' statement block, and removes that filter at the
+        end of the block.
+
+        :param filter_: A custom :class:`logging.Filter` object.
+
+        .. versionadded:: 7.5
+        """
+        self.handler.addFilter(filter_)
+        try:
+            yield
+        finally:
+            self.handler.removeFilter(filter_)
+
+
+@fixture
+def caplog(request: FixtureRequest) -> Generator[LogCaptureFixture]:
+    """Access and control log capturing.
+
+    Captured logs are available through the following properties/methods::
+
+    * caplog.messages        -> list of format-interpolated log messages
+    * caplog.text            -> string containing formatted log output
+    * caplog.records         -> list of logging.LogRecord instances
+    * caplog.record_tuples   -> list of (logger_name, level, message) tuples
+    * caplog.clear()         -> clear captured records and formatted log output string
+    """
+    result = LogCaptureFixture(request.node, _ispytest=True)
+    yield result
+    result._finalize()
+
+
+def get_log_level_for_setting(config: Config, *setting_names: str) -> int | None:
+    for setting_name in setting_names:
+        log_level = config.getoption(setting_name)
+        if log_level is None:
+            log_level = config.getini(setting_name)
+        if log_level:
+            break
+    else:
+        return None
+
+    if isinstance(log_level, str):
+        log_level = log_level.upper()
+    try:
+        return int(getattr(logging, log_level, log_level))
+    except ValueError as e:
+        # Python logging does not recognise this as a logging level
+        raise UsageError(
+            f"'{log_level}' is not recognized as a logging level name for "
+            f"'{setting_name}'. Please consider passing the "
+            "logging level num instead."
+        ) from e
+
+
+# run after terminalreporter/capturemanager are configured
+@hookimpl(trylast=True)
+def pytest_configure(config: Config) -> None:
+    config.pluginmanager.register(LoggingPlugin(config), "logging-plugin")
+
+
+class LoggingPlugin:
+    """Attaches to the logging module and captures log messages for each test."""
+
+    def __init__(self, config: Config) -> None:
+        """Create a new plugin to capture log messages.
+
+        The formatter can be safely shared across all handlers so
+        create a single one for the entire test session here.
+        """
+        self._config = config
+
+        # Report logging.
+        self.formatter = self._create_formatter(
+            get_option_ini(config, "log_format"),
+            get_option_ini(config, "log_date_format"),
+            get_option_ini(config, "log_auto_indent"),
+        )
+        self.log_level = get_log_level_for_setting(config, "log_level")
+        self.caplog_handler = LogCaptureHandler()
+        self.caplog_handler.setFormatter(self.formatter)
+        self.report_handler = LogCaptureHandler()
+        self.report_handler.setFormatter(self.formatter)
+
+        # File logging.
+        self.log_file_level = get_log_level_for_setting(
+            config, "log_file_level", "log_level"
+        )
+        log_file = get_option_ini(config, "log_file") or os.devnull
+        if log_file != os.devnull:
+            directory = os.path.dirname(os.path.abspath(log_file))
+            if not os.path.isdir(directory):
+                os.makedirs(directory)
+
+        self.log_file_mode = get_option_ini(config, "log_file_mode") or "w"
+        self.log_file_handler = _FileHandler(
+            log_file, mode=self.log_file_mode, encoding="UTF-8"
+        )
+        log_file_format = get_option_ini(config, "log_file_format", "log_format")
+        log_file_date_format = get_option_ini(
+            config, "log_file_date_format", "log_date_format"
+        )
+
+        log_file_formatter = DatetimeFormatter(
+            log_file_format, datefmt=log_file_date_format
+        )
+        self.log_file_handler.setFormatter(log_file_formatter)
+
+        # CLI/live logging.
+        self.log_cli_level = get_log_level_for_setting(
+            config, "log_cli_level", "log_level"
+        )
+        if self._log_cli_enabled():
+            terminal_reporter = config.pluginmanager.get_plugin("terminalreporter")
+            # Guaranteed by `_log_cli_enabled()`.
+            assert terminal_reporter is not None
+            capture_manager = config.pluginmanager.get_plugin("capturemanager")
+            # if capturemanager plugin is disabled, live logging still works.
+            self.log_cli_handler: (
+                _LiveLoggingStreamHandler | _LiveLoggingNullHandler
+            ) = _LiveLoggingStreamHandler(terminal_reporter, capture_manager)
+        else:
+            self.log_cli_handler = _LiveLoggingNullHandler()
+        log_cli_formatter = self._create_formatter(
+            get_option_ini(config, "log_cli_format", "log_format"),
+            get_option_ini(config, "log_cli_date_format", "log_date_format"),
+            get_option_ini(config, "log_auto_indent"),
+        )
+        self.log_cli_handler.setFormatter(log_cli_formatter)
+        self._disable_loggers(loggers_to_disable=config.option.logger_disable)
+
+    def _disable_loggers(self, loggers_to_disable: list[str]) -> None:
+        if not loggers_to_disable:
+            return
+
+        for name in loggers_to_disable:
+            logger = logging.getLogger(name)
+            logger.disabled = True
+
+    def _create_formatter(self, log_format, log_date_format, auto_indent):
+        # Color option doesn't exist if terminal plugin is disabled.
+        color = getattr(self._config.option, "color", "no")
+        if color != "no" and ColoredLevelFormatter.LEVELNAME_FMT_REGEX.search(
+            log_format
+        ):
+            formatter: logging.Formatter = ColoredLevelFormatter(
+                create_terminal_writer(self._config), log_format, log_date_format
+            )
+        else:
+            formatter = DatetimeFormatter(log_format, log_date_format)
+
+        formatter._style = PercentStyleMultiline(
+            formatter._style._fmt, auto_indent=auto_indent
+        )
+
+        return formatter
+
+    def set_log_path(self, fname: str) -> None:
+        """Set the filename parameter for Logging.FileHandler().
+
+        Creates parent directory if it does not exist.
+
+        .. warning::
+            This is an experimental API.
+        """
+        fpath = Path(fname)
+
+        if not fpath.is_absolute():
+            fpath = self._config.rootpath / fpath
+
+        if not fpath.parent.exists():
+            fpath.parent.mkdir(exist_ok=True, parents=True)
+
+        # https://github.com/python/mypy/issues/11193
+        stream: io.TextIOWrapper = fpath.open(mode=self.log_file_mode, encoding="UTF-8")  # type: ignore[assignment]
+        old_stream = self.log_file_handler.setStream(stream)
+        if old_stream:
+            old_stream.close()
+
+    def _log_cli_enabled(self) -> bool:
+        """Return whether live logging is enabled."""
+        enabled = self._config.getoption(
+            "--log-cli-level"
+        ) is not None or self._config.getini("log_cli")
+        if not enabled:
+            return False
+
+        terminal_reporter = self._config.pluginmanager.get_plugin("terminalreporter")
+        if terminal_reporter is None:
+            # terminal reporter is disabled e.g. by pytest-xdist.
+            return False
+
+        return True
+
+    @hookimpl(wrapper=True, tryfirst=True)
+    def pytest_sessionstart(self) -> Generator[None]:
+        self.log_cli_handler.set_when("sessionstart")
+
+        with catching_logs(self.log_cli_handler, level=self.log_cli_level):
+            with catching_logs(self.log_file_handler, level=self.log_file_level):
+                return (yield)
+
+    @hookimpl(wrapper=True, tryfirst=True)
+    def pytest_collection(self) -> Generator[None]:
+        self.log_cli_handler.set_when("collection")
+
+        with catching_logs(self.log_cli_handler, level=self.log_cli_level):
+            with catching_logs(self.log_file_handler, level=self.log_file_level):
+                return (yield)
+
+    @hookimpl(wrapper=True)
+    def pytest_runtestloop(self, session: Session) -> Generator[None, object, object]:
+        if session.config.option.collectonly:
+            return (yield)
+
+        if self._log_cli_enabled() and self._config.get_verbosity() < 1:
+            # The verbose flag is needed to avoid messy test progress output.
+            self._config.option.verbose = 1
+
+        with catching_logs(self.log_cli_handler, level=self.log_cli_level):
+            with catching_logs(self.log_file_handler, level=self.log_file_level):
+                return (yield)  # Run all the tests.
+
+    @hookimpl
+    def pytest_runtest_logstart(self) -> None:
+        self.log_cli_handler.reset()
+        self.log_cli_handler.set_when("start")
+
+    @hookimpl
+    def pytest_runtest_logreport(self) -> None:
+        self.log_cli_handler.set_when("logreport")
+
+    def _runtest_for(self, item: nodes.Item, when: str) -> Generator[None]:
+        """Implement the internals of the pytest_runtest_xxx() hooks."""
+        with catching_logs(
+            self.caplog_handler,
+            level=self.log_level,
+        ) as caplog_handler, catching_logs(
+            self.report_handler,
+            level=self.log_level,
+        ) as report_handler:
+            caplog_handler.reset()
+            report_handler.reset()
+            item.stash[caplog_records_key][when] = caplog_handler.records
+            item.stash[caplog_handler_key] = caplog_handler
+
+            try:
+                yield
+            finally:
+                log = report_handler.stream.getvalue().strip()
+                item.add_report_section(when, "log", log)
+
+    @hookimpl(wrapper=True)
+    def pytest_runtest_setup(self, item: nodes.Item) -> Generator[None]:
+        self.log_cli_handler.set_when("setup")
+
+        empty: dict[str, list[logging.LogRecord]] = {}
+        item.stash[caplog_records_key] = empty
+        yield from self._runtest_for(item, "setup")
+
+    @hookimpl(wrapper=True)
+    def pytest_runtest_call(self, item: nodes.Item) -> Generator[None]:
+        self.log_cli_handler.set_when("call")
+
+        yield from self._runtest_for(item, "call")
+
+    @hookimpl(wrapper=True)
+    def pytest_runtest_teardown(self, item: nodes.Item) -> Generator[None]:
+        self.log_cli_handler.set_when("teardown")
+
+        try:
+            yield from self._runtest_for(item, "teardown")
+        finally:
+            del item.stash[caplog_records_key]
+            del item.stash[caplog_handler_key]
+
+    @hookimpl
+    def pytest_runtest_logfinish(self) -> None:
+        self.log_cli_handler.set_when("finish")
+
+    @hookimpl(wrapper=True, tryfirst=True)
+    def pytest_sessionfinish(self) -> Generator[None]:
+        self.log_cli_handler.set_when("sessionfinish")
+
+        with catching_logs(self.log_cli_handler, level=self.log_cli_level):
+            with catching_logs(self.log_file_handler, level=self.log_file_level):
+                return (yield)
+
+    @hookimpl
+    def pytest_unconfigure(self) -> None:
+        # Close the FileHandler explicitly.
+        # (logging.shutdown might have lost the weakref?!)
+        self.log_file_handler.close()
+
+
+class _FileHandler(logging.FileHandler):
+    """A logging FileHandler with pytest tweaks."""
+
+    def handleError(self, record: logging.LogRecord) -> None:
+        # Handled by LogCaptureHandler.
+        pass
+
+
+class _LiveLoggingStreamHandler(logging_StreamHandler):
+    """A logging StreamHandler used by the live logging feature: it will
+    write a newline before the first log message in each test.
+
+    During live logging we must also explicitly disable stdout/stderr
+    capturing otherwise it will get captured and won't appear in the
+    terminal.
+    """
+
+    # Officially stream needs to be a IO[str], but TerminalReporter
+    # isn't. So force it.
+    stream: TerminalReporter = None  # type: ignore
+
+    def __init__(
+        self,
+        terminal_reporter: TerminalReporter,
+        capture_manager: CaptureManager | None,
+    ) -> None:
+        super().__init__(stream=terminal_reporter)  # type: ignore[arg-type]
+        self.capture_manager = capture_manager
+        self.reset()
+        self.set_when(None)
+        self._test_outcome_written = False
+
+    def reset(self) -> None:
+        """Reset the handler; should be called before the start of each test."""
+        self._first_record_emitted = False
+
+    def set_when(self, when: str | None) -> None:
+        """Prepare for the given test phase (setup/call/teardown)."""
+        self._when = when
+        self._section_name_shown = False
+        if when == "start":
+            self._test_outcome_written = False
+
+    def emit(self, record: logging.LogRecord) -> None:
+        ctx_manager = (
+            self.capture_manager.global_and_fixture_disabled()
+            if self.capture_manager
+            else nullcontext()
+        )
+        with ctx_manager:
+            if not self._first_record_emitted:
+                self.stream.write("\n")
+                self._first_record_emitted = True
+            elif self._when in ("teardown", "finish"):
+                if not self._test_outcome_written:
+                    self._test_outcome_written = True
+                    self.stream.write("\n")
+            if not self._section_name_shown and self._when:
+                self.stream.section("live log " + self._when, sep="-", bold=True)
+                self._section_name_shown = True
+            super().emit(record)
+
+    def handleError(self, record: logging.LogRecord) -> None:
+        # Handled by LogCaptureHandler.
+        pass
+
+
+class _LiveLoggingNullHandler(logging.NullHandler):
+    """A logging handler used when live logging is disabled."""
+
+    def reset(self) -> None:
+        pass
+
+    def set_when(self, when: str) -> None:
+        pass
+
+    def handleError(self, record: logging.LogRecord) -> None:
+        # Handled by LogCaptureHandler.
+        pass

.venv/lib/python3.11/site-packages/_pytest/nodes.py

@@ -0,0 +1,766 @@
+# mypy: allow-untyped-defs
+from __future__ import annotations
+
+import abc
+from functools import cached_property
+from inspect import signature
+import os
+import pathlib
+from pathlib import Path
+from typing import Any
+from typing import Callable
+from typing import cast
+from typing import Iterable
+from typing import Iterator
+from typing import MutableMapping
+from typing import NoReturn
+from typing import overload
+from typing import TYPE_CHECKING
+from typing import TypeVar
+import warnings
+
+import pluggy
+
+import _pytest._code
+from _pytest._code import getfslineno
+from _pytest._code.code import ExceptionInfo
+from _pytest._code.code import TerminalRepr
+from _pytest._code.code import Traceback
+from _pytest._code.code import TracebackStyle
+from _pytest.compat import LEGACY_PATH
+from _pytest.config import Config
+from _pytest.config import ConftestImportFailure
+from _pytest.config.compat import _check_path
+from _pytest.deprecated import NODE_CTOR_FSPATH_ARG
+from _pytest.mark.structures import Mark
+from _pytest.mark.structures import MarkDecorator
+from _pytest.mark.structures import NodeKeywords
+from _pytest.outcomes import fail
+from _pytest.pathlib import absolutepath
+from _pytest.pathlib import commonpath
+from _pytest.stash import Stash
+from _pytest.warning_types import PytestWarning
+
+
+if TYPE_CHECKING:
+    from typing_extensions import Self
+
+    # Imported here due to circular import.
+    from _pytest.main import Session
+
+
+SEP = "/"
+
+tracebackcutdir = Path(_pytest.__file__).parent
+
+
+_T = TypeVar("_T")
+
+
+def _imply_path(
+    node_type: type[Node],
+    path: Path | None,
+    fspath: LEGACY_PATH | None,
+) -> Path:
+    if fspath is not None:
+        warnings.warn(
+            NODE_CTOR_FSPATH_ARG.format(
+                node_type_name=node_type.__name__,
+            ),
+            stacklevel=6,
+        )
+    if path is not None:
+        if fspath is not None:
+            _check_path(path, fspath)
+        return path
+    else:
+        assert fspath is not None
+        return Path(fspath)
+
+
+_NodeType = TypeVar("_NodeType", bound="Node")
+
+
+class NodeMeta(abc.ABCMeta):
+    """Metaclass used by :class:`Node` to enforce that direct construction raises
+    :class:`Failed`.
+
+    This behaviour supports the indirection introduced with :meth:`Node.from_parent`,
+    the named constructor to be used instead of direct construction. The design
+    decision to enforce indirection with :class:`NodeMeta` was made as a
+    temporary aid for refactoring the collection tree, which was diagnosed to
+    have :class:`Node` objects whose creational patterns were overly entangled.
+    Once the refactoring is complete, this metaclass can be removed.
+
+    See https://github.com/pytest-dev/pytest/projects/3 for an overview of the
+    progress on detangling the :class:`Node` classes.
+    """
+
+    def __call__(cls, *k, **kw) -> NoReturn:
+        msg = (
+            "Direct construction of {name} has been deprecated, please use {name}.from_parent.\n"
+            "See "
+            "https://docs.pytest.org/en/stable/deprecations.html#node-construction-changed-to-node-from-parent"
+            " for more details."
+        ).format(name=f"{cls.__module__}.{cls.__name__}")
+        fail(msg, pytrace=False)
+
+    def _create(cls: type[_T], *k, **kw) -> _T:
+        try:
+            return super().__call__(*k, **kw)  # type: ignore[no-any-return,misc]
+        except TypeError:
+            sig = signature(getattr(cls, "__init__"))
+            known_kw = {k: v for k, v in kw.items() if k in sig.parameters}
+            from .warning_types import PytestDeprecationWarning
+
+            warnings.warn(
+                PytestDeprecationWarning(
+                    f"{cls} is not using a cooperative constructor and only takes {set(known_kw)}.\n"
+                    "See https://docs.pytest.org/en/stable/deprecations.html"
+                    "#constructors-of-custom-pytest-node-subclasses-should-take-kwargs "
+                    "for more details."
+                )
+            )
+
+            return super().__call__(*k, **known_kw)  # type: ignore[no-any-return,misc]
+
+
+class Node(abc.ABC, metaclass=NodeMeta):
+    r"""Base class of :class:`Collector` and :class:`Item`, the components of
+    the test collection tree.
+
+    ``Collector``\'s are the internal nodes of the tree, and ``Item``\'s are the
+    leaf nodes.
+    """
+
+    # Implemented in the legacypath plugin.
+    #: A ``LEGACY_PATH`` copy of the :attr:`path` attribute. Intended for usage
+    #: for methods not migrated to ``pathlib.Path`` yet, such as
+    #: :meth:`Item.reportinfo <pytest.Item.reportinfo>`. Will be deprecated in
+    #: a future release, prefer using :attr:`path` instead.
+    fspath: LEGACY_PATH
+
+    # Use __slots__ to make attribute access faster.
+    # Note that __dict__ is still available.
+    __slots__ = (
+        "name",
+        "parent",
+        "config",
+        "session",
+        "path",
+        "_nodeid",
+        "_store",
+        "__dict__",
+    )
+
+    def __init__(
+        self,
+        name: str,
+        parent: Node | None = None,
+        config: Config | None = None,
+        session: Session | None = None,
+        fspath: LEGACY_PATH | None = None,
+        path: Path | None = None,
+        nodeid: str | None = None,
+    ) -> None:
+        #: A unique name within the scope of the parent node.
+        self.name: str = name
+
+        #: The parent collector node.
+        self.parent = parent
+
+        if config:
+            #: The pytest config object.
+            self.config: Config = config
+        else:
+            if not parent:
+                raise TypeError("config or parent must be provided")
+            self.config = parent.config
+
+        if session:
+            #: The pytest session this node is part of.
+            self.session: Session = session
+        else:
+            if not parent:
+                raise TypeError("session or parent must be provided")
+            self.session = parent.session
+
+        if path is None and fspath is None:
+            path = getattr(parent, "path", None)
+        #: Filesystem path where this node was collected from (can be None).
+        self.path: pathlib.Path = _imply_path(type(self), path, fspath=fspath)
+
+        # The explicit annotation is to avoid publicly exposing NodeKeywords.
+        #: Keywords/markers collected from all scopes.
+        self.keywords: MutableMapping[str, Any] = NodeKeywords(self)
+
+        #: The marker objects belonging to this node.
+        self.own_markers: list[Mark] = []
+
+        #: Allow adding of extra keywords to use for matching.
+        self.extra_keyword_matches: set[str] = set()
+
+        if nodeid is not None:
+            assert "::()" not in nodeid
+            self._nodeid = nodeid
+        else:
+            if not self.parent:
+                raise TypeError("nodeid or parent must be provided")
+            self._nodeid = self.parent.nodeid + "::" + self.name
+
+        #: A place where plugins can store information on the node for their
+        #: own use.
+        self.stash: Stash = Stash()
+        # Deprecated alias. Was never public. Can be removed in a few releases.
+        self._store = self.stash
+
+    @classmethod
+    def from_parent(cls, parent: Node, **kw) -> Self:
+        """Public constructor for Nodes.
+
+        This indirection got introduced in order to enable removing
+        the fragile logic from the node constructors.
+
+        Subclasses can use ``super().from_parent(...)`` when overriding the
+        construction.
+
+        :param parent: The parent node of this Node.
+        """
+        if "config" in kw:
+            raise TypeError("config is not a valid argument for from_parent")
+        if "session" in kw:
+            raise TypeError("session is not a valid argument for from_parent")
+        return cls._create(parent=parent, **kw)
+
+    @property
+    def ihook(self) -> pluggy.HookRelay:
+        """fspath-sensitive hook proxy used to call pytest hooks."""
+        return self.session.gethookproxy(self.path)
+
+    def __repr__(self) -> str:
+        return "<{} {}>".format(self.__class__.__name__, getattr(self, "name", None))
+
+    def warn(self, warning: Warning) -> None:
+        """Issue a warning for this Node.
+
+        Warnings will be displayed after the test session, unless explicitly suppressed.
+
+        :param Warning warning:
+            The warning instance to issue.
+
+        :raises ValueError: If ``warning`` instance is not a subclass of Warning.
+
+        Example usage:
+
+        .. code-block:: python
+
+            node.warn(PytestWarning("some message"))
+            node.warn(UserWarning("some message"))
+
+        .. versionchanged:: 6.2
+            Any subclass of :class:`Warning` is now accepted, rather than only
+            :class:`PytestWarning <pytest.PytestWarning>` subclasses.
+        """
+        # enforce type checks here to avoid getting a generic type error later otherwise.
+        if not isinstance(warning, Warning):
+            raise ValueError(
+                f"warning must be an instance of Warning or subclass, got {warning!r}"
+            )
+        path, lineno = get_fslocation_from_item(self)
+        assert lineno is not None
+        warnings.warn_explicit(
+            warning,
+            category=None,
+            filename=str(path),
+            lineno=lineno + 1,
+        )
+
+    # Methods for ordering nodes.
+
+    @property
+    def nodeid(self) -> str:
+        """A ::-separated string denoting its collection tree address."""
+        return self._nodeid
+
+    def __hash__(self) -> int:
+        return hash(self._nodeid)
+
+    def setup(self) -> None:
+        pass
+
+    def teardown(self) -> None:
+        pass
+
+    def iter_parents(self) -> Iterator[Node]:
+        """Iterate over all parent collectors starting from and including self
+        up to the root of the collection tree.
+
+        .. versionadded:: 8.1
+        """
+        parent: Node | None = self
+        while parent is not None:
+            yield parent
+            parent = parent.parent
+
+    def listchain(self) -> list[Node]:
+        """Return a list of all parent collectors starting from the root of the
+        collection tree down to and including self."""
+        chain = []
+        item: Node | None = self
+        while item is not None:
+            chain.append(item)
+            item = item.parent
+        chain.reverse()
+        return chain
+
+    def add_marker(self, marker: str | MarkDecorator, append: bool = True) -> None:
+        """Dynamically add a marker object to the node.
+
+        :param marker:
+            The marker.
+        :param append:
+            Whether to append the marker, or prepend it.
+        """
+        from _pytest.mark import MARK_GEN
+
+        if isinstance(marker, MarkDecorator):
+            marker_ = marker
+        elif isinstance(marker, str):
+            marker_ = getattr(MARK_GEN, marker)
+        else:
+            raise ValueError("is not a string or pytest.mark.* Marker")
+        self.keywords[marker_.name] = marker_
+        if append:
+            self.own_markers.append(marker_.mark)
+        else:
+            self.own_markers.insert(0, marker_.mark)
+
+    def iter_markers(self, name: str | None = None) -> Iterator[Mark]:
+        """Iterate over all markers of the node.
+
+        :param name: If given, filter the results by the name attribute.
+        :returns: An iterator of the markers of the node.
+        """
+        return (x[1] for x in self.iter_markers_with_node(name=name))
+
+    def iter_markers_with_node(
+        self, name: str | None = None
+    ) -> Iterator[tuple[Node, Mark]]:
+        """Iterate over all markers of the node.
+
+        :param name: If given, filter the results by the name attribute.
+        :returns: An iterator of (node, mark) tuples.
+        """
+        for node in self.iter_parents():
+            for mark in node.own_markers:
+                if name is None or getattr(mark, "name", None) == name:
+                    yield node, mark
+
+    @overload
+    def get_closest_marker(self, name: str) -> Mark | None: ...
+
+    @overload
+    def get_closest_marker(self, name: str, default: Mark) -> Mark: ...
+
+    def get_closest_marker(self, name: str, default: Mark | None = None) -> Mark | None:
+        """Return the first marker matching the name, from closest (for
+        example function) to farther level (for example module level).
+
+        :param default: Fallback return value if no marker was found.
+        :param name: Name to filter by.
+        """
+        return next(self.iter_markers(name=name), default)
+
+    def listextrakeywords(self) -> set[str]:
+        """Return a set of all extra keywords in self and any parents."""
+        extra_keywords: set[str] = set()
+        for item in self.listchain():
+            extra_keywords.update(item.extra_keyword_matches)
+        return extra_keywords
+
+    def listnames(self) -> list[str]:
+        return [x.name for x in self.listchain()]
+
+    def addfinalizer(self, fin: Callable[[], object]) -> None:
+        """Register a function to be called without arguments when this node is
+        finalized.
+
+        This method can only be called when this node is active
+        in a setup chain, for example during self.setup().
+        """
+        self.session._setupstate.addfinalizer(fin, self)
+
+    def getparent(self, cls: type[_NodeType]) -> _NodeType | None:
+        """Get the closest parent node (including self) which is an instance of
+        the given class.
+
+        :param cls: The node class to search for.
+        :returns: The node, if found.
+        """
+        for node in self.iter_parents():
+            if isinstance(node, cls):
+                return node
+        return None
+
+    def _traceback_filter(self, excinfo: ExceptionInfo[BaseException]) -> Traceback:
+        return excinfo.traceback
+
+    def _repr_failure_py(
+        self,
+        excinfo: ExceptionInfo[BaseException],
+        style: TracebackStyle | None = None,
+    ) -> TerminalRepr:
+        from _pytest.fixtures import FixtureLookupError
+
+        if isinstance(excinfo.value, ConftestImportFailure):
+            excinfo = ExceptionInfo.from_exception(excinfo.value.cause)
+        if isinstance(excinfo.value, fail.Exception):
+            if not excinfo.value.pytrace:
+                style = "value"
+        if isinstance(excinfo.value, FixtureLookupError):
+            return excinfo.value.formatrepr()
+
+        tbfilter: bool | Callable[[ExceptionInfo[BaseException]], Traceback]
+        if self.config.getoption("fulltrace", False):
+            style = "long"
+            tbfilter = False
+        else:
+            tbfilter = self._traceback_filter
+            if style == "auto":
+                style = "long"
+        # XXX should excinfo.getrepr record all data and toterminal() process it?
+        if style is None:
+            if self.config.getoption("tbstyle", "auto") == "short":
+                style = "short"
+            else:
+                style = "long"
+
+        if self.config.get_verbosity() > 1:
+            truncate_locals = False
+        else:
+            truncate_locals = True
+
+        truncate_args = False if self.config.get_verbosity() > 2 else True
+
+        # excinfo.getrepr() formats paths relative to the CWD if `abspath` is False.
+        # It is possible for a fixture/test to change the CWD while this code runs, which
+        # would then result in the user seeing confusing paths in the failure message.
+        # To fix this, if the CWD changed, always display the full absolute path.
+        # It will be better to just always display paths relative to invocation_dir, but
+        # this requires a lot of plumbing (#6428).
+        try:
+            abspath = Path(os.getcwd()) != self.config.invocation_params.dir
+        except OSError:
+            abspath = True
+
+        return excinfo.getrepr(
+            funcargs=True,
+            abspath=abspath,
+            showlocals=self.config.getoption("showlocals", False),
+            style=style,
+            tbfilter=tbfilter,
+            truncate_locals=truncate_locals,
+            truncate_args=truncate_args,
+        )
+
+    def repr_failure(
+        self,
+        excinfo: ExceptionInfo[BaseException],
+        style: TracebackStyle | None = None,
+    ) -> str | TerminalRepr:
+        """Return a representation of a collection or test failure.
+
+        .. seealso:: :ref:`non-python tests`
+
+        :param excinfo: Exception information for the failure.
+        """
+        return self._repr_failure_py(excinfo, style)
+
+
+def get_fslocation_from_item(node: Node) -> tuple[str | Path, int | None]:
+    """Try to extract the actual location from a node, depending on available attributes:
+
+    * "location": a pair (path, lineno)
+    * "obj": a Python object that the node wraps.
+    * "path": just a path
+
+    :rtype: A tuple of (str|Path, int) with filename and 0-based line number.
+    """
+    # See Item.location.
+    location: tuple[str, int | None, str] | None = getattr(node, "location", None)
+    if location is not None:
+        return location[:2]
+    obj = getattr(node, "obj", None)
+    if obj is not None:
+        return getfslineno(obj)
+    return getattr(node, "path", "unknown location"), -1
+
+
+class Collector(Node, abc.ABC):
+    """Base class of all collectors.
+
+    Collector create children through `collect()` and thus iteratively build
+    the collection tree.
+    """
+
+    class CollectError(Exception):
+        """An error during collection, contains a custom message."""
+
+    @abc.abstractmethod
+    def collect(self) -> Iterable[Item | Collector]:
+        """Collect children (items and collectors) for this collector."""
+        raise NotImplementedError("abstract")
+
+    # TODO: This omits the style= parameter which breaks Liskov Substitution.
+    def repr_failure(  # type: ignore[override]
+        self, excinfo: ExceptionInfo[BaseException]
+    ) -> str | TerminalRepr:
+        """Return a representation of a collection failure.
+
+        :param excinfo: Exception information for the failure.
+        """
+        if isinstance(excinfo.value, self.CollectError) and not self.config.getoption(
+            "fulltrace", False
+        ):
+            exc = excinfo.value
+            return str(exc.args[0])
+
+        # Respect explicit tbstyle option, but default to "short"
+        # (_repr_failure_py uses "long" with "fulltrace" option always).
+        tbstyle = self.config.getoption("tbstyle", "auto")
+        if tbstyle == "auto":
+            tbstyle = "short"
+
+        return self._repr_failure_py(excinfo, style=tbstyle)
+
+    def _traceback_filter(self, excinfo: ExceptionInfo[BaseException]) -> Traceback:
+        if hasattr(self, "path"):
+            traceback = excinfo.traceback
+            ntraceback = traceback.cut(path=self.path)
+            if ntraceback == traceback:
+                ntraceback = ntraceback.cut(excludepath=tracebackcutdir)
+            return ntraceback.filter(excinfo)
+        return excinfo.traceback
+
+
+def _check_initialpaths_for_relpath(session: Session, path: Path) -> str | None:
+    for initial_path in session._initialpaths:
+        if commonpath(path, initial_path) == initial_path:
+            rel = str(path.relative_to(initial_path))
+            return "" if rel == "." else rel
+    return None
+
+
+class FSCollector(Collector, abc.ABC):
+    """Base class for filesystem collectors."""
+
+    def __init__(
+        self,
+        fspath: LEGACY_PATH | None = None,
+        path_or_parent: Path | Node | None = None,
+        path: Path | None = None,
+        name: str | None = None,
+        parent: Node | None = None,
+        config: Config | None = None,
+        session: Session | None = None,
+        nodeid: str | None = None,
+    ) -> None:
+        if path_or_parent:
+            if isinstance(path_or_parent, Node):
+                assert parent is None
+                parent = cast(FSCollector, path_or_parent)
+            elif isinstance(path_or_parent, Path):
+                assert path is None
+                path = path_or_parent
+
+        path = _imply_path(type(self), path, fspath=fspath)
+        if name is None:
+            name = path.name
+            if parent is not None and parent.path != path:
+                try:
+                    rel = path.relative_to(parent.path)
+                except ValueError:
+                    pass
+                else:
+                    name = str(rel)
+                name = name.replace(os.sep, SEP)
+        self.path = path
+
+        if session is None:
+            assert parent is not None
+            session = parent.session
+
+        if nodeid is None:
+            try:
+                nodeid = str(self.path.relative_to(session.config.rootpath))
+            except ValueError:
+                nodeid = _check_initialpaths_for_relpath(session, path)
+
+            if nodeid and os.sep != SEP:
+                nodeid = nodeid.replace(os.sep, SEP)
+
+        super().__init__(
+            name=name,
+            parent=parent,
+            config=config,
+            session=session,
+            nodeid=nodeid,
+            path=path,
+        )
+
+    @classmethod
+    def from_parent(
+        cls,
+        parent,
+        *,
+        fspath: LEGACY_PATH | None = None,
+        path: Path | None = None,
+        **kw,
+    ) -> Self:
+        """The public constructor."""
+        return super().from_parent(parent=parent, fspath=fspath, path=path, **kw)
+
+
+class File(FSCollector, abc.ABC):
+    """Base class for collecting tests from a file.
+
+    :ref:`non-python tests`.
+    """
+
+
+class Directory(FSCollector, abc.ABC):
+    """Base class for collecting files from a directory.
+
+    A basic directory collector does the following: goes over the files and
+    sub-directories in the directory and creates collectors for them by calling
+    the hooks :hook:`pytest_collect_directory` and :hook:`pytest_collect_file`,
+    after checking that they are not ignored using
+    :hook:`pytest_ignore_collect`.
+
+    The default directory collectors are :class:`~pytest.Dir` and
+    :class:`~pytest.Package`.
+
+    .. versionadded:: 8.0
+
+    :ref:`custom directory collectors`.
+    """
+
+
+class Item(Node, abc.ABC):
+    """Base class of all test invocation items.
+
+    Note that for a single function there might be multiple test invocation items.
+    """
+
+    nextitem = None
+
+    def __init__(
+        self,
+        name,
+        parent=None,
+        config: Config | None = None,
+        session: Session | None = None,
+        nodeid: str | None = None,
+        **kw,
+    ) -> None:
+        # The first two arguments are intentionally passed positionally,
+        # to keep plugins who define a node type which inherits from
+        # (pytest.Item, pytest.File) working (see issue #8435).
+        # They can be made kwargs when the deprecation above is done.
+        super().__init__(
+            name,
+            parent,
+            config=config,
+            session=session,
+            nodeid=nodeid,
+            **kw,
+        )
+        self._report_sections: list[tuple[str, str, str]] = []
+
+        #: A list of tuples (name, value) that holds user defined properties
+        #: for this test.
+        self.user_properties: list[tuple[str, object]] = []
+
+        self._check_item_and_collector_diamond_inheritance()
+
+    def _check_item_and_collector_diamond_inheritance(self) -> None:
+        """
+        Check if the current type inherits from both File and Collector
+        at the same time, emitting a warning accordingly (#8447).
+        """
+        cls = type(self)
+
+        # We inject an attribute in the type to avoid issuing this warning
+        # for the same class more than once, which is not helpful.
+        # It is a hack, but was deemed acceptable in order to avoid
+        # flooding the user in the common case.
+        attr_name = "_pytest_diamond_inheritance_warning_shown"
+        if getattr(cls, attr_name, False):
+            return
+        setattr(cls, attr_name, True)
+
+        problems = ", ".join(
+            base.__name__ for base in cls.__bases__ if issubclass(base, Collector)
+        )
+        if problems:
+            warnings.warn(
+                f"{cls.__name__} is an Item subclass and should not be a collector, "
+                f"however its bases {problems} are collectors.\n"
+                "Please split the Collectors and the Item into separate node types.\n"
+                "Pytest Doc example: https://docs.pytest.org/en/latest/example/nonpython.html\n"
+                "example pull request on a plugin: https://github.com/asmeurer/pytest-flakes/pull/40/",
+                PytestWarning,
+            )
+
+    @abc.abstractmethod
+    def runtest(self) -> None:
+        """Run the test case for this item.
+
+        Must be implemented by subclasses.
+
+        .. seealso:: :ref:`non-python tests`
+        """
+        raise NotImplementedError("runtest must be implemented by Item subclass")
+
+    def add_report_section(self, when: str, key: str, content: str) -> None:
+        """Add a new report section, similar to what's done internally to add
+        stdout and stderr captured output::
+
+            item.add_report_section("call", "stdout", "report section contents")
+
+        :param str when:
+            One of the possible capture states, ``"setup"``, ``"call"``, ``"teardown"``.
+        :param str key:
+            Name of the section, can be customized at will. Pytest uses ``"stdout"`` and
+            ``"stderr"`` internally.
+        :param str content:
+            The full contents as a string.
+        """
+        if content:
+            self._report_sections.append((when, key, content))
+
+    def reportinfo(self) -> tuple[os.PathLike[str] | str, int | None, str]:
+        """Get location information for this item for test reports.
+
+        Returns a tuple with three elements:
+
+        - The path of the test (default ``self.path``)
+        - The 0-based line number of the test (default ``None``)
+        - A name of the test to be shown (default ``""``)
+
+        .. seealso:: :ref:`non-python tests`
+        """
+        return self.path, None, ""
+
+    @cached_property
+    def location(self) -> tuple[str, int | None, str]:
+        """
+        Returns a tuple of ``(relfspath, lineno, testname)`` for this item
+        where ``relfspath`` is file path relative to ``config.rootpath``
+        and lineno is a 0-based line number.
+        """
+        location = self.reportinfo()
+        path = absolutepath(location[0])
+        relfspath = self.session._node_location_to_relpath(path)
+        assert type(location[2]) is str
+        return (relfspath, location[1], location[2])

.venv/lib/python3.11/site-packages/_pytest/python.py

@@ -0,0 +1,1679 @@
+# mypy: allow-untyped-defs
+"""Python test discovery, setup and run of test functions."""
+
+from __future__ import annotations
+
+import abc
+from collections import Counter
+from collections import defaultdict
+import dataclasses
+import enum
+import fnmatch
+from functools import partial
+import inspect
+import itertools
+import os
+from pathlib import Path
+import types
+from typing import Any
+from typing import Callable
+from typing import Dict
+from typing import final
+from typing import Generator
+from typing import Iterable
+from typing import Iterator
+from typing import Literal
+from typing import Mapping
+from typing import Pattern
+from typing import Sequence
+from typing import TYPE_CHECKING
+import warnings
+
+import _pytest
+from _pytest import fixtures
+from _pytest import nodes
+from _pytest._code import filter_traceback
+from _pytest._code import getfslineno
+from _pytest._code.code import ExceptionInfo
+from _pytest._code.code import TerminalRepr
+from _pytest._code.code import Traceback
+from _pytest._io.saferepr import saferepr
+from _pytest.compat import ascii_escaped
+from _pytest.compat import get_default_arg_names
+from _pytest.compat import get_real_func
+from _pytest.compat import getimfunc
+from _pytest.compat import is_async_function
+from _pytest.compat import is_generator
+from _pytest.compat import LEGACY_PATH
+from _pytest.compat import NOTSET
+from _pytest.compat import safe_getattr
+from _pytest.compat import safe_isclass
+from _pytest.config import Config
+from _pytest.config import hookimpl
+from _pytest.config.argparsing import Parser
+from _pytest.deprecated import check_ispytest
+from _pytest.fixtures import FixtureDef
+from _pytest.fixtures import FixtureRequest
+from _pytest.fixtures import FuncFixtureInfo
+from _pytest.fixtures import get_scope_node
+from _pytest.main import Session
+from _pytest.mark import MARK_GEN
+from _pytest.mark import ParameterSet
+from _pytest.mark.structures import get_unpacked_marks
+from _pytest.mark.structures import Mark
+from _pytest.mark.structures import MarkDecorator
+from _pytest.mark.structures import normalize_mark_list
+from _pytest.outcomes import fail
+from _pytest.outcomes import skip
+from _pytest.pathlib import fnmatch_ex
+from _pytest.pathlib import import_path
+from _pytest.pathlib import ImportPathMismatchError
+from _pytest.pathlib import scandir
+from _pytest.scope import _ScopeName
+from _pytest.scope import Scope
+from _pytest.stash import StashKey
+from _pytest.warning_types import PytestCollectionWarning
+from _pytest.warning_types import PytestReturnNotNoneWarning
+from _pytest.warning_types import PytestUnhandledCoroutineWarning
+
+
+if TYPE_CHECKING:
+    from typing_extensions import Self
+
+
+def pytest_addoption(parser: Parser) -> None:
+    parser.addini(
+        "python_files",
+        type="args",
+        # NOTE: default is also used in AssertionRewritingHook.
+        default=["test_*.py", "*_test.py"],
+        help="Glob-style file patterns for Python test module discovery",
+    )
+    parser.addini(
+        "python_classes",
+        type="args",
+        default=["Test"],
+        help="Prefixes or glob names for Python test class discovery",
+    )
+    parser.addini(
+        "python_functions",
+        type="args",
+        default=["test"],
+        help="Prefixes or glob names for Python test function and method discovery",
+    )
+    parser.addini(
+        "disable_test_id_escaping_and_forfeit_all_rights_to_community_support",
+        type="bool",
+        default=False,
+        help="Disable string escape non-ASCII characters, might cause unwanted "
+        "side effects(use at your own risk)",
+    )
+
+
+def pytest_generate_tests(metafunc: Metafunc) -> None:
+    for marker in metafunc.definition.iter_markers(name="parametrize"):
+        metafunc.parametrize(*marker.args, **marker.kwargs, _param_mark=marker)
+
+
+def pytest_configure(config: Config) -> None:
+    config.addinivalue_line(
+        "markers",
+        "parametrize(argnames, argvalues): call a test function multiple "
+        "times passing in different arguments in turn. argvalues generally "
+        "needs to be a list of values if argnames specifies only one name "
+        "or a list of tuples of values if argnames specifies multiple names. "
+        "Example: @parametrize('arg1', [1,2]) would lead to two calls of the "
+        "decorated test function, one with arg1=1 and another with arg1=2."
+        "see https://docs.pytest.org/en/stable/how-to/parametrize.html for more info "
+        "and examples.",
+    )
+    config.addinivalue_line(
+        "markers",
+        "usefixtures(fixturename1, fixturename2, ...): mark tests as needing "
+        "all of the specified fixtures. see "
+        "https://docs.pytest.org/en/stable/explanation/fixtures.html#usefixtures ",
+    )
+
+
+def async_warn_and_skip(nodeid: str) -> None:
+    msg = "async def functions are not natively supported and have been skipped.\n"
+    msg += (
+        "You need to install a suitable plugin for your async framework, for example:\n"
+    )
+    msg += "  - anyio\n"
+    msg += "  - pytest-asyncio\n"
+    msg += "  - pytest-tornasync\n"
+    msg += "  - pytest-trio\n"
+    msg += "  - pytest-twisted"
+    warnings.warn(PytestUnhandledCoroutineWarning(msg.format(nodeid)))
+    skip(reason="async def function and no async plugin installed (see warnings)")
+
+
+@hookimpl(trylast=True)
+def pytest_pyfunc_call(pyfuncitem: Function) -> object | None:
+    testfunction = pyfuncitem.obj
+    if is_async_function(testfunction):
+        async_warn_and_skip(pyfuncitem.nodeid)
+    funcargs = pyfuncitem.funcargs
+    testargs = {arg: funcargs[arg] for arg in pyfuncitem._fixtureinfo.argnames}
+    result = testfunction(**testargs)
+    if hasattr(result, "__await__") or hasattr(result, "__aiter__"):
+        async_warn_and_skip(pyfuncitem.nodeid)
+    elif result is not None:
+        warnings.warn(
+            PytestReturnNotNoneWarning(
+                f"Expected None, but {pyfuncitem.nodeid} returned {result!r}, which will be an error in a "
+                "future version of pytest.  Did you mean to use `assert` instead of `return`?"
+            )
+        )
+    return True
+
+
+def pytest_collect_directory(
+    path: Path, parent: nodes.Collector
+) -> nodes.Collector | None:
+    pkginit = path / "__init__.py"
+    try:
+        has_pkginit = pkginit.is_file()
+    except PermissionError:
+        # See https://github.com/pytest-dev/pytest/issues/12120#issuecomment-2106349096.
+        return None
+    if has_pkginit:
+        return Package.from_parent(parent, path=path)
+    return None
+
+
+def pytest_collect_file(file_path: Path, parent: nodes.Collector) -> Module | None:
+    if file_path.suffix == ".py":
+        if not parent.session.isinitpath(file_path):
+            if not path_matches_patterns(
+                file_path, parent.config.getini("python_files")
+            ):
+                return None
+        ihook = parent.session.gethookproxy(file_path)
+        module: Module = ihook.pytest_pycollect_makemodule(
+            module_path=file_path, parent=parent
+        )
+        return module
+    return None
+
+
+def path_matches_patterns(path: Path, patterns: Iterable[str]) -> bool:
+    """Return whether path matches any of the patterns in the list of globs given."""
+    return any(fnmatch_ex(pattern, path) for pattern in patterns)
+
+
+def pytest_pycollect_makemodule(module_path: Path, parent) -> Module:
+    return Module.from_parent(parent, path=module_path)
+
+
+@hookimpl(trylast=True)
+def pytest_pycollect_makeitem(
+    collector: Module | Class, name: str, obj: object
+) -> None | nodes.Item | nodes.Collector | list[nodes.Item | nodes.Collector]:
+    assert isinstance(collector, (Class, Module)), type(collector)
+    # Nothing was collected elsewhere, let's do it here.
+    if safe_isclass(obj):
+        if collector.istestclass(obj, name):
+            return Class.from_parent(collector, name=name, obj=obj)
+    elif collector.istestfunction(obj, name):
+        # mock seems to store unbound methods (issue473), normalize it.
+        obj = getattr(obj, "__func__", obj)
+        # We need to try and unwrap the function if it's a functools.partial
+        # or a functools.wrapped.
+        # We mustn't if it's been wrapped with mock.patch (python 2 only).
+        if not (inspect.isfunction(obj) or inspect.isfunction(get_real_func(obj))):
+            filename, lineno = getfslineno(obj)
+            warnings.warn_explicit(
+                message=PytestCollectionWarning(
+                    f"cannot collect {name!r} because it is not a function."
+                ),
+                category=None,
+                filename=str(filename),
+                lineno=lineno + 1,
+            )
+        elif getattr(obj, "__test__", True):
+            if is_generator(obj):
+                res = Function.from_parent(collector, name=name)
+                reason = (
+                    f"yield tests were removed in pytest 4.0 - {name} will be ignored"
+                )
+                res.add_marker(MARK_GEN.xfail(run=False, reason=reason))
+                res.warn(PytestCollectionWarning(reason))
+                return res
+            else:
+                return list(collector._genfunctions(name, obj))
+    return None
+
+
+class PyobjMixin(nodes.Node):
+    """this mix-in inherits from Node to carry over the typing information
+
+    as its intended to always mix in before a node
+    its position in the mro is unaffected"""
+
+    _ALLOW_MARKERS = True
+
+    @property
+    def module(self):
+        """Python module object this node was collected from (can be None)."""
+        node = self.getparent(Module)
+        return node.obj if node is not None else None
+
+    @property
+    def cls(self):
+        """Python class object this node was collected from (can be None)."""
+        node = self.getparent(Class)
+        return node.obj if node is not None else None
+
+    @property
+    def instance(self):
+        """Python instance object the function is bound to.
+
+        Returns None if not a test method, e.g. for a standalone test function,
+        a class or a module.
+        """
+        # Overridden by Function.
+        return None
+
+    @property
+    def obj(self):
+        """Underlying Python object."""
+        obj = getattr(self, "_obj", None)
+        if obj is None:
+            self._obj = obj = self._getobj()
+            # XXX evil hack
+            # used to avoid Function marker duplication
+            if self._ALLOW_MARKERS:
+                self.own_markers.extend(get_unpacked_marks(self.obj))
+                # This assumes that `obj` is called before there is a chance
+                # to add custom keys to `self.keywords`, so no fear of overriding.
+                self.keywords.update((mark.name, mark) for mark in self.own_markers)
+        return obj
+
+    @obj.setter
+    def obj(self, value):
+        self._obj = value
+
+    def _getobj(self):
+        """Get the underlying Python object. May be overwritten by subclasses."""
+        # TODO: Improve the type of `parent` such that assert/ignore aren't needed.
+        assert self.parent is not None
+        obj = self.parent.obj  # type: ignore[attr-defined]
+        return getattr(obj, self.name)
+
+    def getmodpath(self, stopatmodule: bool = True, includemodule: bool = False) -> str:
+        """Return Python path relative to the containing module."""
+        parts = []
+        for node in self.iter_parents():
+            name = node.name
+            if isinstance(node, Module):
+                name = os.path.splitext(name)[0]
+                if stopatmodule:
+                    if includemodule:
+                        parts.append(name)
+                    break
+            parts.append(name)
+        parts.reverse()
+        return ".".join(parts)
+
+    def reportinfo(self) -> tuple[os.PathLike[str] | str, int | None, str]:
+        # XXX caching?
+        path, lineno = getfslineno(self.obj)
+        modpath = self.getmodpath()
+        return path, lineno, modpath
+
+
+# As an optimization, these builtin attribute names are pre-ignored when
+# iterating over an object during collection -- the pytest_pycollect_makeitem
+# hook is not called for them.
+# fmt: off
+class _EmptyClass: pass  # noqa: E701
+IGNORED_ATTRIBUTES = frozenset.union(
+    frozenset(),
+    # Module.
+    dir(types.ModuleType("empty_module")),
+    # Some extra module attributes the above doesn't catch.
+    {"__builtins__", "__file__", "__cached__"},
+    # Class.
+    dir(_EmptyClass),
+    # Instance.
+    dir(_EmptyClass()),
+)
+del _EmptyClass
+# fmt: on
+
+
+class PyCollector(PyobjMixin, nodes.Collector, abc.ABC):
+    def funcnamefilter(self, name: str) -> bool:
+        return self._matches_prefix_or_glob_option("python_functions", name)
+
+    def isnosetest(self, obj: object) -> bool:
+        """Look for the __test__ attribute, which is applied by the
+        @nose.tools.istest decorator.
+        """
+        # We explicitly check for "is True" here to not mistakenly treat
+        # classes with a custom __getattr__ returning something truthy (like a
+        # function) as test classes.
+        return safe_getattr(obj, "__test__", False) is True
+
+    def classnamefilter(self, name: str) -> bool:
+        return self._matches_prefix_or_glob_option("python_classes", name)
+
+    def istestfunction(self, obj: object, name: str) -> bool:
+        if self.funcnamefilter(name) or self.isnosetest(obj):
+            if isinstance(obj, (staticmethod, classmethod)):
+                # staticmethods and classmethods need to be unwrapped.
+                obj = safe_getattr(obj, "__func__", False)
+            return callable(obj) and fixtures.getfixturemarker(obj) is None
+        else:
+            return False
+
+    def istestclass(self, obj: object, name: str) -> bool:
+        if not (self.classnamefilter(name) or self.isnosetest(obj)):
+            return False
+        if inspect.isabstract(obj):
+            return False
+        return True
+
+    def _matches_prefix_or_glob_option(self, option_name: str, name: str) -> bool:
+        """Check if the given name matches the prefix or glob-pattern defined
+        in ini configuration."""
+        for option in self.config.getini(option_name):
+            if name.startswith(option):
+                return True
+            # Check that name looks like a glob-string before calling fnmatch
+            # because this is called for every name in each collected module,
+            # and fnmatch is somewhat expensive to call.
+            elif ("*" in option or "?" in option or "[" in option) and fnmatch.fnmatch(
+                name, option
+            ):
+                return True
+        return False
+
+    def collect(self) -> Iterable[nodes.Item | nodes.Collector]:
+        if not getattr(self.obj, "__test__", True):
+            return []
+
+        # Avoid random getattrs and peek in the __dict__ instead.
+        dicts = [getattr(self.obj, "__dict__", {})]
+        if isinstance(self.obj, type):
+            for basecls in self.obj.__mro__:
+                dicts.append(basecls.__dict__)
+
+        # In each class, nodes should be definition ordered.
+        # __dict__ is definition ordered.
+        seen: set[str] = set()
+        dict_values: list[list[nodes.Item | nodes.Collector]] = []
+        ihook = self.ihook
+        for dic in dicts:
+            values: list[nodes.Item | nodes.Collector] = []
+            # Note: seems like the dict can change during iteration -
+            # be careful not to remove the list() without consideration.
+            for name, obj in list(dic.items()):
+                if name in IGNORED_ATTRIBUTES:
+                    continue
+                if name in seen:
+                    continue
+                seen.add(name)
+                res = ihook.pytest_pycollect_makeitem(
+                    collector=self, name=name, obj=obj
+                )
+                if res is None:
+                    continue
+                elif isinstance(res, list):
+                    values.extend(res)
+                else:
+                    values.append(res)
+            dict_values.append(values)
+
+        # Between classes in the class hierarchy, reverse-MRO order -- nodes
+        # inherited from base classes should come before subclasses.
+        result = []
+        for values in reversed(dict_values):
+            result.extend(values)
+        return result
+
+    def _genfunctions(self, name: str, funcobj) -> Iterator[Function]:
+        modulecol = self.getparent(Module)
+        assert modulecol is not None
+        module = modulecol.obj
+        clscol = self.getparent(Class)
+        cls = clscol and clscol.obj or None
+
+        definition = FunctionDefinition.from_parent(self, name=name, callobj=funcobj)
+        fixtureinfo = definition._fixtureinfo
+
+        # pytest_generate_tests impls call metafunc.parametrize() which fills
+        # metafunc._calls, the outcome of the hook.
+        metafunc = Metafunc(
+            definition=definition,
+            fixtureinfo=fixtureinfo,
+            config=self.config,
+            cls=cls,
+            module=module,
+            _ispytest=True,
+        )
+        methods = []
+        if hasattr(module, "pytest_generate_tests"):
+            methods.append(module.pytest_generate_tests)
+        if cls is not None and hasattr(cls, "pytest_generate_tests"):
+            methods.append(cls().pytest_generate_tests)
+        self.ihook.pytest_generate_tests.call_extra(methods, dict(metafunc=metafunc))
+
+        if not metafunc._calls:
+            yield Function.from_parent(self, name=name, fixtureinfo=fixtureinfo)
+        else:
+            # Direct parametrizations taking place in module/class-specific
+            # `metafunc.parametrize` calls may have shadowed some fixtures, so make sure
+            # we update what the function really needs a.k.a its fixture closure. Note that
+            # direct parametrizations using `@pytest.mark.parametrize` have already been considered
+            # into making the closure using `ignore_args` arg to `getfixtureclosure`.
+            fixtureinfo.prune_dependency_tree()
+
+            for callspec in metafunc._calls:
+                subname = f"{name}[{callspec.id}]"
+                yield Function.from_parent(
+                    self,
+                    name=subname,
+                    callspec=callspec,
+                    fixtureinfo=fixtureinfo,
+                    keywords={callspec.id: True},
+                    originalname=name,
+                )
+
+
+def importtestmodule(
+    path: Path,
+    config: Config,
+):
+    # We assume we are only called once per module.
+    importmode = config.getoption("--import-mode")
+    try:
+        mod = import_path(
+            path,
+            mode=importmode,
+            root=config.rootpath,
+            consider_namespace_packages=config.getini("consider_namespace_packages"),
+        )
+    except SyntaxError as e:
+        raise nodes.Collector.CollectError(
+            ExceptionInfo.from_current().getrepr(style="short")
+        ) from e
+    except ImportPathMismatchError as e:
+        raise nodes.Collector.CollectError(
+            "import file mismatch:\n"
+            "imported module {!r} has this __file__ attribute:\n"
+            "  {}\n"
+            "which is not the same as the test file we want to collect:\n"
+            "  {}\n"
+            "HINT: remove __pycache__ / .pyc files and/or use a "
+            "unique basename for your test file modules".format(*e.args)
+        ) from e
+    except ImportError as e:
+        exc_info = ExceptionInfo.from_current()
+        if config.get_verbosity() < 2:
+            exc_info.traceback = exc_info.traceback.filter(filter_traceback)
+        exc_repr = (
+            exc_info.getrepr(style="short")
+            if exc_info.traceback
+            else exc_info.exconly()
+        )
+        formatted_tb = str(exc_repr)
+        raise nodes.Collector.CollectError(
+            f"ImportError while importing test module '{path}'.\n"
+            "Hint: make sure your test modules/packages have valid Python names.\n"
+            "Traceback:\n"
+            f"{formatted_tb}"
+        ) from e
+    except skip.Exception as e:
+        if e.allow_module_level:
+            raise
+        raise nodes.Collector.CollectError(
+            "Using pytest.skip outside of a test will skip the entire module. "
+            "If that's your intention, pass `allow_module_level=True`. "
+            "If you want to skip a specific test or an entire class, "
+            "use the @pytest.mark.skip or @pytest.mark.skipif decorators."
+        ) from e
+    config.pluginmanager.consider_module(mod)
+    return mod
+
+
+class Module(nodes.File, PyCollector):
+    """Collector for test classes and functions in a Python module."""
+
+    def _getobj(self):
+        return importtestmodule(self.path, self.config)
+
+    def collect(self) -> Iterable[nodes.Item | nodes.Collector]:
+        self._register_setup_module_fixture()
+        self._register_setup_function_fixture()
+        self.session._fixturemanager.parsefactories(self)
+        return super().collect()
+
+    def _register_setup_module_fixture(self) -> None:
+        """Register an autouse, module-scoped fixture for the collected module object
+        that invokes setUpModule/tearDownModule if either or both are available.
+
+        Using a fixture to invoke this methods ensures we play nicely and unsurprisingly with
+        other fixtures (#517).
+        """
+        setup_module = _get_first_non_fixture_func(
+            self.obj, ("setUpModule", "setup_module")
+        )
+        teardown_module = _get_first_non_fixture_func(
+            self.obj, ("tearDownModule", "teardown_module")
+        )
+
+        if setup_module is None and teardown_module is None:
+            return
+
+        def xunit_setup_module_fixture(request) -> Generator[None]:
+            module = request.module
+            if setup_module is not None:
+                _call_with_optional_argument(setup_module, module)
+            yield
+            if teardown_module is not None:
+                _call_with_optional_argument(teardown_module, module)
+
+        self.session._fixturemanager._register_fixture(
+            # Use a unique name to speed up lookup.
+            name=f"_xunit_setup_module_fixture_{self.obj.__name__}",
+            func=xunit_setup_module_fixture,
+            nodeid=self.nodeid,
+            scope="module",
+            autouse=True,
+        )
+
+    def _register_setup_function_fixture(self) -> None:
+        """Register an autouse, function-scoped fixture for the collected module object
+        that invokes setup_function/teardown_function if either or both are available.
+
+        Using a fixture to invoke this methods ensures we play nicely and unsurprisingly with
+        other fixtures (#517).
+        """
+        setup_function = _get_first_non_fixture_func(self.obj, ("setup_function",))
+        teardown_function = _get_first_non_fixture_func(
+            self.obj, ("teardown_function",)
+        )
+        if setup_function is None and teardown_function is None:
+            return
+
+        def xunit_setup_function_fixture(request) -> Generator[None]:
+            if request.instance is not None:
+                # in this case we are bound to an instance, so we need to let
+                # setup_method handle this
+                yield
+                return
+            function = request.function
+            if setup_function is not None:
+                _call_with_optional_argument(setup_function, function)
+            yield
+            if teardown_function is not None:
+                _call_with_optional_argument(teardown_function, function)
+
+        self.session._fixturemanager._register_fixture(
+            # Use a unique name to speed up lookup.
+            name=f"_xunit_setup_function_fixture_{self.obj.__name__}",
+            func=xunit_setup_function_fixture,
+            nodeid=self.nodeid,
+            scope="function",
+            autouse=True,
+        )
+
+
+class Package(nodes.Directory):
+    """Collector for files and directories in a Python packages -- directories
+    with an `__init__.py` file.
+
+    .. note::
+
+        Directories without an `__init__.py` file are instead collected by
+        :class:`~pytest.Dir` by default. Both are :class:`~pytest.Directory`
+        collectors.
+
+    .. versionchanged:: 8.0
+
+        Now inherits from :class:`~pytest.Directory`.
+    """
+
+    def __init__(
+        self,
+        fspath: LEGACY_PATH | None,
+        parent: nodes.Collector,
+        # NOTE: following args are unused:
+        config=None,
+        session=None,
+        nodeid=None,
+        path: Path | None = None,
+    ) -> None:
+        # NOTE: Could be just the following, but kept as-is for compat.
+        # super().__init__(self, fspath, parent=parent)
+        session = parent.session
+        super().__init__(
+            fspath=fspath,
+            path=path,
+            parent=parent,
+            config=config,
+            session=session,
+            nodeid=nodeid,
+        )
+
+    def setup(self) -> None:
+        init_mod = importtestmodule(self.path / "__init__.py", self.config)
+
+        # Not using fixtures to call setup_module here because autouse fixtures
+        # from packages are not called automatically (#4085).
+        setup_module = _get_first_non_fixture_func(
+            init_mod, ("setUpModule", "setup_module")
+        )
+        if setup_module is not None:
+            _call_with_optional_argument(setup_module, init_mod)
+
+        teardown_module = _get_first_non_fixture_func(
+            init_mod, ("tearDownModule", "teardown_module")
+        )
+        if teardown_module is not None:
+            func = partial(_call_with_optional_argument, teardown_module, init_mod)
+            self.addfinalizer(func)
+
+    def collect(self) -> Iterable[nodes.Item | nodes.Collector]:
+        # Always collect __init__.py first.
+        def sort_key(entry: os.DirEntry[str]) -> object:
+            return (entry.name != "__init__.py", entry.name)
+
+        config = self.config
+        col: nodes.Collector | None
+        cols: Sequence[nodes.Collector]
+        ihook = self.ihook
+        for direntry in scandir(self.path, sort_key):
+            if direntry.is_dir():
+                path = Path(direntry.path)
+                if not self.session.isinitpath(path, with_parents=True):
+                    if ihook.pytest_ignore_collect(collection_path=path, config=config):
+                        continue
+                col = ihook.pytest_collect_directory(path=path, parent=self)
+                if col is not None:
+                    yield col
+
+            elif direntry.is_file():
+                path = Path(direntry.path)
+                if not self.session.isinitpath(path):
+                    if ihook.pytest_ignore_collect(collection_path=path, config=config):
+                        continue
+                cols = ihook.pytest_collect_file(file_path=path, parent=self)
+                yield from cols
+
+
+def _call_with_optional_argument(func, arg) -> None:
+    """Call the given function with the given argument if func accepts one argument, otherwise
+    calls func without arguments."""
+    arg_count = func.__code__.co_argcount
+    if inspect.ismethod(func):
+        arg_count -= 1
+    if arg_count:
+        func(arg)
+    else:
+        func()
+
+
+def _get_first_non_fixture_func(obj: object, names: Iterable[str]) -> object | None:
+    """Return the attribute from the given object to be used as a setup/teardown
+    xunit-style function, but only if not marked as a fixture to avoid calling it twice.
+    """
+    for name in names:
+        meth: object | None = getattr(obj, name, None)
+        if meth is not None and fixtures.getfixturemarker(meth) is None:
+            return meth
+    return None
+
+
+class Class(PyCollector):
+    """Collector for test methods (and nested classes) in a Python class."""
+
+    @classmethod
+    def from_parent(cls, parent, *, name, obj=None, **kw) -> Self:  # type: ignore[override]
+        """The public constructor."""
+        return super().from_parent(name=name, parent=parent, **kw)
+
+    def newinstance(self):
+        return self.obj()
+
+    def collect(self) -> Iterable[nodes.Item | nodes.Collector]:
+        if not safe_getattr(self.obj, "__test__", True):
+            return []
+        if hasinit(self.obj):
+            assert self.parent is not None
+            self.warn(
+                PytestCollectionWarning(
+                    f"cannot collect test class {self.obj.__name__!r} because it has a "
+                    f"__init__ constructor (from: {self.parent.nodeid})"
+                )
+            )
+            return []
+        elif hasnew(self.obj):
+            assert self.parent is not None
+            self.warn(
+                PytestCollectionWarning(
+                    f"cannot collect test class {self.obj.__name__!r} because it has a "
+                    f"__new__ constructor (from: {self.parent.nodeid})"
+                )
+            )
+            return []
+
+        self._register_setup_class_fixture()
+        self._register_setup_method_fixture()
+
+        self.session._fixturemanager.parsefactories(self.newinstance(), self.nodeid)
+
+        return super().collect()
+
+    def _register_setup_class_fixture(self) -> None:
+        """Register an autouse, class scoped fixture into the collected class object
+        that invokes setup_class/teardown_class if either or both are available.
+
+        Using a fixture to invoke this methods ensures we play nicely and unsurprisingly with
+        other fixtures (#517).
+        """
+        setup_class = _get_first_non_fixture_func(self.obj, ("setup_class",))
+        teardown_class = _get_first_non_fixture_func(self.obj, ("teardown_class",))
+        if setup_class is None and teardown_class is None:
+            return
+
+        def xunit_setup_class_fixture(request) -> Generator[None]:
+            cls = request.cls
+            if setup_class is not None:
+                func = getimfunc(setup_class)
+                _call_with_optional_argument(func, cls)
+            yield
+            if teardown_class is not None:
+                func = getimfunc(teardown_class)
+                _call_with_optional_argument(func, cls)
+
+        self.session._fixturemanager._register_fixture(
+            # Use a unique name to speed up lookup.
+            name=f"_xunit_setup_class_fixture_{self.obj.__qualname__}",
+            func=xunit_setup_class_fixture,
+            nodeid=self.nodeid,
+            scope="class",
+            autouse=True,
+        )
+
+    def _register_setup_method_fixture(self) -> None:
+        """Register an autouse, function scoped fixture into the collected class object
+        that invokes setup_method/teardown_method if either or both are available.
+
+        Using a fixture to invoke these methods ensures we play nicely and unsurprisingly with
+        other fixtures (#517).
+        """
+        setup_name = "setup_method"
+        setup_method = _get_first_non_fixture_func(self.obj, (setup_name,))
+        teardown_name = "teardown_method"
+        teardown_method = _get_first_non_fixture_func(self.obj, (teardown_name,))
+        if setup_method is None and teardown_method is None:
+            return
+
+        def xunit_setup_method_fixture(request) -> Generator[None]:
+            instance = request.instance
+            method = request.function
+            if setup_method is not None:
+                func = getattr(instance, setup_name)
+                _call_with_optional_argument(func, method)
+            yield
+            if teardown_method is not None:
+                func = getattr(instance, teardown_name)
+                _call_with_optional_argument(func, method)
+
+        self.session._fixturemanager._register_fixture(
+            # Use a unique name to speed up lookup.
+            name=f"_xunit_setup_method_fixture_{self.obj.__qualname__}",
+            func=xunit_setup_method_fixture,
+            nodeid=self.nodeid,
+            scope="function",
+            autouse=True,
+        )
+
+
+def hasinit(obj: object) -> bool:
+    init: object = getattr(obj, "__init__", None)
+    if init:
+        return init != object.__init__
+    return False
+
+
+def hasnew(obj: object) -> bool:
+    new: object = getattr(obj, "__new__", None)
+    if new:
+        return new != object.__new__
+    return False
+
+
+@final
+@dataclasses.dataclass(frozen=True)
+class IdMaker:
+    """Make IDs for a parametrization."""
+
+    __slots__ = (
+        "argnames",
+        "parametersets",
+        "idfn",
+        "ids",
+        "config",
+        "nodeid",
+        "func_name",
+    )
+
+    # The argnames of the parametrization.
+    argnames: Sequence[str]
+    # The ParameterSets of the parametrization.
+    parametersets: Sequence[ParameterSet]
+    # Optionally, a user-provided callable to make IDs for parameters in a
+    # ParameterSet.
+    idfn: Callable[[Any], object | None] | None
+    # Optionally, explicit IDs for ParameterSets by index.
+    ids: Sequence[object | None] | None
+    # Optionally, the pytest config.
+    # Used for controlling ASCII escaping, and for calling the
+    # :hook:`pytest_make_parametrize_id` hook.
+    config: Config | None
+    # Optionally, the ID of the node being parametrized.
+    # Used only for clearer error messages.
+    nodeid: str | None
+    # Optionally, the ID of the function being parametrized.
+    # Used only for clearer error messages.
+    func_name: str | None
+
+    def make_unique_parameterset_ids(self) -> list[str]:
+        """Make a unique identifier for each ParameterSet, that may be used to
+        identify the parametrization in a node ID.
+
+        Format is <prm_1_token>-...-<prm_n_token>[counter], where prm_x_token is
+        - user-provided id, if given
+        - else an id derived from the value, applicable for certain types
+        - else <argname><parameterset index>
+        The counter suffix is appended only in case a string wouldn't be unique
+        otherwise.
+        """
+        resolved_ids = list(self._resolve_ids())
+        # All IDs must be unique!
+        if len(resolved_ids) != len(set(resolved_ids)):
+            # Record the number of occurrences of each ID.
+            id_counts = Counter(resolved_ids)
+            # Map the ID to its next suffix.
+            id_suffixes: dict[str, int] = defaultdict(int)
+            # Suffix non-unique IDs to make them unique.
+            for index, id in enumerate(resolved_ids):
+                if id_counts[id] > 1:
+                    suffix = ""
+                    if id and id[-1].isdigit():
+                        suffix = "_"
+                    new_id = f"{id}{suffix}{id_suffixes[id]}"
+                    while new_id in set(resolved_ids):
+                        id_suffixes[id] += 1
+                        new_id = f"{id}{suffix}{id_suffixes[id]}"
+                    resolved_ids[index] = new_id
+                    id_suffixes[id] += 1
+        assert len(resolved_ids) == len(
+            set(resolved_ids)
+        ), f"Internal error: {resolved_ids=}"
+        return resolved_ids
+
+    def _resolve_ids(self) -> Iterable[str]:
+        """Resolve IDs for all ParameterSets (may contain duplicates)."""
+        for idx, parameterset in enumerate(self.parametersets):
+            if parameterset.id is not None:
+                # ID provided directly - pytest.param(..., id="...")
+                yield parameterset.id
+            elif self.ids and idx < len(self.ids) and self.ids[idx] is not None:
+                # ID provided in the IDs list - parametrize(..., ids=[...]).
+                yield self._idval_from_value_required(self.ids[idx], idx)
+            else:
+                # ID not provided - generate it.
+                yield "-".join(
+                    self._idval(val, argname, idx)
+                    for val, argname in zip(parameterset.values, self.argnames)
+                )
+
+    def _idval(self, val: object, argname: str, idx: int) -> str:
+        """Make an ID for a parameter in a ParameterSet."""
+        idval = self._idval_from_function(val, argname, idx)
+        if idval is not None:
+            return idval
+        idval = self._idval_from_hook(val, argname)
+        if idval is not None:
+            return idval
+        idval = self._idval_from_value(val)
+        if idval is not None:
+            return idval
+        return self._idval_from_argname(argname, idx)
+
+    def _idval_from_function(self, val: object, argname: str, idx: int) -> str | None:
+        """Try to make an ID for a parameter in a ParameterSet using the
+        user-provided id callable, if given."""
+        if self.idfn is None:
+            return None
+        try:
+            id = self.idfn(val)
+        except Exception as e:
+            prefix = f"{self.nodeid}: " if self.nodeid is not None else ""
+            msg = "error raised while trying to determine id of parameter '{}' at position {}"
+            msg = prefix + msg.format(argname, idx)
+            raise ValueError(msg) from e
+        if id is None:
+            return None
+        return self._idval_from_value(id)
+
+    def _idval_from_hook(self, val: object, argname: str) -> str | None:
+        """Try to make an ID for a parameter in a ParameterSet by calling the
+        :hook:`pytest_make_parametrize_id` hook."""
+        if self.config:
+            id: str | None = self.config.hook.pytest_make_parametrize_id(
+                config=self.config, val=val, argname=argname
+            )
+            return id
+        return None
+
+    def _idval_from_value(self, val: object) -> str | None:
+        """Try to make an ID for a parameter in a ParameterSet from its value,
+        if the value type is supported."""
+        if isinstance(val, (str, bytes)):
+            return _ascii_escaped_by_config(val, self.config)
+        elif val is None or isinstance(val, (float, int, bool, complex)):
+            return str(val)
+        elif isinstance(val, Pattern):
+            return ascii_escaped(val.pattern)
+        elif val is NOTSET:
+            # Fallback to default. Note that NOTSET is an enum.Enum.
+            pass
+        elif isinstance(val, enum.Enum):
+            return str(val)
+        elif isinstance(getattr(val, "__name__", None), str):
+            # Name of a class, function, module, etc.
+            name: str = getattr(val, "__name__")
+            return name
+        return None
+
+    def _idval_from_value_required(self, val: object, idx: int) -> str:
+        """Like _idval_from_value(), but fails if the type is not supported."""
+        id = self._idval_from_value(val)
+        if id is not None:
+            return id
+
+        # Fail.
+        if self.func_name is not None:
+            prefix = f"In {self.func_name}: "
+        elif self.nodeid is not None:
+            prefix = f"In {self.nodeid}: "
+        else:
+            prefix = ""
+        msg = (
+            f"{prefix}ids contains unsupported value {saferepr(val)} (type: {type(val)!r}) at index {idx}. "
+            "Supported types are: str, bytes, int, float, complex, bool, enum, regex or anything with a __name__."
+        )
+        fail(msg, pytrace=False)
+
+    @staticmethod
+    def _idval_from_argname(argname: str, idx: int) -> str:
+        """Make an ID for a parameter in a ParameterSet from the argument name
+        and the index of the ParameterSet."""
+        return str(argname) + str(idx)
+
+
+@final
+@dataclasses.dataclass(frozen=True)
+class CallSpec2:
+    """A planned parameterized invocation of a test function.
+
+    Calculated during collection for a given test function's Metafunc.
+    Once collection is over, each callspec is turned into a single Item
+    and stored in item.callspec.
+    """
+
+    # arg name -> arg value which will be passed to a fixture or pseudo-fixture
+    # of the same name. (indirect or direct parametrization respectively)
+    params: dict[str, object] = dataclasses.field(default_factory=dict)
+    # arg name -> arg index.
+    indices: dict[str, int] = dataclasses.field(default_factory=dict)
+    # Used for sorting parametrized resources.
+    _arg2scope: Mapping[str, Scope] = dataclasses.field(default_factory=dict)
+    # Parts which will be added to the item's name in `[..]` separated by "-".
+    _idlist: Sequence[str] = dataclasses.field(default_factory=tuple)
+    # Marks which will be applied to the item.
+    marks: list[Mark] = dataclasses.field(default_factory=list)
+
+    def setmulti(
+        self,
+        *,
+        argnames: Iterable[str],
+        valset: Iterable[object],
+        id: str,
+        marks: Iterable[Mark | MarkDecorator],
+        scope: Scope,
+        param_index: int,
+    ) -> CallSpec2:
+        params = self.params.copy()
+        indices = self.indices.copy()
+        arg2scope = dict(self._arg2scope)
+        for arg, val in zip(argnames, valset):
+            if arg in params:
+                raise ValueError(f"duplicate parametrization of {arg!r}")
+            params[arg] = val
+            indices[arg] = param_index
+            arg2scope[arg] = scope
+        return CallSpec2(
+            params=params,
+            indices=indices,
+            _arg2scope=arg2scope,
+            _idlist=[*self._idlist, id],
+            marks=[*self.marks, *normalize_mark_list(marks)],
+        )
+
+    def getparam(self, name: str) -> object:
+        try:
+            return self.params[name]
+        except KeyError as e:
+            raise ValueError(name) from e
+
+    @property
+    def id(self) -> str:
+        return "-".join(self._idlist)
+
+
+def get_direct_param_fixture_func(request: FixtureRequest) -> Any:
+    return request.param
+
+
+# Used for storing pseudo fixturedefs for direct parametrization.
+name2pseudofixturedef_key = StashKey[Dict[str, FixtureDef[Any]]]()
+
+
+@final
+class Metafunc:
+    """Objects passed to the :hook:`pytest_generate_tests` hook.
+
+    They help to inspect a test function and to generate tests according to
+    test configuration or values specified in the class or module where a
+    test function is defined.
+    """
+
+    def __init__(
+        self,
+        definition: FunctionDefinition,
+        fixtureinfo: fixtures.FuncFixtureInfo,
+        config: Config,
+        cls=None,
+        module=None,
+        *,
+        _ispytest: bool = False,
+    ) -> None:
+        check_ispytest(_ispytest)
+
+        #: Access to the underlying :class:`_pytest.python.FunctionDefinition`.
+        self.definition = definition
+
+        #: Access to the :class:`pytest.Config` object for the test session.
+        self.config = config
+
+        #: The module object where the test function is defined in.
+        self.module = module
+
+        #: Underlying Python test function.
+        self.function = definition.obj
+
+        #: Set of fixture names required by the test function.
+        self.fixturenames = fixtureinfo.names_closure
+
+        #: Class object where the test function is defined in or ``None``.
+        self.cls = cls
+
+        self._arg2fixturedefs = fixtureinfo.name2fixturedefs
+
+        # Result of parametrize().
+        self._calls: list[CallSpec2] = []
+
+    def parametrize(
+        self,
+        argnames: str | Sequence[str],
+        argvalues: Iterable[ParameterSet | Sequence[object] | object],
+        indirect: bool | Sequence[str] = False,
+        ids: Iterable[object | None] | Callable[[Any], object | None] | None = None,
+        scope: _ScopeName | None = None,
+        *,
+        _param_mark: Mark | None = None,
+    ) -> None:
+        """Add new invocations to the underlying test function using the list
+        of argvalues for the given argnames. Parametrization is performed
+        during the collection phase. If you need to setup expensive resources
+        see about setting indirect to do it rather than at test setup time.
+
+        Can be called multiple times per test function (but only on different
+        argument names), in which case each call parametrizes all previous
+        parametrizations, e.g.
+
+        ::
+
+            unparametrized:         t
+            parametrize ["x", "y"]: t[x], t[y]
+            parametrize [1, 2]:     t[x-1], t[x-2], t[y-1], t[y-2]
+
+        :param argnames:
+            A comma-separated string denoting one or more argument names, or
+            a list/tuple of argument strings.
+
+        :param argvalues:
+            The list of argvalues determines how often a test is invoked with
+            different argument values.
+
+            If only one argname was specified argvalues is a list of values.
+            If N argnames were specified, argvalues must be a list of
+            N-tuples, where each tuple-element specifies a value for its
+            respective argname.
+        :type argvalues: Iterable[_pytest.mark.structures.ParameterSet | Sequence[object] | object]
+        :param indirect:
+            A list of arguments' names (subset of argnames) or a boolean.
+            If True the list contains all names from the argnames. Each
+            argvalue corresponding to an argname in this list will
+            be passed as request.param to its respective argname fixture
+            function so that it can perform more expensive setups during the
+            setup phase of a test rather than at collection time.
+
+        :param ids:
+            Sequence of (or generator for) ids for ``argvalues``,
+            or a callable to return part of the id for each argvalue.
+
+            With sequences (and generators like ``itertools.count()``) the
+            returned ids should be of type ``string``, ``int``, ``float``,
+            ``bool``, or ``None``.
+            They are mapped to the corresponding index in ``argvalues``.
+            ``None`` means to use the auto-generated id.
+
+            If it is a callable it will be called for each entry in
+            ``argvalues``, and the return value is used as part of the
+            auto-generated id for the whole set (where parts are joined with
+            dashes ("-")).
+            This is useful to provide more specific ids for certain items, e.g.
+            dates.  Returning ``None`` will use an auto-generated id.
+
+            If no ids are provided they will be generated automatically from
+            the argvalues.
+
+        :param scope:
+            If specified it denotes the scope of the parameters.
+            The scope is used for grouping tests by parameter instances.
+            It will also override any fixture-function defined scope, allowing
+            to set a dynamic scope using test context or configuration.
+        """
+        argnames, parametersets = ParameterSet._for_parametrize(
+            argnames,
+            argvalues,
+            self.function,
+            self.config,
+            nodeid=self.definition.nodeid,
+        )
+        del argvalues
+
+        if "request" in argnames:
+            fail(
+                "'request' is a reserved name and cannot be used in @pytest.mark.parametrize",
+                pytrace=False,
+            )
+
+        if scope is not None:
+            scope_ = Scope.from_user(
+                scope, descr=f"parametrize() call in {self.function.__name__}"
+            )
+        else:
+            scope_ = _find_parametrized_scope(argnames, self._arg2fixturedefs, indirect)
+
+        self._validate_if_using_arg_names(argnames, indirect)
+
+        # Use any already (possibly) generated ids with parametrize Marks.
+        if _param_mark and _param_mark._param_ids_from:
+            generated_ids = _param_mark._param_ids_from._param_ids_generated
+            if generated_ids is not None:
+                ids = generated_ids
+
+        ids = self._resolve_parameter_set_ids(
+            argnames, ids, parametersets, nodeid=self.definition.nodeid
+        )
+
+        # Store used (possibly generated) ids with parametrize Marks.
+        if _param_mark and _param_mark._param_ids_from and generated_ids is None:
+            object.__setattr__(_param_mark._param_ids_from, "_param_ids_generated", ids)
+
+        # Add funcargs as fixturedefs to fixtureinfo.arg2fixturedefs by registering
+        # artificial "pseudo" FixtureDef's so that later at test execution time we can
+        # rely on a proper FixtureDef to exist for fixture setup.
+        node = None
+        # If we have a scope that is higher than function, we need
+        # to make sure we only ever create an according fixturedef on
+        # a per-scope basis. We thus store and cache the fixturedef on the
+        # node related to the scope.
+        if scope_ is not Scope.Function:
+            collector = self.definition.parent
+            assert collector is not None
+            node = get_scope_node(collector, scope_)
+            if node is None:
+                # If used class scope and there is no class, use module-level
+                # collector (for now).
+                if scope_ is Scope.Class:
+                    assert isinstance(collector, Module)
+                    node = collector
+                # If used package scope and there is no package, use session
+                # (for now).
+                elif scope_ is Scope.Package:
+                    node = collector.session
+                else:
+                    assert False, f"Unhandled missing scope: {scope}"
+        if node is None:
+            name2pseudofixturedef = None
+        else:
+            default: dict[str, FixtureDef[Any]] = {}
+            name2pseudofixturedef = node.stash.setdefault(
+                name2pseudofixturedef_key, default
+            )
+        arg_directness = self._resolve_args_directness(argnames, indirect)
+        for argname in argnames:
+            if arg_directness[argname] == "indirect":
+                continue
+            if name2pseudofixturedef is not None and argname in name2pseudofixturedef:
+                fixturedef = name2pseudofixturedef[argname]
+            else:
+                fixturedef = FixtureDef(
+                    config=self.config,
+                    baseid="",
+                    argname=argname,
+                    func=get_direct_param_fixture_func,
+                    scope=scope_,
+                    params=None,
+                    ids=None,
+                    _ispytest=True,
+                )
+                if name2pseudofixturedef is not None:
+                    name2pseudofixturedef[argname] = fixturedef
+            self._arg2fixturedefs[argname] = [fixturedef]
+
+        # Create the new calls: if we are parametrize() multiple times (by applying the decorator
+        # more than once) then we accumulate those calls generating the cartesian product
+        # of all calls.
+        newcalls = []
+        for callspec in self._calls or [CallSpec2()]:
+            for param_index, (param_id, param_set) in enumerate(
+                zip(ids, parametersets)
+            ):
+                newcallspec = callspec.setmulti(
+                    argnames=argnames,
+                    valset=param_set.values,
+                    id=param_id,
+                    marks=param_set.marks,
+                    scope=scope_,
+                    param_index=param_index,
+                )
+                newcalls.append(newcallspec)
+        self._calls = newcalls
+
+    def _resolve_parameter_set_ids(
+        self,
+        argnames: Sequence[str],
+        ids: Iterable[object | None] | Callable[[Any], object | None] | None,
+        parametersets: Sequence[ParameterSet],
+        nodeid: str,
+    ) -> list[str]:
+        """Resolve the actual ids for the given parameter sets.
+
+        :param argnames:
+            Argument names passed to ``parametrize()``.
+        :param ids:
+            The `ids` parameter of the ``parametrize()`` call (see docs).
+        :param parametersets:
+            The parameter sets, each containing a set of values corresponding
+            to ``argnames``.
+        :param nodeid str:
+            The nodeid of the definition item that generated this
+            parametrization.
+        :returns:
+            List with ids for each parameter set given.
+        """
+        if ids is None:
+            idfn = None
+            ids_ = None
+        elif callable(ids):
+            idfn = ids
+            ids_ = None
+        else:
+            idfn = None
+            ids_ = self._validate_ids(ids, parametersets, self.function.__name__)
+        id_maker = IdMaker(
+            argnames,
+            parametersets,
+            idfn,
+            ids_,
+            self.config,
+            nodeid=nodeid,
+            func_name=self.function.__name__,
+        )
+        return id_maker.make_unique_parameterset_ids()
+
+    def _validate_ids(
+        self,
+        ids: Iterable[object | None],
+        parametersets: Sequence[ParameterSet],
+        func_name: str,
+    ) -> list[object | None]:
+        try:
+            num_ids = len(ids)  # type: ignore[arg-type]
+        except TypeError:
+            try:
+                iter(ids)
+            except TypeError as e:
+                raise TypeError("ids must be a callable or an iterable") from e
+            num_ids = len(parametersets)
+
+        # num_ids == 0 is a special case: https://github.com/pytest-dev/pytest/issues/1849
+        if num_ids != len(parametersets) and num_ids != 0:
+            msg = "In {}: {} parameter sets specified, with different number of ids: {}"
+            fail(msg.format(func_name, len(parametersets), num_ids), pytrace=False)
+
+        return list(itertools.islice(ids, num_ids))
+
+    def _resolve_args_directness(
+        self,
+        argnames: Sequence[str],
+        indirect: bool | Sequence[str],
+    ) -> dict[str, Literal["indirect", "direct"]]:
+        """Resolve if each parametrized argument must be considered an indirect
+        parameter to a fixture of the same name, or a direct parameter to the
+        parametrized function, based on the ``indirect`` parameter of the
+        parametrized() call.
+
+        :param argnames:
+            List of argument names passed to ``parametrize()``.
+        :param indirect:
+            Same as the ``indirect`` parameter of ``parametrize()``.
+        :returns
+            A dict mapping each arg name to either "indirect" or "direct".
+        """
+        arg_directness: dict[str, Literal["indirect", "direct"]]
+        if isinstance(indirect, bool):
+            arg_directness = dict.fromkeys(
+                argnames, "indirect" if indirect else "direct"
+            )
+        elif isinstance(indirect, Sequence):
+            arg_directness = dict.fromkeys(argnames, "direct")
+            for arg in indirect:
+                if arg not in argnames:
+                    fail(
+                        f"In {self.function.__name__}: indirect fixture '{arg}' doesn't exist",
+                        pytrace=False,
+                    )
+                arg_directness[arg] = "indirect"
+        else:
+            fail(
+                f"In {self.function.__name__}: expected Sequence or boolean"
+                f" for indirect, got {type(indirect).__name__}",
+                pytrace=False,
+            )
+        return arg_directness
+
+    def _validate_if_using_arg_names(
+        self,
+        argnames: Sequence[str],
+        indirect: bool | Sequence[str],
+    ) -> None:
+        """Check if all argnames are being used, by default values, or directly/indirectly.
+
+        :param List[str] argnames: List of argument names passed to ``parametrize()``.
+        :param indirect: Same as the ``indirect`` parameter of ``parametrize()``.
+        :raises ValueError: If validation fails.
+        """
+        default_arg_names = set(get_default_arg_names(self.function))
+        func_name = self.function.__name__
+        for arg in argnames:
+            if arg not in self.fixturenames:
+                if arg in default_arg_names:
+                    fail(
+                        f"In {func_name}: function already takes an argument '{arg}' with a default value",
+                        pytrace=False,
+                    )
+                else:
+                    if isinstance(indirect, Sequence):
+                        name = "fixture" if arg in indirect else "argument"
+                    else:
+                        name = "fixture" if indirect else "argument"
+                    fail(
+                        f"In {func_name}: function uses no {name} '{arg}'",
+                        pytrace=False,
+                    )
+
+
+def _find_parametrized_scope(
+    argnames: Sequence[str],
+    arg2fixturedefs: Mapping[str, Sequence[fixtures.FixtureDef[object]]],
+    indirect: bool | Sequence[str],
+) -> Scope:
+    """Find the most appropriate scope for a parametrized call based on its arguments.
+
+    When there's at least one direct argument, always use "function" scope.
+
+    When a test function is parametrized and all its arguments are indirect
+    (e.g. fixtures), return the most narrow scope based on the fixtures used.
+
+    Related to issue #1832, based on code posted by @Kingdread.
+    """
+    if isinstance(indirect, Sequence):
+        all_arguments_are_fixtures = len(indirect) == len(argnames)
+    else:
+        all_arguments_are_fixtures = bool(indirect)
+
+    if all_arguments_are_fixtures:
+        fixturedefs = arg2fixturedefs or {}
+        used_scopes = [
+            fixturedef[-1]._scope
+            for name, fixturedef in fixturedefs.items()
+            if name in argnames
+        ]
+        # Takes the most narrow scope from used fixtures.
+        return min(used_scopes, default=Scope.Function)
+
+    return Scope.Function
+
+
+def _ascii_escaped_by_config(val: str | bytes, config: Config | None) -> str:
+    if config is None:
+        escape_option = False
+    else:
+        escape_option = config.getini(
+            "disable_test_id_escaping_and_forfeit_all_rights_to_community_support"
+        )
+    # TODO: If escaping is turned off and the user passes bytes,
+    #       will return a bytes. For now we ignore this but the
+    #       code *probably* doesn't handle this case.
+    return val if escape_option else ascii_escaped(val)  # type: ignore
+
+
+class Function(PyobjMixin, nodes.Item):
+    """Item responsible for setting up and executing a Python test function.
+
+    :param name:
+        The full function name, including any decorations like those
+        added by parametrization (``my_func[my_param]``).
+    :param parent:
+        The parent Node.
+    :param config:
+        The pytest Config object.
+    :param callspec:
+        If given, this function has been parametrized and the callspec contains
+        meta information about the parametrization.
+    :param callobj:
+        If given, the object which will be called when the Function is invoked,
+        otherwise the callobj will be obtained from ``parent`` using ``originalname``.
+    :param keywords:
+        Keywords bound to the function object for "-k" matching.
+    :param session:
+        The pytest Session object.
+    :param fixtureinfo:
+        Fixture information already resolved at this fixture node..
+    :param originalname:
+        The attribute name to use for accessing the underlying function object.
+        Defaults to ``name``. Set this if name is different from the original name,
+        for example when it contains decorations like those added by parametrization
+        (``my_func[my_param]``).
+    """
+
+    # Disable since functions handle it themselves.
+    _ALLOW_MARKERS = False
+
+    def __init__(
+        self,
+        name: str,
+        parent,
+        config: Config | None = None,
+        callspec: CallSpec2 | None = None,
+        callobj=NOTSET,
+        keywords: Mapping[str, Any] | None = None,
+        session: Session | None = None,
+        fixtureinfo: FuncFixtureInfo | None = None,
+        originalname: str | None = None,
+    ) -> None:
+        super().__init__(name, parent, config=config, session=session)
+
+        if callobj is not NOTSET:
+            self._obj = callobj
+            self._instance = getattr(callobj, "__self__", None)
+
+        #: Original function name, without any decorations (for example
+        #: parametrization adds a ``"[...]"`` suffix to function names), used to access
+        #: the underlying function object from ``parent`` (in case ``callobj`` is not given
+        #: explicitly).
+        #:
+        #: .. versionadded:: 3.0
+        self.originalname = originalname or name
+
+        # Note: when FunctionDefinition is introduced, we should change ``originalname``
+        # to a readonly property that returns FunctionDefinition.name.
+
+        self.own_markers.extend(get_unpacked_marks(self.obj))
+        if callspec:
+            self.callspec = callspec
+            self.own_markers.extend(callspec.marks)
+
+        # todo: this is a hell of a hack
+        # https://github.com/pytest-dev/pytest/issues/4569
+        # Note: the order of the updates is important here; indicates what
+        # takes priority (ctor argument over function attributes over markers).
+        # Take own_markers only; NodeKeywords handles parent traversal on its own.
+        self.keywords.update((mark.name, mark) for mark in self.own_markers)
+        self.keywords.update(self.obj.__dict__)
+        if keywords:
+            self.keywords.update(keywords)
+
+        if fixtureinfo is None:
+            fm = self.session._fixturemanager
+            fixtureinfo = fm.getfixtureinfo(self, self.obj, self.cls)
+        self._fixtureinfo: FuncFixtureInfo = fixtureinfo
+        self.fixturenames = fixtureinfo.names_closure
+        self._initrequest()
+
+    # todo: determine sound type limitations
+    @classmethod
+    def from_parent(cls, parent, **kw) -> Self:
+        """The public constructor."""
+        return super().from_parent(parent=parent, **kw)
+
+    def _initrequest(self) -> None:
+        self.funcargs: dict[str, object] = {}
+        self._request = fixtures.TopRequest(self, _ispytest=True)
+
+    @property
+    def function(self):
+        """Underlying python 'function' object."""
+        return getimfunc(self.obj)
+
+    @property
+    def instance(self):
+        try:
+            return self._instance
+        except AttributeError:
+            if isinstance(self.parent, Class):
+                # Each Function gets a fresh class instance.
+                self._instance = self._getinstance()
+            else:
+                self._instance = None
+        return self._instance
+
+    def _getinstance(self):
+        if isinstance(self.parent, Class):
+            # Each Function gets a fresh class instance.
+            return self.parent.newinstance()
+        else:
+            return None
+
+    def _getobj(self):
+        instance = self.instance
+        if instance is not None:
+            parent_obj = instance
+        else:
+            assert self.parent is not None
+            parent_obj = self.parent.obj  # type: ignore[attr-defined]
+        return getattr(parent_obj, self.originalname)
+
+    @property
+    def _pyfuncitem(self):
+        """(compatonly) for code expecting pytest-2.2 style request objects."""
+        return self
+
+    def runtest(self) -> None:
+        """Execute the underlying test function."""
+        self.ihook.pytest_pyfunc_call(pyfuncitem=self)
+
+    def setup(self) -> None:
+        self._request._fillfixtures()
+
+    def _traceback_filter(self, excinfo: ExceptionInfo[BaseException]) -> Traceback:
+        if hasattr(self, "_obj") and not self.config.getoption("fulltrace", False):
+            code = _pytest._code.Code.from_function(get_real_func(self.obj))
+            path, firstlineno = code.path, code.firstlineno
+            traceback = excinfo.traceback
+            ntraceback = traceback.cut(path=path, firstlineno=firstlineno)
+            if ntraceback == traceback:
+                ntraceback = ntraceback.cut(path=path)
+                if ntraceback == traceback:
+                    ntraceback = ntraceback.filter(filter_traceback)
+                    if not ntraceback:
+                        ntraceback = traceback
+            ntraceback = ntraceback.filter(excinfo)
+
+            # issue364: mark all but first and last frames to
+            # only show a single-line message for each frame.
+            if self.config.getoption("tbstyle", "auto") == "auto":
+                if len(ntraceback) > 2:
+                    ntraceback = Traceback(
+                        (
+                            ntraceback[0],
+                            *(t.with_repr_style("short") for t in ntraceback[1:-1]),
+                            ntraceback[-1],
+                        )
+                    )
+
+            return ntraceback
+        return excinfo.traceback
+
+    # TODO: Type ignored -- breaks Liskov Substitution.
+    def repr_failure(  # type: ignore[override]
+        self,
+        excinfo: ExceptionInfo[BaseException],
+    ) -> str | TerminalRepr:
+        style = self.config.getoption("tbstyle", "auto")
+        if style == "auto":
+            style = "long"
+        return self._repr_failure_py(excinfo, style=style)
+
+
+class FunctionDefinition(Function):
+    """This class is a stop gap solution until we evolve to have actual function
+    definition nodes and manage to get rid of ``metafunc``."""
+
+    def runtest(self) -> None:
+        raise RuntimeError("function definitions are not supposed to be run as tests")
+
+    setup = runtest

.venv/lib/python3.11/site-packages/_pytest/python_api.py

@@ -0,0 +1,1028 @@
+# mypy: allow-untyped-defs
+from __future__ import annotations
+
+from collections.abc import Collection
+from collections.abc import Sized
+from decimal import Decimal
+import math
+from numbers import Complex
+import pprint
+import re
+from types import TracebackType
+from typing import Any
+from typing import Callable
+from typing import cast
+from typing import ContextManager
+from typing import final
+from typing import Mapping
+from typing import overload
+from typing import Pattern
+from typing import Sequence
+from typing import Tuple
+from typing import Type
+from typing import TYPE_CHECKING
+from typing import TypeVar
+
+import _pytest._code
+from _pytest.outcomes import fail
+
+
+if TYPE_CHECKING:
+    from numpy import ndarray
+
+
+def _compare_approx(
+    full_object: object,
+    message_data: Sequence[tuple[str, str, str]],
+    number_of_elements: int,
+    different_ids: Sequence[object],
+    max_abs_diff: float,
+    max_rel_diff: float,
+) -> list[str]:
+    message_list = list(message_data)
+    message_list.insert(0, ("Index", "Obtained", "Expected"))
+    max_sizes = [0, 0, 0]
+    for index, obtained, expected in message_list:
+        max_sizes[0] = max(max_sizes[0], len(index))
+        max_sizes[1] = max(max_sizes[1], len(obtained))
+        max_sizes[2] = max(max_sizes[2], len(expected))
+    explanation = [
+        f"comparison failed. Mismatched elements: {len(different_ids)} / {number_of_elements}:",
+        f"Max absolute difference: {max_abs_diff}",
+        f"Max relative difference: {max_rel_diff}",
+    ] + [
+        f"{indexes:<{max_sizes[0]}} | {obtained:<{max_sizes[1]}} | {expected:<{max_sizes[2]}}"
+        for indexes, obtained, expected in message_list
+    ]
+    return explanation
+
+
+# builtin pytest.approx helper
+
+
+class ApproxBase:
+    """Provide shared utilities for making approximate comparisons between
+    numbers or sequences of numbers."""
+
+    # Tell numpy to use our `__eq__` operator instead of its.
+    __array_ufunc__ = None
+    __array_priority__ = 100
+
+    def __init__(self, expected, rel=None, abs=None, nan_ok: bool = False) -> None:
+        __tracebackhide__ = True
+        self.expected = expected
+        self.abs = abs
+        self.rel = rel
+        self.nan_ok = nan_ok
+        self._check_type()
+
+    def __repr__(self) -> str:
+        raise NotImplementedError
+
+    def _repr_compare(self, other_side: Any) -> list[str]:
+        return [
+            "comparison failed",
+            f"Obtained: {other_side}",
+            f"Expected: {self}",
+        ]
+
+    def __eq__(self, actual) -> bool:
+        return all(
+            a == self._approx_scalar(x) for a, x in self._yield_comparisons(actual)
+        )
+
+    def __bool__(self):
+        __tracebackhide__ = True
+        raise AssertionError(
+            "approx() is not supported in a boolean context.\nDid you mean: `assert a == approx(b)`?"
+        )
+
+    # Ignore type because of https://github.com/python/mypy/issues/4266.
+    __hash__ = None  # type: ignore
+
+    def __ne__(self, actual) -> bool:
+        return not (actual == self)
+
+    def _approx_scalar(self, x) -> ApproxScalar:
+        if isinstance(x, Decimal):
+            return ApproxDecimal(x, rel=self.rel, abs=self.abs, nan_ok=self.nan_ok)
+        return ApproxScalar(x, rel=self.rel, abs=self.abs, nan_ok=self.nan_ok)
+
+    def _yield_comparisons(self, actual):
+        """Yield all the pairs of numbers to be compared.
+
+        This is used to implement the `__eq__` method.
+        """
+        raise NotImplementedError
+
+    def _check_type(self) -> None:
+        """Raise a TypeError if the expected value is not a valid type."""
+        # This is only a concern if the expected value is a sequence.  In every
+        # other case, the approx() function ensures that the expected value has
+        # a numeric type.  For this reason, the default is to do nothing.  The
+        # classes that deal with sequences should reimplement this method to
+        # raise if there are any non-numeric elements in the sequence.
+
+
+def _recursive_sequence_map(f, x):
+    """Recursively map a function over a sequence of arbitrary depth"""
+    if isinstance(x, (list, tuple)):
+        seq_type = type(x)
+        return seq_type(_recursive_sequence_map(f, xi) for xi in x)
+    elif _is_sequence_like(x):
+        return [_recursive_sequence_map(f, xi) for xi in x]
+    else:
+        return f(x)
+
+
+class ApproxNumpy(ApproxBase):
+    """Perform approximate comparisons where the expected value is numpy array."""
+
+    def __repr__(self) -> str:
+        list_scalars = _recursive_sequence_map(
+            self._approx_scalar, self.expected.tolist()
+        )
+        return f"approx({list_scalars!r})"
+
+    def _repr_compare(self, other_side: ndarray | list[Any]) -> list[str]:
+        import itertools
+        import math
+
+        def get_value_from_nested_list(
+            nested_list: list[Any], nd_index: tuple[Any, ...]
+        ) -> Any:
+            """
+            Helper function to get the value out of a nested list, given an n-dimensional index.
+            This mimics numpy's indexing, but for raw nested python lists.
+            """
+            value: Any = nested_list
+            for i in nd_index:
+                value = value[i]
+            return value
+
+        np_array_shape = self.expected.shape
+        approx_side_as_seq = _recursive_sequence_map(
+            self._approx_scalar, self.expected.tolist()
+        )
+
+        # convert other_side to numpy array to ensure shape attribute is available
+        other_side_as_array = _as_numpy_array(other_side)
+        assert other_side_as_array is not None
+
+        if np_array_shape != other_side_as_array.shape:
+            return [
+                "Impossible to compare arrays with different shapes.",
+                f"Shapes: {np_array_shape} and {other_side_as_array.shape}",
+            ]
+
+        number_of_elements = self.expected.size
+        max_abs_diff = -math.inf
+        max_rel_diff = -math.inf
+        different_ids = []
+        for index in itertools.product(*(range(i) for i in np_array_shape)):
+            approx_value = get_value_from_nested_list(approx_side_as_seq, index)
+            other_value = get_value_from_nested_list(other_side_as_array, index)
+            if approx_value != other_value:
+                abs_diff = abs(approx_value.expected - other_value)
+                max_abs_diff = max(max_abs_diff, abs_diff)
+                if other_value == 0.0:
+                    max_rel_diff = math.inf
+                else:
+                    max_rel_diff = max(max_rel_diff, abs_diff / abs(other_value))
+                different_ids.append(index)
+
+        message_data = [
+            (
+                str(index),
+                str(get_value_from_nested_list(other_side_as_array, index)),
+                str(get_value_from_nested_list(approx_side_as_seq, index)),
+            )
+            for index in different_ids
+        ]
+        return _compare_approx(
+            self.expected,
+            message_data,
+            number_of_elements,
+            different_ids,
+            max_abs_diff,
+            max_rel_diff,
+        )
+
+    def __eq__(self, actual) -> bool:
+        import numpy as np
+
+        # self.expected is supposed to always be an array here.
+
+        if not np.isscalar(actual):
+            try:
+                actual = np.asarray(actual)
+            except Exception as e:
+                raise TypeError(f"cannot compare '{actual}' to numpy.ndarray") from e
+
+        if not np.isscalar(actual) and actual.shape != self.expected.shape:
+            return False
+
+        return super().__eq__(actual)
+
+    def _yield_comparisons(self, actual):
+        import numpy as np
+
+        # `actual` can either be a numpy array or a scalar, it is treated in
+        # `__eq__` before being passed to `ApproxBase.__eq__`, which is the
+        # only method that calls this one.
+
+        if np.isscalar(actual):
+            for i in np.ndindex(self.expected.shape):
+                yield actual, self.expected[i].item()
+        else:
+            for i in np.ndindex(self.expected.shape):
+                yield actual[i].item(), self.expected[i].item()
+
+
+class ApproxMapping(ApproxBase):
+    """Perform approximate comparisons where the expected value is a mapping
+    with numeric values (the keys can be anything)."""
+
+    def __repr__(self) -> str:
+        return f"approx({({k: self._approx_scalar(v) for k, v in self.expected.items()})!r})"
+
+    def _repr_compare(self, other_side: Mapping[object, float]) -> list[str]:
+        import math
+
+        approx_side_as_map = {
+            k: self._approx_scalar(v) for k, v in self.expected.items()
+        }
+
+        number_of_elements = len(approx_side_as_map)
+        max_abs_diff = -math.inf
+        max_rel_diff = -math.inf
+        different_ids = []
+        for (approx_key, approx_value), other_value in zip(
+            approx_side_as_map.items(), other_side.values()
+        ):
+            if approx_value != other_value:
+                if approx_value.expected is not None and other_value is not None:
+                    try:
+                        max_abs_diff = max(
+                            max_abs_diff, abs(approx_value.expected - other_value)
+                        )
+                        if approx_value.expected == 0.0:
+                            max_rel_diff = math.inf
+                        else:
+                            max_rel_diff = max(
+                                max_rel_diff,
+                                abs(
+                                    (approx_value.expected - other_value)
+                                    / approx_value.expected
+                                ),
+                            )
+                    except ZeroDivisionError:
+                        pass
+                different_ids.append(approx_key)
+
+        message_data = [
+            (str(key), str(other_side[key]), str(approx_side_as_map[key]))
+            for key in different_ids
+        ]
+
+        return _compare_approx(
+            self.expected,
+            message_data,
+            number_of_elements,
+            different_ids,
+            max_abs_diff,
+            max_rel_diff,
+        )
+
+    def __eq__(self, actual) -> bool:
+        try:
+            if set(actual.keys()) != set(self.expected.keys()):
+                return False
+        except AttributeError:
+            return False
+
+        return super().__eq__(actual)
+
+    def _yield_comparisons(self, actual):
+        for k in self.expected.keys():
+            yield actual[k], self.expected[k]
+
+    def _check_type(self) -> None:
+        __tracebackhide__ = True
+        for key, value in self.expected.items():
+            if isinstance(value, type(self.expected)):
+                msg = "pytest.approx() does not support nested dictionaries: key={!r} value={!r}\n  full mapping={}"
+                raise TypeError(msg.format(key, value, pprint.pformat(self.expected)))
+
+
+class ApproxSequenceLike(ApproxBase):
+    """Perform approximate comparisons where the expected value is a sequence of numbers."""
+
+    def __repr__(self) -> str:
+        seq_type = type(self.expected)
+        if seq_type not in (tuple, list):
+            seq_type = list
+        return f"approx({seq_type(self._approx_scalar(x) for x in self.expected)!r})"
+
+    def _repr_compare(self, other_side: Sequence[float]) -> list[str]:
+        import math
+
+        if len(self.expected) != len(other_side):
+            return [
+                "Impossible to compare lists with different sizes.",
+                f"Lengths: {len(self.expected)} and {len(other_side)}",
+            ]
+
+        approx_side_as_map = _recursive_sequence_map(self._approx_scalar, self.expected)
+
+        number_of_elements = len(approx_side_as_map)
+        max_abs_diff = -math.inf
+        max_rel_diff = -math.inf
+        different_ids = []
+        for i, (approx_value, other_value) in enumerate(
+            zip(approx_side_as_map, other_side)
+        ):
+            if approx_value != other_value:
+                abs_diff = abs(approx_value.expected - other_value)
+                max_abs_diff = max(max_abs_diff, abs_diff)
+                if other_value == 0.0:
+                    max_rel_diff = math.inf
+                else:
+                    max_rel_diff = max(max_rel_diff, abs_diff / abs(other_value))
+                different_ids.append(i)
+
+        message_data = [
+            (str(i), str(other_side[i]), str(approx_side_as_map[i]))
+            for i in different_ids
+        ]
+
+        return _compare_approx(
+            self.expected,
+            message_data,
+            number_of_elements,
+            different_ids,
+            max_abs_diff,
+            max_rel_diff,
+        )
+
+    def __eq__(self, actual) -> bool:
+        try:
+            if len(actual) != len(self.expected):
+                return False
+        except TypeError:
+            return False
+        return super().__eq__(actual)
+
+    def _yield_comparisons(self, actual):
+        return zip(actual, self.expected)
+
+    def _check_type(self) -> None:
+        __tracebackhide__ = True
+        for index, x in enumerate(self.expected):
+            if isinstance(x, type(self.expected)):
+                msg = "pytest.approx() does not support nested data structures: {!r} at index {}\n  full sequence: {}"
+                raise TypeError(msg.format(x, index, pprint.pformat(self.expected)))
+
+
+class ApproxScalar(ApproxBase):
+    """Perform approximate comparisons where the expected value is a single number."""
+
+    # Using Real should be better than this Union, but not possible yet:
+    # https://github.com/python/typeshed/pull/3108
+    DEFAULT_ABSOLUTE_TOLERANCE: float | Decimal = 1e-12
+    DEFAULT_RELATIVE_TOLERANCE: float | Decimal = 1e-6
+
+    def __repr__(self) -> str:
+        """Return a string communicating both the expected value and the
+        tolerance for the comparison being made.
+
+        For example, ``1.0 ± 1e-6``, ``(3+4j) ± 5e-6 ∠ ±180°``.
+        """
+        # Don't show a tolerance for values that aren't compared using
+        # tolerances, i.e. non-numerics and infinities. Need to call abs to
+        # handle complex numbers, e.g. (inf + 1j).
+        if (
+            isinstance(self.expected, bool)
+            or (not isinstance(self.expected, (Complex, Decimal)))
+            or math.isinf(abs(self.expected) or isinstance(self.expected, bool))
+        ):
+            return str(self.expected)
+
+        # If a sensible tolerance can't be calculated, self.tolerance will
+        # raise a ValueError.  In this case, display '???'.
+        try:
+            vetted_tolerance = f"{self.tolerance:.1e}"
+            if (
+                isinstance(self.expected, Complex)
+                and self.expected.imag
+                and not math.isinf(self.tolerance)
+            ):
+                vetted_tolerance += " ∠ ±180°"
+        except ValueError:
+            vetted_tolerance = "???"
+
+        return f"{self.expected} ± {vetted_tolerance}"
+
+    def __eq__(self, actual) -> bool:
+        """Return whether the given value is equal to the expected value
+        within the pre-specified tolerance."""
+        asarray = _as_numpy_array(actual)
+        if asarray is not None:
+            # Call ``__eq__()`` manually to prevent infinite-recursion with
+            # numpy<1.13.  See #3748.
+            return all(self.__eq__(a) for a in asarray.flat)
+
+        # Short-circuit exact equality, except for bool
+        if isinstance(self.expected, bool) and not isinstance(actual, bool):
+            return False
+        elif actual == self.expected:
+            return True
+
+        # If either type is non-numeric, fall back to strict equality.
+        # NB: we need Complex, rather than just Number, to ensure that __abs__,
+        # __sub__, and __float__ are defined. Also, consider bool to be
+        # nonnumeric, even though it has the required arithmetic.
+        if isinstance(self.expected, bool) or not (
+            isinstance(self.expected, (Complex, Decimal))
+            and isinstance(actual, (Complex, Decimal))
+        ):
+            return False
+
+        # Allow the user to control whether NaNs are considered equal to each
+        # other or not.  The abs() calls are for compatibility with complex
+        # numbers.
+        if math.isnan(abs(self.expected)):
+            return self.nan_ok and math.isnan(abs(actual))
+
+        # Infinity shouldn't be approximately equal to anything but itself, but
+        # if there's a relative tolerance, it will be infinite and infinity
+        # will seem approximately equal to everything.  The equal-to-itself
+        # case would have been short circuited above, so here we can just
+        # return false if the expected value is infinite.  The abs() call is
+        # for compatibility with complex numbers.
+        if math.isinf(abs(self.expected)):
+            return False
+
+        # Return true if the two numbers are within the tolerance.
+        result: bool = abs(self.expected - actual) <= self.tolerance
+        return result
+
+    # Ignore type because of https://github.com/python/mypy/issues/4266.
+    __hash__ = None  # type: ignore
+
+    @property
+    def tolerance(self):
+        """Return the tolerance for the comparison.
+
+        This could be either an absolute tolerance or a relative tolerance,
+        depending on what the user specified or which would be larger.
+        """
+
+        def set_default(x, default):
+            return x if x is not None else default
+
+        # Figure out what the absolute tolerance should be.  ``self.abs`` is
+        # either None or a value specified by the user.
+        absolute_tolerance = set_default(self.abs, self.DEFAULT_ABSOLUTE_TOLERANCE)
+
+        if absolute_tolerance < 0:
+            raise ValueError(
+                f"absolute tolerance can't be negative: {absolute_tolerance}"
+            )
+        if math.isnan(absolute_tolerance):
+            raise ValueError("absolute tolerance can't be NaN.")
+
+        # If the user specified an absolute tolerance but not a relative one,
+        # just return the absolute tolerance.
+        if self.rel is None:
+            if self.abs is not None:
+                return absolute_tolerance
+
+        # Figure out what the relative tolerance should be.  ``self.rel`` is
+        # either None or a value specified by the user.  This is done after
+        # we've made sure the user didn't ask for an absolute tolerance only,
+        # because we don't want to raise errors about the relative tolerance if
+        # we aren't even going to use it.
+        relative_tolerance = set_default(
+            self.rel, self.DEFAULT_RELATIVE_TOLERANCE
+        ) * abs(self.expected)
+
+        if relative_tolerance < 0:
+            raise ValueError(
+                f"relative tolerance can't be negative: {relative_tolerance}"
+            )
+        if math.isnan(relative_tolerance):
+            raise ValueError("relative tolerance can't be NaN.")
+
+        # Return the larger of the relative and absolute tolerances.
+        return max(relative_tolerance, absolute_tolerance)
+
+
+class ApproxDecimal(ApproxScalar):
+    """Perform approximate comparisons where the expected value is a Decimal."""
+
+    DEFAULT_ABSOLUTE_TOLERANCE = Decimal("1e-12")
+    DEFAULT_RELATIVE_TOLERANCE = Decimal("1e-6")
+
+
+def approx(expected, rel=None, abs=None, nan_ok: bool = False) -> ApproxBase:
+    """Assert that two numbers (or two ordered sequences of numbers) are equal to each other
+    within some tolerance.
+
+    Due to the :doc:`python:tutorial/floatingpoint`, numbers that we
+    would intuitively expect to be equal are not always so::
+
+        >>> 0.1 + 0.2 == 0.3
+        False
+
+    This problem is commonly encountered when writing tests, e.g. when making
+    sure that floating-point values are what you expect them to be.  One way to
+    deal with this problem is to assert that two floating-point numbers are
+    equal to within some appropriate tolerance::
+
+        >>> abs((0.1 + 0.2) - 0.3) < 1e-6
+        True
+
+    However, comparisons like this are tedious to write and difficult to
+    understand.  Furthermore, absolute comparisons like the one above are
+    usually discouraged because there's no tolerance that works well for all
+    situations.  ``1e-6`` is good for numbers around ``1``, but too small for
+    very big numbers and too big for very small ones.  It's better to express
+    the tolerance as a fraction of the expected value, but relative comparisons
+    like that are even more difficult to write correctly and concisely.
+
+    The ``approx`` class performs floating-point comparisons using a syntax
+    that's as intuitive as possible::
+
+        >>> from pytest import approx
+        >>> 0.1 + 0.2 == approx(0.3)
+        True
+
+    The same syntax also works for ordered sequences of numbers::
+
+        >>> (0.1 + 0.2, 0.2 + 0.4) == approx((0.3, 0.6))
+        True
+
+    ``numpy`` arrays::
+
+        >>> import numpy as np                                                          # doctest: +SKIP
+        >>> np.array([0.1, 0.2]) + np.array([0.2, 0.4]) == approx(np.array([0.3, 0.6])) # doctest: +SKIP
+        True
+
+    And for a ``numpy`` array against a scalar::
+
+        >>> import numpy as np                                         # doctest: +SKIP
+        >>> np.array([0.1, 0.2]) + np.array([0.2, 0.1]) == approx(0.3) # doctest: +SKIP
+        True
+
+    Only ordered sequences are supported, because ``approx`` needs
+    to infer the relative position of the sequences without ambiguity. This means
+    ``sets`` and other unordered sequences are not supported.
+
+    Finally, dictionary *values* can also be compared::
+
+        >>> {'a': 0.1 + 0.2, 'b': 0.2 + 0.4} == approx({'a': 0.3, 'b': 0.6})
+        True
+
+    The comparison will be true if both mappings have the same keys and their
+    respective values match the expected tolerances.
+
+    **Tolerances**
+
+    By default, ``approx`` considers numbers within a relative tolerance of
+    ``1e-6`` (i.e. one part in a million) of its expected value to be equal.
+    This treatment would lead to surprising results if the expected value was
+    ``0.0``, because nothing but ``0.0`` itself is relatively close to ``0.0``.
+    To handle this case less surprisingly, ``approx`` also considers numbers
+    within an absolute tolerance of ``1e-12`` of its expected value to be
+    equal.  Infinity and NaN are special cases.  Infinity is only considered
+    equal to itself, regardless of the relative tolerance.  NaN is not
+    considered equal to anything by default, but you can make it be equal to
+    itself by setting the ``nan_ok`` argument to True.  (This is meant to
+    facilitate comparing arrays that use NaN to mean "no data".)
+
+    Both the relative and absolute tolerances can be changed by passing
+    arguments to the ``approx`` constructor::
+
+        >>> 1.0001 == approx(1)
+        False
+        >>> 1.0001 == approx(1, rel=1e-3)
+        True
+        >>> 1.0001 == approx(1, abs=1e-3)
+        True
+
+    If you specify ``abs`` but not ``rel``, the comparison will not consider
+    the relative tolerance at all.  In other words, two numbers that are within
+    the default relative tolerance of ``1e-6`` will still be considered unequal
+    if they exceed the specified absolute tolerance.  If you specify both
+    ``abs`` and ``rel``, the numbers will be considered equal if either
+    tolerance is met::
+
+        >>> 1 + 1e-8 == approx(1)
+        True
+        >>> 1 + 1e-8 == approx(1, abs=1e-12)
+        False
+        >>> 1 + 1e-8 == approx(1, rel=1e-6, abs=1e-12)
+        True
+
+    You can also use ``approx`` to compare nonnumeric types, or dicts and
+    sequences containing nonnumeric types, in which case it falls back to
+    strict equality. This can be useful for comparing dicts and sequences that
+    can contain optional values::
+
+        >>> {"required": 1.0000005, "optional": None} == approx({"required": 1, "optional": None})
+        True
+        >>> [None, 1.0000005] == approx([None,1])
+        True
+        >>> ["foo", 1.0000005] == approx([None,1])
+        False
+
+    If you're thinking about using ``approx``, then you might want to know how
+    it compares to other good ways of comparing floating-point numbers.  All of
+    these algorithms are based on relative and absolute tolerances and should
+    agree for the most part, but they do have meaningful differences:
+
+    - ``math.isclose(a, b, rel_tol=1e-9, abs_tol=0.0)``:  True if the relative
+      tolerance is met w.r.t. either ``a`` or ``b`` or if the absolute
+      tolerance is met.  Because the relative tolerance is calculated w.r.t.
+      both ``a`` and ``b``, this test is symmetric (i.e.  neither ``a`` nor
+      ``b`` is a "reference value").  You have to specify an absolute tolerance
+      if you want to compare to ``0.0`` because there is no tolerance by
+      default.  More information: :py:func:`math.isclose`.
+
+    - ``numpy.isclose(a, b, rtol=1e-5, atol=1e-8)``: True if the difference
+      between ``a`` and ``b`` is less that the sum of the relative tolerance
+      w.r.t. ``b`` and the absolute tolerance.  Because the relative tolerance
+      is only calculated w.r.t. ``b``, this test is asymmetric and you can
+      think of ``b`` as the reference value.  Support for comparing sequences
+      is provided by :py:func:`numpy.allclose`.  More information:
+      :std:doc:`numpy:reference/generated/numpy.isclose`.
+
+    - ``unittest.TestCase.assertAlmostEqual(a, b)``: True if ``a`` and ``b``
+      are within an absolute tolerance of ``1e-7``.  No relative tolerance is
+      considered , so this function is not appropriate for very large or very
+      small numbers.  Also, it's only available in subclasses of ``unittest.TestCase``
+      and it's ugly because it doesn't follow PEP8.  More information:
+      :py:meth:`unittest.TestCase.assertAlmostEqual`.
+
+    - ``a == pytest.approx(b, rel=1e-6, abs=1e-12)``: True if the relative
+      tolerance is met w.r.t. ``b`` or if the absolute tolerance is met.
+      Because the relative tolerance is only calculated w.r.t. ``b``, this test
+      is asymmetric and you can think of ``b`` as the reference value.  In the
+      special case that you explicitly specify an absolute tolerance but not a
+      relative tolerance, only the absolute tolerance is considered.
+
+    .. note::
+
+        ``approx`` can handle numpy arrays, but we recommend the
+        specialised test helpers in :std:doc:`numpy:reference/routines.testing`
+        if you need support for comparisons, NaNs, or ULP-based tolerances.
+
+        To match strings using regex, you can use
+        `Matches <https://github.com/asottile/re-assert#re_assertmatchespattern-str-args-kwargs>`_
+        from the
+        `re_assert package <https://github.com/asottile/re-assert>`_.
+
+    .. warning::
+
+       .. versionchanged:: 3.2
+
+       In order to avoid inconsistent behavior, :py:exc:`TypeError` is
+       raised for ``>``, ``>=``, ``<`` and ``<=`` comparisons.
+       The example below illustrates the problem::
+
+           assert approx(0.1) > 0.1 + 1e-10  # calls approx(0.1).__gt__(0.1 + 1e-10)
+           assert 0.1 + 1e-10 > approx(0.1)  # calls approx(0.1).__lt__(0.1 + 1e-10)
+
+       In the second example one expects ``approx(0.1).__le__(0.1 + 1e-10)``
+       to be called. But instead, ``approx(0.1).__lt__(0.1 + 1e-10)`` is used to
+       comparison. This is because the call hierarchy of rich comparisons
+       follows a fixed behavior. More information: :py:meth:`object.__ge__`
+
+    .. versionchanged:: 3.7.1
+       ``approx`` raises ``TypeError`` when it encounters a dict value or
+       sequence element of nonnumeric type.
+
+    .. versionchanged:: 6.1.0
+       ``approx`` falls back to strict equality for nonnumeric types instead
+       of raising ``TypeError``.
+    """
+    # Delegate the comparison to a class that knows how to deal with the type
+    # of the expected value (e.g. int, float, list, dict, numpy.array, etc).
+    #
+    # The primary responsibility of these classes is to implement ``__eq__()``
+    # and ``__repr__()``.  The former is used to actually check if some
+    # "actual" value is equivalent to the given expected value within the
+    # allowed tolerance.  The latter is used to show the user the expected
+    # value and tolerance, in the case that a test failed.
+    #
+    # The actual logic for making approximate comparisons can be found in
+    # ApproxScalar, which is used to compare individual numbers.  All of the
+    # other Approx classes eventually delegate to this class.  The ApproxBase
+    # class provides some convenient methods and overloads, but isn't really
+    # essential.
+
+    __tracebackhide__ = True
+
+    if isinstance(expected, Decimal):
+        cls: type[ApproxBase] = ApproxDecimal
+    elif isinstance(expected, Mapping):
+        cls = ApproxMapping
+    elif _is_numpy_array(expected):
+        expected = _as_numpy_array(expected)
+        cls = ApproxNumpy
+    elif _is_sequence_like(expected):
+        cls = ApproxSequenceLike
+    elif isinstance(expected, Collection) and not isinstance(expected, (str, bytes)):
+        msg = f"pytest.approx() only supports ordered sequences, but got: {expected!r}"
+        raise TypeError(msg)
+    else:
+        cls = ApproxScalar
+
+    return cls(expected, rel, abs, nan_ok)
+
+
+def _is_sequence_like(expected: object) -> bool:
+    return (
+        hasattr(expected, "__getitem__")
+        and isinstance(expected, Sized)
+        and not isinstance(expected, (str, bytes))
+    )
+
+
+def _is_numpy_array(obj: object) -> bool:
+    """
+    Return true if the given object is implicitly convertible to ndarray,
+    and numpy is already imported.
+    """
+    return _as_numpy_array(obj) is not None
+
+
+def _as_numpy_array(obj: object) -> ndarray | None:
+    """
+    Return an ndarray if the given object is implicitly convertible to ndarray,
+    and numpy is already imported, otherwise None.
+    """
+    import sys
+
+    np: Any = sys.modules.get("numpy")
+    if np is not None:
+        # avoid infinite recursion on numpy scalars, which have __array__
+        if np.isscalar(obj):
+            return None
+        elif isinstance(obj, np.ndarray):
+            return obj
+        elif hasattr(obj, "__array__") or hasattr("obj", "__array_interface__"):
+            return np.asarray(obj)
+    return None
+
+
+# builtin pytest.raises helper
+
+E = TypeVar("E", bound=BaseException)
+
+
+@overload
+def raises(
+    expected_exception: type[E] | tuple[type[E], ...],
+    *,
+    match: str | Pattern[str] | None = ...,
+) -> RaisesContext[E]: ...
+
+
+@overload
+def raises(
+    expected_exception: type[E] | tuple[type[E], ...],
+    func: Callable[..., Any],
+    *args: Any,
+    **kwargs: Any,
+) -> _pytest._code.ExceptionInfo[E]: ...
+
+
+def raises(
+    expected_exception: type[E] | tuple[type[E], ...], *args: Any, **kwargs: Any
+) -> RaisesContext[E] | _pytest._code.ExceptionInfo[E]:
+    r"""Assert that a code block/function call raises an exception type, or one of its subclasses.
+
+    :param expected_exception:
+        The expected exception type, or a tuple if one of multiple possible
+        exception types are expected. Note that subclasses of the passed exceptions
+        will also match.
+
+    :kwparam str | re.Pattern[str] | None match:
+        If specified, a string containing a regular expression,
+        or a regular expression object, that is tested against the string
+        representation of the exception and its :pep:`678` `__notes__`
+        using :func:`re.search`.
+
+        To match a literal string that may contain :ref:`special characters
+        <re-syntax>`, the pattern can first be escaped with :func:`re.escape`.
+
+        (This is only used when ``pytest.raises`` is used as a context manager,
+        and passed through to the function otherwise.
+        When using ``pytest.raises`` as a function, you can use:
+        ``pytest.raises(Exc, func, match="passed on").match("my pattern")``.)
+
+    Use ``pytest.raises`` as a context manager, which will capture the exception of the given
+    type, or any of its subclasses::
+
+        >>> import pytest
+        >>> with pytest.raises(ZeroDivisionError):
+        ...    1/0
+
+    If the code block does not raise the expected exception (:class:`ZeroDivisionError` in the example
+    above), or no exception at all, the check will fail instead.
+
+    You can also use the keyword argument ``match`` to assert that the
+    exception matches a text or regex::
+
+        >>> with pytest.raises(ValueError, match='must be 0 or None'):
+        ...     raise ValueError("value must be 0 or None")
+
+        >>> with pytest.raises(ValueError, match=r'must be \d+$'):
+        ...     raise ValueError("value must be 42")
+
+    The ``match`` argument searches the formatted exception string, which includes any
+    `PEP-678 <https://peps.python.org/pep-0678/>`__ ``__notes__``:
+
+        >>> with pytest.raises(ValueError, match=r"had a note added"):  # doctest: +SKIP
+        ...     e = ValueError("value must be 42")
+        ...     e.add_note("had a note added")
+        ...     raise e
+
+    The context manager produces an :class:`ExceptionInfo` object which can be used to inspect the
+    details of the captured exception::
+
+        >>> with pytest.raises(ValueError) as exc_info:
+        ...     raise ValueError("value must be 42")
+        >>> assert exc_info.type is ValueError
+        >>> assert exc_info.value.args[0] == "value must be 42"
+
+    .. warning::
+
+       Given that ``pytest.raises`` matches subclasses, be wary of using it to match :class:`Exception` like this::
+
+           with pytest.raises(Exception):  # Careful, this will catch ANY exception raised.
+               some_function()
+
+       Because :class:`Exception` is the base class of almost all exceptions, it is easy for this to hide
+       real bugs, where the user wrote this expecting a specific exception, but some other exception is being
+       raised due to a bug introduced during a refactoring.
+
+       Avoid using ``pytest.raises`` to catch :class:`Exception` unless certain that you really want to catch
+       **any** exception raised.
+
+    .. note::
+
+       When using ``pytest.raises`` as a context manager, it's worthwhile to
+       note that normal context manager rules apply and that the exception
+       raised *must* be the final line in the scope of the context manager.
+       Lines of code after that, within the scope of the context manager will
+       not be executed. For example::
+
+           >>> value = 15
+           >>> with pytest.raises(ValueError) as exc_info:
+           ...     if value > 10:
+           ...         raise ValueError("value must be <= 10")
+           ...     assert exc_info.type is ValueError  # This will not execute.
+
+       Instead, the following approach must be taken (note the difference in
+       scope)::
+
+           >>> with pytest.raises(ValueError) as exc_info:
+           ...     if value > 10:
+           ...         raise ValueError("value must be <= 10")
+           ...
+           >>> assert exc_info.type is ValueError
+
+    **Using with** ``pytest.mark.parametrize``
+
+    When using :ref:`pytest.mark.parametrize ref`
+    it is possible to parametrize tests such that
+    some runs raise an exception and others do not.
+
+    See :ref:`parametrizing_conditional_raising` for an example.
+
+    .. seealso::
+
+        :ref:`assertraises` for more examples and detailed discussion.
+
+    **Legacy form**
+
+    It is possible to specify a callable by passing a to-be-called lambda::
+
+        >>> raises(ZeroDivisionError, lambda: 1/0)
+        <ExceptionInfo ...>
+
+    or you can specify an arbitrary callable with arguments::
+
+        >>> def f(x): return 1/x
+        ...
+        >>> raises(ZeroDivisionError, f, 0)
+        <ExceptionInfo ...>
+        >>> raises(ZeroDivisionError, f, x=0)
+        <ExceptionInfo ...>
+
+    The form above is fully supported but discouraged for new code because the
+    context manager form is regarded as more readable and less error-prone.
+
+    .. note::
+        Similar to caught exception objects in Python, explicitly clearing
+        local references to returned ``ExceptionInfo`` objects can
+        help the Python interpreter speed up its garbage collection.
+
+        Clearing those references breaks a reference cycle
+        (``ExceptionInfo`` --> caught exception --> frame stack raising
+        the exception --> current frame stack --> local variables -->
+        ``ExceptionInfo``) which makes Python keep all objects referenced
+        from that cycle (including all local variables in the current
+        frame) alive until the next cyclic garbage collection run.
+        More detailed information can be found in the official Python
+        documentation for :ref:`the try statement <python:try>`.
+    """
+    __tracebackhide__ = True
+
+    if not expected_exception:
+        raise ValueError(
+            f"Expected an exception type or a tuple of exception types, but got `{expected_exception!r}`. "
+            f"Raising exceptions is already understood as failing the test, so you don't need "
+            f"any special code to say 'this should never raise an exception'."
+        )
+    if isinstance(expected_exception, type):
+        expected_exceptions: tuple[type[E], ...] = (expected_exception,)
+    else:
+        expected_exceptions = expected_exception
+    for exc in expected_exceptions:
+        if not isinstance(exc, type) or not issubclass(exc, BaseException):
+            msg = "expected exception must be a BaseException type, not {}"  # type: ignore[unreachable]
+            not_a = exc.__name__ if isinstance(exc, type) else type(exc).__name__
+            raise TypeError(msg.format(not_a))
+
+    message = f"DID NOT RAISE {expected_exception}"
+
+    if not args:
+        match: str | Pattern[str] | None = kwargs.pop("match", None)
+        if kwargs:
+            msg = "Unexpected keyword arguments passed to pytest.raises: "
+            msg += ", ".join(sorted(kwargs))
+            msg += "\nUse context-manager form instead?"
+            raise TypeError(msg)
+        return RaisesContext(expected_exception, message, match)
+    else:
+        func = args[0]
+        if not callable(func):
+            raise TypeError(f"{func!r} object (type: {type(func)}) must be callable")
+        try:
+            func(*args[1:], **kwargs)
+        except expected_exception as e:
+            return _pytest._code.ExceptionInfo.from_exception(e)
+    fail(message)
+
+
+# This doesn't work with mypy for now. Use fail.Exception instead.
+raises.Exception = fail.Exception  # type: ignore
+
+
+@final
+class RaisesContext(ContextManager[_pytest._code.ExceptionInfo[E]]):
+    def __init__(
+        self,
+        expected_exception: type[E] | tuple[type[E], ...],
+        message: str,
+        match_expr: str | Pattern[str] | None = None,
+    ) -> None:
+        self.expected_exception = expected_exception
+        self.message = message
+        self.match_expr = match_expr
+        self.excinfo: _pytest._code.ExceptionInfo[E] | None = None
+        if self.match_expr is not None:
+            re_error = None
+            try:
+                re.compile(self.match_expr)
+            except re.error as e:
+                re_error = e
+            if re_error is not None:
+                fail(f"Invalid regex pattern provided to 'match': {re_error}")
+
+    def __enter__(self) -> _pytest._code.ExceptionInfo[E]:
+        self.excinfo = _pytest._code.ExceptionInfo.for_later()
+        return self.excinfo
+
+    def __exit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc_val: BaseException | None,
+        exc_tb: TracebackType | None,
+    ) -> bool:
+        __tracebackhide__ = True
+        if exc_type is None:
+            fail(self.message)
+        assert self.excinfo is not None
+        if not issubclass(exc_type, self.expected_exception):
+            return False
+        # Cast to narrow the exception type now that it's verified.
+        exc_info = cast(Tuple[Type[E], E, TracebackType], (exc_type, exc_val, exc_tb))
+        self.excinfo.fill_unfilled(exc_info)
+        if self.match_expr is not None:
+            self.excinfo.match(self.match_expr)
+        return True

.venv/lib/python3.11/site-packages/_pytest/recwarn.py

@@ -0,0 +1,364 @@
+# mypy: allow-untyped-defs
+"""Record warnings during test function execution."""
+
+from __future__ import annotations
+
+from pprint import pformat
+import re
+from types import TracebackType
+from typing import Any
+from typing import Callable
+from typing import final
+from typing import Generator
+from typing import Iterator
+from typing import overload
+from typing import Pattern
+from typing import TYPE_CHECKING
+from typing import TypeVar
+
+
+if TYPE_CHECKING:
+    from typing_extensions import Self
+
+import warnings
+
+from _pytest.deprecated import check_ispytest
+from _pytest.fixtures import fixture
+from _pytest.outcomes import Exit
+from _pytest.outcomes import fail
+
+
+T = TypeVar("T")
+
+
+@fixture
+def recwarn() -> Generator[WarningsRecorder]:
+    """Return a :class:`WarningsRecorder` instance that records all warnings emitted by test functions.
+
+    See :ref:`warnings` for information on warning categories.
+    """
+    wrec = WarningsRecorder(_ispytest=True)
+    with wrec:
+        warnings.simplefilter("default")
+        yield wrec
+
+
+@overload
+def deprecated_call(*, match: str | Pattern[str] | None = ...) -> WarningsRecorder: ...
+
+
+@overload
+def deprecated_call(func: Callable[..., T], *args: Any, **kwargs: Any) -> T: ...
+
+
+def deprecated_call(
+    func: Callable[..., Any] | None = None, *args: Any, **kwargs: Any
+) -> WarningsRecorder | Any:
+    """Assert that code produces a ``DeprecationWarning`` or ``PendingDeprecationWarning`` or ``FutureWarning``.
+
+    This function can be used as a context manager::
+
+        >>> import warnings
+        >>> def api_call_v2():
+        ...     warnings.warn('use v3 of this api', DeprecationWarning)
+        ...     return 200
+
+        >>> import pytest
+        >>> with pytest.deprecated_call():
+        ...    assert api_call_v2() == 200
+
+    It can also be used by passing a function and ``*args`` and ``**kwargs``,
+    in which case it will ensure calling ``func(*args, **kwargs)`` produces one of
+    the warnings types above. The return value is the return value of the function.
+
+    In the context manager form you may use the keyword argument ``match`` to assert
+    that the warning matches a text or regex.
+
+    The context manager produces a list of :class:`warnings.WarningMessage` objects,
+    one for each warning raised.
+    """
+    __tracebackhide__ = True
+    if func is not None:
+        args = (func, *args)
+    return warns(
+        (DeprecationWarning, PendingDeprecationWarning, FutureWarning), *args, **kwargs
+    )
+
+
+@overload
+def warns(
+    expected_warning: type[Warning] | tuple[type[Warning], ...] = ...,
+    *,
+    match: str | Pattern[str] | None = ...,
+) -> WarningsChecker: ...
+
+
+@overload
+def warns(
+    expected_warning: type[Warning] | tuple[type[Warning], ...],
+    func: Callable[..., T],
+    *args: Any,
+    **kwargs: Any,
+) -> T: ...
+
+
+def warns(
+    expected_warning: type[Warning] | tuple[type[Warning], ...] = Warning,
+    *args: Any,
+    match: str | Pattern[str] | None = None,
+    **kwargs: Any,
+) -> WarningsChecker | Any:
+    r"""Assert that code raises a particular class of warning.
+
+    Specifically, the parameter ``expected_warning`` can be a warning class or tuple
+    of warning classes, and the code inside the ``with`` block must issue at least one
+    warning of that class or classes.
+
+    This helper produces a list of :class:`warnings.WarningMessage` objects, one for
+    each warning emitted (regardless of whether it is an ``expected_warning`` or not).
+    Since pytest 8.0, unmatched warnings are also re-emitted when the context closes.
+
+    This function can be used as a context manager::
+
+        >>> import pytest
+        >>> with pytest.warns(RuntimeWarning):
+        ...    warnings.warn("my warning", RuntimeWarning)
+
+    In the context manager form you may use the keyword argument ``match`` to assert
+    that the warning matches a text or regex::
+
+        >>> with pytest.warns(UserWarning, match='must be 0 or None'):
+        ...     warnings.warn("value must be 0 or None", UserWarning)
+
+        >>> with pytest.warns(UserWarning, match=r'must be \d+$'):
+        ...     warnings.warn("value must be 42", UserWarning)
+
+        >>> with pytest.warns(UserWarning):  # catch re-emitted warning
+        ...     with pytest.warns(UserWarning, match=r'must be \d+$'):
+        ...         warnings.warn("this is not here", UserWarning)
+        Traceback (most recent call last):
+          ...
+        Failed: DID NOT WARN. No warnings of type ...UserWarning... were emitted...
+
+    **Using with** ``pytest.mark.parametrize``
+
+    When using :ref:`pytest.mark.parametrize ref` it is possible to parametrize tests
+    such that some runs raise a warning and others do not.
+
+    This could be achieved in the same way as with exceptions, see
+    :ref:`parametrizing_conditional_raising` for an example.
+
+    """
+    __tracebackhide__ = True
+    if not args:
+        if kwargs:
+            argnames = ", ".join(sorted(kwargs))
+            raise TypeError(
+                f"Unexpected keyword arguments passed to pytest.warns: {argnames}"
+                "\nUse context-manager form instead?"
+            )
+        return WarningsChecker(expected_warning, match_expr=match, _ispytest=True)
+    else:
+        func = args[0]
+        if not callable(func):
+            raise TypeError(f"{func!r} object (type: {type(func)}) must be callable")
+        with WarningsChecker(expected_warning, _ispytest=True):
+            return func(*args[1:], **kwargs)
+
+
+class WarningsRecorder(warnings.catch_warnings):  # type:ignore[type-arg]
+    """A context manager to record raised warnings.
+
+    Each recorded warning is an instance of :class:`warnings.WarningMessage`.
+
+    Adapted from `warnings.catch_warnings`.
+
+    .. note::
+        ``DeprecationWarning`` and ``PendingDeprecationWarning`` are treated
+        differently; see :ref:`ensuring_function_triggers`.
+
+    """
+
+    def __init__(self, *, _ispytest: bool = False) -> None:
+        check_ispytest(_ispytest)
+        super().__init__(record=True)
+        self._entered = False
+        self._list: list[warnings.WarningMessage] = []
+
+    @property
+    def list(self) -> list[warnings.WarningMessage]:
+        """The list of recorded warnings."""
+        return self._list
+
+    def __getitem__(self, i: int) -> warnings.WarningMessage:
+        """Get a recorded warning by index."""
+        return self._list[i]
+
+    def __iter__(self) -> Iterator[warnings.WarningMessage]:
+        """Iterate through the recorded warnings."""
+        return iter(self._list)
+
+    def __len__(self) -> int:
+        """The number of recorded warnings."""
+        return len(self._list)
+
+    def pop(self, cls: type[Warning] = Warning) -> warnings.WarningMessage:
+        """Pop the first recorded warning which is an instance of ``cls``,
+        but not an instance of a child class of any other match.
+        Raises ``AssertionError`` if there is no match.
+        """
+        best_idx: int | None = None
+        for i, w in enumerate(self._list):
+            if w.category == cls:
+                return self._list.pop(i)  # exact match, stop looking
+            if issubclass(w.category, cls) and (
+                best_idx is None
+                or not issubclass(w.category, self._list[best_idx].category)
+            ):
+                best_idx = i
+        if best_idx is not None:
+            return self._list.pop(best_idx)
+        __tracebackhide__ = True
+        raise AssertionError(f"{cls!r} not found in warning list")
+
+    def clear(self) -> None:
+        """Clear the list of recorded warnings."""
+        self._list[:] = []
+
+    def __enter__(self) -> Self:
+        if self._entered:
+            __tracebackhide__ = True
+            raise RuntimeError(f"Cannot enter {self!r} twice")
+        _list = super().__enter__()
+        # record=True means it's None.
+        assert _list is not None
+        self._list = _list
+        warnings.simplefilter("always")
+        return self
+
+    def __exit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc_val: BaseException | None,
+        exc_tb: TracebackType | None,
+    ) -> None:
+        if not self._entered:
+            __tracebackhide__ = True
+            raise RuntimeError(f"Cannot exit {self!r} without entering first")
+
+        super().__exit__(exc_type, exc_val, exc_tb)
+
+        # Built-in catch_warnings does not reset entered state so we do it
+        # manually here for this context manager to become reusable.
+        self._entered = False
+
+
+@final
+class WarningsChecker(WarningsRecorder):
+    def __init__(
+        self,
+        expected_warning: type[Warning] | tuple[type[Warning], ...] = Warning,
+        match_expr: str | Pattern[str] | None = None,
+        *,
+        _ispytest: bool = False,
+    ) -> None:
+        check_ispytest(_ispytest)
+        super().__init__(_ispytest=True)
+
+        msg = "exceptions must be derived from Warning, not %s"
+        if isinstance(expected_warning, tuple):
+            for exc in expected_warning:
+                if not issubclass(exc, Warning):
+                    raise TypeError(msg % type(exc))
+            expected_warning_tup = expected_warning
+        elif isinstance(expected_warning, type) and issubclass(
+            expected_warning, Warning
+        ):
+            expected_warning_tup = (expected_warning,)
+        else:
+            raise TypeError(msg % type(expected_warning))
+
+        self.expected_warning = expected_warning_tup
+        self.match_expr = match_expr
+
+    def matches(self, warning: warnings.WarningMessage) -> bool:
+        assert self.expected_warning is not None
+        return issubclass(warning.category, self.expected_warning) and bool(
+            self.match_expr is None or re.search(self.match_expr, str(warning.message))
+        )
+
+    def __exit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc_val: BaseException | None,
+        exc_tb: TracebackType | None,
+    ) -> None:
+        super().__exit__(exc_type, exc_val, exc_tb)
+
+        __tracebackhide__ = True
+
+        # BaseExceptions like pytest.{skip,fail,xfail,exit} or Ctrl-C within
+        # pytest.warns should *not* trigger "DID NOT WARN" and get suppressed
+        # when the warning doesn't happen. Control-flow exceptions should always
+        # propagate.
+        if exc_val is not None and (
+            not isinstance(exc_val, Exception)
+            # Exit is an Exception, not a BaseException, for some reason.
+            or isinstance(exc_val, Exit)
+        ):
+            return
+
+        def found_str() -> str:
+            return pformat([record.message for record in self], indent=2)
+
+        try:
+            if not any(issubclass(w.category, self.expected_warning) for w in self):
+                fail(
+                    f"DID NOT WARN. No warnings of type {self.expected_warning} were emitted.\n"
+                    f" Emitted warnings: {found_str()}."
+                )
+            elif not any(self.matches(w) for w in self):
+                fail(
+                    f"DID NOT WARN. No warnings of type {self.expected_warning} matching the regex were emitted.\n"
+                    f" Regex: {self.match_expr}\n"
+                    f" Emitted warnings: {found_str()}."
+                )
+        finally:
+            # Whether or not any warnings matched, we want to re-emit all unmatched warnings.
+            for w in self:
+                if not self.matches(w):
+                    warnings.warn_explicit(
+                        message=w.message,
+                        category=w.category,
+                        filename=w.filename,
+                        lineno=w.lineno,
+                        module=w.__module__,
+                        source=w.source,
+                    )
+
+            # Currently in Python it is possible to pass other types than an
+            # `str` message when creating `Warning` instances, however this
+            # causes an exception when :func:`warnings.filterwarnings` is used
+            # to filter those warnings. See
+            # https://github.com/python/cpython/issues/103577 for a discussion.
+            # While this can be considered a bug in CPython, we put guards in
+            # pytest as the error message produced without this check in place
+            # is confusing (#10865).
+            for w in self:
+                if type(w.message) is not UserWarning:
+                    # If the warning was of an incorrect type then `warnings.warn()`
+                    # creates a UserWarning. Any other warning must have been specified
+                    # explicitly.
+                    continue
+                if not w.message.args:
+                    # UserWarning() without arguments must have been specified explicitly.
+                    continue
+                msg = w.message.args[0]
+                if isinstance(msg, str):
+                    continue
+                # It's possible that UserWarning was explicitly specified, and
+                # its first argument was not a string. But that case can't be
+                # distinguished from an invalid type.
+                raise TypeError(
+                    f"Warning must be str or Warning, got {msg!r} (type {type(msg).__name__})"
+                )

.venv/lib/python3.11/site-packages/_pytest/tmpdir.py

@@ -0,0 +1,314 @@
+# mypy: allow-untyped-defs
+"""Support for providing temporary directories to test functions."""
+
+from __future__ import annotations
+
+import dataclasses
+import os
+from pathlib import Path
+import re
+from shutil import rmtree
+import tempfile
+from typing import Any
+from typing import Dict
+from typing import final
+from typing import Generator
+from typing import Literal
+
+from .pathlib import cleanup_dead_symlinks
+from .pathlib import LOCK_TIMEOUT
+from .pathlib import make_numbered_dir
+from .pathlib import make_numbered_dir_with_cleanup
+from .pathlib import rm_rf
+from _pytest.compat import get_user_id
+from _pytest.config import Config
+from _pytest.config import ExitCode
+from _pytest.config import hookimpl
+from _pytest.config.argparsing import Parser
+from _pytest.deprecated import check_ispytest
+from _pytest.fixtures import fixture
+from _pytest.fixtures import FixtureRequest
+from _pytest.monkeypatch import MonkeyPatch
+from _pytest.nodes import Item
+from _pytest.reports import TestReport
+from _pytest.stash import StashKey
+
+
+tmppath_result_key = StashKey[Dict[str, bool]]()
+RetentionType = Literal["all", "failed", "none"]
+
+
+@final
+@dataclasses.dataclass
+class TempPathFactory:
+    """Factory for temporary directories under the common base temp directory,
+    as discussed at :ref:`temporary directory location and retention`.
+    """
+
+    _given_basetemp: Path | None
+    # pluggy TagTracerSub, not currently exposed, so Any.
+    _trace: Any
+    _basetemp: Path | None
+    _retention_count: int
+    _retention_policy: RetentionType
+
+    def __init__(
+        self,
+        given_basetemp: Path | None,
+        retention_count: int,
+        retention_policy: RetentionType,
+        trace,
+        basetemp: Path | None = None,
+        *,
+        _ispytest: bool = False,
+    ) -> None:
+        check_ispytest(_ispytest)
+        if given_basetemp is None:
+            self._given_basetemp = None
+        else:
+            # Use os.path.abspath() to get absolute path instead of resolve() as it
+            # does not work the same in all platforms (see #4427).
+            # Path.absolute() exists, but it is not public (see https://bugs.python.org/issue25012).
+            self._given_basetemp = Path(os.path.abspath(str(given_basetemp)))
+        self._trace = trace
+        self._retention_count = retention_count
+        self._retention_policy = retention_policy
+        self._basetemp = basetemp
+
+    @classmethod
+    def from_config(
+        cls,
+        config: Config,
+        *,
+        _ispytest: bool = False,
+    ) -> TempPathFactory:
+        """Create a factory according to pytest configuration.
+
+        :meta private:
+        """
+        check_ispytest(_ispytest)
+        count = int(config.getini("tmp_path_retention_count"))
+        if count < 0:
+            raise ValueError(
+                f"tmp_path_retention_count must be >= 0. Current input: {count}."
+            )
+
+        policy = config.getini("tmp_path_retention_policy")
+        if policy not in ("all", "failed", "none"):
+            raise ValueError(
+                f"tmp_path_retention_policy must be either all, failed, none. Current input: {policy}."
+            )
+
+        return cls(
+            given_basetemp=config.option.basetemp,
+            trace=config.trace.get("tmpdir"),
+            retention_count=count,
+            retention_policy=policy,
+            _ispytest=True,
+        )
+
+    def _ensure_relative_to_basetemp(self, basename: str) -> str:
+        basename = os.path.normpath(basename)
+        if (self.getbasetemp() / basename).resolve().parent != self.getbasetemp():
+            raise ValueError(f"{basename} is not a normalized and relative path")
+        return basename
+
+    def mktemp(self, basename: str, numbered: bool = True) -> Path:
+        """Create a new temporary directory managed by the factory.
+
+        :param basename:
+            Directory base name, must be a relative path.
+
+        :param numbered:
+            If ``True``, ensure the directory is unique by adding a numbered
+            suffix greater than any existing one: ``basename="foo-"`` and ``numbered=True``
+            means that this function will create directories named ``"foo-0"``,
+            ``"foo-1"``, ``"foo-2"`` and so on.
+
+        :returns:
+            The path to the new directory.
+        """
+        basename = self._ensure_relative_to_basetemp(basename)
+        if not numbered:
+            p = self.getbasetemp().joinpath(basename)
+            p.mkdir(mode=0o700)
+        else:
+            p = make_numbered_dir(root=self.getbasetemp(), prefix=basename, mode=0o700)
+            self._trace("mktemp", p)
+        return p
+
+    def getbasetemp(self) -> Path:
+        """Return the base temporary directory, creating it if needed.
+
+        :returns:
+            The base temporary directory.
+        """
+        if self._basetemp is not None:
+            return self._basetemp
+
+        if self._given_basetemp is not None:
+            basetemp = self._given_basetemp
+            if basetemp.exists():
+                rm_rf(basetemp)
+            basetemp.mkdir(mode=0o700)
+            basetemp = basetemp.resolve()
+        else:
+            from_env = os.environ.get("PYTEST_DEBUG_TEMPROOT")
+            temproot = Path(from_env or tempfile.gettempdir()).resolve()
+            user = get_user() or "unknown"
+            # use a sub-directory in the temproot to speed-up
+            # make_numbered_dir() call
+            rootdir = temproot.joinpath(f"pytest-of-{user}")
+            try:
+                rootdir.mkdir(mode=0o700, exist_ok=True)
+            except OSError:
+                # getuser() likely returned illegal characters for the platform, use unknown back off mechanism
+                rootdir = temproot.joinpath("pytest-of-unknown")
+                rootdir.mkdir(mode=0o700, exist_ok=True)
+            # Because we use exist_ok=True with a predictable name, make sure
+            # we are the owners, to prevent any funny business (on unix, where
+            # temproot is usually shared).
+            # Also, to keep things private, fixup any world-readable temp
+            # rootdir's permissions. Historically 0o755 was used, so we can't
+            # just error out on this, at least for a while.
+            uid = get_user_id()
+            if uid is not None:
+                rootdir_stat = rootdir.stat()
+                if rootdir_stat.st_uid != uid:
+                    raise OSError(
+                        f"The temporary directory {rootdir} is not owned by the current user. "
+                        "Fix this and try again."
+                    )
+                if (rootdir_stat.st_mode & 0o077) != 0:
+                    os.chmod(rootdir, rootdir_stat.st_mode & ~0o077)
+            keep = self._retention_count
+            if self._retention_policy == "none":
+                keep = 0
+            basetemp = make_numbered_dir_with_cleanup(
+                prefix="pytest-",
+                root=rootdir,
+                keep=keep,
+                lock_timeout=LOCK_TIMEOUT,
+                mode=0o700,
+            )
+        assert basetemp is not None, basetemp
+        self._basetemp = basetemp
+        self._trace("new basetemp", basetemp)
+        return basetemp
+
+
+def get_user() -> str | None:
+    """Return the current user name, or None if getuser() does not work
+    in the current environment (see #1010)."""
+    try:
+        # In some exotic environments, getpass may not be importable.
+        import getpass
+
+        return getpass.getuser()
+    except (ImportError, OSError, KeyError):
+        return None
+
+
+def pytest_configure(config: Config) -> None:
+    """Create a TempPathFactory and attach it to the config object.
+
+    This is to comply with existing plugins which expect the handler to be
+    available at pytest_configure time, but ideally should be moved entirely
+    to the tmp_path_factory session fixture.
+    """
+    mp = MonkeyPatch()
+    config.add_cleanup(mp.undo)
+    _tmp_path_factory = TempPathFactory.from_config(config, _ispytest=True)
+    mp.setattr(config, "_tmp_path_factory", _tmp_path_factory, raising=False)
+
+
+def pytest_addoption(parser: Parser) -> None:
+    parser.addini(
+        "tmp_path_retention_count",
+        help="How many sessions should we keep the `tmp_path` directories, according to `tmp_path_retention_policy`.",
+        default=3,
+    )
+
+    parser.addini(
+        "tmp_path_retention_policy",
+        help="Controls which directories created by the `tmp_path` fixture are kept around, based on test outcome. "
+        "(all/failed/none)",
+        default="all",
+    )
+
+
+@fixture(scope="session")
+def tmp_path_factory(request: FixtureRequest) -> TempPathFactory:
+    """Return a :class:`pytest.TempPathFactory` instance for the test session."""
+    # Set dynamically by pytest_configure() above.
+    return request.config._tmp_path_factory  # type: ignore
+
+
+def _mk_tmp(request: FixtureRequest, factory: TempPathFactory) -> Path:
+    name = request.node.name
+    name = re.sub(r"[\W]", "_", name)
+    MAXVAL = 30
+    name = name[:MAXVAL]
+    return factory.mktemp(name, numbered=True)
+
+
+@fixture
+def tmp_path(
+    request: FixtureRequest, tmp_path_factory: TempPathFactory
+) -> Generator[Path]:
+    """Return a temporary directory (as :class:`pathlib.Path` object)
+    which is unique to each test function invocation.
+    The temporary directory is created as a subdirectory
+    of the base temporary directory, with configurable retention,
+    as discussed in :ref:`temporary directory location and retention`.
+    """
+    path = _mk_tmp(request, tmp_path_factory)
+    yield path
+
+    # Remove the tmpdir if the policy is "failed" and the test passed.
+    tmp_path_factory: TempPathFactory = request.session.config._tmp_path_factory  # type: ignore
+    policy = tmp_path_factory._retention_policy
+    result_dict = request.node.stash[tmppath_result_key]
+
+    if policy == "failed" and result_dict.get("call", True):
+        # We do a "best effort" to remove files, but it might not be possible due to some leaked resource,
+        # permissions, etc, in which case we ignore it.
+        rmtree(path, ignore_errors=True)
+
+    del request.node.stash[tmppath_result_key]
+
+
+def pytest_sessionfinish(session, exitstatus: int | ExitCode):
+    """After each session, remove base directory if all the tests passed,
+    the policy is "failed", and the basetemp is not specified by a user.
+    """
+    tmp_path_factory: TempPathFactory = session.config._tmp_path_factory
+    basetemp = tmp_path_factory._basetemp
+    if basetemp is None:
+        return
+
+    policy = tmp_path_factory._retention_policy
+    if (
+        exitstatus == 0
+        and policy == "failed"
+        and tmp_path_factory._given_basetemp is None
+    ):
+        if basetemp.is_dir():
+            # We do a "best effort" to remove files, but it might not be possible due to some leaked resource,
+            # permissions, etc, in which case we ignore it.
+            rmtree(basetemp, ignore_errors=True)
+
+    # Remove dead symlinks.
+    if basetemp.is_dir():
+        cleanup_dead_symlinks(basetemp)
+
+
+@hookimpl(wrapper=True, tryfirst=True)
+def pytest_runtest_makereport(
+    item: Item, call
+) -> Generator[None, TestReport, TestReport]:
+    rep = yield
+    assert rep.when is not None
+    empty: dict[str, bool] = {}
+    item.stash.setdefault(tmppath_result_key, empty)[rep.when] = rep.passed
+    return rep

.venv/lib/python3.11/site-packages/_pytest/unittest.py

@@ -0,0 +1,435 @@
+# mypy: allow-untyped-defs
+"""Discover and run std-library "unittest" style tests."""
+
+from __future__ import annotations
+
+import inspect
+import sys
+import traceback
+import types
+from typing import Any
+from typing import Callable
+from typing import Generator
+from typing import Iterable
+from typing import Tuple
+from typing import Type
+from typing import TYPE_CHECKING
+from typing import Union
+
+import _pytest._code
+from _pytest.compat import is_async_function
+from _pytest.config import hookimpl
+from _pytest.fixtures import FixtureRequest
+from _pytest.nodes import Collector
+from _pytest.nodes import Item
+from _pytest.outcomes import exit
+from _pytest.outcomes import fail
+from _pytest.outcomes import skip
+from _pytest.outcomes import xfail
+from _pytest.python import Class
+from _pytest.python import Function
+from _pytest.python import Module
+from _pytest.runner import CallInfo
+import pytest
+
+
+if sys.version_info[:2] < (3, 11):
+    from exceptiongroup import ExceptionGroup
+
+if TYPE_CHECKING:
+    import unittest
+
+    import twisted.trial.unittest
+
+
+_SysExcInfoType = Union[
+    Tuple[Type[BaseException], BaseException, types.TracebackType],
+    Tuple[None, None, None],
+]
+
+
+def pytest_pycollect_makeitem(
+    collector: Module | Class, name: str, obj: object
+) -> UnitTestCase | None:
+    try:
+        # Has unittest been imported?
+        ut = sys.modules["unittest"]
+        # Is obj a subclass of unittest.TestCase?
+        # Type ignored because `ut` is an opaque module.
+        if not issubclass(obj, ut.TestCase):  # type: ignore
+            return None
+    except Exception:
+        return None
+    # Is obj a concrete class?
+    # Abstract classes can't be instantiated so no point collecting them.
+    if inspect.isabstract(obj):
+        return None
+    # Yes, so let's collect it.
+    return UnitTestCase.from_parent(collector, name=name, obj=obj)
+
+
+class UnitTestCase(Class):
+    # Marker for fixturemanger.getfixtureinfo()
+    # to declare that our children do not support funcargs.
+    nofuncargs = True
+
+    def newinstance(self):
+        # TestCase __init__ takes the method (test) name. The TestCase
+        # constructor treats the name "runTest" as a special no-op, so it can be
+        # used when a dummy instance is needed. While unittest.TestCase has a
+        # default, some subclasses omit the default (#9610), so always supply
+        # it.
+        return self.obj("runTest")
+
+    def collect(self) -> Iterable[Item | Collector]:
+        from unittest import TestLoader
+
+        cls = self.obj
+        if not getattr(cls, "__test__", True):
+            return
+
+        skipped = _is_skipped(cls)
+        if not skipped:
+            self._register_unittest_setup_method_fixture(cls)
+            self._register_unittest_setup_class_fixture(cls)
+            self._register_setup_class_fixture()
+
+        self.session._fixturemanager.parsefactories(self.newinstance(), self.nodeid)
+
+        loader = TestLoader()
+        foundsomething = False
+        for name in loader.getTestCaseNames(self.obj):
+            x = getattr(self.obj, name)
+            if not getattr(x, "__test__", True):
+                continue
+            yield TestCaseFunction.from_parent(self, name=name)
+            foundsomething = True
+
+        if not foundsomething:
+            runtest = getattr(self.obj, "runTest", None)
+            if runtest is not None:
+                ut = sys.modules.get("twisted.trial.unittest", None)
+                if ut is None or runtest != ut.TestCase.runTest:
+                    yield TestCaseFunction.from_parent(self, name="runTest")
+
+    def _register_unittest_setup_class_fixture(self, cls: type) -> None:
+        """Register an auto-use fixture to invoke setUpClass and
+        tearDownClass (#517)."""
+        setup = getattr(cls, "setUpClass", None)
+        teardown = getattr(cls, "tearDownClass", None)
+        if setup is None and teardown is None:
+            return None
+        cleanup = getattr(cls, "doClassCleanups", lambda: None)
+
+        def process_teardown_exceptions() -> None:
+            # tearDown_exceptions is a list set in the class containing exc_infos for errors during
+            # teardown for the class.
+            exc_infos = getattr(cls, "tearDown_exceptions", None)
+            if not exc_infos:
+                return
+            exceptions = [exc for (_, exc, _) in exc_infos]
+            # If a single exception, raise it directly as this provides a more readable
+            # error (hopefully this will improve in #12255).
+            if len(exceptions) == 1:
+                raise exceptions[0]
+            else:
+                raise ExceptionGroup("Unittest class cleanup errors", exceptions)
+
+        def unittest_setup_class_fixture(
+            request: FixtureRequest,
+        ) -> Generator[None]:
+            cls = request.cls
+            if _is_skipped(cls):
+                reason = cls.__unittest_skip_why__
+                raise pytest.skip.Exception(reason, _use_item_location=True)
+            if setup is not None:
+                try:
+                    setup()
+                # unittest does not call the cleanup function for every BaseException, so we
+                # follow this here.
+                except Exception:
+                    cleanup()
+                    process_teardown_exceptions()
+                    raise
+            yield
+            try:
+                if teardown is not None:
+                    teardown()
+            finally:
+                cleanup()
+                process_teardown_exceptions()
+
+        self.session._fixturemanager._register_fixture(
+            # Use a unique name to speed up lookup.
+            name=f"_unittest_setUpClass_fixture_{cls.__qualname__}",
+            func=unittest_setup_class_fixture,
+            nodeid=self.nodeid,
+            scope="class",
+            autouse=True,
+        )
+
+    def _register_unittest_setup_method_fixture(self, cls: type) -> None:
+        """Register an auto-use fixture to invoke setup_method and
+        teardown_method (#517)."""
+        setup = getattr(cls, "setup_method", None)
+        teardown = getattr(cls, "teardown_method", None)
+        if setup is None and teardown is None:
+            return None
+
+        def unittest_setup_method_fixture(
+            request: FixtureRequest,
+        ) -> Generator[None]:
+            self = request.instance
+            if _is_skipped(self):
+                reason = self.__unittest_skip_why__
+                raise pytest.skip.Exception(reason, _use_item_location=True)
+            if setup is not None:
+                setup(self, request.function)
+            yield
+            if teardown is not None:
+                teardown(self, request.function)
+
+        self.session._fixturemanager._register_fixture(
+            # Use a unique name to speed up lookup.
+            name=f"_unittest_setup_method_fixture_{cls.__qualname__}",
+            func=unittest_setup_method_fixture,
+            nodeid=self.nodeid,
+            scope="function",
+            autouse=True,
+        )
+
+
+class TestCaseFunction(Function):
+    nofuncargs = True
+    _excinfo: list[_pytest._code.ExceptionInfo[BaseException]] | None = None
+
+    def _getinstance(self):
+        assert isinstance(self.parent, UnitTestCase)
+        return self.parent.obj(self.name)
+
+    # Backward compat for pytest-django; can be removed after pytest-django
+    # updates + some slack.
+    @property
+    def _testcase(self):
+        return self.instance
+
+    def setup(self) -> None:
+        # A bound method to be called during teardown() if set (see 'runtest()').
+        self._explicit_tearDown: Callable[[], None] | None = None
+        super().setup()
+
+    def teardown(self) -> None:
+        if self._explicit_tearDown is not None:
+            self._explicit_tearDown()
+            self._explicit_tearDown = None
+        self._obj = None
+        del self._instance
+        super().teardown()
+
+    def startTest(self, testcase: unittest.TestCase) -> None:
+        pass
+
+    def _addexcinfo(self, rawexcinfo: _SysExcInfoType) -> None:
+        # Unwrap potential exception info (see twisted trial support below).
+        rawexcinfo = getattr(rawexcinfo, "_rawexcinfo", rawexcinfo)
+        try:
+            excinfo = _pytest._code.ExceptionInfo[BaseException].from_exc_info(
+                rawexcinfo  # type: ignore[arg-type]
+            )
+            # Invoke the attributes to trigger storing the traceback
+            # trial causes some issue there.
+            _ = excinfo.value
+            _ = excinfo.traceback
+        except TypeError:
+            try:
+                try:
+                    values = traceback.format_exception(*rawexcinfo)
+                    values.insert(
+                        0,
+                        "NOTE: Incompatible Exception Representation, "
+                        "displaying natively:\n\n",
+                    )
+                    fail("".join(values), pytrace=False)
+                except (fail.Exception, KeyboardInterrupt):
+                    raise
+                except BaseException:
+                    fail(
+                        "ERROR: Unknown Incompatible Exception "
+                        f"representation:\n{rawexcinfo!r}",
+                        pytrace=False,
+                    )
+            except KeyboardInterrupt:
+                raise
+            except fail.Exception:
+                excinfo = _pytest._code.ExceptionInfo.from_current()
+        self.__dict__.setdefault("_excinfo", []).append(excinfo)
+
+    def addError(
+        self, testcase: unittest.TestCase, rawexcinfo: _SysExcInfoType
+    ) -> None:
+        try:
+            if isinstance(rawexcinfo[1], exit.Exception):
+                exit(rawexcinfo[1].msg)
+        except TypeError:
+            pass
+        self._addexcinfo(rawexcinfo)
+
+    def addFailure(
+        self, testcase: unittest.TestCase, rawexcinfo: _SysExcInfoType
+    ) -> None:
+        self._addexcinfo(rawexcinfo)
+
+    def addSkip(self, testcase: unittest.TestCase, reason: str) -> None:
+        try:
+            raise pytest.skip.Exception(reason, _use_item_location=True)
+        except skip.Exception:
+            self._addexcinfo(sys.exc_info())
+
+    def addExpectedFailure(
+        self,
+        testcase: unittest.TestCase,
+        rawexcinfo: _SysExcInfoType,
+        reason: str = "",
+    ) -> None:
+        try:
+            xfail(str(reason))
+        except xfail.Exception:
+            self._addexcinfo(sys.exc_info())
+
+    def addUnexpectedSuccess(
+        self,
+        testcase: unittest.TestCase,
+        reason: twisted.trial.unittest.Todo | None = None,
+    ) -> None:
+        msg = "Unexpected success"
+        if reason:
+            msg += f": {reason.reason}"
+        # Preserve unittest behaviour - fail the test. Explicitly not an XPASS.
+        try:
+            fail(msg, pytrace=False)
+        except fail.Exception:
+            self._addexcinfo(sys.exc_info())
+
+    def addSuccess(self, testcase: unittest.TestCase) -> None:
+        pass
+
+    def stopTest(self, testcase: unittest.TestCase) -> None:
+        pass
+
+    def addDuration(self, testcase: unittest.TestCase, elapsed: float) -> None:
+        pass
+
+    def runtest(self) -> None:
+        from _pytest.debugging import maybe_wrap_pytest_function_for_tracing
+
+        testcase = self.instance
+        assert testcase is not None
+
+        maybe_wrap_pytest_function_for_tracing(self)
+
+        # Let the unittest framework handle async functions.
+        if is_async_function(self.obj):
+            testcase(result=self)
+        else:
+            # When --pdb is given, we want to postpone calling tearDown() otherwise
+            # when entering the pdb prompt, tearDown() would have probably cleaned up
+            # instance variables, which makes it difficult to debug.
+            # Arguably we could always postpone tearDown(), but this changes the moment where the
+            # TestCase instance interacts with the results object, so better to only do it
+            # when absolutely needed.
+            # We need to consider if the test itself is skipped, or the whole class.
+            assert isinstance(self.parent, UnitTestCase)
+            skipped = _is_skipped(self.obj) or _is_skipped(self.parent.obj)
+            if self.config.getoption("usepdb") and not skipped:
+                self._explicit_tearDown = testcase.tearDown
+                setattr(testcase, "tearDown", lambda *args: None)
+
+            # We need to update the actual bound method with self.obj, because
+            # wrap_pytest_function_for_tracing replaces self.obj by a wrapper.
+            setattr(testcase, self.name, self.obj)
+            try:
+                testcase(result=self)
+            finally:
+                delattr(testcase, self.name)
+
+    def _traceback_filter(
+        self, excinfo: _pytest._code.ExceptionInfo[BaseException]
+    ) -> _pytest._code.Traceback:
+        traceback = super()._traceback_filter(excinfo)
+        ntraceback = traceback.filter(
+            lambda x: not x.frame.f_globals.get("__unittest"),
+        )
+        if not ntraceback:
+            ntraceback = traceback
+        return ntraceback
+
+
+@hookimpl(tryfirst=True)
+def pytest_runtest_makereport(item: Item, call: CallInfo[None]) -> None:
+    if isinstance(item, TestCaseFunction):
+        if item._excinfo:
+            call.excinfo = item._excinfo.pop(0)
+            try:
+                del call.result
+            except AttributeError:
+                pass
+
+    # Convert unittest.SkipTest to pytest.skip.
+    # This is actually only needed for nose, which reuses unittest.SkipTest for
+    # its own nose.SkipTest. For unittest TestCases, SkipTest is already
+    # handled internally, and doesn't reach here.
+    unittest = sys.modules.get("unittest")
+    if unittest and call.excinfo and isinstance(call.excinfo.value, unittest.SkipTest):
+        excinfo = call.excinfo
+        call2 = CallInfo[None].from_call(
+            lambda: pytest.skip(str(excinfo.value)), call.when
+        )
+        call.excinfo = call2.excinfo
+
+
+# Twisted trial support.
+classImplements_has_run = False
+
+
+@hookimpl(wrapper=True)
+def pytest_runtest_protocol(item: Item) -> Generator[None, object, object]:
+    if isinstance(item, TestCaseFunction) and "twisted.trial.unittest" in sys.modules:
+        ut: Any = sys.modules["twisted.python.failure"]
+        global classImplements_has_run
+        Failure__init__ = ut.Failure.__init__
+        if not classImplements_has_run:
+            from twisted.trial.itrial import IReporter
+            from zope.interface import classImplements
+
+            classImplements(TestCaseFunction, IReporter)
+            classImplements_has_run = True
+
+        def excstore(
+            self, exc_value=None, exc_type=None, exc_tb=None, captureVars=None
+        ):
+            if exc_value is None:
+                self._rawexcinfo = sys.exc_info()
+            else:
+                if exc_type is None:
+                    exc_type = type(exc_value)
+                self._rawexcinfo = (exc_type, exc_value, exc_tb)
+            try:
+                Failure__init__(
+                    self, exc_value, exc_type, exc_tb, captureVars=captureVars
+                )
+            except TypeError:
+                Failure__init__(self, exc_value, exc_type, exc_tb)
+
+        ut.Failure.__init__ = excstore
+        try:
+            res = yield
+        finally:
+            ut.Failure.__init__ = Failure__init__
+    else:
+        res = yield
+    return res
+
+
+def _is_skipped(obj) -> bool:
+    """Return True if the given object has been marked with @unittest.skip."""
+    return bool(getattr(obj, "__unittest_skip__", False))

.venv/lib/python3.11/site-packages/cpuinfo/__init__.py

@@ -0,0 +1,5 @@
+
+import sys
+from cpuinfo.cpuinfo import *
+
+

.venv/lib/python3.11/site-packages/outlines_core-0.1.26.dist-info/INSTALLER

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

.venv/lib/python3.11/site-packages/outlines_core-0.1.26.dist-info/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2023- The Outlines developers
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

.venv/lib/python3.11/site-packages/outlines_core-0.1.26.dist-info/METADATA

@@ -0,0 +1,124 @@
+Metadata-Version: 2.1
+Name: outlines_core
+Version: 0.1.26
+Summary: Structured Text Generation in Rust
+Author: Outlines Developers
+License: Apache-2.0
+Project-URL: homepage, https://github.com/dottxt-ai/outlines-core
+Project-URL: documentation, https://dottxt-ai.github.io/outlines-core/
+Project-URL: repository, https://github.com/dottxt-ai/outlines-core
+Keywords: machine learning,deep learning,language models,structured generation
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Information Technology
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: interegular
+Requires-Dist: jsonschema
+Provides-Extra: test
+Requires-Dist: pre-commit; extra == "test"
+Requires-Dist: pydantic; extra == "test"
+Requires-Dist: pytest; extra == "test"
+Requires-Dist: pytest-benchmark; extra == "test"
+Requires-Dist: pytest-cov; extra == "test"
+Requires-Dist: pytest-mock; extra == "test"
+Requires-Dist: coverage[toml]>=5.1; extra == "test"
+Requires-Dist: diff-cover; extra == "test"
+Requires-Dist: accelerate; extra == "test"
+Requires-Dist: beartype<0.16.0; extra == "test"
+Requires-Dist: huggingface_hub; extra == "test"
+Requires-Dist: torch; extra == "test"
+Requires-Dist: numpy; extra == "test"
+Requires-Dist: scipy; extra == "test"
+Requires-Dist: transformers; extra == "test"
+Requires-Dist: datasets; extra == "test"
+Requires-Dist: pillow; extra == "test"
+Requires-Dist: asv; extra == "test"
+Requires-Dist: psutil; extra == "test"
+Requires-Dist: setuptools-rust; extra == "test"
+
+<div align="center" style="margin-bottom: 1em;">
+
+<img src="./docs/assets/images/logo.png" alt="Outlines-core Logo" width=500></img>
+
+[![Contributors][contributors-badge]][contributors]
+
+*Structured generation (in Rust).*
+</div>
+
+This package provides the core functionality for structured generation, formerly implemented in [Outlines][outlines], with a focus on performance and portability.
+
+# Install
+
+We provide bindings to the following languages:
+- [Rust][rust-implementation] (Original implementation)
+- [Python][python-bindings]
+
+The latest release of the Python bindings is available on PyPi using `pip`:
+
+``` python
+pip install outlines-core
+```
+
+The current development branch of `outlines-core` can be installed from GitHub, also using `pip`:
+
+``` shell
+pip install git+https://github.com/outlines-dev/outlines-core
+```
+
+Or install in a rust project with cargo:
+``` bash
+cargo add outlines-core
+```
+
+# How to contribute?
+
+## Setup
+
+First, fork the repository on GitHub and clone the fork locally:
+
+```bash
+git clone git@github.com/YourUserName/outlines-core.git
+cd outlines-core
+```
+
+Create a new virtual environment:
+
+``` bash
+python -m venv .venv
+source .venv/bin/activate
+```
+
+Then install the dependencies in editable mode, and install the pre-commit hooks:
+
+``` bash
+pip install -e ".[test]"
+pre-commit install
+```
+
+## Before pushing your code
+
+Run the tests:
+
+
+``` bash
+pytest
+```
+
+And run the code style checks:
+
+``` bash
+pre-commit run --all-files
+```
+
+
+[outlines]: https://github.com/dottxt-ai/outlines
+[contributors]: https://github.com/outlines-dev/outlines-core/graphs/contributors
+[contributors-badge]: https://img.shields.io/github/contributors/outlines-dev/outlines-core?style=flat-square&logo=github&logoColor=white&color=ECEFF4
+[rust-implementation]: https://github.com/outlines-dev/outlines-core/tree/readme/src
+[python-bindings]: https://github.com/outlines-dev/outlines-core/tree/readme/python/outlines_core

.venv/lib/python3.11/site-packages/outlines_core-0.1.26.dist-info/RECORD

@@ -0,0 +1,21 @@
+outlines_core-0.1.26.dist-info/INSTALLER,sha256=zuuue4knoyJ-UwPPXg8fezS7VCrXJQrAP7zeNuwvFQg,4
+outlines_core-0.1.26.dist-info/LICENSE,sha256=9xB47oqqPVZwSIdW8Zk7neOuZMlUagIy67vdWVxTddc,11354
+outlines_core-0.1.26.dist-info/METADATA,sha256=YNmRZrAWCy_JWcTTuWsTzD9qZu-Wdm5J8JTTolLRigM,3761
+outlines_core-0.1.26.dist-info/RECORD,,
+outlines_core-0.1.26.dist-info/WHEEL,sha256=9BFfIe-Zq441iQ0ehutX65O5faGDpmB1Uw3WaQGk4f0,151
+outlines_core-0.1.26.dist-info/top_level.txt,sha256=45vDiTQKP-oMzuyEv9_QNERQrpBud0CXZ1BDiFJjyV4,14
+outlines_core/__init__.py,sha256=U-Sz4BgH-fmII5vv_AL_qSp2a2mLd6g6aHbEfnUPmKU,208
+outlines_core/__pycache__/__init__.cpython-311.pyc,,
+outlines_core/__pycache__/_version.cpython-311.pyc,,
+outlines_core/_version.py,sha256=pHptU6h1OxA8-tsynXa5Rz3N6XELevZ_27Ye-N1R-ds,413
+outlines_core/fsm/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+outlines_core/fsm/__pycache__/__init__.cpython-311.pyc,,
+outlines_core/fsm/__pycache__/guide.cpython-311.pyc,,
+outlines_core/fsm/__pycache__/json_schema.cpython-311.pyc,,
+outlines_core/fsm/__pycache__/regex.cpython-311.pyc,,
+outlines_core/fsm/guide.py,sha256=PujEqMU_UgYHBfOmWsAvVbdEb1HeniffGHQj61ZtCBE,9584
+outlines_core/fsm/json_schema.py,sha256=nXgIMF6uVI7sYqy9b1kJOChFfNutvbmvwmOgFbHcnl0,230
+outlines_core/fsm/outlines_core_rs.cpython-311-x86_64-linux-gnu.so,sha256=O3cV_9q1Ah16BFzf7g2xbNTxx7H8P6gbW8P9yt8QQ98,686792
+outlines_core/fsm/outlines_core_rs.pyi,sha256=1pvCFg3KDIDySgwhyzC4-r7tljU-DoWVr-AWs5KuhM0,2917
+outlines_core/fsm/regex.py,sha256=jw4pOwLhXXVlErnN6QUN56F6_nmPp8ATIDN-e3cl1y8,17243
+outlines_core/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0

.venv/lib/python3.11/site-packages/outlines_core-0.1.26.dist-info/WHEEL

@@ -0,0 +1,6 @@
+Wheel-Version: 1.0
+Generator: setuptools (75.6.0)
+Root-Is-Purelib: false
+Tag: cp311-cp311-manylinux_2_17_x86_64
+Tag: cp311-cp311-manylinux2014_x86_64
+

.venv/lib/python3.11/site-packages/outlines_core-0.1.26.dist-info/top_level.txt

@@ -0,0 +1 @@
+outlines_core

.venv/lib/python3.11/site-packages/ray/cloudpickle/__init__.py

@@ -0,0 +1,47 @@
+from __future__ import absolute_import
+
+import os
+from pickle import PicklingError
+
+from ray.cloudpickle.cloudpickle import *  # noqa
+from ray.cloudpickle.cloudpickle_fast import CloudPickler, dumps, dump  # noqa
+
+
+# Conform to the convention used by python serialization libraries, which
+# expose their Pickler subclass at top-level under the  "Pickler" name.
+Pickler = CloudPickler
+
+__version__ = '2.0.0'
+
+
+def _warn_msg(obj, method, exc):
+    return (
+        f"{method}({str(obj)}) failed."
+        "\nTo check which non-serializable variables are captured "
+        "in scope, re-run the ray script with 'RAY_PICKLE_VERBOSE_DEBUG=1'.")
+
+
+def dump_debug(obj, *args, **kwargs):
+    try:
+        return dump(obj, *args, **kwargs)
+    except (TypeError, PicklingError) as exc:
+        if os.environ.get("RAY_PICKLE_VERBOSE_DEBUG"):
+            from ray.util.check_serialize import inspect_serializability
+            inspect_serializability(obj)
+            raise
+        else:
+            msg = _warn_msg(obj, "ray.cloudpickle.dump", exc)
+            raise type(exc)(msg)
+
+
+def dumps_debug(obj, *args, **kwargs):
+    try:
+        return dumps(obj, *args, **kwargs)
+    except (TypeError, PicklingError) as exc:
+        if os.environ.get("RAY_PICKLE_VERBOSE_DEBUG"):
+            from ray.util.check_serialize import inspect_serializability
+            inspect_serializability(obj)
+            raise
+        else:
+            msg = _warn_msg(obj, "ray.cloudpickle.dumps", exc)
+            raise type(exc)(msg)

.venv/lib/python3.11/site-packages/ray/cloudpickle/cloudpickle.py

@@ -0,0 +1,1487 @@
+"""Pickler class to extend the standard pickle.Pickler functionality
+
+The main objective is to make it natural to perform distributed computing on
+clusters (such as PySpark, Dask, Ray...) with interactively defined code
+(functions, classes, ...) written in notebooks or console.
+
+In particular this pickler adds the following features:
+- serialize interactively-defined or locally-defined functions, classes,
+  enums, typevars, lambdas and nested functions to compiled byte code;
+- deal with some other non-serializable objects in an ad-hoc manner where
+  applicable.
+
+This pickler is therefore meant to be used for the communication between short
+lived Python processes running the same version of Python and libraries. In
+particular, it is not meant to be used for long term storage of Python objects.
+
+It does not include an unpickler, as standard Python unpickling suffices.
+
+This module was extracted from the `cloud` package, developed by `PiCloud, Inc.
+<https://web.archive.org/web/20140626004012/http://www.picloud.com/>`_.
+
+Copyright (c) 2012-now, CloudPickle developers and contributors.
+Copyright (c) 2012, Regents of the University of California.
+Copyright (c) 2009 `PiCloud, Inc. <https://web.archive.org/web/20140626004012/http://www.picloud.com/>`_.
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions
+are met:
+    * Redistributions of source code must retain the above copyright
+      notice, this list of conditions and the following disclaimer.
+    * Redistributions in binary form must reproduce the above copyright
+      notice, this list of conditions and the following disclaimer in the
+      documentation and/or other materials provided with the distribution.
+    * Neither the name of the University of California, Berkeley nor the
+      names of its contributors may be used to endorse or promote
+      products derived from this software without specific prior written
+      permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED
+TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
+PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
+LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
+NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+"""
+
+import _collections_abc
+from collections import ChainMap, OrderedDict
+import abc
+import builtins
+import copyreg
+import dataclasses
+import dis
+from enum import Enum
+import io
+import itertools
+import logging
+import opcode
+import pickle
+from pickle import _getattribute
+import platform
+import struct
+import sys
+import threading
+import types
+import typing
+import uuid
+import warnings
+import weakref
+
+# The following import is required to be imported in the cloudpickle
+# namespace to be able to load pickle files generated with older versions of
+# cloudpickle. See: tests/test_backward_compat.py
+from types import CellType  # noqa: F401
+
+
+# cloudpickle is meant for inter process communication: we expect all
+# communicating processes to run the same Python version hence we favor
+# communication speed over compatibility:
+DEFAULT_PROTOCOL = pickle.HIGHEST_PROTOCOL
+
+# Names of modules whose resources should be treated as dynamic.
+_PICKLE_BY_VALUE_MODULES = set()
+
+# Track the provenance of reconstructed dynamic classes to make it possible to
+# reconstruct instances from the matching singleton class definition when
+# appropriate and preserve the usual "isinstance" semantics of Python objects.
+_DYNAMIC_CLASS_TRACKER_BY_CLASS = weakref.WeakKeyDictionary()
+_DYNAMIC_CLASS_TRACKER_BY_ID = weakref.WeakValueDictionary()
+_DYNAMIC_CLASS_TRACKER_LOCK = threading.Lock()
+
+PYPY = platform.python_implementation() == "PyPy"
+
+builtin_code_type = None
+if PYPY:
+    # builtin-code objects only exist in pypy
+    builtin_code_type = type(float.__new__.__code__)
+
+_extract_code_globals_cache = weakref.WeakKeyDictionary()
+
+
+def _get_or_create_tracker_id(class_def):
+    with _DYNAMIC_CLASS_TRACKER_LOCK:
+        class_tracker_id = _DYNAMIC_CLASS_TRACKER_BY_CLASS.get(class_def)
+        if class_tracker_id is None:
+            class_tracker_id = uuid.uuid4().hex
+            _DYNAMIC_CLASS_TRACKER_BY_CLASS[class_def] = class_tracker_id
+            _DYNAMIC_CLASS_TRACKER_BY_ID[class_tracker_id] = class_def
+    return class_tracker_id
+
+
+def _lookup_class_or_track(class_tracker_id, class_def):
+    if class_tracker_id is not None:
+        with _DYNAMIC_CLASS_TRACKER_LOCK:
+            class_def = _DYNAMIC_CLASS_TRACKER_BY_ID.setdefault(
+                class_tracker_id, class_def
+            )
+            _DYNAMIC_CLASS_TRACKER_BY_CLASS[class_def] = class_tracker_id
+    return class_def
+
+
+def register_pickle_by_value(module):
+    """Register a module to make it functions and classes picklable by value.
+
+    By default, functions and classes that are attributes of an importable
+    module are to be pickled by reference, that is relying on re-importing
+    the attribute from the module at load time.
+
+    If `register_pickle_by_value(module)` is called, all its functions and
+    classes are subsequently to be pickled by value, meaning that they can
+    be loaded in Python processes where the module is not importable.
+
+    This is especially useful when developing a module in a distributed
+    execution environment: restarting the client Python process with the new
+    source code is enough: there is no need to re-install the new version
+    of the module on all the worker nodes nor to restart the workers.
+
+    Note: this feature is considered experimental. See the cloudpickle
+    README.md file for more details and limitations.
+    """
+    if not isinstance(module, types.ModuleType):
+        raise ValueError(f"Input should be a module object, got {str(module)} instead")
+    # In the future, cloudpickle may need a way to access any module registered
+    # for pickling by value in order to introspect relative imports inside
+    # functions pickled by value. (see
+    # https://github.com/cloudpipe/cloudpickle/pull/417#issuecomment-873684633).
+    # This access can be ensured by checking that module is present in
+    # sys.modules at registering time and assuming that it will still be in
+    # there when accessed during pickling. Another alternative would be to
+    # store a weakref to the module. Even though cloudpickle does not implement
+    # this introspection yet, in order to avoid a possible breaking change
+    # later, we still enforce the presence of module inside sys.modules.
+    if module.__name__ not in sys.modules:
+        raise ValueError(
+            f"{module} was not imported correctly, have you used an "
+            "`import` statement to access it?"
+        )
+    _PICKLE_BY_VALUE_MODULES.add(module.__name__)
+
+
+def unregister_pickle_by_value(module):
+    """Unregister that the input module should be pickled by value."""
+    if not isinstance(module, types.ModuleType):
+        raise ValueError(f"Input should be a module object, got {str(module)} instead")
+    if module.__name__ not in _PICKLE_BY_VALUE_MODULES:
+        raise ValueError(f"{module} is not registered for pickle by value")
+    else:
+        _PICKLE_BY_VALUE_MODULES.remove(module.__name__)
+
+
+def list_registry_pickle_by_value():
+    return _PICKLE_BY_VALUE_MODULES.copy()
+
+
+def _is_registered_pickle_by_value(module):
+    module_name = module.__name__
+    if module_name in _PICKLE_BY_VALUE_MODULES:
+        return True
+    while True:
+        parent_name = module_name.rsplit(".", 1)[0]
+        if parent_name == module_name:
+            break
+        if parent_name in _PICKLE_BY_VALUE_MODULES:
+            return True
+        module_name = parent_name
+    return False
+
+
+def _whichmodule(obj, name):
+    """Find the module an object belongs to.
+
+    This function differs from ``pickle.whichmodule`` in two ways:
+    - it does not mangle the cases where obj's module is __main__ and obj was
+      not found in any module.
+    - Errors arising during module introspection are ignored, as those errors
+      are considered unwanted side effects.
+    """
+    module_name = getattr(obj, "__module__", None)
+
+    if module_name is not None:
+        return module_name
+    # Protect the iteration by using a copy of sys.modules against dynamic
+    # modules that trigger imports of other modules upon calls to getattr or
+    # other threads importing at the same time.
+    for module_name, module in sys.modules.copy().items():
+        # Some modules such as coverage can inject non-module objects inside
+        # sys.modules
+        if (
+            module_name == "__main__"
+            or module is None
+            or not isinstance(module, types.ModuleType)
+        ):
+            continue
+        try:
+            if _getattribute(module, name)[0] is obj:
+                return module_name
+        except Exception:
+            pass
+    return None
+
+
+def _should_pickle_by_reference(obj, name=None):
+    """Test whether an function or a class should be pickled by reference
+
+    Pickling by reference means by that the object (typically a function or a
+    class) is an attribute of a module that is assumed to be importable in the
+    target Python environment. Loading will therefore rely on importing the
+    module and then calling `getattr` on it to access the function or class.
+
+    Pickling by reference is the only option to pickle functions and classes
+    in the standard library. In cloudpickle the alternative option is to
+    pickle by value (for instance for interactively or locally defined
+    functions and classes or for attributes of modules that have been
+    explicitly registered to be pickled by value.
+    """
+    if isinstance(obj, types.FunctionType) or issubclass(type(obj), type):
+        module_and_name = _lookup_module_and_qualname(obj, name=name)
+        if module_and_name is None:
+            return False
+        module, name = module_and_name
+        return not _is_registered_pickle_by_value(module)
+
+    elif isinstance(obj, types.ModuleType):
+        # We assume that sys.modules is primarily used as a cache mechanism for
+        # the Python import machinery. Checking if a module has been added in
+        # is sys.modules therefore a cheap and simple heuristic to tell us
+        # whether we can assume that a given module could be imported by name
+        # in another Python process.
+        if _is_registered_pickle_by_value(obj):
+            return False
+        return obj.__name__ in sys.modules
+    else:
+        raise TypeError(
+            "cannot check importability of {} instances".format(type(obj).__name__)
+        )
+
+
+def _lookup_module_and_qualname(obj, name=None):
+    if name is None:
+        name = getattr(obj, "__qualname__", None)
+    if name is None:  # pragma: no cover
+        # This used to be needed for Python 2.7 support but is probably not
+        # needed anymore. However we keep the __name__ introspection in case
+        # users of cloudpickle rely on this old behavior for unknown reasons.
+        name = getattr(obj, "__name__", None)
+
+    module_name = _whichmodule(obj, name)
+
+    if module_name is None:
+        # In this case, obj.__module__ is None AND obj was not found in any
+        # imported module. obj is thus treated as dynamic.
+        return None
+
+    if module_name == "__main__":
+        return None
+
+    # Note: if module_name is in sys.modules, the corresponding module is
+    # assumed importable at unpickling time. See #357
+    module = sys.modules.get(module_name, None)
+    if module is None:
+        # The main reason why obj's module would not be imported is that this
+        # module has been dynamically created, using for example
+        # types.ModuleType. The other possibility is that module was removed
+        # from sys.modules after obj was created/imported. But this case is not
+        # supported, as the standard pickle does not support it either.
+        return None
+
+    try:
+        obj2, parent = _getattribute(module, name)
+    except AttributeError:
+        # obj was not found inside the module it points to
+        return None
+    if obj2 is not obj:
+        return None
+    return module, name
+
+
+def _extract_code_globals(co):
+    """Find all globals names read or written to by codeblock co."""
+    out_names = _extract_code_globals_cache.get(co)
+    if out_names is None:
+        # We use a dict with None values instead of a set to get a
+        # deterministic order and avoid introducing non-deterministic pickle
+        # bytes as a results.
+        out_names = {name: None for name in _walk_global_ops(co)}
+
+        # Declaring a function inside another one using the "def ..." syntax
+        # generates a constant code object corresponding to the one of the
+        # nested function's As the nested function may itself need global
+        # variables, we need to introspect its code, extract its globals, (look
+        # for code object in it's co_consts attribute..) and add the result to
+        # code_globals
+        if co.co_consts:
+            for const in co.co_consts:
+                if isinstance(const, types.CodeType):
+                    out_names.update(_extract_code_globals(const))
+
+        _extract_code_globals_cache[co] = out_names
+
+    return out_names
+
+
+def _find_imported_submodules(code, top_level_dependencies):
+    """Find currently imported submodules used by a function.
+
+    Submodules used by a function need to be detected and referenced for the
+    function to work correctly at depickling time. Because submodules can be
+    referenced as attribute of their parent package (``package.submodule``), we
+    need a special introspection technique that does not rely on GLOBAL-related
+    opcodes to find references of them in a code object.
+
+    Example:
+    ```
+    import concurrent.futures
+    import cloudpickle
+    def func():
+        x = concurrent.futures.ThreadPoolExecutor
+    if __name__ == '__main__':
+        cloudpickle.dumps(func)
+    ```
+    The globals extracted by cloudpickle in the function's state include the
+    concurrent package, but not its submodule (here, concurrent.futures), which
+    is the module used by func. Find_imported_submodules will detect the usage
+    of concurrent.futures. Saving this module alongside with func will ensure
+    that calling func once depickled does not fail due to concurrent.futures
+    not being imported
+    """
+
+    subimports = []
+    # check if any known dependency is an imported package
+    for x in top_level_dependencies:
+        if (
+            isinstance(x, types.ModuleType)
+            and hasattr(x, "__package__")
+            and x.__package__
+        ):
+            # check if the package has any currently loaded sub-imports
+            prefix = x.__name__ + "."
+            # A concurrent thread could mutate sys.modules,
+            # make sure we iterate over a copy to avoid exceptions
+            for name in list(sys.modules):
+                # Older versions of pytest will add a "None" module to
+                # sys.modules.
+                if name is not None and name.startswith(prefix):
+                    # check whether the function can address the sub-module
+                    tokens = set(name[len(prefix) :].split("."))
+                    if not tokens - set(code.co_names):
+                        subimports.append(sys.modules[name])
+    return subimports
+
+
+# relevant opcodes
+STORE_GLOBAL = opcode.opmap["STORE_GLOBAL"]
+DELETE_GLOBAL = opcode.opmap["DELETE_GLOBAL"]
+LOAD_GLOBAL = opcode.opmap["LOAD_GLOBAL"]
+GLOBAL_OPS = (STORE_GLOBAL, DELETE_GLOBAL, LOAD_GLOBAL)
+HAVE_ARGUMENT = dis.HAVE_ARGUMENT
+EXTENDED_ARG = dis.EXTENDED_ARG
+
+
+_BUILTIN_TYPE_NAMES = {}
+for k, v in types.__dict__.items():
+    if type(v) is type:
+        _BUILTIN_TYPE_NAMES[v] = k
+
+
+def _builtin_type(name):
+    if name == "ClassType":  # pragma: no cover
+        # Backward compat to load pickle files generated with cloudpickle
+        # < 1.3 even if loading pickle files from older versions is not
+        # officially supported.
+        return type
+    return getattr(types, name)
+
+
+def _walk_global_ops(code):
+    """Yield referenced name for global-referencing instructions in code."""
+    for instr in dis.get_instructions(code):
+        op = instr.opcode
+        if op in GLOBAL_OPS:
+            yield instr.argval
+
+
+def _extract_class_dict(cls):
+    """Retrieve a copy of the dict of a class without the inherited method."""
+    clsdict = dict(cls.__dict__)  # copy dict proxy to a dict
+    if len(cls.__bases__) == 1:
+        inherited_dict = cls.__bases__[0].__dict__
+    else:
+        inherited_dict = {}
+        for base in reversed(cls.__bases__):
+            inherited_dict.update(base.__dict__)
+    to_remove = []
+    for name, value in clsdict.items():
+        try:
+            base_value = inherited_dict[name]
+            if value is base_value:
+                to_remove.append(name)
+        except KeyError:
+            pass
+    for name in to_remove:
+        clsdict.pop(name)
+    return clsdict
+
+
+def is_tornado_coroutine(func):
+    """Return whether `func` is a Tornado coroutine function.
+
+    Running coroutines are not supported.
+    """
+    warnings.warn(
+        "is_tornado_coroutine is deprecated in cloudpickle 3.0 and will be "
+        "removed in cloudpickle 4.0. Use tornado.gen.is_coroutine_function "
+        "directly instead.",
+        category=DeprecationWarning,
+    )
+    if "tornado.gen" not in sys.modules:
+        return False
+    gen = sys.modules["tornado.gen"]
+    if not hasattr(gen, "is_coroutine_function"):
+        # Tornado version is too old
+        return False
+    return gen.is_coroutine_function(func)
+
+
+def subimport(name):
+    # We cannot do simply: `return __import__(name)`: Indeed, if ``name`` is
+    # the name of a submodule, __import__ will return the top-level root module
+    # of this submodule. For instance, __import__('os.path') returns the `os`
+    # module.
+    __import__(name)
+    return sys.modules[name]
+
+
+def dynamic_subimport(name, vars):
+    mod = types.ModuleType(name)
+    mod.__dict__.update(vars)
+    mod.__dict__["__builtins__"] = builtins.__dict__
+    return mod
+
+
+def _get_cell_contents(cell):
+    try:
+        return cell.cell_contents
+    except ValueError:
+        # Handle empty cells explicitly with a sentinel value.
+        return _empty_cell_value
+
+
+def instance(cls):
+    """Create a new instance of a class.
+
+    Parameters
+    ----------
+    cls : type
+        The class to create an instance of.
+
+    Returns
+    -------
+    instance : cls
+        A new instance of ``cls``.
+    """
+    return cls()
+
+
+@instance
+class _empty_cell_value:
+    """Sentinel for empty closures."""
+
+    @classmethod
+    def __reduce__(cls):
+        return cls.__name__
+
+
+def _make_function(code, globals, name, argdefs, closure):
+    # Setting __builtins__ in globals is needed for nogil CPython.
+    globals["__builtins__"] = __builtins__
+    return types.FunctionType(code, globals, name, argdefs, closure)
+
+
+def _make_empty_cell():
+    if False:
+        # trick the compiler into creating an empty cell in our lambda
+        cell = None
+        raise AssertionError("this route should not be executed")
+
+    return (lambda: cell).__closure__[0]
+
+
+def _make_cell(value=_empty_cell_value):
+    cell = _make_empty_cell()
+    if value is not _empty_cell_value:
+        cell.cell_contents = value
+    return cell
+
+
+def _make_skeleton_class(
+    type_constructor, name, bases, type_kwargs, class_tracker_id, extra
+):
+    """Build dynamic class with an empty __dict__ to be filled once memoized
+
+    If class_tracker_id is not None, try to lookup an existing class definition
+    matching that id. If none is found, track a newly reconstructed class
+    definition under that id so that other instances stemming from the same
+    class id will also reuse this class definition.
+
+    The "extra" variable is meant to be a dict (or None) that can be used for
+    forward compatibility shall the need arise.
+    """
+    skeleton_class = types.new_class(
+        name, bases, {"metaclass": type_constructor}, lambda ns: ns.update(type_kwargs)
+    )
+    return _lookup_class_or_track(class_tracker_id, skeleton_class)
+
+
+def _make_skeleton_enum(
+    bases, name, qualname, members, module, class_tracker_id, extra
+):
+    """Build dynamic enum with an empty __dict__ to be filled once memoized
+
+    The creation of the enum class is inspired by the code of
+    EnumMeta._create_.
+
+    If class_tracker_id is not None, try to lookup an existing enum definition
+    matching that id. If none is found, track a newly reconstructed enum
+    definition under that id so that other instances stemming from the same
+    class id will also reuse this enum definition.
+
+    The "extra" variable is meant to be a dict (or None) that can be used for
+    forward compatibility shall the need arise.
+    """
+    # enums always inherit from their base Enum class at the last position in
+    # the list of base classes:
+    enum_base = bases[-1]
+    metacls = enum_base.__class__
+    classdict = metacls.__prepare__(name, bases)
+
+    for member_name, member_value in members.items():
+        classdict[member_name] = member_value
+    enum_class = metacls.__new__(metacls, name, bases, classdict)
+    enum_class.__module__ = module
+    enum_class.__qualname__ = qualname
+
+    return _lookup_class_or_track(class_tracker_id, enum_class)
+
+
+def _make_typevar(name, bound, constraints, covariant, contravariant, class_tracker_id):
+    tv = typing.TypeVar(
+        name,
+        *constraints,
+        bound=bound,
+        covariant=covariant,
+        contravariant=contravariant,
+    )
+    return _lookup_class_or_track(class_tracker_id, tv)
+
+
+def _decompose_typevar(obj):
+    return (
+        obj.__name__,
+        obj.__bound__,
+        obj.__constraints__,
+        obj.__covariant__,
+        obj.__contravariant__,
+        _get_or_create_tracker_id(obj),
+    )
+
+
+def _typevar_reduce(obj):
+    # TypeVar instances require the module information hence why we
+    # are not using the _should_pickle_by_reference directly
+    module_and_name = _lookup_module_and_qualname(obj, name=obj.__name__)
+
+    if module_and_name is None:
+        return (_make_typevar, _decompose_typevar(obj))
+    elif _is_registered_pickle_by_value(module_and_name[0]):
+        return (_make_typevar, _decompose_typevar(obj))
+
+    return (getattr, module_and_name)
+
+
+def _get_bases(typ):
+    if "__orig_bases__" in getattr(typ, "__dict__", {}):
+        # For generic types (see PEP 560)
+        # Note that simply checking `hasattr(typ, '__orig_bases__')` is not
+        # correct.  Subclasses of a fully-parameterized generic class does not
+        # have `__orig_bases__` defined, but `hasattr(typ, '__orig_bases__')`
+        # will return True because it's defined in the base class.
+        bases_attr = "__orig_bases__"
+    else:
+        # For regular class objects
+        bases_attr = "__bases__"
+    return getattr(typ, bases_attr)
+
+
+def _make_dict_keys(obj, is_ordered=False):
+    if is_ordered:
+        return OrderedDict.fromkeys(obj).keys()
+    else:
+        return dict.fromkeys(obj).keys()
+
+
+def _make_dict_values(obj, is_ordered=False):
+    if is_ordered:
+        return OrderedDict((i, _) for i, _ in enumerate(obj)).values()
+    else:
+        return {i: _ for i, _ in enumerate(obj)}.values()
+
+
+def _make_dict_items(obj, is_ordered=False):
+    if is_ordered:
+        return OrderedDict(obj).items()
+    else:
+        return obj.items()
+
+
+# COLLECTION OF OBJECTS __getnewargs__-LIKE METHODS
+# -------------------------------------------------
+
+
+def _class_getnewargs(obj):
+    type_kwargs = {}
+    if "__module__" in obj.__dict__:
+        type_kwargs["__module__"] = obj.__module__
+
+    __dict__ = obj.__dict__.get("__dict__", None)
+    if isinstance(__dict__, property):
+        type_kwargs["__dict__"] = __dict__
+
+    return (
+        type(obj),
+        obj.__name__,
+        _get_bases(obj),
+        type_kwargs,
+        _get_or_create_tracker_id(obj),
+        None,
+    )
+
+
+def _enum_getnewargs(obj):
+    members = {e.name: e.value for e in obj}
+    return (
+        obj.__bases__,
+        obj.__name__,
+        obj.__qualname__,
+        members,
+        obj.__module__,
+        _get_or_create_tracker_id(obj),
+        None,
+    )
+
+
+# COLLECTION OF OBJECTS RECONSTRUCTORS
+# ------------------------------------
+def _file_reconstructor(retval):
+    return retval
+
+
+# COLLECTION OF OBJECTS STATE GETTERS
+# -----------------------------------
+
+
+def _function_getstate(func):
+    # - Put func's dynamic attributes (stored in func.__dict__) in state. These
+    #   attributes will be restored at unpickling time using
+    #   f.__dict__.update(state)
+    # - Put func's members into slotstate. Such attributes will be restored at
+    #   unpickling time by iterating over slotstate and calling setattr(func,
+    #   slotname, slotvalue)
+    slotstate = {
+        "__name__": func.__name__,
+        "__qualname__": func.__qualname__,
+        "__annotations__": func.__annotations__,
+        "__kwdefaults__": func.__kwdefaults__,
+        "__defaults__": func.__defaults__,
+        "__module__": func.__module__,
+        "__doc__": func.__doc__,
+        "__closure__": func.__closure__,
+    }
+
+    f_globals_ref = _extract_code_globals(func.__code__)
+    f_globals = {k: func.__globals__[k] for k in f_globals_ref if k in func.__globals__}
+
+    if func.__closure__ is not None:
+        closure_values = list(map(_get_cell_contents, func.__closure__))
+    else:
+        closure_values = ()
+
+    # Extract currently-imported submodules used by func. Storing these modules
+    # in a smoke _cloudpickle_subimports attribute of the object's state will
+    # trigger the side effect of importing these modules at unpickling time
+    # (which is necessary for func to work correctly once depickled)
+    slotstate["_cloudpickle_submodules"] = _find_imported_submodules(
+        func.__code__, itertools.chain(f_globals.values(), closure_values)
+    )
+    slotstate["__globals__"] = f_globals
+
+    state = func.__dict__
+    return state, slotstate
+
+
+def _class_getstate(obj):
+    clsdict = _extract_class_dict(obj)
+    clsdict.pop("__weakref__", None)
+
+    if issubclass(type(obj), abc.ABCMeta):
+        # If obj is an instance of an ABCMeta subclass, don't pickle the
+        # cache/negative caches populated during isinstance/issubclass
+        # checks, but pickle the list of registered subclasses of obj.
+        clsdict.pop("_abc_cache", None)
+        clsdict.pop("_abc_negative_cache", None)
+        clsdict.pop("_abc_negative_cache_version", None)
+        registry = clsdict.pop("_abc_registry", None)
+        if registry is None:
+            # The abc caches and registered subclasses of a
+            # class are bundled into the single _abc_impl attribute
+            clsdict.pop("_abc_impl", None)
+            (registry, _, _, _) = abc._get_dump(obj)
+
+            clsdict["_abc_impl"] = [subclass_weakref() for subclass_weakref in registry]
+        else:
+            # In the above if clause, registry is a set of weakrefs -- in
+            # this case, registry is a WeakSet
+            clsdict["_abc_impl"] = [type_ for type_ in registry]
+
+    if "__slots__" in clsdict:
+        # pickle string length optimization: member descriptors of obj are
+        # created automatically from obj's __slots__ attribute, no need to
+        # save them in obj's state
+        if isinstance(obj.__slots__, str):
+            clsdict.pop(obj.__slots__)
+        else:
+            for k in obj.__slots__:
+                clsdict.pop(k, None)
+
+    clsdict.pop("__dict__", None)  # unpicklable property object
+
+    return (clsdict, {})
+
+
+def _enum_getstate(obj):
+    clsdict, slotstate = _class_getstate(obj)
+
+    members = {e.name: e.value for e in obj}
+    # Cleanup the clsdict that will be passed to _make_skeleton_enum:
+    # Those attributes are already handled by the metaclass.
+    for attrname in [
+        "_generate_next_value_",
+        "_member_names_",
+        "_member_map_",
+        "_member_type_",
+        "_value2member_map_",
+    ]:
+        clsdict.pop(attrname, None)
+    for member in members:
+        clsdict.pop(member)
+        # Special handling of Enum subclasses
+    return clsdict, slotstate
+
+
+# COLLECTIONS OF OBJECTS REDUCERS
+# -------------------------------
+# A reducer is a function taking a single argument (obj), and that returns a
+# tuple with all the necessary data to re-construct obj. Apart from a few
+# exceptions (list, dict, bytes, int, etc.), a reducer is necessary to
+# correctly pickle an object.
+# While many built-in objects (Exceptions objects, instances of the "object"
+# class, etc), are shipped with their own built-in reducer (invoked using
+# obj.__reduce__), some do not. The following methods were created to "fill
+# these holes".
+
+
+def _code_reduce(obj):
+    """code object reducer."""
+    # If you are not sure about the order of arguments, take a look at help
+    # of the specific type from types, for example:
+    # >>> from types import CodeType
+    # >>> help(CodeType)
+    if hasattr(obj, "co_exceptiontable"):
+        # Python 3.11 and later: there are some new attributes
+        # related to the enhanced exceptions.
+        args = (
+            obj.co_argcount,
+            obj.co_posonlyargcount,
+            obj.co_kwonlyargcount,
+            obj.co_nlocals,
+            obj.co_stacksize,
+            obj.co_flags,
+            obj.co_code,
+            obj.co_consts,
+            obj.co_names,
+            obj.co_varnames,
+            obj.co_filename,
+            obj.co_name,
+            obj.co_qualname,
+            obj.co_firstlineno,
+            obj.co_linetable,
+            obj.co_exceptiontable,
+            obj.co_freevars,
+            obj.co_cellvars,
+        )
+    elif hasattr(obj, "co_linetable"):
+        # Python 3.10 and later: obj.co_lnotab is deprecated and constructor
+        # expects obj.co_linetable instead.
+        args = (
+            obj.co_argcount,
+            obj.co_posonlyargcount,
+            obj.co_kwonlyargcount,
+            obj.co_nlocals,
+            obj.co_stacksize,
+            obj.co_flags,
+            obj.co_code,
+            obj.co_consts,
+            obj.co_names,
+            obj.co_varnames,
+            obj.co_filename,
+            obj.co_name,
+            obj.co_firstlineno,
+            obj.co_linetable,
+            obj.co_freevars,
+            obj.co_cellvars,
+        )
+    elif hasattr(obj, "co_nmeta"):  # pragma: no cover
+        # "nogil" Python: modified attributes from 3.9
+        args = (
+            obj.co_argcount,
+            obj.co_posonlyargcount,
+            obj.co_kwonlyargcount,
+            obj.co_nlocals,
+            obj.co_framesize,
+            obj.co_ndefaultargs,
+            obj.co_nmeta,
+            obj.co_flags,
+            obj.co_code,
+            obj.co_consts,
+            obj.co_varnames,
+            obj.co_filename,
+            obj.co_name,
+            obj.co_firstlineno,
+            obj.co_lnotab,
+            obj.co_exc_handlers,
+            obj.co_jump_table,
+            obj.co_freevars,
+            obj.co_cellvars,
+            obj.co_free2reg,
+            obj.co_cell2reg,
+        )
+    else:
+        # Backward compat for 3.8 and 3.9
+        args = (
+            obj.co_argcount,
+            obj.co_posonlyargcount,
+            obj.co_kwonlyargcount,
+            obj.co_nlocals,
+            obj.co_stacksize,
+            obj.co_flags,
+            obj.co_code,
+            obj.co_consts,
+            obj.co_names,
+            obj.co_varnames,
+            obj.co_filename,
+            obj.co_name,
+            obj.co_firstlineno,
+            obj.co_lnotab,
+            obj.co_freevars,
+            obj.co_cellvars,
+        )
+    return types.CodeType, args
+
+
+def _cell_reduce(obj):
+    """Cell (containing values of a function's free variables) reducer."""
+    try:
+        obj.cell_contents
+    except ValueError:  # cell is empty
+        return _make_empty_cell, ()
+    else:
+        return _make_cell, (obj.cell_contents,)
+
+
+def _classmethod_reduce(obj):
+    orig_func = obj.__func__
+    return type(obj), (orig_func,)
+
+
+def _file_reduce(obj):
+    """Save a file."""
+    import io
+
+    if not hasattr(obj, "name") or not hasattr(obj, "mode"):
+        raise pickle.PicklingError(
+            "Cannot pickle files that do not map to an actual file"
+        )
+    if obj is sys.stdout:
+        return getattr, (sys, "stdout")
+    if obj is sys.stderr:
+        return getattr, (sys, "stderr")
+    if obj is sys.stdin:
+        raise pickle.PicklingError("Cannot pickle standard input")
+    if obj.closed:
+        raise pickle.PicklingError("Cannot pickle closed files")
+    if hasattr(obj, "isatty") and obj.isatty():
+        raise pickle.PicklingError("Cannot pickle files that map to tty objects")
+    if "r" not in obj.mode and "+" not in obj.mode:
+        raise pickle.PicklingError(
+            "Cannot pickle files that are not opened for reading: %s" % obj.mode
+        )
+
+    name = obj.name
+
+    retval = io.StringIO()
+
+    try:
+        # Read the whole file
+        curloc = obj.tell()
+        obj.seek(0)
+        contents = obj.read()
+        obj.seek(curloc)
+    except OSError as e:
+        raise pickle.PicklingError(
+            "Cannot pickle file %s as it cannot be read" % name
+        ) from e
+    retval.write(contents)
+    retval.seek(curloc)
+
+    retval.name = name
+    return _file_reconstructor, (retval,)
+
+
+def _getset_descriptor_reduce(obj):
+    return getattr, (obj.__objclass__, obj.__name__)
+
+
+def _mappingproxy_reduce(obj):
+    return types.MappingProxyType, (dict(obj),)
+
+
+def _memoryview_reduce(obj):
+    return bytes, (obj.tobytes(),)
+
+
+def _module_reduce(obj):
+    if _should_pickle_by_reference(obj):
+        return subimport, (obj.__name__,)
+    else:
+        # Some external libraries can populate the "__builtins__" entry of a
+        # module's `__dict__` with unpicklable objects (see #316). For that
+        # reason, we do not attempt to pickle the "__builtins__" entry, and
+        # restore a default value for it at unpickling time.
+        state = obj.__dict__.copy()
+        state.pop("__builtins__", None)
+        return dynamic_subimport, (obj.__name__, state)
+
+
+def _method_reduce(obj):
+    return (types.MethodType, (obj.__func__, obj.__self__))
+
+
+def _logger_reduce(obj):
+    return logging.getLogger, (obj.name,)
+
+
+def _root_logger_reduce(obj):
+    return logging.getLogger, ()
+
+
+def _property_reduce(obj):
+    return property, (obj.fget, obj.fset, obj.fdel, obj.__doc__)
+
+
+def _weakset_reduce(obj):
+    return weakref.WeakSet, (list(obj),)
+
+
+def _dynamic_class_reduce(obj):
+    """Save a class that can't be referenced as a module attribute.
+
+    This method is used to serialize classes that are defined inside
+    functions, or that otherwise can't be serialized as attribute lookups
+    from importable modules.
+    """
+    if Enum is not None and issubclass(obj, Enum):
+        return (
+            _make_skeleton_enum,
+            _enum_getnewargs(obj),
+            _enum_getstate(obj),
+            None,
+            None,
+            _class_setstate,
+        )
+    else:
+        return (
+            _make_skeleton_class,
+            _class_getnewargs(obj),
+            _class_getstate(obj),
+            None,
+            None,
+            _class_setstate,
+        )
+
+
+def _class_reduce(obj):
+    """Select the reducer depending on the dynamic nature of the class obj."""
+    if obj is type(None):  # noqa
+        return type, (None,)
+    elif obj is type(Ellipsis):
+        return type, (Ellipsis,)
+    elif obj is type(NotImplemented):
+        return type, (NotImplemented,)
+    elif obj in _BUILTIN_TYPE_NAMES:
+        return _builtin_type, (_BUILTIN_TYPE_NAMES[obj],)
+    elif not _should_pickle_by_reference(obj):
+        return _dynamic_class_reduce(obj)
+    return NotImplemented
+
+
+def _dict_keys_reduce(obj):
+    # Safer not to ship the full dict as sending the rest might
+    # be unintended and could potentially cause leaking of
+    # sensitive information
+    return _make_dict_keys, (list(obj),)
+
+
+def _dict_values_reduce(obj):
+    # Safer not to ship the full dict as sending the rest might
+    # be unintended and could potentially cause leaking of
+    # sensitive information
+    return _make_dict_values, (list(obj),)
+
+
+def _dict_items_reduce(obj):
+    return _make_dict_items, (dict(obj),)
+
+
+def _odict_keys_reduce(obj):
+    # Safer not to ship the full dict as sending the rest might
+    # be unintended and could potentially cause leaking of
+    # sensitive information
+    return _make_dict_keys, (list(obj), True)
+
+
+def _odict_values_reduce(obj):
+    # Safer not to ship the full dict as sending the rest might
+    # be unintended and could potentially cause leaking of
+    # sensitive information
+    return _make_dict_values, (list(obj), True)
+
+
+def _odict_items_reduce(obj):
+    return _make_dict_items, (dict(obj), True)
+
+
+def _dataclass_field_base_reduce(obj):
+    return _get_dataclass_field_type_sentinel, (obj.name,)
+
+
+# COLLECTIONS OF OBJECTS STATE SETTERS
+# ------------------------------------
+# state setters are called at unpickling time, once the object is created and
+# it has to be updated to how it was at unpickling time.
+
+
+def _function_setstate(obj, state):
+    """Update the state of a dynamic function.
+
+    As __closure__ and __globals__ are readonly attributes of a function, we
+    cannot rely on the native setstate routine of pickle.load_build, that calls
+    setattr on items of the slotstate. Instead, we have to modify them inplace.
+    """
+    state, slotstate = state
+    obj.__dict__.update(state)
+
+    obj_globals = slotstate.pop("__globals__")
+    obj_closure = slotstate.pop("__closure__")
+    # _cloudpickle_subimports is a set of submodules that must be loaded for
+    # the pickled function to work correctly at unpickling time. Now that these
+    # submodules are depickled (hence imported), they can be removed from the
+    # object's state (the object state only served as a reference holder to
+    # these submodules)
+    slotstate.pop("_cloudpickle_submodules")
+
+    obj.__globals__.update(obj_globals)
+    obj.__globals__["__builtins__"] = __builtins__
+
+    if obj_closure is not None:
+        for i, cell in enumerate(obj_closure):
+            try:
+                value = cell.cell_contents
+            except ValueError:  # cell is empty
+                continue
+            obj.__closure__[i].cell_contents = value
+
+    for k, v in slotstate.items():
+        setattr(obj, k, v)
+
+
+def _class_setstate(obj, state):
+    state, slotstate = state
+    registry = None
+    for attrname, attr in state.items():
+        if attrname == "_abc_impl":
+            registry = attr
+        else:
+            setattr(obj, attrname, attr)
+    if registry is not None:
+        for subclass in registry:
+            obj.register(subclass)
+
+    return obj
+
+
+# COLLECTION OF DATACLASS UTILITIES
+# ---------------------------------
+# There are some internal sentinel values whose identity must be preserved when
+# unpickling dataclass fields. Each sentinel value has a unique name that we can
+# use to retrieve its identity at unpickling time.
+
+
+_DATACLASSE_FIELD_TYPE_SENTINELS = {
+    dataclasses._FIELD.name: dataclasses._FIELD,
+    dataclasses._FIELD_CLASSVAR.name: dataclasses._FIELD_CLASSVAR,
+    dataclasses._FIELD_INITVAR.name: dataclasses._FIELD_INITVAR,
+}
+
+
+def _get_dataclass_field_type_sentinel(name):
+    return _DATACLASSE_FIELD_TYPE_SENTINELS[name]
+
+
+class Pickler(pickle.Pickler):
+    # set of reducers defined and used by cloudpickle (private)
+    _dispatch_table = {}
+    _dispatch_table[classmethod] = _classmethod_reduce
+    _dispatch_table[io.TextIOWrapper] = _file_reduce
+    _dispatch_table[logging.Logger] = _logger_reduce
+    _dispatch_table[logging.RootLogger] = _root_logger_reduce
+    _dispatch_table[memoryview] = _memoryview_reduce
+    _dispatch_table[property] = _property_reduce
+    _dispatch_table[staticmethod] = _classmethod_reduce
+    _dispatch_table[CellType] = _cell_reduce
+    _dispatch_table[types.CodeType] = _code_reduce
+    _dispatch_table[types.GetSetDescriptorType] = _getset_descriptor_reduce
+    _dispatch_table[types.ModuleType] = _module_reduce
+    _dispatch_table[types.MethodType] = _method_reduce
+    _dispatch_table[types.MappingProxyType] = _mappingproxy_reduce
+    _dispatch_table[weakref.WeakSet] = _weakset_reduce
+    _dispatch_table[typing.TypeVar] = _typevar_reduce
+    _dispatch_table[_collections_abc.dict_keys] = _dict_keys_reduce
+    _dispatch_table[_collections_abc.dict_values] = _dict_values_reduce
+    _dispatch_table[_collections_abc.dict_items] = _dict_items_reduce
+    _dispatch_table[type(OrderedDict().keys())] = _odict_keys_reduce
+    _dispatch_table[type(OrderedDict().values())] = _odict_values_reduce
+    _dispatch_table[type(OrderedDict().items())] = _odict_items_reduce
+    _dispatch_table[abc.abstractmethod] = _classmethod_reduce
+    _dispatch_table[abc.abstractclassmethod] = _classmethod_reduce
+    _dispatch_table[abc.abstractstaticmethod] = _classmethod_reduce
+    _dispatch_table[abc.abstractproperty] = _property_reduce
+    _dispatch_table[dataclasses._FIELD_BASE] = _dataclass_field_base_reduce
+
+    dispatch_table = ChainMap(_dispatch_table, copyreg.dispatch_table)
+
+    # function reducers are defined as instance methods of cloudpickle.Pickler
+    # objects, as they rely on a cloudpickle.Pickler attribute (globals_ref)
+    def _dynamic_function_reduce(self, func):
+        """Reduce a function that is not pickleable via attribute lookup."""
+        newargs = self._function_getnewargs(func)
+        state = _function_getstate(func)
+        return (_make_function, newargs, state, None, None, _function_setstate)
+
+    def _function_reduce(self, obj):
+        """Reducer for function objects.
+
+        If obj is a top-level attribute of a file-backed module, this reducer
+        returns NotImplemented, making the cloudpickle.Pickler fall back to
+        traditional pickle.Pickler routines to save obj. Otherwise, it reduces
+        obj using a custom cloudpickle reducer designed specifically to handle
+        dynamic functions.
+        """
+        if _should_pickle_by_reference(obj):
+            return NotImplemented
+        else:
+            return self._dynamic_function_reduce(obj)
+
+    def _function_getnewargs(self, func):
+        code = func.__code__
+
+        # base_globals represents the future global namespace of func at
+        # unpickling time. Looking it up and storing it in
+        # cloudpickle.Pickler.globals_ref allow functions sharing the same
+        # globals at pickling time to also share them once unpickled, at one
+        # condition: since globals_ref is an attribute of a cloudpickle.Pickler
+        # instance, and that a new cloudpickle.Pickler is created each time
+        # cloudpickle.dump or cloudpickle.dumps is called, functions also need
+        # to be saved within the same invocation of
+        # cloudpickle.dump/cloudpickle.dumps (for example:
+        # cloudpickle.dumps([f1, f2])). There is no such limitation when using
+        # cloudpickle.Pickler.dump, as long as the multiple invocations are
+        # bound to the same cloudpickle.Pickler instance.
+        base_globals = self.globals_ref.setdefault(id(func.__globals__), {})
+
+        if base_globals == {}:
+            # Add module attributes used to resolve relative imports
+            # instructions inside func.
+            for k in ["__package__", "__name__", "__path__", "__file__"]:
+                if k in func.__globals__:
+                    base_globals[k] = func.__globals__[k]
+
+        # Do not bind the free variables before the function is created to
+        # avoid infinite recursion.
+        if func.__closure__ is None:
+            closure = None
+        else:
+            closure = tuple(_make_empty_cell() for _ in range(len(code.co_freevars)))
+
+        return code, base_globals, None, None, closure
+
+    def dump(self, obj):
+        try:
+            return super().dump(obj)
+        except RuntimeError as e:
+            if len(e.args) > 0 and "recursion" in e.args[0]:
+                msg = "Could not pickle object as excessively deep recursion required."
+                raise pickle.PicklingError(msg) from e
+            else:
+                raise
+
+    def __init__(self, file, protocol=None, buffer_callback=None):
+        if protocol is None:
+            protocol = DEFAULT_PROTOCOL
+        super().__init__(file, protocol=protocol, buffer_callback=buffer_callback)
+        # map functions __globals__ attribute ids, to ensure that functions
+        # sharing the same global namespace at pickling time also share
+        # their global namespace at unpickling time.
+        self.globals_ref = {}
+        self.proto = int(protocol)
+
+    if not PYPY:
+        # pickle.Pickler is the C implementation of the CPython pickler and
+        # therefore we rely on reduce_override method to customize the pickler
+        # behavior.
+
+        # `cloudpickle.Pickler.dispatch` is only left for backward
+        # compatibility - note that when using protocol 5,
+        # `cloudpickle.Pickler.dispatch` is not an extension of
+        # `pickle._Pickler.dispatch` dictionary, because `cloudpickle.Pickler`
+        # subclasses the C-implemented `pickle.Pickler`, which does not expose
+        # a `dispatch` attribute.  Earlier versions of `cloudpickle.Pickler`
+        # used `cloudpickle.Pickler.dispatch` as a class-level attribute
+        # storing all reducers implemented by cloudpickle, but the attribute
+        # name was not a great choice given because it would collide with a
+        # similarly named attribute in the pure-Python `pickle._Pickler`
+        # implementation in the standard library.
+        dispatch = dispatch_table
+
+        # Implementation of the reducer_override callback, in order to
+        # efficiently serialize dynamic functions and classes by subclassing
+        # the C-implemented `pickle.Pickler`.
+        # TODO: decorrelate reducer_override (which is tied to CPython's
+        # implementation - would it make sense to backport it to pypy? - and
+        # pickle's protocol 5 which is implementation agnostic. Currently, the
+        # availability of both notions coincide on CPython's pickle, but it may
+        # not be the case anymore when pypy implements protocol 5.
+
+        def reducer_override(self, obj):
+            """Type-agnostic reducing callback for function and classes.
+
+            For performance reasons, subclasses of the C `pickle.Pickler` class
+            cannot register custom reducers for functions and classes in the
+            dispatch_table attribute. Reducers for such types must instead
+            implemented via the special `reducer_override` method.
+
+            Note that this method will be called for any object except a few
+            builtin-types (int, lists, dicts etc.), which differs from reducers
+            in the Pickler's dispatch_table, each of them being invoked for
+            objects of a specific type only.
+
+            This property comes in handy for classes: although most classes are
+            instances of the ``type`` metaclass, some of them can be instances
+            of other custom metaclasses (such as enum.EnumMeta for example). In
+            particular, the metaclass will likely not be known in advance, and
+            thus cannot be special-cased using an entry in the dispatch_table.
+            reducer_override, among other things, allows us to register a
+            reducer that will be called for any class, independently of its
+            type.
+
+            Notes:
+
+            * reducer_override has the priority over dispatch_table-registered
+            reducers.
+            * reducer_override can be used to fix other limitations of
+              cloudpickle for other types that suffered from type-specific
+              reducers, such as Exceptions. See
+              https://github.com/cloudpipe/cloudpickle/issues/248
+            """
+            t = type(obj)
+            try:
+                is_anyclass = issubclass(t, type)
+            except TypeError:  # t is not a class (old Boost; see SF #502085)
+                is_anyclass = False
+
+            if is_anyclass:
+                return _class_reduce(obj)
+            elif isinstance(obj, types.FunctionType):
+                return self._function_reduce(obj)
+            else:
+                # fallback to save_global, including the Pickler's
+                # dispatch_table
+                return NotImplemented
+
+    else:
+        # When reducer_override is not available, hack the pure-Python
+        # Pickler's types.FunctionType and type savers. Note: the type saver
+        # must override Pickler.save_global, because pickle.py contains a
+        # hard-coded call to save_global when pickling meta-classes.
+        dispatch = pickle.Pickler.dispatch.copy()
+
+        def _save_reduce_pickle5(
+            self,
+            func,
+            args,
+            state=None,
+            listitems=None,
+            dictitems=None,
+            state_setter=None,
+            obj=None,
+        ):
+            save = self.save
+            write = self.write
+            self.save_reduce(
+                func,
+                args,
+                state=None,
+                listitems=listitems,
+                dictitems=dictitems,
+                obj=obj,
+            )
+            # backport of the Python 3.8 state_setter pickle operations
+            save(state_setter)
+            save(obj)  # simple BINGET opcode as obj is already memoized.
+            save(state)
+            write(pickle.TUPLE2)
+            # Trigger a state_setter(obj, state) function call.
+            write(pickle.REDUCE)
+            # The purpose of state_setter is to carry-out an
+            # inplace modification of obj. We do not care about what the
+            # method might return, so its output is eventually removed from
+            # the stack.
+            write(pickle.POP)
+
+        def save_global(self, obj, name=None, pack=struct.pack):
+            """Main dispatch method.
+
+            The name of this method is somewhat misleading: all types get
+            dispatched here.
+            """
+            if obj is type(None):  # noqa
+                return self.save_reduce(type, (None,), obj=obj)
+            elif obj is type(Ellipsis):
+                return self.save_reduce(type, (Ellipsis,), obj=obj)
+            elif obj is type(NotImplemented):
+                return self.save_reduce(type, (NotImplemented,), obj=obj)
+            elif obj in _BUILTIN_TYPE_NAMES:
+                return self.save_reduce(
+                    _builtin_type, (_BUILTIN_TYPE_NAMES[obj],), obj=obj
+                )
+
+            if name is not None:
+                super().save_global(obj, name=name)
+            elif not _should_pickle_by_reference(obj, name=name):
+                self._save_reduce_pickle5(*_dynamic_class_reduce(obj), obj=obj)
+            else:
+                super().save_global(obj, name=name)
+
+        dispatch[type] = save_global
+
+        def save_function(self, obj, name=None):
+            """Registered with the dispatch to handle all function types.
+
+            Determines what kind of function obj is (e.g. lambda, defined at
+            interactive prompt, etc) and handles the pickling appropriately.
+            """
+            if _should_pickle_by_reference(obj, name=name):
+                return super().save_global(obj, name=name)
+            elif PYPY and isinstance(obj.__code__, builtin_code_type):
+                return self.save_pypy_builtin_func(obj)
+            else:
+                return self._save_reduce_pickle5(
+                    *self._dynamic_function_reduce(obj), obj=obj
+                )
+
+        def save_pypy_builtin_func(self, obj):
+            """Save pypy equivalent of builtin functions.
+
+            PyPy does not have the concept of builtin-functions. Instead,
+            builtin-functions are simple function instances, but with a
+            builtin-code attribute.
+            Most of the time, builtin functions should be pickled by attribute.
+            But PyPy has flaky support for __qualname__, so some builtin
+            functions such as float.__new__ will be classified as dynamic. For
+            this reason only, we created this special routine. Because
+            builtin-functions are not expected to have closure or globals,
+            there is no additional hack (compared the one already implemented
+            in pickle) to protect ourselves from reference cycles. A simple
+            (reconstructor, newargs, obj.__dict__) tuple is save_reduced.  Note
+            also that PyPy improved their support for __qualname__ in v3.6, so
+            this routing should be removed when cloudpickle supports only PyPy
+            3.6 and later.
+            """
+            rv = (
+                types.FunctionType,
+                (obj.__code__, {}, obj.__name__, obj.__defaults__, obj.__closure__),
+                obj.__dict__,
+            )
+            self.save_reduce(*rv, obj=obj)
+
+        dispatch[types.FunctionType] = save_function
+
+
+# Shorthands similar to pickle.dump/pickle.dumps
+
+
+def dump(obj, file, protocol=None, buffer_callback=None):
+    """Serialize obj as bytes streamed into file
+
+    protocol defaults to cloudpickle.DEFAULT_PROTOCOL which is an alias to
+    pickle.HIGHEST_PROTOCOL. This setting favors maximum communication
+    speed between processes running the same Python version.
+
+    Set protocol=pickle.DEFAULT_PROTOCOL instead if you need to ensure
+    compatibility with older versions of Python (although this is not always
+    guaranteed to work because cloudpickle relies on some internal
+    implementation details that can change from one Python version to the
+    next).
+    """
+    Pickler(file, protocol=protocol, buffer_callback=buffer_callback).dump(obj)
+
+
+def dumps(obj, protocol=None, buffer_callback=None):
+    """Serialize obj as a string of bytes allocated in memory
+
+    protocol defaults to cloudpickle.DEFAULT_PROTOCOL which is an alias to
+    pickle.HIGHEST_PROTOCOL. This setting favors maximum communication
+    speed between processes running the same Python version.
+
+    Set protocol=pickle.DEFAULT_PROTOCOL instead if you need to ensure
+    compatibility with older versions of Python (although this is not always
+    guaranteed to work because cloudpickle relies on some internal
+    implementation details that can change from one Python version to the
+    next).
+    """
+    with io.BytesIO() as file:
+        cp = Pickler(file, protocol=protocol, buffer_callback=buffer_callback)
+        cp.dump(obj)
+        return file.getvalue()
+
+
+# Include pickles unloading functions in this namespace for convenience.
+load, loads = pickle.load, pickle.loads
+
+# Backward compat alias.
+CloudPickler = Pickler

.venv/lib/python3.11/site-packages/ray/cloudpickle/cloudpickle_fast.py

@@ -0,0 +1,13 @@
+"""Compatibility module.
+
+It can be necessary to load files generated by previous versions of cloudpickle
+that rely on symbols being defined under the `cloudpickle.cloudpickle_fast`
+namespace.
+
+See: tests/test_backward_compat.py
+"""
+from . import cloudpickle
+
+
+def __getattr__(name):
+    return getattr(cloudpickle, name)

.venv/lib/python3.11/site-packages/ray/cloudpickle/compat.py

@@ -0,0 +1,19 @@
+import logging
+import os
+
+logger = logging.getLogger(__name__)
+
+RAY_PICKLE_VERBOSE_DEBUG = os.environ.get("RAY_PICKLE_VERBOSE_DEBUG")
+verbose_level = int(RAY_PICKLE_VERBOSE_DEBUG) if RAY_PICKLE_VERBOSE_DEBUG else 0
+
+if verbose_level > 1:
+    logger.warning(
+        "Environmental variable RAY_PICKLE_VERBOSE_DEBUG is set to "
+        f"'{verbose_level}', this enabled python-based serialization backend "
+        f"instead of C-Pickle. Serialization would be very slow."
+    )
+    from ray.cloudpickle import py_pickle as pickle
+    from ray.cloudpickle.py_pickle import Pickler
+else:
+    import pickle  # noqa: F401
+    from _pickle import Pickler  # noqa: F401

.venv/lib/python3.11/site-packages/ray/cloudpickle/py_pickle.py

@@ -0,0 +1,30 @@
+from pickle import (
+    _Pickler,
+    _Unpickler as Unpickler,
+    _loads as loads,
+    _load as load,
+    PickleError,
+    PicklingError,
+    UnpicklingError,
+    HIGHEST_PROTOCOL,
+)
+
+__all__ = [
+    "PickleError",
+    "PicklingError",
+    "UnpicklingError",
+    "Pickler",
+    "Unpickler",
+    "load",
+    "loads",
+    "HIGHEST_PROTOCOL",
+]
+
+
+class Pickler(_Pickler):
+    def __init__(self, file, protocol=None, *, fix_imports=True, buffer_callback=None):
+        super().__init__(
+            file, protocol, fix_imports=fix_imports, buffer_callback=buffer_callback
+        )
+        # avoid being overrided by cloudpickle
+        self.dispatch = _Pickler.dispatch.copy()

.venv/lib/python3.11/site-packages/ray/scripts/scripts.py

@@ -0,0 +1,2695 @@
+import copy
+import json
+import logging
+import os
+import platform
+import signal
+import subprocess
+import sys
+import time
+import urllib
+import urllib.parse
+import warnings
+import shutil
+from datetime import datetime
+from typing import Optional, Set, List, Tuple
+from ray.dashboard.modules.metrics import install_and_start_prometheus
+from ray.util.check_open_ports import check_open_ports
+import requests
+
+import click
+import colorama
+import psutil
+import yaml
+
+import ray
+import ray._private.ray_constants as ray_constants
+import ray._private.services as services
+from ray._private.utils import (
+    check_ray_client_dependencies_installed,
+    parse_resources_json,
+    parse_node_labels_json,
+)
+from ray._private.internal_api import memory_summary
+from ray._private.storage import _load_class
+from ray._private.usage import usage_lib
+from ray.autoscaler._private.cli_logger import add_click_logging_options, cf, cli_logger
+from ray.autoscaler._private.commands import (
+    RUN_ENV_TYPES,
+    attach_cluster,
+    create_or_update_cluster,
+    debug_status,
+    exec_cluster,
+    get_cluster_dump_archive,
+    get_head_node_ip,
+    get_local_dump_archive,
+    get_worker_node_ips,
+    kill_node,
+    monitor_cluster,
+    rsync,
+    teardown_cluster,
+)
+from ray.autoscaler._private.constants import RAY_PROCESSES
+from ray.autoscaler._private.fake_multi_node.node_provider import FAKE_HEAD_NODE_ID
+from ray.util.annotations import PublicAPI
+from ray.core.generated import autoscaler_pb2
+
+
+logger = logging.getLogger(__name__)
+
+
+def _check_ray_version(gcs_client):
+    import ray._private.usage.usage_lib as ray_usage_lib
+
+    cluster_metadata = ray_usage_lib.get_cluster_metadata(gcs_client)
+    if cluster_metadata and cluster_metadata["ray_version"] != ray.__version__:
+        raise RuntimeError(
+            "Ray version mismatch: cluster has Ray version "
+            f'{cluster_metadata["ray_version"]} '
+            f"but local Ray version is {ray.__version__}"
+        )
+
+
+@click.group()
+@click.option(
+    "--logging-level",
+    required=False,
+    default=ray_constants.LOGGER_LEVEL,
+    type=str,
+    help=ray_constants.LOGGER_LEVEL_HELP,
+)
+@click.option(
+    "--logging-format",
+    required=False,
+    default=ray_constants.LOGGER_FORMAT,
+    type=str,
+    help=ray_constants.LOGGER_FORMAT_HELP,
+)
+@click.version_option()
+def cli(logging_level, logging_format):
+    level = logging.getLevelName(logging_level.upper())
+    ray._private.ray_logging.setup_logger(level, logging_format)
+    cli_logger.set_format(format_tmpl=logging_format)
+
+
+@click.command()
+@click.argument("cluster_config_file", required=True, type=str)
+@click.option(
+    "--cluster-name",
+    "-n",
+    required=False,
+    type=str,
+    help="Override the configured cluster name.",
+)
+@click.option(
+    "--port",
+    "-p",
+    required=False,
+    type=int,
+    default=ray_constants.DEFAULT_DASHBOARD_PORT,
+    help="The local port to forward to the dashboard",
+)
+@click.option(
+    "--remote-port",
+    required=False,
+    type=int,
+    default=ray_constants.DEFAULT_DASHBOARD_PORT,
+    help="The remote port your dashboard runs on",
+)
+@click.option(
+    "--no-config-cache",
+    is_flag=True,
+    default=False,
+    help="Disable the local cluster config cache.",
+)
+@PublicAPI
+def dashboard(cluster_config_file, cluster_name, port, remote_port, no_config_cache):
+    """Port-forward a Ray cluster's dashboard to the local machine."""
+    # Sleeping in a loop is preferable to `sleep infinity` because the latter
+    # only works on linux.
+    # Find the first open port sequentially from `remote_port`.
+    try:
+        port_forward = [
+            (port, remote_port),
+        ]
+        click.echo(
+            "Attempting to establish dashboard locally at"
+            " http://localhost:{}/ connected to"
+            " remote port {}".format(port, remote_port)
+        )
+        # We want to probe with a no-op that returns quickly to avoid
+        # exceptions caused by network errors.
+        exec_cluster(
+            cluster_config_file,
+            override_cluster_name=cluster_name,
+            port_forward=port_forward,
+            no_config_cache=no_config_cache,
+        )
+        click.echo("Successfully established connection.")
+    except Exception as e:
+        raise click.ClickException(
+            "Failed to forward dashboard from remote port {1} to local port "
+            "{0}. There are a couple possibilities: \n 1. The remote port is "
+            "incorrectly specified \n 2. The local port {0} is already in "
+            "use.\n The exception is: {2}".format(port, remote_port, e)
+        ) from None
+
+
+def continue_debug_session(live_jobs: Set[str]):
+    """Continue active debugging session.
+
+    This function will connect 'ray debug' to the right debugger
+    when a user is stepping between Ray tasks.
+    """
+    active_sessions = ray.experimental.internal_kv._internal_kv_list(
+        "RAY_PDB_", namespace=ray_constants.KV_NAMESPACE_PDB
+    )
+
+    for active_session in active_sessions:
+        if active_session.startswith(b"RAY_PDB_CONTINUE"):
+            # Check to see that the relevant job is still alive.
+            data = ray.experimental.internal_kv._internal_kv_get(
+                active_session, namespace=ray_constants.KV_NAMESPACE_PDB
+            )
+            if json.loads(data)["job_id"] not in live_jobs:
+                ray.experimental.internal_kv._internal_kv_del(
+                    active_session, namespace=ray_constants.KV_NAMESPACE_PDB
+                )
+                continue
+
+            print("Continuing pdb session in different process...")
+            key = b"RAY_PDB_" + active_session[len("RAY_PDB_CONTINUE_") :]
+            while True:
+                data = ray.experimental.internal_kv._internal_kv_get(
+                    key, namespace=ray_constants.KV_NAMESPACE_PDB
+                )
+                if data:
+                    session = json.loads(data)
+                    if "exit_debugger" in session or session["job_id"] not in live_jobs:
+                        ray.experimental.internal_kv._internal_kv_del(
+                            key, namespace=ray_constants.KV_NAMESPACE_PDB
+                        )
+                        return
+                    host, port = session["pdb_address"].split(":")
+                    ray.util.rpdb._connect_pdb_client(host, int(port))
+                    ray.experimental.internal_kv._internal_kv_del(
+                        key, namespace=ray_constants.KV_NAMESPACE_PDB
+                    )
+                    continue_debug_session(live_jobs)
+                    return
+                time.sleep(1.0)
+
+
+def none_to_empty(s):
+    if s is None:
+        return ""
+    return s
+
+
+def format_table(table):
+    """Format a table as a list of lines with aligned columns."""
+    result = []
+    col_width = [max(len(x) for x in col) for col in zip(*table)]
+    for line in table:
+        result.append(
+            " | ".join("{0:{1}}".format(x, col_width[i]) for i, x in enumerate(line))
+        )
+    return result
+
+
+@cli.command()
+@click.option(
+    "--address", required=False, type=str, help="Override the address to connect to."
+)
+@click.option(
+    "-v",
+    "--verbose",
+    required=False,
+    is_flag=True,
+    help="Shows additional fields in breakpoint selection page.",
+)
+def debug(address: str, verbose: bool):
+    """Show all active breakpoints and exceptions in the Ray debugger."""
+    address = services.canonicalize_bootstrap_address_or_die(address)
+    logger.info(f"Connecting to Ray instance at {address}.")
+    ray.init(address=address, log_to_driver=False)
+    if os.environ.get("RAY_DEBUG", "1") != "legacy":
+        print(
+            f"{colorama.Fore.YELLOW}NOTE: The distributed debugger "
+            "https://docs.ray.io/en/latest/ray-observability"
+            "/ray-distributed-debugger.html is now the default "
+            "due to better interactive debugging support. If you want "
+            "to keep using 'ray debug' please set RAY_DEBUG=legacy "
+            f"in your cluster (e.g. via runtime environment).{colorama.Fore.RESET}"
+        )
+    while True:
+        # Used to filter out and clean up entries from dead jobs.
+        live_jobs = {
+            job["JobID"] for job in ray._private.state.jobs() if not job["IsDead"]
+        }
+        continue_debug_session(live_jobs)
+
+        active_sessions = ray.experimental.internal_kv._internal_kv_list(
+            "RAY_PDB_", namespace=ray_constants.KV_NAMESPACE_PDB
+        )
+        print("Active breakpoints:")
+        sessions_data = []
+        for active_session in active_sessions:
+            data = json.loads(
+                ray.experimental.internal_kv._internal_kv_get(
+                    active_session, namespace=ray_constants.KV_NAMESPACE_PDB
+                )
+            )
+            # Check that the relevant job is alive, else clean up the entry.
+            if data["job_id"] in live_jobs:
+                sessions_data.append(data)
+            else:
+                ray.experimental.internal_kv._internal_kv_del(
+                    active_session, namespace=ray_constants.KV_NAMESPACE_PDB
+                )
+        sessions_data = sorted(
+            sessions_data, key=lambda data: data["timestamp"], reverse=True
+        )
+        if verbose:
+            table = [
+                [
+                    "index",
+                    "timestamp",
+                    "Ray task",
+                    "filename:lineno",
+                    "Task ID",
+                    "Worker ID",
+                    "Actor ID",
+                    "Node ID",
+                ]
+            ]
+            for i, data in enumerate(sessions_data):
+                date = datetime.utcfromtimestamp(data["timestamp"]).strftime(
+                    "%Y-%m-%d %H:%M:%S"
+                )
+                table.append(
+                    [
+                        str(i),
+                        date,
+                        data["proctitle"],
+                        data["filename"] + ":" + str(data["lineno"]),
+                        data["task_id"],
+                        data["worker_id"],
+                        none_to_empty(data["actor_id"]),
+                        data["node_id"],
+                    ]
+                )
+        else:
+            # Non verbose mode: no IDs.
+            table = [["index", "timestamp", "Ray task", "filename:lineno"]]
+            for i, data in enumerate(sessions_data):
+                date = datetime.utcfromtimestamp(data["timestamp"]).strftime(
+                    "%Y-%m-%d %H:%M:%S"
+                )
+                table.append(
+                    [
+                        str(i),
+                        date,
+                        data["proctitle"],
+                        data["filename"] + ":" + str(data["lineno"]),
+                    ]
+                )
+        for i, line in enumerate(format_table(table)):
+            print(line)
+            if i >= 1 and not sessions_data[i - 1]["traceback"].startswith(
+                "NoneType: None"
+            ):
+                print(sessions_data[i - 1]["traceback"])
+        inp = input("Enter breakpoint index or press enter to refresh: ")
+        if inp == "":
+            print()
+            continue
+        else:
+            index = int(inp)
+            session = json.loads(
+                ray.experimental.internal_kv._internal_kv_get(
+                    active_sessions[index], namespace=ray_constants.KV_NAMESPACE_PDB
+                )
+            )
+            host, port = session["pdb_address"].split(":")
+            ray.util.rpdb._connect_pdb_client(host, int(port))
+
+
+@cli.command()
+@click.option(
+    "--node-ip-address", required=False, type=str, help="the IP address of this node"
+)
+@click.option("--address", required=False, type=str, help="the address to use for Ray")
+@click.option(
+    "--port",
+    type=int,
+    required=False,
+    help=f"the port of the head ray process. If not provided, defaults to "
+    f"{ray_constants.DEFAULT_PORT}; if port is set to 0, we will"
+    f" allocate an available port.",
+)
+@click.option(
+    "--node-name",
+    required=False,
+    hidden=True,
+    type=str,
+    help="the user-provided identifier or name for this node. "
+    "Defaults to the node's ip_address",
+)
+@click.option(
+    "--redis-username",
+    required=False,
+    hidden=True,
+    type=str,
+    default=ray_constants.REDIS_DEFAULT_USERNAME,
+    help="If provided, secure Redis ports with this username",
+)
+@click.option(
+    "--redis-password",
+    required=False,
+    hidden=True,
+    type=str,
+    default=ray_constants.REDIS_DEFAULT_PASSWORD,
+    help="If provided, secure Redis ports with this password",
+)
+@click.option(
+    "--redis-shard-ports",
+    required=False,
+    hidden=True,
+    type=str,
+    help="the port to use for the Redis shards other than the primary Redis shard",
+)
+@click.option(
+    "--object-manager-port",
+    required=False,
+    type=int,
+    help="the port to use for starting the object manager",
+)
+@click.option(
+    "--node-manager-port",
+    required=False,
+    type=int,
+    default=0,
+    help="the port to use for starting the node manager",
+)
+@click.option(
+    "--gcs-server-port",
+    required=False,
+    type=int,
+    help="Port number for the GCS server.",
+)
+@click.option(
+    "--min-worker-port",
+    required=False,
+    type=int,
+    default=10002,
+    help="the lowest port number that workers will bind on. If not set, "
+    "random ports will be chosen.",
+)
+@click.option(
+    "--max-worker-port",
+    required=False,
+    type=int,
+    default=19999,
+    help="the highest port number that workers will bind on. If set, "
+    "'--min-worker-port' must also be set.",
+)
+@click.option(
+    "--worker-port-list",
+    required=False,
+    help="a comma-separated list of open ports for workers to bind on. "
+    "Overrides '--min-worker-port' and '--max-worker-port'.",
+)
+@click.option(
+    "--ray-client-server-port",
+    required=False,
+    type=int,
+    default=None,
+    help="the port number the ray client server binds on, default to 10001, "
+    "or None if ray[client] is not installed.",
+)
+@click.option(
+    "--memory",
+    required=False,
+    hidden=True,
+    type=int,
+    help="The amount of memory (in bytes) to make available to workers. "
+    "By default, this is set to the available memory on the node.",
+)
+@click.option(
+    "--object-store-memory",
+    required=False,
+    type=int,
+    help="The amount of memory (in bytes) to start the object store with. "
+    "By default, this is 30% (ray_constants.DEFAULT_OBJECT_STORE_MEMORY_PROPORTION) "
+    "of available system memory capped by "
+    "the shm size and 200G (ray_constants.DEFAULT_OBJECT_STORE_MAX_MEMORY_BYTES) "
+    "but can be set higher.",
+)
+@click.option(
+    "--redis-max-memory",
+    required=False,
+    hidden=True,
+    type=int,
+    help="The max amount of memory (in bytes) to allow redis to use. Once the "
+    "limit is exceeded, redis will start LRU eviction of entries. This only "
+    "applies to the sharded redis tables (task, object, and profile tables). "
+    "By default this is capped at 10GB but can be set higher.",
+)
+@click.option(
+    "--num-cpus", required=False, type=int, help="the number of CPUs on this node"
+)
+@click.option(
+    "--num-gpus", required=False, type=int, help="the number of GPUs on this node"
+)
+@click.option(
+    "--resources",
+    required=False,
+    default="{}",
+    type=str,
+    help="A JSON serialized dictionary mapping resource name to resource quantity."
+    + (
+        r"""
+
+Windows command prompt users must ensure to double quote command line arguments. Because
+JSON requires the use of double quotes you must escape these arguments as well, for
+example:
+
+    ray start --head --resources="{\"special_hardware\":1, \"custom_label\":1}"
+
+Windows powershell users need additional escaping:
+
+    ray start --head --resources="{\""special_hardware\"":1, \""custom_label\"":1}"
+"""
+        if platform.system() == "Windows"
+        else ""
+    ),
+)
+@click.option(
+    "--head",
+    is_flag=True,
+    default=False,
+    help="provide this argument for the head node",
+)
+@click.option(
+    "--include-dashboard",
+    default=None,
+    type=bool,
+    help="provide this argument to start the Ray dashboard GUI",
+)
+@click.option(
+    "--dashboard-host",
+    required=False,
+    default=ray_constants.DEFAULT_DASHBOARD_IP,
+    help="the host to bind the dashboard server to, either localhost "
+    "(127.0.0.1) or 0.0.0.0 (available from all interfaces). By default, this "
+    "is 127.0.0.1",
+)
+@click.option(
+    "--dashboard-port",
+    required=False,
+    type=int,
+    default=ray_constants.DEFAULT_DASHBOARD_PORT,
+    help="the port to bind the dashboard server to--defaults to {}".format(
+        ray_constants.DEFAULT_DASHBOARD_PORT
+    ),
+)
+@click.option(
+    "--dashboard-agent-listen-port",
+    type=int,
+    default=ray_constants.DEFAULT_DASHBOARD_AGENT_LISTEN_PORT,
+    help="the port for dashboard agents to listen for http on.",
+)
+@click.option(
+    "--dashboard-agent-grpc-port",
+    type=int,
+    default=None,
+    help="the port for dashboard agents to listen for grpc on.",
+)
+@click.option(
+    "--dashboard-grpc-port",
+    type=int,
+    default=None,
+    help="The port for the dashboard head to listen for grpc on.",
+)
+@click.option(
+    "--runtime-env-agent-port",
+    type=int,
+    default=None,
+    help="The port for the runtime enviroment agents to listen for http on.",
+)
+@click.option(
+    "--block",
+    is_flag=True,
+    default=False,
+    help="provide this argument to block forever in this command",
+)
+@click.option(
+    "--plasma-directory",
+    required=False,
+    type=str,
+    help="object store directory for memory mapped files",
+)
+@click.option(
+    "--autoscaling-config",
+    required=False,
+    type=str,
+    help="the file that contains the autoscaling config",
+)
+@click.option(
+    "--no-redirect-output",
+    is_flag=True,
+    default=False,
+    help="do not redirect non-worker stdout and stderr to files",
+)
+@click.option(
+    "--plasma-store-socket-name",
+    default=None,
+    help="manually specify the socket name of the plasma store",
+)
+@click.option(
+    "--raylet-socket-name",
+    default=None,
+    help="manually specify the socket path of the raylet process",
+)
+@click.option(
+    "--temp-dir",
+    default=None,
+    help="manually specify the root temporary dir of the Ray process, only "
+    "works when --head is specified",
+)
+@click.option(
+    "--storage",
+    default=None,
+    help="the persistent storage URI for the cluster. Experimental.",
+)
+@click.option(
+    "--system-config",
+    default=None,
+    hidden=True,
+    type=json.loads,
+    help="Override system configuration defaults.",
+)
+@click.option(
+    "--enable-object-reconstruction",
+    is_flag=True,
+    default=False,
+    hidden=True,
+    help="Specify whether object reconstruction will be used for this cluster.",
+)
+@click.option(
+    "--metrics-export-port",
+    type=int,
+    default=None,
+    help="the port to use to expose Ray metrics through a Prometheus endpoint.",
+)
+@click.option(
+    "--no-monitor",
+    is_flag=True,
+    hidden=True,
+    default=False,
+    help="If True, the ray autoscaler monitor for this cluster will not be started.",
+)
+@click.option(
+    "--tracing-startup-hook",
+    type=str,
+    hidden=True,
+    default=None,
+    help="The function that sets up tracing with a tracing provider, remote "
+    "span processor, and additional instruments. See docs.ray.io/tracing.html "
+    "for more info.",
+)
+@click.option(
+    "--ray-debugger-external",
+    is_flag=True,
+    default=False,
+    help="Make the Ray debugger available externally to the node. This is only "
+    "safe to activate if the node is behind a firewall.",
+)
+@click.option(
+    "--disable-usage-stats",
+    is_flag=True,
+    default=False,
+    help="If True, the usage stats collection will be disabled.",
+)
+@click.option(
+    "--labels",
+    required=False,
+    hidden=True,
+    default="{}",
+    type=str,
+    help="a JSON serialized dictionary mapping label name to label value.",
+)
+@click.option(
+    "--include-log-monitor",
+    default=None,
+    type=bool,
+    help="If set to True or left unset, a log monitor will start monitoring "
+    "the log files of all processes on this node and push their contents to GCS. "
+    "Only one log monitor should be started per physical host to avoid log "
+    "duplication on the driver process.",
+)
+@add_click_logging_options
+@PublicAPI
+def start(
+    node_ip_address,
+    address,
+    port,
+    node_name,
+    redis_username,
+    redis_password,
+    redis_shard_ports,
+    object_manager_port,
+    node_manager_port,
+    gcs_server_port,
+    min_worker_port,
+    max_worker_port,
+    worker_port_list,
+    ray_client_server_port,
+    memory,
+    object_store_memory,
+    redis_max_memory,
+    num_cpus,
+    num_gpus,
+    resources,
+    head,
+    include_dashboard,
+    dashboard_host,
+    dashboard_port,
+    dashboard_agent_listen_port,
+    dashboard_agent_grpc_port,
+    dashboard_grpc_port,
+    runtime_env_agent_port,
+    block,
+    plasma_directory,
+    autoscaling_config,
+    no_redirect_output,
+    plasma_store_socket_name,
+    raylet_socket_name,
+    temp_dir,
+    storage,
+    system_config,
+    enable_object_reconstruction,
+    metrics_export_port,
+    no_monitor,
+    tracing_startup_hook,
+    ray_debugger_external,
+    disable_usage_stats,
+    labels,
+    include_log_monitor,
+):
+    """Start Ray processes manually on the local machine."""
+    # TODO(hjiang): Expose physical mode interface to ray cluster start command after
+    # all features implemented.
+
+    if gcs_server_port is not None:
+        cli_logger.error(
+            "`{}` is deprecated and ignored. Use {} to specify "
+            "GCS server port on head node.",
+            cf.bold("--gcs-server-port"),
+            cf.bold("--port"),
+        )
+    # Whether the original arguments include node_ip_address.
+    include_node_ip_address = False
+    if node_ip_address is not None:
+        include_node_ip_address = True
+        node_ip_address = services.resolve_ip_for_localhost(node_ip_address)
+
+    resources = parse_resources_json(resources, cli_logger, cf)
+    labels_dict = parse_node_labels_json(labels, cli_logger, cf)
+
+    if plasma_store_socket_name is not None:
+        warnings.warn(
+            "plasma_store_socket_name is deprecated and will be removed. You are not "
+            "supposed to specify this parameter as it's internal.",
+            DeprecationWarning,
+            stacklevel=2,
+        )
+    if raylet_socket_name is not None:
+        warnings.warn(
+            "raylet_socket_name is deprecated and will be removed. You are not "
+            "supposed to specify this parameter as it's internal.",
+            DeprecationWarning,
+            stacklevel=2,
+        )
+    if temp_dir and not head:
+        cli_logger.warning(
+            f"`--temp-dir={temp_dir}` option will be ignored. "
+            "`--head` is a required flag to use `--temp-dir`. "
+            "temp_dir is only configurable from a head node. "
+            "All the worker nodes will use the same temp_dir as a head node. "
+        )
+        temp_dir = None
+
+    redirect_output = None if not no_redirect_output else True
+
+    # no  client, no  port -> ok
+    # no  port, has client -> default to 10001
+    # has port, no  client -> value error
+    # has port, has client -> ok, check port validity
+    has_ray_client = check_ray_client_dependencies_installed()
+    if has_ray_client and ray_client_server_port is None:
+        ray_client_server_port = 10001
+
+    ray_params = ray._private.parameter.RayParams(
+        node_ip_address=node_ip_address,
+        node_name=node_name if node_name else node_ip_address,
+        min_worker_port=min_worker_port,
+        max_worker_port=max_worker_port,
+        worker_port_list=worker_port_list,
+        ray_client_server_port=ray_client_server_port,
+        object_manager_port=object_manager_port,
+        node_manager_port=node_manager_port,
+        memory=memory,
+        object_store_memory=object_store_memory,
+        redis_username=redis_username,
+        redis_password=redis_password,
+        redirect_output=redirect_output,
+        num_cpus=num_cpus,
+        num_gpus=num_gpus,
+        resources=resources,
+        labels=labels_dict,
+        autoscaling_config=autoscaling_config,
+        plasma_directory=plasma_directory,
+        huge_pages=False,
+        plasma_store_socket_name=plasma_store_socket_name,
+        raylet_socket_name=raylet_socket_name,
+        temp_dir=temp_dir,
+        storage=storage,
+        include_dashboard=include_dashboard,
+        dashboard_host=dashboard_host,
+        dashboard_port=dashboard_port,
+        dashboard_agent_listen_port=dashboard_agent_listen_port,
+        metrics_agent_port=dashboard_agent_grpc_port,
+        dashboard_grpc_port=dashboard_grpc_port,
+        runtime_env_agent_port=runtime_env_agent_port,
+        _system_config=system_config,
+        enable_object_reconstruction=enable_object_reconstruction,
+        metrics_export_port=metrics_export_port,
+        no_monitor=no_monitor,
+        tracing_startup_hook=tracing_startup_hook,
+        ray_debugger_external=ray_debugger_external,
+        enable_physical_mode=False,
+        include_log_monitor=include_log_monitor,
+    )
+
+    if ray_constants.RAY_START_HOOK in os.environ:
+        _load_class(os.environ[ray_constants.RAY_START_HOOK])(ray_params, head)
+
+    if head:
+        # Start head node.
+
+        if disable_usage_stats:
+            usage_lib.set_usage_stats_enabled_via_env_var(False)
+        usage_lib.show_usage_stats_prompt(cli=True)
+        cli_logger.newline()
+
+        if port is None:
+            port = ray_constants.DEFAULT_PORT
+
+        # Set bootstrap port.
+        assert ray_params.redis_port is None
+        assert ray_params.gcs_server_port is None
+        ray_params.gcs_server_port = port
+
+        if os.environ.get("RAY_FAKE_CLUSTER"):
+            ray_params.env_vars = {
+                "RAY_OVERRIDE_NODE_ID_FOR_TESTING": FAKE_HEAD_NODE_ID
+            }
+
+        num_redis_shards = None
+        # Start Ray on the head node.
+        if redis_shard_ports is not None and address is None:
+            redis_shard_ports = redis_shard_ports.split(",")
+            # Infer the number of Redis shards from the ports if the number is
+            # not provided.
+            num_redis_shards = len(redis_shard_ports)
+
+        # This logic is deprecated and will be removed later.
+        if address is not None:
+            cli_logger.warning(
+                "Specifying {} for external Redis address is deprecated. "
+                "Please specify environment variable {}={} instead.",
+                cf.bold("--address"),
+                cf.bold("RAY_REDIS_ADDRESS"),
+                address,
+            )
+            external_addresses = address.split(",")
+
+            # We reuse primary redis as sharding when there's only one
+            # instance provided.
+            if len(external_addresses) == 1:
+                external_addresses.append(external_addresses[0])
+
+            ray_params.update_if_absent(external_addresses=external_addresses)
+            num_redis_shards = len(external_addresses) - 1
+            if redis_username == ray_constants.REDIS_DEFAULT_USERNAME:
+                cli_logger.warning(
+                    "`{}` should not be specified as empty string if "
+                    "external Redis server(s) `{}` points to requires "
+                    "username.",
+                    cf.bold("--redis-username"),
+                    cf.bold("--address"),
+                )
+            if redis_password == ray_constants.REDIS_DEFAULT_PASSWORD:
+                cli_logger.warning(
+                    "`{}` should not be specified as empty string if "
+                    "external redis server(s) `{}` points to requires "
+                    "password.",
+                    cf.bold("--redis-password"),
+                    cf.bold("--address"),
+                )
+
+        # Get the node IP address if one is not provided.
+        ray_params.update_if_absent(node_ip_address=services.get_node_ip_address())
+        cli_logger.labeled_value("Local node IP", ray_params.node_ip_address)
+
+        # Initialize Redis settings.
+        ray_params.update_if_absent(
+            redis_shard_ports=redis_shard_ports,
+            redis_max_memory=redis_max_memory,
+            num_redis_shards=num_redis_shards,
+            redis_max_clients=None,
+        )
+
+        # Fail early when starting a new cluster when one is already running
+        if address is None:
+            default_address = f"{ray_params.node_ip_address}:{port}"
+            bootstrap_address = services.find_bootstrap_address(temp_dir)
+            if (
+                default_address == bootstrap_address
+                and bootstrap_address in services.find_gcs_addresses()
+            ):
+                # The default address is already in use by a local running GCS
+                # instance.
+                raise ConnectionError(
+                    f"Ray is trying to start at {default_address}, "
+                    f"but is already running at {bootstrap_address}. "
+                    "Please specify a different port using the `--port`"
+                    " flag of `ray start` command."
+                )
+
+        node = ray._private.node.Node(
+            ray_params, head=True, shutdown_at_exit=block, spawn_reaper=block
+        )
+
+        bootstrap_address = node.address
+
+        # this is a noop if new-style is not set, so the old logger calls
+        # are still in place
+        cli_logger.newline()
+        startup_msg = "Ray runtime started."
+        cli_logger.success("-" * len(startup_msg))
+        cli_logger.success(startup_msg)
+        cli_logger.success("-" * len(startup_msg))
+        cli_logger.newline()
+        with cli_logger.group("Next steps"):
+            dashboard_url = node.address_info["webui_url"]
+            if ray_constants.ENABLE_RAY_CLUSTER:
+                cli_logger.print("To add another node to this Ray cluster, run")
+                # NOTE(kfstorm): Java driver rely on this line to get the address
+                # of the cluster. Please be careful when updating this line.
+                cli_logger.print(
+                    cf.bold(" {} ray start --address='{}'"),
+                    f" {ray_constants.ENABLE_RAY_CLUSTERS_ENV_VAR}=1"
+                    if ray_constants.IS_WINDOWS_OR_OSX
+                    else "",
+                    bootstrap_address,
+                )
+
+            cli_logger.newline()
+            cli_logger.print("To connect to this Ray cluster:")
+            with cli_logger.indented():
+                cli_logger.print("{} ray", cf.magenta("import"))
+                cli_logger.print(
+                    "ray{}init({})",
+                    cf.magenta("."),
+                    "_node_ip_address{}{}".format(
+                        cf.magenta("="), cf.yellow("'" + node_ip_address + "'")
+                    )
+                    if include_node_ip_address
+                    else "",
+                )
+
+            if dashboard_url:
+                cli_logger.newline()
+                cli_logger.print("To submit a Ray job using the Ray Jobs CLI:")
+                cli_logger.print(
+                    cf.bold(
+                        "  RAY_ADDRESS='http://{}' ray job submit "
+                        "--working-dir . "
+                        "-- python my_script.py"
+                    ),
+                    dashboard_url,
+                )
+                cli_logger.newline()
+                cli_logger.print(
+                    "See https://docs.ray.io/en/latest/cluster/running-applications"
+                    "/job-submission/index.html "
+                )
+                cli_logger.print(
+                    "for more information on submitting Ray jobs to the Ray cluster."
+                )
+
+            cli_logger.newline()
+            cli_logger.print("To terminate the Ray runtime, run")
+            cli_logger.print(cf.bold("  ray stop"))
+
+            cli_logger.newline()
+            cli_logger.print("To view the status of the cluster, use")
+            cli_logger.print("  {}".format(cf.bold("ray status")))
+
+            if dashboard_url:
+                cli_logger.newline()
+                cli_logger.print("To monitor and debug Ray, view the dashboard at ")
+                cli_logger.print(
+                    "  {}".format(
+                        cf.bold(dashboard_url),
+                    )
+                )
+
+                cli_logger.newline()
+                cli_logger.print(
+                    cf.underlined(
+                        "If connection to the dashboard fails, check your "
+                        "firewall settings and "
+                        "network configuration."
+                    )
+                )
+        ray_params.gcs_address = bootstrap_address
+    else:
+        # Start worker node.
+        if not ray_constants.ENABLE_RAY_CLUSTER:
+            cli_logger.abort(
+                "Multi-node Ray clusters are not supported on Windows and OSX. "
+                "Restart the Ray cluster with the environment variable `{}=1` "
+                "to proceed anyway.",
+                cf.bold(ray_constants.ENABLE_RAY_CLUSTERS_ENV_VAR),
+            )
+            raise Exception(
+                "Multi-node Ray clusters are not supported on Windows and OSX. "
+                "Restart the Ray cluster with the environment variable "
+                f"`{ray_constants.ENABLE_RAY_CLUSTERS_ENV_VAR}=1` to proceed "
+                "anyway.",
+            )
+
+        # Ensure `--address` flag is specified.
+        if address is None:
+            cli_logger.abort(
+                "`{}` is a required flag unless starting a head node with `{}`.",
+                cf.bold("--address"),
+                cf.bold("--head"),
+            )
+            raise Exception(
+                "`--address` is a required flag unless starting a "
+                "head node with `--head`."
+            )
+
+        # Raise error if any head-only flag are specified.
+        head_only_flags = {
+            "--port": port,
+            "--redis-shard-ports": redis_shard_ports,
+            "--include-dashboard": include_dashboard,
+        }
+        for flag, val in head_only_flags.items():
+            if val is None:
+                continue
+            cli_logger.abort(
+                "`{}` should only be specified when starting head node with `{}`.",
+                cf.bold(flag),
+                cf.bold("--head"),
+            )
+            raise ValueError(
+                f"{flag} should only be specified when starting head node "
+                "with `--head`."
+            )
+
+        # Start Ray on a non-head node.
+        bootstrap_address = services.canonicalize_bootstrap_address(
+            address, temp_dir=temp_dir
+        )
+
+        if bootstrap_address is None:
+            cli_logger.abort(
+                "Cannot canonicalize address `{}={}`.",
+                cf.bold("--address"),
+                cf.bold(address),
+            )
+            raise Exception("Cannot canonicalize address " f"`--address={address}`.")
+
+        ray_params.gcs_address = bootstrap_address
+
+        # Get the node IP address if one is not provided.
+        ray_params.update_if_absent(
+            node_ip_address=services.get_node_ip_address(bootstrap_address)
+        )
+
+        cli_logger.labeled_value("Local node IP", ray_params.node_ip_address)
+
+        node = ray._private.node.Node(
+            ray_params, head=False, shutdown_at_exit=block, spawn_reaper=block
+        )
+        temp_dir = node.get_temp_dir_path()
+
+        # TODO(hjiang): Validate whether specified resource is true for physical
+        # resource.
+
+        # Ray and Python versions should probably be checked before
+        # initializing Node.
+        node.check_version_info()
+
+        cli_logger.newline()
+        startup_msg = "Ray runtime started."
+        cli_logger.success("-" * len(startup_msg))
+        cli_logger.success(startup_msg)
+        cli_logger.success("-" * len(startup_msg))
+        cli_logger.newline()
+        cli_logger.print("To terminate the Ray runtime, run")
+        cli_logger.print(cf.bold("  ray stop"))
+        cli_logger.flush()
+
+    assert ray_params.gcs_address is not None
+    ray._private.utils.write_ray_address(ray_params.gcs_address, temp_dir)
+
+    if block:
+        cli_logger.newline()
+        with cli_logger.group(cf.bold("--block")):
+            cli_logger.print(
+                "This command will now block forever until terminated by a signal."
+            )
+            cli_logger.print(
+                "Running subprocesses are monitored and a message will be "
+                "printed if any of them terminate unexpectedly. Subprocesses "
+                "exit with SIGTERM will be treated as graceful, thus NOT reported."
+            )
+            cli_logger.flush()
+
+        while True:
+            time.sleep(1)
+            deceased = node.dead_processes()
+
+            # Report unexpected exits of subprocesses with unexpected return codes.
+            # We are explicitly expecting SIGTERM because this is how `ray stop` sends
+            # shutdown signal to subprocesses, i.e. log_monitor, raylet...
+            # NOTE(rickyyx): We are treating 128+15 as an expected return code since
+            # this is what autoscaler/_private/monitor.py does upon SIGTERM
+            # handling.
+            expected_return_codes = [
+                0,
+                signal.SIGTERM,
+                -1 * signal.SIGTERM,
+                128 + signal.SIGTERM,
+            ]
+            unexpected_deceased = [
+                (process_type, process)
+                for process_type, process in deceased
+                if process.returncode not in expected_return_codes
+            ]
+            if len(unexpected_deceased) > 0:
+                cli_logger.newline()
+                cli_logger.error("Some Ray subprocesses exited unexpectedly:")
+
+                with cli_logger.indented():
+                    for process_type, process in unexpected_deceased:
+                        cli_logger.error(
+                            "{}",
+                            cf.bold(str(process_type)),
+                            _tags={"exit code": str(process.returncode)},
+                        )
+
+                cli_logger.newline()
+                cli_logger.error("Remaining processes will be killed.")
+                # explicitly kill all processes since atexit handlers
+                # will not exit with errors.
+                node.kill_all_processes(check_alive=False, allow_graceful=False)
+                os._exit(1)
+        # not-reachable
+
+
+@cli.command()
+@click.option(
+    "-f",
+    "--force",
+    is_flag=True,
+    help="If set, ray will send SIGKILL instead of SIGTERM.",
+)
+@click.option(
+    "-g",
+    "--grace-period",
+    default=16,
+    help=(
+        "The time in seconds ray waits for processes to be properly terminated. "
+        "If processes are not terminated within the grace period, "
+        "they are forcefully terminated after the grace period. "
+    ),
+)
+@add_click_logging_options
+@PublicAPI
+def stop(force: bool, grace_period: int):
+    """Stop Ray processes manually on the local machine."""
+    is_linux = sys.platform.startswith("linux")
+    total_procs_found = 0
+    total_procs_stopped = 0
+    procs_not_gracefully_killed = []
+
+    def kill_procs(
+        force: bool, grace_period: int, processes_to_kill: List[str]
+    ) -> Tuple[int, int, List[psutil.Process]]:
+        """Find all processes from `processes_to_kill` and terminate them.
+
+        Unless `force` is specified, it gracefully kills processes. If
+        processes are not cleaned within `grace_period`, it force kill all
+        remaining processes.
+
+        Returns:
+            total_procs_found: Total number of processes found from
+                `processes_to_kill` is added.
+            total_procs_stopped: Total number of processes gracefully
+                stopped from `processes_to_kill` is added.
+            procs_not_gracefully_killed: If processes are not killed
+                gracefully, they are added here.
+        """
+        process_infos = []
+        for proc in psutil.process_iter(["name", "cmdline"]):
+            try:
+                process_infos.append((proc, proc.name(), proc.cmdline()))
+            except psutil.Error:
+                pass
+
+        stopped = []
+        for keyword, filter_by_cmd in processes_to_kill:
+            if filter_by_cmd and is_linux and len(keyword) > 15:
+                # getting here is an internal bug, so we do not use cli_logger
+                msg = (
+                    "The filter string should not be more than {} "
+                    "characters. Actual length: {}. Filter: {}"
+                ).format(15, len(keyword), keyword)
+                raise ValueError(msg)
+
+            found = []
+            for candidate in process_infos:
+                proc, proc_cmd, proc_args = candidate
+                corpus = (
+                    proc_cmd if filter_by_cmd else subprocess.list2cmdline(proc_args)
+                )
+                if keyword in corpus:
+                    found.append(candidate)
+            for proc, proc_cmd, proc_args in found:
+                proc_string = str(subprocess.list2cmdline(proc_args))
+                try:
+                    if force:
+                        proc.kill()
+                    else:
+                        # TODO(mehrdadn): On Windows, this is forceful termination.
+                        # We don't want CTRL_BREAK_EVENT, because that would
+                        # terminate the entire process group. What to do?
+                        proc.terminate()
+
+                    if force:
+                        cli_logger.verbose(
+                            "Killed `{}` {} ",
+                            cf.bold(proc_string),
+                            cf.dimmed("(via SIGKILL)"),
+                        )
+                    else:
+                        cli_logger.verbose(
+                            "Send termination request to `{}` {}",
+                            cf.bold(proc_string),
+                            cf.dimmed("(via SIGTERM)"),
+                        )
+
+                    stopped.append(proc)
+                except psutil.NoSuchProcess:
+                    cli_logger.verbose(
+                        "Attempted to stop `{}`, but process was already dead.",
+                        cf.bold(proc_string),
+                    )
+                except (psutil.Error, OSError) as ex:
+                    cli_logger.error(
+                        "Could not terminate `{}` due to {}",
+                        cf.bold(proc_string),
+                        str(ex),
+                    )
+
+        # Wait for the processes to actually stop.
+        # Dedup processes.
+        stopped, alive = psutil.wait_procs(stopped, timeout=0)
+        procs_to_kill = stopped + alive
+        total_found = len(procs_to_kill)
+
+        # Wait for grace period to terminate processes.
+        gone_procs = set()
+
+        def on_terminate(proc):
+            gone_procs.add(proc)
+            cli_logger.print(f"{len(gone_procs)}/{total_found} stopped.", end="\r")
+
+        stopped, alive = psutil.wait_procs(
+            procs_to_kill, timeout=grace_period, callback=on_terminate
+        )
+        total_stopped = len(stopped)
+
+        # For processes that are not killed within the grace period,
+        # we send force termination signals.
+        for proc in alive:
+            proc.kill()
+        # Wait a little bit to make sure processes are killed forcefully.
+        psutil.wait_procs(alive, timeout=2)
+        return total_found, total_stopped, alive
+
+    # Process killing procedure: we put processes into 3 buckets.
+    # Bucket 1: raylet
+    # Bucket 2: all other processes, e.g. dashboard, runtime env agents
+    # Bucket 3: gcs_server.
+    #
+    # For each bucket, we send sigterm to all processes, then wait for 30s, then if
+    # they are still alive, send sigkill.
+    processes_to_kill = RAY_PROCESSES
+    # Raylet should exit before all other processes exit.
+    # Otherwise, fate-sharing agents will complain and exit.
+    assert processes_to_kill[0][0] == "raylet"
+
+    # GCS should exit after all other processes exit.
+    # Otherwise, some of processes may exit with an unexpected
+    # exit code which breaks ray start --block.
+    assert processes_to_kill[-1][0] == "gcs_server"
+
+    buckets = [[processes_to_kill[0]], processes_to_kill[1:-1], [processes_to_kill[-1]]]
+
+    for bucket in buckets:
+        found, stopped, alive = kill_procs(force, grace_period / len(buckets), bucket)
+        total_procs_found += found
+        total_procs_stopped += stopped
+        procs_not_gracefully_killed.extend(alive)
+
+    # Print the termination result.
+    if total_procs_found == 0:
+        cli_logger.print("Did not find any active Ray processes.")
+    else:
+        if total_procs_stopped == total_procs_found:
+            cli_logger.success("Stopped all {} Ray processes.", total_procs_stopped)
+        else:
+            cli_logger.warning(
+                f"Stopped only {total_procs_stopped} out of {total_procs_found} "
+                f"Ray processes within the grace period {grace_period} seconds. "
+                f"Set `{cf.bold('-v')}` to see more details. "
+                f"Remaining processes {procs_not_gracefully_killed} "
+                "will be forcefully terminated.",
+            )
+            cli_logger.warning(
+                f"You can also use `{cf.bold('--force')}` to forcefully terminate "
+                "processes or set higher `--grace-period` to wait longer time for "
+                "proper termination."
+            )
+
+    # NOTE(swang): This will not reset the cluster address for a user-defined
+    # temp_dir. This is fine since it will get overwritten the next time we
+    # call `ray start`.
+    ray._private.utils.reset_ray_address()
+
+
+@cli.command()
+@click.argument("cluster_config_file", required=True, type=str)
+@click.option(
+    "--min-workers",
+    required=False,
+    type=int,
+    help="Override the configured min worker node count for the cluster.",
+)
+@click.option(
+    "--max-workers",
+    required=False,
+    type=int,
+    help="Override the configured max worker node count for the cluster.",
+)
+@click.option(
+    "--no-restart",
+    is_flag=True,
+    default=False,
+    help=(
+        "Whether to skip restarting Ray services during the update. "
+        "This avoids interrupting running jobs."
+    ),
+)
+@click.option(
+    "--restart-only",
+    is_flag=True,
+    default=False,
+    help=(
+        "Whether to skip running setup commands and only restart Ray. "
+        "This cannot be used with 'no-restart'."
+    ),
+)
+@click.option(
+    "--yes", "-y", is_flag=True, default=False, help="Don't ask for confirmation."
+)
+@click.option(
+    "--cluster-name",
+    "-n",
+    required=False,
+    type=str,
+    help="Override the configured cluster name.",
+)
+@click.option(
+    "--no-config-cache",
+    is_flag=True,
+    default=False,
+    help="Disable the local cluster config cache.",
+)
+@click.option(
+    "--redirect-command-output",
+    is_flag=True,
+    default=False,
+    help="Whether to redirect command output to a file.",
+)
+@click.option(
+    "--use-login-shells/--use-normal-shells",
+    is_flag=True,
+    default=True,
+    help=(
+        "Ray uses login shells (bash --login -i) to run cluster commands "
+        "by default. If your workflow is compatible with normal shells, "
+        "this can be disabled for a better user experience."
+    ),
+)
+@click.option(
+    "--disable-usage-stats",
+    is_flag=True,
+    default=False,
+    help="If True, the usage stats collection will be disabled.",
+)
+@add_click_logging_options
+@PublicAPI
+def up(
+    cluster_config_file,
+    min_workers,
+    max_workers,
+    no_restart,
+    restart_only,
+    yes,
+    cluster_name,
+    no_config_cache,
+    redirect_command_output,
+    use_login_shells,
+    disable_usage_stats,
+):
+    """Create or update a Ray cluster."""
+    if disable_usage_stats:
+        usage_lib.set_usage_stats_enabled_via_env_var(False)
+
+    if restart_only or no_restart:
+        cli_logger.doassert(
+            restart_only != no_restart,
+            "`{}` is incompatible with `{}`.",
+            cf.bold("--restart-only"),
+            cf.bold("--no-restart"),
+        )
+        assert (
+            restart_only != no_restart
+        ), "Cannot set both 'restart_only' and 'no_restart' at the same time!"
+
+    if urllib.parse.urlparse(cluster_config_file).scheme in ("http", "https"):
+        try:
+            response = urllib.request.urlopen(cluster_config_file, timeout=5)
+            content = response.read()
+            file_name = cluster_config_file.split("/")[-1]
+            with open(file_name, "wb") as f:
+                f.write(content)
+            cluster_config_file = file_name
+        except urllib.error.HTTPError as e:
+            cli_logger.warning("{}", str(e))
+            cli_logger.warning("Could not download remote cluster configuration file.")
+    create_or_update_cluster(
+        config_file=cluster_config_file,
+        override_min_workers=min_workers,
+        override_max_workers=max_workers,
+        no_restart=no_restart,
+        restart_only=restart_only,
+        yes=yes,
+        override_cluster_name=cluster_name,
+        no_config_cache=no_config_cache,
+        redirect_command_output=redirect_command_output,
+        use_login_shells=use_login_shells,
+    )
+
+
+@cli.command()
+@click.argument("cluster_config_file", required=True, type=str)
+@click.option(
+    "--yes", "-y", is_flag=True, default=False, help="Don't ask for confirmation."
+)
+@click.option(
+    "--workers-only", is_flag=True, default=False, help="Only destroy the workers."
+)
+@click.option(
+    "--cluster-name",
+    "-n",
+    required=False,
+    type=str,
+    help="Override the configured cluster name.",
+)
+@click.option(
+    "--keep-min-workers",
+    is_flag=True,
+    default=False,
+    help="Retain the minimal amount of workers specified in the config.",
+)
+@add_click_logging_options
+@PublicAPI
+def down(cluster_config_file, yes, workers_only, cluster_name, keep_min_workers):
+    """Tear down a Ray cluster."""
+    teardown_cluster(
+        cluster_config_file, yes, workers_only, cluster_name, keep_min_workers
+    )
+
+
+@cli.command(hidden=True)
+@click.argument("cluster_config_file", required=True, type=str)
+@click.option(
+    "--yes", "-y", is_flag=True, default=False, help="Don't ask for confirmation."
+)
+@click.option(
+    "--hard",
+    is_flag=True,
+    default=False,
+    help="Terminates the node via node provider (defaults to a 'soft kill'"
+    " which terminates Ray but does not actually delete the instances).",
+)
+@click.option(
+    "--cluster-name",
+    "-n",
+    required=False,
+    type=str,
+    help="Override the configured cluster name.",
+)
+def kill_random_node(cluster_config_file, yes, hard, cluster_name):
+    """Kills a random Ray node. For testing purposes only."""
+    click.echo(
+        "Killed node with IP " + kill_node(cluster_config_file, yes, hard, cluster_name)
+    )
+
+
+@cli.command()
+@click.argument("cluster_config_file", required=True, type=str)
+@click.option(
+    "--lines", required=False, default=100, type=int, help="Number of lines to tail."
+)
+@click.option(
+    "--cluster-name",
+    "-n",
+    required=False,
+    type=str,
+    help="Override the configured cluster name.",
+)
+@add_click_logging_options
+def monitor(cluster_config_file, lines, cluster_name):
+    """Tails the autoscaler logs of a Ray cluster."""
+    monitor_cluster(cluster_config_file, lines, cluster_name)
+
+
+@cli.command()
+@click.argument("cluster_config_file", required=True, type=str)
+@click.option(
+    "--start", is_flag=True, default=False, help="Start the cluster if needed."
+)
+@click.option(
+    "--screen", is_flag=True, default=False, help="Run the command in screen."
+)
+@click.option("--tmux", is_flag=True, default=False, help="Run the command in tmux.")
+@click.option(
+    "--cluster-name",
+    "-n",
+    required=False,
+    type=str,
+    help="Override the configured cluster name.",
+)
+@click.option(
+    "--no-config-cache",
+    is_flag=True,
+    default=False,
+    help="Disable the local cluster config cache.",
+)
+@click.option("--new", "-N", is_flag=True, help="Force creation of a new screen.")
+@click.option(
+    "--port-forward",
+    "-p",
+    required=False,
+    multiple=True,
+    type=int,
+    help="Port to forward. Use this multiple times to forward multiple ports.",
+)
+@add_click_logging_options
+@PublicAPI
+def attach(
+    cluster_config_file,
+    start,
+    screen,
+    tmux,
+    cluster_name,
+    no_config_cache,
+    new,
+    port_forward,
+):
+    """Create or attach to a SSH session to a Ray cluster."""
+    port_forward = [(port, port) for port in list(port_forward)]
+    attach_cluster(
+        cluster_config_file,
+        start,
+        screen,
+        tmux,
+        cluster_name,
+        no_config_cache=no_config_cache,
+        new=new,
+        port_forward=port_forward,
+    )
+
+
+@cli.command()
+@click.argument("cluster_config_file", required=True, type=str)
+@click.argument("source", required=False, type=str)
+@click.argument("target", required=False, type=str)
+@click.option(
+    "--cluster-name",
+    "-n",
+    required=False,
+    type=str,
+    help="Override the configured cluster name.",
+)
+@add_click_logging_options
+def rsync_down(cluster_config_file, source, target, cluster_name):
+    """Download specific files from a Ray cluster."""
+    rsync(cluster_config_file, source, target, cluster_name, down=True)
+
+
+@cli.command()
+@click.argument("cluster_config_file", required=True, type=str)
+@click.argument("source", required=False, type=str)
+@click.argument("target", required=False, type=str)
+@click.option(
+    "--cluster-name",
+    "-n",
+    required=False,
+    type=str,
+    help="Override the configured cluster name.",
+)
+@click.option(
+    "--all-nodes",
+    "-A",
+    is_flag=True,
+    required=False,
+    help="Upload to all nodes (workers and head).",
+)
+@add_click_logging_options
+def rsync_up(cluster_config_file, source, target, cluster_name, all_nodes):
+    """Upload specific files to a Ray cluster."""
+    if all_nodes:
+        cli_logger.warning(
+            "WARNING: the `all_nodes` option is deprecated and will be "
+            "removed in the future. "
+            "Rsync to worker nodes is not reliable since workers may be "
+            "added during autoscaling. Please use the `file_mounts` "
+            "feature instead for consistent file sync in autoscaling clusters"
+        )
+
+    rsync(
+        cluster_config_file,
+        source,
+        target,
+        cluster_name,
+        down=False,
+        all_nodes=all_nodes,
+    )
+
+
+@cli.command(context_settings={"ignore_unknown_options": True})
+@click.argument("cluster_config_file", required=True, type=str)
+@click.option(
+    "--stop",
+    is_flag=True,
+    default=False,
+    help="Stop the cluster after the command finishes running.",
+)
+@click.option(
+    "--start", is_flag=True, default=False, help="Start the cluster if needed."
+)
+@click.option(
+    "--screen", is_flag=True, default=False, help="Run the command in a screen."
+)
+@click.option("--tmux", is_flag=True, default=False, help="Run the command in tmux.")
+@click.option(
+    "--cluster-name",
+    "-n",
+    required=False,
+    type=str,
+    help="Override the configured cluster name.",
+)
+@click.option(
+    "--no-config-cache",
+    is_flag=True,
+    default=False,
+    help="Disable the local cluster config cache.",
+)
+@click.option(
+    "--port-forward",
+    "-p",
+    required=False,
+    multiple=True,
+    type=int,
+    help="Port to forward. Use this multiple times to forward multiple ports.",
+)
+@click.argument("script", required=True, type=str)
+@click.option(
+    "--args",
+    required=False,
+    type=str,
+    help="(deprecated) Use '-- --arg1 --arg2' for script args.",
+)
+@click.argument("script_args", nargs=-1)
+@click.option(
+    "--disable-usage-stats",
+    is_flag=True,
+    default=False,
+    help="If True, the usage stats collection will be disabled.",
+)
+@click.option(
+    "--extra-screen-args",
+    default=None,
+    help="if screen is enabled, add the provided args to it. A useful example "
+    "usage scenario is passing --extra-screen-args='-Logfile /full/path/blah_log.txt'"
+    " as it redirects screen output also to a custom file",
+)
+@add_click_logging_options
+def submit(
+    cluster_config_file,
+    screen,
+    tmux,
+    stop,
+    start,
+    cluster_name,
+    no_config_cache,
+    port_forward,
+    script,
+    args,
+    script_args,
+    disable_usage_stats,
+    extra_screen_args: Optional[str] = None,
+):
+    """Uploads and runs a script on the specified cluster.
+
+    The script is automatically synced to the following location:
+
+        os.path.join("~", os.path.basename(script))
+
+    Example:
+        ray submit [CLUSTER.YAML] experiment.py -- --smoke-test
+    """
+    cli_logger.doassert(
+        not (screen and tmux),
+        "`{}` and `{}` are incompatible.",
+        cf.bold("--screen"),
+        cf.bold("--tmux"),
+    )
+    cli_logger.doassert(
+        not (script_args and args),
+        "`{0}` and `{1}` are incompatible. Use only `{1}`.\nExample: `{2}`",
+        cf.bold("--args"),
+        cf.bold("-- <args ...>"),
+        cf.bold("ray submit script.py -- --arg=123 --flag"),
+    )
+
+    assert not (screen and tmux), "Can specify only one of `screen` or `tmux`."
+    assert not (script_args and args), "Use -- --arg1 --arg2 for script args."
+
+    if (extra_screen_args is not None) and (not screen):
+        cli_logger.abort(
+            "To use extra_screen_args, it is required to use the --screen flag"
+        )
+
+    if args:
+        cli_logger.warning(
+            "`{}` is deprecated and will be removed in the future.", cf.bold("--args")
+        )
+        cli_logger.warning(
+            "Use `{}` instead. Example: `{}`.",
+            cf.bold("-- <args ...>"),
+            cf.bold("ray submit script.py -- --arg=123 --flag"),
+        )
+        cli_logger.newline()
+
+    if start:
+        if disable_usage_stats:
+            usage_lib.set_usage_stats_enabled_via_env_var(False)
+
+        create_or_update_cluster(
+            config_file=cluster_config_file,
+            override_min_workers=None,
+            override_max_workers=None,
+            no_restart=False,
+            restart_only=False,
+            yes=True,
+            override_cluster_name=cluster_name,
+            no_config_cache=no_config_cache,
+            redirect_command_output=False,
+            use_login_shells=True,
+        )
+    target = os.path.basename(script)
+    target = os.path.join("~", target)
+    rsync(
+        cluster_config_file,
+        script,
+        target,
+        cluster_name,
+        no_config_cache=no_config_cache,
+        down=False,
+    )
+
+    command_parts = ["python", target]
+    if script_args:
+        command_parts += list(script_args)
+    elif args is not None:
+        command_parts += [args]
+
+    port_forward = [(port, port) for port in list(port_forward)]
+    cmd = " ".join(command_parts)
+    exec_cluster(
+        cluster_config_file,
+        cmd=cmd,
+        run_env="docker",
+        screen=screen,
+        tmux=tmux,
+        stop=stop,
+        start=False,
+        override_cluster_name=cluster_name,
+        no_config_cache=no_config_cache,
+        port_forward=port_forward,
+        extra_screen_args=extra_screen_args,
+    )
+
+
+@cli.command()
+@click.argument("cluster_config_file", required=True, type=str)
+@click.argument("cmd", required=True, type=str)
+@click.option(
+    "--run-env",
+    required=False,
+    type=click.Choice(RUN_ENV_TYPES),
+    default="auto",
+    help="Choose whether to execute this command in a container or directly on"
+    " the cluster head. Only applies when docker is configured in the YAML.",
+)
+@click.option(
+    "--stop",
+    is_flag=True,
+    default=False,
+    help="Stop the cluster after the command finishes running.",
+)
+@click.option(
+    "--start", is_flag=True, default=False, help="Start the cluster if needed."
+)
+@click.option(
+    "--screen", is_flag=True, default=False, help="Run the command in a screen."
+)
+@click.option("--tmux", is_flag=True, default=False, help="Run the command in tmux.")
+@click.option(
+    "--cluster-name",
+    "-n",
+    required=False,
+    type=str,
+    help="Override the configured cluster name.",
+)
+@click.option(
+    "--no-config-cache",
+    is_flag=True,
+    default=False,
+    help="Disable the local cluster config cache.",
+)
+@click.option(
+    "--port-forward",
+    "-p",
+    required=False,
+    multiple=True,
+    type=int,
+    help="Port to forward. Use this multiple times to forward multiple ports.",
+)
+@click.option(
+    "--disable-usage-stats",
+    is_flag=True,
+    default=False,
+    help="If True, the usage stats collection will be disabled.",
+)
+@add_click_logging_options
+def exec(
+    cluster_config_file,
+    cmd,
+    run_env,
+    screen,
+    tmux,
+    stop,
+    start,
+    cluster_name,
+    no_config_cache,
+    port_forward,
+    disable_usage_stats,
+):
+    """Execute a command via SSH on a Ray cluster."""
+    port_forward = [(port, port) for port in list(port_forward)]
+
+    if start:
+        if disable_usage_stats:
+            usage_lib.set_usage_stats_enabled_via_env_var(False)
+
+    exec_cluster(
+        cluster_config_file,
+        cmd=cmd,
+        run_env=run_env,
+        screen=screen,
+        tmux=tmux,
+        stop=stop,
+        start=start,
+        override_cluster_name=cluster_name,
+        no_config_cache=no_config_cache,
+        port_forward=port_forward,
+        _allow_uninitialized_state=True,
+    )
+
+
+@cli.command()
+@click.argument("cluster_config_file", required=True, type=str)
+@click.option(
+    "--cluster-name",
+    "-n",
+    required=False,
+    type=str,
+    help="Override the configured cluster name.",
+)
+def get_head_ip(cluster_config_file, cluster_name):
+    """Return the head node IP of a Ray cluster."""
+    click.echo(get_head_node_ip(cluster_config_file, cluster_name))
+
+
+@cli.command()
+@click.argument("cluster_config_file", required=True, type=str)
+@click.option(
+    "--cluster-name",
+    "-n",
+    required=False,
+    type=str,
+    help="Override the configured cluster name.",
+)
+def get_worker_ips(cluster_config_file, cluster_name):
+    """Return the list of worker IPs of a Ray cluster."""
+    worker_ips = get_worker_node_ips(cluster_config_file, cluster_name)
+    click.echo("\n".join(worker_ips))
+
+
+@cli.command()
+def disable_usage_stats():
+    """Disable usage stats collection.
+
+    This will not affect the current running clusters
+    but clusters launched in the future.
+    """
+    usage_lib.set_usage_stats_enabled_via_config(enabled=False)
+    print(
+        "Usage stats disabled for future clusters. "
+        "Restart any current running clusters for this to take effect."
+    )
+
+
+@cli.command()
+def enable_usage_stats():
+    """Enable usage stats collection.
+
+    This will not affect the current running clusters
+    but clusters launched in the future.
+    """
+    usage_lib.set_usage_stats_enabled_via_config(enabled=True)
+    print(
+        "Usage stats enabled for future clusters. "
+        "Restart any current running clusters for this to take effect."
+    )
+
+
+@cli.command()
+def stack():
+    """Take a stack dump of all Python workers on the local machine."""
+    COMMAND = """
+pyspy=`which py-spy`
+if [ ! -e "$pyspy" ]; then
+    echo "ERROR: Please 'pip install py-spy'" \
+        "or 'pip install ray[default]' first."
+    exit 1
+fi
+# Set IFS to iterate over lines instead of over words.
+export IFS="
+"
+# Call sudo to prompt for password before anything has been printed.
+sudo true
+workers=$(
+    ps aux | grep -E ' ray::|default_worker.py' | grep -v raylet | grep -v grep
+)
+for worker in $workers; do
+    echo "Stack dump for $worker";
+    pid=`echo $worker | awk '{print $2}'`;
+    case "$(uname -s)" in
+        Linux*) native=--native;;
+        *)      native=;;
+    esac
+    sudo $pyspy dump --pid $pid $native;
+    echo;
+done
+    """
+    subprocess.call(COMMAND, shell=True)
+
+
+@cli.command()
+def microbenchmark():
+    """Run a local Ray microbenchmark on the current machine."""
+    from ray._private.ray_perf import main
+
+    main()
+
+
+@cli.command()
+@click.option(
+    "--address",
+    required=False,
+    type=str,
+    help="Override the Ray address to connect to.",
+)
+def timeline(address):
+    """Take a Chrome tracing timeline for a Ray cluster."""
+    address = services.canonicalize_bootstrap_address_or_die(address)
+    logger.info(f"Connecting to Ray instance at {address}.")
+    ray.init(address=address)
+    time = datetime.today().strftime("%Y-%m-%d_%H-%M-%S")
+    filename = os.path.join(
+        ray._private.utils.get_user_temp_dir(), f"ray-timeline-{time}.json"
+    )
+    ray.timeline(filename=filename)
+    size = os.path.getsize(filename)
+    logger.info(f"Trace file written to {filename} ({size} bytes).")
+    logger.info("You can open this with chrome://tracing in the Chrome browser.")
+
+
+@cli.command()
+@click.option(
+    "--address", required=False, type=str, help="Override the address to connect to."
+)
+@click.option(
+    "--group-by",
+    type=click.Choice(["NODE_ADDRESS", "STACK_TRACE"]),
+    default="NODE_ADDRESS",
+    help="Group object references by a GroupByType \
+(e.g. NODE_ADDRESS or STACK_TRACE).",
+)
+@click.option(
+    "--sort-by",
+    type=click.Choice(["PID", "OBJECT_SIZE", "REFERENCE_TYPE"]),
+    default="OBJECT_SIZE",
+    help="Sort object references in ascending order by a SortingType \
+(e.g. PID, OBJECT_SIZE, or REFERENCE_TYPE).",
+)
+@click.option(
+    "--units",
+    type=click.Choice(["B", "KB", "MB", "GB"]),
+    default="B",
+    help="Specify unit metrics for displaying object sizes \
+(e.g. B, KB, MB, GB).",
+)
+@click.option(
+    "--no-format",
+    is_flag=True,
+    type=bool,
+    default=True,
+    help="Display unformatted results. Defaults to true when \
+terminal width is less than 137 characters.",
+)
+@click.option(
+    "--stats-only", is_flag=True, default=False, help="Display plasma store stats only."
+)
+@click.option(
+    "--num-entries",
+    "--n",
+    type=int,
+    default=None,
+    help="Specify number of sorted entries per group.",
+)
+def memory(
+    address,
+    group_by,
+    sort_by,
+    units,
+    no_format,
+    stats_only,
+    num_entries,
+):
+    """Print object references held in a Ray cluster."""
+    address = services.canonicalize_bootstrap_address_or_die(address)
+    gcs_client = ray._raylet.GcsClient(address=address)
+    _check_ray_version(gcs_client)
+    time = datetime.now()
+    header = "=" * 8 + f" Object references status: {time} " + "=" * 8
+    mem_stats = memory_summary(
+        address,
+        group_by,
+        sort_by,
+        units,
+        no_format,
+        stats_only,
+        num_entries,
+    )
+    print(f"{header}\n{mem_stats}")
+
+
+@cli.command()
+@click.option(
+    "--address", required=False, type=str, help="Override the address to connect to."
+)
+@click.option(
+    "-v",
+    "--verbose",
+    required=False,
+    is_flag=True,
+    hidden=True,
+    help="Experimental: Display additional debuggging information.",
+)
+@PublicAPI
+def status(address: str, verbose: bool):
+    """Print cluster status, including autoscaling info."""
+    address = services.canonicalize_bootstrap_address_or_die(address)
+    gcs_client = ray._raylet.GcsClient(address=address)
+    _check_ray_version(gcs_client)
+    ray.experimental.internal_kv._initialize_internal_kv(gcs_client)
+    status = gcs_client.internal_kv_get(ray_constants.DEBUG_AUTOSCALING_STATUS.encode())
+    error = gcs_client.internal_kv_get(ray_constants.DEBUG_AUTOSCALING_ERROR.encode())
+    print(debug_status(status, error, verbose=verbose, address=address))
+
+
+@cli.command(hidden=True)
+@click.option(
+    "--stream",
+    "-S",
+    required=False,
+    type=bool,
+    is_flag=True,
+    default=False,
+    help="If True, will stream the binary archive contents to stdout",
+)
+@click.option(
+    "--output", "-o", required=False, type=str, default=None, help="Output file."
+)
+@click.option(
+    "--logs/--no-logs",
+    is_flag=True,
+    default=True,
+    help="Collect logs from ray session dir",
+)
+@click.option(
+    "--debug-state/--no-debug-state",
+    is_flag=True,
+    default=True,
+    help="Collect debug_state.txt from ray session dir",
+)
+@click.option(
+    "--pip/--no-pip", is_flag=True, default=True, help="Collect installed pip packages"
+)
+@click.option(
+    "--processes/--no-processes",
+    is_flag=True,
+    default=True,
+    help="Collect info on running processes",
+)
+@click.option(
+    "--processes-verbose/--no-processes-verbose",
+    is_flag=True,
+    default=True,
+    help="Increase process information verbosity",
+)
+@click.option(
+    "--tempfile",
+    "-T",
+    required=False,
+    type=str,
+    default=None,
+    help="Temporary file to use",
+)
+def local_dump(
+    stream: bool = False,
+    output: Optional[str] = None,
+    logs: bool = True,
+    debug_state: bool = True,
+    pip: bool = True,
+    processes: bool = True,
+    processes_verbose: bool = False,
+    tempfile: Optional[str] = None,
+):
+    """Collect local data and package into an archive.
+
+    Usage:
+
+        ray local-dump [--stream/--output file]
+
+    This script is called on remote nodes to fetch their data.
+    """
+    # This may stream data to stdout, so no printing here
+    get_local_dump_archive(
+        stream=stream,
+        output=output,
+        logs=logs,
+        debug_state=debug_state,
+        pip=pip,
+        processes=processes,
+        processes_verbose=processes_verbose,
+        tempfile=tempfile,
+    )
+
+
+@cli.command()
+@click.argument("cluster_config_file", required=False, type=str)
+@click.option(
+    "--host",
+    "-h",
+    required=False,
+    type=str,
+    help="Single or list of hosts, separated by comma.",
+)
+@click.option(
+    "--ssh-user",
+    "-U",
+    required=False,
+    type=str,
+    default=None,
+    help="Username of the SSH user.",
+)
+@click.option(
+    "--ssh-key",
+    "-K",
+    required=False,
+    type=str,
+    default=None,
+    help="Path to the SSH key file.",
+)
+@click.option(
+    "--docker",
+    "-d",
+    required=False,
+    type=str,
+    default=None,
+    help="Name of the docker container, if applicable.",
+)
+@click.option(
+    "--local",
+    "-L",
+    required=False,
+    type=bool,
+    is_flag=True,
+    default=None,
+    help="Also include information about the local node.",
+)
+@click.option(
+    "--output", "-o", required=False, type=str, default=None, help="Output file."
+)
+@click.option(
+    "--logs/--no-logs",
+    is_flag=True,
+    default=True,
+    help="Collect logs from ray session dir",
+)
+@click.option(
+    "--debug-state/--no-debug-state",
+    is_flag=True,
+    default=True,
+    help="Collect debug_state.txt from ray log dir",
+)
+@click.option(
+    "--pip/--no-pip", is_flag=True, default=True, help="Collect installed pip packages"
+)
+@click.option(
+    "--processes/--no-processes",
+    is_flag=True,
+    default=True,
+    help="Collect info on running processes",
+)
+@click.option(
+    "--processes-verbose/--no-processes-verbose",
+    is_flag=True,
+    default=True,
+    help="Increase process information verbosity",
+)
+@click.option(
+    "--tempfile",
+    "-T",
+    required=False,
+    type=str,
+    default=None,
+    help="Temporary file to use",
+)
+def cluster_dump(
+    cluster_config_file: Optional[str] = None,
+    host: Optional[str] = None,
+    ssh_user: Optional[str] = None,
+    ssh_key: Optional[str] = None,
+    docker: Optional[str] = None,
+    local: Optional[bool] = None,
+    output: Optional[str] = None,
+    logs: bool = True,
+    debug_state: bool = True,
+    pip: bool = True,
+    processes: bool = True,
+    processes_verbose: bool = False,
+    tempfile: Optional[str] = None,
+):
+    """Get log data from one or more nodes.
+
+    Best used with Ray cluster configs:
+
+        ray cluster-dump [cluster.yaml]
+
+    Include the --local flag to also collect and include data from the
+    local node.
+
+    Missing fields will be tried to be auto-filled.
+
+    You can also manually specify a list of hosts using the
+    ``--host <host1,host2,...>`` parameter.
+    """
+    archive_path = get_cluster_dump_archive(
+        cluster_config_file=cluster_config_file,
+        host=host,
+        ssh_user=ssh_user,
+        ssh_key=ssh_key,
+        docker=docker,
+        local=local,
+        output=output,
+        logs=logs,
+        debug_state=debug_state,
+        pip=pip,
+        processes=processes,
+        processes_verbose=processes_verbose,
+        tempfile=tempfile,
+    )
+    if archive_path:
+        click.echo(f"Created archive: {archive_path}")
+    else:
+        click.echo("Could not create archive.")
+
+
+@cli.command(hidden=True)
+@click.option(
+    "--address", required=False, type=str, help="Override the address to connect to."
+)
+def global_gc(address):
+    """Trigger Python garbage collection on all cluster workers."""
+    ray.init(address=address)
+    ray._private.internal_api.global_gc()
+    print("Triggered gc.collect() on all workers.")
+
+
+@cli.command(hidden=True)
+@click.option(
+    "--address", required=False, type=str, help="Override the address to connect to."
+)
+@click.option(
+    "--node-id",
+    required=True,
+    type=str,
+    help="Hex ID of the worker node to be drained.",
+)
+@click.option(
+    "--reason",
+    required=True,
+    type=click.Choice(
+        [
+            item[0]
+            for item in autoscaler_pb2.DrainNodeReason.items()
+            if item[1] != autoscaler_pb2.DRAIN_NODE_REASON_UNSPECIFIED
+        ]
+    ),
+    help="The reason why the node will be drained.",
+)
+@click.option(
+    "--reason-message",
+    required=True,
+    type=str,
+    help="The detailed drain reason message.",
+)
+@click.option(
+    "--deadline-remaining-seconds",
+    required=False,
+    type=int,
+    default=None,
+    help="Inform GCS that the node to be drained will be force killed "
+    "after this many of seconds. "
+    "Default is None which means there is no deadline. "
+    "Note: This command doesn't actually force kill the node after the deadline, "
+    "it's the caller's responsibility to do that.",
+)
+def drain_node(
+    address: str,
+    node_id: str,
+    reason: str,
+    reason_message: str,
+    deadline_remaining_seconds: int,
+):
+    """
+    This is NOT a public API.
+
+    Manually drain a worker node.
+    """
+    deadline_timestamp_ms = 0
+    if deadline_remaining_seconds is not None:
+        if deadline_remaining_seconds < 0:
+            raise click.BadParameter(
+                "--deadline-remaining-seconds cannot be negative, "
+                f"got {deadline_remaining_seconds}"
+            )
+        deadline_timestamp_ms = (time.time_ns() // 1000000) + (
+            deadline_remaining_seconds * 1000
+        )
+
+    if ray.NodeID.from_hex(node_id) == ray.NodeID.nil():
+        raise click.BadParameter(f"Invalid hex ID of a Ray node, got {node_id}")
+
+    address = services.canonicalize_bootstrap_address_or_die(address)
+
+    gcs_client = ray._raylet.GcsClient(address=address)
+    _check_ray_version(gcs_client)
+    is_accepted, rejection_error_message = gcs_client.drain_node(
+        node_id,
+        autoscaler_pb2.DrainNodeReason.Value(reason),
+        reason_message,
+        deadline_timestamp_ms,
+    )
+
+    if not is_accepted:
+        raise click.ClickException(
+            f"The drain request is not accepted: {rejection_error_message}"
+        )
+
+
+@cli.command(name="kuberay-autoscaler", hidden=True)
+@click.option(
+    "--cluster-name",
+    required=True,
+    type=str,
+    help="The name of the Ray Cluster.\n"
+    "Should coincide with the `metadata.name` of the RayCluster CR.",
+)
+@click.option(
+    "--cluster-namespace",
+    required=True,
+    type=str,
+    help="The Kubernetes namespace the Ray Cluster lives in.\n"
+    "Should coincide with the `metadata.namespace` of the RayCluster CR.",
+)
+def kuberay_autoscaler(cluster_name: str, cluster_namespace: str) -> None:
+    """Runs the autoscaler for a Ray cluster managed by the KubeRay operator.
+
+    `ray kuberay-autoscaler` is meant to be used as an entry point in
+        KubeRay cluster configs.
+    `ray kuberay-autoscaler` is NOT a public CLI.
+    """
+    # Delay import to avoid introducing Ray core dependency on the Python Kubernetes
+    # client.
+    from ray.autoscaler._private.kuberay.run_autoscaler import run_kuberay_autoscaler
+
+    run_kuberay_autoscaler(cluster_name, cluster_namespace)
+
+
+@cli.command(name="health-check", hidden=True)
+@click.option(
+    "--address", required=False, type=str, help="Override the address to connect to."
+)
+@click.option(
+    "--component",
+    required=False,
+    type=str,
+    help="Health check for a specific component. Currently supports: "
+    "[ray_client_server]",
+)
+@click.option(
+    "--skip-version-check",
+    is_flag=True,
+    default=False,
+    help="Skip comparison of GCS version with local Ray version.",
+)
+def healthcheck(address, component, skip_version_check):
+    """
+    This is NOT a public API.
+
+    Health check a Ray or a specific component. Exit code 0 is healthy.
+    """
+
+    address = services.canonicalize_bootstrap_address_or_die(address)
+    gcs_client = ray._raylet.GcsClient(address=address)
+    if not skip_version_check:
+        _check_ray_version(gcs_client)
+
+    if not component:
+        sys.exit(0)
+
+    report_str = gcs_client.internal_kv_get(
+        component.encode(), namespace=ray_constants.KV_NAMESPACE_HEALTHCHECK
+    )
+    if not report_str:
+        # Status was never updated
+        sys.exit(1)
+
+    report = json.loads(report_str)
+
+    # TODO (Alex): We probably shouldn't rely on time here, but cloud providers
+    # have very well synchronized NTP servers, so this should be fine in
+    # practice.
+    cur_time = time.time()
+    report_time = float(report["time"])
+
+    # If the status is too old, the service has probably already died.
+    delta = cur_time - report_time
+    time_ok = delta < ray._private.ray_constants.HEALTHCHECK_EXPIRATION_S
+
+    if time_ok:
+        sys.exit(0)
+    else:
+        sys.exit(1)
+
+
+@cli.command()
+@click.option("-v", "--verbose", is_flag=True)
+@click.option(
+    "--dryrun",
+    is_flag=True,
+    help="Identifies the wheel but does not execute the installation.",
+)
+def install_nightly(verbose, dryrun):
+    """Install the latest wheels for Ray.
+
+    This uses the same python environment as the one that Ray is currently
+    installed in. Make sure that there is no Ray processes on this
+    machine (ray stop) when running this command.
+    """
+    raydir = os.path.abspath(os.path.dirname(ray.__file__))
+    all_wheels_path = os.path.join(raydir, "nightly-wheels.yaml")
+
+    wheels = None
+    if os.path.exists(all_wheels_path):
+        with open(all_wheels_path) as f:
+            wheels = yaml.safe_load(f)
+
+    if not wheels:
+        raise click.ClickException(
+            f"Wheels not found in '{all_wheels_path}'! "
+            "Please visit https://docs.ray.io/en/master/installation.html to "
+            "obtain the latest wheels."
+        )
+
+    platform = sys.platform
+    py_version = "{0}.{1}".format(*sys.version_info[:2])
+
+    matching_wheel = None
+    for target_platform, wheel_map in wheels.items():
+        if verbose:
+            print(f"Evaluating os={target_platform}, python={list(wheel_map)}")
+        if platform.startswith(target_platform):
+            if py_version in wheel_map:
+                matching_wheel = wheel_map[py_version]
+                break
+        if verbose:
+            print("Not matched.")
+
+    if matching_wheel is None:
+        raise click.ClickException(
+            "Unable to identify a matching platform. "
+            "Please visit https://docs.ray.io/en/master/installation.html to "
+            "obtain the latest wheels."
+        )
+    if dryrun:
+        print(f"Found wheel: {matching_wheel}")
+    else:
+        cmd = [sys.executable, "-m", "pip", "install", "-U", matching_wheel]
+        print(f"Running: {' '.join(cmd)}.")
+        subprocess.check_call(cmd)
+
+
+@cli.command()
+@click.option(
+    "--show-library-path",
+    "-show",
+    required=False,
+    is_flag=True,
+    help="Show the cpp include path and library path, if provided.",
+)
+@click.option(
+    "--generate-bazel-project-template-to",
+    "-gen",
+    required=False,
+    type=str,
+    help="The directory to generate the bazel project template to, if provided.",
+)
+@add_click_logging_options
+def cpp(show_library_path, generate_bazel_project_template_to):
+    """Show the cpp library path and generate the bazel project template."""
+    if sys.platform == "win32":
+        cli_logger.error("Ray C++ API is not supported on Windows currently.")
+        sys.exit(1)
+    if not show_library_path and not generate_bazel_project_template_to:
+        raise ValueError(
+            "Please input at least one option of '--show-library-path'"
+            " and '--generate-bazel-project-template-to'."
+        )
+    raydir = os.path.abspath(os.path.dirname(ray.__file__))
+    cpp_dir = os.path.join(raydir, "cpp")
+    cpp_templete_dir = os.path.join(cpp_dir, "example")
+    include_dir = os.path.join(cpp_dir, "include")
+    lib_dir = os.path.join(cpp_dir, "lib")
+    if not os.path.isdir(cpp_dir):
+        raise ValueError('Please install ray with C++ API by "pip install ray[cpp]".')
+    if show_library_path:
+        cli_logger.print("Ray C++ include path {} ", cf.bold(f"{include_dir}"))
+        cli_logger.print("Ray C++ library path {} ", cf.bold(f"{lib_dir}"))
+    if generate_bazel_project_template_to:
+        # copytree expects that the dst dir doesn't exist
+        # so we manually delete it if it exists.
+        if os.path.exists(generate_bazel_project_template_to):
+            shutil.rmtree(generate_bazel_project_template_to)
+        shutil.copytree(cpp_templete_dir, generate_bazel_project_template_to)
+        out_include_dir = os.path.join(
+            generate_bazel_project_template_to, "thirdparty/include"
+        )
+        if os.path.exists(out_include_dir):
+            shutil.rmtree(out_include_dir)
+        shutil.copytree(include_dir, out_include_dir)
+        out_lib_dir = os.path.join(generate_bazel_project_template_to, "thirdparty/lib")
+        if os.path.exists(out_lib_dir):
+            shutil.rmtree(out_lib_dir)
+        shutil.copytree(lib_dir, out_lib_dir)
+
+        cli_logger.print(
+            "Project template generated to {}",
+            cf.bold(f"{os.path.abspath(generate_bazel_project_template_to)}"),
+        )
+        cli_logger.print("To build and run this template, run")
+        cli_logger.print(
+            cf.bold(
+                f"    cd {os.path.abspath(generate_bazel_project_template_to)}"
+                " && bash run.sh"
+            )
+        )
+
+
+@click.group(name="metrics")
+def metrics_group():
+    pass
+
+
+@metrics_group.command(name="launch-prometheus")
+def launch_prometheus():
+    install_and_start_prometheus.main()
+
+
+@metrics_group.command(name="shutdown-prometheus")
+def shutdown_prometheus():
+    try:
+        requests.post("http://localhost:9090/-/quit")
+    except requests.exceptions.RequestException as e:
+        print(f"An error occurred: {e}")
+        sys.exit(1)
+
+
+def add_command_alias(command, name, hidden):
+    new_command = copy.deepcopy(command)
+    new_command.hidden = hidden
+    cli.add_command(new_command, name=name)
+
+
+cli.add_command(dashboard)
+cli.add_command(debug)
+cli.add_command(start)
+cli.add_command(stop)
+cli.add_command(up)
+add_command_alias(up, name="create_or_update", hidden=True)
+cli.add_command(attach)
+cli.add_command(exec)
+add_command_alias(exec, name="exec_cmd", hidden=True)
+add_command_alias(rsync_down, name="rsync_down", hidden=True)
+add_command_alias(rsync_up, name="rsync_up", hidden=True)
+cli.add_command(submit)
+cli.add_command(down)
+add_command_alias(down, name="teardown", hidden=True)
+cli.add_command(kill_random_node)
+add_command_alias(get_head_ip, name="get_head_ip", hidden=True)
+cli.add_command(get_worker_ips)
+cli.add_command(microbenchmark)
+cli.add_command(stack)
+cli.add_command(status)
+cli.add_command(memory)
+cli.add_command(local_dump)
+cli.add_command(cluster_dump)
+cli.add_command(global_gc)
+cli.add_command(timeline)
+cli.add_command(install_nightly)
+cli.add_command(cpp)
+cli.add_command(disable_usage_stats)
+cli.add_command(enable_usage_stats)
+cli.add_command(metrics_group)
+cli.add_command(drain_node)
+cli.add_command(check_open_ports)
+
+try:
+    from ray.util.state.state_cli import (
+        ray_get,
+        ray_list,
+        logs_state_cli_group,
+        summary_state_cli_group,
+    )
+
+    cli.add_command(ray_list, name="list")
+    cli.add_command(ray_get, name="get")
+    add_command_alias(summary_state_cli_group, name="summary", hidden=False)
+    add_command_alias(logs_state_cli_group, name="logs", hidden=False)
+except ImportError as e:
+    logger.debug(f"Integrating ray state command line tool failed: {e}")
+
+
+try:
+    from ray.dashboard.modules.job.cli import job_cli_group
+
+    add_command_alias(job_cli_group, name="job", hidden=False)
+except Exception as e:
+    logger.debug(f"Integrating ray jobs command line tool failed with {e}")
+
+
+try:
+    from ray.serve.scripts import serve_cli
+
+    cli.add_command(serve_cli)
+except Exception as e:
+    logger.debug(f"Integrating ray serve command line tool failed with {e}")
+
+
+def main():
+    return cli()
+
+
+if __name__ == "__main__":
+    main()

.venv/lib/python3.11/site-packages/ray/thirdparty_files/colorama-0.4.6.dist-info/METADATA

@@ -0,0 +1,441 @@
+Metadata-Version: 2.1
+Name: colorama
+Version: 0.4.6
+Summary: Cross-platform colored terminal text.
+Project-URL: Homepage, https://github.com/tartley/colorama
+Author-email: Jonathan Hartley <tartley@tartley.com>
+License-File: LICENSE.txt
+Keywords: ansi,color,colour,crossplatform,terminal,text,windows,xplatform
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: BSD License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 2
+Classifier: Programming Language :: Python :: 2.7
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.7
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: Implementation :: CPython
+Classifier: Programming Language :: Python :: Implementation :: PyPy
+Classifier: Topic :: Terminals
+Requires-Python: !=3.0.*,!=3.1.*,!=3.2.*,!=3.3.*,!=3.4.*,!=3.5.*,!=3.6.*,>=2.7
+Description-Content-Type: text/x-rst
+
+.. image:: https://img.shields.io/pypi/v/colorama.svg
+    :target: https://pypi.org/project/colorama/
+    :alt: Latest Version
+
+.. image:: https://img.shields.io/pypi/pyversions/colorama.svg
+    :target: https://pypi.org/project/colorama/
+    :alt: Supported Python versions
+
+.. image:: https://github.com/tartley/colorama/actions/workflows/test.yml/badge.svg
+    :target: https://github.com/tartley/colorama/actions/workflows/test.yml
+    :alt: Build Status
+
+Colorama
+========
+
+Makes ANSI escape character sequences (for producing colored terminal text and
+cursor positioning) work under MS Windows.
+
+.. |donate| image:: https://www.paypalobjects.com/en_US/i/btn/btn_donate_SM.gif
+  :target: https://www.paypal.com/cgi-bin/webscr?cmd=_donations&business=2MZ9D2GMLYCUJ&item_name=Colorama&currency_code=USD
+  :alt: Donate with Paypal
+
+`PyPI for releases <https://pypi.org/project/colorama/>`_ |
+`Github for source <https://github.com/tartley/colorama>`_ |
+`Colorama for enterprise on Tidelift <https://github.com/tartley/colorama/blob/master/ENTERPRISE.md>`_
+
+If you find Colorama useful, please |donate| to the authors. Thank you!
+
+Installation
+------------
+
+Tested on CPython 2.7, 3.7, 3.8, 3.9 and 3.10 and Pypy 2.7 and 3.8.
+
+No requirements other than the standard library.
+
+.. code-block:: bash
+
+    pip install colorama
+    # or
+    conda install -c anaconda colorama
+
+Description
+-----------
+
+ANSI escape character sequences have long been used to produce colored terminal
+text and cursor positioning on Unix and Macs. Colorama makes this work on
+Windows, too, by wrapping ``stdout``, stripping ANSI sequences it finds (which
+would appear as gobbledygook in the output), and converting them into the
+appropriate win32 calls to modify the state of the terminal. On other platforms,
+Colorama does nothing.
+
+This has the upshot of providing a simple cross-platform API for printing
+colored terminal text from Python, and has the happy side-effect that existing
+applications or libraries which use ANSI sequences to produce colored output on
+Linux or Macs can now also work on Windows, simply by calling
+``colorama.just_fix_windows_console()`` (since v0.4.6) or ``colorama.init()``
+(all versions, but may have other side-effects – see below).
+
+An alternative approach is to install ``ansi.sys`` on Windows machines, which
+provides the same behaviour for all applications running in terminals. Colorama
+is intended for situations where that isn't easy (e.g., maybe your app doesn't
+have an installer.)
+
+Demo scripts in the source code repository print some colored text using
+ANSI sequences. Compare their output under Gnome-terminal's built in ANSI
+handling, versus on Windows Command-Prompt using Colorama:
+
+.. image:: https://github.com/tartley/colorama/raw/master/screenshots/ubuntu-demo.png
+    :width: 661
+    :height: 357
+    :alt: ANSI sequences on Ubuntu under gnome-terminal.
+
+.. image:: https://github.com/tartley/colorama/raw/master/screenshots/windows-demo.png
+    :width: 668
+    :height: 325
+    :alt: Same ANSI sequences on Windows, using Colorama.
+
+These screenshots show that, on Windows, Colorama does not support ANSI 'dim
+text'; it looks the same as 'normal text'.
+
+Usage
+-----
+
+Initialisation
+..............
+
+If the only thing you want from Colorama is to get ANSI escapes to work on
+Windows, then run:
+
+.. code-block:: python
+
+    from colorama import just_fix_windows_console
+    just_fix_windows_console()
+
+If you're on a recent version of Windows 10 or better, and your stdout/stderr
+are pointing to a Windows console, then this will flip the magic configuration
+switch to enable Windows' built-in ANSI support.
+
+If you're on an older version of Windows, and your stdout/stderr are pointing to
+a Windows console, then this will wrap ``sys.stdout`` and/or ``sys.stderr`` in a
+magic file object that intercepts ANSI escape sequences and issues the
+appropriate Win32 calls to emulate them.
+
+In all other circumstances, it does nothing whatsoever. Basically the idea is
+that this makes Windows act like Unix with respect to ANSI escape handling.
+
+It's safe to call this function multiple times. It's safe to call this function
+on non-Windows platforms, but it won't do anything. It's safe to call this
+function when one or both of your stdout/stderr are redirected to a file – it
+won't do anything to those streams.
+
+Alternatively, you can use the older interface with more features (but also more
+potential footguns):
+
+.. code-block:: python
+
+    from colorama import init
+    init()
+
+This does the same thing as ``just_fix_windows_console``, except for the
+following differences:
+
+- It's not safe to call ``init`` multiple times; you can end up with multiple
+  layers of wrapping and broken ANSI support.
+
+- Colorama will apply a heuristic to guess whether stdout/stderr support ANSI,
+  and if it thinks they don't, then it will wrap ``sys.stdout`` and
+  ``sys.stderr`` in a magic file object that strips out ANSI escape sequences
+  before printing them. This happens on all platforms, and can be convenient if
+  you want to write your code to emit ANSI escape sequences unconditionally, and
+  let Colorama decide whether they should actually be output. But note that
+  Colorama's heuristic is not particularly clever.
+
+- ``init`` also accepts explicit keyword args to enable/disable various
+  functionality – see below.
+
+To stop using Colorama before your program exits, simply call ``deinit()``.
+This will restore ``stdout`` and ``stderr`` to their original values, so that
+Colorama is disabled. To resume using Colorama again, call ``reinit()``; it is
+cheaper than calling ``init()`` again (but does the same thing).
+
+Most users should depend on ``colorama >= 0.4.6``, and use
+``just_fix_windows_console``. The old ``init`` interface will be supported
+indefinitely for backwards compatibility, but we don't plan to fix any issues
+with it, also for backwards compatibility.
+
+Colored Output
+..............
+
+Cross-platform printing of colored text can then be done using Colorama's
+constant shorthand for ANSI escape sequences. These are deliberately
+rudimentary, see below.
+
+.. code-block:: python
+
+    from colorama import Fore, Back, Style
+    print(Fore.RED + 'some red text')
+    print(Back.GREEN + 'and with a green background')
+    print(Style.DIM + 'and in dim text')
+    print(Style.RESET_ALL)
+    print('back to normal now')
+
+...or simply by manually printing ANSI sequences from your own code:
+
+.. code-block:: python
+
+    print('\033[31m' + 'some red text')
+    print('\033[39m') # and reset to default color
+
+...or, Colorama can be used in conjunction with existing ANSI libraries
+such as the venerable `Termcolor <https://pypi.org/project/termcolor/>`_
+the fabulous `Blessings <https://pypi.org/project/blessings/>`_,
+or the incredible `_Rich <https://pypi.org/project/rich/>`_.
+
+If you wish Colorama's Fore, Back and Style constants were more capable,
+then consider using one of the above highly capable libraries to generate
+colors, etc, and use Colorama just for its primary purpose: to convert
+those ANSI sequences to also work on Windows:
+
+SIMILARLY, do not send PRs adding the generation of new ANSI types to Colorama.
+We are only interested in converting ANSI codes to win32 API calls, not
+shortcuts like the above to generate ANSI characters.
+
+.. code-block:: python
+
+    from colorama import just_fix_windows_console
+    from termcolor import colored
+
+    # use Colorama to make Termcolor work on Windows too
+    just_fix_windows_console()
+
+    # then use Termcolor for all colored text output
+    print(colored('Hello, World!', 'green', 'on_red'))
+
+Available formatting constants are::
+
+    Fore: BLACK, RED, GREEN, YELLOW, BLUE, MAGENTA, CYAN, WHITE, RESET.
+    Back: BLACK, RED, GREEN, YELLOW, BLUE, MAGENTA, CYAN, WHITE, RESET.
+    Style: DIM, NORMAL, BRIGHT, RESET_ALL
+
+``Style.RESET_ALL`` resets foreground, background, and brightness. Colorama will
+perform this reset automatically on program exit.
+
+These are fairly well supported, but not part of the standard::
+
+    Fore: LIGHTBLACK_EX, LIGHTRED_EX, LIGHTGREEN_EX, LIGHTYELLOW_EX, LIGHTBLUE_EX, LIGHTMAGENTA_EX, LIGHTCYAN_EX, LIGHTWHITE_EX
+    Back: LIGHTBLACK_EX, LIGHTRED_EX, LIGHTGREEN_EX, LIGHTYELLOW_EX, LIGHTBLUE_EX, LIGHTMAGENTA_EX, LIGHTCYAN_EX, LIGHTWHITE_EX
+
+Cursor Positioning
+..................
+
+ANSI codes to reposition the cursor are supported. See ``demos/demo06.py`` for
+an example of how to generate them.
+
+Init Keyword Args
+.................
+
+``init()`` accepts some ``**kwargs`` to override default behaviour.
+
+init(autoreset=False):
+    If you find yourself repeatedly sending reset sequences to turn off color
+    changes at the end of every print, then ``init(autoreset=True)`` will
+    automate that:
+
+    .. code-block:: python
+
+        from colorama import init
+        init(autoreset=True)
+        print(Fore.RED + 'some red text')
+        print('automatically back to default color again')
+
+init(strip=None):
+    Pass ``True`` or ``False`` to override whether ANSI codes should be
+    stripped from the output. The default behaviour is to strip if on Windows
+    or if output is redirected (not a tty).
+
+init(convert=None):
+    Pass ``True`` or ``False`` to override whether to convert ANSI codes in the
+    output into win32 calls. The default behaviour is to convert if on Windows
+    and output is to a tty (terminal).
+
+init(wrap=True):
+    On Windows, Colorama works by replacing ``sys.stdout`` and ``sys.stderr``
+    with proxy objects, which override the ``.write()`` method to do their work.
+    If this wrapping causes you problems, then this can be disabled by passing
+    ``init(wrap=False)``. The default behaviour is to wrap if ``autoreset`` or
+    ``strip`` or ``convert`` are True.
+
+    When wrapping is disabled, colored printing on non-Windows platforms will
+    continue to work as normal. To do cross-platform colored output, you can
+    use Colorama's ``AnsiToWin32`` proxy directly:
+
+    .. code-block:: python
+
+        import sys
+        from colorama import init, AnsiToWin32
+        init(wrap=False)
+        stream = AnsiToWin32(sys.stderr).stream
+
+        # Python 2
+        print >>stream, Fore.BLUE + 'blue text on stderr'
+
+        # Python 3
+        print(Fore.BLUE + 'blue text on stderr', file=stream)
+
+Recognised ANSI Sequences
+.........................
+
+ANSI sequences generally take the form::
+
+    ESC [ <param> ; <param> ... <command>
+
+Where ``<param>`` is an integer, and ``<command>`` is a single letter. Zero or
+more params are passed to a ``<command>``. If no params are passed, it is
+generally synonymous with passing a single zero. No spaces exist in the
+sequence; they have been inserted here simply to read more easily.
+
+The only ANSI sequences that Colorama converts into win32 calls are::
+
+    ESC [ 0 m       # reset all (colors and brightness)
+    ESC [ 1 m       # bright
+    ESC [ 2 m       # dim (looks same as normal brightness)
+    ESC [ 22 m      # normal brightness
+
+    # FOREGROUND:
+    ESC [ 30 m      # black
+    ESC [ 31 m      # red
+    ESC [ 32 m      # green
+    ESC [ 33 m      # yellow
+    ESC [ 34 m      # blue
+    ESC [ 35 m      # magenta
+    ESC [ 36 m      # cyan
+    ESC [ 37 m      # white
+    ESC [ 39 m      # reset
+
+    # BACKGROUND
+    ESC [ 40 m      # black
+    ESC [ 41 m      # red
+    ESC [ 42 m      # green
+    ESC [ 43 m      # yellow
+    ESC [ 44 m      # blue
+    ESC [ 45 m      # magenta
+    ESC [ 46 m      # cyan
+    ESC [ 47 m      # white
+    ESC [ 49 m      # reset
+
+    # cursor positioning
+    ESC [ y;x H     # position cursor at x across, y down
+    ESC [ y;x f     # position cursor at x across, y down
+    ESC [ n A       # move cursor n lines up
+    ESC [ n B       # move cursor n lines down
+    ESC [ n C       # move cursor n characters forward
+    ESC [ n D       # move cursor n characters backward
+
+    # clear the screen
+    ESC [ mode J    # clear the screen
+
+    # clear the line
+    ESC [ mode K    # clear the line
+
+Multiple numeric params to the ``'m'`` command can be combined into a single
+sequence::
+
+    ESC [ 36 ; 45 ; 1 m     # bright cyan text on magenta background
+
+All other ANSI sequences of the form ``ESC [ <param> ; <param> ... <command>``
+are silently stripped from the output on Windows.
+
+Any other form of ANSI sequence, such as single-character codes or alternative
+initial characters, are not recognised or stripped. It would be cool to add
+them though. Let me know if it would be useful for you, via the Issues on
+GitHub.
+
+Status & Known Problems
+-----------------------
+
+I've personally only tested it on Windows XP (CMD, Console2), Ubuntu
+(gnome-terminal, xterm), and OS X.
+
+Some valid ANSI sequences aren't recognised.
+
+If you're hacking on the code, see `README-hacking.md`_. ESPECIALLY, see the
+explanation there of why we do not want PRs that allow Colorama to generate new
+types of ANSI codes.
+
+See outstanding issues and wish-list:
+https://github.com/tartley/colorama/issues
+
+If anything doesn't work for you, or doesn't do what you expected or hoped for,
+I'd love to hear about it on that issues list, would be delighted by patches,
+and would be happy to grant commit access to anyone who submits a working patch
+or two.
+
+.. _README-hacking.md: README-hacking.md
+
+License
+-------
+
+Copyright Jonathan Hartley & Arnon Yaari, 2013-2020. BSD 3-Clause license; see
+LICENSE file.
+
+Professional support
+--------------------
+
+.. |tideliftlogo| image:: https://cdn2.hubspot.net/hubfs/4008838/website/logos/logos_for_download/Tidelift_primary-shorthand-logo.png
+   :alt: Tidelift
+   :target: https://tidelift.com/subscription/pkg/pypi-colorama?utm_source=pypi-colorama&utm_medium=referral&utm_campaign=readme
+
+.. list-table::
+   :widths: 10 100
+
+   * - |tideliftlogo|
+     - Professional support for colorama is available as part of the
+       `Tidelift Subscription`_.
+       Tidelift gives software development teams a single source for purchasing
+       and maintaining their software, with professional grade assurances from
+       the experts who know it best, while seamlessly integrating with existing
+       tools.
+
+.. _Tidelift Subscription: https://tidelift.com/subscription/pkg/pypi-colorama?utm_source=pypi-colorama&utm_medium=referral&utm_campaign=readme
+
+Thanks
+------
+
+See the CHANGELOG for more thanks!
+
+* Marc Schlaich (schlamar) for a ``setup.py`` fix for Python2.5.
+* Marc Abramowitz, reported & fixed a crash on exit with closed ``stdout``,
+  providing a solution to issue #7's setuptools/distutils debate,
+  and other fixes.
+* User 'eryksun', for guidance on correctly instantiating ``ctypes.windll``.
+* Matthew McCormick for politely pointing out a longstanding crash on non-Win.
+* Ben Hoyt, for a magnificent fix under 64-bit Windows.
+* Jesse at Empty Square for submitting a fix for examples in the README.
+* User 'jamessp', an observant documentation fix for cursor positioning.
+* User 'vaal1239', Dave Mckee & Lackner Kristof for a tiny but much-needed Win7
+  fix.
+* Julien Stuyck, for wisely suggesting Python3 compatible updates to README.
+* Daniel Griffith for multiple fabulous patches.
+* Oscar Lesta for a valuable fix to stop ANSI chars being sent to non-tty
+  output.
+* Roger Binns, for many suggestions, valuable feedback, & bug reports.
+* Tim Golden for thought and much appreciated feedback on the initial idea.
+* User 'Zearin' for updates to the README file.
+* John Szakmeister for adding support for light colors
+* Charles Merriam for adding documentation to demos
+* Jurko for a fix on 64-bit Windows CPython2.5 w/o ctypes
+* Florian Bruhin for a fix when stdout or stderr are None
+* Thomas Weininger for fixing ValueError on Windows
+* Remi Rampin for better Github integration and fixes to the README file
+* Simeon Visser for closing a file handle using 'with' and updating classifiers
+  to include Python 3.3 and 3.4
+* Andy Neff for fixing RESET of LIGHT_EX colors.
+* Jonathan Hartley for the initial idea and implementation.

.venv/lib/python3.11/site-packages/ray/thirdparty_files/colorama-0.4.6.dist-info/RECORD

@@ -0,0 +1,32 @@
+colorama-0.4.6.dist-info/INSTALLER,sha256=zuuue4knoyJ-UwPPXg8fezS7VCrXJQrAP7zeNuwvFQg,4
+colorama-0.4.6.dist-info/METADATA,sha256=e67SnrUMOym9sz_4TjF3vxvAV4T3aF7NyqRHHH3YEMw,17158
+colorama-0.4.6.dist-info/RECORD,,
+colorama-0.4.6.dist-info/REQUESTED,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+colorama-0.4.6.dist-info/WHEEL,sha256=cdcF4Fbd0FPtw2EMIOwH-3rSOTUdTCeOSXRMD1iLUb8,105
+colorama-0.4.6.dist-info/licenses/LICENSE.txt,sha256=ysNcAmhuXQSlpxQL-zs25zrtSWZW6JEQLkKIhteTAxg,1491
+colorama/__init__.py,sha256=wePQA4U20tKgYARySLEC047ucNX-g8pRLpYBuiHlLb8,266
+colorama/__pycache__/__init__.cpython-311.pyc,,
+colorama/__pycache__/ansi.cpython-311.pyc,,
+colorama/__pycache__/ansitowin32.cpython-311.pyc,,
+colorama/__pycache__/initialise.cpython-311.pyc,,
+colorama/__pycache__/win32.cpython-311.pyc,,
+colorama/__pycache__/winterm.cpython-311.pyc,,
+colorama/ansi.py,sha256=Top4EeEuaQdBWdteKMEcGOTeKeF19Q-Wo_6_Cj5kOzQ,2522
+colorama/ansitowin32.py,sha256=vPNYa3OZbxjbuFyaVo0Tmhmy1FZ1lKMWCnT7odXpItk,11128
+colorama/initialise.py,sha256=-hIny86ClXo39ixh5iSCfUIa2f_h_bgKRDW7gqs-KLU,3325
+colorama/tests/__init__.py,sha256=MkgPAEzGQd-Rq0w0PZXSX2LadRWhUECcisJY8lSrm4Q,75
+colorama/tests/__pycache__/__init__.cpython-311.pyc,,
+colorama/tests/__pycache__/ansi_test.cpython-311.pyc,,
+colorama/tests/__pycache__/ansitowin32_test.cpython-311.pyc,,
+colorama/tests/__pycache__/initialise_test.cpython-311.pyc,,
+colorama/tests/__pycache__/isatty_test.cpython-311.pyc,,
+colorama/tests/__pycache__/utils.cpython-311.pyc,,
+colorama/tests/__pycache__/winterm_test.cpython-311.pyc,,
+colorama/tests/ansi_test.py,sha256=FeViDrUINIZcr505PAxvU4AjXz1asEiALs9GXMhwRaE,2839
+colorama/tests/ansitowin32_test.py,sha256=RN7AIhMJ5EqDsYaCjVo-o4u8JzDD4ukJbmevWKS70rY,10678
+colorama/tests/initialise_test.py,sha256=BbPy-XfyHwJ6zKozuQOvNvQZzsx9vdb_0bYXn7hsBTc,6741
+colorama/tests/isatty_test.py,sha256=Pg26LRpv0yQDB5Ac-sxgVXG7hsA1NYvapFgApZfYzZg,1866
+colorama/tests/utils.py,sha256=1IIRylG39z5-dzq09R_ngufxyPZxgldNbrxKxUGwGKE,1079
+colorama/tests/winterm_test.py,sha256=qoWFPEjym5gm2RuMwpf3pOis3a5r_PJZFCzK254JL8A,3709
+colorama/win32.py,sha256=YQOKwMTwtGBbsY4dL5HYTvwTeP9wIQra5MvPNddpxZs,6181
+colorama/winterm.py,sha256=XCQFDHjPi6AHYNdZwy0tA02H-Jh48Jp-HvCjeLeLp3U,7134

.venv/lib/python3.11/site-packages/ray/thirdparty_files/colorama-0.4.6.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.11.1
+Root-Is-Purelib: true
+Tag: py2-none-any
+Tag: py3-none-any

.venv/lib/python3.11/site-packages/ray/thirdparty_files/colorama-0.4.6.dist-info/licenses/LICENSE.txt

@@ -0,0 +1,27 @@
+Copyright (c) 2010 Jonathan Hartley
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+* Redistributions of source code must retain the above copyright notice, this
+  list of conditions and the following disclaimer.
+
+* Redistributions in binary form must reproduce the above copyright notice,
+  this list of conditions and the following disclaimer in the documentation
+  and/or other materials provided with the distribution.
+
+* Neither the name of the copyright holders, nor those of its contributors
+  may be used to endorse or promote products derived from this software without
+  specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
+ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

.venv/lib/python3.11/site-packages/ray/thirdparty_files/psutil/_psutil_linux.abi3.so

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:2d76b01666546f2806089d6f4ef08f005db0bb410d893a54d463a7b0f8b727e2
+size 115336

.venv/lib/python3.11/site-packages/ray/thirdparty_files/setproctitle-1.2.2.dist-info/METADATA

@@ -0,0 +1,327 @@
+Metadata-Version: 2.2
+Name: setproctitle
+Version: 1.2.2
+Summary: A Python module to customize the process title
+Home-page: https://github.com/dvarrazzo/py-setproctitle
+Download-URL: http://pypi.python.org/pypi/setproctitle/
+Author: Daniele Varrazzo
+Author-email: daniele.varrazzo@gmail.com
+License: BSD
+Platform: GNU/Linux
+Platform: BSD
+Platform: MacOS X
+Platform: Windows
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: BSD License
+Classifier: Programming Language :: C
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.6
+Classifier: Programming Language :: Python :: 3.7
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Operating System :: POSIX :: BSD
+Classifier: Operating System :: MacOS :: MacOS X
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Topic :: Software Development
+Requires-Python: >=3.6
+Description-Content-Type: text/x-rst
+Provides-Extra: test
+Requires-Dist: pytest<6.2,>=6.1; extra == "test"
+Dynamic: author
+Dynamic: author-email
+Dynamic: classifier
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: download-url
+Dynamic: home-page
+Dynamic: license
+Dynamic: platform
+Dynamic: provides-extra
+Dynamic: requires-python
+Dynamic: summary
+
+A Python module to customize the process title
+==============================================
+
+.. image:: https://github.com/dvarrazzo/py-setproctitle/workflows/Tests/badge.svg
+    :target: https://github.com/dvarrazzo/py-setproctitle/actions?query=workflow%3ATests
+    :alt: Tests
+
+:author: Daniele Varrazzo
+
+The ``setproctitle`` module allows a process to change its title (as displayed
+by system tools such as ``ps`` and ``top``).
+
+Changing the title is mostly useful in multi-process systems, for example
+when a master process is forked: changing the children's title allows to
+identify the task each process is busy with.  The technique is used by
+PostgreSQL_ and the `OpenSSH Server`_ for example.
+
+The procedure is hardly portable across different systems.  PostgreSQL provides
+a good `multi-platform implementation`__:  this module is a Python wrapper
+around PostgreSQL code.
+
+- `Homepage <https://github.com/dvarrazzo/py-setproctitle>`__
+- `Download <http://pypi.python.org/pypi/setproctitle/>`__
+- `Bug tracker <https://github.com/dvarrazzo/py-setproctitle/issues>`__
+
+
+.. _PostgreSQL: http://www.postgresql.org
+.. _OpenSSH Server: http://www.openssh.com/
+.. __: http://doxygen.postgresql.org/ps__status_8c_source.html
+
+
+Installation
+------------
+
+``setproctitle`` is a C extension: in order to build it you will need a C
+compiler and the Python development support (the ``python-dev`` or
+``python3-dev`` package in most Linux distributions). No further external
+dependencies are required.
+
+You can use ``pip`` to install the module::
+
+    pip install setproctitle
+
+You can use ``pip -t`` or ``virtualenv`` for local installations, ``sudo pip``
+for a system-wide one... the usual stuff. Read pip_ or virtualenv_ docs for
+all the details.
+
+.. _pip: https://pip.readthedocs.org/
+.. _virtualenv: https://virtualenv.readthedocs.org/
+
+
+Usage
+-----
+
+.. note::
+   You should import and use the module (even just calling ``getproctitle()``)
+   pretty early in your program lifetime: code writing env vars `may
+   interfere`__ with the module initialisation.
+
+    .. __: https://github.com/dvarrazzo/py-setproctitle/issues/42
+
+
+The ``setproctitle`` module exports the following functions:
+
+``setproctitle(title)``
+    Set *title* as the title for the current process.
+
+``getproctitle()``
+    Return the current process title.
+
+The process title is usually visible in files such as ``/proc/PID/cmdline``,
+``/proc/PID/status``, ``/proc/PID/comm``, depending on the operating system
+and kernel version. These information are used by user-space tools such as
+``ps`` and ``top``.
+
+
+``setthreadtitle(title)``
+    Set *title* as the title for the current thread.
+
+``getthreadtitle()``
+    Get the current thread title.
+
+The thread title is exposed by some operating systems as the file
+``/proc/PID/task/TID/comm``, which is used by certain tools such as ``htop``.
+
+
+Environment variables
+~~~~~~~~~~~~~~~~~~~~~
+
+A few environment variables can be used to customize the module behavior:
+
+``SPT_NOENV``
+    Avoid clobbering ``/proc/PID/environ``.
+
+    On many platforms, setting the process title will clobber the
+    ``environ`` memory area. ``os.environ`` will work as expected from within
+    the Python process, but the content of the file ``/proc/PID/environ`` will
+    be overwritten.  If you require this file not to be broken you can set the
+    ``SPT_NOENV`` environment variable to any non-empty value: in this case
+    the maximum length for the title will be limited to the length of the
+    command line.
+
+``SPT_DEBUG``
+    Print debug information on ``stderr``.
+
+    If the module doesn't work as expected you can set this variable to a
+    non-empty value to generate information useful for debugging.  Note that
+    the most useful information is printed when the module is imported, not
+    when the functions are called.
+
+
+Module status
+-------------
+
+The module can be currently compiled and effectively used on the following
+platforms:
+
+- GNU/Linux
+- BSD
+- MacOS X
+- Windows
+
+Note that on Windows there is no way to change the process string:
+what the module does is to create a *Named Object* whose value can be read
+using a tool such as `Process Explorer`_ (contribution of a more useful tool
+to be used together with ``setproctitle`` would be well accepted).
+
+The module can probably work on HP-UX, but I haven't found any to test with.
+It is unlikely that it can work on Solaris instead.
+
+.. _Process Explorer: http://technet.microsoft.com/en-us/sysinternals/bb896653.aspx
+
+Releases history
+----------------
+
+Version 1.2.2
+-------------
+
+- Fixed Windows build (issues #89, #90).
+- Added wheel packages for Windows (issues #47, #90).
+- Added wheel packages for aarch64 (issues #95).
+
+
+Version 1.2.1
+-------------
+
+- Fixed segfault after ``os.environ.clear()`` (issue #88).
+
+
+Version 1.2
+~~~~~~~~~~~
+
+- added ``getthreadtitle()`` and ``setthreadtitle()``.
+- Initialisation of the module moved to the first usage: importing the module
+  doesn't cause side effects.
+- Manage much longer command lines (#52)
+- Improved build on BSD, dropped ancient versions (issue #67).
+- Fixed build for Python 3.8 (#66, #72)
+- Added support for Python 3.9
+- Dropped support for Python < 3.6
+
+
+Version 1.1.10
+~~~~~~~~~~~~~~
+
+- Fixed building with certain ``prctl.h`` implementations (issue #44).
+- Use ``setuptools`` if available (issue #48).
+
+
+Version 1.1.9
+~~~~~~~~~~~~~
+
+- Fixed build on VC (issues #20, #33).
+- Added ``MANIFEST.in`` to the source distribution to help with RPM building
+  (issue #30).
+
+
+Version 1.1.8
+~~~~~~~~~~~~~
+
+- Added support for Python "diehard" 2.4 (pull request #3).
+- Fixed build on Mac OS X 10.9 Maverick (issue #27).
+
+
+Version 1.1.7
+~~~~~~~~~~~~~
+
+- Added PyPy support, courtesy of Ozan Turksever - http://www.logsign.net
+  (pull request #2).
+
+
+Version 1.1.6
+~~~~~~~~~~~~~
+
+- The module can be compiled again on Windows (issue #21).
+
+
+Version 1.1.5
+~~~~~~~~~~~~~
+
+- No module bug, but a packaging issue: files ``README`` and ``HISTORY``
+  added back into the distribution.
+
+
+Version 1.1.4
+~~~~~~~~~~~~~
+
+- The module works correctly in embedded Python.
+- ``setproctitle()`` accepts a keyword argument.
+- Debug output support always compiled in: the variable ``SPT_DEBUG`` can be
+  used to emit debug log.
+
+
+Version 1.1.3
+~~~~~~~~~~~~~
+
+- Don't clobber environ if the variable ``SPT_NOENV`` is set (issue #16).
+
+
+Version 1.1.2
+~~~~~~~~~~~~~
+
+- Find the setproctitle include file on OpenBSD (issue #11).
+- Skip test with unicode if the file system encoding wouldn't make it pass
+  (issue #13).
+
+
+Version 1.1.1
+~~~~~~~~~~~~~
+
+- Fixed segfault when the module is imported under mod_wsgi (issue #9).
+
+
+Version 1.1
+~~~~~~~~~~~
+
+- The module works correctly with Python 3.
+
+
+Version 1.0.1
+~~~~~~~~~~~~~
+
+- ``setproctitle()`` works even when Python messes up with argv, e.g. when run
+  with the -m option (issue #8).
+
+
+Version 1.0
+~~~~~~~~~~~
+
+No major change since the previous version.  The module has been heavily used
+in production environment without any problem reported, so it's time to declare
+it stable.
+
+
+Version 0.4
+~~~~~~~~~~~
+
+- Module works on BSD (tested on FreeBSD 7.2).
+
+- Module works on Windows. Many thanks to `Develer`_ for providing a neat `GCC
+  package for Windows with Python integration`__ that made the Windows porting
+  painless.
+
+  .. _Develer: http://www.develer.com/
+  .. __: http://www.develer.com/oss/GccWinBinaries
+
+
+Version 0.3
+~~~~~~~~~~~
+
+- Module works on Mac OS X 10.2. Reported working on OS X 10.6 too.
+
+
+Version 0.2
+~~~~~~~~~~~
+
+- Added ``prctl()`` call on Linux >= 2.6.9 to update ``/proc/self/status``.
+
+
+Version 0.1
+~~~~~~~~~~~
+
+- Initial public release.

.venv/lib/python3.11/site-packages/ray/thirdparty_files/setproctitle-1.2.2.dist-info/RECORD

@@ -0,0 +1,7 @@
+setproctitle-1.2.2.dist-info/INSTALLER,sha256=zuuue4knoyJ-UwPPXg8fezS7VCrXJQrAP7zeNuwvFQg,4
+setproctitle-1.2.2.dist-info/METADATA,sha256=FFhJMjb-VT6QB94FksWKoQkg-sZy52OTBXC_KG3_hf8,9051
+setproctitle-1.2.2.dist-info/RECORD,,
+setproctitle-1.2.2.dist-info/REQUESTED,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+setproctitle-1.2.2.dist-info/WHEEL,sha256=HDBMQ19ZtMFARwRc3ZGC21o8Tu11IBK6tQtXGgqOICs,104
+setproctitle-1.2.2.dist-info/top_level.txt,sha256=khlu2SuNEK2Ct594XhMTT62ll8p0oFza-4dmzUFTBhQ,13
+setproctitle.cpython-311-x86_64-linux-gnu.so,sha256=sOhOZH3jZQWd3CIHW_KKe8qLZZm-YPo86kISUM-MZkM,69120

.venv/lib/python3.11/site-packages/yaml/__init__.py

@@ -0,0 +1,390 @@
+
+from .error import *
+
+from .tokens import *
+from .events import *
+from .nodes import *
+
+from .loader import *
+from .dumper import *
+
+__version__ = '6.0.2'
+try:
+    from .cyaml import *
+    __with_libyaml__ = True
+except ImportError:
+    __with_libyaml__ = False
+
+import io
+
+#------------------------------------------------------------------------------
+# XXX "Warnings control" is now deprecated. Leaving in the API function to not
+# break code that uses it.
+#------------------------------------------------------------------------------
+def warnings(settings=None):
+    if settings is None:
+        return {}
+
+#------------------------------------------------------------------------------
+def scan(stream, Loader=Loader):
+    """
+    Scan a YAML stream and produce scanning tokens.
+    """
+    loader = Loader(stream)
+    try:
+        while loader.check_token():
+            yield loader.get_token()
+    finally:
+        loader.dispose()
+
+def parse(stream, Loader=Loader):
+    """
+    Parse a YAML stream and produce parsing events.
+    """
+    loader = Loader(stream)
+    try:
+        while loader.check_event():
+            yield loader.get_event()
+    finally:
+        loader.dispose()
+
+def compose(stream, Loader=Loader):
+    """
+    Parse the first YAML document in a stream
+    and produce the corresponding representation tree.
+    """
+    loader = Loader(stream)
+    try:
+        return loader.get_single_node()
+    finally:
+        loader.dispose()
+
+def compose_all(stream, Loader=Loader):
+    """
+    Parse all YAML documents in a stream
+    and produce corresponding representation trees.
+    """
+    loader = Loader(stream)
+    try:
+        while loader.check_node():
+            yield loader.get_node()
+    finally:
+        loader.dispose()
+
+def load(stream, Loader):
+    """
+    Parse the first YAML document in a stream
+    and produce the corresponding Python object.
+    """
+    loader = Loader(stream)
+    try:
+        return loader.get_single_data()
+    finally:
+        loader.dispose()
+
+def load_all(stream, Loader):
+    """
+    Parse all YAML documents in a stream
+    and produce corresponding Python objects.
+    """
+    loader = Loader(stream)
+    try:
+        while loader.check_data():
+            yield loader.get_data()
+    finally:
+        loader.dispose()
+
+def full_load(stream):
+    """
+    Parse the first YAML document in a stream
+    and produce the corresponding Python object.
+
+    Resolve all tags except those known to be
+    unsafe on untrusted input.
+    """
+    return load(stream, FullLoader)
+
+def full_load_all(stream):
+    """
+    Parse all YAML documents in a stream
+    and produce corresponding Python objects.
+
+    Resolve all tags except those known to be
+    unsafe on untrusted input.
+    """
+    return load_all(stream, FullLoader)
+
+def safe_load(stream):
+    """
+    Parse the first YAML document in a stream
+    and produce the corresponding Python object.
+
+    Resolve only basic YAML tags. This is known
+    to be safe for untrusted input.
+    """
+    return load(stream, SafeLoader)
+
+def safe_load_all(stream):
+    """
+    Parse all YAML documents in a stream
+    and produce corresponding Python objects.
+
+    Resolve only basic YAML tags. This is known
+    to be safe for untrusted input.
+    """
+    return load_all(stream, SafeLoader)
+
+def unsafe_load(stream):
+    """
+    Parse the first YAML document in a stream
+    and produce the corresponding Python object.
+
+    Resolve all tags, even those known to be
+    unsafe on untrusted input.
+    """
+    return load(stream, UnsafeLoader)
+
+def unsafe_load_all(stream):
+    """
+    Parse all YAML documents in a stream
+    and produce corresponding Python objects.
+
+    Resolve all tags, even those known to be
+    unsafe on untrusted input.
+    """
+    return load_all(stream, UnsafeLoader)
+
+def emit(events, stream=None, Dumper=Dumper,
+        canonical=None, indent=None, width=None,
+        allow_unicode=None, line_break=None):
+    """
+    Emit YAML parsing events into a stream.
+    If stream is None, return the produced string instead.
+    """
+    getvalue = None
+    if stream is None:
+        stream = io.StringIO()
+        getvalue = stream.getvalue
+    dumper = Dumper(stream, canonical=canonical, indent=indent, width=width,
+            allow_unicode=allow_unicode, line_break=line_break)
+    try:
+        for event in events:
+            dumper.emit(event)
+    finally:
+        dumper.dispose()
+    if getvalue:
+        return getvalue()
+
+def serialize_all(nodes, stream=None, Dumper=Dumper,
+        canonical=None, indent=None, width=None,
+        allow_unicode=None, line_break=None,
+        encoding=None, explicit_start=None, explicit_end=None,
+        version=None, tags=None):
+    """
+    Serialize a sequence of representation trees into a YAML stream.
+    If stream is None, return the produced string instead.
+    """
+    getvalue = None
+    if stream is None:
+        if encoding is None:
+            stream = io.StringIO()
+        else:
+            stream = io.BytesIO()
+        getvalue = stream.getvalue
+    dumper = Dumper(stream, canonical=canonical, indent=indent, width=width,
+            allow_unicode=allow_unicode, line_break=line_break,
+            encoding=encoding, version=version, tags=tags,
+            explicit_start=explicit_start, explicit_end=explicit_end)
+    try:
+        dumper.open()
+        for node in nodes:
+            dumper.serialize(node)
+        dumper.close()
+    finally:
+        dumper.dispose()
+    if getvalue:
+        return getvalue()
+
+def serialize(node, stream=None, Dumper=Dumper, **kwds):
+    """
+    Serialize a representation tree into a YAML stream.
+    If stream is None, return the produced string instead.
+    """
+    return serialize_all([node], stream, Dumper=Dumper, **kwds)
+
+def dump_all(documents, stream=None, Dumper=Dumper,
+        default_style=None, default_flow_style=False,
+        canonical=None, indent=None, width=None,
+        allow_unicode=None, line_break=None,
+        encoding=None, explicit_start=None, explicit_end=None,
+        version=None, tags=None, sort_keys=True):
+    """
+    Serialize a sequence of Python objects into a YAML stream.
+    If stream is None, return the produced string instead.
+    """
+    getvalue = None
+    if stream is None:
+        if encoding is None:
+            stream = io.StringIO()
+        else:
+            stream = io.BytesIO()
+        getvalue = stream.getvalue
+    dumper = Dumper(stream, default_style=default_style,
+            default_flow_style=default_flow_style,
+            canonical=canonical, indent=indent, width=width,
+            allow_unicode=allow_unicode, line_break=line_break,
+            encoding=encoding, version=version, tags=tags,
+            explicit_start=explicit_start, explicit_end=explicit_end, sort_keys=sort_keys)
+    try:
+        dumper.open()
+        for data in documents:
+            dumper.represent(data)
+        dumper.close()
+    finally:
+        dumper.dispose()
+    if getvalue:
+        return getvalue()
+
+def dump(data, stream=None, Dumper=Dumper, **kwds):
+    """
+    Serialize a Python object into a YAML stream.
+    If stream is None, return the produced string instead.
+    """
+    return dump_all([data], stream, Dumper=Dumper, **kwds)
+
+def safe_dump_all(documents, stream=None, **kwds):
+    """
+    Serialize a sequence of Python objects into a YAML stream.
+    Produce only basic YAML tags.
+    If stream is None, return the produced string instead.
+    """
+    return dump_all(documents, stream, Dumper=SafeDumper, **kwds)
+
+def safe_dump(data, stream=None, **kwds):
+    """
+    Serialize a Python object into a YAML stream.
+    Produce only basic YAML tags.
+    If stream is None, return the produced string instead.
+    """
+    return dump_all([data], stream, Dumper=SafeDumper, **kwds)
+
+def add_implicit_resolver(tag, regexp, first=None,
+        Loader=None, Dumper=Dumper):
+    """
+    Add an implicit scalar detector.
+    If an implicit scalar value matches the given regexp,
+    the corresponding tag is assigned to the scalar.
+    first is a sequence of possible initial characters or None.
+    """
+    if Loader is None:
+        loader.Loader.add_implicit_resolver(tag, regexp, first)
+        loader.FullLoader.add_implicit_resolver(tag, regexp, first)
+        loader.UnsafeLoader.add_implicit_resolver(tag, regexp, first)
+    else:
+        Loader.add_implicit_resolver(tag, regexp, first)
+    Dumper.add_implicit_resolver(tag, regexp, first)
+
+def add_path_resolver(tag, path, kind=None, Loader=None, Dumper=Dumper):
+    """
+    Add a path based resolver for the given tag.
+    A path is a list of keys that forms a path
+    to a node in the representation tree.
+    Keys can be string values, integers, or None.
+    """
+    if Loader is None:
+        loader.Loader.add_path_resolver(tag, path, kind)
+        loader.FullLoader.add_path_resolver(tag, path, kind)
+        loader.UnsafeLoader.add_path_resolver(tag, path, kind)
+    else:
+        Loader.add_path_resolver(tag, path, kind)
+    Dumper.add_path_resolver(tag, path, kind)
+
+def add_constructor(tag, constructor, Loader=None):
+    """
+    Add a constructor for the given tag.
+    Constructor is a function that accepts a Loader instance
+    and a node object and produces the corresponding Python object.
+    """
+    if Loader is None:
+        loader.Loader.add_constructor(tag, constructor)
+        loader.FullLoader.add_constructor(tag, constructor)
+        loader.UnsafeLoader.add_constructor(tag, constructor)
+    else:
+        Loader.add_constructor(tag, constructor)
+
+def add_multi_constructor(tag_prefix, multi_constructor, Loader=None):
+    """
+    Add a multi-constructor for the given tag prefix.
+    Multi-constructor is called for a node if its tag starts with tag_prefix.
+    Multi-constructor accepts a Loader instance, a tag suffix,
+    and a node object and produces the corresponding Python object.
+    """
+    if Loader is None:
+        loader.Loader.add_multi_constructor(tag_prefix, multi_constructor)
+        loader.FullLoader.add_multi_constructor(tag_prefix, multi_constructor)
+        loader.UnsafeLoader.add_multi_constructor(tag_prefix, multi_constructor)
+    else:
+        Loader.add_multi_constructor(tag_prefix, multi_constructor)
+
+def add_representer(data_type, representer, Dumper=Dumper):
+    """
+    Add a representer for the given type.
+    Representer is a function accepting a Dumper instance
+    and an instance of the given data type
+    and producing the corresponding representation node.
+    """
+    Dumper.add_representer(data_type, representer)
+
+def add_multi_representer(data_type, multi_representer, Dumper=Dumper):
+    """
+    Add a representer for the given type.
+    Multi-representer is a function accepting a Dumper instance
+    and an instance of the given data type or subtype
+    and producing the corresponding representation node.
+    """
+    Dumper.add_multi_representer(data_type, multi_representer)
+
+class YAMLObjectMetaclass(type):
+    """
+    The metaclass for YAMLObject.
+    """
+    def __init__(cls, name, bases, kwds):
+        super(YAMLObjectMetaclass, cls).__init__(name, bases, kwds)
+        if 'yaml_tag' in kwds and kwds['yaml_tag'] is not None:
+            if isinstance(cls.yaml_loader, list):
+                for loader in cls.yaml_loader:
+                    loader.add_constructor(cls.yaml_tag, cls.from_yaml)
+            else:
+                cls.yaml_loader.add_constructor(cls.yaml_tag, cls.from_yaml)
+
+            cls.yaml_dumper.add_representer(cls, cls.to_yaml)
+
+class YAMLObject(metaclass=YAMLObjectMetaclass):
+    """
+    An object that can dump itself to a YAML stream
+    and load itself from a YAML stream.
+    """
+
+    __slots__ = ()  # no direct instantiation, so allow immutable subclasses
+
+    yaml_loader = [Loader, FullLoader, UnsafeLoader]
+    yaml_dumper = Dumper
+
+    yaml_tag = None
+    yaml_flow_style = None
+
+    @classmethod
+    def from_yaml(cls, loader, node):
+        """
+        Convert a representation node to a Python object.
+        """
+        return loader.construct_yaml_object(node, cls)
+
+    @classmethod
+    def to_yaml(cls, dumper, data):
+        """
+        Convert a Python object to a representation node.
+        """
+        return dumper.represent_yaml_object(cls.yaml_tag, data, cls,
+                flow_style=cls.yaml_flow_style)
+