Files
2026-11-04 21:01:26 +01:00

114 lines
4.3 KiB
Python

"""Structured representation of a pytest "nodeid".
A nodeid is represented as a ``::``-separated string, identifying a node in the collection
tree, e.g. ``path/to/test_file.py::TestClass::test_method[param]``.
The :class:`NodeId` class represents that information in a proper dataclass with the relevant
parts readily available, avoiding reparsing that information when needed and also making for
a better type than `str`.
The traditional ``::``-joined string form remains available via ``str(node_id)``.
"""
from __future__ import annotations
import dataclasses
@dataclasses.dataclass(frozen=True, slots=True, kw_only=True)
class NodeId:
"""Structured identifier of a node in the collection tree.
:param path:
``/``-normalized, rootpath-relative filesystem path. Empty string
for the session root.
:param names:
Ordered ``::``-segment names after the path.
:param params:
Raw contents inside the outermost ``[...]`` bracket, kept as one
opaque string -- traditional string-node ids are often recovered from the outside (for example
files), so we cannot recover the actual params and values used to build the parametrization.
"""
path: str
names: tuple[str, ...] = ()
params: str | None = None
_str_cache: str | None = dataclasses.field(
default=None, init=False, repr=False, compare=False
)
@classmethod
def parse(cls, nodeid: str) -> NodeId:
"""Parse a nodeid string into its path, names, and raw params."""
path, sep, tail = nodeid.partition("::")
if not sep:
# No "::" -- everything is the path. Never interpret a bracket
# here: file paths can legitimately contain "[" (e.g. test[1].py).
self = cls(path=path)
else:
# Peel the params bracket off the tail FIRST.
name_part, bracket, param_part = tail.partition("[")
names = tuple(name_part.split("::"))
params = param_part.removesuffix("]") if bracket else None
self = cls(path=path, names=names, params=params)
# We already have the original string in hand -- cache it directly
# as _str_cache instead of letting __str__ reconstruct it later.
object.__setattr__(self, "_str_cache", nodeid)
return self
def __str__(self) -> str:
if self._str_cache is not None:
return self._str_cache
s = "::".join((self.path, *self.names))
if self.params is not None:
s += f"[{self.params}]"
object.__setattr__(self, "_str_cache", s)
return s
@property
def rest(self) -> str | None:
"""Everything after the first ``"::"`` as a single string, or
``None`` when there is no ``"::"`` (i.e. ``names`` is empty).
"""
if not self.names:
return None
s = "::".join(self.names)
if self.params is not None:
s += f"[{self.params}]"
return s
def child(self, name: str) -> NodeId:
"""Return a new :class:`NodeId` for a child collector node.
:raises ValueError: if called on a node that already has params
(i.e., a leaf item) -- only collector ids (``params=None``) can
have children.
"""
if self.params is not None:
raise ValueError(
f"cannot call .child() on a parameterised id {self!r}; "
"only collector ids (params=None) can have children"
)
return NodeId(path=self.path, names=(*self.names, name))
def with_params(self, params: str | None) -> NodeId:
"""Return a new :class:`NodeId` with ``params`` set.
:raises ValueError: if ``self`` is already parameterised (i.e. an
item id with ``params is not None``).
"""
if self.params is not None:
raise ValueError(
f"cannot call .with_params() on a parameterised id {self!r}; "
"only collector ids (params=None) can be parameterised"
)
return NodeId(path=self.path, names=self.names, params=params)
def coerce_node_id(nodeid: str | NodeId) -> NodeId:
"""Return ``nodeid`` unchanged if already a :class:`NodeId`; otherwise
parse it via :meth:`NodeId.parse`."""
if isinstance(nodeid, NodeId):
return nodeid
return NodeId.parse(nodeid)