About

This documentation covers the models system of {typed} which is used specifically to data validation.

Overview
Model Factories
Validation Conditions
Model Types
Defining Models
Decorators
Universal Decorator
Data Validation
Optional Attributes
Optional Decorator
Mandatory Attributes
Model Extension
Filtering Models
Model Attributes
Model Operations
Other Docs

Overview

The models system is defined in the typed.models module, such that:

it provides model factories, which are type factories constructing models;
the difference between the kinds of model factories is how data is validated in instances of their models;
each model factory has a corresponding model type, consisting of all its models;
the process of creating models is compatible with other sources of data validation structures, as Python dataclasses and pydantic BaseModel.

Model Factories

Recall that in {typed} we have type factories, which are functions that return a type, hence that take values into the metatype TYPE of all types. Recall, yet, that we have a primitive type Json.

In a very general perspective, a model factory is a type factory such that:

it has only keyword arguments;
the value of each kwarg is a type;
the key of each kwarg defines an attribute in the returning type;
its returning type is a subtype of Json.

In other words, a type factory is a function ModelFactory: Dict(TYPE) -> TYPE such that:

model = ModelFactory(**kwargs) is a subtype of Json
model.key is defined for each key in kwargs.

We have the following model factories:

model factory	description
Model	the factory of _basic_ modes
Exact	the factory of _strict_ models
Ordered	the factory of _ordered_ models
Rigid	the factory of _rigid_ models

table 1: model factories

Validation Conditions

In {typed}, a model is precisely a type which is constructed from a model factory. In other words, it is an instance model = ModelFactory(**kwargs) for some ModelFactory listed above, and some kwargs in Dict(TYPE).

The difference between the model factories is precisely how their models are validated.

More precisely, since the model factories produces subtypes of Json, it follows that if isinstance(x, model) is True, then x is a Json data. Each key in kwargs corresponds to an attribute of model, which, in turn, corresponds to an entry in each instance x of model, when viewed as a Json datas. The different flavors of model factories deals, precisely, with the reciprocal question:

Take a model factory ModelFactory. Then, given an object x such that isinstance(x, Json) is True, which conditions x should satisfy such that isinstance(x, model) is True for model = ModelFactory(**kwargs) for some kwargs in Dict(TYPE)?

The answers for each question are in the following table:

model factory	validation condition
Model	the json data contains at least the defined attributes
Exact	the json data contains precisely the defined attributes
Ordered	the json data contains at least the defined attributes, but in the same ordering
Rigid	the json data contains precisely the defined attributes, and in the same ordering

table 2: validation conditions

Model Types

Each model factory defines a type whose instances are its models:

model factory	models type
Model	MODEL
Exact	EXACT
Ordered	ORDERED
Rigid	RIGID

table 3: model types

So, isinstance(x, MODEL) is True iff isinstance(x, TYPE) is True, and x = Model(**kwargs) for some dictionary kwargs of type Dict(TYPE). Analogously for the other model factories and model types.

Defining Models

Let ModelFactory be a generic model factory, i.e, some of that in table 1. The typical way to define a model for it, is as follows:

from typed import SomeType, OtherType, ...
from typed.models import ModelFactory

MyModel = ModelFactory(
    some_attr: SomeType,
    other_attr: OtherType,
    ...
)

So, for example, we define an instance of the model type MODEL as below (and Analogously for the other model factories and model types):

from typed import SomeType, OtherType, ...
from typed.models import Model

MyModel = Model(
    some_attr: SomeType,
    other_attr: OtherType,
    ...
)

print(isinstance(MyModel, MODEL)) # returns True

Decorators

There is another way to define models, which is using the model decorators. Indeed, to each model factory there corresponds a namesake decorator, named in lowercase:

model factor	decorator
Model	@model
Exact	@exact
Ordered	@ordered
Rigid	@rigid

table 4: model decorators

The decorators can be applied to any class. This will generate a model of the corresponding model type, based on the attributes of the given class. This can be used to quickly create models, as follows (same for other model types by making use of other model decorators):

