cfx.types.typed_field¶

Annotation-native field factory.

Field() is the primary way to declare config fields when you want the field type inferred automatically from the type annotation:

class SearchConfig(Config):
    n_sigma: float = Field(5.0, "Detection threshold", ge=0.0)
    method: Literal["DBSCAN", "RANSAC"] = Field("DBSCAN", "Algorithm")

For custom field types or advanced validation, import explicit types from cfx.types and declare them directly:

from cfx.types import Float, Options

class SearchConfig(Config):
    n_sigma = Float(5.0, "Detection threshold", ge=0.0)
    method  = Options(("DBSCAN", "RANSAC"), "Algorithm")

Classes¶

FieldSpec

Placeholder returned by Field(); resolved at class-definition time.

Functions¶

`Field`(default[, doc])	Declare an annotation-native config field.
`resolve_field_spec`(name, spec, annotation)	Instantiate the right `ConfigField` subclass for an annotation.

Module Contents¶

class cfx.types.typed_field.FieldSpec(default, doc, **kwargs)[source]¶

Placeholder returned by Field(); resolved at class-definition time.

Users should not instantiate this directly — use Field() instead. Config.__init_subclass__ replaces every FieldSpec with the appropriate ConfigField subclass before any instance is created.

default¶

doc¶

kwargs¶

cfx.types.typed_field.Field(default, doc='', **kwargs)[source]¶

Declare an annotation-native config field.

Use as the right-hand side of a type-annotated class attribute on a Config subclass. The concrete ConfigField subclass is inferred from the annotation at class-definition time:

from typing import Literal
from cfx import Config, Field

class SearchConfig(Config):
    n_sigma: float = Field(5.0, "Detection threshold", ge=0.0)
    method: Literal["DBSCAN", "RANSAC"] = Field("DBSCAN", "Algorithm")
    verbose: bool = Field(False, "Enable verbose output")

choices= is an alternative to Literal[...] annotations — useful when the allowed values are a runtime constant rather than a literal:

ALGORITHMS = ("DBSCAN", "RANSAC", "IsolationForest")

class SearchConfig(Config):
    method: str = Field("DBSCAN", "Algorithm", choices=ALGORITHMS)

Callable defaults are supported for computed fields:

class DerivedConfig(Config):
    base: float = Field(1.0, "Base value")
    derived: float = Field(lambda self: self.base * 2, "Derived value")

Parameters:

defaultobject or callable: Default value or lazy factory accepting the owning instance.
docstr, optional: Human-readable description shown in display tables.
choicestuple, optional: Allowed values. Resolves to Options (or MultiOptions when the annotation is set). Unlike Literal[...], the choices are not visible to static type checkers — invalid assignments are caught at runtime only.
**kwargs: Any keyword argument accepted by the resolved field type (e.g. ge=,
``le=``, ``gt=``, ``lt=``, ``env=``, ``static=``, ``transient=``).

Returns:

specFieldSpec: Placeholder resolved to a ConfigField at class-definition time.

cfx.types.typed_field.resolve_field_spec(name, spec, annotation)[source]¶

Instantiate the right ConfigField subclass for an annotation.

Called by Config.__init_subclass__ for every FieldSpec in the class body. Not part of the end-user API but importable for advanced use.

Parameters:

namestr: The attribute name (used in error messages).
specFieldSpec: The placeholder carrying default, doc, and extra kwargs.
annotationtype: The resolved type annotation for this attribute.

Returns:

fieldConfigField: A fully constructed field descriptor.

Raises:

TypeError: If the annotation cannot be mapped to a known ConfigField type.