Model

Models are classes that represent structures (dicts) with well-defined keys within your data. They allow converting raw (JSON-serializable) data to nice classes, validate the inputs and can be serialized back to raw data, optionally omitting fields or adding defaults and calculated fields.

class stereotype.Model(raw_data: dict | None = None)

The base class for all your models.

May inherit from other models, but if inheriting from multiple Models, all but one of the bases must be marked as abstract by adding the attribute __abstract__ = True.

Class attributes will become fields (deserialized, validated, serialized) if they:

• are a public attribute (i.e. not prefixed with _)

• they have a type hint, unless that type hint is wrapped in ClassVar

copy(deep: bool = False) → Model

Creates an optionally deep copy of this model.

Return type:

Model

classmethod declare_roles() → Iterable[RequestedRoleFields]

Override to specify which fields are serialized for particular roles.

Define a stereotype.Role globally, like: MY_ROLE = Role('my')

Then in this class method do for example: yield MY_ROLE.blacklist(cls.my_field)

Return type:

Iterable[RequestedRoleFields]

classmethod field_names_for_role(role: ~stereotype.roles.Role = <Role default>) → List[str]

Lists the field names (using primitive names, as in serialized data) present for a given role.

Parameters:

role (Role) – The Role that controls which fields are present

Return type:

List[str]

classmethod fields_for_role(role: ~stereotype.roles.Role = <Role default>) → List[Field]

Lists fields present in output for a given role. Omits those suppressed by roles or None primitive_name.

Parameters:

role (Role) – The Role that controls which fields are present

Return type:

List[Field]

get(key, default=None)

Returns a value of a field with the given key, or the provided default if no such field exists or a required field is missing value.

items() → Iterable[Tuple[str, Any]]

Provides an iterator over the fields of this model, with field name and converted value pairs.

Return type:

Iterable[Tuple[str, Any]]

classmethod resolve_extra_types() → Set[Type[Model]]

Override to provide a set of symbols that are not available globally in this model’s module, such as locally declared other models or models that cannot be imported globally and use if TYPE_CHECKING. Simply return any such model classes in this class method, importing them locally if needed.

If inheriting from a Model that implements this, use return {...} | super().resolve_extra_types()

Return type:

Set[Type[Model]]

serialize(role: ~stereotype.roles.Role = <Role default>, context=None)

Creates raw data from this Model, creating a copy of the data it was initialized with.

Parameters:

• role (Role) – Can be used together with declare_roles to exclude fields for certain roles.

• context – Optional value opaque to stereotype, useful for serializing custom field types.

to_primitive(role: ~stereotype.roles.Role = <Role default>, context=None)

Creates raw data from this Model, creating a copy of the data it was initialized with.

Parameters:

• role (Role) – Can be used together with declare_roles to exclude fields for certain roles.

• context – Optional value opaque to stereotype, useful for serializing custom field types.

validate(context=None)

Validates data, raising a ValidationError with potentially multiple error messages, mapped by field paths.

Validation catches: fields without defaults missing in data, None in non-Optional fields and failing validators (whether native Field validation options or custom validate_* methods).

Parameters:

context – Optional value opaque to stereotype, passed to any custom validation methods (validate_*).

validation_errors(context=None) → Iterable[Tuple[Tuple[str, ...], str]]

Validates data, yielding errors one by one, each with a field path.

Validation catches: fields without defaults missing in data, None in non-Optional fields and failing validators (whether native Field validation options, custom Field validators or custom validate_* methods).

Parameters:

context – Optional value opaque to stereotype, passed to Field validators and validate_* Model methods.

Return type:

Iterable[Tuple[Tuple[str, …], str]]