sporco.cdict

Constrained dictionary class.

Functions

keycmp(a, b[, pth])

Compare keys in nested dicts.

Classes

ConstrainedDict([d, pth, dflt])

A dict subclass that constrains the allowed dict keys.

Exceptions

UnknownKeyError(arg)	Exception for unrecognised dict key.
InvalidValueError(arg)	Exception for invalid dict value.

Function Descriptions

sporco.cdict.keycmp(a, b, pth=())

Compare keys in nested dicts.

Recurse down the tree of nested dicts b, at each level checking that it does not have any keys that are not also at the same level in a. The key path is recorded in pth. If an unknown key is encountered in b, an UnknownKeyError exception is raised. If a non-dict value is encountered in b for which the corresponding value in a is a dict, an InvalidValueError exception is raised.

Parameters:

adict

Reference dict tree

adict

Compared dict tree

pthstr or tuple of str

Dict key

Class Descriptions

class sporco.cdict.ConstrainedDict(d=None, pth=(), dflt=None)

Bases: dict

A dict subclass that constrains the allowed dict keys.

Base class for a dict subclass that constrains the allowed dict keys, including those of nested dicts, and also initialises the dict with default content on instantiation. The default content is specified by the defaults class attribute, and the allowed keys are determined from the same attribute.

Initialise a ConstrainedDict object.

The object is first created with default content, which is then overwritten with the content of parameter d. When a subdict is initialised via this constructor, the key path from the root to this subdict (i.e. the set of keys, in sequence, that select the subdict starting from the top-level dict) should be passed as a tuple via the pth parameter, and the defaults dict should be passed via the dflt parameter.

Parameters:

ddict

Content to overwrite the defaults

pthtuple of str

Key path for objects that are subdicts of other objects

dflt: dict

Reference to top level defaults dict for objects that are subdicts of other objects

defaults = {}

Default content and allowed dict keys

update(d)

Update the dict with the dict tree in parameter d.

Parameters:

ddict

New dict content

check(key, value)

Check whether key, value pair is allowed.

The key is allowed if there is a corresponding key in the defaults class attribute dict. The value is not allowed if it is a dict in the defaults dict and not a dict in value.

Parameters:

keystr or tuple of str

Dict key

valueany

Dict value corresponding to key

static getparent(d, pth)

Get the parent node of a subdict as specified by the key path in pth.

Parameters:

ddict

Dict tree in which access is required

pthstr or tuple of str

Dict key

static getnode(d, pth)

Get the node of a subdict specified by the key path in pth.

Parameters:

ddict

Dict tree in which access is required

pthstr or tuple of str

Dict key

Exception Descriptions

exception sporco.cdict.UnknownKeyError(arg)

Bases: KeyError

Exception for unrecognised dict key.

exception sporco.cdict.InvalidValueError(arg)

Bases: ValueError

Exception for invalid dict value.