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 
34
35
36
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
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")
        return type(
            f"Path[{getattr(target, '__name__', target)}]",
            (cls,),
            {"__slots__": (), "_target": target},
        )

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

__class_getitem__(target) #

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

Source code in capturegraph-lib/capturegraph/types/special/path.py 
46
47
48
49
50
51
52
53
54
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")
    return type(
        f"Path[{getattr(target, '__name__', target)}]",
        (cls,),
        {"__slots__": (), "_target": target},
    )

schema() classmethod #

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

Source code in capturegraph-lib/capturegraph/types/special/path.py 
56
57
58
59
60
61
62
@classmethod
def schema(cls) -> dict[str, JSONValue]:
    """This path's wire form: ``{"type": "path"}``, plus ``target`` if resolved."""
    target = cls._target
    if not (isinstance(target, type) and issubclass(target, CGType)):
        return {"type": "path"}  # bare Path, or an unresolved TypeVar target
    return {"type": "path", "target": target.schema()}