Eve-SQLAlchemy extension
========================
.. image:: https://travis-ci.org/pyeve/eve-sqlalchemy.svg?branch=master
:target: https://travis-ci.org/pyeve/eve-sqlalchemy
Powered by Eve, SQLAlchemy and good intentions this extension allows
to effortlessly build and deploy highly customizable, fully featured
RESTful Web Services with SQL-based backends.
Eve-SQLAlchemy is simple
------------------------
The following code blocks are excerpts of ``examples/one_to_many`` and should
give you an idea of how Eve-SQLAlchemy is used. A complete working example can
be found there. If you are not familiar with `Eve <http://python-eve.org/>`_
and `SQLAlchemy <https://www.sqlalchemy.org/>`_, it is recommended to read up
on them first.
For this example, we declare two SQLAlchemy mappings (from ``domain.py``):
.. code-block:: python
class Parent(BaseModel):
__tablename__ = 'parent'
id = Column(Integer, primary_key=True)
children = relationship("Child")
class Child(BaseModel):
__tablename__ = 'child'
id = Column(Integer, primary_key=True)
parent_id = Column(Integer, ForeignKey('parent.id'))
As for Eve, a ``settings.py`` is used to configure our API. Eve-SQLAlchemy,
having access to a lot of metadata from your models, can automatically generate
a great deal of the `DOMAIN` dictionary for you:
.. code-block:: python
DEBUG = True
SQLALCHEMY_DATABASE_URI = 'sqlite://'
SQLALCHEMY_TRACK_MODIFICATIONS = False
RESOURCE_METHODS = ['GET', 'POST']
DOMAIN = DomainConfig({
'parents': ResourceConfig(Parent),
'children': ResourceConfig(Child)
}).render()
Finally, running our application server is easy (from ``app.py``):
.. code-block:: python
app = Eve(validator=ValidatorSQL, data=SQL)
db = app.data.driver
Base.metadata.bind = db.engine
db.Model = Base
# create database schema on startup and populate some example data
db.create_all()
db.session.add_all([Parent(children=[Child() for k in range(n)])
for n in range(10)])
db.session.commit()
# using reloader will destroy the in-memory sqlite db
app.run(debug=True, use_reloader=False)
The API is now live, ready to be consumed:
.. code-block:: console
$ curl -s http://localhost:5000/parents | python -m json.tool
.. code-block:: json
{
"_items": [
{
"_created": "Sun, 22 Oct 2017 07:58:28 GMT",
"_etag": "f56d7cb013bf3d8449e11e8e1f0213f5efd0f07d",
"_links": {
"self": {
"href": "parents/1",
"title": "Parent"
}
},
"_updated": "Sun, 22 Oct 2017 07:58:28 GMT",
"children": [],
"id": 1
},
{
"_created": "Sun, 22 Oct 2017 07:58:28 GMT",
"_etag": "dd1698161cb6beef04f564b2e18804d4a7c4330d",
"_links": {
"self": {
"href": "parents/2",
"title": "Parent"
}
},
"_updated": "Sun, 22 Oct 2017 07:58:28 GMT",
"children": [
1
],
"id": 2
},
"..."
],
"_links": {
"parent": {
"href": "/",
"title": "home"
},
"self": {
"href": "parents",
"title": "parents"
}
},
"_meta": {
"max_results": 25,
"page": 1,
"total": 10
}
}
All you need to bring your API online is a database, a configuration
file (defaults to ``settings.py``) and a launch script. Overall, you
will find that configuring and fine-tuning your API is a very simple
process.
Eve-SQLAlchemy is thoroughly tested under Python 2.7-3.7 and PyPy.
Documentation
-------------
The offical project documentation can be accessed at
`eve-sqlalchemy.readthedocs.org
<https://eve-sqlalchemy.readthedocs.org/>`_. For full working examples,
especially regarding different relationship types, see the ``examples``
directory in this repository.
Changelog
---------
0.7.1 (2019-08-10)
~~~~~~~~~~~~~~~~~~
- Updated Tutorial to use werkzeug.security module (#196) [Mandar Vaze]
- Require Flask-SQLAlchemy >= 2.4 and SQLAlchemy >= 1.3 due to security issues
[Dominik Kellner]
- Support filtering on embedded document fields / across relations (#186)
[Dominik Kellner]
- Fix sorting across relations [Dominik Kellner]
- Add Python 3.7 and PyPy3 to supported (and tested) versions [Dominik Kellner]
- Pin SQLAlchemy version due to warnings in Flask-SQLAlchemy [Dominik Kellner]
- Improve documentation (#187, #189) [Marc Vila]
0.7.0 (2018-10-08)
~~~~~~~~~~~~~~~~~~
- Eve 0.7 support (#178) [Nicola Iarocci]
0.6.0 (2018-08-15)
~~~~~~~~~~~~~~~~~~
- Fix querying of list relations using `where` [Dominik Kellner]
- Update Tutorial (#177) [Nicola Iarocci]
- Return None-values again (#155) [Cuong Manh Le]
- Allow to supply own Flask-SQLAlchemy driver (#86) [fubu]
- Support columns with server_default (#160) [Asif Mahmud Shimon]
0.5.0 (2017-10-22)
~~~~~~~~~~~~~~~~~~
- Add DomainConfig and ResourceConfig to ease configuration (#152)
[Dominik Kellner]
- Fixes in documentation (#151) [Alessandro De Angelis]
- Fix deprecated import warning (#142) [Cuong Manh Le]
- Configure `zest.releaser` for release management (#137)
[Dominik Kellner, Øystein S. Haaland]
- Leverage further automated syntax and formatting checks (#138)
[Dominik Kellner]
- Clean up specification of dependencies [Dominik Kellner]
- Added 'Contributing' section to docs (#129) [Mario Kralj]
- Fix trivial app output in documentation (#131) [Michal Vlasák]
- Added dialect-specific PostgreSQL JSON type (#133) [Mario Kralj]
- Fix url field in documentation about additional lookup (#110) [Killian Kemps]
- Compatibility with Eve 0.6.4 and refactoring of tests (#92) [Dominik Kellner]
0.4.1 (2015-12-16)
~~~~~~~~~~~~~~~~~~
- improve query with null values [amleczko]
0.4.0a3 (2015-10-20)
~~~~~~~~~~~~~~~~~~~~
- `hybrid_properties` are now readonly in Eve schema [amleczko]
0.4.0a2 (2015-09-17)
~~~~~~~~~~~~~~~~~~~~
- PUT drops/recreates item in the same transaction [goneri]
0.4.0a1 (2015-06-18)
~~~~~~~~~~~~~~~~~~~~
- support the Python-Eve generic sorting syntax [Goneri Le Bouder]
- add support for `and_` and `or_` conjunctions in sqla expressions [toxsick]
- embedded table: use DOMAIN to look up the resource fields [Goneri Le Bouder]
0.3.4 (2015-05-18)
~~~~~~~~~~~~~~~~~~
- fix setup.py metadata
- fix how embedded documents are resolved [amleczko]
0.3.3 (2015-05-13)
~~~~~~~~~~~~~~~~~~
- added support of SA association proxy [Kevin Roy]
- make sure relationships are generated properly [amleczko]
0.3.2 (2015-05-01)
~~~~~~~~~~~~~~~~~~
- add fallback on attr.op if the operator doesn't exists in the
`ColumnProperty` [Kevin Roy]
- add support for PostgreSQL JSON type [Goneri Le Bouder]
0.3.1 (2015-04-29)
~~~~~~~~~~~~~~~~~~
- more flexible handling sqlalchemy operators [amleczko]
0.3 (2015-04-17)
~~~~~~~~~~~~~~~~
- return everything as dicts instead of SQLAResult, remove SQLAResult
[Leonidaz0r]
- fix update function, this closes #22 [David Durieux]
- fixed replaced method, we are compatible with Eve>=0.5.1 [Kevin Roy]
- fixed jsonify function [Leonidaz0r]
- update documentation [Alex Kerney]
- use id_field column from the config [Goneri Le Bouder]
- add flake8 in tox [Goneri Le Bouder]
0.2.1 (2015-02-25)
~~~~~~~~~~~~~~~~~~
- always wrap embedded documents [amleczko]
0.2 (2015-01-27)
~~~~~~~~~~~~~~~~
- various bugfixing [Arie Brosztein, toxsick]
- refactor sorting parser, add sql order by expresssions; please check
http://eve-sqlalchemy.readthedocs.org/#sqlalchemy-sorting for more details
[amleczko]
0.1 (2015-01-13)
~~~~~~~~~~~~~~~~
- First public preview release. [amleczko]