Skip to content

path

path #

Path[T] — a typed position in a schema; the only non-storable composite.

A Path is an address, not data: it points at a value of type T somewhere in a target schema. The procedure layer threads Path[T] through access nodes (field, key, index) and a CacheProcedure stores a value at one. It is non-storable: a Path is never a Struct field, a Map key, or another Path's target. It may be an Array element or Map value — Array[Path[V]] / Map[K, Path[V]] are fan-out collections of positions, themselves non-storable.

Path.schema() carries the target (so two Path types compare structurally), but a bare Path — or one parameterized by a still-unresolved TypeVar while a generic node class is being defined — serializes compactly as {"type": "path"}; the procedure graph relies on the embedded schema, not the per-node target.

Path #

Bases: CGType

A position in a schema pointing at a value of type T (Path[T]).

The type parameter types the fluent loaders (load()/load_or() return Procedure[T]); the runtime target still travels via __class_getitem__'s generated subclasses.

Source code in capturegraph-lib/capturegraph/types/special/path.py 
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
class Path[T: CGType](CGType):
    """A position in a schema pointing at a value of type ``T`` (``Path[T]``).

    The type parameter types the fluent loaders (``load()``/``load_or()``
    return ``Procedure[T]``); the runtime target still travels via
    ``__class_getitem__``'s generated subclasses.
    """

    __slots__ = ()
    storable: ClassVar[bool] = False
    _target: ClassVar[type[CGType] | None] = None

    def __class_getitem__(cls, target: object) -> type[Path]:
        """Build ``Path[target]``, carrying ``target`` for structural comparison."""
        if _is_cgtype(target):
            check_element(target, "Path target")
        key = (cls, target)
        if key not in _SUBSCRIPTS:
            _SUBSCRIPTS[key] = type(
                f"Path[{getattr(target, '__name__', target)}]",
                (cls,),
                {"__slots__": (), "_target": target},
            )
        return _SUBSCRIPTS[key]

    @classmethod
    def schema(cls) -> dict[str, JSONValue]:
        """This path's wire form: ``{"type": "path"}``, plus ``target`` if resolved."""
        if not _is_cgtype(cls._target):
            return {"type": "path"}  # bare Path, or an unresolved TypeVar target
        return {"type": "path", "target": cls._target.schema()}

    @classmethod
    def _children(cls) -> list[tuple[str, type[CGType]]]:
        """The target type, which shares this address (label ``""``)."""
        return [("", cls._target)] if _is_cgtype(cls._target) else []

__class_getitem__(target) #

Build Path[target], carrying target for structural comparison.

Source code in capturegraph-lib/capturegraph/types/special/path.py 
49
50
51
52
53
54
55
56
57
58
59
60
def __class_getitem__(cls, target: object) -> type[Path]:
    """Build ``Path[target]``, carrying ``target`` for structural comparison."""
    if _is_cgtype(target):
        check_element(target, "Path target")
    key = (cls, target)
    if key not in _SUBSCRIPTS:
        _SUBSCRIPTS[key] = type(
            f"Path[{getattr(target, '__name__', target)}]",
            (cls,),
            {"__slots__": (), "_target": target},
        )
    return _SUBSCRIPTS[key]

schema() classmethod #

This path's wire form: {"type": "path"}, plus target if resolved.

Source code in capturegraph-lib/capturegraph/types/special/path.py 
62
63
64
65
66
67
@classmethod
def schema(cls) -> dict[str, JSONValue]:
    """This path's wire form: ``{"type": "path"}``, plus ``target`` if resolved."""
    if not _is_cgtype(cls._target):
        return {"type": "path"}  # bare Path, or an unresolved TypeVar target
    return {"type": "path", "target": cls._target.schema()}