From 755ce9bc808a5a6eb63d601a27aab6064e1faeaa Mon Sep 17 00:00:00 2001 From: Ran Benita Date: Sat, 23 Oct 2021 22:29:20 +0300 Subject: [PATCH] hookspec: improve legacy path deprecation docs --- changelog/7259.deprecation.rst | 1 + doc/en/deprecations.rst | 16 +++++++++------ src/_pytest/hookspec.py | 36 ++++++++++++++++++++-------------- 3 files changed, 32 insertions(+), 21 deletions(-) create mode 100644 changelog/7259.deprecation.rst diff --git a/changelog/7259.deprecation.rst b/changelog/7259.deprecation.rst new file mode 100644 index 000000000..e450b3599 --- /dev/null +++ b/changelog/7259.deprecation.rst @@ -0,0 +1 @@ +``py.path.local`` arguments for hooks have been deprecated. See :ref:`the deprecation note ` for full details. diff --git a/doc/en/deprecations.rst b/doc/en/deprecations.rst index 775bc1958..ddddcfb0e 100644 --- a/doc/en/deprecations.rst +++ b/doc/en/deprecations.rst @@ -19,16 +19,20 @@ Below is a complete list of all pytest features which are considered deprecated. :class:`PytestWarning` or subclasses, which can be filtered using :ref:`standard warning filters `. +.. _legacy-path-hooks-deprecated: + ``py.path.local`` arguments for hooks replaced with ``pathlib.Path`` ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -In order to support the transition to :mod:`pathlib`, the following hooks now receive additional arguments: +.. deprecated:: 7.0 -* :func:`pytest_ignore_collect(fspath: pathlib.Path) <_pytest.hookspec.pytest_ignore_collect>` -* :func:`pytest_collect_file(fspath: pathlib.Path) <_pytest.hookspec.pytest_collect_file>` -* :func:`pytest_pycollect_makemodule(fspath: pathlib.Path) <_pytest.hookspec.pytest_pycollect_makemodule>` -* :func:`pytest_report_header(startpath: pathlib.Path) <_pytest.hookspec.pytest_report_header>` -* :func:`pytest_report_collectionfinish(startpath: pathlib.Path) <_pytest.hookspec.pytest_report_collectionfinish>` +In order to support the transition from ``py.path.local`` to :mod:`pathlib`, the following hooks now receive additional arguments: + +* :func:`pytest_ignore_collect(fspath: pathlib.Path) <_pytest.hookspec.pytest_ignore_collect>` instead of ``path`` +* :func:`pytest_collect_file(fspath: pathlib.Path) <_pytest.hookspec.pytest_collect_file>` instead of ``path`` +* :func:`pytest_pycollect_makemodule(fspath: pathlib.Path) <_pytest.hookspec.pytest_pycollect_makemodule>` instead of ``path`` +* :func:`pytest_report_header(startpath: pathlib.Path) <_pytest.hookspec.pytest_report_header>` instead of ``startdir`` +* :func:`pytest_report_collectionfinish(startpath: pathlib.Path) <_pytest.hookspec.pytest_report_collectionfinish>` instead of ``startdir`` The accompanying ``py.path.local`` based paths have been deprecated: plugins which manually invoke those hooks should only pass the new ``pathlib.Path`` arguments, and users should change their hook implementations to use the new ``pathlib.Path`` arguments. diff --git a/src/_pytest/hookspec.py b/src/_pytest/hookspec.py index 29a713b00..e3cfc0718 100644 --- a/src/_pytest/hookspec.py +++ b/src/_pytest/hookspec.py @@ -272,12 +272,13 @@ def pytest_ignore_collect( Stops at first non-None result, see :ref:`firstresult`. :param pathlib.Path fspath: The path to analyze. - :param LEGACY_PATH path: The path to analyze. + :param LEGACY_PATH path: The path to analyze (deprecated). :param pytest.Config config: The pytest config object. - .. versionchanged:: 6.3.0 + .. versionchanged:: 7.0.0 The ``fspath`` parameter was added as a :class:`pathlib.Path` - equivalent of the ``path`` parameter. + equivalent of the ``path`` parameter. The ``path`` parameter + has been deprecated. """ @@ -289,11 +290,12 @@ def pytest_collect_file( The new node needs to have the specified ``parent`` as a parent. :param pathlib.Path fspath: The path to analyze. - :param LEGACY_PATH path: The path to collect. + :param LEGACY_PATH path: The path to collect (deprecated). - .. versionchanged:: 6.3.0 + .. versionchanged:: 7.0.0 The ``fspath`` parameter was added as a :class:`pathlib.Path` - equivalent of the ``path`` parameter. + equivalent of the ``path`` parameter. The ``path`` parameter + has been deprecated. """ @@ -345,11 +347,13 @@ def pytest_pycollect_makemodule( Stops at first non-None result, see :ref:`firstresult`. :param pathlib.Path fspath: The path of the module to collect. - :param legacy_path path: The path of the module to collect. + :param LEGACY_PATH path: The path of the module to collect (deprecated). - .. versionchanged:: 6.3.0 + .. versionchanged:: 7.0.0 The ``fspath`` parameter was added as a :class:`pathlib.Path` equivalent of the ``path`` parameter. + + The ``path`` parameter has been deprecated in favor of ``fspath``. """ @@ -674,7 +678,7 @@ def pytest_report_header( :param pytest.Config config: The pytest config object. :param Path startpath: The starting dir. - :param LEGACY_PATH startdir: The starting dir. + :param LEGACY_PATH startdir: The starting dir (deprecated). .. note:: @@ -689,9 +693,10 @@ def pytest_report_header( files situated at the tests root directory due to how pytest :ref:`discovers plugins during startup `. - .. versionchanged:: 6.3.0 + .. versionchanged:: 7.0.0 The ``startpath`` parameter was added as a :class:`pathlib.Path` - equivalent of the ``startdir`` parameter. + equivalent of the ``startdir`` parameter. The ``startdir`` parameter + has been deprecated. """ @@ -709,8 +714,8 @@ def pytest_report_collectionfinish( .. versionadded:: 3.2 :param pytest.Config config: The pytest config object. - :param Path startpath: The starting path. - :param LEGACY_PATH startdir: The starting dir. + :param Path startpath: The starting dir. + :param LEGACY_PATH startdir: The starting dir (deprecated). :param items: List of pytest items that are going to be executed; this list should not be modified. .. note:: @@ -720,9 +725,10 @@ def pytest_report_collectionfinish( If you want to have your line(s) displayed first, use :ref:`trylast=True `. - .. versionchanged:: 6.3.0 + .. versionchanged:: 7.0.0 The ``startpath`` parameter was added as a :class:`pathlib.Path` - equivalent of the ``startdir`` parameter. + equivalent of the ``startdir`` parameter. The ``startdir`` parameter + has been deprecated. """