Skip to content

array

array #

Array — a homogeneous sequence that broadcasts attribute access over its elements.

A loaded array is read-only; .clone() gives an in-memory copy that can change.

Array #

Bases: CGType

A homogeneous sequence.

Array[T] is storable when T is (so Array[Path[V]] is a non-storable view); a bare Array is the schemaless broadcast view a projection lands in. The type parameter types the element surface (indexing, iteration, append), and map/pmap carry the function's return type. A broadcast or projection names a field no type system can resolve, so it carries Any elements — the caller's next call types them.

Source code in capturegraph-lib/capturegraph/types/containers/array.py
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
class Array[T](CGType):
    """A homogeneous sequence.

    ``Array[T]`` is storable when ``T`` is (so ``Array[Path[V]]`` is a
    non-storable view); a bare ``Array`` is the schemaless broadcast view a
    projection lands in. The type parameter types the element surface
    (indexing, iteration, ``append``), and ``map``/``pmap`` carry the
    function's return type. A broadcast or projection names a field no type
    system can resolve, so it carries ``Any`` elements — the caller's next
    call types them.
    """

    __slots__ = ("_items", "_cg_base", "_cg_hash", "_cg_pin")
    _items: list[T]
    _element: ClassVar[type[CGType] | None] = None

    def __init__(self, items: Iterable[T] = ()) -> None:
        """Wrap ``items`` (any iterable, copied into a plain list) as an Array."""
        object.__setattr__(self, "_items", list(items))

    def __class_getitem__(cls, element: object) -> type[Array] | GenericAlias:
        """Build ``Array[element]`` — a storable subclass, or a typing-only alias.

        A CGType element makes ``Array[T]`` whose storability *follows* the
        element: ``Array[Image]`` is storable, while ``Array[Path[V]]`` is a
        non-storable fan-out collection (an array of positions, never written to
        disk). A non-CGType element is a typing-only alias, so loaded values can
        be annotated without a schema.
        """
        if not (isinstance(element, type) and issubclass(element, CGType)):
            return GenericAlias(cls, element)
        check_cgtype(element, "Array element")
        key = (cls, element)
        if key not in _SUBSCRIPTS:
            _SUBSCRIPTS[key] = type(
                f"Array[{element.__name__}]",
                (cls,),
                {"__slots__": (), "_element": element, "storable": element.storable},
            )
        return _SUBSCRIPTS[key]

    # --- storage (a schema'd Array[T] only) ---------------------------------

    @classmethod
    def schema(cls) -> dict[str, JSONValue]:
        """This array's wire form: its element's schema, tagged ``"array"``."""
        if cls._element is None:
            raise TypeError("a schemaless Array has no wire form")
        return {"type": "array", "element": cls._element.schema()}

    @classmethod
    def _children(cls) -> list[tuple[str, type[CGType]]]:
        """The element type, labelled ``[*]``; a schemaless array declares none."""
        return [("[*]", cls._element)] if cls._element is not None else []

    @classmethod
    def _descend(cls, component: str) -> type[CGType]:
        """The element type, reached by any canonical index name.

        Raises:
            SchemaPathError: If this array is schemaless, or ``component`` is not
                a canonical index name.
        """
        if cls._element is None:
            raise SchemaPathError(f"{cls.__name__} is a schemaless array")
        try:
            parse_index_name(component)
        except ValueError as error:
            raise SchemaPathError(str(error)) from error
        return cls._element

    @classmethod
    def index_name(cls, index: int) -> str:
        """The entry name of the element at ``index``: what a page links to it by.

        ```python
        assert cg.Array.index_name(17) == "00017"
        ```
        """
        return index_name(index)

    @classmethod
    def load(cls, base: Path) -> Self:
        """The array stored at ``base``, elements in index order; an unwritten tree is empty.

        Raises:
            TypeError: If this array is schemaless.
        """
        if cls._element is None:
            raise TypeError(f"{cls.__name__} cannot load without an element type")
        stems = entry_stems(base) if base.is_dir() else []
        array = cls(cast("list[T]", [load_entry(cls._element, base / stem) for stem in stems]))
        freeze_at(array, base)
        return array

    @classmethod
    def store(cls, base: Path, value: object) -> None:
        """Write ``value`` under ``base``, one zero-padded index entry per element.

        A ``Missing`` element keeps its index: it is written as the marker
        ``<index>.cg-missing`` holding its reason, and loads back as ``Missing``.

        Raises:
            TypeError: If this array is schemaless or ``value`` is not iterable.
        """
        if cls._element is None:
            raise TypeError(f"{cls.__name__} cannot store without an element type")
        if not isinstance(value, Iterable):
            raise TypeError(f"{cls.__name__}.store needs an iterable, got {value!r}")
        base.mkdir(parents=True, exist_ok=True)
        for index, item in enumerate(value):
            store_entry(cls._element, base / index_name(index), item)

    # --- sequence (any Array instance) --------------------------------------

    def __iter__(self) -> Iterator[T]:
        """Iterate the wrapped elements, in order."""
        return iter(self._items)

    def __len__(self) -> int:
        """The number of elements."""
        return len(self._items)

    def __bool__(self) -> bool:
        """Falsy when empty, like a plain list."""
        return bool(self._items)

    def append(self, item: T) -> None:
        """Add ``item`` to the end of the array, in place.

        Raises:
            TypeError: If this array was loaded from disk.
        """
        refuse_change(self)
        self._items.append(item)

    def clone(self) -> Self:
        """An in-memory copy that can change, its containers copied and its scalars shared."""
        return share_hold(self, type(self)(cast("T", cloned(item)) for item in self._items))

    def __eq__(self, other: object) -> bool:
        """Equal to another ``Array`` or a plain ``list`` with the same elements."""
        if isinstance(other, Array):
            return self._items == other._items
        if isinstance(other, list):
            return self._items == other
        return NotImplemented

    __hash__ = None  # pyright: ignore[reportAssignmentType] # a mutable container is unhashable

    def __repr__(self) -> str:
        """The wrapped elements' own ``repr``."""
        return repr(self._items)

    def __add__(self, other: Iterable[T]) -> Array[T]:
        """Concatenate with another sequence into a new ``Array``."""
        return Array([*self._items, *other])

    def __radd__(self, other: Iterable[T]) -> Array[T]:
        """Concatenate a sequence with this array into a new ``Array``."""
        return Array([*other, *self._items])

    # --- broadcast attribute access -----------------------------------------

    def __getattr__(self, name: str) -> Array[Any]:
        """Broadcast attribute access over the elements.

        A name no element has raises (a typo), a name some lack chains as
        ``Missing``; this array's own machinery is not an element field
        (``broadcastable``).
        """
        if not broadcastable(self, name):
            raise AttributeError(name)
        return Array(broadcast(self._items, f"attribute {name!r}", _accessor(name)))

    def __setattr__(self, name: str, value: object) -> None:
        """Broadcast attribute assignment over the elements.

        An empty array adopts the length of ``value``, creating a plain ``dict``
        per entry; a non-empty array assigns element-wise (a same-length
        sequence), broadcasts a single-element sequence or a scalar, and skips
        ``Missing`` elements. Each element is written by attribute when it
        supports one, else by key (a ``dict`` row).

        Raises:
            TypeError: If this array, or an element written, was loaded from disk.
        """
        if not broadcastable(self, name):
            object.__setattr__(self, name, value)
            return

        refuse_change(self)
        if isinstance(value, (list, tuple, Array)):
            values = list(value)
            if not self._items:
                _backing(self).extend({name: item} for item in values)
                return
            if len(values) == len(self._items):
                pairs = zip(self._items, values, strict=True)
            elif len(values) == 1:
                pairs = ((item, values[0]) for item in self._items)
            else:
                raise ValueError(
                    f"Cannot assign sequence of length {len(values)} to Array of "
                    f"length {len(self._items)}; lengths must match, or use a "
                    f"single-element sequence / scalar to broadcast."
                )
            for item, item_value in pairs:
                if not is_missing(item):
                    _set(item, name, item_value)
            return
        for item in self._items:
            if not is_missing(item):
                _set(item, name, value)

    # --- indexing / projection ----------------------------------------------

    @overload
    def __getitem__(self, key: SupportsIndex) -> T: ...
    @overload
    def __getitem__(self, key: slice) -> Array[T]: ...
    @overload
    def __getitem__(self, key: str | tuple[str, ...]) -> Array[Any]: ...
    def __getitem__(self, key: SupportsIndex | slice | str | tuple[str, ...]) -> object:
        """Index by position (``int``/``slice``) or project by ``str``/``tuple``.

        ``numbers.Integral`` is accepted alongside plain ``int`` so a NumPy
        index (``np.argmax`` etc.) works like one — this Array converts to and
        from NumPy for analysis. An out-of-range index chains as ``Missing``
        (typed as the element).
        """
        if isinstance(key, numbers.Integral):
            try:
                return wrapped(self._items[int(key)])
            except IndexError as error:
                return _Missing(error)
        if isinstance(key, slice):
            return Array(wrapped(item) for item in self._items[key])
        if isinstance(key, str):
            return Array(self._project(key))
        if isinstance(key, tuple):
            columns = {name: self._project(name) for name in key}
            return Array(
                {name: columns[name][index] for name in key} for index in range(len(self._items))
            )
        raise TypeError(f"Array indices must be int, slice, str, or tuple[str, ...]; got {key!r}")

    def _project(self, name: str) -> list[Any]:
        """``access(item, name)`` over the elements, guarded so a typo raises."""
        return broadcast(self._items, f"key {name!r}", _accessor(name))

    # --- function application -----------------------------------------------

    def map[R](
        self,
        function: Callable[[T], R],
        label: str | None = None,
        on_error: OnError = "raise",
    ) -> Array[R]:
        """Apply ``function`` to each element, in order.

        The walk is a logged count of the elements, shown as ``label`` or
        ``function``'s name. An element that raises stops it: the exception
        propagates at once. ``on_error="missing"`` runs every element instead,
        keeping a failure as a reasoned ``Missing`` and raising only when every
        element fails for a non-data reason.

        ```python
        keypoints = images.map(cgr.sfm.keypoints)
        sparse = images.map(cgr.sfm.keypoints, on_error="missing")
        ```
        """
        if not callable(function):
            raise TypeError(f"Array.map needs a callable, got {function!r}")
        return Array(mapped(self._items, function, label, on_error))

    def pmap[R](
        self,
        function: Callable[[T], R],
        label: str | None = None,
        on_error: OnError = "raise",
    ) -> Array[R]:
        """Like ``map``, across the process's one thread pool, sized to the CPU count.

        Parallel only where ``function`` releases the GIL: decoding an image,
        NumPy, a subprocess. ``cg.parallelism(workers)`` caps how many elements
        are in flight at once. Each worker runs in a copy of the caller's
        context, so the active scratch, workspace and log scope carry over;
        a ``pmap`` inside a worker runs sequentially, the outer pool being the
        parallelism. The first element to raise propagates as soon as it
        does, and elements not yet started never start; ``on_error`` is as
        for ``map``.

        ```python
        thumbnails = sessions.photo.pmap(session_thumbnail)
        ```
        """
        if not callable(function):
            raise TypeError(f"Array.pmap needs a callable, got {function!r}")
        return Array(pmapped(self._items, function, label, on_error))

    def map_leaves(self, function: Callable[[Any], object]) -> Array[Any]:
        """Apply ``function`` to every leaf, descending into nested Arrays.

        Raises if the call fails on every leaf for a non-data reason (a broken
        lambda fails loudly); a sparse data-absence failure chains as ``Missing``.
        """

        def leaf(value: object) -> object:
            if is_missing(value):
                return value if isinstance(value, _Missing) else Missing
            return isolated(function, value)

        result = Array(_rebuilt(item, leaf) for item in self._items)
        guard_broadcast(list(_leaves(result)), "map_leaves")
        return result

    def __call__(self, *args: object, **kwargs: object) -> Array[Any]:
        """Call each element with the same arguments (the elements are callables).

        Raises if the call fails on every element for a non-data reason (every
        element non-callable is a typo); a sparse failure chains as ``Missing``.
        """

        def called(item: object) -> object:
            if not callable(item):
                raise TypeError(f"Array element {item!r} is not callable")
            return item(*args, **kwargs)

        return Array(broadcast(self._items, "call", called))

    def __or__(self, default: object) -> Array[T]:
        """Fill ``Missing``/``None`` leaves with ``default``.

        A parallel sequence fills element-wise; this recurses into nested Arrays.
        """
        if isinstance(default, (Array, list)) and len(default) == len(self._items):
            filled = (
                _rebuilt(item, _filler(fill))
                for item, fill in zip(self._items, default, strict=True)
            )
        else:
            filled = (_rebuilt(item, _filler(default)) for item in self._items)
        return cast("Array[T]", Array(filled))

    # --- inspection ---------------------------------------------------------

    @property
    def dtype(self) -> type | None:
        """The type of the first present row (descends nested arrays), or ``None``."""
        return next((type(row) for row in _rows(self._items) if not is_missing(row)), None)

    @property
    def dkeys(self) -> Array[str]:
        """The union of field/key names across all present rows."""
        keys: set[str] = set()
        for row in _rows(self._items):
            keys.update(_field_names(row))
        return Array(keys)

    def __dir__(self) -> list[str]:
        """Standard members plus the broadcastable element field names.

        Surfaces ``photos.location`` in REPL/notebook autocomplete; the
        broadcast itself stays dynamically typed.
        """
        return [*super().__dir__(), *self.dkeys]

    # --- conversion ---------------------------------------------------------

    def to_numpy(self) -> np.ndarray:
        """Convert to a NumPy array, mapping ``Missing``/``None`` to ``nan``."""
        import numpy as np

        return np.array(_unwrapped(self._items))

    def __array__(
        self,
        dtype: DTypeLike | None = None,
        copy: bool = True,
    ) -> np.ndarray:
        """NumPy's array-conversion protocol hook — see ``to_numpy``."""
        array = self.to_numpy()
        return array if dtype is None else array.astype(dtype)

    def to_dict(
        self,
        keys: tuple[str, ...] | list[str] | None = None,
    ) -> dict[str, list[object]]:
        """Column-orient as ``{name: [values]}`` for a DataFrame.

        With no ``keys``, the union of leaf field names is used; ``Missing`` is
        written as ``None``.
        """
        if keys is None:
            keys = list(self.dkeys)
        if not self._items:
            return {key: [] for key in keys}
        return {key: [_unwrapped(item) for item in self[key]] for key in keys}

