ming.schema module

class ming.schema.Anything(required=(), if_missing=())

Accepts any value without validation.

Passes validation unchanged except for converting dict => Object

This is often used to avoid the cost of validation on fields that might contain huge entries that do not need to be validated.

Parameters:

  • required (bool) – if True and this field is missing, an Invalid exception will be raised

  • if_missing (value or callable) – provides a default value for this field if the field is missing

validate(value, **kw)

Validate an object or raise an Invalid exception.

Default implementation just raises NotImplementedError

class ming.schema.Array(field_type, **kw)

Validates a MongoDB Array.

All elements of the array must pass validation by a single field_type (which itself may be Anything, however).

Parameters:

  • required (bool) – if True and this field is missing, an Invalid exception will be raised

  • if_missing (value or callable) – provides a default value for this field if the field is missing

class ming.schema.Binary(**kw)

Validates value is a bson.Binary

Parameters:

  • required (bool) – if True and this field is missing, an Invalid exception will be raised

  • if_missing (value or callable) – provides a default value for this field if the field is missing

type = (<class 'bson.binary.Binary'>, <class 'bytes'>)

Expected Type of the validated value.

class ming.schema.Bool(**kw)

Validates value is a bool

Parameters:

  • required (bool) – if True and this field is missing, an Invalid exception will be raised

  • if_missing (value or callable) – provides a default value for this field if the field is missing

type

alias of bool

class ming.schema.DateTime(**kw)

Validates value is a datetime and ensures its on UTC.

If value is a datetime but it’s not on UTC it gets converted to UTC timezone. if value is instance of date it will be converted to datetime

Parameters:

  • required (bool) – if True and this field is missing, an Invalid exception will be raised

  • if_missing (value or callable) – provides a default value for this field if the field is missing

_validate(value, **kw)

Performs actual validation.

Subclasses are expected to override this method to provide the actual validation.

The default implementation leaves the value as is.

class ming.schema.DateTimeTZ(**kw)

Validates value is a datetime.

Parameters:

  • required (bool) – if True and this field is missing, an Invalid exception will be raised

  • if_missing (value or callable) – provides a default value for this field if the field is missing

type

alias of datetime

class ming.schema.Deprecated

Used for deprecated fields – they will be stripped from the object.

validate(value, **kw)

Validate an object or raise an Invalid exception.

Default implementation just raises NotImplementedError

class ming.schema.Document(fields=None, required=False, if_missing=())

Specializes Object adding polymorphic validation.

This is usually not used directly, but it’s the Schema against which each document in Ming is validated to.

Polymorphic Validation means that Document._validate(…) sometimes will return an instance of ChildClass based on .polymorphic_on entry of the object (its value is used to determine the class it should be promoted based on polymorphic_identity of .managed_class).

Map of polymorphic_identity values are stored in .polymorphic_registry dictionary.

By default .polymorphic_on, .managed_class and .polymorphic_registry are all None. So .managed_class must be set and and set_polymorphic() method must be called to configure them properly.

Parameters:

  • required (bool) – if True and this field is missing, an Invalid exception will be raised

  • if_missing (value or callable) – provides a default value for this field if the field is missing

_validate(d, allow_extra=False, strip_extra=False)

Performs actual validation.

Subclasses are expected to override this method to provide the actual validation.

The default implementation leaves the value as is.

get_polymorphic_cls(data)

Given a mongodb document it returns the class it should be converted to.

set_polymorphic(field, registry, identity)

Configure polymorphic behaviour (except for .managed_class).

field is the .polymorphic_on, which is the name of the field used to detect polymorphic type.

registry is the .polymorphic_registry which is a map of field values to classes.

identity is the value which leads to .managed_class type itself.

validate(value, **kw)

Validate an object or raise an Invalid exception.

Default implementation just raises NotImplementedError

class ming.schema.FancySchemaItem(required=(), if_missing=())

SchemaItem that provides support for required fields and default values.

If the value is present, then the result of _validate() method is returned.

Parameters:

  • required (bool) – if True and this field is missing, an Invalid exception will be raised

  • if_missing (value or callable) – provides a default value for this field if the field is missing

_validate(value, **kw)

Performs actual validation.

