#################################################### SQLAthanor ####################################################

Serialization/De-serialization Support for the SQLAlchemy Declarative ORM

.. image:: https://sqlathanor.readthedocs.io/en/latest/_static/sqlathanor-logo-200x100.png :align: right :alt: SQLAthanor - Serialization/De-serialization for SQLAlchemy :target: https://sqlathanor.readthedocs.io/en/latest/index.html

.. list-table:: :widths: 10 90 :header-rows: 1

• • Branch
  • Unit Tests

• • latest <https://github.com/insightindustry/sqlathanor/tree/master>_

  • .. image:: https://travis-ci.com/insightindustry/sqlathanor.svg?branch=master :target: https://travis-ci.com/insightindustry/sqlathanor :alt: Build Status (Travis CI)

    .. image:: https://codecov.io/gh/insightindustry/sqlathanor/branch/master/graph/badge.svg :target: https://codecov.io/gh/insightindustry/sqlathanor :alt: Code Coverage Status (Codecov)

    .. image:: https://readthedocs.org/projects/sqlathanor/badge/?version=latest :target: http://sqlathanor.readthedocs.io/en/latest/?badge=latest :alt: Documentation Status (ReadTheDocs)

• • v.0.7 <https://github.com/insightindustry/sqlathanor/tree/v.0.7.0>_

  • .. image:: https://travis-ci.com/insightindustry/sqlathanor.svg?branch=v.0.7.0 :target: https://travis-ci.com/insightindustry/sqlathanor :alt: Build Status (Travis CI)

    .. image:: https://codecov.io/gh/insightindustry/sqlathanor/branch/v.0.7.0/graph/badge.svg :target: https://codecov.io/gh/insightindustry/sqlathanor :alt: Code Coverage Status (Codecov)

    .. image:: https://readthedocs.org/projects/sqlathanor/badge/?version=v.0.7.0 :target: http://sqlathanor.readthedocs.io/en/latest/?badge=v.0.7.0 :alt: Documentation Status (ReadTheDocs)

• • v.0.6 <https://github.com/insightindustry/sqlathanor/tree/v.0.6.0>_

  • .. image:: https://travis-ci.com/insightindustry/sqlathanor.svg?branch=v.0.6.0 :target: https://travis-ci.com/insightindustry/sqlathanor :alt: Build Status (Travis CI)

    .. image:: https://codecov.io/gh/insightindustry/sqlathanor/branch/v.0.6.0/graph/badge.svg :target: https://codecov.io/gh/insightindustry/sqlathanor :alt: Code Coverage Status (Codecov)

    .. image:: https://readthedocs.org/projects/sqlathanor/badge/?version=v.0.6.0 :target: http://sqlathanor.readthedocs.io/en/latest/?badge=v.0.6.0 :alt: Documentation Status (ReadTheDocs)

• • v.0.5 <https://github.com/insightindustry/sqlathanor/tree/v.0.5.1>_

  • .. image:: https://travis-ci.com/insightindustry/sqlathanor.svg?branch=v.0.5.1 :target: https://travis-ci.com/insightindustry/sqlathanor :alt: Build Status (Travis CI)

    .. image:: https://codecov.io/gh/insightindustry/sqlathanor/branch/v.0.5.1/graph/badge.svg :target: https://codecov.io/gh/insightindustry/sqlathanor :alt: Code Coverage Status (Codecov)

    .. image:: https://readthedocs.org/projects/sqlathanor/badge/?version=v.0.5.1 :target: http://sqlathanor.readthedocs.io/en/latest/?badge=v.0.5.1 :alt: Documentation Status (ReadTheDocs)

• • v.0.4 <https://github.com/insightindustry/sqlathanor/tree/v.0.4.0>_

  • .. image:: https://travis-ci.com/insightindustry/sqlathanor.svg?branch=v.0.4.0 :target: https://travis-ci.com/insightindustry/sqlathanor :alt: Build Status (Travis CI)

    .. image:: https://codecov.io/gh/insightindustry/sqlathanor/branch/v.0.4.0/graph/badge.svg :target: https://codecov.io/gh/insightindustry/sqlathanor :alt: Code Coverage Status (Codecov)

    .. image:: https://readthedocs.org/projects/sqlathanor/badge/?version=v.0.4.0 :target: http://sqlathanor.readthedocs.io/en/latest/?badge=v.0.4.0 :alt: Documentation Status (ReadTheDocs)

