modelity.visitors

Built-in implementations of the modelity.interface.IModelVisitor interface.

Added in version 0.17.0.

class modelity.visitors.DumpVisitor(out: dict)

Bases: EmptyVisitor

Visitor that dumps model to dict without type narrowing or any kind of value formatting.

It basically produces same structure as the model has, but based on Python collection types (dicts, lists, tuples and sets) instead of Modelity built-in ones.

Important

This visitor assumes that use of its API is done by modelity.model.Model.accept() method that keeps the right order of method calling. It may not work correctly if used manually.

Added in version 0.31.0.

__abstractmethods__ = frozenset({})

__init__(out: dict)

visit_any(loc: Loc, value: Any)

Visit any value.

This is called for values from untyped containers, fields marked with typing.Any or typed containers where typing.Any is used as a type hint.

This method, unlike visit_scalar(), can also be called with elements that are containers, not scalars.

Implementations are responsible for deciding whether to recurse into the value if it is a container.

Parameters:

loc – The location of the visited value.
value – The visited value.

visit_mapping_begin(loc: Loc, value: Mapping)

Start visiting a mapping object.

Parameters:

loc – The location of the visited mapping object.
value – The visited mapping object.

visit_mapping_end(loc: Loc, value: Mapping)

Finish visiting a mapping object.

Parameters:

loc – The location of the visited mapping object.
value – The visited mapping object.

visit_model_begin(loc: Loc, value: Model)

Start visiting model object.

Parameters:

loc – The location of the visited model.
value – The visited model object.

visit_model_end(loc: Loc, value: Model)

Finish visiting model object.

Parameters:

loc – The location of the visited model.
value – The visited model object.

visit_none(loc: Loc, value: None)

Visit a None value.

Called when None object is found.

Parameters:

loc – The location of the visited value.
value – The visited value.

visit_scalar(loc: Loc, value: Any)

Visit scalar object.

Scalars are primitive objects that are neither containers, nor model objects. All Python primitive types (ints, floats, strings, booleans, enums, datetimes etc.) are scalars from the Modelity point of view.

Parameters:

loc – The location of the visited value.
value – The visited value.

visit_sequence_begin(loc: Loc, value: Sequence)

Start visiting a sequence object.

Parameters:

loc – The location of the visited sequence object.
value – The visited sequence object.

visit_sequence_end(loc: Loc, value: Sequence)

Finish visiting a sequence object.

Parameters:

loc – The location of the visited sequence object.
value – The visited sequence object.

visit_set_begin(loc: Loc, value: Set)

Start visiting a set object.

Parameters:

loc – The location of the visited set object.
value – The visited set object.

visit_set_end(loc: Loc, value: Set)

Finish visiting a set object.

Parameters:

loc – The location of the visited set object.
value – The visited set object.

visit_unset(loc: Loc, value: UnsetType)

Visit an Unset value.

Called when modelity.unset.Unset object is found.

Parameters:

loc – The location of the visited value.
value – The visited value.

class modelity.visitors.EmptyVisitor

Bases: ModelVisitor

A visitor that simply implements modelity.interface.IModelVisitor interface with methods doing nothing.

It is meant to be used as a base for other visitors, especially ones that do not need to overload all methods.

Changed in version 0.34.0: Restored the whole set of modelity.interface.IModelVisitor interface methods to get rid of linter warnings in subclasses.

__abstractmethods__ = frozenset({})

visit_any(loc: Loc, value: Any)

Visit any value.

This is called for values from untyped containers, fields marked with typing.Any or typed containers where typing.Any is used as a type hint.

This method, unlike visit_scalar(), can also be called with elements that are containers, not scalars.

Implementations are responsible for deciding whether to recurse into the value if it is a container.

Parameters:

loc – The location of the visited value.
value – The visited value.

visit_mapping_begin(loc: Loc, value: Mapping) → bool | None

Start visiting a mapping object.

Parameters:

loc – The location of the visited mapping object.
value – The visited mapping object.

visit_mapping_end(loc: Loc, value: Mapping)

Finish visiting a mapping object.

Parameters:

loc – The location of the visited mapping object.
value – The visited mapping object.

visit_model_begin(loc: Loc, value: Model) → bool | None

Start visiting model object.

Parameters:

loc – The location of the visited model.
value – The visited model object.

visit_model_end(loc: Loc, value: Model)

Finish visiting model object.