dkeys property #

The union of field/key names across all present rows.

dtype property #

The type of the first present row (descends nested arrays), or None.

__add__(other) #

Concatenate with another sequence into a new Array.

Source code in capturegraph-lib/capturegraph/types/containers/array.py
def __add__(self, other: Iterable[T]) -> Array[T]:
    """Concatenate with another sequence into a new ``Array``."""
    return Array([*self._items, *other])

__array__(dtype=None, copy=True) #

NumPy's array-conversion protocol hook — see to_numpy.

Source code in capturegraph-lib/capturegraph/types/containers/array.py
def __array__(
    self,
    dtype: DTypeLike | None = None,
    copy: bool = True,
) -> np.ndarray:
    """NumPy's array-conversion protocol hook — see ``to_numpy``."""
    array = self.to_numpy()
    return array if dtype is None else array.astype(dtype)

__bool__() #

Falsy when empty, like a plain list.

Source code in capturegraph-lib/capturegraph/types/containers/array.py
def __bool__(self) -> bool:
    """Falsy when empty, like a plain list."""
    return bool(self._items)

__call__(*args, **kwargs) #

Call each element with the same arguments (the elements are callables).

Raises if the call fails on every element for a non-data reason (every element non-callable is a typo); a sparse failure chains as Missing.

