modelity.error

class modelity.error.Error(loc: ~modelity.loc.Loc, code: str, msg: str, value: ~typing.Any = Unset, data: dict = <factory>)

Bases: object

Object containing details of the single error.

It is used for both parsing and validation stages of the model processing.

__eq__(other)

Return self==value.

__hash__ = None
__init__(loc: ~modelity.loc.Loc, code: str, msg: str, value: ~typing.Any = Unset, data: dict = <factory>) → None
__match_args__ = ('loc', 'code', 'msg', 'value', 'data')
__repr__()

Return repr(self).

code: str

Error code.

This is a short description of the error. Check ErrorCode for the list of Modelity built-in error code constants and their meaning.

data: dict

Additional error data.

This property, along with code, can be used to render custom error messages. It is recommended to always use same structure for same error code.

For built-in errors, this property will get filled with any extra arguments passed to factory functions defined in ErrorFactory class.

loc: Loc

Error location in the model.

msg: str

Formatted error message.

Contains human-readable error description based on code and data.

value: Any = Unset

The incorrect value, if present, or modelity.unset.Unset otherwise.

property value_type: type

The type of the incorrect value.

class modelity.error.ErrorCode

Bases: object

Class defining all built-in error codes.

CONVERSION_ERROR = 'modelity.CONVERSION_ERROR'

Used when it was not possible to automatically convert allowed input value type into expected type.

For example, a set cannot be created from list if the list contains unhashable elements.

Use by ErrorFactory.conversion_error() to create errors with this code.

DECODE_ERROR = 'modelity.DECODE_ERROR'

Used when bytes could not be decoded into string using any of the provided encoding.

Use ErrorFactory.decode_error() to create errors with this code.

EXCEPTION = 'modelity.EXCEPTION'

Used to wrap user exception caught during parsing or validation stage.

This error code is used to wrap TypeError (and its subclasses) raised during parsing stage or ValueError (and its subclasses) raised during validation stage by user-defined hook.

Use ErrorFactory.exception() to create errors with this code.

INVALID_DATETIME_FORMAT = 'modelity.INVALID_DATETIME_FORMAT'

Used when datetime field gets text input that has invalid datetime format.

Used ErrorFactory.invalid_datetime_format() to create errors with this code.

INVALID_DATE_FORMAT = 'modelity.INVALID_DATE_FORMAT'

Same as for INVALID_DATETIME_FORMAT, but for dates.

Use ErrorFactory.invalid_date_format() to create errors with this code.

INVALID_ENUM_VALUE = 'modelity.INVALID_ENUM_VALUE'

Similar to INVALID_VALUE, but used with enumerated values and enum.Enum type.

Use ErrorFactory.invalid_enum_value() to create errors with this code.

INVALID_LENGTH = 'modelity.INVALID_LENGTH'

Used to signal value length range errors.

Use invalid_length() to create errors with this code.

INVALID_STRING_FORMAT = 'modelity.INVALID_STRING_FORMAT'

Used to inform that the input value string has incorrect format.

For example, input expects data matching some regular expression pattern, but the input value does not match the pattern.

Use invalid_string_format() to create errors with this code.

INVALID_TUPLE_LENGTH = 'modelity.INVALID_TUPLE_LENGTH'

Used for fixed-length tuple types where input value is a tuple that does not have the exact number of elements.

Use ErrorFactory.invalid_tuple() to create errors with this code.

INVALID_TYPE = 'modelity.INVALID_TYPE'

Used when type of the input value does not match the expected type and it cannot be automatically converted.

Use ErrorFactory.invalid_type() to create errors with this code.

INVALID_VALUE = 'modelity.INVALID_VALUE'

Used when input value was not one of the expected values.

For example, field accepts literals Literal[1, 2, "3"], but the input was "2" which is not one of the allowed literals.

Use ErrorFactory.invalid_value() to create errors with this code.

NONE_NOT_ALLOWED = 'modelity.NONE_NOT_ALLOWED'

Reported during parsing of modelity.typing.StrictOptional wrapped fields if None is used as input value.

Strict optional fields require the field to either be set to instance of type T, or not set at all (unlike typing.Optional, which allows None). Modelity needs to provide such clean separation to make sure that model satisfies all type constraints after validation.

Important

This error is reserved for modelity.typing.StrictOptional wrapper and should not be used elsewhere.

Use ErrorFactory.none_not_allowed() to create errors with this code.

