core.schema

class immp.core.schema.Any(*choices)

Bases: object

Allow values to match from a choice of schemas. Invalid will be raised if none of them are valid for a given value.

If no schemas are defined, this acts as a wildcard, i.e. it will match any value given.

When used as a dictionary key, exactly one choice must be present. To allow any number of keys, use Optional instead.

choices

Set of valid schemas, or an empty set to match any possible value.

Type:

.Schema list

class immp.core.schema.Nullable(schema)

Bases: object

Allow values tested against the inner schema to hold a null value. Without this wrapper, None will not be accepted by a schema and will raise Invalid, whereas Nullable(str) matches both "foo" and None.

This object evaluates equally to its inner schema.

schema

Inner schema for non-null processing.

Type:

.Schema

classmethod unwrap(value)

Unpack a value, whether nullable or not.

Parameters:

value – Plain or Nullable schema value.

Returns:

Tuple of (schema, nullable), where nullable is True if the source value was Nullable, False otherwise.

class immp.core.schema.Optional(schema, default=None)

Bases: object

Allows keys matching the inner schema to not be present in the source dict. Without this wrapper, Invalid will be raised if the corresponding key is missing.

This object evaluates equally to its inner schema.

schema

Inner schema for processing.

Type:

.Schema

default
Alternative value for when the key is missing. This can be one of:

  • None (the default; requires the value to be marked Nullable)

  • an instance of a static class (int, float, bool)

  • the list or dict constructor

  • a lambda or function that produces the desired value (e.g. lambda: {"a": 1})

  • Optional.MISSING, which prevents the insertion of a default value

classmethod unwrap(key)

Unpack a dict key, whether optional or not.

Parameters:

key – Plain or Optional key.

Returns:

Tuple of (schema, default), where default is Optional.MISSING if key is not an Optional instance, or no default is provided.

exception immp.core.schema.SchemaError

Bases: Exception

Error with the definitiion of the schema itself, raised during validation.

exception immp.core.schema.Invalid

Bases: Exception

Error with input data not matching the corresponding schema.

class immp.core.schema.Walker

Bases: object

Base class for stepping through all nodes of a Schema instance.

classmethod recurse(obj, path, seen, *args)

Handle recursion of the schema. By default, raises RecursionError when a node is discovered again during a single call.

If Walker.RECURSE is returned, the node will be processed again. Otherwise, the resulting value (including None) will be used for the inner repeat of this node without any further processing.

Parameters:

  • obj (.Schema) – Schema node.

  • path (str) – Path taken through the schema from the root.

  • seen (.Schema list) – Nodes already visited in the schema.

Raises:

RecursionError – To block looping through the same portion of the schema.

classmethod static(obj, path, seen, *args)

Handle a static object or type, as defined by Walker.STATIC.

Parameters:

  • obj (int, float, bool, str) – Schema node.

  • path (str) – Path taken through the schema from the root.

  • seen (.Schema list) – Nodes already visited in the schema.

classmethod nullable(obj, path, seen, *args)

Handle a nullable wrapper.

Parameters:

  • obj (.Nullable) – Schema node.

  • path (str) – Path taken through the schema from the root.

  • seen (.Schema list) – Nodes already visited in the schema.

classmethod any(obj, path, seen, *args)

Handle a multiple-choice wrapper.

Parameters:

  • obj (.Nullable) – Schema node.

  • path (str) – Path taken through the schema from the root.

  • seen (.Schema list) – Nodes already visited in the schema.

classmethod list(obj, path, seen, *args)

Handle a list. Multiple list members are considered equivalent to an Any.

Parameters:

  • obj (list) – Schema node.

  • path (str) – Path taken through the schema from the root.

  • seen (.Schema list) – Nodes already visited in the schema.

classmethod dict(obj, path, seen, *args)

Handle a dictionary.

Parameters:

  • obj (dict) – Schema node.

  • path (str) – Path taken through the schema from the root.

  • seen (.Schema list) – Nodes already visited in the schema.

classmethod dispatch(obj, path, seen, *args)

Defer to other helper methods based on the input type.

Parameters:

  • obj (.Schema) – Schema node.

  • path (str) – Path taken through the schema from the root.

  • seen (.Schema list) – Nodes already visited in the schema.

classmethod walk(obj, *args)

Main entrypoint to the walk.

Parameters:

obj (.Schema) – Schema node.

Raises:

SchemaError – When the schema is misconfigured.

class immp.core.schema.Validator

Bases: Walker

Validation of schemas against input data.

classmethod recurse(obj, path, seen, data)

