marshmallow-sqlalchemy

SQLAlchemy integration with the marshmallow (de)serialization library.

Release v1.4.2 (Changelog)

---

Declare your models

SQLAlchemy 1.4

import sqlalchemy as sa from sqlalchemy.orm import ( DeclarativeBase, backref, relationship, sessionmaker, ) from marshmallow_sqlalchemy import SQLAlchemySchema, auto_field engine = sa.create_engine("sqlite:///:memory:") Session = sessionmaker(engine) class Base(DeclarativeBase): pass class Author(Base): __tablename__ = "authors" id = sa.Column(sa.Integer, primary_key=True) name = sa.Column(sa.String, nullable=False) def __repr__(self): return f"<Author(name={self.name!r})>" class Book(Base): __tablename__ = "books" id = sa.Column(sa.Integer, primary_key=True) title = sa.Column(sa.String) author_id = sa.Column(sa.Integer, sa.ForeignKey("authors.id")) author = relationship("Author", backref=backref("books")) 

SQLAlchemy 2

import sqlalchemy as sa from sqlalchemy.orm import ( DeclarativeBase, backref, relationship, sessionmaker, mapped_column, Mapped, ) from marshmallow_sqlalchemy import SQLAlchemySchema, auto_field engine = sa.create_engine("sqlite:///:memory:") Session = sessionmaker(engine) class Base(DeclarativeBase): pass class Author(Base): __tablename__ = "authors" id: Mapped[int] = mapped_column(primary_key=True) name: Mapped[str] = mapped_column(nullable=False) def __repr__(self): return f"<Author(name={self.name!r})>" class Book(Base): __tablename__ = "books" id: Mapped[int] = mapped_column(primary_key=True) title: Mapped[str] = mapped_column() author_id: Mapped[int] = mapped_column(sa.ForeignKey("authors.id")) author: Mapped["Author"] = relationship("Author", backref=backref("books")) 

Generate marshmallow schemas

from marshmallow_sqlalchemy import SQLAlchemySchema, auto_field class AuthorSchema(SQLAlchemySchema): class Meta: model = Author load_instance = True # Optional: deserialize to model instances id = auto_field() name = auto_field() books = auto_field() class BookSchema(SQLAlchemySchema): class Meta: model = Book load_instance = True id = auto_field() title = auto_field() author_id = auto_field() 

You can automatically generate fields for a model’s columns using SQLAlchemyAutoSchema. The following schema classes are equivalent to the above.

from marshmallow_sqlalchemy import SQLAlchemyAutoSchema class AuthorSchema(SQLAlchemyAutoSchema): class Meta: model = Author include_relationships = True load_instance = True class BookSchema(SQLAlchemyAutoSchema): class Meta: model = Book include_fk = True load_instance = True 

Make sure to declare Models before instantiating Schemas. Otherwise sqlalchemy.orm.configure_mappers() will run too soon and fail.

(De)serialize your data

author = Author(name="Chuck Paluhniuk") author_schema = AuthorSchema() book = Book(title="Fight Club", author=author) with Session() as session: session.add(author) session.add(book) session.commit() dump_data = author_schema.dump(author) print(dump_data) # {'id': 1, 'name': 'Chuck Paluhniuk', 'books': [1]} with Session() as session: load_data = author_schema.load(dump_data, session=session) print(load_data) # <Author(name='Chuck Paluhniuk')> 

Get it now

$ pip install -U marshmallow-sqlalchemy 

Requires Python >= 3.9, marshmallow >= 3.18.0, and SQLAlchemy >= 1.4.40.

Learn

Learn

• Recipes
  • Base Schema I
  • Base Schema II
  • Using Related to serialize relationships
  • Introspecting generated fields
  • Overriding generated fields
  • Automatically generating schemas for SQLAlchemy models
  • Smart Nested field
  • Transient object creation
  • Controlling instance loading

API reference

API reference

• Top-level API
• Fields

Project info

Project info

• Changelog
• Contributing guidelines
• Authors
• License