init.py

Overview

This file serves as the core of the pytest configuration and plugin management system. It implements:

The main entry points for running pytest programmatically and via the command line.
The PytestPluginManager, an extension of pluggy.PluginManager customized for pytest's plugin lifecycle, including loading of builtin plugins, external plugins, and local conftest.py plugins.
The Config class, which encapsulates pytest's configuration state, command-line options, ini-file values, and plugin management.
Utilities for argument validation, warning filter parsing, assertion support checking, and terminal output configuration.

This file integrates tightly with pytest’s plugin and hook infrastructure, enabling flexible plugin discovery, registration, and hook dispatching. It also manages configuration parsing from command line, ini files, and environment variables, and coordinates the loading and execution of plugins and conftest files.

Detailed Documentation

Constants and Types

_PluggyPlugin
Alias type for plugin objects, which can be any namespace.
hookimpl and hookspec
Pluggy decorators used to mark hook implementations and hook specifications respectively.

Enum: `ExitCode`

class ExitCode(enum.IntEnum)

Defines standard exit codes for pytest runs:

ExitCode	Value	Meaning
`OK`	0	All tests passed.
`TESTS_FAILED`	1	Some tests failed.
`INTERRUPTED`	2	pytest was interrupted.
`INTERNAL_ERROR`	3	Internal error occurred.
`USAGE_ERROR`	4	Usage error or misconfiguration.
`NO_TESTS_COLLECTED`	5	No tests were collected.

*Introduced in pytest 5.0.*

Exception: `ConftestImportFailure`

class ConftestImportFailure(Exception)

Raised when importing a `conftest.py` file fails.

Attributes:
- path (pathlib.Path): Path to the conftest file that failed to import.
- cause (Exception): The original exception causing the failure.
Usage Example:

try:
    # import conftest logic
except Exception as e:
    raise ConftestImportFailure(conftest_path, cause=e)

String Representation:
Displays the original exception and the file path, e.g., "ImportError: ... (from /path/to/conftest.py)".

Functions

`main(args=None, plugins=None) -> int | ExitCode`

Perform an in-process pytest test run.

Parameters:
- args (list[str] | os.PathLike[str] | None): Command line arguments. Defaults to sys.argv[1:] if None.
- plugins (Sequence[str | _PluggyPlugin] | None): Plugins to auto-register.
Returns:
Exit code as int or ExitCode.
Behavior:
- Sets PYTEST_VERSION environment variable.
- Prepares configuration and plugin manager.
- Handles ConftestImportFailure with user-friendly error output.
- Invokes hook pytest_cmdline_main to run tests.
- Ensures proper unconfiguration and error handling.
Example:

exit_code = main(["-v", "tests/"])
sys.exit(exit_code)

`console_main() -> int`

Entry point for pytest CLI execution.

Wraps main() and handles broken pipe errors gracefully.
Not intended for programmatic use—use main() instead.

`filename_arg(path: str, optname: str) -> str`

Argparse validator ensuring the given path is a filename (not a directory).

Raises UsageError if path is a directory.
Used internally for command-line argument validation.

`directory_arg(path: str, optname: str) -> str`

Argparse validator ensuring the given path is a directory.

Raises UsageError if path is not a directory.

`get_config(args=None, plugins=None) -> Config`

Creates and returns a new `Config` object with default plugins loaded.

Processes -p no: plugin blocking arguments.
Loads default and essential plugins.

`get_plugin_manager() -> PytestPluginManager`

Returns a new `PytestPluginManager` instance with default plugins loaded.

Useful for external integrations such as IDEs.

Class: `PytestPluginManager`

class PytestPluginManager(PluginManager)

**Description:** An extension of `pluggy.PluginManager` tailored for pytest’s plugin system, with support for:

Managing builtin, external, and local conftest.py plugins.
Plugin blocking/unblocking via command-line options.
Loading plugins from environment variables and entry points.
Tracking skipped plugins and issuing warnings.
Interaction with pytest’s assertion rewriting system.

**Key Attributes:**

