Skip to content

access

access #

Value-level access nodes that navigate a materialized value.

Navigate a materialized Struct/Array/Map value the way the destination/access path family navigates a Path[...].

Each one is the value twin of a path node, resolving its return type through the same shared resolvers (...type_checking.containers): where PathField walks a Path[Struct] to Path[FieldType], StructField reads a struct value and yields the field's value. They compose, so the structured value a node returns can be drilled into — CapturePanorama().frames[1].angle is StructField → ArrayIndex → StructField — and the result cached at a path (root.angle &= …).

Like the path family, every node takes the position it descends as source.

operation path-level (destination/access) value-level (here)
struct field PathField StructField
array index PathIndex ArrayIndex
map key PathKey MapKey

A node can return a Map value — CaptureImagesByLabel collects one image sequence per label — so map access has a value twin too: MapKey reads a Map value and yields one entry's value, the way PathKey walks a Path[Map] to Path[V]. A key the map lacks at runtime yields no value rather than aborting the run. .keys() / .values() enumeration stays path-level (PathKeys/PathValues).

ArrayIndex #

Bases: Procedure[CGType]

Select one element of an array value (negative indexes from the end).

Returns the array's element type E. The value-level twin of PathIndex. The element type carries through: indexing an Array[Path[V]] yields a navigable Path[V] (so values()[-1].primary keeps navigating), while indexing an Array[Time] yields a Time value (keys()[0]).

Attributes:

Name Type Description
source Procedure[Array]

A procedure producing the Array to index.
index Setting[int]

The integer position (-1 for the last entry).
Source code in capturegraph-lib/capturegraph/procedures/nodes/process/access.py 
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
@make_procedure
class ArrayIndex(Procedure[CGType]):
    """Select one element of an array value (negative indexes from the end).

    Returns the array's element type ``E``. The value-level twin of
    [PathIndex][capturegraph.procedures.nodes.destination.access.PathIndex]. The
    element type carries through: indexing an ``Array[Path[V]]`` yields a
    navigable ``Path[V]`` (so ``values()[-1].primary`` keeps navigating), while
    indexing an ``Array[Time]`` yields a ``Time`` value (``keys()[0]``).

    Attributes:
        source: A procedure producing the ``Array`` to index.
        index: The integer position (``-1`` for the last entry).
    """

    source: Procedure[Array]
    index: Setting[int]

    def _resolve_type(self) -> type[CGType]:
        """The source array's element type."""
        return array_element(self.source.return_type, "ArrayIndex")

MapKey #

Bases: Procedure[CGType]

Select one entry of a map value by key. Returns the map's element type V.

The value-level twin of PathKey: PathKey navigates a Path[Map] to Path[V], while MapKey reads a Map value and yields the entry's value. It is what indexing a map-returning node builds — cg.CaptureImagesByLabel(labels=["A", "B"])["A"].

A key the map lacks at runtime yields no value (the access produces nothing, so caching it stores nothing) and the executing client reports the unknown key, rather than aborting the run.

Attributes:

Name Type Description
source Procedure[Map]

A procedure producing the Map value to read.
key Procedure[CGType]

A procedure producing the key value (a keyable scalar matching the map's key type).
Source code in capturegraph-lib/capturegraph/procedures/nodes/process/access.py 
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
@make_procedure
class MapKey(Procedure[CGType]):
    """Select one entry of a map value by key. Returns the map's element type ``V``.

    The value-level twin of
    [PathKey][capturegraph.procedures.nodes.destination.access.PathKey]: ``PathKey``
    navigates a ``Path[Map]`` to ``Path[V]``, while ``MapKey`` reads a ``Map``
    *value* and yields the entry's *value*. It is what indexing a map-returning
    node builds — ``cg.CaptureImagesByLabel(labels=["A", "B"])["A"]``.

    A key the map lacks at runtime yields no value (the access produces nothing,
    so caching it stores nothing) and the executing client reports the unknown
    key, rather than aborting the run.

    Attributes:
        source: A procedure producing the ``Map`` value to read.
        key: A procedure producing the key value (a keyable scalar matching the
            map's key type).
    """

    source: Procedure[Map]
    key: Procedure[CGType]

    def _resolve_type(self) -> type[CGType]:
        """The source map's entry type for this key."""
        return map_entry(self.source.return_type, self.key.return_type, "MapKey")

StructField #

Bases: Procedure[CGType]

Read a named field of a struct value. Returns the field's type.

The value-level twin of PathField: PathField navigates a Path[Struct] to Path[FieldType], while StructField reads a struct value and yields the field's value.

Attributes:

Name Type Description
source Procedure[Struct]

A procedure producing the Struct value to read.
field Setting[str]

The field name to read.
Source code in capturegraph-lib/capturegraph/procedures/nodes/process/access.py 
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
@make_procedure
class StructField(Procedure[CGType]):
    """Read a named field of a struct value. Returns the field's type.

    The value-level twin of
    [PathField][capturegraph.procedures.nodes.destination.access.PathField]:
    ``PathField`` navigates a ``Path[Struct]`` to ``Path[FieldType]``, while
    ``StructField`` reads a struct *value* and yields the field's *value*.

    Attributes:
        source: A procedure producing the ``Struct`` value to read.
        field: The field name to read.
    """

    source: Procedure[Struct]
    field: Setting[str]

    def _resolve_type(self) -> type[CGType]:
        """The source struct's field type."""
        return struct_field(self.source.return_type, self.field, "StructField")