Added in version 0.29.0.

OUT_OF_RANGE = 'modelity.OUT_OF_RANGE'

Used to signal value range errors.

Use out_of_range() to create error with this code.

PARSE_ERROR = 'modelity.PARSE_ERROR'

Used when Modelity could not parse input value to an expected type.

For example, string “abc” cannot be parsed as integer number.

Use ErrorFactory.parse_error() to create errors with this code.

REQUIRED_MISSING = 'modelity.REQUIRED_MISSING'

Signals that the field is required but is not present in the model.

Use ErrorFactory.required_missing() to create errors with this code.

UNSET_NOT_ALLOWED = 'modelity.UNSET_NOT_ALLOWED'

Reported during validation for typing.Optional fields that remain unset during validation.

To allow usage of Unset please use modelity.typing.StrictOptional or modelity.typing.LooseOptional type wrappers. Check their docs for more details.

This error can be avoided by setting default values for optional fields.

Use ErrorFactory.unset_not_allowed() to create errors with this code.

Added in version 0.29.0.

USER_ERROR = 'modelity.USER_ERROR'

Default error code for the modelity.exc.UserError exception.

Added in version 0.30.0.

class modelity.error.ErrorFactory

Bases: object

Class grouping factory methods for creating built-in errors.

static conversion_error(loc: Loc, value: Any, expected_type: type, /, reason: str | None = None, *, msg: str | None = None, **extra_data) → Error

Create conversion error.

This signals that value could not be converted into instance of expected_type due to the reason explained in error message.

Important

This error is reserved only for failing conversion where input value is non-string. If input value is string or bytes then it is better to use parse_error() factory instead.

Parameters:

  • loc – Error location in the model.

  • value – Input value that could not be converted.

  • expected_type – Expected value type.

  • reason – The optional reason text.

  • msg –

    The optional message to override built-in one.

    Added in version 0.33.0.

  • **extra_data –

    The optional extra error data.

    This will be placed inside modelity.error.Error.data dict of a created error object.

    Added in version 0.33.0.

static decode_error(loc: Loc, value: bytes, expected_encodings: list[str], /) → Error

Create decode error.

Parameters:

  • loc – Error location in the model.

  • value – Input bytes that could not be decoded into string.

  • expected_encodings – List of expected encodings.

static exception(loc: Loc, value: Any, exc: Exception, /) → Error

Create error from a user exception.

Parameters:

  • loc – Error location in the model.

  • value – The incorrect value.

  • exc – The exception object.

static invalid_date_format(loc: Loc, value: str, expected_formats: list[str], /)

Create invalid date format error.

Parameters:

  • loc – Error location in the model.

  • value – Incorrect input string.

  • expected_formats – List with expected date formats.

static invalid_datetime_format(loc: Loc, value: str, expected_formats: list[str], /) → Error

Create invalid datetime format error.

Parameters:

  • loc – Error location in the model.

  • value – Incorrect input string.

  • expected_formats – List with expected datetime formats.

static invalid_enum_value(loc: Loc, value: Any, expected_enum_type: type[Enum], /) → Error

Create invalid enum value error.

Parameters:

  • loc – Error location in the model.

  • value – Input value from outside of expected enumerated values set.

  • expected_enum_type – Expected enum type.

static invalid_length(loc: Loc, value: Sized, /, min_length: int | None = None, max_length: int | None = None, *, msg: str | None = None) → Error

Create invalid length error.

This error is reported for containers or other sized types when length constraints are not satisfied.

Important

The built-in message composer requires at least one length range parameter to be provided.

Parameters:

  • loc – Error location in the model.

  • value – Incorrect input value.

  • min_length – Minimum length.

  • max_length – Maximum length.

  • msg –

    The optional message to override built-in one.

    When custom message is provided then length range parameters, although still recommended, become optional.

    Added in version 0.33.0.

static invalid_string_format(loc: Loc, value: str, expected_pattern: str, /, *, msg: str | None = None) → Error

Create invalid string format error.

Changed in version 0.33.0: Now loc, value and expected_pattern are positional-only arguments, while msg is keyword-only argument. This was changed for compliance with other methods.

Parameters:

  • loc – Error location in the model.

  • value – Incorrect input string.

  • expected_pattern – Expected string pattern (f.e. regex pattern).

  • msg – Optional user-defined message to use instead of built-in one.

static invalid_tuple_length(loc: Loc, value: tuple, expected_tuple: tuple[type, ...], /) → Error

