field

class Factory(func)

A function wrapper to specify that a default value should be treated as a factory method

class RecordField(*, filler: records.fillers.filler.Filler, owner, name: str, default)

A singular field in a record, each field is owned by a single RecordBase subclass

filler: Filler

The filler instance when filling the field with arbitrary values

name: str

The name of the field

owner: type

the class the field is first defined in

tags: Set[Tag]

The tags of the field

__init__(*, filler: records.fillers.filler.Filler, owner, name: str, default)

Parameters

• filler – the filler instance to use when filling the field

• owner – the owning RecordBase subclass the field is bound to

• name – the name of the field

• default – the default of the field, wrapped in Factory for factory functions, or the singleton NO_DEFAULT if there is no default.

add_coercer(func, sub_key=None, **kwargs)

add a CallCoercion to the field’s filler.

Parameters

• func – the callable to wrap inside the CallCoercion

• sub_key – the key (if any) of the sub-filler to add the coercer to.

• kwargs – all kwargs are forwarded to CallCoercion

Returns

func, to use as a decorator

Warning

must be used inside of the owner class’s pre_bind class method.

class A(RecordBase):
    x: Annotated[int, check]
    @classmethod
    def pre_bind(cls):
        super().pre_bind()
        @cls.x.add_coercer
        def coercion0():
            ...

        @cls.x.add_coercer(a=15)
        def coercion1(a):
            ...

add_assert_validator(func, sub_key=None, **kwargs)

add a AssertCallValidation to the field’s filler.

Parameters

• func – the callable to wrap inside the AssertCallValidation

• sub_key – the key (if any) of the sub-filler to add the validator to.

• kwargs – all kwargs are forwarded to AssertCallValidation

Returns

func, to use as a decorator

Warning

must be used inside of the owner class’s pre_bind class method.

class A(RecordBase):
    x: Annotated[int, check]
    @classmethod
    def pre_bind(cls):
        super().pre_bind()
        @cls.x.add_assert_validator
        def validator0():
            ...

        @cls.x.add_assert_validator(warn=True)
        def validator1():
            ...

add_validator(func, sub_key=None, **kwargs)

add a CallValidation to the field’s filler.

Parameters

• func – the callable to wrap inside the CallValidation

• sub_key – the key (if any) of the sub-filler to add the validator to.

• kwargs – all kwargs are forwarded to CallValidation

Returns

func, to use as a decorator

Warning

must be used inside of the owner class’s pre_bind class method.

class A(RecordBase):
    x: Annotated[int, check]
    @classmethod
    def pre_bind(cls):
        super().pre_bind()
        @cls.x.add_validator
        def validator0():
            ...

        @cls.x.add_validator(a=0)
        def validator1(a):
            ...

classmethod from_type_hint(th, *, owner, **kwargs) → Union[records.field.RecordField, object]

Create a field from a type hint.

Parameters

• th – the type hint to use

• owner – the owner RecordBase subclass

• kwargs – all keyword arguments are forwarded to the RecordField.__init__

Returns

a RecordField instance matching the type hint provided, or the sentinel SKIP_FIELD to indicate that this declaration should be skipped (in case of a ClassVar)

property has_default

Returns

whether or not the field has a default set

is_default(v)

Parameters

v – the value to compare

Returns

whether v is equal to the default value, if one exists

Note

currently, fields with a factory default always return False for this method, this is subject to change

make_default()

get a default value of the field, either from the default or default factory

Returns

An instance default value for the field.

Warning

It is an error to call this method on a field without a default

class FieldDict(Dict[str, RecordField])

A mapping from names to fields

filter_by_tag(tag: records.tags.Tag)

Filter the fields in the mapping to only those that have a tag

Parameters

tag – the tag to include

Returns

a new FieldDict including only the fields that possess tag