pyskema package

Submodules

pyskema.describe module

Implement a function to describe a schema in human readable text.

class pyskema.describe.Describer

Bases: Visitor

A visitor that implement description.

You should probably be using describe() instead.

classmethod describe(schema): Generate a set lines describing schema.

describe_node(value, prefix='', indent=0)

visit_atom(atom, indent=0): Visit an pyskema.schema.Atom instance.

visit_collection(collection, indent=0): Visit a pyskema.schema.Collection instance.

visit_map(map, indent=0): Visit a pyskema.schema.Map instance.

visit_record(rec, indent=0): Visit a pyskema.schema.Record instance.

visit_tuple(tup, indent=0): Visit a pyskema.schema.Tuple instance.

visit_union(union, indent=0): Visit an pyskema.schema.Union instance.

class pyskema.describe.Searcher

Bases: Visitor

A visitor implementing the search.

classmethod search(schema, name): Show the visit

visit_atom(atom, name, path=()): Visit an pyskema.schema.Atom instance.

visit_collection(collection, name, path=()): Visit a pyskema.schema.Collection instance.

visit_map(map, name, path=()): Visit a pyskema.schema.Map instance.

visit_record(rec, name, path=()): Visit a pyskema.schema.Record instance.

visit_tuple(tup, name, path=()): Visit a pyskema.schema.Tuple instance.

visit_union(union, name, path=()): Visit an pyskema.schema.Union instance.

pyskema.describe.describe(schema, selects=())

Describe in human readable format schema.

Parameters:

schema – The schema to describe.
selects – (optional, ()) a path into schema to describe a sub-tree element only.

pyskema.describe.search(schema, name): Search for name into schema.

pyskema.describe.select(schema, selects, index=0)

pyskema.edit module

Create a new schema with edits.

Internally used to implement schema.Node.inject() and schema.Node.delete().

class pyskema.edit.Deleter

Bases: CopyingVisitor

Visitor implementing schema.Node.delete().

visit_atom(atom, path): Visit an pyskema.schema.Atom instance.

visit_record(rec, path): Visit a pyskema.schema.Record instance.

visit_tuple(tup, path): Visit a pyskema.schema.Tuple instance.

visit_union(union, path): Visit an pyskema.schema.Union instance.

class pyskema.edit.Injecter

Bases: CopyingVisitor

Visitor implementing schema.Node.inject().

visit_atom(atom, path, _element): Visit an pyskema.schema.Atom instance.

visit_record(rec, path, element): Visit a pyskema.schema.Record instance.

visit_tuple(tup, path, element): Visit a pyskema.schema.Tuple instance.

visit_union(union, path, element): Visit an pyskema.schema.Union instance.

pyskema.misc module

Miscellaneous utils.

class pyskema.misc.Result(valid: bool, val)

Bases: object

The Result monad.

property error

classmethod fail(error)

classmethod ok(value)

property value

pyskema.misc.closest(alternatives, key)

Search among alternatives the element to key.

Uses lev_dist() to compute the distance.

Parameters:

alternatives – a list[str] of elements to analyse.
key – a str key to search for.

pyskema.misc.lev_dist(a, b): Compute the Levenstein distance between two str.

pyskema.schema module

The core definition of a schema.

class pyskema.schema.Atom(type_: AtomType, options: List[str] | None = None)

Bases: Structure

Structure of an atomic piece of data

accept(visitor, *args, **kwargs)

options: List[str] | None = None

type_: AtomType

class pyskema.schema.AtomType(value)

Bases: Enum

Kind of atomic value.

BOOL = 3

FLOAT = 1

INT = 0

OPTION = 4

STR = 2

class pyskema.schema.Collection(element: Node)

Bases: Structure

An ordered collection of similar nodes

accept(visitor, *args, **kwargs)

element: Node

classmethod structure_default()

class pyskema.schema.Map(element: Node)

Bases: Structure

A key-value pair collection.

Keys are not restricted and values are of a single type.

accept(visitor, *args, **kwargs)

element: Node

classmethod structure_default()

