Fields

Most fields are created simply with an annotated class attribute, with an optional default:

class MyModel(Model):
    required: int
    optional: Optional[str] = None

If you wish to use advanced field options, such as validation, assign an instance of one of these field classes to the attribute. The type hint is still mandatory and should correspond to the type represented by the field class.

class stereotype.BoolField(*, default: Any = Missing, hide_none: bool = False, hide_false: bool = False, primitive_name: str | None = Missing, to_primitive_name: str | None = Missing, validators: List[Callable[[Any, Any], None]] | None = None)

Boolean value (annotation bool), accepting boolean values or true/yes/false/no strings.

Parameters:

• default (Any) – Means the field isn’t required, used as default directly or called if callable

• hide_none (bool) – If the field’s value is None, it will be hidden from serialized output

• hide_false (bool) – If the field’s value is False, it will be hidden from serialized output

• primitive_name (Optional[str]) – Changes the key used to represent the field in serialized data - input or output

• to_primitive_name (Optional[str]) – Changes the key used to represent the field in serialized data - output only

• validators (Optional[List[Validator]]) – Optional list of validator callbacks - they raise ValueError if the value is invalid

class stereotype.IntField(*, default: Any = Missing, hide_none: bool = False, hide_zero: bool = False, primitive_name: str | None = Missing, to_primitive_name: str | None = Missing, min_value: int | None = None, max_value: int | None = None, validators: List[Callable[[Any, Any], None]] | None = None)

Integer value (annotation int), accepting integer values, whole float values or strings with integer values.

Parameters:

• default (Any) – Means the field isn’t required, used as default directly or called if callable

• hide_none (bool) – If the field’s value is None, it will be hidden from serialized output

• hide_zero (bool) – If the field’s value is 0, it will be hidden from serialized output

• primitive_name (Optional[str]) – Changes the key used to represent the field in serialized data - input or output

• to_primitive_name (Optional[str]) – Changes the key used to represent the field in serialized data - output only

• min_value (int | float | None) – Validation enforces the number is greater than or equal to this value

• max_value (int | float | None) – Validation enforces the number is lower than or equal to this value

• validators (Optional[List[Validator]]) – Optional list of validator callbacks - they raise ValueError if the value is invalid

class stereotype.FloatField(*, default: Any = Missing, hide_none: bool = False, hide_zero: bool = False, primitive_name: str | None = Missing, to_primitive_name: str | None = Missing, min_value: float | None = None, max_value: float | None = None, validators: List[Callable[[Any, Any], None]] | None = None)

Floating point value (annotation float), accepting float values, integers or strings with float values.

Parameters:

• default (Any) – Means the field isn’t required, used as default directly or called if callable

• hide_none (bool) – If the field’s value is None, it will be hidden from serialized output

• hide_zero (bool) – If the field’s value is 0.0, it will be hidden from serialized output

• primitive_name (Optional[str]) – Changes the key used to represent the field in serialized data - input or output

• to_primitive_name (Optional[str]) – Changes the key used to represent the field in serialized data - output only

• min_value (int | float | None) – Validation enforces the number is greater than or equal to this value

• max_value (int | float | None) – Validation enforces the number is lower than or equal to this value

• validators (Optional[List[Validator]]) – Optional list of validator callbacks - they raise ValueError if the value is invalid

class stereotype.StrField(*, default: Any = Missing, hide_none: bool = False, hide_empty: bool = False, primitive_name: str | None = Missing, to_primitive_name: str | None = Missing, min_length: int = 0, max_length: int | None = None, choices: Iterable[str] | None = None, regex: str | re.Pattern | None = None, validators: List[Validator] | None = None)

String value (annotation str), accepting string values, or anything that can be cast to a string.

Parameters:

• default (Any) – Means the field isn’t required, used as default directly or called if callable

• hide_none (bool) – If the field’s value is None, it will be hidden from serialized output

• hide_empty (bool) – If the field’s value is an empty string, it will be hidden from serialized output

• primitive_name (Optional[str]) – Changes the key used to represent the field in serialized data - input or output

• to_primitive_name (Optional[str]) – Changes the key used to represent the field in serialized data - output only

• min_length (int) – Validation enforces the string has a minimum number of characters (1 => non-empty)

• max_length (Optional[int]) – Validation enforces the string has a maximum number of characters

• choices (Optional[Iterable[str]]) – Validation enforces the string matches (case-sensitive) one of these choices

• regex (str | re.Pattern | None) – Validation enforces the string matches the regular expression

• validators (Optional[List[Validator]]) – Optional list of validator callbacks - they raise ValueError if the value is invalid

class stereotype.ListField(item_field: Field = NotImplemented, *, default: Any = Missing, hide_none: bool = False, hide_empty: bool = False, primitive_name: str | None = Missing, to_primitive_name: str | None = Missing, min_length: int = 0, max_length: int | None = None, validators: List[Callable[[Any, Any], None]] | None = None)

List value (annotation typing.List), accepting lists of the inner type.

Parameters:

• item_field (Field) – Optionally allows specifying further options for the type of the list’s items

• default (Any) – Means the field isn’t required, should be None, [] or a callable, for example list

