Skip to content

Introspection⚓︎

introspection ⚓︎

Immutable, machine-readable descriptions of table schema contracts.

The objects in this module are returned by Table.describe() and power the talika describe command. They intentionally contain only serializable or easily renderable metadata.

Info

Contracts describe schema shape and configured hooks. They do not parse a table or execute project validators.

FieldContract dataclass ⚓︎

FieldContract(
    name: str,
    label: str,
    aliases: tuple[str, ...],
    required: bool,
    is_id: bool,
    is_discriminator: bool,
    has_default: bool,
    default_repr: str | None,
    default_factory: str | None,
    parser: str | None,
    reference_target: str | None,
    reference_many: bool,
    empty: str,
)

Public description of one declared schema field.

Attributes:

  • name (str) –

    Python schema attribute name.

  • label (str) –

    Canonical Gherkin data table label.

  • aliases (tuple[str, ...]) –

    Alternate accepted labels.

  • required (bool) –

    Whether the field is required.

  • is_id (bool) –

    Whether the field identifies column-oriented records.

  • is_discriminator (bool) –

    Whether the field selects variants.

  • has_default (bool) –

    Whether a static or factory default is configured.

  • default_repr (str | None) –

    repr of a static default when present.

  • default_factory (str | None) –

    Display name of the default factory when present.

  • parser (str | None) –

    Display name of the parser when present.

  • reference_target (str | None) –

    Referenced field name when this is a reference.

  • reference_many (bool) –

    Whether the reference contains multiple keys.

  • empty (str) –

    Explicit empty-cell policy for optional values.

Info

The contract is frozen so tools can cache it safely.

from_field classmethod ⚓︎

from_field(name: str, declared: Field) -> FieldContract

Build an immutable contract from one field declaration.

Parameters:

  • name (str) –

    Python schema attribute name.

  • declared (Field) –

    Internal Field declaration.

Returns:

  • FieldContract –

    A FieldContract suitable for JSON conversion.

Warning

Defaults are represented with repr rather than copied as live objects, because contracts are descriptive metadata.

VariantContract dataclass ⚓︎

VariantContract(
    value: Any,
    schema_name: str,
    fields: tuple[FieldContract, ...],
    output_model: str | None,
    output_builder: str,
)

Description of one discriminator value and selected schema.

Attributes:

  • value (Any) –

    Parsed discriminator value that selects the variant.

  • schema_name (str) –

    Display name of the concrete variant schema.

  • fields (tuple[FieldContract, ...]) –

    Field contracts active for that variant.

  • output_model (str | None) –

    Display name of the variant output model, if any.

  • output_builder (str) –

    Display name of the output builder hook.

Info

Generated variant class names may change, so tooling should present schema_name and use variant_for() for runtime lookup.

TableContract dataclass ⚓︎

TableContract(
    schema_name: str,
    orientation: str,
    fields: tuple[FieldContract, ...],
    variants: tuple[VariantContract, ...],
    unknown_fields: str,
    inapplicable_fields: str,
    transformer: str | None,
    output_model: str | None,
    output_builder: str,
)

Complete public description returned by Table.describe().

Attributes:

  • schema_name (str) –

    Display name of the described schema.

  • orientation (str) –

    "row" or "column".

  • fields (tuple[FieldContract, ...]) –

    Base schema field contracts.

  • variants (tuple[VariantContract, ...]) –

    Discriminator variant contracts.

  • unknown_fields (str) –

    Policy for undeclared table labels.

  • inapplicable_fields (str) –

    Policy for values belonging to other variants.

  • transformer (str | None) –

    Display name of configured table transformer.

  • output_model (str | None) –

    Display name of configured output model.

  • output_builder (str) –

    Display name of the output builder hook.

Example

contract = UserTable.describe()
assert contract.orientation == "row"

as_dict ⚓︎

as_dict() -> dict[str, Any]

Return a recursively structured dictionary.

Returns:

  • dict[str, Any] –

    Dictionary containing only standard container values.

Info

CLI JSON output delegates to this method so editor integrations and CI scripts receive the same shape as Python callers.

_callable_name ⚓︎

_callable_name(value: Any) -> str | None

Return a best-effort display name for a callable or object.

Parameters:

  • value (Any) –

    Callable, object, None, or MISSING sentinel.

Returns:

  • str | None –

    None for absent values, otherwise a stable Talika parser

  • str | None –

    description or a qualified/name/type fallback.

Info

The result is for diagnostics and schema descriptions, not for re-importing the callable.

describe_schema ⚓︎

describe_schema(schema: Any) -> TableContract

Inspect one table schema without parsing a feature table.

Parameters:

  • schema (Any) –

    RowTable or ColumnTable subclass to describe.

Returns:

Warning

This function trusts that schema has already been created by the talika metaclass. Use Table.describe() for the public API.