1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
|
**********************
marshmallow-sqlalchemy
**********************
|pypi-package| |build-status| |docs| |marshmallow-support|
Homepage: https://marshmallow-sqlalchemy.readthedocs.io/
`SQLAlchemy <http://www.sqlalchemy.org/>`_ integration with the `marshmallow <https://marshmallow.readthedocs.io/en/latest/>`_ (de)serialization library.
Declare your models
===================
.. code-block:: python
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"))
Base.metadata.create_all(engine)
.. start elevator-pitch
Generate marshmallow schemas
============================
.. code-block:: python
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.
.. code-block:: python
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() <https://docs.sqlalchemy.org/en/latest/orm/mapping_api.html>`_ will run too soon and fail.
(De)serialize your data
=======================
.. code-block:: python
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
==========
.. code-block:: shell-session
$ pip install -U marshmallow-sqlalchemy
Requires Python >= 3.9, marshmallow >= 3.18.0, and SQLAlchemy >= 1.4.40.
.. end elevator-pitch
Documentation
=============
Documentation is available at https://marshmallow-sqlalchemy.readthedocs.io/ .
Project links
=============
- Docs: https://marshmallow-sqlalchemy.readthedocs.io/
- Changelog: https://marshmallow-sqlalchemy.readthedocs.io/en/latest/changelog.html
- Contributing Guidelines: https://marshmallow-sqlalchemy.readthedocs.io/en/latest/contributing.html
- PyPI: https://pypi.python.org/pypi/marshmallow-sqlalchemy
- Issues: https://github.com/marshmallow-code/marshmallow-sqlalchemy/issues
License
=======
MIT licensed. See the bundled `LICENSE <https://github.com/marshmallow-code/marshmallow-sqlalchemy/blob/dev/LICENSE>`_ file for more details.
.. |pypi-package| image:: https://badgen.net/pypi/v/marshmallow-sqlalchemy
:target: https://pypi.org/project/marshmallow-sqlalchemy/
:alt: Latest version
.. |build-status| image:: https://github.com/marshmallow-code/marshmallow-sqlalchemy/actions/workflows/build-release.yml/badge.svg
:target: https://github.com/marshmallow-code/marshmallow-sqlalchemy/actions/workflows/build-release.yml
:alt: Build status
.. |docs| image:: https://readthedocs.org/projects/marshmallow-sqlalchemy/badge/
:target: http://marshmallow-sqlalchemy.readthedocs.io/
:alt: Documentation
.. |marshmallow-support| image:: https://badgen.net/badge/marshmallow/3,4?list=1
:target: https://marshmallow.readthedocs.io/en/latest/upgrading.html
:alt: marshmallow 3|4 compatible
|
