In order to get started with ColanderAlchemy, you can either use colanderalchemy.setup_schema() to automatically create and attach a schema to a mapped class for you, or else you can use colanderalchemy.SQLAlchemySchemaNode to have more control over the auto-generated schema.
The easiest way to get going is to set up an SQLAlchemy event listener. The colanderalchemy.setup_schema() method is designed to be attached to the mapper_configured event:
from sqlalchemy import event from colanderalchemy import setup_schema event.listen(mapper, 'mapper_configured', setup_schema)
Now, once you configure any mapped class, you’ll automatically get a mapped Colander schema on the class as the attribute __colanderalchemy__. Keep in mind that you should configure the event listener as soon as possible in your application, especially if you’re using declarative definitions.
By associating ColanderAlchemy configuration with your mapped class, its columns, and its relationships, you can tell ColanderAlchemy how to generate each and every part of your mapped schema - including things like titles, descriptions, preparers, validators, widgets, and more.
Check out Configuring within SQLAlchemy models for more information on how.
Beyond the event listener methodology above, you can use colanderalchemy.setup_schema() manually. Simply pass it a SQLAlchemy mapped class like so:
from sqlalchemy import Column, Integer, String, Text from sqlalchemy.ext.declarative import declarative_base from colanderalchemy import setup_schema Base = declarative_base() class SomeClass(Base): __tablename__ = 'some_table' id = Column(Integer, primary_key=True) name = Column(String(50)) biography = Column(Text()) setup_schema(None, SomeClass) SomeClass.__colanderalchemy__ #A Colander schema for you to use
If you already have a mapped class available, you can just pass it as is - you don’t need to redefine another schema.
Also, if you’d like even more control over your generated schema, then use colanderalchemy.SQLAlchemySchemaNode directly like so:
from colanderalchemy import SQLAlchemySchemaNode from my.project import SomeClass schema = SQLAlchemySchemaNode(SomeClass, includes=['name', 'biography'], excludes=['id'], title='Some class')
Note the various arguments you can pass when creating your mapped schema - you have full control over how the schema is generated and what fields are included, which are excluded, and more. See the colanderalchemy.SQLAlchemySchemaNode API documentation for more information. For more information you should read the section Examples to see how use ColanderAlchemy.
In either situation, you can now pass the resulting Colander schema to anything that needs it. For instance, this works well with Deform and you can read more about this later in this documentation: Examples: using ColanderAlchemy with Deform.
How it works¶
ColanderAlchemy auto-generates Colander schemas following these rules:
The type of the schema is colander.MappingSchema,
The schema has a colander.SchemaNode for each sqlalchemy.Column in the mapped object:
- The type of colander.SchemaNode is based on the type of sqlalchemy.Column
- The colander.SchemaNode has a validator if the sqlalchemy.Column is an instance of either sqlalchemy.types.Enum or sqlalchemy.types.String. Enum is checked with colander.OneOf and String is checked with colander.Length
- colander.SchemaNode has missing=colander.required except for the when default is set, nullable=True, there’s a server_default, or the field is an auto incrementing integer used as part of a primary key. Essentially it’s required unless SQLAlchemy can derive a value for you automatically if it’s missing.
- colander.SchemaNode has default=colander.null unless there is a column default which is a static scalar value. Callable function defaults and server defaults are ignored for the purposes of generating a colander schema
The schema has a colander.SchemaNode for each relationship (sqlalchemy.orm.relationship or those from sqlalchemy.orm.backref) in the mapped object:
The colander.SchemaNode has missing=None
- The type of colander.SchemaNode is:
- A colander.Mapping for ManyToOne and OneToOne relationships
- A colander.Sequence of colander.Mapping for ManyToMany and OneToMany relationships
For both kind of relationships, the colander.Mapping is built using rule 2 on the mapped class referenced by relationship.
Read the section Customization to see how change these rules and how to customize the Colander schema returned by ColanderAlchemy.