Wala shell

Advanced PHP File Manager

Server IP: 127.0.0.1 | PHP Version: 8.3.30 | Domains Hosted: 54

Name	Size	Last Modified	Actions
📁 ..	-	2026-03-21 15:45
📄 __init__.py """Command line options, ini-file and conftest.py processing.""" import argparse import collections.abc import copy import dataclasses import enum import glob import inspect import os import re import shlex import sys import types import warnings from functools import lru_cache from pathlib import Path from textwrap import dedent from types import FunctionType from types import TracebackType from typing import Any from typing import Callable from typing import cast from typing import Dict from typing import Generator from typing import IO from typing import Iterable from typing import Iterator from typing import List from typing import Optional from typing import Sequence from typing import Set from typing import TextIO from typing import Tuple from typing import Type from typing import TYPE_CHECKING from typing import Union from pluggy import HookimplMarker from pluggy import HookspecMarker from pluggy import PluginManager import _pytest._code import _pytest.deprecated import _pytest.hookspec from .exceptions import PrintHelp as PrintHelp from .exceptions import UsageError as UsageError from .findpaths import determine_setup from _pytest._code import ExceptionInfo from _pytest._code import filter_traceback from _pytest._io import TerminalWriter from _pytest.compat import final from _pytest.compat import importlib_metadata # type: ignore[attr-defined] from _pytest.outcomes import fail from _pytest.outcomes import Skipped from _pytest.pathlib import absolutepath from _pytest.pathlib import bestrelpath from _pytest.pathlib import import_path from _pytest.pathlib import ImportMode from _pytest.pathlib import resolve_package_path from _pytest.stash import Stash from _pytest.warning_types import PytestConfigWarning from _pytest.warning_types import warn_explicit_for if TYPE_CHECKING: from _pytest._code.code import _TracebackStyle from _pytest.terminal import TerminalReporter from .argparsing import Argument _PluggyPlugin = object """A type to represent plugin objects. Plugins can be any namespace, so we can't narrow it down much, but we use an alias to make the intent clear. Ideally this type would be provided by pluggy itself. """ hookimpl = HookimplMarker("pytest") hookspec = HookspecMarker("pytest") @final class ExitCode(enum.IntEnum): """Encodes the valid exit codes by pytest. Currently users and plugins may supply other exit codes as well. .. versionadded:: 5.0 """ #: Tests passed. OK = 0 #: Tests failed. TESTS_FAILED = 1 #: pytest was interrupted. INTERRUPTED = 2 #: An internal error got in the way. INTERNAL_ERROR = 3 #: pytest was misused. USAGE_ERROR = 4 #: pytest couldn't find tests. NO_TESTS_COLLECTED = 5 class ConftestImportFailure(Exception): def __init__( self, path: Path, excinfo: Tuple[Type[Exception], Exception, TracebackType], ) -> None: super().__init__(path, excinfo) self.path = path self.excinfo = excinfo def __str__(self) -> str: return "{}: {} (from {})".format( self.excinfo[0].__name__, self.excinfo[1], self.path ) def filter_traceback_for_conftest_import_failure( entry: _pytest._code.TracebackEntry, ) -> bool: """Filter tracebacks entries which point to pytest internals or importlib. Make a special case for importlib because we use it to import test modules and conftest files in _pytest.pathlib.import_path. """ return filter_traceback(entry) and "importlib" not in str(entry.path).split(os.sep) def main( args: Optional[Union[List[str], "os.PathLike[str]"]] = None, plugins: Optional[Sequence[Union[str, _PluggyPlugin]]] = None, ) -> Union[int, ExitCode]: """Perform an in-process test run. :param args: List of command line arguments. :param plugins: List of plugin objects to be auto-registered during initialization. :returns: An exit code. """ try: try: config = _prepareconfig(args, plugins) except ConftestImportFailure as e: exc_info = ExceptionInfo.from_exc_info(e.excinfo) tw = TerminalWriter(sys.stderr) tw.line(f"ImportError while loading conftest '{e.path}'.", red=True) exc_info.traceback = exc_info.traceback.filter( filter_traceback_for_conftest_import_failure ) exc_repr = ( exc_info.getrepr(style="short", chain=False) if exc_info.traceback else exc_info.exconly() ) formatted_tb = str(exc_repr) for line in formatted_tb.splitlines(): tw.line(line.rstrip(), red=True) return ExitCode.USAGE_ERROR else: try: ret: Union[ExitCode, int] = config.hook.pytest_cmdline_main( config=config ) try: return ExitCode(ret) except ValueError: return ret finally: config._ensure_unconfigure() except UsageError as e: tw = TerminalWriter(sys.stderr) for msg in e.args: tw.line(f"ERROR: {msg}\n", red=True) return ExitCode.USAGE_ERROR def console_main() -> int: """The CLI entry point of pytest. This function is not meant for programmable use; use `main()` instead. """ # https://docs.python.org/3/library/signal.html#note-on-sigpipe try: code = main() sys.stdout.flush() return code except BrokenPipeError: # Python flushes standard streams on exit; redirect remaining output # to devnull to avoid another BrokenPipeError at shutdown devnull = os.open(os.devnull, os.O_WRONLY) os.dup2(devnull, sys.stdout.fileno()) return 1 # Python exits with error code 1 on EPIPE class cmdline: # compatibility namespace main = staticmethod(main) def filename_arg(path: str, optname: str) -> str: """Argparse type validator for filename arguments. :path: Path of filename. :optname: Name of the option. """ if os.path.isdir(path): raise UsageError(f"{optname} must be a filename, given: {path}") return path def directory_arg(path: str, optname: str) -> str: """Argparse type validator for directory arguments. :path: Path of directory. :optname: Name of the option. """ if not os.path.isdir(path): raise UsageError(f"{optname} must be a directory, given: {path}") return path # Plugins that cannot be disabled via "-p no:X" currently. essential_plugins = ( "mark", "main", "runner", "fixtures", "helpconfig", # Provides -p. ) default_plugins = essential_plugins + ( "python", "terminal", "debugging", "unittest", "capture", "skipping", "legacypath", "tmpdir", "monkeypatch", "recwarn", "pastebin", "nose", "assertion", "junitxml", "doctest", "cacheprovider", "freeze_support", "setuponly", "setupplan", "stepwise", "warnings", "logging", "reports", "python_path", (["unraisableexception", "threadexception"] if sys.version_info >= (3, 8) else []), "faulthandler", ) builtin_plugins = set(default_plugins) builtin_plugins.add("pytester") builtin_plugins.add("pytester_assertions") def get_config( args: Optional[List[str]] = None, plugins: Optional[Sequence[Union[str, _PluggyPlugin]]] = None, ) -> "Config": # subsequent calls to main will create a fresh instance pluginmanager = PytestPluginManager() config = Config( pluginmanager, invocation_params=Config.InvocationParams( args=args or (), plugins=plugins, dir=Path.cwd(), ), ) if args is not None: # Handle any "-p no:plugin" args. pluginmanager.consider_preparse(args, exclude_only=True) for spec in default_plugins: pluginmanager.import_plugin(spec) return config def get_plugin_manager() -> "PytestPluginManager": """Obtain a new instance of the :py:class:`pytest.PytestPluginManager`, with default plugins already loaded. This function can be used by integration with other tools, like hooking into pytest to run tests into an IDE. """ return get_config().pluginmanager def _prepareconfig( args: Optional[Union[List[str], "os.PathLike[str]"]] = None, plugins: Optional[Sequence[Union[str, _PluggyPlugin]]] = None, ) -> "Config": if args is None: args = sys.argv[1:] elif isinstance(args, os.PathLike): args = [os.fspath(args)] elif not isinstance(args, list): msg = ( # type:ignore[unreachable] "`args` parameter expected to be a list of strings, got: {!r} (type: {})" ) raise TypeError(msg.format(args, type(args))) config = get_config(args, plugins) pluginmanager = config.pluginmanager try: if plugins: for plugin in plugins: if isinstance(plugin, str): pluginmanager.consider_pluginarg(plugin) else: pluginmanager.register(plugin) config = pluginmanager.hook.pytest_cmdline_parse( pluginmanager=pluginmanager, args=args ) return config except BaseException: config._ensure_unconfigure() raise def _get_directory(path: Path) -> Path: """Get the directory of a path - itself if already a directory.""" if path.is_file(): return path.parent else: return path def _get_legacy_hook_marks( method: Any, hook_type: str, opt_names: Tuple[str, ...], ) -> Dict[str, bool]: if TYPE_CHECKING: # abuse typeguard from importlib to avoid massive method type union thats lacking a alias assert inspect.isroutine(method) known_marks: set[str] = {m.name for m in getattr(method, "pytestmark", [])} must_warn: list[str] = [] opts: dict[str, bool] = {} for opt_name in opt_names: opt_attr = getattr(method, opt_name, AttributeError) if opt_attr is not AttributeError: must_warn.append(f"{opt_name}={opt_attr}") opts[opt_name] = True elif opt_name in known_marks: must_warn.append(f"{opt_name}=True") opts[opt_name] = True else: opts[opt_name] = False if must_warn: hook_opts = ", ".join(must_warn) message = _pytest.deprecated.HOOK_LEGACY_MARKING.format( type=hook_type, fullname=method.__qualname__, hook_opts=hook_opts, ) warn_explicit_for(cast(FunctionType, method), message) return opts @final class PytestPluginManager(PluginManager): """A :py:class:`pluggy.PluginManager <pluggy.PluginManager>` with additional pytest-specific functionality: Loading plugins from the command line, ``PYTEST_PLUGINS`` env variable and ``pytest_plugins`` global variables found in plugins being loaded. * ``conftest.py`` loading during start-up. """ def __init__(self) -> None: import _pytest.assertion super().__init__("pytest") # -- State related to local conftest plugins. # All loaded conftest modules. self._conftest_plugins: Set[types.ModuleType] = set() # All conftest modules applicable for a directory. # This includes the directory's own conftest modules as well # as those of its parent directories. self._dirpath2confmods: Dict[Path, List[types.ModuleType]] = {} # Cutoff directory above which conftests are no longer discovered. self._confcutdir: Optional[Path] = None # If set, conftest loading is skipped. self._noconftest = False # _getconftestmodules()'s call to _get_directory() causes a stat # storm when it's called potentially thousands of times in a test # session (#9478), often with the same path, so cache it. self._get_directory = lru_cache(256)(_get_directory) self._duplicatepaths: Set[Path] = set() # plugins that were explicitly skipped with pytest.skip # list of (module name, skip reason) # previously we would issue a warning when a plugin was skipped, but # since we refactored warnings as first citizens of Config, they are # just stored here to be used later. self.skipped_plugins: List[Tuple[str, str]] = [] self.add_hookspecs(_pytest.hookspec) self.register(self) if os.environ.get("PYTEST_DEBUG"): err: IO[str] = sys.stderr encoding: str = getattr(err, "encoding", "utf8") try: err = open( os.dup(err.fileno()), mode=err.mode, buffering=1, encoding=encoding, ) except Exception: pass self.trace.root.setwriter(err.write) self.enable_tracing() # Config._consider_importhook will set a real object if required. self.rewrite_hook = _pytest.assertion.DummyRewriteHook() # Used to know when we are importing conftests after the pytest_configure stage. self._configured = False def parse_hookimpl_opts(self, plugin: _PluggyPlugin, name: str): # pytest hooks are always prefixed with "pytest_", # so we avoid accessing possibly non-readable attributes # (see issue #1073). if not name.startswith("pytest_"): return # Ignore names which can not be hooks. if name == "pytest_plugins": return opts = super().parse_hookimpl_opts(plugin, name) if opts is not None: return opts method = getattr(plugin, name) # Consider only actual functions for hooks (#3775). if not inspect.isroutine(method): return # Collect unmarked hooks as long as they have the `pytest_' prefix. return _get_legacy_hook_marks( method, "impl", ("tryfirst", "trylast", "optionalhook", "hookwrapper") ) def parse_hookspec_opts(self, module_or_class, name: str): opts = super().parse_hookspec_opts(module_or_class, name) if opts is None: method = getattr(module_or_class, name) if name.startswith("pytest_"): opts = _get_legacy_hook_marks( method, "spec", ("firstresult", "historic"), ) return opts def register( self, plugin: _PluggyPlugin, name: Optional[str] = None ) -> Optional[str]: if name in _pytest.deprecated.DEPRECATED_EXTERNAL_PLUGINS: warnings.warn( PytestConfigWarning( "{} plugin has been merged into the core, " "please remove it from your requirements.".format( name.replace("_", "-") ) ) ) return None ret: Optional[str] = super().register(plugin, name) if ret: self.hook.pytest_plugin_registered.call_historic( kwargs=dict(plugin=plugin, manager=self) ) if isinstance(plugin, types.ModuleType): self.consider_module(plugin) return ret def getplugin(self, name: str): # Support deprecated naming because plugins (xdist e.g.) use it. plugin: Optional[_PluggyPlugin] = self.get_plugin(name) return plugin def hasplugin(self, name: str) -> bool: """Return whether a plugin with the given name is registered.""" return bool(self.get_plugin(name)) def pytest_configure(self, config: "Config") -> None: """:meta private:""" # XXX now that the pluginmanager exposes hookimpl(tryfirst...) # we should remove tryfirst/trylast as markers. config.addinivalue_line( "markers", "tryfirst: mark a hook implementation function such that the " "plugin machinery will try to call it first/as early as possible. " "DEPRECATED, use @pytest.hookimpl(tryfirst=True) instead.", ) config.addinivalue_line( "markers", "trylast: mark a hook implementation function such that the " "plugin machinery will try to call it last/as late as possible. " "DEPRECATED, use @pytest.hookimpl(trylast=True) instead.", ) self._configured = True # # Internal API for local conftest plugin handling. # def _set_initial_conftests( self, args: Sequence[Union[str, Path]], pyargs: bool, noconftest: bool, rootpath: Path, confcutdir: Optional[Path], importmode: Union[ImportMode, str], ) -> None: """Load initial conftest files given a preparsed "namespace". As conftest files may add their own command line options which have arguments ('--my-opt somepath') we might get some false positives. All builtin and 3rd party plugins will have been loaded, however, so common options will not confuse our logic here. """ current = Path.cwd() self._confcutdir = absolutepath(current / confcutdir) if confcutdir else None self._noconftest = noconftest self._using_pyargs = pyargs foundanchor = False for intitial_path in args: path = str(intitial_path) # remove node-id syntax i = path.find("::") if i != -1: path = path[:i] anchor = absolutepath(current / path) # Ensure we do not break if what appears to be an anchor # is in fact a very long option (#10169). try: anchor_exists = anchor.exists() except OSError: # pragma: no cover anchor_exists = False if anchor_exists: self._try_load_conftest(anchor, importmode, rootpath) foundanchor = True if not foundanchor: self._try_load_conftest(current, importmode, rootpath) def _is_in_confcutdir(self, path: Path) -> bool: """Whether a path is within the confcutdir. When false, should not load conftest. """ if self._confcutdir is None: return True return path not in self._confcutdir.parents def _try_load_conftest( self, anchor: Path, importmode: Union[str, ImportMode], rootpath: Path ) -> None: self._getconftestmodules(anchor, importmode, rootpath) # let's also consider test* subdirs if anchor.is_dir(): for x in anchor.glob("test"): if x.is_dir(): self._getconftestmodules(x, importmode, rootpath) def _getconftestmodules( self, path: Path, importmode: Union[str, ImportMode], rootpath: Path ) -> Sequence[types.ModuleType]: if self._noconftest: return [] directory = self._get_directory(path) # Optimization: avoid repeated searches in the same directory. # Assumes always called with same importmode and rootpath. existing_clist = self._dirpath2confmods.get(directory) if existing_clist is not None: return existing_clist # XXX these days we may rather want to use config.rootpath # and allow users to opt into looking into the rootdir parent # directories instead of requiring to specify confcutdir. clist = [] for parent in reversed((directory, directory.parents)): if self._is_in_confcutdir(parent): conftestpath = parent / "conftest.py" if conftestpath.is_file(): mod = self._importconftest(conftestpath, importmode, rootpath) clist.append(mod) self._dirpath2confmods[directory] = clist return clist def _rget_with_confmod( self, name: str, path: Path, importmode: Union[str, ImportMode], rootpath: Path, ) -> Tuple[types.ModuleType, Any]: modules = self._getconftestmodules(path, importmode, rootpath=rootpath) for mod in reversed(modules): try: return mod, getattr(mod, name) except AttributeError: continue raise KeyError(name) def _importconftest( self, conftestpath: Path, importmode: Union[str, ImportMode], rootpath: Path ) -> types.ModuleType: existing = self.get_plugin(str(conftestpath)) if existing is not None: return cast(types.ModuleType, existing) pkgpath = resolve_package_path(conftestpath) if pkgpath is None: _ensure_removed_sysmodule(conftestpath.stem) try: mod = import_path(conftestpath, mode=importmode, root=rootpath) except Exception as e: assert e.__traceback__ is not None exc_info = (type(e), e, e.__traceback__) raise ConftestImportFailure(conftestpath, exc_info) from e self._check_non_top_pytest_plugins(mod, conftestpath) self._conftest_plugins.add(mod) dirpath = conftestpath.parent if dirpath in self._dirpath2confmods: for path, mods in self._dirpath2confmods.items(): if dirpath in path.parents or path == dirpath: assert mod not in mods mods.append(mod) self.trace(f"loading conftestmodule {mod!r}") self.consider_conftest(mod) return mod def _check_non_top_pytest_plugins( self, mod: types.ModuleType, conftestpath: Path, ) -> None: if ( hasattr(mod, "pytest_plugins") and self._configured and not self._using_pyargs ): msg = ( "Defining 'pytest_plugins' in a non-top-level conftest is no longer supported:\n" "It affects the entire test suite instead of just below the conftest as expected.\n" " {}\n" "Please move it to a top level conftest file at the rootdir:\n" " {}\n" "For more information, visit:\n" " https://docs.pytest.org/en/stable/deprecations.html#pytest-plugins-in-non-top-level-conftest-files" ) fail(msg.format(conftestpath, self._confcutdir), pytrace=False) # # API for bootstrapping plugin loading # # def consider_preparse( self, args: Sequence[str], , exclude_only: bool = False ) -> None: """:meta private:""" i = 0 n = len(args) while i < n: opt = args[i] i += 1 if isinstance(opt, str): if opt == "-p": try: parg = args[i] except IndexError: return i += 1 elif opt.startswith("-p"): parg = opt[2:] else: continue parg = parg.strip() if exclude_only and not parg.startswith("no:"): continue self.consider_pluginarg(parg) def consider_pluginarg(self, arg: str) -> None: """:meta private:""" if arg.startswith("no:"): name = arg[3:] if name in essential_plugins: raise UsageError("plugin %s cannot be disabled" % name) # PR #4304: remove stepwise if cacheprovider is blocked. if name == "cacheprovider": self.set_blocked("stepwise") self.set_blocked("pytest_stepwise") self.set_blocked(name) if not name.startswith("pytest_"): self.set_blocked("pytest_" + name) else: name = arg # Unblock the plugin. None indicates that it has been blocked. # There is no interface with pluggy for this. if self._name2plugin.get(name, -1) is None: del self._name2plugin[name] if not name.startswith("pytest_"): if self._name2plugin.get("pytest_" + name, -1) is None: del self._name2plugin["pytest_" + name] self.import_plugin(arg, consider_entry_points=True) def consider_conftest(self, conftestmodule: types.ModuleType) -> None: """:meta private:""" self.register(conftestmodule, name=conftestmodule.__file__) def consider_env(self) -> None: """:meta private:""" self._import_plugin_specs(os.environ.get("PYTEST_PLUGINS")) def consider_module(self, mod: types.ModuleType) -> None: """:meta private:""" self._import_plugin_specs(getattr(mod, "pytest_plugins", [])) def _import_plugin_specs( self, spec: Union[None, types.ModuleType, str, Sequence[str]] ) -> None: plugins = _get_plugin_specs_as_list(spec) for import_spec in plugins: self.import_plugin(import_spec) def import_plugin(self, modname: str, consider_entry_points: bool = False) -> None: """Import a plugin with ``modname``. If ``consider_entry_points`` is True, entry point names are also considered to find a plugin. """ # Most often modname refers to builtin modules, e.g. "pytester", # "terminal" or "capture". Those plugins are registered under their # basename for historic purposes but must be imported with the # _pytest prefix. assert isinstance(modname, str), ( "module name as text required, got %r" % modname ) if self.is_blocked(modname) or self.get_plugin(modname) is not None: return importspec = "_pytest." + modname if modname in builtin_plugins else modname self.rewrite_hook.mark_rewrite(importspec) if consider_entry_points: loaded = self.load_setuptools_entrypoints("pytest11", name=modname) if loaded: return try: __import__(importspec) except ImportError as e: raise ImportError( f'Error importing plugin "{modname}": {e.args[0]}' ).with_traceback(e.__traceback__) from e except Skipped as e: self.skipped_plugins.append((modname, e.msg or "")) else: mod = sys.modules[importspec] self.register(mod, modname) def _get_plugin_specs_as_list( specs: Union[None, types.ModuleType, str, Sequence[str]] ) -> List[str]: """Parse a plugins specification into a list of plugin names.""" # None means empty. if specs is None: return [] # Workaround for #3899 - a submodule which happens to be called "pytest_plugins". if isinstance(specs, types.ModuleType): return [] # Comma-separated list. if isinstance(specs, str): return specs.split(",") if specs else [] # Direct specification. if isinstance(specs, collections.abc.Sequence): return list(specs) raise UsageError( "Plugins may be specified as a sequence or a ','-separated string of plugin names. Got: %r" % specs ) def _ensure_removed_sysmodule(modname: str) -> None: try: del sys.modules[modname] except KeyError: pass class Notset: def __repr__(self): return "<NOTSET>" notset = Notset() def _iter_rewritable_modules(package_files: Iterable[str]) -> Iterator[str]: """Given an iterable of file names in a source distribution, return the "names" that should be marked for assertion rewrite. For example the package "pytest_mock/__init__.py" should be added as "pytest_mock" in the assertion rewrite mechanism. This function has to deal with dist-info based distributions and egg based distributions (which are still very much in use for "editable" installs). Here are the file names as seen in a dist-info based distribution: pytest_mock/__init__.py pytest_mock/_version.py pytest_mock/plugin.py pytest_mock.egg-info/PKG-INFO Here are the file names as seen in an egg based distribution: src/pytest_mock/__init__.py src/pytest_mock/_version.py src/pytest_mock/plugin.py src/pytest_mock.egg-info/PKG-INFO LICENSE setup.py We have to take in account those two distribution flavors in order to determine which names should be considered for assertion rewriting. More information: https://github.com/pytest-dev/pytest-mock/issues/167 """ package_files = list(package_files) seen_some = False for fn in package_files: is_simple_module = "/" not in fn and fn.endswith(".py") is_package = fn.count("/") == 1 and fn.endswith("__init__.py") if is_simple_module: module_name, _ = os.path.splitext(fn) # we ignore "setup.py" at the root of the distribution # as well as editable installation finder modules made by setuptools if module_name != "setup" and not module_name.startswith("__editable__"): seen_some = True yield module_name elif is_package: package_name = os.path.dirname(fn) seen_some = True yield package_name if not seen_some: # At this point we did not find any packages or modules suitable for assertion # rewriting, so we try again by stripping the first path component (to account for # "src" based source trees for example). # This approach lets us have the common case continue to be fast, as egg-distributions # are rarer. new_package_files = [] for fn in package_files: parts = fn.split("/") new_fn = "/".join(parts[1:]) if new_fn: new_package_files.append(new_fn) if new_package_files: yield from _iter_rewritable_modules(new_package_files) @final class Config: """Access to configuration values, pluginmanager and plugin hooks. :param PytestPluginManager pluginmanager: A pytest PluginManager. :param InvocationParams invocation_params: Object containing parameters regarding the :func:`pytest.main` invocation. """ @final @dataclasses.dataclass(frozen=True) class InvocationParams: """Holds parameters passed during :func:`pytest.main`. The object attributes are read-only. .. versionadded:: 5.1 .. note:: Note that the environment variable ``PYTEST_ADDOPTS`` and the ``addopts`` ini option are handled by pytest, not being included in the ``args`` attribute. Plugins accessing ``InvocationParams`` must be aware of that. """ args: Tuple[str, ...] """The command-line arguments as passed to :func:`pytest.main`.""" plugins: Optional[Sequence[Union[str, _PluggyPlugin]]] """Extra plugins, might be `None`.""" dir: Path """The directory from which :func:`pytest.main` was invoked.""" def __init__( self, , args: Iterable[str], plugins: Optional[Sequence[Union[str, _PluggyPlugin]]], dir: Path, ) -> None: object.__setattr__(self, "args", tuple(args)) object.__setattr__(self, "plugins", plugins) object.__setattr__(self, "dir", dir) class ArgsSource(enum.Enum): """Indicates the source of the test arguments. .. versionadded:: 7.2 """ #: Command line arguments. ARGS = enum.auto() #: Invocation directory. INCOVATION_DIR = enum.auto() #: 'testpaths' configuration value. TESTPATHS = enum.auto() def __init__( self, pluginmanager: PytestPluginManager, , invocation_params: Optional[InvocationParams] = None, ) -> None: from .argparsing import Parser, FILE_OR_DIR if invocation_params is None: invocation_params = self.InvocationParams( args=(), plugins=None, dir=Path.cwd() ) self.option = argparse.Namespace() """Access to command line option as attributes. :type: argparse.Namespace """ self.invocation_params = invocation_params """The parameters with which pytest was invoked. :type: InvocationParams """ _a = FILE_OR_DIR self._parser = Parser( usage=f"%(prog)s [options] [{_a}] [{_a}] [...]", processopt=self._processopt, _ispytest=True, ) self.pluginmanager = pluginmanager """The plugin manager handles plugin registration and hook invocation. :type: PytestPluginManager """ self.stash = Stash() """A place where plugins can store information on the config for their own use. :type: Stash """ # Deprecated alias. Was never public. Can be removed in a few releases. self._store = self.stash from .compat import PathAwareHookProxy self.trace = self.pluginmanager.trace.root.get("config") self.hook = PathAwareHookProxy(self.pluginmanager.hook) self._inicache: Dict[str, Any] = {} self._override_ini: Sequence[str] = () self._opt2dest: Dict[str, str] = {} self._cleanup: List[Callable[[], None]] = [] self.pluginmanager.register(self, "pytestconfig") self._configured = False self.hook.pytest_addoption.call_historic( kwargs=dict(parser=self._parser, pluginmanager=self.pluginmanager) ) self.args_source = Config.ArgsSource.ARGS self.args: List[str] = [] if TYPE_CHECKING: from _pytest.cacheprovider import Cache self.cache: Optional[Cache] = None @property def rootpath(self) -> Path: """The path to the :ref:`rootdir <rootdir>`. :type: pathlib.Path .. versionadded:: 6.1 """ return self._rootpath @property def inipath(self) -> Optional[Path]: """The path to the :ref:`configfile <configfiles>`. :type: Optional[pathlib.Path] .. versionadded:: 6.1 """ return self._inipath def add_cleanup(self, func: Callable[[], None]) -> None: """Add a function to be called when the config object gets out of use (usually coinciding with pytest_unconfigure).""" self._cleanup.append(func) def _do_configure(self) -> None: assert not self._configured self._configured = True with warnings.catch_warnings(): warnings.simplefilter("default") self.hook.pytest_configure.call_historic(kwargs=dict(config=self)) def _ensure_unconfigure(self) -> None: if self._configured: self._configured = False self.hook.pytest_unconfigure(config=self) self.hook.pytest_configure._call_history = [] while self._cleanup: fin = self._cleanup.pop() fin() def get_terminal_writer(self) -> TerminalWriter: terminalreporter: TerminalReporter = self.pluginmanager.get_plugin( "terminalreporter" ) return terminalreporter._tw def pytest_cmdline_parse( self, pluginmanager: PytestPluginManager, args: List[str] ) -> "Config": try: self.parse(args) except UsageError: # Handle --version and --help here in a minimal fashion. # This gets done via helpconfig normally, but its # pytest_cmdline_main is not called in case of errors. if getattr(self.option, "version", False) or "--version" in args: from _pytest.helpconfig import showversion showversion(self) elif ( getattr(self.option, "help", False) or "--help" in args or "-h" in args ): self._parser._getparser().print_help() sys.stdout.write( "\nNOTE: displaying only minimal help due to UsageError.\n\n" ) raise return self def notify_exception( self, excinfo: ExceptionInfo[BaseException], option: Optional[argparse.Namespace] = None, ) -> None: if option and getattr(option, "fulltrace", False): style: _TracebackStyle = "long" else: style = "native" excrepr = excinfo.getrepr( funcargs=True, showlocals=getattr(option, "showlocals", False), style=style ) res = self.hook.pytest_internalerror(excrepr=excrepr, excinfo=excinfo) if not any(res): for line in str(excrepr).split("\n"): sys.stderr.write("INTERNALERROR> %s\n" % line) sys.stderr.flush() def cwd_relative_nodeid(self, nodeid: str) -> str: # nodeid's are relative to the rootpath, compute relative to cwd. if self.invocation_params.dir != self.rootpath: fullpath = self.rootpath / nodeid nodeid = bestrelpath(self.invocation_params.dir, fullpath) return nodeid @classmethod def fromdictargs(cls, option_dict, args) -> "Config": """Constructor usable for subprocesses.""" config = get_config(args) config.option.__dict__.update(option_dict) config.parse(args, addopts=False) for x in config.option.plugins: config.pluginmanager.consider_pluginarg(x) return config def _processopt(self, opt: "Argument") -> None: for name in opt._short_opts + opt._long_opts: self._opt2dest[name] = opt.dest if hasattr(opt, "default"): if not hasattr(self.option, opt.dest): setattr(self.option, opt.dest, opt.default) @hookimpl(trylast=True) def pytest_load_initial_conftests(self, early_config: "Config") -> None: # We haven't fully parsed the command line arguments yet, so # early_config.args it not set yet. But we need it for # discovering the initial conftests. So "pre-run" the logic here. # It will be done for real in `parse()`. args, args_source = early_config._decide_args( args=early_config.known_args_namespace.file_or_dir, pyargs=early_config.known_args_namespace.pyargs, testpaths=early_config.getini("testpaths"), invocation_dir=early_config.invocation_params.dir, rootpath=early_config.rootpath, warn=False, ) self.pluginmanager._set_initial_conftests( args=args, pyargs=early_config.known_args_namespace.pyargs, noconftest=early_config.known_args_namespace.noconftest, rootpath=early_config.rootpath, confcutdir=early_config.known_args_namespace.confcutdir, importmode=early_config.known_args_namespace.importmode, ) def _initini(self, args: Sequence[str]) -> None: ns, unknown_args = self._parser.parse_known_and_unknown_args( args, namespace=copy.copy(self.option) ) rootpath, inipath, inicfg = determine_setup( ns.inifilename, ns.file_or_dir + unknown_args, rootdir_cmd_arg=ns.rootdir or None, config=self, ) self._rootpath = rootpath self._inipath = inipath self.inicfg = inicfg self._parser.extra_info["rootdir"] = str(self.rootpath) self._parser.extra_info["inifile"] = str(self.inipath) self._parser.addini("addopts", "Extra command line options", "args") self._parser.addini("minversion", "Minimally required pytest version") self._parser.addini( "required_plugins", "Plugins that must be present for pytest to run", type="args", default=[], ) self._override_ini = ns.override_ini or () def _consider_importhook(self, args: Sequence[str]) -> None: """Install the PEP 302 import hook if using assertion rewriting. Needs to parse the --assert=<mode> option from the commandline and find all the installed plugins to mark them for rewriting by the importhook. """ ns, unknown_args = self._parser.parse_known_and_unknown_args(args) mode = getattr(ns, "assertmode", "plain") if mode == "rewrite": import _pytest.assertion try: hook = _pytest.assertion.install_importhook(self) except SystemError: mode = "plain" else: self._mark_plugins_for_rewrite(hook) self._warn_about_missing_assertion(mode) def _mark_plugins_for_rewrite(self, hook) -> None: """Given an importhook, mark for rewrite any top-level modules or packages in the distribution package for all pytest plugins.""" self.pluginmanager.rewrite_hook = hook if os.environ.get("PYTEST_DISABLE_PLUGIN_AUTOLOAD"): # We don't autoload from setuptools entry points, no need to continue. return package_files = ( str(file) for dist in importlib_metadata.distributions() if any(ep.group == "pytest11" for ep in dist.entry_points) for file in dist.files or [] ) for name in _iter_rewritable_modules(package_files): hook.mark_rewrite(name) def _validate_args(self, args: List[str], via: str) -> List[str]: """Validate known args.""" self._parser._config_source_hint = via # type: ignore try: self._parser.parse_known_and_unknown_args( args, namespace=copy.copy(self.option) ) finally: del self._parser._config_source_hint # type: ignore return args def _decide_args( self, , args: List[str], pyargs: List[str], testpaths: List[str], invocation_dir: Path, rootpath: Path, warn: bool, ) -> Tuple[List[str], ArgsSource]: """Decide the args (initial paths/nodeids) to use given the relevant inputs. :param warn: Whether can issue warnings. """ if args: source = Config.ArgsSource.ARGS result = args else: if invocation_dir == rootpath: source = Config.ArgsSource.TESTPATHS if pyargs: result = testpaths else: result = [] for path in testpaths: result.extend(sorted(glob.iglob(path, recursive=True))) if testpaths and not result: if warn: warning_text = ( "No files were found in testpaths; " "consider removing or adjusting your testpaths configuration. " "Searching recursively from the current directory instead." ) self.issue_config_time_warning( PytestConfigWarning(warning_text), stacklevel=3 ) else: result = [] if not result: source = Config.ArgsSource.INCOVATION_DIR result = [str(invocation_dir)] return result, source def _preparse(self, args: List[str], addopts: bool = True) -> None: if addopts: env_addopts = os.environ.get("PYTEST_ADDOPTS", "") if len(env_addopts): args[:] = ( self._validate_args(shlex.split(env_addopts), "via PYTEST_ADDOPTS") + args ) self._initini(args) if addopts: args[:] = ( self._validate_args(self.getini("addopts"), "via addopts config") + args ) self.known_args_namespace = self._parser.parse_known_args( args, namespace=copy.copy(self.option) ) self._checkversion() self._consider_importhook(args) self.pluginmanager.consider_preparse(args, exclude_only=False) if not os.environ.get("PYTEST_DISABLE_PLUGIN_AUTOLOAD"): # Don't autoload from setuptools entry point. Only explicitly specified # plugins are going to be loaded. self.pluginmanager.load_setuptools_entrypoints("pytest11") self.pluginmanager.consider_env() self.known_args_namespace = self._parser.parse_known_args( args, namespace=copy.copy(self.known_args_namespace) ) self._validate_plugins() self._warn_about_skipped_plugins() if self.known_args_namespace.strict: self.issue_config_time_warning( _pytest.deprecated.STRICT_OPTION, stacklevel=2 ) if self.known_args_namespace.confcutdir is None: if self.inipath is not None: confcutdir = str(self.inipath.parent) else: confcutdir = str(self.rootpath) self.known_args_namespace.confcutdir = confcutdir try: self.hook.pytest_load_initial_conftests( early_config=self, args=args, parser=self._parser ) except ConftestImportFailure as e: if self.known_args_namespace.help or self.known_args_namespace.version: # we don't want to prevent --help/--version to work # so just let is pass and print a warning at the end self.issue_config_time_warning( PytestConfigWarning(f"could not load initial conftests: {e.path}"), stacklevel=2, ) else: raise @hookimpl(hookwrapper=True) def pytest_collection(self) -> Generator[None, None, None]: # Validate invalid ini keys after collection is done so we take in account # options added by late-loading conftest files. yield self._validate_config_options() def _checkversion(self) -> None: import pytest minver = self.inicfg.get("minversion", None) if minver: # Imported lazily to improve start-up time. from packaging.version import Version if not isinstance(minver, str): raise pytest.UsageError( "%s: 'minversion' must be a single value" % self.inipath ) if Version(minver) > Version(pytest.__version__): raise pytest.UsageError( "%s: 'minversion' requires pytest-%s, actual pytest-%s'" % ( self.inipath, minver, pytest.__version__, ) ) def _validate_config_options(self) -> None: for key in sorted(self._get_unknown_ini_keys()): self._warn_or_fail_if_strict(f"Unknown config option: {key}\n") def _validate_plugins(self) -> None: required_plugins = sorted(self.getini("required_plugins")) if not required_plugins: return # Imported lazily to improve start-up time. from packaging.version import Version from packaging.requirements import InvalidRequirement, Requirement plugin_info = self.pluginmanager.list_plugin_distinfo() plugin_dist_info = {dist.project_name: dist.version for _, dist in plugin_info} missing_plugins = [] for required_plugin in required_plugins: try: req = Requirement(required_plugin) except InvalidRequirement: missing_plugins.append(required_plugin) continue if req.name not in plugin_dist_info: missing_plugins.append(required_plugin) elif not req.specifier.contains( Version(plugin_dist_info[req.name]), prereleases=True ): missing_plugins.append(required_plugin) if missing_plugins: raise UsageError( "Missing required plugins: {}".format(", ".join(missing_plugins)), ) def _warn_or_fail_if_strict(self, message: str) -> None: if self.known_args_namespace.strict_config: raise UsageError(message) self.issue_config_time_warning(PytestConfigWarning(message), stacklevel=3) def _get_unknown_ini_keys(self) -> List[str]: parser_inicfg = self._parser._inidict return [name for name in self.inicfg if name not in parser_inicfg] def parse(self, args: List[str], addopts: bool = True) -> None: # Parse given cmdline arguments into this config object. assert ( self.args == [] ), "can only parse cmdline args at most once per Config object" self.hook.pytest_addhooks.call_historic( kwargs=dict(pluginmanager=self.pluginmanager) ) self._preparse(args, addopts=addopts) # XXX deprecated hook: self.hook.pytest_cmdline_preparse(config=self, args=args) self._parser.after_preparse = True # type: ignore try: args = self._parser.parse_setoption( args, self.option, namespace=self.option ) self.args, self.args_source = self._decide_args( args=args, pyargs=self.known_args_namespace.pyargs, testpaths=self.getini("testpaths"), invocation_dir=self.invocation_params.dir, rootpath=self.rootpath, warn=True, ) except PrintHelp: pass def issue_config_time_warning(self, warning: Warning, stacklevel: int) -> None: """Issue and handle a warning during the "configure" stage. During ``pytest_configure`` we can't capture warnings using the ``catch_warnings_for_item`` function because it is not possible to have hookwrappers around ``pytest_configure``. This function is mainly intended for plugins that need to issue warnings during ``pytest_configure`` (or similar stages). :param warning: The warning instance. :param stacklevel: stacklevel forwarded to warnings.warn. """ if self.pluginmanager.is_blocked("warnings"): return cmdline_filters = self.known_args_namespace.pythonwarnings or [] config_filters = self.getini("filterwarnings") with warnings.catch_warnings(record=True) as records: warnings.simplefilter("always", type(warning)) apply_warning_filters(config_filters, cmdline_filters) warnings.warn(warning, stacklevel=stacklevel) if records: frame = sys._getframe(stacklevel - 1) location = frame.f_code.co_filename, frame.f_lineno, frame.f_code.co_name self.hook.pytest_warning_recorded.call_historic( kwargs=dict( warning_message=records[0], when="config", nodeid="", location=location, ) ) def addinivalue_line(self, name: str, line: str) -> None: """Add a line to an ini-file option. The option must have been declared but might not yet be set in which case the line becomes the first line in its value.""" x = self.getini(name) assert isinstance(x, list) x.append(line) # modifies the cached list inline def getini(self, name: str): """Return configuration value from an :ref:`ini file <configfiles>`. If the specified name hasn't been registered through a prior :func:`parser.addini <pytest.Parser.addini>` call (usually from a plugin), a ValueError is raised. """ try: return self._inicache[name] except KeyError: self._inicache[name] = val = self._getini(name) return val # Meant for easy monkeypatching by legacypath plugin. # Can be inlined back (with no cover removed) once legacypath is gone. def _getini_unknown_type(self, name: str, type: str, value: Union[str, List[str]]): msg = f"unknown configuration type: {type}" raise ValueError(msg, value) # pragma: no cover def _getini(self, name: str): try: description, type, default = self._parser._inidict[name] except KeyError as e: raise ValueError(f"unknown configuration value: {name!r}") from e override_value = self._get_override_ini_value(name) if override_value is None: try: value = self.inicfg[name] except KeyError: if default is not None: return default if type is None: return "" return [] else: value = override_value # Coerce the values based on types. # # Note: some coercions are only required if we are reading from .ini files, because # the file format doesn't contain type information, but when reading from toml we will # get either str or list of str values (see _parse_ini_config_from_pyproject_toml). # For example: # # ini: # a_line_list = "tests acceptance" # in this case, we need to split the string to obtain a list of strings. # # toml: # a_line_list = ["tests", "acceptance"] # in this case, we already have a list ready to use. # if type == "paths": # 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 [dp / x for x in input_values] elif type == "args": return shlex.split(value) if isinstance(value, str) else value elif type == "linelist": if isinstance(value, str): return [t for t in map(lambda x: x.strip(), value.split("\n")) if t] else: return value elif type == "bool": return _strtobool(str(value).strip()) elif type == "string": return value elif type is None: return value else: return self._getini_unknown_type(name, type, value) def _getconftest_pathlist( self, name: str, path: Path, rootpath: Path ) -> Optional[List[Path]]: try: mod, relroots = self.pluginmanager._rget_with_confmod( name, path, self.getoption("importmode"), rootpath ) except KeyError: return None assert mod.__file__ is not None modpath = Path(mod.__file__).parent values: List[Path] = [] for relroot in relroots: if isinstance(relroot, os.PathLike): relroot = Path(relroot) else: relroot = relroot.replace("/", os.sep) relroot = absolutepath(modpath / relroot) values.append(relroot) return values def _get_override_ini_value(self, name: str) -> Optional[str]: value = None # override_ini is a list of "ini=value" options. # Always use the last item if multiple values are set for same ini-name, # e.g. -o foo=bar1 -o foo=bar2 will set foo to bar2. for ini_config in self._override_ini: try: key, user_ini_value = ini_config.split("=", 1) except ValueError as e: raise UsageError( "-o/--override-ini expects option=value style (got: {!r}).".format( ini_config ) ) from e else: if key == name: value = user_ini_value return value def getoption(self, name: str, default=notset, skip: bool = False): """Return command line option value. :param name: Name of the option. You may also specify the literal ``--OPT`` option instead of the "dest" option name. :param default: Default value if no option of that name exists. :param skip: If True, raise pytest.skip if option does not exists or has a None value. """ name = self._opt2dest.get(name, name) try: val = getattr(self.option, name) if val is None and skip: raise AttributeError(name) return val except AttributeError as e: if default is not notset: return default if skip: import pytest pytest.skip(f"no {name!r} option found") raise ValueError(f"no option named {name!r}") from e def getvalue(self, name: str, path=None): """Deprecated, use getoption() instead.""" return self.getoption(name) def getvalueorskip(self, name: str, path=None): """Deprecated, use getoption(skip=True) instead.""" return self.getoption(name, skip=True) def _warn_about_missing_assertion(self, mode: str) -> None: if not _assertion_supported(): if mode == "plain": warning_text = ( "ASSERTIONS ARE NOT EXECUTED" " and FAILING TESTS WILL PASS. Are you" " using python -O?" ) else: warning_text = ( "assertions not in test modules or" " plugins will be ignored" " because assert statements are not executed " "by the underlying Python interpreter " "(are you using python -O?)\n" ) self.issue_config_time_warning( PytestConfigWarning(warning_text), stacklevel=3, ) def _warn_about_skipped_plugins(self) -> None: for module_name, msg in self.pluginmanager.skipped_plugins: self.issue_config_time_warning( PytestConfigWarning(f"skipped plugin {module_name!r}: {msg}"), stacklevel=2, ) def _assertion_supported() -> bool: try: assert False except AssertionError: return True else: return False # type: ignore[unreachable] def create_terminal_writer( config: Config, file: Optional[TextIO] = None ) -> TerminalWriter: """Create a TerminalWriter instance configured according to the options in the config object. Every code which requires a TerminalWriter object and has access to a config object should use this function. """ tw = TerminalWriter(file=file) if config.option.color == "yes": tw.hasmarkup = True elif config.option.color == "no": tw.hasmarkup = False if config.option.code_highlight == "yes": tw.code_highlight = True elif config.option.code_highlight == "no": tw.code_highlight = False return tw def _strtobool(val: str) -> bool: """Convert a string representation of truth to True or False. True values are 'y', 'yes', 't', 'true', 'on', and '1'; false values are 'n', 'no', 'f', 'false', 'off', and '0'. Raises ValueError if 'val' is anything else. .. note:: Copied from distutils.util. """ val = val.lower() if val in ("y", "yes", "t", "true", "on", "1"): return True elif val in ("n", "no", "f", "false", "off", "0"): return False else: raise ValueError(f"invalid truth value {val!r}") @lru_cache(maxsize=50) def parse_warning_filter( arg: str, , escape: bool ) -> Tuple["warnings._ActionKind", str, Type[Warning], str, int]: """Parse a warnings filter string. This is copied from warnings._setoption with the following changes: Does not apply the filter. * Escaping is optional. * Raises UsageError so we get nice error messages on failure. """ __tracebackhide__ = True error_template = dedent( f"""\ while parsing the following warning configuration: {arg} This error occurred: {{error}} """ ) parts = arg.split(":") if len(parts) > 5: doc_url = ( "https://docs.python.org/3/library/warnings.html#describing-warning-filters" ) error = dedent( f"""\ Too many fields ({len(parts)}), expected at most 5 separated by colons: action:message:category:module:line For more information please consult: {doc_url} """ ) raise UsageError(error_template.format(error=error)) while len(parts) < 5: parts.append("") action_, message, category_, module, lineno_ = (s.strip() for s in parts) try: action: "warnings._ActionKind" = warnings._getaction(action_) # type: ignore[attr-defined] except warnings._OptionError as e: raise UsageError(error_template.format(error=str(e))) try: category: Type[Warning] = _resolve_warning_category(category_) except Exception: exc_info = ExceptionInfo.from_current() exception_text = exc_info.getrepr(style="native") raise UsageError(error_template.format(error=exception_text)) if message and escape: message = re.escape(message) if module and escape: module = re.escape(module) + r"\Z" if lineno_: try: lineno = int(lineno_) if lineno < 0: raise ValueError("number is negative") except ValueError as e: raise UsageError( error_template.format(error=f"invalid lineno {lineno_!r}: {e}") ) else: lineno = 0 return action, message, category, module, lineno def _resolve_warning_category(category: str) -> Type[Warning]: """ Copied from warnings._getcategory, but changed so it lets exceptions (specially ImportErrors) propagate so we can get access to their tracebacks (#9218). """ __tracebackhide__ = True if not category: return Warning if "." not in category: import builtins as m klass = category else: module, _, klass = category.rpartition(".") m = __import__(module, None, None, [klass]) cat = getattr(m, klass) if not issubclass(cat, Warning): raise UsageError(f"{cat} is not a Warning subclass") return cast(Type[Warning], cat) def apply_warning_filters( config_filters: Iterable[str], cmdline_filters: Iterable[str] ) -> None: """Applies pytest-configured filters to the warnings module""" # Filters should have this precedence: cmdline options, config. # Filters should be applied in the inverse order of precedence. for arg in config_filters: warnings.filterwarnings(parse_warning_filter(arg, escape=False)) for arg in cmdline_filters: warnings.filterwarnings(parse_warning_filter(arg, escape=True))	62.52 KB	2026-01-20 12:58
📁 __pycache__	-	2026-03-21 15:45
📄 argparsing.py import argparse import os import sys import warnings from gettext import gettext from typing import Any from typing import Callable from typing import cast from typing import Dict from typing import List from typing import Mapping from typing import NoReturn from typing import Optional from typing import Sequence from typing import Tuple from typing import TYPE_CHECKING from typing import Union import _pytest._io from _pytest.compat import final from _pytest.config.exceptions import UsageError from _pytest.deprecated import ARGUMENT_PERCENT_DEFAULT from _pytest.deprecated import ARGUMENT_TYPE_STR from _pytest.deprecated import ARGUMENT_TYPE_STR_CHOICE from _pytest.deprecated import check_ispytest if TYPE_CHECKING: from typing_extensions import Literal FILE_OR_DIR = "file_or_dir" @final class Parser: """Parser for command line arguments and ini-file values. :ivar extra_info: Dict of generic param -> value to display in case there's an error processing the command line arguments. """ prog: Optional[str] = None def __init__( self, usage: Optional[str] = None, processopt: Optional[Callable[["Argument"], None]] = None, , _ispytest: bool = False, ) -> None: check_ispytest(_ispytest) self._anonymous = OptionGroup("Custom options", parser=self, _ispytest=True) self._groups: List[OptionGroup] = [] self._processopt = processopt self._usage = usage self._inidict: Dict[str, Tuple[str, Optional[str], Any]] = {} self._ininames: List[str] = [] self.extra_info: Dict[str, Any] = {} def processoption(self, option: "Argument") -> None: if self._processopt: if option.dest: self._processopt(option) def getgroup( self, name: str, description: str = "", after: Optional[str] = None ) -> "OptionGroup": """Get (or create) a named option Group. :param name: Name of the option group. :param description: Long description for --help output. :param after: Name of another group, used for ordering --help output. :returns: The option group. The returned group object has an ``addoption`` method with the same signature as :func:`parser.addoption <pytest.Parser.addoption>` but will be shown in the respective group in the output of ``pytest --help``. """ for group in self._groups: if group.name == name: return group group = OptionGroup(name, description, parser=self, _ispytest=True) i = 0 for i, grp in enumerate(self._groups): if grp.name == after: break self._groups.insert(i + 1, group) return group def addoption(self, opts: str, *attrs: Any) -> None: """Register a command line option. :param opts: Option names, can be short or long options. :param attrs: Same attributes as the argparse library's :py:func:`add_argument() <argparse.ArgumentParser.add_argument>` function accepts. After command line parsing, options are available on the pytest config object via ``config.option.NAME`` where ``NAME`` is usually set by passing a ``dest`` attribute, for example ``addoption("--long", dest="NAME", ...)``. """ self._anonymous.addoption(opts, *attrs) def parse( self, args: Sequence[Union[str, "os.PathLike[str]"]], namespace: Optional[argparse.Namespace] = None, ) -> argparse.Namespace: from _pytest._argcomplete import try_argcomplete self.optparser = self._getparser() try_argcomplete(self.optparser) strargs = [os.fspath(x) for x in args] return self.optparser.parse_args(strargs, namespace=namespace) def _getparser(self) -> "MyOptionParser": from _pytest._argcomplete import filescompleter optparser = MyOptionParser(self, self.extra_info, prog=self.prog) groups = self._groups + [self._anonymous] for group in groups: if group.options: desc = group.description or group.name arggroup = optparser.add_argument_group(desc) for option in group.options: n = option.names() a = option.attrs() arggroup.add_argument(n, *a) file_or_dir_arg = optparser.add_argument(FILE_OR_DIR, nargs="") # bash like autocompletion for dirs (appending '/') # Type ignored because typeshed doesn't know about argcomplete. file_or_dir_arg.completer = filescompleter # type: ignore return optparser def parse_setoption( self, args: Sequence[Union[str, "os.PathLike[str]"]], option: argparse.Namespace, namespace: Optional[argparse.Namespace] = None, ) -> List[str]: parsedoption = self.parse(args, namespace=namespace) for name, value in parsedoption.__dict__.items(): setattr(option, name, value) return cast(List[str], getattr(parsedoption, FILE_OR_DIR)) def parse_known_args( self, args: Sequence[Union[str, "os.PathLike[str]"]], namespace: Optional[argparse.Namespace] = None, ) -> argparse.Namespace: """Parse the known arguments at this point. :returns: An argparse namespace object. """ return self.parse_known_and_unknown_args(args, namespace=namespace)[0] def parse_known_and_unknown_args( self, args: Sequence[Union[str, "os.PathLike[str]"]], namespace: Optional[argparse.Namespace] = None, ) -> Tuple[argparse.Namespace, List[str]]: """Parse the known arguments at this point, and also return the remaining unknown arguments. :returns: A tuple containing an argparse namespace object for the known arguments, and a list of the unknown arguments. """ optparser = self._getparser() strargs = [os.fspath(x) for x in args] return optparser.parse_known_args(strargs, namespace=namespace) def addini( self, name: str, help: str, type: Optional[ "Literal['string', 'paths', 'pathlist', 'args', 'linelist', 'bool']" ] = None, default: Any = None, ) -> None: """Register an ini-file option. :param name: Name of the ini-variable. :param type: Type of the variable. Can be: * ``string``: a string * ``bool``: a boolean * ``args``: a list of strings, separated as in a shell * ``linelist``: a list of strings, separated by line breaks * ``paths``: a list of :class:`pathlib.Path`, separated as in a shell * ``pathlist``: a list of ``py.path``, separated as in a shell .. versionadded:: 7.0 The ``paths`` variable type. Defaults to ``string`` if ``None`` or not passed. :param default: Default value if no ini-file option exists but is queried. The value of ini-variables can be retrieved via a call to :py:func:`config.getini(name) <pytest.Config.getini>`. """ assert type in (None, "string", "paths", "pathlist", "args", "linelist", "bool") self._inidict[name] = (help, type, default) self._ininames.append(name) class ArgumentError(Exception): """Raised if an Argument instance is created with invalid or inconsistent arguments.""" def __init__(self, msg: str, option: Union["Argument", str]) -> None: self.msg = msg self.option_id = str(option) def __str__(self) -> str: if self.option_id: return f"option {self.option_id}: {self.msg}" else: return self.msg class Argument: """Class that mimics the necessary behaviour of optparse.Option. It's currently a least effort implementation and ignoring choices and integer prefixes. https://docs.python.org/3/library/optparse.html#optparse-standard-option-types """ _typ_map = {"int": int, "string": str, "float": float, "complex": complex} def __init__(self, names: str, attrs: Any) -> None: """Store params in private vars for use in add_argument.""" self._attrs = attrs self._short_opts: List[str] = [] self._long_opts: List[str] = [] if "%default" in (attrs.get("help") or ""): warnings.warn(ARGUMENT_PERCENT_DEFAULT, stacklevel=3) try: typ = attrs["type"] except KeyError: pass else: # This might raise a keyerror as well, don't want to catch that. if isinstance(typ, str): if typ == "choice": warnings.warn( ARGUMENT_TYPE_STR_CHOICE.format(typ=typ, names=names), stacklevel=4, ) # argparse expects a type here take it from # the type of the first element attrs["type"] = type(attrs["choices"][0]) else: warnings.warn( ARGUMENT_TYPE_STR.format(typ=typ, names=names), stacklevel=4 ) attrs["type"] = Argument._typ_map[typ] # Used in test_parseopt -> test_parse_defaultgetter. self.type = attrs["type"] else: self.type = typ try: # Attribute existence is tested in Config._processopt. self.default = attrs["default"] except KeyError: pass self._set_opt_strings(names) dest: Optional[str] = attrs.get("dest") if dest: self.dest = dest elif self._long_opts: self.dest = self._long_opts[0][2:].replace("-", "_") else: try: self.dest = self._short_opts[0][1:] except IndexError as e: self.dest = "???" # Needed for the error repr. raise ArgumentError("need a long or short option", self) from e def names(self) -> List[str]: return self._short_opts + self._long_opts def attrs(self) -> Mapping[str, Any]: # Update any attributes set by processopt. attrs = "default dest help".split() attrs.append(self.dest) for attr in attrs: try: self._attrs[attr] = getattr(self, attr) except AttributeError: pass if self._attrs.get("help"): a = self._attrs["help"] a = a.replace("%default", "%(default)s") # a = a.replace('%prog', '%(prog)s') self._attrs["help"] = a return self._attrs def _set_opt_strings(self, opts: Sequence[str]) -> None: """Directly from optparse. Might not be necessary as this is passed to argparse later on. """ for opt in opts: if len(opt) < 2: raise ArgumentError( "invalid option string %r: " "must be at least two characters long" % opt, self, ) elif len(opt) == 2: if not (opt[0] == "-" and opt[1] != "-"): raise ArgumentError( "invalid short option string %r: " "must be of the form -x, (x any non-dash char)" % opt, self, ) self._short_opts.append(opt) else: if not (opt[0:2] == "--" and opt[2] != "-"): raise ArgumentError( "invalid long option string %r: " "must start with --, followed by non-dash" % opt, self, ) self._long_opts.append(opt) def __repr__(self) -> str: args: List[str] = [] if self._short_opts: args += ["_short_opts: " + repr(self._short_opts)] if self._long_opts: args += ["_long_opts: " + repr(self._long_opts)] args += ["dest: " + repr(self.dest)] if hasattr(self, "type"): args += ["type: " + repr(self.type)] if hasattr(self, "default"): args += ["default: " + repr(self.default)] return "Argument({})".format(", ".join(args)) class OptionGroup: """A group of options shown in its own section.""" def __init__( self, name: str, description: str = "", parser: Optional[Parser] = None, , _ispytest: bool = False, ) -> None: check_ispytest(_ispytest) self.name = name self.description = description self.options: List[Argument] = [] self.parser = parser def addoption(self, opts: str, attrs: Any) -> None: """Add an option to this group. If a shortened version of a long option is specified, it will be suppressed in the help. ``addoption('--twowords', '--two-words')`` results in help showing ``--two-words`` only, but ``--twowords`` gets accepted and* the automatic destination is in ``args.twowords``. :param opts: Option names, can be short or long options. :param attrs: Same attributes as the argparse library's :py:func:`add_argument() <argparse.ArgumentParser.add_argument>` function accepts. """ conflict = set(opts).intersection( name for opt in self.options for name in opt.names() ) if conflict: raise ValueError("option names %s already added" % conflict) option = Argument(opts, attrs) self._addoption_instance(option, shortupper=False) def _addoption(self, opts: str, *attrs: Any) -> None: option = Argument(opts, attrs) self._addoption_instance(option, shortupper=True) def _addoption_instance(self, option: "Argument", shortupper: bool = False) -> None: if not shortupper: for opt in option._short_opts: if opt[0] == "-" and opt[1].islower(): raise ValueError("lowercase shortoptions reserved") if self.parser: self.parser.processoption(option) self.options.append(option) class MyOptionParser(argparse.ArgumentParser): def __init__( self, parser: Parser, extra_info: Optional[Dict[str, Any]] = None, prog: Optional[str] = None, ) -> None: self._parser = parser super().__init__( prog=prog, usage=parser._usage, add_help=False, formatter_class=DropShorterLongHelpFormatter, allow_abbrev=False, ) # extra_info is a dict of (param -> value) to display if there's # an usage error to provide more contextual information to the user. self.extra_info = extra_info if extra_info else {} def error(self, message: str) -> NoReturn: """Transform argparse error message into UsageError.""" msg = f"{self.prog}: error: {message}" if hasattr(self._parser, "_config_source_hint"): # Type ignored because the attribute is set dynamically. msg = f"{msg} ({self._parser._config_source_hint})" # type: ignore raise UsageError(self.format_usage() + msg) # Type ignored because typeshed has a very complex type in the superclass. def parse_args( # type: ignore self, args: Optional[Sequence[str]] = None, namespace: Optional[argparse.Namespace] = None, ) -> argparse.Namespace: """Allow splitting of positional arguments.""" parsed, unrecognized = self.parse_known_args(args, namespace) if unrecognized: for arg in unrecognized: if arg and arg[0] == "-": lines = ["unrecognized arguments: %s" % (" ".join(unrecognized))] for k, v in sorted(self.extra_info.items()): lines.append(f" {k}: {v}") self.error("\n".join(lines)) getattr(parsed, FILE_OR_DIR).extend(unrecognized) return parsed if sys.version_info[:2] < (3, 9): # pragma: no cover # Backport of https://github.com/python/cpython/pull/14316 so we can # disable long --argument abbreviations without breaking short flags. def _parse_optional( self, arg_string: str ) -> Optional[Tuple[Optional[argparse.Action], str, Optional[str]]]: if not arg_string: return None if not arg_string[0] in self.prefix_chars: return None if arg_string in self._option_string_actions: action = self._option_string_actions[arg_string] return action, arg_string, None if len(arg_string) == 1: return None if "=" in arg_string: option_string, explicit_arg = arg_string.split("=", 1) if option_string in self._option_string_actions: action = self._option_string_actions[option_string] return action, option_string, explicit_arg if self.allow_abbrev or not arg_string.startswith("--"): option_tuples = self._get_option_tuples(arg_string) if len(option_tuples) > 1: msg = gettext( "ambiguous option: %(option)s could match %(matches)s" ) options = ", ".join(option for _, option, _ in option_tuples) self.error(msg % {"option": arg_string, "matches": options}) elif len(option_tuples) == 1: (option_tuple,) = option_tuples return option_tuple if self._negative_number_matcher.match(arg_string): if not self._has_negative_number_optionals: return None if " " in arg_string: return None return None, arg_string, None class DropShorterLongHelpFormatter(argparse.HelpFormatter): """Shorten help for long options that differ only in extra hyphens. - Collapse long** options that are the same except for extra hyphens. - Shortcut if there are only two options and one of them is a short one. - Cache result on the action object as this is called at least 2 times. """ def __init__(self, args: Any, kwargs: Any) -> None: # Use more accurate terminal width. if "width" not in kwargs: kwargs["width"] = _pytest._io.get_terminal_width() super().__init__(args, kwargs) def _format_action_invocation(self, action: argparse.Action) -> str: orgstr = super()._format_action_invocation(action) if orgstr and orgstr[0] != "-": # only optional arguments return orgstr res: Optional[str] = getattr(action, "_formatted_action_invocation", None) if res: return res options = orgstr.split(", ") if len(options) == 2 and (len(options[0]) == 2 or len(options[1]) == 2): # a shortcut for '-h, --help' or '--abc', '-a' action._formatted_action_invocation = orgstr # type: ignore return orgstr return_list = [] short_long: Dict[str, str] = {} for option in options: if len(option) == 2 or option[2] == " ": continue if not option.startswith("--"): raise ArgumentError( 'long optional argument without "--": [%s]' % (option), option ) xxoption = option[2:] shortened = xxoption.replace("-", "") if shortened not in short_long or len(short_long[shortened]) < len( xxoption ): short_long[shortened] = xxoption # now short_long has been filled out to the longest with dashes # and** we keep the right option ordering from add_argument for option in options: if len(option) == 2 or option[2] == " ": return_list.append(option) if option[2:] == short_long.get(option.replace("-", "")): return_list.append(option.replace(" ", "=", 1)) formatted_action_invocation = ", ".join(return_list) action._formatted_action_invocation = formatted_action_invocation # type: ignore return formatted_action_invocation def _split_lines(self, text, width): """Wrap lines after splitting on original newlines. This allows to have explicit line breaks in the help text. """ import textwrap lines = [] for line in text.splitlines(): lines.extend(textwrap.wrap(line.strip(), width)) return lines	20.73 KB	2026-01-20 12:58
📄 compat.py import functools import warnings from pathlib import Path from typing import Optional from ..compat import LEGACY_PATH from ..compat import legacy_path from ..deprecated import HOOK_LEGACY_PATH_ARG from _pytest.nodes import _check_path # hookname: (Path, LEGACY_PATH) imply_paths_hooks = { "pytest_ignore_collect": ("collection_path", "path"), "pytest_collect_file": ("file_path", "path"), "pytest_pycollect_makemodule": ("module_path", "path"), "pytest_report_header": ("start_path", "startdir"), "pytest_report_collectionfinish": ("start_path", "startdir"), } class PathAwareHookProxy: """ this helper wraps around hook callers until pluggy supports fixingcalls, this one will do it currently doesn't return full hook caller proxies for fixed hooks, this may have to be changed later depending on bugs """ def __init__(self, hook_caller): self.__hook_caller = hook_caller def __dir__(self): return dir(self.__hook_caller) def __getattr__(self, key, _wraps=functools.wraps): hook = getattr(self.__hook_caller, key) if key not in imply_paths_hooks: self.__dict__[key] = hook return hook else: path_var, fspath_var = imply_paths_hooks[key] @_wraps(hook) def fixed_hook(kw): path_value: Optional[Path] = kw.pop(path_var, None) fspath_value: Optional[LEGACY_PATH] = kw.pop(fspath_var, None) if fspath_value is not None: warnings.warn( HOOK_LEGACY_PATH_ARG.format( pylib_path_arg=fspath_var, pathlib_path_arg=path_var ), stacklevel=2, ) if path_value is not None: if fspath_value is not None: _check_path(path_value, fspath_value) else: fspath_value = legacy_path(path_value) else: assert fspath_value is not None path_value = Path(fspath_value) kw[path_var] = path_value kw[fspath_var] = fspath_value return hook(kw) fixed_hook.__name__ = key self.__dict__[key] = fixed_hook return fixed_hook	2.34 KB	2026-01-20 12:58
📄 exceptions.py from _pytest.compat import final @final class UsageError(Exception): """Error in pytest usage or invocation.""" class PrintHelp(Exception): """Raised when pytest should print its help to skip the rest of the argument parsing and validation."""	260 B	2026-01-20 12:58
📄 findpaths.py import os import sys from pathlib import Path from typing import Dict from typing import Iterable from typing import List from typing import Optional from typing import Sequence from typing import Tuple from typing import TYPE_CHECKING from typing import Union import iniconfig from .exceptions import UsageError from _pytest.outcomes import fail from _pytest.pathlib import absolutepath from _pytest.pathlib import commonpath if TYPE_CHECKING: from . import Config def _parse_ini_config(path: Path) -> iniconfig.IniConfig: """Parse the given generic '.ini' file using legacy IniConfig parser, returning the parsed object. Raise UsageError if the file cannot be parsed. """ try: return iniconfig.IniConfig(str(path)) except iniconfig.ParseError as exc: raise UsageError(str(exc)) from exc def load_config_dict_from_file( filepath: Path, ) -> Optional[Dict[str, Union[str, List[str]]]]: """Load pytest configuration from the given file path, if supported. Return None if the file does not contain valid pytest configuration. """ # Configuration from ini files are obtained from the [pytest] section, if present. if filepath.suffix == ".ini": iniconfig = _parse_ini_config(filepath) if "pytest" in iniconfig: return dict(iniconfig["pytest"].items()) else: # "pytest.ini" files are always the source of configuration, even if empty. if filepath.name == "pytest.ini": return {} # '.cfg' files are considered if they contain a "[tool:pytest]" section. elif filepath.suffix == ".cfg": iniconfig = _parse_ini_config(filepath) if "tool:pytest" in iniconfig.sections: return dict(iniconfig["tool:pytest"].items()) elif "pytest" in iniconfig.sections: # If a setup.cfg contains a "[pytest]" section, we raise a failure to indicate users that # plain "[pytest]" sections in setup.cfg files is no longer supported (#3086). fail(CFG_PYTEST_SECTION.format(filename="setup.cfg"), pytrace=False) # '.toml' files are considered if they contain a [tool.pytest.ini_options] table. elif filepath.suffix == ".toml": if sys.version_info >= (3, 11): import tomllib else: import tomli as tomllib toml_text = filepath.read_text(encoding="utf-8") try: config = tomllib.loads(toml_text) except tomllib.TOMLDecodeError as exc: raise UsageError(f"{filepath}: {exc}") from exc result = config.get("tool", {}).get("pytest", {}).get("ini_options", None) if result is not None: # TOML supports richer data types than ini files (strings, arrays, floats, ints, etc), # however we need to convert all scalar values to str for compatibility with the rest # of the configuration system, which expects strings only. def make_scalar(v: object) -> Union[str, List[str]]: return v if isinstance(v, list) else str(v) return {k: make_scalar(v) for k, v in result.items()} return None def locate_config( args: Iterable[Path], ) -> Tuple[Optional[Path], Optional[Path], Dict[str, Union[str, List[str]]]]: """Search in the list of arguments for a valid ini-file for pytest, and return a tuple of (rootdir, inifile, cfg-dict).""" config_names = [ "pytest.ini", ".pytest.ini", "pyproject.toml", "tox.ini", "setup.cfg", ] args = [x for x in args if not str(x).startswith("-")] if not args: args = [Path.cwd()] for arg in args: argpath = absolutepath(arg) for base in (argpath, argpath.parents): for config_name in config_names: p = base / config_name if p.is_file(): ini_config = load_config_dict_from_file(p) if ini_config is not None: return base, p, ini_config return None, None, {} def get_common_ancestor(paths: Iterable[Path]) -> Path: common_ancestor: Optional[Path] = None for path in paths: if not path.exists(): continue if common_ancestor is None: common_ancestor = path else: if common_ancestor in path.parents or path == common_ancestor: continue elif path in common_ancestor.parents: common_ancestor = path else: shared = commonpath(path, common_ancestor) if shared is not None: common_ancestor = shared if common_ancestor is None: common_ancestor = Path.cwd() elif common_ancestor.is_file(): common_ancestor = common_ancestor.parent return common_ancestor def get_dirs_from_args(args: Iterable[str]) -> List[Path]: def is_option(x: str) -> bool: return x.startswith("-") def get_file_part_from_node_id(x: str) -> str: return x.split("::")[0] def get_dir_from_path(path: Path) -> Path: if path.is_dir(): return path return path.parent def safe_exists(path: Path) -> bool: # This can throw on paths that contain characters unrepresentable at the OS level, # or with invalid syntax on Windows (https://bugs.python.org/issue35306) try: return path.exists() except OSError: return False # These look like paths but may not exist possible_paths = ( absolutepath(get_file_part_from_node_id(arg)) for arg in args if not is_option(arg) ) return [get_dir_from_path(path) for path in possible_paths if safe_exists(path)] CFG_PYTEST_SECTION = "[pytest] section in {filename} files is no longer supported, change to [tool:pytest] instead." def determine_setup( inifile: Optional[str], args: Sequence[str], rootdir_cmd_arg: Optional[str] = None, config: Optional["Config"] = None, ) -> Tuple[Path, Optional[Path], Dict[str, Union[str, List[str]]]]: rootdir = None dirs = get_dirs_from_args(args) if inifile: inipath_ = absolutepath(inifile) inipath: Optional[Path] = inipath_ inicfg = load_config_dict_from_file(inipath_) or {} if rootdir_cmd_arg is None: rootdir = inipath_.parent else: ancestor = get_common_ancestor(dirs) rootdir, inipath, inicfg = locate_config([ancestor]) if rootdir is None and rootdir_cmd_arg is None: for possible_rootdir in (ancestor, ancestor.parents): if (possible_rootdir / "setup.py").is_file(): rootdir = possible_rootdir break else: if dirs != [ancestor]: rootdir, inipath, inicfg = locate_config(dirs) if rootdir is None: if config is not None: cwd = config.invocation_params.dir else: cwd = Path.cwd() rootdir = get_common_ancestor([cwd, ancestor]) if is_fs_root(rootdir): rootdir = ancestor if rootdir_cmd_arg: rootdir = absolutepath(os.path.expandvars(rootdir_cmd_arg)) if not rootdir.is_dir(): raise UsageError( "Directory '{}' not found. Check your '--rootdir' option.".format( rootdir ) ) assert rootdir is not None return rootdir, inipath, inicfg or {} def is_fs_root(p: Path) -> bool: r""" Return True if the given path is pointing to the root of the file system ("/" on Unix and "C:\\" on Windows for example). """ return os.path.splitdrive(str(p))[1] == os.sep	7.7 KB	2026-01-20 12:58

Terminal