modelity.helpers

class modelity.helpers.ModelLoader(model_type: type[MT], ctx: Any = None)

Bases: Generic[MT]

Similar to load() function, but allows to create loader for given model type and then create instances of that model using keyword args.

Example use:

from modelity.base import Model
from modelity.helpers import ModelLoader

class Dummy(Model):
    a: int
    b: str

DummyLoader = ModelLoader(Dummy)

>>> one = DummyLoader(a=1, b="spam")
>>> one
Dummy(a=1, b='spam')

Added in version 0.17.0.

Parameters:

  • model_type – The model type.

  • ctx – The user-defined validation context.

__call__(**kwargs) → MT

Create and validate instance of the given model type.

On success, valid model instance is returned.

On failure, modelity.exc.ModelError exception is raised.

Parameters:

**kwargs – Named arguments for model’s constructor.

__init__(model_type: type[MT], ctx: Any = None)
__orig_bases__ = (typing.Generic[~MT],)
__parameters__ = (~MT,)
modelity.helpers.dump(model: Model, /, exclude_unset: bool = False, exclude_none: bool = False, exclude_if: Callable[[Loc, Any], bool] | None = None, datetime_format: str = 'YYYY-MM-DDThh:mm:ss.ffffffZZZZ', date_format: str = 'YYYY-MM-DD') → dict

Serialize given model to a dict.

This helper is designed to handle most common dump scenarios, like skipping unset fields or optional field set to None. More advanced behavior can be achieved by implementing custom modelity.interface.IModelVisitor interface and running modelity.model.Model.accept() method directly.

Parameters:

  • model – The model to serialize.

  • exclude_unset – Exclude unset fields.

  • exclude_none – Exclude fields set to None.

  • exclude_if –

    Conditional function executed for every model location and value.

    Should return True to drop the value from resulting dict, or False to leave it. Can be used to achieve exclusion based on location and/or value.

  • datetime_format –

    The format to use for datetime.datetime objects.

    Added in version 0.31.0.

  • date_format –

    The format to use for datetime.date objects.

    Added in version 0.31.0.

modelity.helpers.fixup(model: Model, ctx: Any = None)

Perform fixup on given model.

This helper runs all modelity.hooks.model_fixup() hooks defined for a model and also recurses into nested models. Performing fixup allows to run some post-parsing and pre-validation user-defined logic to fill in the model with derived or missing information.

Parameters:

  • model – The model to fixup.

  • ctx –

    The user-defined context object to be shared by all fixup hooks.

    Can be used to pass some additional data to model, like results of API calls etc.

Changed in version 0.37.0: Added ctx argument.

Added in version 0.36.0.

modelity.helpers.has_fields_set(model: Model) → bool

Check if model has at least one field set.

Parameters:

model – The model object.

modelity.helpers.load(model_type: type[MT], data: dict, ctx: Any = None) → MT

Parse and validate given raw data using provided model type.

This is a helper function meant to be used to create models from data that is coming from an untrusted source, like API request, JSON file etc.

On success, this function returns new instance of the given model_type.

On failure, this function raises modelity.exc.ModelError.

Here’s an example:

from modelity.base import Model
from modelity.helpers import load

class Example(Model):
    foo: int
    bar: int

>>> untrusted_data = {"foo": "123", "bar": "456"}
>>> example = load(Example, untrusted_data)
>>> example
Example(foo=123, bar=456)
Parameters:

  • model_type – The model type to parse data with.

  • data – The data to be parsed.

  • ctx – The user-defined validation context.

modelity.helpers.validate(model: Model, ctx: Any = None)

Validate provided model.

On success, this method raises no exception and returns None.

On failure, modelity.exc.ValidationError exception is raised.

Parameters:

  • model – The model to validate.

  • ctx – The user-defined validation context.