from typed import SomeType, OtherType, ...
from typed.models import model

@model
class MyModel:
    some_attr: SomeType
    other_attr: OtherType
    ...

This approach can also be used to convert models from other sources into {typed} models. In particular, this can be used to generate {typed} models from pydantic models and from Python dataclasses.

The approach of creating {typed} models from model decorators is recommended. Indeed, while created directly from a model factory, the model a fully dynamically entity. This means that a LSP will not collect its attributes. On the other hand, while using the model decorators, they are applied to static classes, whose attributes are recognized by LSPs, providing a better developing experience.

Universal Decorator

Actually, one can use @model as an “universal decorator”, in the sense that one can reconstruct the behavior of the other model decorators from it. Indeed, @model contains boolean variables, as below, which, when set, introduce the corresponding decorator in the model construction.

variable	model decorator
exact	@exact
ordered	@ordered
rigid	@rigid

table 5: variables in @model

For example, one could create an exact model as follows:

from typed import SomeType, OtherType, ...
from typed.models import model

@model(exact=True)
def MyModel:
    some_attr: SomeType
    other_attr: OtherType
    ...

print(isinstance(MyModel, EXACT)) # prints True

Data Validation

One time defined a model, one can use it to:

validate existing Json data;
create already validated Json data.

Indeed, suppose we have a given json_data. The validation can be realized by calling the model with the given Json data:

json_data = {
    "some_attr": some_value,
    "other_attr": other_value
    ...
}

validated_data = MyModel(**json_data)

Another way of validating a predefined json_data is through the Validate function:

from typed.models import Validate

validated_data = Validate(
    model=MyModel,
    data=json_data
)

The simplest way to create validated data is to call the model with specified kwargs:

validated_data = MyModel(
    some_attr=some_value,
    other_attr=other_value,
    ...
)

Independently of the case, if some condition used in the definition of the model MyModel is not satisfied, a TypeError will be raised.

For more on the {typed} error messages, see errors.

Optional Attributes

In the moment of the definition of a model, one can determine certain attributes as optional. If the model is defined from a model factory, this can be done my making use of the Optional: TYPE x Any -> TYPE directive, which receives an attribute and a default value:

from typed import SomeType, OtherType, OptType
from typed.models import ModelFactory, Optional

MyModel = ModelFactory(
    some_attr=SomeType,
    other_attr=OtherValue,
    opt_atrr=Optional(OptType, default_value),
    ...
)

Then, in the validation of some json_data through the model MyModel, if there is no entry named opt_attr, the validated data will be appended with such entry with value given by default_value.

The directive Optional also accept to do not pass a default value, i.e, it accepts a single argument Optional(OptType). In this case:

First it will be checked if passed type OptType is nullable. In this case, Optional(OptType) will return Optional(OptType, null(OptType)), i.e, the null object of OptType will be set as the default argument.
If OptType is not nullable, it will be checked if it can be initialized. In this case, Optional(OptType) will return Optional(OptType, OptType()).
Finally, if not of the above conditions are satisfied, then None will be set as the default value. More precisely, Optional(OptType) will return Optional(Maybe(OptType), None).

In the definition of a model from a model decorator, an optional attribute can be defined by just setting a default value, or by making use of the Optional directive:

from typed import SomeType, OtherType, OptType
from tped.models import model, Optional

@model
class MyModel:
    some_attr: SomeType
    other_attr: OtherType
    opt_attr: OptType=default_value
    ...

@model
class MyModel:
    some_attr: SomeType
    other_attr: OtherType
    opt_attr: Optional(OptType, default_value)
    ...

The difference, here, is that you can customize the behavior of passing a single argument to Optional through the variable nullable. Indeed, if nullable=False in the model decorator, then Optional(OptType) will return Optional(Maybe(OptType), None) directly, without checking for nullability conditions for OptType.

Optional Decorator