class pyskema.schema.Node(structure: Structure, description: str | None = None, optional: bool = False, default: Any | None = None)

Bases: object

Base class for a node of the schema

copy(): Deep copy of the schema.

default: Any = None

delete(path)

Remove a node from an exisisting schema.

The original object is not altered, but a new schema is created instead with the same nodes (except for the deletion).

Parameters:: path – a tuple of str and int to indicate the place to modify. Use the names of record fields and the index of tuple fields and unions alternatives.
Returns:: a fresh schema of the same structure as self with due modifications.

Example:

>>> s1 = Node.of_record({
    "foo": Node.of_tuple([
        Node.of_atom(AtomType.INT, description="width"),
        Node.of_atom(AtomType.INT, description="height"),
        Node.of_atom(AtomType.INT, description="depth"),
    ]),
    "bar": Node.of_atom(AtomType.STR),
})
>>> s2 = s1.delete(("foo", 2))
>>> describe(s1)
foo: 
    - width
        value of type int
    - height
        value of type int
    - depth
        value of type int
bar: 
    value of type str
>>> describe(s2)
foo: 
    - width
        value of type int
    - height
        value of type int
bar: 
    value of type str

description: str | None = None

inject(path, elem)

Inject new nodes or replace nodes in an exisisting schema.

The original object is not altered, but a new schema is created instead with the same nodes (except for the injection).

Parameters:

path – a tuple of str and int to indicate the place to modify. Use the names of record fields and the index of tuple fields and unions alternatives.
elem – the element to insert at path

Returns:

a fresh schema of the same structure as self with due modifications.

Example:

>>> s1 = Node.of_record({
    "foo": Node.of_tuple([
        Node.of_atom(AtomType.INT, description="width"),
        Node.of_atom(AtomType.INT, description="height"),
    ]),
    "bar": Node.of_atom(AtomType.STR),
})
>>> s2 = s1.inject(("foo", 2), Node.of_atom(AtomType.INT, description="depth"))
>>> describe(s1)
foo: 
    - width
        value of type int
    - height
        value of type int
bar: 
    value of type str
>>> describe(s2)
foo: 
    - width
        value of type int
    - height
        value of type int
    - depth
        value of type int
bar: 
    value of type str

classmethod of_atom(atom, options=None, **kwargs)

Constructor for an Atom node.

Parameters:

atom – the AtomType for the node.
options – options for Atom constructor.
**kwargs – kw parameters for Node.__init__.

classmethod of_collection(element, **kwargs)

Constructor for a Collection node.

Parameters:

element – the Node instance describing an element of the collection.
**kwargs – kw parameters for Node.__init__.

classmethod of_map(element, **kwargs)

Constructor for a Map node.

Parameters:

element – the Node instance describing an element of the map.
**kwargs – kw parameters for Node.__init__.

classmethod of_record(fields, **kwargs)

Constructor for a Record node.

Parameters:

fields – a dict of str
options – options for Atom constructor.
**kwargs – kw parameters for Node.__init__.

classmethod of_tuple(elements, **kwargs)

Constructor for a Tuple node.

Parameters:

elements – list of Node describing the elements of the tuple.
**kwargs – kw parameters for Node.__init__.

classmethod of_union(options, **kwargs)

Constructor for a Union node.

Parameters:

options – list of Node instances for the alternatives.
**kwargs – kw parameters for Node.__init__.

optional: bool = False

structure: Structure

class pyskema.schema.Record(fields: Dict[str, Node])

Bases: Structure

A key-value pair collection.

Keys are from a defined set and values are defined per-key. Keys are supposed to be valid identifiers.

accept(visitor, *args, **kwargs)

fields: Dict[str, Node]

classmethod structure_default()

class pyskema.schema.Structure

Bases: object

Abstract structure of a node

abstract accept(visitor, *args, **kwargs)

classmethod structure_default()

class pyskema.schema.Tuple(fields: List[Node])

Bases: Structure

A fixed set of ordered fields.

Each field can have a different structure.

accept(visitor, *args, **kwargs)

fields: List[Node]

classmethod structure_default()

