####################################################
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
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
-
-
- | *
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/