Skip to content

struct

struct #

Struct — named fields. Subclass Struct; the annotations are the fields.

class Session(cg.Struct):
    photo: cg.Image
    location: cg.Location

A field named with a leading _ is hidden on disk (_metadata → .metadata). A loaded struct is read-only; .clone() gives an in-memory copy that can change.

Struct #

Bases: CGType

A type with named fields; each subclass is a dataclass over its annotations.

Source code in capturegraph-lib/capturegraph/types/containers/struct.py
@dataclass_transform()
class Struct(CGType):
    """A type with named fields; each subclass is a dataclass over its annotations."""

    _fields: ClassVar[dict[str, type[CGType]]] = {}

    def __init_subclass__(cls, **kwargs: object) -> None:
        """Turn ``cls`` into a dataclass over its annotated CGType fields."""
        super().__init_subclass__(**kwargs)
        annotations = inspect.get_annotations(cls, eval_str=True)
        if not annotations:
            return
        for name, field_type in annotations.items():
            check_element(field_type, f"Struct field {name!r}")
        cls._fields = annotations
        dataclass(cls)

    def __setattr__(self, name: str, value: object) -> None:
        """Assign a field.

        Raises:
            TypeError: If this struct was loaded from disk.
        """
        if not name.startswith("_"):
            refuse_change(self)
        object.__setattr__(self, name, value)

    def clone(self) -> Self:
        """An in-memory copy that can change, its containers copied and its scalars shared."""
        return share_hold(
            self,
            type(self)(**{name: cloned(getattr(self, name)) for name in self._fields}),
        )

    @classmethod
    def schema(cls) -> dict[str, JSONValue]:
        """This struct's wire form: each field's schema, tagged ``"struct"``."""
        return {
            "type": "struct",
            "fields": {n: t.schema() for n, t in cls._fields.items()},
        }

    @classmethod
    def _children(cls) -> list[tuple[str, type[CGType]]]:
        """Every declared field, labelled ``.name``."""
        return [(f".{name}", field) for name, field in cls._fields.items()]

    @classmethod
    def _descend(cls, component: str) -> type[CGType]:
        """The field stored at on-disk entry ``component``.

        Raises:
            SchemaPathError: If no field carries that on-disk name.
        """
        for name, field in cls._fields.items():
            if on_disk(name) == component:
                return field
        raise SchemaPathError(
            f"{cls.__name__} has no field at {component!r}; "
            f"expected one of {[on_disk(name) for name in cls._fields]}"
        )

    @classmethod
    def load(cls, base: Path) -> Self:
        """The struct stored at ``base``, one entry per field; an absent field is ``Missing``.

        A field with nothing on disk (an optional capture that never happened)
        is ``Missing`` with a ``FileNotFoundError`` reason; a field stored as a
        marker carries the reason the marker holds.

        Raises:
            FileNotFoundError: If ``base`` is not a directory.
        """
        if not base.is_dir():
            raise FileNotFoundError(f"no {cls.__name__} directory at {base}")
        values: dict[str, object] = {}
        for name, field in cls._fields.items():
            try:
                values[name] = load_entry(field, base / on_disk(name))
            except FileNotFoundError as error:
                values[name] = _Missing(error)
        value = cls(**values)
        freeze_at(value, base)
        return value

    @classmethod
    def store(cls, base: Path, value: object) -> None:
        """Write each field of ``value`` under ``base``, named for the field.

        ``value`` is an instance of this struct or of any struct with the same
        schema — one defined by a re-executed module, say. A ``Missing`` field
        is written as the marker ``<field>.cg-missing`` holding its reason, and
        loads back as ``Missing``.

        Raises:
            TypeError: If ``value`` is not a struct with this schema.
        """
        if not (
            isinstance(value, cls) or (isinstance(value, Struct) and value.schema() == cls.schema())
        ):
            raise TypeError(f"{cls.__name__}.store needs a {cls.__name__}, got {value!r}")
        base.mkdir(parents=True, exist_ok=True)
        for name, field in cls._fields.items():
            store_entry(field, base / on_disk(name), getattr(value, name))

__init_subclass__(**kwargs) #

Turn cls into a dataclass over its annotated CGType fields.

Source code in capturegraph-lib/capturegraph/types/containers/struct.py
def __init_subclass__(cls, **kwargs: object) -> None:
    """Turn ``cls`` into a dataclass over its annotated CGType fields."""
    super().__init_subclass__(**kwargs)
    annotations = inspect.get_annotations(cls, eval_str=True)
    if not annotations:
        return
    for name, field_type in annotations.items():
        check_element(field_type, f"Struct field {name!r}")
    cls._fields = annotations
    dataclass(cls)

