monk 0.10.1

Modeling

The schema is defined as a template using native Python data types:

# we will reuse this structure in examples below

spec = {
    'title': 'Untitled',
    'comments': [
        { 'author': str,
          'date': datetime.datetime.utcnow,
          'text': str
        }
    ],
}

You are free to design as complex a document as you need. The manipulation and validation functions (described below) support arbitrary nested structures.

When this “natural” pythonic approach is not sufficient, you can mix it with a more verbose notation, e.g.:

title_spec = Rule(datatype=str, default='Untitled', validators=[...])

There are also neat shortcuts:

spec = {
    'url': optional(str),
    'status': one_of(['new', 'in progress', 'closed']),
    'blob': any_or_none,
    'price': optional(in_range(5, 200)),
}

By the way, the last one is translated into this one under the hood:

spec = {
    'price': Rule(datatype=int, optional=True,
                  validators=[monk.validators.validate_range(5, 200)]),
}

And, yes, you can mix notations. See FAQ.

This very short intro shows that Monk requires almost zero learning to start and then provides very powerful tools when you need them; you won’t have to rewrite the “intuitive” code, only augment complexity exactly in places where it’s inevitable.

Manipulation

The schema can be used to create full documents from incomplete data:

from monk.manipulation import merged

# default values are set for missing keys

>>> merge_defaults(spec, {})
{ 'title': 'Untitled',
  'comments': []
}

# it's easy to override the defaults

>>> merge_defaults(spec, {'title': 'Hello'})
{ 'title': 'Hello',
  'comments': []
}

# nested lists of dictionaries can be auto-filled, too.
# by the way, note the date.

>>> merge_defaults(spec, {'comments': ['author': 'john']})
{ 'title': 'Untitled',
  'comments': [
        { 'author': 'john',
          'date': datetime.datetime(2013, 3, 3, 1, 8, 4, 152113),
          'text': None
        }
    ]
}

Validation

The same schema can be used to ensure that the document has correct structure and the values are of correct types:

from monk.validation import validate

# correct data: staying silent

>>> validate(spec, data)

# a key is missing

>>> validate(spec, {'title': 'Hello'})
Traceback (most recent call last):
   ...
monk.errors.MissingKey: comments

# a key is missing in a dictionary in a nested list

>>> validate(spec, {'comments': [{'author': 'john'}]}
Traceback (most recent call last):
   ...
monk.errors.MissingKey: comments: #0: date

# type check; also works with functions and methods (by return value)

>>> validation.validate(spec, {'title': 123, 'comments': []})
Traceback (most recent call last):
    ...
TypeError: title: expected str, got int 123

Custom validators can be used. Behaviour can be fine-tuned.

The library can be also viewed as a framework for building ODMs (object-document mappers). See the MongoDB extension and note how it reuses mixins provided by DB-agnostic modules.

Here’s an example of the MongoDB ODM bundled with Monk:

from monk.mongo import Document

class Item(Document):
    structure = dict(text=unicode, slug=unicode)
    indexes = dict(text=None, slug=dict(unique=True))

# this involves manipulation (inserting missing fields)
item = Item(text=u'foo', slug=u'bar')

# this involves validation
item.save(db)