serialchemy 0.20.0rc6.post13

Serializers for SQLAlchemy models.

Serialchemy

SQLAlchemy model serialization.

Motivation

Serialchemy was developed as a module of Flask-RESTAlchemy, a lib to create Restful APIs using Flask and SQLAlchemy. We first tried marshmallow-sqlalchemy, probably the most well-known lib for SQLAlchemy model serialization, but we faced issues related to nested models. We also think that is possible to build a simpler and more maintainable solution by having SQLAlchemy in mind from the ground up, as opposed to marshmallow-sqlalchemy that had to be designed and built on top of marshmallow.

How to Use it

Serializing Generic Types

Suppose we have an Employee SQLAlchemy model declared:

class Employee(Base):
    __tablename__ = 'Employee'

    id = Column(Integer, primary_key=True)
    fullname = Column(String)
    admission = Column(DateTime, default=datetime(2000, 1, 1))
    company_id = Column(ForeignKey('Company.id'))
    company = relationship(Company)
    company_name = column_property(
        select([Company.name]).where(Company.id == company_id)
    )
    password = Column(String)

Generic Types are automatically serialized by ModelSerializer:

from serialchemy import ModelSerializer

emp = Employee(fullname='Roberto Silva', admission=datetime(2019, 4, 2))

serializer = ModelSerializer(Employee)
serializer.dump(emp)

>> {'id': None,
    'fullname': 'Roberto Silva',
    'admission': '2019-04-02T00:00:00',
    'company_id': None,
    'company_name': None,
    'password': None
    }

New items can be deserialized by the same serializer:

new_employee = {'fullname': 'Jobson Gomes', 'admission': '2018-02-03'}
serializer.load(new_employee)
>> <Employee object at 0x000001C119DE3940>

Serializers do not commit into the database. You must do this by yourself:

emp = serializer.load(new_employee)
session.add(emp)
session.commit()

Custom Serializers

For anything beyond Generic Types we must extend the ModelSerializer class:

class EmployeeSerializer(ModelSerializer):

    password = Field(load_only=True)     # passwords should be only deserialized
    company = NestedModelField(Company)  # dump company as nested object

serializer = EmployeeSerializer(Employee)
serializer.dump(emp)

>> {'id': 1,
    'fullname': 'Roberto Silva',
    'admission': '2019-04-02T00:00:00',
    'company': {'id': 3,
                'name': 'Acme Co'
               }
    }

Contributing

For guidance on setting up a development environment and how to make a contribution to serialchemy, see the contributing guidelines.

Release

A reminder for the maintainers on how to make a new release.

Note that the VERSION should folow the semantic versioning as X.Y.Z Ex.: v1.0.5

1. Create a release-VERSION branch from upstream/master.

2. Update CHANGELOG.rst.

3. Push a branch with the changes.

4. Once all builds pass, push a VERSION tag to upstream.

5. Merge the PR.

History

0.3.0 (2019-17-07)

• Add the composite fields to list of properties of model, to serialize that fields if it type is in EXTRA_SERIALIZERS.

• Fix error for SQLAlchemy composite attributes

• Added free functions dump and load so users can quickly dump a SQLAlchemy model without having to instancialize ModelSerializer.

0.2.0 (2019-03-22)

• Fix: Error when deserializing of nested models when SQLAlchemy model primary key attribute name differs from the column name

• Allow EXTRA_SERIALIZERS to be defined in runtime

• Check if a session was given when serializing/deserializing nested fields

0.1.0 (2019-02-12)

• First release on PyPI.