"""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)