_conftest_plugins: Set of loaded conftest.py modules.
_dirpath2confmods: Directory-path to list of conftest modules cache.
_confcutdir: Directory cutoff for conftest discovery.
_noconftest: Flag to disable conftest loading.
skipped_plugins: List of skipped plugins with reasons.
rewrite_hook: Reference to assertion rewriting import hook.
_configured: Whether pytest configuration is complete.

**Key Methods:**

register(plugin, name=None): Registers a plugin and emits pytest_plugin_registered.
import_plugin(modname, consider_entry_points=False): Imports and registers a plugin by name.
consider_preparse(args, exclude_only=False): Parse -p options early for blocking/enabling plugins.
consider_pluginarg(arg): Enable or disable plugins explicitly.
consider_conftest(conftestmodule, registration_name): Register a local conftest plugin.
_try_load_conftest(anchor, importmode, rootpath, ...): Load conftest files for a directory.
_loadconftestmodules(path, importmode, rootpath, ...): Load and cache conftest modules.
_importconftest(conftestpath, importmode, rootpath, ...): Import a single conftest.py file.
_check_non_top_pytest_plugins(mod, conftestpath): Warn if pytest_plugins defined in non-top-level conftest.

**Usage Example:**

pm = PytestPluginManager()
pm.consider_preparse(["-p", "no:cacheprovider"], exclude_only=True)
pm.import_plugin("myplugin")

Class: `Config`

class Config

**Description:** Central configuration object for pytest. It provides access to:

Command line options (via option attribute).
Ini-file configuration values (getini()).
Plugin manager instance (pluginmanager).
Hooks (hook) for invoking pytest hook calls.
Management of configuration lifecycle and cleanup.

**Initialization:**

config = Config(pluginmanager)

**Key Attributes:**

option (argparse.Namespace): Parsed command line options.
pluginmanager (PytestPluginManager): Plugin manager instance.
invocation_params: Immutable object holding invocation arguments, plugins, and invocation directory.
stash: A storage for plugins to keep arbitrary data.
hook: Hook proxy for calling pytest hooks.
rootpath and inipath: Paths to root directory and config file.
_parser: CLI option and ini file parser.

**Important Methods:**

parse(args, addopts=True): Parse command line arguments and ini files.
getoption(name, default=notset, skip=False): Get option value by name.
getini(name): Get ini-file configuration value.
add_cleanup(func): Register cleanup callbacks.
get_terminal_writer(): Get configured terminal writer for output.
issue_config_time_warning(warning, stacklevel): Emit warnings during config phase.
_preparse(args, addopts): Internal preprocessing of args and ini files.
_decide_args(...): Determine test paths/nodeids from various sources.
_configure_python_path(): Add pythonpath ini values to sys.path.
_consider_importhook(args): Setup assertion rewriting import hook if needed.

**Nested Types:**

InvocationParams (frozen dataclass): Holds args, plugins, and dir used during pytest invocation.
ArgsSource (enum): Source of test arguments (ARGS, INVOCATION_DIR, TESTPATHS).

**Usage Example:**

config = get_config(["-v", "tests"])
verbosity = config.get_verbosity()
option_val = config.getoption("maxfail", default=5)

Utility Functions

_iter_rewritable_modules(package_files: Iterable[str]) -> Iterator[str]
Iterates over package/module names from distribution files for assertion rewriting.
_strtobool(val: str) -> bool
Converts string representations of boolean values to Python bool.
parse_warning_filter(arg: str, *, escape: bool) -> tuple
Parses warning filter strings into components suitable for warnings.filterwarnings.
_resolve_warning_category(category: str) -> type[Warning]
Resolves a warning category string to a Warning subclass.
apply_warning_filters(config_filters: Iterable[str], cmdline_filters: Iterable[str])
Applies configured warning filters from ini files and command-line to Python's warnings module.
create_terminal_writer(config: Config, file: TextIO | None = None) -> TerminalWriter
Creates a TerminalWriter instance configured according to terminal options.

Important Implementation Details

