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
[source]¶ Raised when an error occurs in converting a SQLAlchemy construct to a marshmallow object.
-
class
marshmallow_sqlalchemy.
ModelConverter
(schema_cls=None)[source]¶ Class that converts a SQLAlchemy model into a dictionary of corresponding marshmallow
Fields
.
-
class
marshmallow_sqlalchemy.
ModelSchema
(*args, **kwargs)[source]¶ 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
marshmallow_sqlalchemy.schema.model_schema.ModelSchemaOpts
-
class
marshmallow_sqlalchemy.
ModelSchemaOpts
(meta, *args, **kwargs)[source]¶ Options class for
ModelSchema
. Adds the following options:model
: The SQLAlchemy model to generate theSchema
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
isTrue
. You can also pass a session to the Schema’sload
method.
transient
: Whether to load model instances in a transient state (effectively ignoring the session).Only relevant when
load_instance
isTrue
.
include_fk
: Whether to include foreign fields; defaults toFalse
.include_relationships
: Whether to include relationships; defaults toTrue
.model_converter
:ModelConverter
class to use for converting the SQLAlchemy model tomarshmallow fields.
-
class
marshmallow_sqlalchemy.
SQLAlchemyAutoSchema
(*args, **kwargs)[source]¶ - 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
marshmallow_sqlalchemy.schema.sqlalchemy_schema.SQLAlchemyAutoSchemaOpts
-
class
marshmallow_sqlalchemy.
SQLAlchemyAutoSchemaOpts
(meta, *args, **kwargs)[source]¶ Options class for
SQLAlchemyAutoSchema
. Has the same options asSQLAlchemySchemaOpts
, with the addition of:
-
class
marshmallow_sqlalchemy.
SQLAlchemySchema
(*args, **kwargs)[source]¶ 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
marshmallow_sqlalchemy.schema.sqlalchemy_schema.SQLAlchemySchemaOpts
-
-
class
marshmallow_sqlalchemy.
SQLAlchemySchemaOpts
(meta, *args, **kwargs)[source]¶ Options class for
SQLAlchemySchema
. Adds the following options:model
: The SQLAlchemy model to generate theSchema
from (mutually exclusive withtable
).table
: The SQLAlchemy table to generate theSchema
from (mutually exclusive withmodel
).load_instance
: Whether to load model instances.sqla_session
: SQLAlchemy session to be used for deserialization.This is only needed when
load_instance
isTrue
. You can also pass a session to the Schema’sload
method.
transient
: Whether to load model instances in a transient state (effectively ignoring the session).Only relevant when
load_instance
isTrue
.
model_converter
:ModelConverter
class to use for converting the SQLAlchemy model to marshmallow fields.
-
class
marshmallow_sqlalchemy.
TableSchema
(*, only: Optional[Union[Sequence[str], Set[str]]] = None, exclude: Union[Sequence[str], Set[str]] = (), many: bool = False, context: Optional[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: Optional[str] = None)[source]¶ 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
marshmallow_sqlalchemy.schema.table_schema.TableSchemaOpts
-
-
class
marshmallow_sqlalchemy.
TableSchemaOpts
(meta, *args, **kwargs)[source]¶ Options class for
TableSchema
. Adds the following options:table
: The SQLAlchemy table to generate theSchema
from (required).model_converter
:ModelConverter
class to use for converting the SQLAlchemy table tomarshmallow fields.
include_fk
: Whether to include foreign fields; defaults toFalse
.
-
marshmallow_sqlalchemy.
auto_field
(column_name: Optional[str] = None, *, model: Optional[sqlalchemy.ext.declarative.api.DeclarativeMeta] = None, table: Optional[sqlalchemy.sql.schema.Table] = None, **kwargs)[source]¶ 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. Ifattribute
is unspecified,attribute
will be set to the same value ascolumn_name
.model – Model to generate the field from. If
None
, usesmodel
specified onclass Meta
.table – Table to generate the field from. If
None
, usestable
specified onclass 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: Optional[Union[Sequence[str], Set[str]]] = None, exclude: Union[Sequence[str], Set[str]] = (), many: bool = False, unknown: Optional[str] = None, **kwargs)[source]¶ Nested field that inherits the session from its parent.
-
class
marshmallow_sqlalchemy.fields.
Related
(column=None, **kwargs)[source]¶ Related data represented by a SQLAlchemy
relationship
. Must be attached to aSchema
class whose options includes a SQLAlchemymodel
, such asModelSchema
.- 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)[source]¶ 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)[source]¶ 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.
-
class
marshmallow_sqlalchemy.fields.
RelatedList
(cls_or_instance: Union[marshmallow.fields.Field, type], **kwargs)[source]¶ -
get_value
(obj, attr, accessor=None)[source]¶ 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 objectobj
. Defaults tomarshmallow.utils.get_value
.
-