Source code in capturegraph-lib/capturegraph/types/containers/array.py
def __call__(self, *args: object, **kwargs: object) -> Array[Any]:
    """Call each element with the same arguments (the elements are callables).

    Raises if the call fails on every element for a non-data reason (every
    element non-callable is a typo); a sparse failure chains as ``Missing``.
    """

    def called(item: object) -> object:
        if not callable(item):
            raise TypeError(f"Array element {item!r} is not callable")
        return item(*args, **kwargs)

    return Array(broadcast(self._items, "call", called))

__class_getitem__(element) #

Build Array[element] — a storable subclass, or a typing-only alias.

A CGType element makes Array[T] whose storability follows the element: Array[Image] is storable, while Array[Path[V]] is a non-storable fan-out collection (an array of positions, never written to disk). A non-CGType element is a typing-only alias, so loaded values can be annotated without a schema.

Source code in capturegraph-lib/capturegraph/types/containers/array.py
def __class_getitem__(cls, element: object) -> type[Array] | GenericAlias:
    """Build ``Array[element]`` — a storable subclass, or a typing-only alias.

    A CGType element makes ``Array[T]`` whose storability *follows* the
    element: ``Array[Image]`` is storable, while ``Array[Path[V]]`` is a
    non-storable fan-out collection (an array of positions, never written to
    disk). A non-CGType element is a typing-only alias, so loaded values can
    be annotated without a schema.
    """
    if not (isinstance(element, type) and issubclass(element, CGType)):
        return GenericAlias(cls, element)
    check_cgtype(element, "Array element")
    key = (cls, element)
    if key not in _SUBSCRIPTS:
        _SUBSCRIPTS[key] = type(
            f"Array[{element.__name__}]",
            (cls,),
            {"__slots__": (), "_element": element, "storable": element.storable},
        )
    return _SUBSCRIPTS[key]

