diff --git a/changelog/7259.deprecation.rst b/changelog/7259.deprecation.rst index c0307740d55..ae857c0d826 100644 --- a/changelog/7259.deprecation.rst +++ b/changelog/7259.deprecation.rst @@ -1,3 +1,12 @@ ``py.path.local`` arguments for hooks have been deprecated. See :ref:`the deprecation note ` for full details. ``py.path.local`` arguments to Node constructors have been deprecated. See :ref:`the deprecation note ` for full details. + +.. note:: + The name of the :class:`~_pytest.nodes.Node` arguments and attributes (the + new attribute being ``path``) is **the opposite** of the situation for hooks + (the old argument being ``path``). + + This is an unfortunate artifact due to historical reasons, which should be + resolved in future versions as we slowly get rid of the :pypi:`py` + dependency (see :issue:`9283` for a longer discussion). diff --git a/changelog/8144.feature.rst b/changelog/8144.feature.rst index effd4bf84d8..fe576eeffa8 100644 --- a/changelog/8144.feature.rst +++ b/changelog/8144.feature.rst @@ -5,3 +5,12 @@ The following hooks now receive an additional ``pathlib.Path`` argument, equival - :func:`pytest_pycollect_makemodule <_pytest.hookspec.pytest_pycollect_makemodule>` - The ``module_path`` parameter (equivalent to existing ``path`` parameter). - :func:`pytest_report_header <_pytest.hookspec.pytest_report_header>` - The ``start_path`` parameter (equivalent to existing ``startdir`` parameter). - :func:`pytest_report_collectionfinish <_pytest.hookspec.pytest_report_collectionfinish>` - The ``start_path`` parameter (equivalent to existing ``startdir`` parameter). + +.. note:: + The name of the :class:`~_pytest.nodes.Node` arguments and attributes (the + new attribute being ``path``) is **the opposite** of the situation for hooks + (the old argument being ``path``). + + This is an unfortunate artifact due to historical reasons, which should be + resolved in future versions as we slowly get rid of the :pypi:`py` + dependency (see :issue:`9283` for a longer discussion). diff --git a/changelog/8251.feature.rst b/changelog/8251.feature.rst index 49aede797a0..fe157cc98b7 100644 --- a/changelog/8251.feature.rst +++ b/changelog/8251.feature.rst @@ -1 +1,11 @@ -Implement ``Node.path`` as a ``pathlib.Path``. +Implement ``Node.path`` as a ``pathlib.Path``. Both the old ``fspath`` and this new attribute gets set no matter whether ``path`` or ``fspath`` (deprecated) is passed to the constructor. It is a replacement for the ``fspath`` attribute (which represents the same path as ``py.path.local``). While ``fspath`` is not deprecated yet +due to the ongoing migration of methods like :meth:`~_pytest.Item.reportinfo`, we expect to deprecate it in a future release. + +.. note:: + The name of the :class:`~_pytest.nodes.Node` arguments and attributes (the + new attribute being ``path``) is **the opposite** of the situation for hooks + (the old argument being ``path``). + + This is an unfortunate artifact due to historical reasons, which should be + resolved in future versions as we slowly get rid of the :pypi:`py` + dependency (see :issue:`9283` for a longer discussion). diff --git a/changelog/9341.doc.rst b/changelog/9341.doc.rst new file mode 100644 index 00000000000..1b97a581247 --- /dev/null +++ b/changelog/9341.doc.rst @@ -0,0 +1 @@ +Various methods commonly used for :ref:`non-python tests` are now correctly documented in the reference docs. They were undocumented previously. diff --git a/doc/en/deprecations.rst b/doc/en/deprecations.rst index 84f7b8fa8bd..ea9ef2aa35d 100644 --- a/doc/en/deprecations.rst +++ b/doc/en/deprecations.rst @@ -53,9 +53,24 @@ Plugins which construct nodes should pass the ``path`` argument, of type :class:`pathlib.Path`, instead of the ``fspath`` argument. Plugins which implement custom items and collectors are encouraged to replace -``py.path.local`` ``fspath`` parameters with ``pathlib.Path`` parameters, and -drop any other usage of the ``py`` library if possible. +``fspath`` parameters (``py.path.local``) with ``path`` parameters +(``pathlib.Path``), and drop any other usage of the ``py`` library if possible. +.. note:: + The name of the :class:`~_pytest.nodes.Node` arguments and attributes (the + new attribute being ``path``) is **the opposite** of the situation for + hooks, :ref:`outlined below ` (the old + argument being ``path``). + + This is an unfortunate artifact due to historical reasons, which should be + resolved in future versions as we slowly get rid of the :pypi:`py` + dependency (see :issue:`9283` for a longer discussion). + +Due to the ongoing migration of methods like :meth:`~_pytest.Item.reportinfo` +which still is expected to return a ``py.path.local`` object, nodes still have +both ``fspath`` (``py.path.local``) and ``path`` (``pathlib.Path``) attributes, +no matter what argument was used in the constructor. We expect to deprecate the +``fspath`` attribute in a future release. .. _legacy-path-hooks-deprecated: @@ -74,6 +89,16 @@ In order to support the transition from ``py.path.local`` to :mod:`pathlib`, the 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. +.. note:: + The name of the :class:`~_pytest.nodes.Node` arguments and attributes, + :ref:`outlined above ` (the new attribute + being ``path``) is **the opposite** of the situation for hooks (the old + argument being ``path``). + + This is an unfortunate artifact due to historical reasons, which should be + resolved in future versions as we slowly get rid of the :pypi:`py` + dependency (see :issue:`9283` for a longer discussion). + Directly constructing internal classes ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/src/_pytest/nodes.py b/src/_pytest/nodes.py index 72747e6e6ff..53dea04e795 100644 --- a/src/_pytest/nodes.py +++ b/src/_pytest/nodes.py @@ -159,6 +159,13 @@ class Node(metaclass=NodeMeta): Collector subclasses have children; Items are leaf nodes. """ + # Implemented in the legacypath plugin. + #: A ``LEGACY_PATH`` copy of the :attr:`path` attribute. Intended for usage + #: for methods not migrated to ``pathlib.Path`` yet, such as + #: :meth:`Item.reportinfo`. Will be deprecated in a future release, prefer + #: using :attr:`path` instead. + fspath: LEGACY_PATH + # Use __slots__ to make attribute access faster. # Note that __dict__ is still available. __slots__ = ( @@ -188,26 +195,26 @@ def __init__( #: The parent collector node. self.parent = parent - #: The pytest config object. if config: + #: The pytest config object. self.config: Config = config else: if not parent: raise TypeError("config or parent must be provided") self.config = parent.config - #: The pytest session this node is part of. if session: + #: The pytest session this node is part of. self.session = session else: if not parent: raise TypeError("session or parent must be provided") self.session = parent.session - #: Filesystem path where this node was collected from (can be None). if path is None and fspath is None: path = getattr(parent, "path", None) - self.path = _imply_path(type(self), path, fspath=fspath) + #: Filesystem path where this node was collected from (can be None). + self.path: Path = _imply_path(type(self), path, fspath=fspath) # The explicit annotation is to avoid publicly exposing NodeKeywords. #: Keywords/markers collected from all scopes. @@ -478,6 +485,8 @@ def repr_failure( ) -> Union[str, TerminalRepr]: """Return a representation of a collection or test failure. + .. seealso:: :ref:`non-python tests` + :param excinfo: Exception information for the failure. """ return self._repr_failure_py(excinfo, style) @@ -686,6 +695,12 @@ def __init__( self.user_properties: List[Tuple[str, object]] = [] def runtest(self) -> None: + """Run the test case for this item. + + Must be implemented by subclasses. + + .. seealso:: :ref:`non-python tests` + """ raise NotImplementedError("runtest must be implemented by Item subclass") def add_report_section(self, when: str, key: str, content: str) -> None: @@ -706,6 +721,16 @@ def add_report_section(self, when: str, key: str, content: str) -> None: self._report_sections.append((when, key, content)) def reportinfo(self) -> Tuple[Union["os.PathLike[str]", str], Optional[int], str]: + """Get location information for this item for test reports. + + Returns a tuple with three elements: + + - The path of the test (default ``self.path``) + - The line number of the test (default ``None``) + - A name of the test to be shown (default ``""``) + + .. seealso:: :ref:`non-python tests` + """ return self.path, None, "" @cached_property diff --git a/src/_pytest/python.py b/src/_pytest/python.py index ff623625bff..b557cd8fa77 100644 --- a/src/_pytest/python.py +++ b/src/_pytest/python.py @@ -1578,26 +1578,26 @@ def write_docstring(tw: TerminalWriter, doc: str, indent: str = " ") -> None: class Function(PyobjMixin, nodes.Item): """An Item responsible for setting up and executing a Python test function. - param name: + :param name: The full function name, including any decorations like those added by parametrization (``my_func[my_param]``). - param parent: + :param parent: The parent Node. - param config: + :param config: The pytest Config object. - param callspec: + :param callspec: If given, this is function has been parametrized and the callspec contains meta information about the parametrization. - param callobj: + :param callobj: If given, the object which will be called when the Function is invoked, otherwise the callobj will be obtained from ``parent`` using ``originalname``. - param keywords: + :param keywords: Keywords bound to the function object for "-k" matching. - param session: + :param session: The pytest Session object. - param fixtureinfo: + :param fixtureinfo: Fixture information already resolved at this fixture node.. - param originalname: + :param originalname: The attribute name to use for accessing the underlying function object. Defaults to ``name``. Set this if name is different from the original name, for example when it contains decorations like those added by parametrization