• • v.0.3 <https://github.com/insightindustry/sqlathanor/tree/v.0.3.1>_

  • .. image:: https://travis-ci.com/insightindustry/sqlathanor.svg?branch=v.0.3.1 :target: https://travis-ci.com/insightindustry/sqlathanor :alt: Build Status (Travis CI)

    .. image:: https://codecov.io/gh/insightindustry/sqlathanor/branch/v.0.3.1/graph/badge.svg :target: https://codecov.io/gh/insightindustry/sqlathanor :alt: Code Coverage Status (Codecov)

    .. image:: https://readthedocs.org/projects/sqlathanor/badge/?version=v.0.3.1 :target: http://sqlathanor.readthedocs.io/en/latest/?badge=v.0.3.1 :alt: Documentation Status (ReadTheDocs)

• • v.0.2 <https://github.com/insightindustry/sqlathanor/tree/v.0.2.2>_

  • .. image:: https://travis-ci.com/insightindustry/sqlathanor.svg?branch=v.0.2.2 :target: https://travis-ci.com/insightindustry/sqlathanor :alt: Build Status (Travis CI)

    .. image:: https://codecov.io/gh/insightindustry/sqlathanor/branch/v.0.2.2/graph/badge.svg :target: https://codecov.io/gh/insightindustry/sqlathanor :alt: Code Coverage Status (Codecov)

    .. image:: https://readthedocs.org/projects/sqlathanor/badge/?version=v.0.2.2 :target: http://sqlathanor.readthedocs.io/en/latest/?badge=v.0.2.2 :alt: Documentation Status (ReadTheDocs)

• • v.0.1 <https://github.com/insightindustry/sqlathanor/tree/v.0.1.1>_

  • .. image:: https://travis-ci.com/insightindustry/sqlathanor.svg?branch=v.0.1.1 :target: https://travis-ci.com/insightindustry/sqlathanor :alt: Build Status (Travis CI)

    .. image:: https://codecov.io/gh/insightindustry/sqlathanor/branch/v.0.1.1/graph/badge.svg :target: https://codecov.io/gh/insightindustry/sqlathanor :alt: Code Coverage Status (Codecov)

    .. image:: https://readthedocs.org/projects/sqlathanor/badge/?version=v.0.1.1 :target: http://sqlathanor.readthedocs.io/en/latest/?badge=v.0.1.1 :alt: Documentation Status (ReadTheDocs)

• • develop <https://github.com/insightindustry/sqlathanor/tree/develop>_

  • .. image:: https://travis-ci.com/insightindustry/sqlathanor.svg?branch=develop :target: https://travis-ci.com/insightindustry/sqlathanor :alt: Build Status (Travis CI)

    .. image:: https://codecov.io/gh/insightindustry/sqlathanor/branch/develop/graph/badge.svg :target: https://codecov.io/gh/insightindustry/sqlathanor :alt: Code Coverage Status (Codecov)

    .. image:: https://readthedocs.org/projects/sqlathanor/badge/?version=develop :target: http://sqlathanor.readthedocs.io/en/latest/?badge=develop :alt: Documentation Status (ReadTheDocs)

SQLAthanor is a Python library that extends SQLAlchemy <http://www.sqlalchemy.org>'s fantastic Declarative ORM <http://www.sqlalchemy.org/en/latest/orm/extensions/declarative/index.html> to provide easy-to-use record serialization/de-serialization with support for:

• JSON
• CSV
• YAML
• Python dict

The library works as a drop-in extension - change one line of existing code, and it should just work. Furthermore, it has been extensively tested on Python 2.7, 3.4, 3.5, 3.6, 3.7, and 3.8 using SQLAlchemy <http://www.sqlalchemy.org>_ 0.9 and higher.

COMPLETE DOCUMENTATION: http://sqlathanor.readthedocs.org/en/latest/index.html

.. contents:: :depth: 3 :backlinks: entry

Installation

To install SQLAthanor, just execute:

.. code:: bash

$ pip install sqlathanor

Dependencies

.. list-table:: :widths: 50 50 :header-rows: 1

• • Python 3.x
  • Python 2.7
• • | * SQLAlchemy v.0.9 <https://www.sqlalchemy.org>_ or higher | * PyYAML v3.10 <https://github.com/yaml/pyyaml>_ or higher | * simplejson v3.0 <https://simplejson.readthedocs.io/en/latest/>_ or higher | * Validator-Collection v1.4.0 <https://github.com/insightindustry/validator-collection>_ or higher
  • | * SQLAlchemy v.0.9 <https://www.sqlalchemy.org>_ or higher | * PyYAML v3.10 <https://github.com/yaml/pyyaml>_ or higher | * simplejson v3.0 <https://simplejson.readthedocs.io/en/latest/>_ or higher | * Validator-Collection v1.4.0 <https://github.com/insightindustry/validator-collection>_ or higher

