monk 0.13.2

建模

模式定义为使用原生Python数据类型的模板

# we will reuse this structure in examples below

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

您可以自由设计所需复杂程度的文档。下面的操作和验证函数（以下将描述）支持任意嵌套结构。

当这种“自然”的Pythonic方法不够用时，您可以将其与更冗长的表示法混合使用，例如：

title_spec = IsA(str, default='Untitled') | Equals(None)

还有便捷的快捷方式

spec = {
    'url': nullable(str),
    'status': one_of(['new', 'in progress', 'closed']),
    'comments': [str],
    'blob': None,
}

这可以写成更详细的形式

spec = {
    'url': IsA(str) | Equals(None),
    'status': Equals('new') | Equals('in progress') | Equals('closed'),
    'comments': ListOf(IsA(str)),
    'blob': Anything(),
}

甚至可以定义字典键的模式

CATEGORIES = ['books', 'films', 'toys']
spec = {
    'title': str,
    optional('price'): float,    # key is optional; value is mandatory
    'similar_items': {
        one_of(CATEGORIES): [    # suggestions grouped by category
            {'url': str, 'title': str}
        ],
    }
}

# (what if the categories should be populated dynamically?
#  well, the schema is plain Python data, just copy/update on the fly.)

是的，您可以将表示法混合使用。请参阅常见问题解答。

这个非常简短的介绍表明，Monk几乎需要零学习即可开始，然后当您需要时提供非常强大的工具；您无需重写“直观”的代码，只需在不可避免的地方增加复杂性。

操作

可以使用模式从完整数据创建完整文档

from monk import merge_defaults

# 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,
        }
    ]
}

验证

相同的模式可以用来确保文档具有正确的结构，并且值是正确的类型

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):
   ...
MissingKey: 'comments'

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

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

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

>>> validate(spec, {'title': 123, 'comments': []})
Traceback (most recent call last):
    ...
ValidationError: 'title': must be str

可以使用自定义验证器。行为可以微调。

validate()函数在底层将“自然”表示法转换为验证器对象。为了提高性能，您可以一次“编译”验证器（使用translate()函数或在原地创建验证器实例）并多次用于验证不同的值

>>> from monk import *
>>> translate(str) == IsA(str)
True
>>> validator = IsA(str) | IsA(int)
>>> validator('hello')
>>> validator(123)
>>> validator(5.5)
Traceback (most recent call last):
    ...
AllFailed: 5.5 (must be str; must be int)

该库也可以被视为构建ODMs（对象-文档映射器）的框架。请参阅MongoDB扩展，并注意它是如何重用DB无关模块提供的混入（mixins）的。

以下是Monk附带的一个MongoDB ODM的示例

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)