__dir__() #

Standard members plus the broadcastable element field names.

Surfaces photos.location in REPL/notebook autocomplete; the broadcast itself stays dynamically typed.

Source code in capturegraph-lib/capturegraph/types/containers/array.py
def __dir__(self) -> list[str]:
    """Standard members plus the broadcastable element field names.

    Surfaces ``photos.location`` in REPL/notebook autocomplete; the
    broadcast itself stays dynamically typed.
    """
    return [*super().__dir__(), *self.dkeys]

__eq__(other) #

Equal to another Array or a plain list with the same elements.

Source code in capturegraph-lib/capturegraph/types/containers/array.py
def __eq__(self, other: object) -> bool:
    """Equal to another ``Array`` or a plain ``list`` with the same elements."""
    if isinstance(other, Array):
        return self._items == other._items
    if isinstance(other, list):
        return self._items == other
    return NotImplemented

__getattr__(name) #

Broadcast attribute access over the elements.

A name no element has raises (a typo), a name some lack chains as Missing; this array's own machinery is not an element field (broadcastable).

Source code in capturegraph-lib/capturegraph/types/containers/array.py
def __getattr__(self, name: str) -> Array[Any]:
    """Broadcast attribute access over the elements.

    A name no element has raises (a typo), a name some lack chains as
    ``Missing``; this array's own machinery is not an element field
    (``broadcastable``).
    """
    if not broadcastable(self, name):
        raise AttributeError(name)
    return Array(broadcast(self._items, f"attribute {name!r}", _accessor(name)))

__getitem__(key) #

__getitem__(key: SupportsIndex) -> T
__getitem__(key: slice) -> Array[T]
__getitem__(key: str | tuple[str, ...]) -> Array[Any]

Index by position (int/slice) or project by str/tuple.

numbers.Integral is accepted alongside plain int so a NumPy index (np.argmax etc.) works like one — this Array converts to and from NumPy for analysis. An out-of-range index chains as Missing (typed as the element).