Why SQLAthanor?

Odds are you've used SQLAlchemy <http://www.sqlalchemy.org>_ before. And if you haven't, why on earth not? It is hands down the best relational database toolkit and Object Relational Mapper (ORM) available for Python, and has helped me quickly write code for many APIs, software platforms, and data science projects. Just look at some of these great features <http://www.sqlalchemy.org/features.html>_.

As its name suggests, SQLAlchemy focuses on the problem of connecting your Python code to an underlying relational (SQL) database. That's a super hard problem, especially when you consider the complexity of abstraction, different SQL databases, different SQL dialects, performance optimization, etc. It ain't easy, and the SQLAlchemy team has spent years building one of the most elegant solutions out there.

But as hard as Pythonically communicating with a database is, in the real world with microservices, serverless architectures, RESTful APIs and the like we often need to do more with the data than read or write from/to our database. In almost all of the projects I've worked on over the last two decades, I've had to:

• hand data off in some fashion (serialize) for another program (possibly written by someone else in another programming language) to work with, or
• accept and interpret data (de-serialize) received from some other program (possibly written by someone else in another programming language).

Python objects (pickled or not) are great, but they're rarely the best way of transmitting data over the wire, or communicating data between independent applications. Which is where formats like JSON, CSV, and YAML come in.

So when writing many Python APIs, I found myself writing methods to convert my SQLAlchemy records (technically, model instances) into JSON or creating new SQLAlchemy records based on data I received in JSON. So after writing similar methods many times over, I figured a better approach would be to write the serialization/de-serialization code just once, and then re-use it across all of my various projects.

Which is how SQLAthanor came about.

It adds simple methods like to_json() <http://sqlathanor.readthedocs.org/en/latest/using.html#sqlathanor.BaseModel.to_json>, new_from_csv() <http://sqlathanor.readthedocs.org/en/latest/using.html#sqlathanor.BaseModel.new_from_csv>, and update_from_csv() <http://sqlathanor.readthedocs.org/en/latest/using.html#sqlathanor.BaseModel.update_from_json>_ to your SQLAlchemy declarative models and provides powerful configuration options that give you tons of flexibility.

Key SQLAthanor Features

• Easy to adopt: Just tweak your existing SQLAlchemy import statements and you're good to go.

• With one method call, convert SQLAlchemy model instances to:

  • CSV records
  • JSON objects
  • YAML objects
  • Python dict objects (technically, OrderedDict objects but they behave just like dict)

• With one method call, create or update SQLAlchemy model instances from:

  • Python dict or OrderedDict objects
  • CSV records
  • JSON objects
  • YAML objects

• Decide which serialization formats you want to support for which models.

• Decide which columns/attributes you want to include in their serialized form (and pick different columns for different formats, too).

• Default validation for de-serialized data for every SQLAlchemy data type.

• Customize the validation used when de-serializing particular columns to match your needs.

• Works with Declarative Reflection and the SQLAlchemy Automap extension.

• Programmatically generate Declarative Base Models from serialized data.

• Programmatically generate SQLAlchemy Table objects from serialized data.

SQLAthanor vs Alternatives

For a comparison of SQLAthanor to various alternative serialization/de-serialization approaches, please see full documentation: https://sqlathanor.readthedocs.io/en/latest/index.html#sqlathanor-vs-alternatives

Complete Documentation

SQLAthanor is a complex library that integrates with other complex libraries. We strongly recommend that you review our comprehensive documentation at:

https://sqlathanor.readthedocs.org/en/latest/index.html

Questions and Issues

You can ask questions and report issues on the project's Github Issues Page <https://github.com/insightindustry/sqlathanor/issues>_

Contributing

We welcome contributions and pull requests! For more information, please see the Contributor Guide <http://sqlathanor.readthedocs.org/en/latest/contributing.html>_

Testing

We use TravisCI <http://travisci.org>_ for our build automation, Codecov.io <http://codecov.io>_ for our test coverage, and ReadTheDocs <https://readthedocs.org>_ for our documentation.

Detailed information about our test suite and how to run tests locally can be found in our Testing Reference <http://sqlathanor.readthedocs.org/en/latest/testing.html>_.

License

SQLAthanor is made available under an MIT License <http://sqlathanor.readthedocs.org/en/latest/license.html>_.

.. _SQLAlchemy: http://www.sqlalchemy.org .. _Flask-SQLAlchemy: http://flask-sqlalchemy.pocoo.org/2.3/