| 1 |
SQLAlchemy Serialization Plugin |
| 2 |
------------------------------- |
| 3 |
|
| 4 |
The SQLAlchemy Serialization Plugin allows Litestar to do the work of transforming inbound and outbound data to and from |
| 5 |
SQLAlchemy models. The plugin takes no arguments, simply instantiate it and pass it to your application. |
| 6 |
|
| 7 |
Example |
| 8 |
======= |
| 9 |
|
| 10 |
.. tab-set:: |
| 11 |
|
| 12 |
.. tab-item:: Async |
| 13 |
|
| 14 |
.. literalinclude:: /examples/contrib/sqlalchemy/plugins/sqlalchemy_async_serialization_plugin.py |
| 15 |
:caption: SQLAlchemy Async Serialization Plugin |
| 16 |
:language: python |
| 17 |
:linenos: |
| 18 |
|
| 19 |
.. tab-item:: Sync |
| 20 |
|
| 21 |
.. literalinclude:: /examples/contrib/sqlalchemy/plugins/sqlalchemy_sync_serialization_plugin.py |
| 22 |
:caption: SQLAlchemy Sync Serialization Plugin |
| 23 |
:language: python |
| 24 |
:linenos: |
| 25 |
|
| 26 |
How it works |
| 27 |
============ |
| 28 |
|
| 29 |
The plugin works by defining a :class:`SQLAlchemyDTO <advanced_alchemy.extensions.litestar.dto.SQLAlchemyDTO>` class for each |
| 30 |
handler ``data`` or return annotation that is a SQLAlchemy model, or collection of SQLAlchemy models, that isn't |
| 31 |
otherwise managed by an explicitly defined DTO class. |
| 32 |
|
| 33 |
The following two examples are functionally equivalent: |
| 34 |
|
| 35 |
.. tab-set:: |
| 36 |
|
| 37 |
.. tab-item:: Serialization Plugin |
| 38 |
|
| 39 |
.. literalinclude:: /examples/contrib/sqlalchemy/plugins/sqlalchemy_async_serialization_plugin.py |
| 40 |
:language: python |
| 41 |
:linenos: |
| 42 |
|
| 43 |
.. tab-item:: Data Transfer Object |
| 44 |
|
| 45 |
.. literalinclude:: /examples/contrib/sqlalchemy/plugins/sqlalchemy_async_serialization_dto.py |
| 46 |
:language: python |
| 47 |
:linenos: |
| 48 |
|
| 49 |
During registration, the application recognizes that there is no DTO class explicitly defined and determines that the |
| 50 |
handler annotations are supported by the SQLAlchemy Serialization Plugin. The plugin is then used to generate a DTO |
| 51 |
class for both the ``data`` keyword argument and the return annotation. |
| 52 |
|
| 53 |
Configuring data transfer |
| 54 |
######################### |
| 55 |
|
| 56 |
As the serialization plugin merely defines DTOs for the handler, we can |
| 57 |
:ref:`mark the model fields <dto-marking-fields>` to control the data that we allow in and out of |
| 58 |
our application. |
| 59 |
|
| 60 |
.. tab-set:: |
| 61 |
|
| 62 |
.. tab-item:: Async |
| 63 |
|
| 64 |
.. literalinclude:: /examples/contrib/sqlalchemy/plugins/sqlalchemy_async_serialization_plugin_marking_fields.py |
| 65 |
:caption: SQLAlchemy Async Marking Fields |
| 66 |
:language: python |
| 67 |
:linenos: |
| 68 |
:emphasize-lines: 9,23,28 |
| 69 |
|
| 70 |
.. tab-item:: Sync |
| 71 |
|
| 72 |
.. literalinclude:: /examples/contrib/sqlalchemy/plugins/sqlalchemy_sync_serialization_plugin_marking_fields.py |
| 73 |
:caption: SQLAlchemy Sync Marking Fields |
| 74 |
:language: python |
| 75 |
:linenos: |
| 76 |
:emphasize-lines: 9,23,28 |
| 77 |
|
| 78 |
In the above example, a new attribute called ``super_secret_value`` has been added to the model, and a value set for it |
| 79 |
in the handler. However, due to "marking" the field as "private", when the model is serialized, the value is not present |
| 80 |
in the response. |