API Reference

Core

marshmallow_sqlalchemy.fields_for_model =func(...)

marshmallow_sqlalchemy.property2field =func(...)

marshmallow_sqlalchemy.column2field =func(...)

marshmallow_sqlalchemy.field_for =func(...)

exception marshmallow_sqlalchemy.ModelConversionError

Raised when an error occurs in converting a SQLAlchemy construct to a marshmallow object.

class marshmallow_sqlalchemy.ModelConverter(schema_cls=None)

Class that converts a SQLAlchemy model into a dictionary of corresponding marshmallow Fields.

class marshmallow_sqlalchemy.ModelSchema(*args, **kwargs)

Base class for SQLAlchemy model-based Schemas.

Example:

from marshmallow_sqlalchemy import ModelSchema
from mymodels import User, session

class UserSchema(ModelSchema):
    class Meta:
        model = User

schema = UserSchema()

user = schema.load({'name': 'Bill'}, session=session)
existing_user = schema.load({'name': 'Bill'}, instance=User.query.first())

Parameters

• session – Optional SQLAlchemy session; may be overridden in load.

• instance – Optional existing instance to modify; may be overridden in load.

Deprecated since version 0.22.0: Use SQLAlchemyAutoSchema instead.

OPTIONS_CLASS

alias of ModelSchemaOpts

class marshmallow_sqlalchemy.ModelSchemaOpts(meta, *args, **kwargs)

Options class for ModelSchema. Adds the following options:

• model: The SQLAlchemy model to generate the Schema from (required).

• load_instance: Whether to load model instances.

• sqla_session: SQLAlchemy session to be used for deserialization.

  This is only needed when load_instance is True. You can also pass a session to the Schema’s load method.

• transient: Whether to load model instances in a transient state (effectively ignoring the session).

  Only relevant when load_instance is True.

• include_fk: Whether to include foreign fields; defaults to False.

• include_relationships: Whether to include relationships; defaults to True.

• model_converter: ModelConverter class to use for converting the SQLAlchemy model to

  marshmallow fields.

class marshmallow_sqlalchemy.SQLAlchemyAutoSchema(*args, **kwargs)

Schema that automatically generates fields from the columns of

a SQLAlchemy model or table.

Example:

from marshmallow_sqlalchemy import SQLAlchemyAutoSchema, auto_field

from mymodels import User

class UserSchema(SQLAlchemyAutoSchema):
    class Meta:
        model = User
        # OR
        # table = User.__table__

    created_at = auto_field(dump_only=True)

OPTIONS_CLASS

alias of SQLAlchemyAutoSchemaOpts

class marshmallow_sqlalchemy.SQLAlchemyAutoSchemaOpts(meta, *args, **kwargs)

Options class for SQLAlchemyAutoSchema. Has the same options as SQLAlchemySchemaOpts, with the addition of:

• include_fk: Whether to include foreign fields; defaults to False.

• include_relationships: Whether to include relationships; defaults to False.

class marshmallow_sqlalchemy.SQLAlchemySchema(*args, **kwargs)

Schema for a SQLAlchemy model or table. Use together with auto_field to generate fields from columns.

Example:

from marshmallow_sqlalchemy import SQLAlchemySchema, auto_field

from mymodels import User

class UserSchema(SQLAlchemySchema):
    class Meta:
        model = User

    id = auto_field()
    created_at = auto_field(dump_only=True)
    name = auto_field()

OPTIONS_CLASS

alias of SQLAlchemySchemaOpts

class marshmallow_sqlalchemy.SQLAlchemySchemaOpts(meta, *args, **kwargs)

Options class for SQLAlchemySchema. Adds the following options:

• model: The SQLAlchemy model to generate the Schema from (mutually exclusive with table).

• table: The SQLAlchemy table to generate the Schema from (mutually exclusive with model).

• load_instance: Whether to load model instances.

• sqla_session: SQLAlchemy session to be used for deserialization.

  This is only needed when load_instance is True. You can also pass a session to the Schema’s load method.

• transient: Whether to load model instances in a transient state (effectively ignoring the session).

  Only relevant when load_instance is True.

• model_converter: ModelConverter class to use for converting the SQLAlchemy model to marshmallow fields.