Create invalid tuple length error.

Parameters:

  • loc – Error location in the model.

  • value – Incorrect input tuple.

  • expected_tuple – Expected tuple shape.

static invalid_type(loc: Loc, value: Any, expected_types: list[type], /, allowed_types: list[type] | None = None, forbidden_types: list[type] | None = None, *, msg: str | None = None, **extra_data) → Error

Create invalid type error.

Parameters:

  • loc – Error location in the model.

  • value – Incorrect input value.

  • expected_types – List with expected type or types.

  • allowed_types –

    Optional list with allowed types.

    This is information that if one of these types is used as type of the input value then it will be accepted and converted to one of expected types.

    For example, a set can be constructed from set, list or tuple of items.

  • forbidden_types –

    Optional list of forbidden types.

    This is used to specify types that are arbitrary forbidden and will fail value processing immediately when encountered.

  • msg –

    The optional message to override built-in one.

    Added in version 0.33.0.

  • **extra_data –

    The optional extra error data.

    This will be placed inside modelity.error.Error.data dict of a created error object.

    Added in version 0.33.0.

static invalid_value(loc: Loc, value: Any, expected_values: list, /, *, msg: str | None = None, **extra_data) → Error

Create invalid value error.

Parameters:

  • loc – Error location in the model.

  • value – Input value from outside of expected values set.

  • expected_values – List with expected values.

  • msg –

    The optional message to override built-in one.

    Added in version 0.32.0.

  • **extra_data –

    The optional extra error data.

    This will be placed inside modelity.error.Error.data dict of a created error object.

    Added in version 0.33.0.

static none_not_allowed(loc: Loc, expected_type: Any, /) → Error

Create NONE_NOT_ALLOWED error.

See ErrorCode.NONE_NOT_ALLOWED for more details.

Added in version 0.29.0.

Parameters:

  • loc – Error location in the model.

  • expected_types – The expected type.

static out_of_range(loc: Loc, value: T, /, min_inclusive: T | None = None, min_exclusive: T | None = None, max_inclusive: T | None = None, max_exclusive: T | None = None, *, msg: str | None = None) → Error

Create out of range error.

This is a generic error factory for all kind of value range errors.

Important

The built-in message composer requires at least one range parameter to be provided.

Parameters:

  • loc – Error location in the model.

  • value – Incorrect input value.

  • min_inclusive – Minimum value (inclusive).

  • min_exclusive – Minimum value (exclusive).

  • max_inclusive – Maximum value (inclusive).

  • max_exclusive – Maximum value (exclusive).

  • msg –

    The optional message to override built-in one.

    When custom message is provided then range parameters, although still recommended, become optional.

    Added in version 0.33.0.

static parse_error(loc: Loc, value: Any, expected_type: type, /, *, msg: str | None = None, **extra_data) → Error

Create parse error.

Parameters:

  • loc – Error location in the model.

  • value – Input value that could not be parsed.

  • expected_type – Expected value type.

  • msg – The optional message to override built-in one.

  • **extra_data –

    The optional extra error data.

    This will be placed inside modelity.error.Error.data dict of a created error object.

static required_missing(loc: Loc, /)

Create required missing error.

Parameters:

loc – The location of a missing field.

static unset_not_allowed(loc: Loc, expected_type: Any, /) → Error

Create UNSET_NOT_ALLOWED error.

See ErrorCode.UNSET_NOT_ALLOWED for more details.

Added in version 0.29.0.

Parameters:

  • loc – Error location in the model.

  • expected_types – The expected type.

class modelity.error.ErrorWriter(out: TextIO, indent_string: str = '  ', indent_level: int = 0, show_code: bool = False, show_value: bool = False, show_value_type: bool = False, show_data: bool = False)

Bases: object

Class that formats errors as string and appends to the end of provided text buffer.

Parameters:

  • out – The output text buffer.

  • indent_string – Indentation string.

  • indent_level – Indentation level.

  • show_code – Display error code.

  • show_value – Display input value.

  • show_value_type – Display input value type.

  • show_data – Display additional error data.

Added in version 0.28.0.

__init__(out: TextIO, indent_string: str = '  ', indent_level: int = 0, show_code: bool = False, show_value: bool = False, show_value_type: bool = False, show_data: bool = False)
write(obj: Error)

Format given error object and write to the end of the text buffer provided in the constructor.

Parameters:

obj – The error object.