ColanderAlchemy API¶
-
class
colanderalchemy.
SQLAlchemySchemaNode
(class_, includes=None, excludes=None, overrides=None, unknown='ignore', **kw)[source]¶ Build a Colander Schema based on the SQLAlchemy mapped class.
-
__init__
(class_, includes=None, excludes=None, overrides=None, unknown='ignore', **kw)[source]¶ Initialise the given mapped schema according to options provided.
Arguments/Keywords
- class_
An
SQLAlchemy
mapped class that you want aColander
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 precedence 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 tocolander.Mapping
, which defaults to'ignore'
, can be set by adding anunknown
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__
, theunknown
option is not directly passed tocolander.SchemaNode
. Instead, it is passed to thecolander.Mapping
object, which itself is passed tocolander.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, passingtitle='My Model'
means the returned schema will have itstitle
attribute set accordingly.See http://docs.pylonsproject.org/projects/colander/en/latest/basics.html for more information.
-
dictify
(obj)[source]¶ 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)[source]¶ 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 thedictify()
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’sdictify()
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 ascontext
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)[source]¶ 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 thatColander
options can be specified declaratively inSQLAlchemy
models using theinfo
argument that you can pass tosqlalchemy.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 precedence over all others.
-
get_schema_from_relationship
(prop, overrides)[source]¶ 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
ofMapping
nodes in Colander, and translate one-to-one and many-to-one relationships into aMapping
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 thatColander
options can be specified declaratively inSQLAlchemy
models using theinfo
argument that you can pass tosqlalchemy.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 precedence over all others. Example keys includechildren
,includes
,excludes
,overrides
.
-
-
colanderalchemy.
setup_schema
(mapper, class_)[source]¶ 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.