From 264e7ac32733572fad3892ba0e830dba7cc87cf0 Mon Sep 17 00:00:00 2001 From: Ran Benita Date: Wed, 14 Jun 2023 09:22:34 +0300 Subject: [PATCH 1/2] reference: add doc for `Package` We document the other py collectors, we should document `Package` as well. --- doc/en/reference/reference.rst | 6 ++++++ src/_pytest/python.py | 3 +++ 2 files changed, 9 insertions(+) diff --git a/doc/en/reference/reference.rst b/doc/en/reference/reference.rst index 7107218b3..f591eb21e 100644 --- a/doc/en/reference/reference.rst +++ b/doc/en/reference/reference.rst @@ -926,6 +926,12 @@ Parser .. autoclass:: pytest.Parser() :members: +Package +~~~~~~~ + +.. autoclass:: pytest.Package() + :members: + OptionGroup ~~~~~~~~~~~ diff --git a/src/_pytest/python.py b/src/_pytest/python.py index ad847c8af..2036819cf 100644 --- a/src/_pytest/python.py +++ b/src/_pytest/python.py @@ -659,6 +659,9 @@ class Module(nodes.File, PyCollector): class Package(Module): + """Collector for files and directories in a Python packages -- directories + with an `__init__.py` file.""" + def __init__( self, fspath: Optional[LEGACY_PATH], From bd88a6412d7518c94ebdb4bbfcff39accd771d4f Mon Sep 17 00:00:00 2001 From: Ran Benita Date: Wed, 14 Jun 2023 09:19:56 +0300 Subject: [PATCH 2/2] reference: separate node types to their own section I think it's helpful to separate the node classes from the other objects, as they have their own unique usage. I've chosen not to alphabetize the order, but to use a logical order instead. Also slightly improve the docstrings. --- doc/en/reference/reference.rst | 150 +++++++++++++++++---------------- src/_pytest/main.py | 5 ++ src/_pytest/nodes.py | 21 +++-- src/_pytest/python.py | 12 ++- 4 files changed, 102 insertions(+), 86 deletions(-) diff --git a/doc/en/reference/reference.rst b/doc/en/reference/reference.rst index f591eb21e..6154bbf25 100644 --- a/doc/en/reference/reference.rst +++ b/doc/en/reference/reference.rst @@ -783,18 +783,66 @@ reporting or interaction with exceptions: .. autofunction:: pytest_leave_pdb -Objects -------- +Collection tree objects +----------------------- -Full reference to objects accessible from :ref:`fixtures ` or :ref:`hooks `. +These are the collector and item classes (collectively called "nodes") which +make up the collection tree. +Node +~~~~ -CallInfo -~~~~~~~~ - -.. autoclass:: pytest.CallInfo() +.. autoclass:: _pytest.nodes.Node() :members: +Collector +~~~~~~~~~ + +.. autoclass:: pytest.Collector() + :members: + :show-inheritance: + +Item +~~~~ + +.. autoclass:: pytest.Item() + :members: + :show-inheritance: + +File +~~~~ + +.. autoclass:: pytest.File() + :members: + :show-inheritance: + +FSCollector +~~~~~~~~~~~ + +.. autoclass:: _pytest.nodes.FSCollector() + :members: + :show-inheritance: + +Session +~~~~~~~ + +.. autoclass:: pytest.Session() + :members: + :show-inheritance: + +Package +~~~~~~~ + +.. autoclass:: pytest.Package() + :members: + :show-inheritance: + +Module +~~~~~~ + +.. autoclass:: pytest.Module() + :members: + :show-inheritance: Class ~~~~~ @@ -803,13 +851,34 @@ Class :members: :show-inheritance: -Collector -~~~~~~~~~ +Function +~~~~~~~~ -.. autoclass:: pytest.Collector() +.. autoclass:: pytest.Function() :members: :show-inheritance: +FunctionDefinition +~~~~~~~~~~~~~~~~~~ + +.. autoclass:: _pytest.python.FunctionDefinition() + :members: + :show-inheritance: + + +Objects +------- + +Objects accessible from :ref:`fixtures ` or :ref:`hooks ` +or importable from ``pytest``. + + +CallInfo +~~~~~~~~ + +.. autoclass:: pytest.CallInfo() + :members: + CollectReport ~~~~~~~~~~~~~ @@ -837,13 +906,6 @@ ExitCode .. autoclass:: pytest.ExitCode :members: -File -~~~~ - -.. autoclass:: pytest.File() - :members: - :show-inheritance: - FixtureDef ~~~~~~~~~~ @@ -852,34 +914,6 @@ FixtureDef :members: :show-inheritance: -FSCollector -~~~~~~~~~~~ - -.. autoclass:: _pytest.nodes.FSCollector() - :members: - :show-inheritance: - -Function -~~~~~~~~ - -.. autoclass:: pytest.Function() - :members: - :show-inheritance: - -FunctionDefinition -~~~~~~~~~~~~~~~~~~ - -.. autoclass:: _pytest.python.FunctionDefinition() - :members: - :show-inheritance: - -Item -~~~~ - -.. autoclass:: pytest.Item() - :members: - :show-inheritance: - MarkDecorator ~~~~~~~~~~~~~ @@ -907,31 +941,12 @@ Metafunc .. autoclass:: pytest.Metafunc() :members: -Module -~~~~~~ - -.. autoclass:: pytest.Module() - :members: - :show-inheritance: - -Node -~~~~ - -.. autoclass:: _pytest.nodes.Node() - :members: - Parser ~~~~~~ .. autoclass:: pytest.Parser() :members: -Package -~~~~~~~ - -.. autoclass:: pytest.Package() - :members: - OptionGroup ~~~~~~~~~~~ @@ -947,13 +962,6 @@ PytestPluginManager :inherited-members: :show-inheritance: -Session -~~~~~~~ - -.. autoclass:: pytest.Session() - :members: - :show-inheritance: - TestReport ~~~~~~~~~~ diff --git a/src/_pytest/main.py b/src/_pytest/main.py index 155d4300e..803b95a20 100644 --- a/src/_pytest/main.py +++ b/src/_pytest/main.py @@ -462,6 +462,11 @@ class _bestrelpath_cache(Dict[Path, str]): @final class Session(nodes.FSCollector): + """The root of the collection tree. + + ``Session`` collects the initial paths given as arguments to pytest. + """ + Interrupted = Interrupted Failed = Failed # Set on the session by runner.pytest_sessionstart. diff --git a/src/_pytest/nodes.py b/src/_pytest/nodes.py index dbd6b0a42..667a02b77 100644 --- a/src/_pytest/nodes.py +++ b/src/_pytest/nodes.py @@ -157,10 +157,11 @@ class NodeMeta(type): class Node(metaclass=NodeMeta): - """Base class for Collector and Item, the components of the test - collection tree. + r"""Base class of :class:`Collector` and :class:`Item`, the components of + the test collection tree. - Collector subclasses have children; Items are leaf nodes. + ``Collector``\'s are the internal nodes of the tree, and ``Item``\'s are the + leaf nodes. """ # Implemented in the legacypath plugin. @@ -525,15 +526,17 @@ def get_fslocation_from_item(node: "Node") -> Tuple[Union[str, Path], Optional[i class Collector(Node): - """Collector instances create children through collect() and thus - iteratively build a tree.""" + """Base class of all collectors. + + Collector create children through `collect()` and thus iteratively build + the collection tree. + """ class CollectError(Exception): """An error during collection, contains a custom message.""" def collect(self) -> Iterable[Union["Item", "Collector"]]: - """Return a list of children (items and collectors) for this - collection node.""" + """Collect children (items and collectors) for this collector.""" raise NotImplementedError("abstract") # TODO: This omits the style= parameter which breaks Liskov Substitution. @@ -577,6 +580,8 @@ def _check_initialpaths_for_relpath(session: "Session", path: Path) -> Optional[ class FSCollector(Collector): + """Base class for filesystem collectors.""" + def __init__( self, fspath: Optional[LEGACY_PATH] = None, @@ -660,7 +665,7 @@ class File(FSCollector): class Item(Node): - """A basic test invocation item. + """Base class of all test invocation items. Note that for a single function there might be multiple test invocation items. """ diff --git a/src/_pytest/python.py b/src/_pytest/python.py index 2036819cf..b24dc90d8 100644 --- a/src/_pytest/python.py +++ b/src/_pytest/python.py @@ -522,7 +522,7 @@ class PyCollector(PyobjMixin, nodes.Collector): class Module(nodes.File, PyCollector): - """Collector for test classes and functions.""" + """Collector for test classes and functions in a Python module.""" def _getobj(self): return self._importtestmodule() @@ -791,7 +791,7 @@ def _get_first_non_fixture_func(obj: object, names: Iterable[str]) -> Optional[o class Class(PyCollector): - """Collector for test methods.""" + """Collector for test methods (and nested classes) in a Python class.""" @classmethod def from_parent(cls, parent, *, name, obj=None, **kw): @@ -1676,7 +1676,7 @@ 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. + """Item responsible for setting up and executing a Python test function. :param name: The full function name, including any decorations like those @@ -1833,10 +1833,8 @@ class Function(PyobjMixin, nodes.Item): class FunctionDefinition(Function): - """ - This class is a step gap solution until we evolve to have actual function definition nodes - and manage to get rid of ``metafunc``. - """ + """This class is a stop gap solution until we evolve to have actual function + definition nodes and manage to get rid of ``metafunc``.""" def runtest(self) -> None: raise RuntimeError("function definitions are not supposed to be run as tests")