Subclasses are expected to override this method to provide the actual validation.

The default implementation leaves the value as is.

class ming.schema.Float(**kw)

Validates value is int or float

Parameters:

  • required (bool) – if True and this field is missing, an Invalid exception will be raised

  • if_missing (value or callable) – provides a default value for this field if the field is missing

type = (<class 'float'>, <class 'int'>)

Expected Type of the validated value.

class ming.schema.Int(**kw)

Validates value is an int.

Also accepts float which represent integer numbers like 10.0 -> 10.

Parameters:

  • required (bool) – if True and this field is missing, an Invalid exception will be raised

  • if_missing (value or callable) – provides a default value for this field if the field is missing

_validate(value, **kw)

Performs actual validation.

Subclasses are expected to override this method to provide the actual validation.

The default implementation leaves the value as is.

type = (<class 'int'>,)

Expected Type of the validated value.

exception ming.schema.Invalid(msg, value, state=None, error_list=None, error_dict=None)

This is raised in response to invalid input. It has several public attributes:

msg:

The message, without values substituted. For instance, if you want HTML quoting of values, you can apply that.

substituteArgs:

The arguments (a dictionary) to go with msg.

str(self):

The message describing the error, with values substituted.

value:

The offending (invalid) value.

state:

The state that went with this validator. This is an application-specific object.

error_list:

If this was a compound validator that takes a repeating value, and sub-validator(s) had errors, then this is a list of those exceptions. The list will be the same length as the number of values – valid values will have None instead of an exception.

error_dict:

Like error_list, but for dictionary compound validators.

class ming.schema.Migrate(old, new, migration_function)

Use when migrating from one Schema to another.

The validate() method first tries to apply the new SchemaItem and if it fails tries the old SchemaItem. If the new fails but the old succeeds the migration_function will be called to upgrade the value from the old schema to the new one.

This is also used by Ming to perform migrations on whole documents through the version_of attribute.

classmethod obj_to_list(key_name, value_name=None)

Factory Method that creates migration functions to convert a dictionary to list of objects.

Migration function will go from object { key: value } to list [ { key_name: key, value_name: value} ].

If value_name is None, then value must be an object which will be expanded in the resulting object itself: [ { key_name: key, **value } ].

validate(value, **kw)

First tries validation against new and if it fails applies migrate_function.

The migrate_function is applied only if old validation succeeds, this is to ensure that we are not actually facing a corrupted value.

If old validation fails, the method just raises the validation error.

class ming.schema.NumberDecimal(precision=None, rounding='ROUND_HALF_DOWN', **kwargs)

Validates value is compatible with bson.Decimal128.

Useful for financial data that need arbitrary precision.

The argument precision specifies the number of decimal digits to evaluate. Defaults to 6.

The argument rounding specifies the kind of rounding to be performed. Valid values are decimal.ROUND_DOWN, decimal.ROUND_HALF_UP, decimal.ROUND_HALF_EVEN, decimal.ROUND_CEILING, decimal.ROUND_FLOOR, decimal.ROUND_UP, decimal.ROUND_HALF_DOWN, decimal.ROUND_05UP. Defaults to decimal.ROUND_HALF_DOWN.

Parameters:

  • required (bool) – if True and this field is missing, an Invalid exception will be raised

  • if_missing (value or callable) – provides a default value for this field if the field is missing

_validate(value, **kw)

Performs actual validation.

Subclasses are expected to override this method to provide the actual validation.

The default implementation leaves the value as is.

type = (<class 'int'>, <class 'float'>, <class 'decimal.Decimal'>, <class 'bson.decimal128.Decimal128'>)

Expected Type of the validated value.

class ming.schema.Object(fields=None, required=False, if_missing=())

Used for dict-like validation.

It validates all the values inside the dictionary and converts it to a ming.base.Object.

Also ensures that the incoming object does not have any extra keys.

Parameters:

  • required (bool) – if True and this field is missing, an Invalid exception will be raised

  • if_missing (value or callable) – provides a default value for this field if the field is missing

_validate(d, allow_extra=False, strip_extra=False)

Performs actual validation.

Subclasses are expected to override this method to provide the actual validation.

The default implementation leaves the value as is.

