Merge pull request #11106 from bluetech/docs-ref-collection-objs

reference: improve the node types docs a bit

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 <fixture>` or :ref:`hooks <hook-reference>`.
+These are the collector and item classes (collectively called "nodes") which
+make up the collection tree.
 
+Node
+~~~~
 
-CallInfo
+.. autoclass:: _pytest.nodes.Node()
-~~~~~~~~
-
-.. autoclass:: pytest.CallInfo()
     :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 <fixture>` or :ref:`hooks <hook-reference>`
+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,19 +941,6 @@ Metafunc
 .. autoclass:: pytest.Metafunc()
     :members:
 
-Module
-~~~~~~
-
-.. autoclass:: pytest.Module()
-    :members:
-    :show-inheritance:
-
-Node
-~~~~
-
-.. autoclass:: _pytest.nodes.Node()
-    :members:
-
 Parser
 ~~~~~~
 
@@ -941,13 +962,6 @@ PytestPluginManager
     :inherited-members:
     :show-inheritance:
 
-Session
-~~~~~~~
-
-.. autoclass:: pytest.Session()
-    :members:
-    :show-inheritance:
-
 TestReport
 ~~~~~~~~~~
 

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.

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
+    r"""Base class of :class:`Collector` and :class:`Item`, the components of
-    collection tree.
+    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
+    """Base class of all collectors.
-    iteratively build a tree."""
+
+    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
+        """Collect children (items and collectors) for this collector."""
-        collection node."""
         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.
     """

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()
@@ -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],
@@ -790,7 +793,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):
@@ -1675,7 +1678,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
@@ -1832,10 +1835,8 @@ class Function(PyobjMixin, nodes.Item):
 
 
 class FunctionDefinition(Function):
-    """
+    """This class is a stop gap solution until we evolve to have actual function
-    This class is a step gap solution until we evolve to have actual function definition nodes
+    definition nodes and manage to get rid of ``metafunc``."""
-    and manage to get rid of ``metafunc``.
-    """
 
     def runtest(self) -> None:
         raise RuntimeError("function definitions are not supposed to be run as tests")