__setattr__(name, value) #

Assign a field.

Raises:

Type Description
TypeError

If this struct was loaded from disk.

Source code in capturegraph-lib/capturegraph/types/containers/struct.py
def __setattr__(self, name: str, value: object) -> None:
    """Assign a field.

    Raises:
        TypeError: If this struct was loaded from disk.
    """
    if not name.startswith("_"):
        refuse_change(self)
    object.__setattr__(self, name, value)

clone() #

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

Source code in capturegraph-lib/capturegraph/types/containers/struct.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)(**{name: cloned(getattr(self, name)) for name in self._fields}),
    )

load(base) classmethod #

The struct stored at base, one entry per field; an absent field is Missing.

A field with nothing on disk (an optional capture that never happened) is Missing with a FileNotFoundError reason; a field stored as a marker carries the reason the marker holds.

Raises:

Type Description
FileNotFoundError

If base is not a directory.

Source code in capturegraph-lib/capturegraph/types/containers/struct.py
@classmethod
def load(cls, base: Path) -> Self:
    """The struct stored at ``base``, one entry per field; an absent field is ``Missing``.

    A field with nothing on disk (an optional capture that never happened)
    is ``Missing`` with a ``FileNotFoundError`` reason; a field stored as a
    marker carries the reason the marker holds.

    Raises:
        FileNotFoundError: If ``base`` is not a directory.
    """
    if not base.is_dir():
        raise FileNotFoundError(f"no {cls.__name__} directory at {base}")
    values: dict[str, object] = {}
    for name, field in cls._fields.items():
        try:
            values[name] = load_entry(field, base / on_disk(name))
        except FileNotFoundError as error:
            values[name] = _Missing(error)
    value = cls(**values)
    freeze_at(value, base)
    return value

schema() classmethod #

This struct's wire form: each field's schema, tagged "struct".

Source code in capturegraph-lib/capturegraph/types/containers/struct.py
@classmethod
def schema(cls) -> dict[str, JSONValue]:
    """This struct's wire form: each field's schema, tagged ``"struct"``."""
    return {
        "type": "struct",
        "fields": {n: t.schema() for n, t in cls._fields.items()},
    }

store(base, value) classmethod #

Write each field of value under base, named for the field.

value is an instance of this struct or of any struct with the same schema — one defined by a re-executed module, say. A Missing field is written as the marker <field>.cg-missing holding its reason, and loads back as Missing.

Raises:

Type Description
TypeError

If value is not a struct with this schema.

Source code in capturegraph-lib/capturegraph/types/containers/struct.py
@classmethod
def store(cls, base: Path, value: object) -> None:
    """Write each field of ``value`` under ``base``, named for the field.

    ``value`` is an instance of this struct or of any struct with the same
    schema — one defined by a re-executed module, say. A ``Missing`` field
    is written as the marker ``<field>.cg-missing`` holding its reason, and
    loads back as ``Missing``.

    Raises:
        TypeError: If ``value`` is not a struct with this schema.
    """
    if not (
        isinstance(value, cls) or (isinstance(value, Struct) and value.schema() == cls.schema())
    ):
        raise TypeError(f"{cls.__name__}.store needs a {cls.__name__}, got {value!r}")
    base.mkdir(parents=True, exist_ok=True)
    for name, field in cls._fields.items():
        store_entry(field, base / on_disk(name), getattr(value, name))

on_disk(field_name) #

The on-disk entry name for a struct field (_metadata → .metadata).

Source code in capturegraph-lib/capturegraph/types/containers/struct.py
def on_disk(field_name: str) -> str:
    """The on-disk entry name for a struct field (``_metadata`` → ``.metadata``)."""
    return f".{field_name[1:]}" if field_name.startswith("_") else field_name

struct_fields(struct_or_type) #

The declared fields of a Struct value or type, name → type, as a fresh dict.

Raises:

Type Description
TypeError

If the argument is not a Struct value or subclass.

Source code in capturegraph-lib/capturegraph/types/containers/struct.py
def struct_fields(struct_or_type: Struct | type[Struct]) -> dict[str, type[CGType]]:
    """The declared fields of a ``Struct`` value or type, name → type, as a fresh dict.

    Raises:
        TypeError: If the argument is not a ``Struct`` value or subclass.
    """
    cls = struct_or_type if isinstance(struct_or_type, type) else type(struct_or_type)
    if not (isinstance(cls, type) and issubclass(cls, Struct)):
        raise TypeError(f"struct_fields expects a Struct, got {cls!r}")
    return dict(cls._fields)