Skip to main content

Serializers for SQLAlchemy models.

Project description

Serialchemy

https://img.shields.io/travis/ESSS/serialchemy.svg https://ci.appveyor.com/api/projects/status/github/ESSS/serialchemy?branch=master https://codecov.io/gh/ESSS/serialchemy/branch/master/graph/badge.svg https://img.shields.io/readthedocs/pip.svg

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.

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.3.0.tar.gz (21.6 kB view hashes)

Uploaded Source

Built Distribution

serialchemy-0.3.0-py2.py3-none-any.whl (23.1 kB view hashes)

Uploaded Python 2 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