Source code in capturegraph-lib/capturegraph/types/containers/array.py
def __getitem__(self, key: SupportsIndex | slice | str | tuple[str, ...]) -> object:
    """Index by position (``int``/``slice``) or project by ``str``/``tuple``.

    ``numbers.Integral`` is accepted alongside plain ``int`` so a NumPy
    index (``np.argmax`` etc.) works like one — this Array converts to and
    from NumPy for analysis. An out-of-range index chains as ``Missing``
    (typed as the element).
    """
    if isinstance(key, numbers.Integral):
        try:
            return wrapped(self._items[int(key)])
        except IndexError as error:
            return _Missing(error)
    if isinstance(key, slice):
        return Array(wrapped(item) for item in self._items[key])
    if isinstance(key, str):
        return Array(self._project(key))
    if isinstance(key, tuple):
        columns = {name: self._project(name) for name in key}
        return Array(
            {name: columns[name][index] for name in key} for index in range(len(self._items))
        )
    raise TypeError(f"Array indices must be int, slice, str, or tuple[str, ...]; got {key!r}")

__init__(items=()) #

Wrap items (any iterable, copied into a plain list) as an Array.

Source code in capturegraph-lib/capturegraph/types/containers/array.py
def __init__(self, items: Iterable[T] = ()) -> None:
    """Wrap ``items`` (any iterable, copied into a plain list) as an Array."""
    object.__setattr__(self, "_items", list(items))

__iter__() #

Iterate the wrapped elements, in order.

Source code in capturegraph-lib/capturegraph/types/containers/array.py
def __iter__(self) -> Iterator[T]:
    """Iterate the wrapped elements, in order."""
    return iter(self._items)

__len__() #

The number of elements.

Source code in capturegraph-lib/capturegraph/types/containers/array.py
def __len__(self) -> int:
    """The number of elements."""
    return len(self._items)

__or__(default) #

Fill Missing/None leaves with default.

A parallel sequence fills element-wise; this recurses into nested Arrays.

Source code in capturegraph-lib/capturegraph/types/containers/array.py
def __or__(self, default: object) -> Array[T]:
    """Fill ``Missing``/``None`` leaves with ``default``.

    A parallel sequence fills element-wise; this recurses into nested Arrays.
    """
    if isinstance(default, (Array, list)) and len(default) == len(self._items):
        filled = (
            _rebuilt(item, _filler(fill))
            for item, fill in zip(self._items, default, strict=True)
        )
    else:
        filled = (_rebuilt(item, _filler(default)) for item in self._items)
    return cast("Array[T]", Array(filled))

__radd__(other) #

Concatenate a sequence with this array into a new Array.

Source code in capturegraph-lib/capturegraph/types/containers/array.py
def __radd__(self, other: Iterable[T]) -> Array[T]:
    """Concatenate a sequence with this array into a new ``Array``."""
    return Array([*other, *self._items])

__repr__() #

The wrapped elements' own repr.

Source code in capturegraph-lib/capturegraph/types/containers/array.py
def __repr__(self) -> str:
    """The wrapped elements' own ``repr``."""
    return repr(self._items)

__setattr__(name, value) #

Broadcast attribute assignment over the elements.

An empty array adopts the length of value, creating a plain dict per entry; a non-empty array assigns element-wise (a same-length sequence), broadcasts a single-element sequence or a scalar, and skips Missing elements. Each element is written by attribute when it supports one, else by key (a dict row).

Raises:

Type Description
TypeError

If this array, or an element written, was loaded from disk.

Source code in capturegraph-lib/capturegraph/types/containers/array.py
def __setattr__(self, name: str, value: object) -> None:
    """Broadcast attribute assignment over the elements.

    An empty array adopts the length of ``value``, creating a plain ``dict``
    per entry; a non-empty array assigns element-wise (a same-length
    sequence), broadcasts a single-element sequence or a scalar, and skips
    ``Missing`` elements. Each element is written by attribute when it
    supports one, else by key (a ``dict`` row).

    Raises:
        TypeError: If this array, or an element written, was loaded from disk.
    """
    if not broadcastable(self, name):
        object.__setattr__(self, name, value)
        return

    refuse_change(self)
    if isinstance(value, (list, tuple, Array)):
        values = list(value)
        if not self._items:
            _backing(self).extend({name: item} for item in values)
            return
        if len(values) == len(self._items):
            pairs = zip(self._items, values, strict=True)
        elif len(values) == 1:
            pairs = ((item, values[0]) for item in self._items)
        else:
            raise ValueError(
                f"Cannot assign sequence of length {len(values)} to Array of "
                f"length {len(self._items)}; lengths must match, or use a "
                f"single-element sequence / scalar to broadcast."
            )
        for item, item_value in pairs:
            if not is_missing(item):
                _set(item, name, item_value)
        return
    for item in self._items:
        if not is_missing(item):
            _set(item, name, value)