Parameters:

loc – The location of the visited model.
value – The visited model object.

visit_model_field_begin(loc: Loc, value: Any, field: Field) → bool | None

Start visiting model field.

This is called for every field in a model no matter if the field is set or not.

Parameters:

loc – The location of the visited value.
value – The visited field value.
field – The visited field metadata.

visit_model_field_end(loc: Loc, value: Any, field: Field)

Finish visiting model field.

Parameters:

loc – The location of the visited value.
value – The visited field value.
field – The visited field metadata.

visit_none(loc: Loc, value: None)

Visit a None value.

Called when None object is found.

Parameters:

loc – The location of the visited value.
value – The visited value.

visit_scalar(loc: Loc, value: Any)

Visit scalar object.

Scalars are primitive objects that are neither containers, nor model objects. All Python primitive types (ints, floats, strings, booleans, enums, datetimes etc.) are scalars from the Modelity point of view.

Parameters:

loc – The location of the visited value.
value – The visited value.

visit_sequence_begin(loc: Loc, value: Sequence) → bool | None

Start visiting a sequence object.

Parameters:

loc – The location of the visited sequence object.
value – The visited sequence object.

visit_sequence_end(loc: Loc, value: Sequence)

Finish visiting a sequence object.

Parameters:

loc – The location of the visited sequence object.
value – The visited sequence object.

visit_set_begin(loc: Loc, value: Set) → bool | None

Start visiting a set object.

Parameters:

loc – The location of the visited set object.
value – The visited set object.

visit_set_end(loc: Loc, value: Set)

Finish visiting a set object.

Parameters:

loc – The location of the visited set object.
value – The visited set object.

visit_unset(loc: Loc, value: UnsetType)

Visit an Unset value.

Called when modelity.unset.Unset object is found.

Parameters:

loc – The location of the visited value.
value – The visited value.

class modelity.visitors.FixupVisitor(root: Model, ctx: Any = None)

Bases: EmptyVisitor

Visitor performing model fixups.

It is implicitly used by modelity.helpers.fixup() helper.

Added in version 0.36.0.

__abstractmethods__ = frozenset({})

__init__(root: Model, ctx: Any = None) → None

visit_model_end(loc: Loc, value: Model)

Finish visiting model object.

Parameters:

loc – The location of the visited model.
value – The visited model object.

class modelity.visitors.JsonDumpVisitorProxy(target: ModelVisitor, /, exclude_unset: bool = False, exclude_none: bool = False, bytes_format: str | Literal['base64'] = 'utf-8', datetime_format: str = 'YYYY-MM-DDThh:mm:ss.ffffffZZZZ', date_format: str = 'YYYY-MM-DD', default_encoder: Callable[[Loc, Any], Any] | None = None)

Bases: object

Proxy visitor that narrows down value types to closest JSON-compatible type: dict, list, str, int, float, bool or None.

Added in version 0.31.0.

Parameters:

target – Target dump visitor, e.g. DumpVisitor object.
exclude_unset – Exclude model fields equal to modelity.unset.Unset object.
exclude_none –
Exclude model fields equal to None.

This does not affect None values used in nested containers, only model fields, typed with e.g. Optional[T], are affected.
bytes_format –
The format used to encode bytes objects.

Supports either encoding name (f.e. utf-8 or ascii) or one of predefined encodings (f.e. base64).
datetime_format –
The format to use to encode datetime.datetime objects.

Following placeholders are supported:
- YYYY for 4-digit years
- MM for 2-digit months in range [01..12]
- DD for 2-digit days in range [01..31]
- hh for 2-digit hours in range [00..23]
- mm for 2-digit minutes in range [00..59]
- ss for 2-digit seconds in range [00..59]
- ffffff for 6-digit microseconds in range [000000..999999]
- ZZZZ for timezone
date_format –
The format to use to encode datetime.date objects.

Following placeholders are supported:
- YYYY for 4-digit years
- MM for 2-digit months in range [01..12]
- DD for 2-digit days in range [01..31]
default_encoder –
The default encoder to use if there is no dedicated type encoder found.

If not given, then str is used as a default.

Changed in version 0.34.0: Parameter was renamed from default_converter.

__getattr__(name)

