Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/insightindustry/sqlathanor
Serialization / De-serialization support for the SQLAlchemy Declarative ORM
https://github.com/insightindustry/sqlathanor
csv deserialization json python-library serialization sqlalchemy yaml
Last synced: about 1 month ago
JSON representation
Serialization / De-serialization support for the SQLAlchemy Declarative ORM
- Host: GitHub
- URL: https://github.com/insightindustry/sqlathanor
- Owner: insightindustry
- License: mit
- Created: 2018-06-15T14:00:46.000Z (over 6 years ago)
- Default Branch: master
- Last Pushed: 2022-04-28T19:34:34.000Z (over 2 years ago)
- Last Synced: 2024-11-10T18:29:30.175Z (about 2 months ago)
- Topics: csv, deserialization, json, python-library, serialization, sqlalchemy, yaml
- Language: Python
- Homepage: https://sqlathanor.readthedocs.io/en/latest/index.html
- Size: 1.16 MB
- Stars: 112
- Watchers: 3
- Forks: 6
- Open Issues: 13
-
Metadata Files:
- Readme: README.rst
- Changelog: CHANGES.rst
- Contributing: docs/contributing.rst
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
Awesome Lists containing this project
README
####################################################
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 `_
-
.. 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 `_
-
.. 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 `_
-
.. 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 `_
-
.. 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 `_
-
.. 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 `_
-
.. 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 `_
-
.. 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 `_
-
.. 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 `_
-
.. 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 `_'s fantastic
`Declarative ORM `_ 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 `_ 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 `_ or higher
| * `PyYAML v3.10 `_ or higher
| * `simplejson v3.0 `_ or higher
| * `Validator-Collection v1.4.0 `_ or higher
- | * `SQLAlchemy v.0.9 `_ or higher
| * `PyYAML v3.10 `_ or higher
| * `simplejson v3.0 `_ or higher
| * `Validator-Collection v1.4.0 `_ or higher
-------------
************************************
Why SQLAthanor?
************************************
Odds are you've used `SQLAlchemy `_ 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 `_.
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() `_,
`new_from_csv() `_, and
`update_from_csv() `_
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 `_
-----------------
*********************
Contributing
*********************
We welcome contributions and pull requests! For more information, please see the
`Contributor Guide `_
-------------------
*********************
Testing
*********************
We use `TravisCI `_ for our build automation,
`Codecov.io `_ for our test coverage, and
`ReadTheDocs `_ for our documentation.
Detailed information about our test suite and how to run tests locally can be
found in our `Testing Reference `_.
--------------------
**********************
License
**********************
**SQLAthanor** is made available under an
`MIT License `_.
.. _SQLAlchemy: http://www.sqlalchemy.org
.. _Flask-SQLAlchemy: http://flask-sqlalchemy.pocoo.org/2.3/