append(item) #

Add item to the end of the array, in place.

Raises:

Type Description
TypeError

If this array was loaded from disk.

Source code in capturegraph-lib/capturegraph/types/containers/array.py
def append(self, item: T) -> None:
    """Add ``item`` to the end of the array, in place.

    Raises:
        TypeError: If this array was loaded from disk.
    """
    refuse_change(self)
    self._items.append(item)

clone() #

An in-memory copy that can change, its containers copied and its scalars shared.

Source code in capturegraph-lib/capturegraph/types/containers/array.py
def clone(self) -> Self:
    """An in-memory copy that can change, its containers copied and its scalars shared."""
    return share_hold(self, type(self)(cast("T", cloned(item)) for item in self._items))

index_name(index) classmethod #

The entry name of the element at index: what a page links to it by.

assert cg.Array.index_name(17) == "00017"
Source code in capturegraph-lib/capturegraph/types/containers/array.py
@classmethod
def index_name(cls, index: int) -> str:
    """The entry name of the element at ``index``: what a page links to it by.

    ```python
    assert cg.Array.index_name(17) == "00017"
    ```
    """
    return index_name(index)

load(base) classmethod #

The array stored at base, elements in index order; an unwritten tree is empty.

Raises:

Type Description
TypeError

If this array is schemaless.

Source code in capturegraph-lib/capturegraph/types/containers/array.py
@classmethod
def load(cls, base: Path) -> Self:
    """The array stored at ``base``, elements in index order; an unwritten tree is empty.

    Raises:
        TypeError: If this array is schemaless.
    """
    if cls._element is None:
        raise TypeError(f"{cls.__name__} cannot load without an element type")
    stems = entry_stems(base) if base.is_dir() else []
    array = cls(cast("list[T]", [load_entry(cls._element, base / stem) for stem in stems]))
    freeze_at(array, base)
    return array

map(function, label=None, on_error='raise') #

Apply function to each element, in order.

The walk is a logged count of the elements, shown as label or function's name. An element that raises stops it: the exception propagates at once. on_error="missing" runs every element instead, keeping a failure as a reasoned Missing and raising only when every element fails for a non-data reason.

keypoints = images.map(cgr.sfm.keypoints)
sparse = images.map(cgr.sfm.keypoints, on_error="missing")
Source code in capturegraph-lib/capturegraph/types/containers/array.py
def map[R](
    self,
    function: Callable[[T], R],
    label: str | None = None,
    on_error: OnError = "raise",
) -> Array[R]:
    """Apply ``function`` to each element, in order.

    The walk is a logged count of the elements, shown as ``label`` or
    ``function``'s name. An element that raises stops it: the exception
    propagates at once. ``on_error="missing"`` runs every element instead,
    keeping a failure as a reasoned ``Missing`` and raising only when every
    element fails for a non-data reason.

    ```python
    keypoints = images.map(cgr.sfm.keypoints)
    sparse = images.map(cgr.sfm.keypoints, on_error="missing")
    ```
    """
    if not callable(function):
        raise TypeError(f"Array.map needs a callable, got {function!r}")
    return Array(mapped(self._items, function, label, on_error))

map_leaves(function) #

Apply function to every leaf, descending into nested Arrays.

Raises if the call fails on every leaf for a non-data reason (a broken lambda fails loudly); a sparse data-absence failure chains as Missing.

Source code in capturegraph-lib/capturegraph/types/containers/array.py
def map_leaves(self, function: Callable[[Any], object]) -> Array[Any]:
    """Apply ``function`` to every leaf, descending into nested Arrays.

    Raises if the call fails on every leaf for a non-data reason (a broken
    lambda fails loudly); a sparse data-absence failure chains as ``Missing``.
    """

    def leaf(value: object) -> object:
        if is_missing(value):
            return value if isinstance(value, _Missing) else Missing
        return isolated(function, value)

    result = Array(_rebuilt(item, leaf) for item in self._items)
    guard_broadcast(list(_leaves(result)), "map_leaves")
    return result

pmap(function, label=None, on_error='raise') #

Like map, across the process's one thread pool, sized to the CPU count.

Parallel only where function releases the GIL: decoding an image, NumPy, a subprocess. cg.parallelism(workers) caps how many elements are in flight at once. Each worker runs in a copy of the caller's context, so the active scratch, workspace and log scope carry over; a pmap inside a worker runs sequentially, the outer pool being the parallelism. The first element to raise propagates as soon as it does, and elements not yet started never start; on_error is as for map.