__init__(target: ModelVisitor, /, exclude_unset: bool = False, exclude_none: bool = False, bytes_format: str | Literal['base64'] = 'utf-8', datetime_format: str = 'YYYY-MM-DDThh:mm:ss.ffffffZZZZ', date_format: str = 'YYYY-MM-DD', default_encoder: Callable[[Loc, Any], Any] | None = None)

register_type_encoder(typ: type[T], func: Callable[[Loc, T], Any])

Register or override type encoder.

Important

Only model field values, nested model instances or container elements encoding can be customized using this method. Containers like dicts, sets or lists cannot be customized.

Added in version 0.34.0.

Parameters:

typ – The type to set converter function for.
func –
The conversion function.

Takes (loc, value) as input and returns encoded value.

visit_any(loc: Loc, value: Any)

visit_model_begin(loc: Loc, value: Model)

visit_none(loc: Loc, value: None)

visit_scalar(loc: Loc, value: Any)

visit_sequence_begin(loc: Loc, value: Sequence)

visit_sequence_end(loc: Loc, value: Sequence)

visit_set_begin(loc: Loc, value: Set)

visit_set_end(loc: Loc, value: Set)

visit_unset(loc: Loc, value: UnsetType)

class modelity.visitors.ModelFieldPruningVisitorProxy(target: ModelVisitor, /, exclude_if: Callable[[Loc, Any], bool])

Bases: object

Visitor proxy that skips model fields if provided exclude function returns True.

Important

This proxy only skips model fields and does not affect container elements in any way.

Parameters:

target – The wrapped model visitor.
exclude_if –
The exclusion function.

Takes (loc, value) as arguments and must return True to skip the matched model field or False to leave it.

__getattr__(name)

__init__(target: ModelVisitor, /, exclude_if: Callable[[Loc, Any], bool])

visit_model_field_begin(loc: Loc, value: Any, field: Field) → bool | None

class modelity.visitors.ValidationVisitor(root: Model, errors: list[Error], ctx: Any = None)

Bases: EmptyVisitor

Visitor that performs model validation.

Added in version 0.31.0: Replaced DefaultValidationVisitor used earlier.

Parameters:

root – The root model.
errors –
The list of errors.

Will be populated with validation errors (if any).
ctx –
User-defined validation context.

It is shared across all validation hooks and can be used as a source of external data needed during validation but not directly available in the model.

__abstractmethods__ = frozenset({})

__init__(root: Model, errors: list[Error], ctx: Any = None)

visit_any(loc: Loc, value: Any)

Visit any value.

This is called for values from untyped containers, fields marked with typing.Any or typed containers where typing.Any is used as a type hint.

This method, unlike visit_scalar(), can also be called with elements that are containers, not scalars.

Implementations are responsible for deciding whether to recurse into the value if it is a container.

Parameters:

loc – The location of the visited value.
value – The visited value.

visit_mapping_end(loc: Loc, value: Mapping)

Finish visiting a mapping object.

Parameters:

loc – The location of the visited mapping object.
value – The visited mapping object.

visit_model_begin(loc: Loc, value: Model)

Start visiting model object.

Parameters:

loc – The location of the visited model.
value – The visited model object.

visit_model_end(loc: Loc, value: Model)

Finish visiting model object.

Parameters:

loc – The location of the visited model.
value – The visited model object.

visit_model_field_begin(loc: Loc, value: Any, field: Field)

Start visiting model field.

This is called for every field in a model no matter if the field is set or not.

Parameters:

loc – The location of the visited value.
value – The visited field value.
field – The visited field metadata.

visit_model_field_end(loc: Loc, value: Any, field: Field)

Finish visiting model field.

Parameters:

loc – The location of the visited value.
value – The visited field value.
field – The visited field metadata.

visit_none(loc: Loc, value: None)

Visit a None value.

Called when None object is found.

Parameters:

loc – The location of the visited value.
value – The visited value.

visit_scalar(loc: Loc, value: Any)

Visit scalar object.

Scalars are primitive objects that are neither containers, nor model objects. All Python primitive types (ints, floats, strings, booleans, enums, datetimes etc.) are scalars from the Modelity point of view.

Parameters:

loc – The location of the visited value.
value – The visited value.

visit_sequence_end(loc: Loc, value: Sequence)

Finish visiting a sequence object.

Parameters:

loc – The location of the visited sequence object.
value – The visited sequence object.

visit_set_end(loc: Loc, value: Set)

Finish visiting a set object.

Parameters:

loc – The location of the visited set object.
value – The visited set object.