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 = ...,
) -> 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 = ...,
) -> 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 = ...,
) -> Any

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,
) -> Field

Construct a Field descriptor.

Parameters:

Name	Type	Description	Default
default	DefaultOrMissing	Default value. If both default and default_factory are omitted, the field is required.	MISSING
default_factory	Callable[[], FieldValue] | None	Zero-argument callable returning a default. Mutually exclusive with default.	None
converter	Callable[[FieldValue], FieldValue] | None	PEP 712 converter applied before type validation.	None
alias	str | None	Serialisation alias. Useful when JSON/TOML payloads use a different name than the Python attribute.	None
description	str | None	Human-readable field description. Populates Theory metadata.	None
examples	tuple[FieldValue, ...]	Example values for documentation and code generation.	()
deprecated	bool	Mark the field as deprecated; warning emitted at construction.	False
nominal	bool	If True, contributes to vertex identity (see VCS docs).	False
constraint	Opaque | None	Constraint metadata equivalent to placing it in Annotated[...].	None
coercion	Callable[..., FieldValue] | None	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.	None
usage_mode	Literal['readwrite', 'computed', 'materialised']	Field role: "readwrite" | "computed" | "materialised".	'readwrite'
extras	Mapping[str, Opaque] | None	Extra metadata for downstream tooling.	None

Returns:

Type	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.

See Also

Field : the descriptor class returned by this function. didactic.models._meta : the metaclass that consumes Fields and produces FieldSpec records.

Examples:

>>> import didactic.api as dx
>>> class User(dx.Model):
...     id: str = dx.field(nominal=True, description="primary key")
...     email: str = dx.field(alias="email_address")

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,
)

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.

Parameters:

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

See Also

field : the function that returns Field instances. FieldSpec : the resolved record produced by the metaclass.

didactic.api.FieldSpec dataclass

FieldSpec(
    name: str,
    annotation: type,
    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] = dict(),
)

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.

Parameters:

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

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:

Type	Description
FieldValue or _Missing	The default. MISSING if the field is required.