class pyskema.schema.Union(options: List[Node])

Bases: Structure

Structure for the union of several nodes

accept(visitor, *args, **kwargs)

options: List[Node]

pyskema.template module

Generate template data from a schema.

class pyskema.template.Templater

Bases: Visitor

Visitor implementing templating.

You should probably be using template() instead.

template_node(value)

visit_atom(atom): Visit an pyskema.schema.Atom instance.

visit_collection(collection): Visit a pyskema.schema.Collection instance.

visit_map(map): Visit a pyskema.schema.Map instance.

visit_record(rec): Visit a pyskema.schema.Record instance.

visit_tuple(tup): Visit a pyskema.schema.Tuple instance.

visit_union(union): Visit an pyskema.schema.Union instance.

pyskema.template.template(schema): Generate a template from schema

pyskema.validate module

Implement validation of data against a schema.

exception pyskema.validate.InvalidDataError(mismatch)

Bases: ValueError

Exception signaling failure to validate data.

class pyskema.validate.Mismatch(where: List[str], what: object, why: str)

Bases: object

Infos on a mismatch between the schema and a piece of data.

from_(where)

what: object

where: List[str]

why: str

class pyskema.validate.Mismatches(errors)

Bases: object

A collection of mismatches between schema and data.

from_(where)

class pyskema.validate.Validator

Bases: Visitor

Visitor implementing validation.

You should probably be using validate() instead.

classmethod validate(schema, data)

validate data against schema.

Parameters:

schema – instance of Node
data – the data to validate

visit_atom(atom, data) → Result: Visit an pyskema.schema.Atom instance.

visit_collection(collection, data) → Result: Visit a pyskema.schema.Collection instance.

visit_map(map_, data) → Result: Visit a pyskema.schema.Map instance.

visit_record(rec, data) → Result: Visit a pyskema.schema.Record instance.

visit_tuple(tup, data) → Result: Visit a pyskema.schema.Tuple instance.

visit_union(union, data) → Result: Visit an pyskema.schema.Union instance.

pyskema.validate.error_message(mismatch, no_loc=False): Format the error message for InvalidDataError.

pyskema.validate.validate(data, schema, fail=True)

Validate a piece of data against a schema.

Parameters:

data – a piece of data to validate.
schema – a schema to refer to
fail –
(optional, True)
- if True, raise an InvalidDataError when failing to validate data
- else, return None

pyskema.visitor module

Schema base visitor.

pyskema uses the visitor patter to implement various operations on schema. This module implement the base class that should be extended to implement such operation.

class pyskema.visitor.CopyingVisitor

Bases: Visitor

A base for non mutating visitors.

Similar to Visitor, but it should create an entirely new tree.

visit(node: Node, *args, **kwargs): The entry point for all scheme.Node.

visit_atom(atom, *args, **kwargs): Visit an pyskema.schema.Atom instance.

visit_collection(collection, *args, **kwargs): Visit a pyskema.schema.Collection instance.

visit_map(map_, *args, **kwargs): Visit a pyskema.schema.Map instance.

visit_record(rec, *args, **kwargs): Visit a pyskema.schema.Record instance.

visit_tuple(tup, *args, **kwargs): Visit a pyskema.schema.Tuple instance.

visit_union(union, *args, **kwargs): Visit an pyskema.schema.Union instance.

class pyskema.visitor.Visitor

Bases: object

The base visitor.

visit(node: Node, *args, **kwargs): The entry point for all scheme.Node.

visit_atom(atom, *args, **kwargs): Visit an pyskema.schema.Atom instance.

visit_collection(collection, *args, **kwargs): Visit a pyskema.schema.Collection instance.

visit_map(map_, *args, **kwargs): Visit a pyskema.schema.Map instance.

visit_record(rec, *args, **kwargs): Visit a pyskema.schema.Record instance.

visit_tuple(tup, *args, **kwargs): Visit a pyskema.schema.Tuple instance.

visit_union(union, *args, **kwargs): Visit an pyskema.schema.Union instance.

Module contents

A schema definition module for validation and documentation of structured data.