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

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

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

.Schema – Inner schema for non-null processing.

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

.Schema – Inner schema for processing.

default

Alternative value for when the key is missing. This can be None (the default), an instance of a static class (int, float, bool), the list or dict constructor, or a lambda or function that produces the desired value (e.g. lambda: {"a": 1}).

When using None, you should also mark the corresponding value as Nullable.

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.
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: immp.core.schema.Walker

Validation of schemas against input data.

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: immp.core.schema.Walker

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

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

dictJSON Schema data corresponding to this schema – see JSONSchema.