ColanderAlchemy API

class colanderalchemy.SQLAlchemySchemaNode(class_, includes=None, excludes=None, overrides=None, unknown='ignore', **kw)

Build a Colander Schema based on the SQLAlchemy mapped class.

__init__(class_, includes=None, excludes=None, overrides=None, unknown='ignore', **kw)

Initialise the given mapped schema according to options provided.

Arguments/Keywords

class_

An SQLAlchemy mapped class that you want a Colander schema to be generated for.

To declaratively customise Colander SchemaNode options, add a __colanderalchemy_config__ attribute to your initial class declaration like so:

class MyModel(Base):
    __colanderalchemy_config__ = {'title': 'Custom title',
                                  'description': 'Sample'}
    ...

includes

Iterable of attributes to include from the resulting schema. Using this option will ensure only the explicitly mentioned attributes are included and all others are excluded.

includes can be included in the __colanderalchemy_config__ dict on a class to declaratively customise the resulting schema. Explicitly passing this option as an argument takes precedence over the declarative configuration.

Incompatible with excludes. Default: None.

excludes

Iterable of attributes to exclude from the resulting schema. Using this option will ensure only the explicitly mentioned attributes are excluded and all others are included.

excludes can be included in the __colanderalchemy_config__ dict on a class to declaratively customise the resulting schema. Explicitly passing this option as an argument takes precedence over the declarative configuration.

Incompatible with includes. Default: None.

overrides

A dict-like structure that consists of schema attributes to override imperatively. Values provides as part of overrides will take precendence over all others.

overrides can be included in the __colanderalchemy_config__ dict on a class to declaratively customise the resulting schema. Explicitly passing this option as an argument takes precedence over the declarative configuration.

Default: None.

unknown

Represents the unknown argument passed to colander.Mapping.

The unknown argument passed to colander.Mapping, which defaults to 'ignore', can be set by adding an unknown key to the __colanderalchemy_config__ dict. For example:

class MyModel(Base):
    __colanderalchemy_config__ = {'title': 'Custom title',
                                  'description': 'Sample',
                                  'unknown': 'preserve'}
    ...

In contrast to the other options in __colanderalchemy_config__, the unknown option is not directly passed to colander.SchemaNode. Instead, it is passed to the colander.Mapping object, which itself is passed to colander.SchemaNode.

From Colander:

unknown controls the behavior of this type when an unknown key is encountered in the cstruct passed to the deserialize method of this instance.

Default: ‘ignore’

**kw

Represents all other options able to be passed to a colander.SchemaNode. Keywords passed will influence the resulting mapped schema accordingly (for instance, passing title='My Model' means the returned schema will have its title attribute set accordingly.

See http://docs.pylonsproject.org/projects/colander/en/latest/basics.html for more information.

dictify(obj)

Return a dictified version of obj using schema information.

The schema will be used to choose what attributes will be included in the returned dict.

Thus, the return value of this function is suitable for consumption as a Deform appstruct and can be used to pre-populate forms in this specific use case.

Arguments/Keywords

obj

An object instance to be converted to a dict structure. This object should conform to the given schema. For example, obj should be an instance of this schema’s mapped class, an instance of a sub-class, or something that has the same attributes.

objectify(dict_, context=None)

Return an object representing dict_ using schema information.

The schema will be used to choose how the data in the structure will be restored into SQLAlchemy model objects. The incoming dict_ structure corresponds with one that may be created from the dictify() method on the same schema. Relationships and backrefs will be restored in accordance with their specific configurations.

The return value of this function will be suitable for adding into an SQLAlchemy session to be committed to a database.

Arguments/Keywords

dict_

An dictionary or similar data structure to be converted to a an SQLAlchemy object. This data structure should conform to the given schema. For example, dict_ should be an appstruct (such as that returned from a Deform form submission), result of a call to this schema’s dictify() method, or a matching structure with relevant keys and nesting, if applicable.

context

Optional keyword argument that, if supplied, becomes the base object, with attributes and objects being applied to it.

Specify a context in the situation where you already have an object that exists already, such as when you have a pre-existing instance of an SQLAlchemy model. If your model is already bound to a session, then this facilitates directly updating the database – just pass in your dict or appstruct, and your existing SQLAlchemy instance as context and this method will update all of its attributes.

This is a perfect fit for something like a CRUD environment.

Default: None. Defaults to instantiating a new instance of the mapped class associated with this schema.

get_schema_from_column(prop, overrides)

Build and return a colander.SchemaNode for a given Column.

This method uses information stored in the column within the info that was passed to the Column on creation. This means that Colander options can be specified declaratively in SQLAlchemy models using the info argument that you can pass to sqlalchemy.Column.

Arguments/Keywords

prop

A given sqlalchemy.orm.properties.ColumnProperty instance that represents the column being mapped.

overrides

A dict-like structure that consists of schema attributes to override imperatively. Values provides as part of overrides will take precendence over all others.

get_schema_from_relationship(prop, overrides)

Build and return a colander.SchemaNode for a relationship.

The mapping process will translate one-to-many and many-to-many relationships from SQLAlchemy into a Sequence of Mapping nodes in Colander, and translate one-to-one and many-to-one relationships into a Mapping node in Colander. The related class involved in the relationship will be recursively mapped by ColanderAlchemy as part of this process, following the same mapping process.

This method uses information stored in the relationship within the info that was passed to the relationship on creation. This means that Colander options can be specified declaratively in SQLAlchemy models using the info argument that you can pass to sqlalchemy.orm.relationship().

For all relationships, the settings will only be applied to the outer Sequence or Mapping. To customise the inner schema node, create the attribute __colanderalchemy_config__ on the related model with a dict-like structure corresponding to the Colander options that should be customised.

Arguments/Keywords

prop

A given sqlalchemy.orm.properties.RelationshipProperty instance that represents the relationship being mapped.

overrides

A dict-like structure that consists of schema attributes to override imperatively. Values provides as part of overrides will take precendence over all others. Example keys include children, includes, excludes, overrides.

colanderalchemy.setup_schema(mapper, class_)

Build a Colander schema for class_ and attach it to that class.

This method is designed to be attached to the mapper_configured event from SQLAlchemy.

See http://docs.sqlalchemy.org/en/latest/orm/events.html#sqlalchemy.orm.events.MapperEvents.mapper_configured for more information about event handling.

Arguments/Keywords

mapper

The mapper associated with the given class_. This is typically passed automatically via the SQLAlchemy event handler.

May be specified as None if this method is being called manually.

class_

The SQLAlchemy mapped class. This class may have attributes, related mapped classes (via SQLAlchemy relationships) and the like.