if_missing()

Missing is a sentinel used to indicate a missing key or missing keyword argument (used since None sometimes has meaning)

class ming.schema.ObjectId(required=(), if_missing=())

Validates value is a bson.ObjectId.

If value is a string that represents an ObjectId it gets converted to an ObjectId.

If the ObjectId is not provided (or it’s Missing) a new one gets generated. To override this behaviour pass if_missing=None to the schema constructor:

>>> schema.ObjectId().validate(schema.Missing)
ObjectId('55d5df957ab71c0a5c3647bd')
>>> schema.ObjectId(if_missing=None).validate(schema.Missing)
None
Parameters:

  • required (bool) – if True and this field is missing, an Invalid exception will be raised

  • if_missing (value or callable) – provides a default value for this field if the field is missing

_validate(value, **kw)

Performs actual validation.

Subclasses are expected to override this method to provide the actual validation.

The default implementation leaves the value as is.

if_missing()

Provides a bson.ObjectId as default

class ming.schema.OneOf(*options, **kwargs)

Expects validated value to be one of options.

This is often used to validate against Enums.

Parameters:

  • required (bool) – if True and this field is missing, an Invalid exception will be raised

  • if_missing (value or callable) – provides a default value for this field if the field is missing

_validate(value, **kw)

Performs actual validation.

Subclasses are expected to override this method to provide the actual validation.

The default implementation leaves the value as is.

class ming.schema.ParticularScalar(**kw)

Specializes Scalar to also check for a specific type.

This is usually not directly used, but its what other validators rely on to implement their behaviour.

Parameters:

  • required (bool) – if True and this field is missing, an Invalid exception will be raised

  • if_missing (value or callable) – provides a default value for this field if the field is missing

_validate(value, **kw)

Performs actual validation.

Subclasses are expected to override this method to provide the actual validation.

The default implementation leaves the value as is.

type = ()

Expected Type of the validated value.

class ming.schema.Scalar(required=(), if_missing=())

Validate that a value is NOT an array or dict.

This is used to validate single values in MongoDB Documents.

Parameters:

  • required (bool) – if True and this field is missing, an Invalid exception will be raised

  • if_missing (value or callable) – provides a default value for this field if the field is missing

_validate(value, **kw)

Performs actual validation.

Subclasses are expected to override this method to provide the actual validation.

The default implementation leaves the value as is.

if_missing = None
class ming.schema.SchemaItem

Basic Schema enforcement validation.

The validate() method is called when a record is loaded from the DB or saved to it.

It should return a “validated” object, raising a Invalid exception if the object is invalid. If it returns Missing, the field will be stripped from its parent object.

This is just the base class for schema validation. When implementing your own schema validation for a Ming Field you probably want to subclass FancySchemaItem.

classmethod make(field, *args, **kwargs)

Factory method for schemas based on a python type.

This accepts a python type as its argument and creates the appropriate SchemaItem that validates it.

Accepted arguments are:

  • int - int or long

  • str - string or unicode

  • float - float, int, or long

  • bool - boolean value

  • datetime - datetime.datetime object

  • None - Anything

  • [] - Array of Anything objects

  • [type] - array of objects of type “type”

  • { fld: type… } - dict-like object with field “fld” of type “type”

  • { type: type… } - dict-like object with fields of type “type”

  • anything else (e.g. literal values), must match exactly

*args and **kwargs are passed on to the specific class of SchemaItem created.

validate(d, **kw)

Validate an object or raise an Invalid exception.

Default implementation just raises NotImplementedError

class ming.schema.String(**kw)

Validates value is str or unicode string

Parameters:

  • required (bool) – if True and this field is missing, an Invalid exception will be raised

  • if_missing (value or callable) – provides a default value for this field if the field is missing

type = (<class 'str'>,)

Expected Type of the validated value.

class ming.schema.Value(value, **kw)

Checks that validated value is exactly value

Parameters:

  • required (bool) – if True and this field is missing, an Invalid exception will be raised

  • if_missing (value or callable) – provides a default value for this field if the field is missing

_validate(value, **kw)

Performs actual validation.

Subclasses are expected to override this method to provide the actual validation.

The default implementation leaves the value as is.

if_missing = None