From 99c4d9dd3afc465192fd3923ac6dc8f8b683d2b1 Mon Sep 17 00:00:00 2001 From: Warren Markham Date: Sun, 10 Sep 2023 23:07:15 +1000 Subject: [PATCH] docs: add class docstring to NodeMeta As I learn how pytest works, I have found it very helpful when there are class docstrings. I can stay high-level instead of getting overwhelmed in the complexity. For that reason, I am adding a summary and project link to the `NodeMeta` docstring. Although I cannot claim to understand all the conversations that have been had about the `NodeMeta` class, I am hoping the summary and project link are helpful to contributors regardless of experience level. --- src/_pytest/nodes.py | 14 ++++++++++++++ 1 file changed, 14 insertions(+) diff --git a/src/_pytest/nodes.py b/src/_pytest/nodes.py index cb8907fe8..058344a2c 100644 --- a/src/_pytest/nodes.py +++ b/src/_pytest/nodes.py @@ -127,6 +127,20 @@ _NodeType = TypeVar("_NodeType", bound="Node") class NodeMeta(type): + """Metaclass used by :class:`Node` to enforce that direct construction raises + :class:`Failed` + + This behaviour supports the indirection introduced with :meth:`Node.from_parent`, + the named constructor to be used instead of direct construction. The design + decision to enforce indirection with :class:`NodeMeta` was made as a + temporary aid for refactoring the collection tree, which was diagnosed to + have :class:`Node` objects whose creational patterns were overly entangled. + Once the refactoring is complete, this metaclass can be removed. + + See https://github.com/pytest-dev/pytest/projects/3 for an overview of the + progress on detangling the :class:`Node` classes. + """ + def __call__(self, *k, **kw): msg = ( "Direct construction of {name} has been deprecated, please use {name}.from_parent.\n"