Some times you want to define a model such that every attribute is optional. These are the so-called optional models and define a type OPTIONAL. You can quickly create an optional model by making use of the @optional decorator:

from typed import SomeType, OtherType
from typed.models import optional

@optional
class MyModel:
    some_attr: SomeType
    other_attr: OtherType=default_value
    ...

print(isinstance(MyModel, OPTIONAL)) # returns True

The above is equivalent to:

from typed import SomeType, OtherType
from typed.models import model, Optional

@model
class MyModel:
    some_attr: Optional(SomeType)
    other_attr: Optional(OtherType, default_value)
    ...

While using @optional, you can control the behavior of the single argument case of Optional by making use of the variable nullable. In other words, @optional(nullable=False) implements the above, but with @model(nullable=False).

You can also use optional not to define an optional model, but to turn an already existing model into an optional model:

from typed import optional
from some.where import MyModel

OptionalModel = optional(MyModel, nullable=False).

print(isinstance(MyModel, OPTIONAL)) # returns True

The decorator @optional preserves the model type. Indeed, if isinstance(MyModel, EXACT) is True, then isinstance(optional(MyModel), EXACT) is True as well, and similarly for the other model types.

Mandatory Attributes

If an attribute in a model is not optional, it is mandatory. A model in which every attribute is mandatory is a mandatory model, which constitute a type MANDATORY.

Analogously to the optional case, there is a decorator @mandatory. If used in the creation of a model, it ignores any introduction of the Optional directive or any default value:

from typed import SomeType, OtherType, AnotherType
from typed.models import mandatory

@mandatory
class MyModel:
    some_attr: SomeType
    other_attr: OtherType=default_value
    another_attr: Optional(AnotherType)
    ...

print(isinstance(MyModel, MANDATORY)) # returns True

The above is equivalent to:

from typed import SomeType, OtherType
from typed.models import model

@model
class MyModel:
    some_attr: SomeType
    other_attr: OtherType
    another_attr: AnotherType
    ...

The function @mandatory can also be used to turn any already existing model into a mandatory model preserving its model type:

from typed import mandatory
from some.where import MyModel

OptionalModel = mandatory(MyModel).

print(isinstance(MyModel, MANDATORY)) # returns True

In the above, if isinstance(MyModel, EXACT) is True, then isinstance(optional(MyModel), EXACT) is True as well, and similarly for the other model types.

Model Extension

A model can be created extending other models. This ensures that the new model have at least the attributes that are defined in the model is extended. This is the inheritance behavior of models.

While defining a new model from a model factory, the models that are being extended can be listed in a __extends__ variable in the factory:

from typed import SomeType, OtherType, ...
from typed.models import ModelFactory
from some.where import SomeModel, OtherModel, ...

MyModel = ModelFactory(
    __extends__=[SomeModel, OtherModel, ...],
    some_attr=SomeType,
    other_attr=OtherType,
    ...
)

In the case of using model decorators, the extended models are passed in the variable extends (in the example below, the same works for other model decorators):

from typed import SomeType, OtherType, ...
from typed.models import model
from some.where import SomeModel, OtherModel, ...

@model(extends=[SomeModel, OtherModel, ...])
class MyModel:
    some_attr=SomeType,
    other_attr=OtherType,
    ...

The variables __extends__ and extends accept not only List(MODEL) type, but also other iterative types based on some model type, as Tuple(MODEL), Set(MODEL) or even just MODEL if a single model will be extended.

Filtering Models

Model Attributes

The model types MODEL, EXACT, and so on, have certain properties, which define corresponding attributes to their models: the so-called model attributes. They are described below:

attribute	meaning
.is_model	True for MODEL instances
.is_exact	True for EXACT instances
.is_ordered	True for ORDERED instances
.is_rigid	True for RIGID instances
.attrs	dict of all attributes
.optional_attrs	dict of optional attributes
.mandatory_attrs	dict of mandatory attributes

table 6: model attributes

Model Operations

… TBA …