thumbnails = sessions.photo.pmap(session_thumbnail)
Source code in capturegraph-lib/capturegraph/types/containers/array.py
def pmap[R](
    self,
    function: Callable[[T], R],
    label: str | None = None,
    on_error: OnError = "raise",
) -> Array[R]:
    """Like ``map``, across the process's one thread pool, sized to the CPU count.

    Parallel only where ``function`` releases the GIL: decoding an image,
    NumPy, a subprocess. ``cg.parallelism(workers)`` caps how many elements
    are in flight at once. Each worker runs in a copy of the caller's
    context, so the active scratch, workspace and log scope carry over;
    a ``pmap`` inside a worker runs sequentially, the outer pool being the
    parallelism. The first element to raise propagates as soon as it
    does, and elements not yet started never start; ``on_error`` is as
    for ``map``.

    ```python
    thumbnails = sessions.photo.pmap(session_thumbnail)
    ```
    """
    if not callable(function):
        raise TypeError(f"Array.pmap needs a callable, got {function!r}")
    return Array(pmapped(self._items, function, label, on_error))

schema() classmethod #

This array's wire form: its element's schema, tagged "array".

Source code in capturegraph-lib/capturegraph/types/containers/array.py
@classmethod
def schema(cls) -> dict[str, JSONValue]:
    """This array's wire form: its element's schema, tagged ``"array"``."""
    if cls._element is None:
        raise TypeError("a schemaless Array has no wire form")
    return {"type": "array", "element": cls._element.schema()}

store(base, value) classmethod #

Write value under base, one zero-padded index entry per element.

A Missing element keeps its index: it is written as the marker <index>.cg-missing holding its reason, and loads back as Missing.

Raises:

Type Description
TypeError

If this array is schemaless or value is not iterable.

Source code in capturegraph-lib/capturegraph/types/containers/array.py
@classmethod
def store(cls, base: Path, value: object) -> None:
    """Write ``value`` under ``base``, one zero-padded index entry per element.

    A ``Missing`` element keeps its index: it is written as the marker
    ``<index>.cg-missing`` holding its reason, and loads back as ``Missing``.

    Raises:
        TypeError: If this array is schemaless or ``value`` is not iterable.
    """
    if cls._element is None:
        raise TypeError(f"{cls.__name__} cannot store without an element type")
    if not isinstance(value, Iterable):
        raise TypeError(f"{cls.__name__}.store needs an iterable, got {value!r}")
    base.mkdir(parents=True, exist_ok=True)
    for index, item in enumerate(value):
        store_entry(cls._element, base / index_name(index), item)

to_dict(keys=None) #

Column-orient as {name: [values]} for a DataFrame.

With no keys, the union of leaf field names is used; Missing is written as None.

Source code in capturegraph-lib/capturegraph/types/containers/array.py
def to_dict(
    self,
    keys: tuple[str, ...] | list[str] | None = None,
) -> dict[str, list[object]]:
    """Column-orient as ``{name: [values]}`` for a DataFrame.

    With no ``keys``, the union of leaf field names is used; ``Missing`` is
    written as ``None``.
    """
    if keys is None:
        keys = list(self.dkeys)
    if not self._items:
        return {key: [] for key in keys}
    return {key: [_unwrapped(item) for item in self[key]] for key in keys}

to_numpy() #

Convert to a NumPy array, mapping Missing/None to nan.

Source code in capturegraph-lib/capturegraph/types/containers/array.py
def to_numpy(self) -> np.ndarray:
    """Convert to a NumPy array, mapping ``Missing``/``None`` to ``nan``."""
    import numpy as np

    return np.array(_unwrapped(self._items))

broadcast(items, operation, function) #

function over items, isolated per element and guarded as a whole.

The one broadcast rule Array and Map share.

Parameters:

Name Type Description Default
items Iterable[I]

The elements to apply function to.

required
operation str

Names this broadcast in the failure message.

required
function Callable[[I], R]

The per-element operation.

required

Returns:

Type Description
list[R]

One result per element, in order; a per-element failure is a reasoned

list[R]

Missing and a raw list result is rewrapped as an Array.

Raises:

Type Description
Exception

The first element's reason, when every element failed for a non-data reason — see guard_broadcast.

Source code in capturegraph-lib/capturegraph/types/containers/array.py
def broadcast[I, R](
    items: Iterable[I],
    operation: str,
    function: Callable[[I], R],
) -> list[R]:
    """``function`` over ``items``, isolated per element and guarded as a whole.

    The one broadcast rule ``Array`` and ``Map`` share.

    Args:
        items: The elements to apply ``function`` to.
        operation: Names this broadcast in the failure message.
        function: The per-element operation.

    Returns:
        One result per element, in order; a per-element failure is a reasoned
        ``Missing`` and a raw ``list`` result is rewrapped as an ``Array``.

    Raises:
        Exception: The first element's reason, when every element failed for a
            non-data reason — see
            [guard_broadcast][capturegraph.types.core.container.missing.guard_broadcast].
    """
    return guard_broadcast([isolated(function, item) for item in items], operation)

broadcastable(container, name) #

Whether name is an element field to broadcast rather than the container's own machinery.

A dunder is Python's own protocol and a declared slot is the container's storage: copy, pickle and notebook probes look those up and must see a plain miss. Every other name broadcasts, a hidden schema field (_metadata) included.

