Metadata-Version: 2.1
Name: serialchemy
Version: 0.20.0rc6.post4
Summary: Serializers for SQLAlchemy models.
Home-page: http://github.com/ESSS/serialchemy
Author: ESSS
Author-email: foss@esss.co
License: MIT license
Keywords: serialchemy
Platform: UNKNOWN
Classifier: Development Status :: 2 - Pre-Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3.6
Classifier: Programming Language :: Python :: 3.7
Requires-Python: >=3.6
Requires-Dist: sqlalchemy (>=1.1)
Provides-Extra: docs
Requires-Dist: sphinx (>=1.4) ; extra == 'docs'
Requires-Dist: sphinx-rtd-theme ; extra == 'docs'
Requires-Dist: sphinx-autodoc-typehints ; extra == 'docs'
Provides-Extra: testing
Requires-Dist: codecov ; extra == 'testing'
Requires-Dist: pytest ; extra == 'testing'
Requires-Dist: pytest-cov ; extra == 'testing'
Requires-Dist: pytest-regressions ; extra == 'testing'
Requires-Dist: pre-commit ; extra == 'testing'
Requires-Dist: tox ; extra == 'testing'

======================================================================
Serialchemy
======================================================================

.. TODO: Publish to PyPi
    .. image:: https://img.shields.io/pypi/v/serialchemy.svg
    :target: https://pypi.python.org/pypi/serialchemy
    .. image:: https://img.shields.io/pypi/pyversions/serialchemy.svg
    :target: https://pypi.org/project/serialchemy

.. image:: https://img.shields.io/travis/ESSS/serialchemy.svg
    :target: https://travis-ci.org/ESSS/serialchemy

.. image:: https://ci.appveyor.com/api/projects/status/github/ESSS/serialchemy?branch=master
    :target: https://ci.appveyor.com/project/ESSS/serialchemy/?branch=master&svg=true

.. image:: https://codecov.io/gh/ESSS/serialchemy/branch/master/graph/badge.svg
    :target: https://codecov.io/gh/ESSS/serialchemy

.. image:: https://img.shields.io/readthedocs/pip.svg
    :target: https://serialchemy.readthedocs.io/en/latest/

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 <https://github.com/marshmallow-code/marshmallow-sqlalchemy/issues/67>`_. 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_.

.. _SQLAlchemy: www.sqlalchemy.org
.. _marshmallow-sqlalchemy: http://marshmallow-sqlalchemy.readthedocs.io
.. _marshmallow: https://marshmallow.readthedocs.io
.. _Flask-RESTAlchemy: https://github.com/ESSS/flask-restalchemy

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()

.. _`Generic Types`: https://docs.sqlalchemy.org/en/rel_1_2/core/type_basics.html#generic-types

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`_.

.. _contributing guidelines: https://github.com/ESSS/serialchemy/blob/master/CONTRIBUTING.rst


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.


