Eve-SQLAlchemy 0.7.1
REST API framework powered by Eve, SQLAlchemy and good intentions.
License: BSD
Keywords: flask sqlalchemy rest

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]