• hide_none (bool) – If the field’s value is None, it will be hidden from serialized output

• hide_empty (bool) – If the list is empty, it will be hidden from serialized output

• primitive_name (Optional[str]) – Changes the key used to represent the field in serialized data - input or output

• to_primitive_name (Optional[str]) – Changes the key used to represent the field in serialized data - output only

• min_length (int) – Validation enforces the list has a minimum number of items (1 => non-empty)

• max_length (Optional[int]) – Validation enforces the list has a maximum number of items

• validators (Optional[List[Validator]]) – Optional list of validator callbacks - they raise ValueError if the value is invalid

class stereotype.DictField(key_field: Field = NotImplemented, value_field: Field = NotImplemented, *, default: Any = Missing, hide_none: bool = False, hide_empty: bool = False, primitive_name: str | None = Missing, to_primitive_name: str | None = Missing, min_length: int = 0, max_length: int | None = None, validators: List[Callable[[Any, Any], None]] | None = None)

Dict value (annotation typing.Dict), accepting dicts with applicable keys and values.

Parameters:

• key_field (Field) – Optionally allows specifying further options for the type of the dict’s keys

• value_field (Field) – Optionally allows specifying further options for the type of the dict’s values

• default (Any) – Means the field isn’t required, should be None, {} or a callable, for example dict

• hide_none (bool) – If the field’s value is None, it will be hidden from serialized output

• hide_empty (bool) – If the dict is empty, it will be hidden from serialized output

• primitive_name (Optional[str]) – Changes the key used to represent the field in serialized data - input or output

• to_primitive_name (Optional[str]) – Changes the key used to represent the field in serialized data - output only

• min_length (int) – Validation enforces the dict has a minimum number of items (1 => non-empty)

• max_length (Optional[int]) – Validation enforces the dict has a maximum number of items

• validators (Optional[List[Validator]]) – Optional list of validator callbacks - they raise ValueError if the value is invalid

class stereotype.ModelField(*, default: Any = Missing, hide_none: bool = False, hide_empty: bool = False, primitive_name: str | None = Missing, to_primitive_name: str | None = Missing, validators: List[Callable[[Any, Any], None]] | None = None)

Field containing another specific Model, as specified in the annotation.

Parameters:

• default (Any) – Means the field isn’t required, should be None or a callable, for example the model’s class

• hide_none (bool) – If the field’s value is None, it will be hidden from serialized output

• hide_empty (bool) – If the model serializes as an empty dict, it will be hidden from serialized output

• primitive_name (Optional[str]) – Changes the key used to represent the field in serialized data - input or output

• to_primitive_name (Optional[str]) – Changes the key used to represent the field in serialized data - output only

• validators (Optional[List[Validator]]) – Optional list of validator callbacks - they raise ValueError if the value is invalid

class stereotype.DynamicModelField(*, default: Any = Missing, hide_none: bool = False, primitive_name: str | None = Missing, to_primitive_name: str | None = Missing, validators: List[Callable[[Any, Any], None]] | None = None)

Field containing one of models recognized by their type, specified as a typing.Union of Model subclasses.

Parameters:

• default (Any) – Means the field isn’t required, should be None or a callable, for example a model’s class

• hide_none (bool) – If the field’s value is None, it will be hidden from serialized output

• primitive_name (Optional[str]) – Changes the key used to represent the field in serialized data - input or output

• to_primitive_name (Optional[str]) – Changes the key used to represent the field in serialized data - output only

• validators (Optional[List[Validator]]) – Optional list of validator callbacks - they raise ValueError if the value is invalid

class stereotype.AnyField(*, deep_copy: bool = False, default: Any = Missing, hide_none: bool = False, primitive_name: str | None = Missing, to_primitive_name: str | None = Missing, validators: List[Callable[[Any, Any], None]] | None = None)

Value of any type (usually annotation typing.Any, but can be anything).

Parameters:

• deep_copy (bool) – If true, conversion, serialization and copying will use copy.deepcopy for this value

• default (Any) – Means the field isn’t required, used as default directly or called if callable

• hide_none (bool) – If the field’s value is None, it will be hidden from serialized output

• primitive_name (Optional[str]) – Changes the key used to represent the field in serialized data - input or output

• to_primitive_name (Optional[str]) – Changes the key used to represent the field in serialized data - output only

• validators (Optional[List[Validator]]) – Optional list of validator callbacks - they raise ValueError if the value is invalid

serializable & SerializableField

stereotype.serializable(func: Callable[[Model], Any] | None = None, *, hide_none: bool = False, to_primitive_name: str = Missing)

Decorator that turns properties or methods to output-only fields that are calculated from other fields.

Will automatically produce a SerializableField.

Parameters:

• func (Optional[Callable[[Model], Any]]) – The Model method or property to be converted to a serializable

• hide_none (bool) – If the field’s calculated value is None, it will be hidden from serialized output

• to_primitive_name (str) – Changes the key used to represent the field in serialized data - output only

class stereotype.SerializableField(func: Callable[[Model], Any] = Missing, *, hide_none: bool = False, to_primitive_name: str = Missing)