diff --git a/changelog/7469.feature.rst b/changelog/7469.feature.rst index 0feef2d7d..9922631fe 100644 --- a/changelog/7469.feature.rst +++ b/changelog/7469.feature.rst @@ -2,11 +2,13 @@ The types of objects used in pytest's API are now exported so they may be used i The newly-exported types are: +- ``pytest.Config`` for :class:`Config `. - ``pytest.Mark`` for :class:`marks `. - ``pytest.MarkDecorator`` for :class:`mark decorators `. - ``pytest.MarkGenerator`` for the :class:`pytest.mark ` singleton. - ``pytest.Metafunc`` for the :class:`metafunc ` argument to the :func:`pytest_generate_tests ` hook. - ``pytest.CallInfo`` for the :class:`CallInfo ` type passed to various hooks. +- ``pytest.PytestPluginManager`` for :class:`PytestPluginManager `. - ``pytest.ExceptionInfo`` for the :class:`ExceptionInfo ` type returned from :func:`pytest.raises` and passed to various hooks. - ``pytest.Parser`` for the :class:`Parser ` type passed to the :func:`pytest_addoption ` hook. - ``pytest.OptionGroup`` for the :class:`OptionGroup ` type returned from the :func:`parser.addgroup ` method. diff --git a/doc/en/builtin.rst b/doc/en/builtin.rst index f0a6eedb1..ea2f27a4c 100644 --- a/doc/en/builtin.rst +++ b/doc/en/builtin.rst @@ -61,7 +61,7 @@ For information about fixtures, see :ref:`fixtures`. To see a complete list of a namespace of doctests. pytestconfig [session scope] - Session-scoped fixture that returns the :class:`_pytest.config.Config` object. + Session-scoped fixture that returns the :class:`pytest.Config` object. Example:: diff --git a/doc/en/how-to/writing_plugins.rst b/doc/en/how-to/writing_plugins.rst index 8ec935cc2..3b58a8333 100644 --- a/doc/en/how-to/writing_plugins.rst +++ b/doc/en/how-to/writing_plugins.rst @@ -337,7 +337,7 @@ testing directory: Alternatively you can invoke pytest with the ``-p pytester`` command line option. -This will allow you to use the :py:class:`pytester <_pytest.pytester.Pytester>` +This will allow you to use the :py:class:`pytester ` fixture for testing your plugin code. Let's demonstrate what you can do with the plugin with an example. Imagine we diff --git a/doc/en/reference/customize.rst b/doc/en/reference/customize.rst index 24d2ec931..d6fb5c6b2 100644 --- a/doc/en/reference/customize.rst +++ b/doc/en/reference/customize.rst @@ -179,12 +179,12 @@ Files will only be matched for configuration if: The files are considered in the order above. Options from multiple ``configfiles`` candidates are never merged - the first match wins. -The internal :class:`Config <_pytest.config.Config>` object (accessible via hooks or through the :fixture:`pytestconfig` fixture) +The :class:`Config ` object (accessible via hooks or through the :fixture:`pytestconfig` fixture) will subsequently carry these attributes: -- :attr:`config.rootpath <_pytest.config.Config.rootpath>`: the determined root directory, guaranteed to exist. +- :attr:`config.rootpath `: the determined root directory, guaranteed to exist. -- :attr:`config.inipath <_pytest.config.Config.inipath>`: the determined ``configfile``, may be ``None`` +- :attr:`config.inipath `: the determined ``configfile``, may be ``None`` (it is named ``inipath`` for historical reasons). .. versionadded:: 6.1 diff --git a/doc/en/reference/reference.rst b/doc/en/reference/reference.rst index 95bf6cf62..1a35d8911 100644 --- a/doc/en/reference/reference.rst +++ b/doc/en/reference/reference.rst @@ -787,7 +787,7 @@ CollectReport Config ~~~~~~ -.. autoclass:: _pytest.config.Config() +.. autoclass:: pytest.Config() :members: ExceptionInfo @@ -901,7 +901,7 @@ OptionGroup PytestPluginManager ~~~~~~~~~~~~~~~~~~~ -.. autoclass:: _pytest.config.PytestPluginManager() +.. autoclass:: pytest.PytestPluginManager() :members: :undoc-members: :inherited-members: diff --git a/src/_pytest/config/__init__.py b/src/_pytest/config/__init__.py index 878507313..f32991137 100644 --- a/src/_pytest/config/__init__.py +++ b/src/_pytest/config/__init__.py @@ -290,7 +290,7 @@ def get_config( def get_plugin_manager() -> "PytestPluginManager": """Obtain a new instance of the - :py:class:`_pytest.config.PytestPluginManager`, with default plugins + :py:class:`pytest.PytestPluginManager`, with default plugins already loaded. This function can be used by integration with other tools, like hooking @@ -632,6 +632,7 @@ class PytestPluginManager(PluginManager): def consider_preparse( self, args: Sequence[str], *, exclude_only: bool = False ) -> None: + """:meta private:""" i = 0 n = len(args) while i < n: @@ -653,6 +654,7 @@ class PytestPluginManager(PluginManager): 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: @@ -678,12 +680,15 @@ class PytestPluginManager(PluginManager): 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( @@ -841,6 +846,7 @@ 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` @@ -1227,8 +1233,8 @@ class Config: @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.""" + # 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() diff --git a/src/_pytest/config/argparsing.py b/src/_pytest/config/argparsing.py index 51acb4033..e6f4c2dea 100644 --- a/src/_pytest/config/argparsing.py +++ b/src/_pytest/config/argparsing.py @@ -193,7 +193,7 @@ class Parser: 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.Config.getini>`. + :py:func:`config.getini(name) `. """ assert type in (None, "string", "paths", "pathlist", "args", "linelist", "bool") self._inidict[name] = (help, type, default) diff --git a/src/_pytest/fixtures.py b/src/_pytest/fixtures.py index 1076debb8..ebc44b2b2 100644 --- a/src/_pytest/fixtures.py +++ b/src/_pytest/fixtures.py @@ -1379,7 +1379,8 @@ def yield_fixture( @fixture(scope="session") def pytestconfig(request: FixtureRequest) -> Config: - """Session-scoped fixture that returns the :class:`_pytest.config.Config` object. + """Session-scoped fixture that returns the session's :class:`pytest.Config` + object. Example:: diff --git a/src/_pytest/hookspec.py b/src/_pytest/hookspec.py index 75110a9a3..e8fcc3d73 100644 --- a/src/_pytest/hookspec.py +++ b/src/_pytest/hookspec.py @@ -56,7 +56,7 @@ def pytest_addhooks(pluginmanager: "PytestPluginManager") -> None: """Called at plugin registration time to allow adding new hooks via a call to ``pluginmanager.add_hookspecs(module_or_class, prefix)``. - :param _pytest.config.PytestPluginManager pluginmanager: pytest plugin manager. + :param pytest.PytestPluginManager pluginmanager: The pytest plugin manager. .. note:: This hook is incompatible with ``hookwrapper=True``. @@ -70,7 +70,7 @@ def pytest_plugin_registered( """A new pytest plugin got registered. :param plugin: The plugin module or instance. - :param _pytest.config.PytestPluginManager manager: pytest plugin manager. + :param pytest.PytestPluginManager manager: pytest plugin manager. .. note:: This hook is incompatible with ``hookwrapper=True``. @@ -94,18 +94,18 @@ def pytest_addoption(parser: "Parser", pluginmanager: "PytestPluginManager") -> To add ini-file values call :py:func:`parser.addini(...) `. - :param _pytest.config.PytestPluginManager pluginmanager: - pytest plugin manager, which can be used to install :py:func:`hookspec`'s + :param pytest.PytestPluginManager pluginmanager: + The pytest plugin manager, which can be used to install :py:func:`hookspec`'s or :py:func:`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.Config>` object, respectively: + :py:class:`config ` object, respectively: - - :py:func:`config.getoption(name) <_pytest.config.Config.getoption>` to + - :py:func:`config.getoption(name) ` to retrieve the value of a command line option. - - :py:func:`config.getini(name) <_pytest.config.Config.getini>` to retrieve + - :py:func:`config.getini(name) ` to retrieve a value read from an ini-style file. The config object is passed around on many internal objects via the ``.config`` @@ -129,7 +129,7 @@ def pytest_configure(config: "Config") -> None: .. note:: This hook is incompatible with ``hookwrapper=True``. - :param _pytest.config.Config config: The pytest config object. + :param pytest.Config config: The pytest config object. """ @@ -152,7 +152,7 @@ def pytest_cmdline_parse( ``plugins`` arg when using `pytest.main`_ to perform an in-process test run. - :param _pytest.config.PytestPluginManager pluginmanager: Pytest plugin manager. + :param pytest.PytestPluginManager pluginmanager: The pytest plugin manager. :param List[str] args: List of arguments passed on the command line. """ @@ -166,7 +166,7 @@ def pytest_cmdline_preparse(config: "Config", args: List[str]) -> None: .. note:: This hook will not be called for ``conftest.py`` files, only for setuptools plugins. - :param _pytest.config.Config config: The pytest config object. + :param pytest.Config config: The pytest config object. :param List[str] args: Arguments passed on the command line. """ @@ -178,7 +178,7 @@ def pytest_cmdline_main(config: "Config") -> Optional[Union["ExitCode", int]]: Stops at first non-None result, see :ref:`firstresult`. - :param _pytest.config.Config config: The pytest config object. + :param pytest.Config config: The pytest config object. """ @@ -191,7 +191,7 @@ def pytest_load_initial_conftests( .. note:: This hook will not be called for ``conftest.py`` files, only for setuptools plugins. - :param _pytest.config.Config early_config: The pytest config object. + :param pytest.Config early_config: The pytest config object. :param List[str] args: Arguments passed on the command line. :param pytest.Parser parser: To add command line options. """ @@ -246,7 +246,7 @@ def pytest_collection_modifyitems( the items in-place. :param pytest.Session session: The pytest session object. - :param _pytest.config.Config config: The pytest config object. + :param pytest.Config config: The pytest config object. :param List[pytest.Item] items: List of item objects. """ @@ -271,7 +271,7 @@ def pytest_ignore_collect( :param pathlib.Path fspath: The path to analyze. :param LEGACY_PATH path: The path to analyze. - :param _pytest.config.Config config: The pytest config object. + :param pytest.Config config: The pytest config object. .. versionchanged:: 6.3.0 The ``fspath`` parameter was added as a :class:`pathlib.Path` @@ -385,7 +385,7 @@ def pytest_make_parametrize_id( Stops at first non-None result, see :ref:`firstresult`. - :param _pytest.config.Config config: The pytest config object. + :param pytest.Config config: The pytest config object. :param val: The parametrized value. :param str argname: The automatic parameter name produced by pytest. """ @@ -609,7 +609,7 @@ def pytest_sessionfinish( def pytest_unconfigure(config: "Config") -> None: """Called before test process is exited. - :param _pytest.config.Config config: The pytest config object. + :param pytest.Config config: The pytest config object. """ @@ -628,7 +628,7 @@ def pytest_assertrepr_compare( *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 _pytest.config.Config config: The pytest config object. + :param pytest.Config config: The pytest config object. """ @@ -677,7 +677,7 @@ def pytest_report_header( ) -> Union[str, List[str]]: """Return a string or list of strings to be displayed as header info for terminal reporting. - :param _pytest.config.Config config: The pytest config object. + :param pytest.Config config: The pytest config object. :param Path startpath: The starting dir. :param LEGACY_PATH startdir: The starting dir. @@ -713,7 +713,7 @@ def pytest_report_collectionfinish( .. versionadded:: 3.2 - :param _pytest.config.Config config: The pytest config object. + :param pytest.Config config: The pytest config object. :param Path startpath: The starting path. :param LEGACY_PATH startdir: The starting dir. :param items: List of pytest items that are going to be executed; this list should not be modified. @@ -752,7 +752,7 @@ def pytest_report_teststatus( for example ``"rerun", "R", ("RERUN", {"yellow": True})``. :param report: The report object whose status is to be returned. - :param _pytest.config.Config config: The pytest config object. + :param pytest.Config config: The pytest config object. Stops at first non-None result, see :ref:`firstresult`. """ @@ -767,7 +767,7 @@ def pytest_terminal_summary( :param _pytest.terminal.TerminalReporter terminalreporter: The internal terminal reporter object. :param int exitstatus: The exit status that will be reported back to the OS. - :param _pytest.config.Config config: The pytest config object. + :param pytest.Config config: The pytest config object. .. versionadded:: 4.2 The ``config`` parameter. @@ -857,7 +857,7 @@ def pytest_markeval_namespace(config: "Config") -> Dict[str, Any]: .. versionadded:: 6.2 - :param _pytest.config.Config config: The pytest config object. + :param pytest.Config config: The pytest config object. :returns: A dictionary of additional globals to add. """ @@ -909,7 +909,7 @@ def pytest_enter_pdb(config: "Config", pdb: "pdb.Pdb") -> None: Can be used by plugins to take special action just before the python debugger enters interactive mode. - :param _pytest.config.Config config: The pytest config object. + :param pytest.Config config: The pytest config object. :param pdb.Pdb pdb: The Pdb instance. """ @@ -920,6 +920,6 @@ def pytest_leave_pdb(config: "Config", pdb: "pdb.Pdb") -> None: Can be used by plugins to take special action just after the python debugger leaves interactive mode. - :param _pytest.config.Config config: The pytest config object. + :param pytest.Config config: The pytest config object. :param pdb.Pdb pdb: The Pdb instance. """ diff --git a/src/_pytest/pytester.py b/src/_pytest/pytester.py index 037f69e0b..af73b6392 100644 --- a/src/_pytest/pytester.py +++ b/src/_pytest/pytester.py @@ -954,7 +954,7 @@ class Pytester: ) -> Optional[Union[Collector, Item]]: """Return the collection node of a file. - :param _pytest.config.Config config: + :param pytest.Config config: A pytest config. See :py:meth:`parseconfig` and :py:meth:`parseconfigure` for creating it. :param os.PathLike[str] arg: @@ -1186,7 +1186,7 @@ class Pytester: This invokes the pytest bootstrapping code in _pytest.config to create a new :py:class:`_pytest.core.PluginManager` and call the pytest_cmdline_parse hook to create a new - :py:class:`_pytest.config.Config` instance. + :py:class:`pytest.Config` instance. If :py:attr:`plugins` has been populated they should be plugin modules to be registered with the PluginManager. @@ -1206,7 +1206,7 @@ class Pytester: def parseconfigure(self, *args: Union[str, "os.PathLike[str]"]) -> Config: """Return a new pytest configured Config instance. - Returns a new :py:class:`_pytest.config.Config` instance like + Returns a new :py:class:`pytest.Config` instance like :py:meth:`parseconfig`, but also calls the pytest_configure hook. """ config = self.parseconfig(*args) diff --git a/src/_pytest/python.py b/src/_pytest/python.py index 436f463ee..f7dfd696b 100644 --- a/src/_pytest/python.py +++ b/src/_pytest/python.py @@ -970,7 +970,7 @@ class Metafunc: #: Access to the underlying :class:`_pytest.python.FunctionDefinition`. self.definition = definition - #: Access to the :class:`_pytest.config.Config` object for the test session. + #: Access to the :class:`pytest.Config` object for the test session. self.config = config #: The module object where the test function is defined in. diff --git a/src/pytest/__init__.py b/src/pytest/__init__.py index 7a81d2341..d8169b808 100644 --- a/src/pytest/__init__.py +++ b/src/pytest/__init__.py @@ -7,11 +7,13 @@ from _pytest.assertion import register_assert_rewrite from _pytest.cacheprovider import Cache from _pytest.capture import CaptureFixture from _pytest.config import cmdline +from _pytest.config import Config from _pytest.config import console_main from _pytest.config import ExitCode from _pytest.config import hookimpl from _pytest.config import hookspec from _pytest.config import main +from _pytest.config import PytestPluginManager from _pytest.config import UsageError from _pytest.config.argparsing import OptionGroup from _pytest.config.argparsing import Parser @@ -79,6 +81,7 @@ __all__ = [ "cmdline", "collect", "Collector", + "Config", "console_main", "deprecated_call", "exit", @@ -116,6 +119,7 @@ __all__ = [ "PytestDeprecationWarning", "PytestExperimentalApiWarning", "Pytester", + "PytestPluginManager", "PytestUnhandledCoroutineWarning", "PytestUnhandledThreadExceptionWarning", "PytestUnknownMarkWarning",