Handle recursion of the schema. By default, raises RecursionError when a node is discovered again during a single call.

If Walker.RECURSE is returned, the node will be processed again. Otherwise, the resulting value (including None) will be used for the inner repeat of this node without any further processing.

Parameters:

  • obj (.Schema) – Schema node.

  • path (str) – Path taken through the schema from the root.

  • seen (.Schema list) – Nodes already visited in the schema.

Raises:

RecursionError – To block looping through the same portion of the schema.

classmethod static(obj, path, seen, data)

Handle a static object or type, as defined by Walker.STATIC.

Parameters:

  • obj (int, float, bool, str) – Schema node.

  • path (str) – Path taken through the schema from the root.

  • seen (.Schema list) – Nodes already visited in the schema.

classmethod nullable(obj, path, seen, data)

Handle a nullable wrapper.

Parameters:

  • obj (.Nullable) – Schema node.

  • path (str) – Path taken through the schema from the root.

  • seen (.Schema list) – Nodes already visited in the schema.

classmethod any(obj, path, seen, data)

Handle a multiple-choice wrapper.

Parameters:

  • obj (.Nullable) – Schema node.

  • path (str) – Path taken through the schema from the root.

  • seen (.Schema list) – Nodes already visited in the schema.

classmethod list(obj, path, seen, data)

Handle a list. Multiple list members are considered equivalent to an Any.

Parameters:

  • obj (list) – Schema node.

  • path (str) – Path taken through the schema from the root.

  • seen (.Schema list) – Nodes already visited in the schema.

classmethod dict(obj, path, seen, data)

Handle a dictionary.

Parameters:

  • obj (dict) – Schema node.

  • path (str) – Path taken through the schema from the root.

  • seen (.Schema list) – Nodes already visited in the schema.

classmethod dispatch(obj, path, seen, data)

Defer to other helper methods based on the input type.

Parameters:

  • obj (.Schema) – Schema node.

  • path (str) – Path taken through the schema from the root.

  • seen (.Schema list) – Nodes already visited in the schema.

classmethod walk(obj, data)

Validate the given data against a schema.

Parameters:

  • obj (.Schema) – Description of the data format.

  • data – Input data to validate.

Raises:

Invalid – When a key or value doesn’t match the accepted type for that field.

Returns:

Parsed data with optional values filled in.

class immp.core.schema.JSONSchema

Bases: Walker

Generator of JSON Schema objects, suitable for external validation of schemas in JSON.

classmethod static(obj, path, seen)

Handle a static object or type, as defined by Walker.STATIC.

Parameters:

  • obj (int, float, bool, str) – Schema node.

  • path (str) – Path taken through the schema from the root.

  • seen (.Schema list) – Nodes already visited in the schema.

classmethod nullable(obj, path, seen)

Handle a nullable wrapper.

Parameters:

  • obj (.Nullable) – Schema node.

  • path (str) – Path taken through the schema from the root.

  • seen (.Schema list) – Nodes already visited in the schema.

classmethod any(obj, path, seen)

Handle a multiple-choice wrapper.

Parameters:

  • obj (.Nullable) – Schema node.

  • path (str) – Path taken through the schema from the root.

  • seen (.Schema list) – Nodes already visited in the schema.

classmethod list(obj, path, seen)

Handle a list. Multiple list members are considered equivalent to an Any.

Parameters:

  • obj (list) – Schema node.

  • path (str) – Path taken through the schema from the root.

  • seen (.Schema list) – Nodes already visited in the schema.

classmethod dict(obj, path, seen)

Handle a dictionary.

Parameters:

  • obj (dict) – Schema node.

  • path (str) – Path taken through the schema from the root.

  • seen (.Schema list) – Nodes already visited in the schema.

classmethod walk(obj)

Convert a schema structure into a JSON Schema representation.

Parameters:

schema (.Schema) – Input schema or structure.

Returns:

Equivalent JSON Schema data.

Return type:

dict

class immp.core.schema.Schema(raw, base=None)

Bases: object

Validate JSON-like Python structures and provide defaults:

config = Schema({
    "flag": bool,
    "numbers": [int],
    "nullable": Nullable(str),
    "nested": {
        Optional("defaulted", 1): int,
        "multiple": Any(int, str)
    }
})

validated = config(data)

Pass a structure representing the expected data format to the constructor, along with an optional base to extend from, then validate some given data against the schema by calling the instance – see Validator.

raw

Root schema item, including any base items.

json

JSON Schema data corresponding to this schema – see JSONSchema.

Type:

dict