Field¶

didactic.api.field ¶

field(
    *,
    default: T,
    converter: Callable[[FieldValue], FieldValue]
    | None = ...,
    alias: str | None = ...,
    description: str | None = ...,
    examples: tuple[FieldValue, ...] = ...,
    deprecated: bool = ...,
    nominal: bool = ...,
    constraint: Opaque | None = ...,
    coercion: Callable[..., FieldValue] | None = ...,
    usage_mode: Literal[
        "readwrite", "computed", "materialised"
    ] = ...,
    extras: Mapping[str, Opaque] | None = ...,
    opaque: bool = ...,
) -> T

field(
    *,
    default_factory: Callable[[], T],
    converter: Callable[[FieldValue], FieldValue]
    | None = ...,
    alias: str | None = ...,
    description: str | None = ...,
    examples: tuple[FieldValue, ...] = ...,
    deprecated: bool = ...,
    nominal: bool = ...,
    constraint: Opaque | None = ...,
    coercion: Callable[..., FieldValue] | None = ...,
    usage_mode: Literal[
        "readwrite", "computed", "materialised"
    ] = ...,
    extras: Mapping[str, Opaque] | None = ...,
    opaque: bool = ...,
) -> T

field(
    *,
    converter: Callable[[FieldValue], FieldValue]
    | None = ...,
    alias: str | None = ...,
    description: str | None = ...,
    examples: tuple[FieldValue, ...] = ...,
    deprecated: bool = ...,
    nominal: bool = ...,
    constraint: Opaque | None = ...,
    coercion: Callable[..., FieldValue] | None = ...,
    usage_mode: Literal[
        "readwrite", "computed", "materialised"
    ] = ...,
    extras: Mapping[str, Opaque] | None = ...,
    opaque: bool = ...,
) -> Any

field(
    *,
    default: FieldValue | _Missing = MISSING,
    default_factory: Callable[[], FieldValue] | None = None,
    converter: Callable[[FieldValue], FieldValue]
    | None = None,
    alias: str | None = None,
    description: str | None = None,
    examples: tuple[FieldValue, ...] = (),
    deprecated: bool = False,
    nominal: bool = False,
    constraint: Opaque | None = None,
    coercion: Callable[..., FieldValue] | None = None,
    usage_mode: Literal[
        "readwrite", "computed", "materialised"
    ] = "readwrite",
    extras: Mapping[str, Opaque] | None = None,
    opaque: bool = False,
) -> Field

Construct a Field descriptor.

PARAMETER	DESCRIPTION
`default`	Default value. If both `default` and `default_factory` are omitted, the field is required. TYPE: `FieldValue \| _Missing` DEFAULT: `MISSING`
`default_factory`	Zero-argument callable returning a default. Mutually exclusive with `default`. TYPE: `Callable[[], FieldValue] \| None` DEFAULT: `None`
`converter`	PEP 712 converter applied before type validation. TYPE: `Callable[[FieldValue], FieldValue] \| None` DEFAULT: `None`
`alias`	Serialisation alias. Useful when JSON/TOML payloads use a different name than the Python attribute. TYPE: `str \| None` DEFAULT: `None`
`description`	Human-readable field description. Populates Theory metadata. TYPE: `str \| None` DEFAULT: `None`
`examples`	Example values for documentation and code generation. TYPE: `tuple[FieldValue, ...]` DEFAULT: `()`
`deprecated`	Mark the field as deprecated; warning emitted at construction. TYPE: `bool` DEFAULT: `False`
`nominal`	If `True`, contributes to vertex identity (see VCS docs). TYPE: `bool` DEFAULT: `False`
`constraint`	Constraint metadata equivalent to placing it in `Annotated[...]`. TYPE: `Opaque \| None` DEFAULT: `None`
`coercion`	A coercion lens or callable. Stored on the FieldSpec and available to downstream tooling, but the Model construction path does not yet route values through it. TYPE: `Callable[..., FieldValue] \| None` DEFAULT: `None`
`usage_mode`	Field role: `"readwrite"` \| `"computed"` \| `"materialised"`. TYPE: `Literal['readwrite', 'computed', 'materialised']` DEFAULT: `'readwrite'`
`extras`	Extra metadata for downstream tooling. TYPE: `Mapping[str, Opaque] \| None` DEFAULT: `None`

RETURNS	DESCRIPTION
`Field`	A field descriptor. With the metaclass's `@dataclass_transform` and the `field_specifiers=(Field, field)` declaration, type checkers accept `foo: int = dx.field(...)` because they recognise this as a synthesised default for the field.

didactic.api.Field `dataclass` ¶

Field(
    default: DefaultOrMissing = MISSING,
    default_factory: Callable[[], FieldValue] | None = None,
    converter: Callable[[FieldValue], FieldValue]
    | None = None,
    alias: str | None = None,
    description: str | None = None,
    examples: tuple[FieldValue, ...] = (),
    deprecated: bool = False,
    nominal: bool = False,
    constraint: Opaque | None = None,
    coercion: Callable[..., FieldValue] | None = None,
    usage_mode: Literal[
        "readwrite", "computed", "materialised"
    ] = "readwrite",
    extras: Mapping[str, Opaque] | None = None,
    opaque: bool = False,
)

Field descriptor produced by the field constructor.

Field instances appear as the right-hand side of class-attribute assignments in a Model body::

class User(dx.Model):
    id: str
    email: str = dx.field(description="primary contact")

The metaclass extracts the configuration and produces a FieldSpec; Field itself carries no runtime behaviour beyond holding the configuration values.