assert broadcastable(cg.Array(), "_metadata")
assert not broadcastable(cg.Array(), "__deepcopy__")
Source code in capturegraph-lib/capturegraph/types/containers/array.py
def broadcastable(container: object, name: str) -> bool:
    """Whether ``name`` is an element field to broadcast rather than the container's own machinery.

    A dunder is Python's own protocol and a declared slot is the container's
    storage: ``copy``, ``pickle`` and notebook probes look those up and must see
    a plain miss. Every other name broadcasts, a hidden schema field
    (``_metadata``) included.

    ```python
    assert broadcastable(cg.Array(), "_metadata")
    assert not broadcastable(cg.Array(), "__deepcopy__")
    ```
    """
    if name.startswith("__") and name.endswith("__"):
        return False
    return not any(name in getattr(base, "__slots__", ()) for base in type(container).__mro__)

index_name(index) #

The on-disk folder name for the array element at index.

Zero-padded to a fixed width so the ascending-lexicographic entry_stems order (the cross-platform enumeration contract) matches numeric order.

Source code in capturegraph-lib/capturegraph/types/containers/array.py
def index_name(index: int) -> str:
    """The on-disk folder name for the array element at ``index``.

    Zero-padded to a fixed width so the ascending-lexicographic ``entry_stems``
    order (the cross-platform enumeration contract) matches numeric order.
    """
    return f"{index:0{_INDEX_WIDTH}d}"

isolated(function, item) #

function(item) with per-element isolation: a failure becomes Missing.

The substitutions a broadcast makes — Missing for a failure, an Array for a raw list — keep function's return type, the way a Missing chains as the element it stands in for.

Source code in capturegraph-lib/capturegraph/types/containers/array.py
def isolated[I, R](function: Callable[[I], R], item: I) -> R:
    """``function(item)`` with per-element isolation: a failure becomes ``Missing``.

    The substitutions a broadcast makes — ``Missing`` for a failure, an
    ``Array`` for a raw ``list`` — keep ``function``'s return type, the way a
    ``Missing`` chains as the element it stands in for.
    """
    try:
        result = wrapped(function(item))
    except Exception as error:  # noqa: BLE001 — per-element isolation
        result = _Missing(error)
    return cast("R", result)

mapped(items, function, label, on_error) #

function over an iterated log count of items: the rule behind map.

Each element is one iteration of the count, so what an element logs revises what the last one logged, the way a for loop over cg.logging.progress does. With on_error="raise" the first element that raises stops the walk and its exception propagates; with "missing" every element runs and a failure is a reasoned Missing (broadcast's rule).

Parameters:

Name Type Description Default
items Sequence[I]

The elements to apply function to.

required
function Callable[[I], R]

The per-element operation.

required
label str | None

What the count shows; function's name when None.

required
on_error OnError

What an element that raises does to the walk.

required
Source code in capturegraph-lib/capturegraph/types/containers/array.py
def mapped[I, R](
    items: Sequence[I],
    function: Callable[[I], R],
    label: str | None,
    on_error: OnError,
) -> list[R]:
    """``function`` over an iterated log count of ``items``: the rule behind ``map``.

    Each element is one iteration of the count, so what an element logs
    revises what the last one logged, the way a ``for`` loop over
    ``cg.logging.progress`` does. With ``on_error="raise"`` the first element
    that raises stops the walk and its exception propagates; with
    ``"missing"`` every element runs and a failure is a reasoned ``Missing``
    (``broadcast``'s rule).

    Args:
        items: The elements to apply ``function`` to.
        function: The per-element operation.
        label: What the count shows; ``function``'s name when ``None``.
        on_error: What an element that raises does to the walk.
    """
    counted = progress(items, label=label or label_of(function))
    if on_error == "missing":
        return broadcast(counted, "map", function)
    return [cast("R", wrapped(function(item))) for item in counted]

parse_index_name(name) #

The array index a folder name encodes, or raise if it is not one.

Canonical means exactly index_name(i): ASCII digits, zero-padded to the fixed width (wider only for a huge index), no sign and no alias padding — so a hostile path component cannot masquerade as an index it does not equal.

Source code in capturegraph-lib/capturegraph/types/containers/array.py
def parse_index_name(name: str) -> int:
    """The array index a folder ``name`` encodes, or raise if it is not one.

    Canonical means exactly ``index_name(i)``: ASCII digits, zero-padded to the
    fixed width (wider only for a huge index), no sign and no alias padding — so a
    hostile path component cannot masquerade as an index it does not equal.
    """
    if not (name.isascii() and name.isdigit()):
        raise ValueError(f"not an array index: {name!r}")
    index = int(name)
    if index_name(index) != name:
        raise ValueError(f"non-canonical array index: {name!r}")
    return index

wrapped(item) #

Wrap a raw list result so nested access keeps broadcasting.

Source code in capturegraph-lib/capturegraph/types/containers/array.py
def wrapped(item: object) -> object:
    """Wrap a raw ``list`` result so nested access keeps broadcasting."""
    return Array(item) if isinstance(item, list) else item