class marshmallow_sqlalchemy.TableSchema(*, only: Union[Sequence[str], Set[str]] = None, exclude: Union[Sequence[str], Set[str]] = (), many: bool = False, context: Dict = None, load_only: Union[Sequence[str], Set[str]] = (), dump_only: Union[Sequence[str], Set[str]] = (), partial: Union[bool, Sequence[str], Set[str]] = False, unknown: str = None)

Base class for SQLAlchemy model-based Schemas.

Example:

from marshmallow_sqlalchemy import TableSchema
from mymodels import engine, users

class UserSchema(TableSchema):
    class Meta:
        table = users

schema = UserSchema()

select = users.select().limit(1)
user = engine.execute(select).fetchone()
serialized = schema.dump(user)

Deprecated since version 0.22.0: Use SQLAlchemyAutoSchema instead.

OPTIONS_CLASS

alias of TableSchemaOpts

class marshmallow_sqlalchemy.TableSchemaOpts(meta, *args, **kwargs)

Options class for TableSchema. Adds the following options:

• table: The SQLAlchemy table to generate the Schema from (required).

• model_converter: ModelConverter class to use for converting the SQLAlchemy table to

  marshmallow fields.

• include_fk: Whether to include foreign fields; defaults to False.

marshmallow_sqlalchemy.auto_field(column_name: str = None, *, model: sqlalchemy.ext.declarative.api.DeclarativeMeta = None, table: sqlalchemy.sql.schema.Table = None, **kwargs)

Mark a field to autogenerate from a model or table.

Parameters

• column_name – Name of the column to generate the field from. If None, matches the field name. If attribute is unspecified, attribute will be set to the same value as column_name.

• model – Model to generate the field from. If None, uses model specified on class Meta.

• table – Table to generate the field from. If None, uses table specified on class Meta.

• kwargs – Field argument overrides.

Fields

class marshmallow_sqlalchemy.fields.Nested(nested: Union[marshmallow.base.SchemaABC, type, str, Callable[[], marshmallow.base.SchemaABC]], *, default: Any = <marshmallow.missing>, only: Union[Sequence[str], Set[str]] = None, exclude: Union[Sequence[str], Set[str]] = (), many: bool = False, unknown: str = None, **kwargs)

Nested field that inherits the session from its parent.

_deserialize(*args, **kwargs)

Same as Field._deserialize() with additional partial argument.

Parameters

partial (bool|tuple) – For nested schemas, the partial parameter passed to Schema.load.

Changed in version 3.0.0: Add partial parameter.

class marshmallow_sqlalchemy.fields.Related(column=None, **kwargs)

Related data represented by a SQLAlchemy relationship. Must be attached to a Schema class whose options includes a SQLAlchemy model, such as ModelSchema.

Parameters

columns (list) – Optional column names on related model. If not provided, the primary key(s) of the related model will be used.

_deserialize(value, *args, **kwargs)

Deserialize a serialized value to a model instance.

If the parent schema is transient, create a new (transient) instance. Otherwise, attempt to find an existing instance in the database. :param value: The value to deserialize.

_get_existing_instance(query, value)

Retrieve the related object from an existing instance in the DB.

Parameters

• query – A SQLAlchemy Query object.

• value – The serialized value to mapto an existing instance.

Raises

NoResultFound – if there is no matching record.

_serialize(value, attr, obj)

Serializes value to a basic Python datatype. Noop by default. Concrete Field classes should implement this method.

Example:

class TitleCase(Field):
    def _serialize(self, value, attr, obj, **kwargs):
        if not value:
            return ''
        return str(value).title()

Parameters

• value – The value to be serialized.

• attr (str) – The attribute or key on the object to be serialized.

• obj (object) – The object the value was pulled from.

• kwargs (dict) – Field-specific keyword arguments.

Returns

The serialized value

class marshmallow_sqlalchemy.fields.RelatedList(cls_or_instance: Union[marshmallow.fields.Field, type], **kwargs)

get_value(obj, attr, accessor=None)

Return the value for a given key from an object.

Parameters

• obj (object) – The object to get the value from.

• attr (str) – The attribute/key in obj to get the value from.

• accessor (callable) – A callable used to retrieve the value of attr from the object obj. Defaults to marshmallow.utils.get_value.

marshmallow_sqlalchemy.fields.get_primary_keys(model)

Get primary key properties for a SQLAlchemy model.

Parameters

model – SQLAlchemy model class