PARAMETER	DESCRIPTION
`default`	Default value, or `MISSING` if no default. Mutually exclusive with `default_factory`. TYPE: `DefaultOrMissing` DEFAULT: `MISSING`
`default_factory`	Zero-argument callable returning a default value. TYPE: `Callable[[], FieldValue] \| None` DEFAULT: `None`
`converter`	PEP 712 converter. Runs before type validation and any `@validates` hooks. TYPE: `Callable[[FieldValue], FieldValue] \| None` DEFAULT: `None`
`alias`	External name for serialisation (input/output rename). TYPE: `str \| None` DEFAULT: `None`
`description`	Human-readable description; populates the Theory's field metadata. Equivalent to `Annotated[T, typing.Doc(...)]` (PEP 727). TYPE: `str \| None` DEFAULT: `None`
`examples`	Example values for documentation and code generation. TYPE: `tuple[FieldValue, ...]` DEFAULT: `()`
`deprecated`	If `True`, surfaces a deprecation warning at construction. TYPE: `bool` DEFAULT: `False`
`nominal`	If `True`, the field contributes to the model's vertex identity (used by panproto-vcs for stable blame across renames). TYPE: `bool` DEFAULT: `False`
`constraint`	A constraint object; typically an `annotated_types` primitive. Equivalent to placing it in `Annotated[T, ...]` metadata. TYPE: `Opaque \| None` DEFAULT: `None`
`coercion`	A coercion lens or callable; stored on the FieldSpec for downstream tooling, not consumed by Model construction yet. TYPE: `Callable[..., FieldValue] \| None` DEFAULT: `None`
`usage_mode`	Field role: `"readwrite"` (default), `"computed"`, or `"materialised"`. TYPE: `Literal['readwrite', 'computed', 'materialised']` DEFAULT: `'readwrite'`
`extras`	Extra metadata for downstream tooling. TYPE: `Mapping[str, Opaque] \| None` DEFAULT: `None`

didactic.api.FieldSpec `dataclass` ¶

FieldSpec(
    name: str,
    annotation: TypeForm | TypeVar | ForwardRef,
    translation: TypeTranslation,
    default: DefaultOrMissing = MISSING,
    default_factory: Callable[[], FieldValue] | None = None,
    converter: Callable[[FieldValue], FieldValue]
    | None = None,
    alias: str | None = None,
    description: str | None = None,
    examples: tuple[FieldValue, ...] = (),
    deprecated: bool = False,
    nominal: bool = False,
    usage_mode: Literal[
        "readwrite", "computed", "materialised"
    ] = "readwrite",
    axioms: tuple[str, ...] = (),
    extras: Mapping[str, Opaque] = (
        lambda: cast("dict[str, Opaque]", {})
    )(),
    is_opaque: bool = False,
)

Fully resolved field record produced by the metaclass.

A FieldSpec captures everything didactic needs to read or write one field: the sort name, the encode/decode pair, the default, the metadata, and any axioms induced by Annotated[...] constraints.

PARAMETER	DESCRIPTION
`name`	The Python attribute name. TYPE: `str`
`annotation`	The original (resolved) type annotation. TYPE: `TypeForm \| TypeVar \| ForwardRef`
`translation`	The result of running `didactic.types._types.classify` on the annotation. TYPE: `TypeTranslation`
`default`	The default value, or `MISSING` if the field is required. TYPE: `DefaultOrMissing` DEFAULT: `MISSING`
`default_factory`	Zero-argument default-producing callable, or `None`. TYPE: `Callable[[], FieldValue] \| None` DEFAULT: `None`
`converter`	PEP 712 converter applied before type validation. TYPE: `Callable[[FieldValue], FieldValue] \| None` DEFAULT: `None`
`alias`	External serialisation name, or `None`. TYPE: `str \| None` DEFAULT: `None`
`description`	Field description (from `dx.field(description=...)` or PEP 727 `Doc`). TYPE: `str \| None` DEFAULT: `None`
`examples`	Example values. TYPE: `tuple[FieldValue, ...]` DEFAULT: `()`
`deprecated`	Whether the field is deprecated. TYPE: `bool` DEFAULT: `False`
`nominal`	Whether the field contributes to vertex identity. TYPE: `bool` DEFAULT: `False`
`usage_mode`	Field role. TYPE: `Literal['readwrite', 'computed', 'materialised']` DEFAULT: `'readwrite'`
`axioms`	Axiom strings induced by `Annotated[...]` metadata. Each is a panproto-Expr-shaped predicate over the field's value. TYPE: `tuple[str, ...]` DEFAULT: `()`
`extras`	Unrecognised `Annotated` metadata, preserved for downstream tools. TYPE: `Mapping[str, Opaque]` DEFAULT: `(lambda: cast('dict[str, Opaque]', {}))()`

is_required `property` ¶

is_required: bool

Whether the field has no default and no default factory.

sort `property` ¶

sort: str

The panproto sort name for this field's value type.

make_default ¶

make_default() -> DefaultOrMissing

Produce a default value, calling the factory if present.

RETURNS	DESCRIPTION
`FieldValue or _Missing`	The default. `MISSING` if the field is required.

Keys	Action
`?`	Open this help
`n`	Next page
`p`	Previous page
`s`	Search

Field¶

didactic.api.field ¶

didactic.api.Field dataclass ¶

didactic.api.FieldSpec dataclass ¶

is_required property ¶

sort property ¶

make_default ¶

didactic.api.Field `dataclass` ¶

didactic.api.FieldSpec `dataclass` ¶

is_required `property` ¶

sort `property` ¶