Skip to main content

Serializers for SQLAlchemy models.

Project description

https://img.shields.io/pypi/v/serialchemy.svg https://img.shields.io/pypi/pyversions/serialchemy.svg https://github.com/ESSS/serialchemy/workflows/build/badge.svg https://codecov.io/gh/ESSS/serialchemy/branch/master/graph/badge.svg https://img.shields.io/readthedocs/serialchemy.svg https://sonarcloud.io/api/project_badges/measure?project=ESSS_serialchemy&metric=alert_status

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"},
}
Extend Polymorphic Serializer

One of the possibilities is to serialize SQLalchemy joined table inheritance and it child tables as well. To do such it’s necessary to set a variable with the desired model class name. Take this Employee class with for instance and let us assume it have a joined table inheritance:

class Employee(Base):
    ...
    type = Column(String(50))

    __mapper_args__ = {"polymorphic_identity": "employee", "polymorphic_on": type}


class Engineer(Employee):
    __tablename__ = "Engineer"
    id = Column(Integer, ForeignKey("employee.id"), primary_key=True)
    association = relationship(Association)

    __mapper_args__ = {
        "polymorphic_identity": "engineer",
    }

To use a extended ModelSerializer class on the Engineer class, you should create the serializer as it follows:

class EmployeeSerializer(
    PolymorphicModelSerializer
):  # Since this class will be polymorphic

    password = Field(load_only=True)
    company = NestedModelField(Company)


class EngineerSerializer(EmployeeSerializer):
    __model_class__ = Engineer  # This is the table Serialchemy will refer to
    association = NestedModelField(Association)

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.4.0 (2013-12-11)

  • Fix to get model attribute name instead of table column name on polymorphic serializer

  • Extends the PolymorphicModelSerializer to accept also column descriptors when searching for the polymorphic column key.

  • Add support for serialization of Python Enums

  • Change PolymorphicModelSerializer to support inherited models of inherited models

  • Change Field to use a default serializer for not None values

  • Added support for sqlalchemy 1.4

  • Add EnumKeySerializer

History

0.4.0 (2013-12-11)

  • Fix to get model attribute name instead of table column name on polymorphic serializer

  • Extends the PolymorphicModelSerializer to accept also column descriptors when searching for the polymorphic column key.

  • Add support for serialization of Python Enums

  • Change PolymorphicModelSerializer to support inherited models of inherited models

  • Change Field to use a default serializer for not None values

  • Added support for sqlalchemy 1.4

  • Add EnumKeySerializer

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.

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

serialchemy-0.4.0.tar.gz (27.1 kB view hashes)

Uploaded Source

Built Distribution

serialchemy-0.4.0-py3-none-any.whl (30.7 kB view hashes)

Uploaded Python 3

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page