Plugin Loading and Blocking:
Plugins can be disabled via -p no:<plugin> command line arguments, managed by PytestPluginManager.consider_preparse() and consider_pluginarg().
Conftest Plugin Loading:
conftest.py files are dynamically imported as plugins for directory scopes, with caching of imports per directory to optimize repeated lookups.
Assertion Rewriting:
The import hook for assertion rewriting is installed and plugins/packages are marked for rewriting early in the configuration phase.
Configuration Parsing:
The Config class uses an internal parser to parse command-line arguments and ini files, applying overrides and validating options.
Warning Filters:
Warning filters are parsed and applied with precedence: command-line filters override ini file filters.
Exit Codes:
Pytest exit codes are standardized via the ExitCode enum, improving clarity in programmatic usage.
Error and Usage Handling:
Custom exceptions like UsageError and ConftestImportFailure provide controlled error handling with user-friendly messages.

Interactions with Other Parts of the System

Plugin System:
This file implements the core plugin manager and config class that interact with pluggy (a third-party hook management library). It loads builtin plugins (e.g., "mark", "runner") and third-party plugins discovered via setuptools entry points or environment variables.
Conftest.py Files:
Local conftest.py files are loaded as plugins to provide directory-scoped configuration and hooks.
Assertion Rewriting:
Integrates with _pytest.assertion to install import hooks enabling enhanced assertion introspection.
Command Line Parsing:
Works with _pytest.config.argparsing to define and parse command line options and ini configuration.
Terminal Output:
Uses _pytest._io.TerminalWriter to manage colored and highlighted output respecting user options.
Exception Handling:
Uses _pytest._code.ExceptionInfo and filtering of tracebacks to provide clean error reporting.
Warnings:
Integrates with _pytest.warning_types for handling and reporting warnings during configuration.
Other Plugins:
Registers and manages many builtin plugins such as "python", "terminal", "cacheprovider", and third-party plugins.

Visual Diagram: Class Structure of Key Entities

classDiagram
    class PytestPluginManager {
        -_conftest_plugins: set
        -_dirpath2confmods: dict
        -_confcutdir: pathlib.Path | None
        -_noconftest: bool
        -skipped_plugins: list
        -rewrite_hook: RewriteHook
        -_configured: bool
        +register(plugin, name=None): str | None
        +import_plugin(modname, consider_entry_points=False): None
        +consider_preparse(args, exclude_only=False): None
        +consider_pluginarg(arg): None
        +consider_conftest(conftestmodule, registration_name): None
        +_try_load_conftest(anchor, importmode, rootpath, ...): None
        +_loadconftestmodules(path, importmode, rootpath, ...): None
        +_importconftest(conftestpath, importmode, rootpath, ...): ModuleType
        +pytest_configure(config): None
    }

    class Config {
        +option: argparse.Namespace
        +pluginmanager: PytestPluginManager
        +invocation_params: InvocationParams
        +stash: Stash
        +hook: pluggy.HookRelay
        +rootpath: pathlib.Path
        +inipath: pathlib.Path | None
        +parse(args, addopts=True): None
        +getoption(name, default=..., skip=False): Any
        +getini(name): Any
        +add_cleanup(func): None
        +issue_config_time_warning(warning, stacklevel): None
        +get_terminal_writer(): TerminalWriter
    }

    Config "1" *-- "1" PytestPluginManager : contains

Summary

The [__init__.py](/projects/286/67254) file of the `pytest.config` package provides the essential foundation for pytest’s configuration and plugin system. It implements:

The main programmatic and CLI entry points.
The PytestPluginManager class managing plugin lifecycle, conftest loading, and plugin discovery.
The Config class managing configuration state, command-line and ini parsing, hooks, and plugin integration.
Utilities for command-line argument validation, warning filter parsing, and terminal writer creation.

Together, these components enable pytest's flexible, extensible architecture that supports rich plugin ecosystems and customizable test runs, while maintaining a clean and consistent user experience.

End of Documentation for init.py

init.py

Overview

Detailed Documentation

Constants and Types

Enum: ExitCode

Exception: ConftestImportFailure

Functions

main(args=None, plugins=None) -> int | ExitCode

console_main() -> int

filename_arg(path: str, optname: str) -> str

directory_arg(path: str, optname: str) -> str

get_config(args=None, plugins=None) -> Config

get_plugin_manager() -> PytestPluginManager

Class: PytestPluginManager

Class: Config