Flask-Restless

Introduction

This is Flask-Restless, a Flask extension which facilitates the creation of ReSTful JSON APIs. It is compatible with models which have been defined using either SQLAlchemy or Flask-SQLAlchemy.

This document contains some brief instructions concerning installation of requirements, installation of this extension, configuration and usage of this extension, and building of documentation.

For more information, check the World Wide Web!

• Documentation
• Python Package Index listing
• Source code repository

Copyright license

The code comprising this program is copyright 2011 Lincoln de Sousa and copyright 2012, 2013, 2014, and 2015 Jeffrey Finkelstein and contributors, and is dual-licensed under the following two copyright licenses:

• the GNU Affero General Public License, either version 3 or (at your option) any later version
• the 3-clause BSD License

For more information, see the files LICENSE.AGPL and LICENSE.BSD in this directory.

The documentation is licensed under the Creative Commons Attribution-ShareAlike 3.0 license.

Contents

This is a partial listing of the contents of this package.

• LICENSE.AGPL - one possible copyright license under which this program is distributed to you (the GNU Affero General Public License version 3)
• LICENSE.BSD - another possible copyright license under which this program is distributed to you (the 3-clause BSD License)
• docs/ - the Sphinx documentation for Flask-Restless
• examples/ - example applications of Flask-Restless
• flask_restless/ - the Python package containing the extension
• README.md - this file
• setup.py - Python setuptools configuration file for packaging this extension
• tests/ - unit tests for Flask-Restless

The flask_restless directory is a Python package containing the following files:

• helpers.py - utility functions, mainly for performing introspection on SQLAlchemy objects
• manager.py - contains the main class which end users will utilize to create ReSTful APIs for their database models
• search.py - functions and classes which facilitate searching the database on requests which require a search
• views.py - the view class which implements the ReSTful API

Installing

This application requires Python version 2.6, 2.7 or 3.3. Python 3.2 is not supported by Flask and therefore cannot be supported by Flask-Restless.

This application requires the following libraries to be installed:

• Flask version 0.10 or greater
• SQLAlchemy version 0.8 or greater
• python-dateutil version greater than 2.0
• Flask-SQLAlchemy only if your models are defined using Flask-SQLAlchemy

These requirements are also listed in the requirements.txt file. Using pip is probably the easiest way to install these:

pip install -r requirements.txt

or

pip install Flask Flask-SQLAlchemy python-dateutil sqlalchemy

Building as a Python egg

This package can be built, installed, etc. as a Python egg using the provided setup.py script. For more information, run

python setup.py --help

How to use

For information on how to use this extension, build the documentation here or view it on the Web.

Testing

Running the unit tests requires the nosetests library. This requirement is also listed in the requirements-test.txt file.

Using pip is probably the easiest way to install this:

pip install -r requirements-test.txt

or

pip install nose

The Python unit tests are contained in the tests/ directory (which is a Python package). To run the test suite, run the command

python setup.py test

You can also run the unit tests in a less verbose way by doing

nosetests

Test coverage

You can measure the test coverage by running

nosetests --with-coverage --cover-package=flask_restless --cover-html \
    --cover-html-dir=<somedir>

where is the name of the directory in which the HTML formatted coverage report will be written.

Measuring test coverage requires the coverage.py package, which can be installed like this:

pip install coverage

Testing validation

Validation is not provided directly by Flask-Restless, but it does provide a way for users to indicate exceptions to catch. If you wish to test validation of SQLAlchemy models with a real external SQLAlchemy validation library, install the development version of SAValidation:

pip install savalidation

This is only possible on Python 2. The test suite will automatically skip these tests if savalidation is not installed or if you are using Python 3.

Building documentation

Flask-Restless requires the following program and supporting library to build the documentation:

• Sphinx
• sphinxcontrib-httpdomain, version 1.1.7 or greater

These requirements are also listed in the requirements-doc.txt file. Using pip is probably the easiest way to install these:

pip install -r requirements-doc.txt

or

pip install sphinx "sphinxcontrib-httpdomain>=1.1.7"

The documentation is written for Sphinx in reStructuredText files in the docs/ directory. Documentation for each class and function is provided in the docstring in the code.

The documentation uses the Flask Sphinx theme. It is included as a git submodule of this project, rooted at docs/_themes. To get the themes, do

git submodule update --init

Now to build the documentation, run the command

python setup.py build_sphinx

in the top-level directory. The output can be viewed in a web browser by opening docs/_build/html/index.html.

Contributing

Please report any issues on the GitHub Issue Tracker.

To suggest a change to the code or documentation, please create a new pull request on GitHub. Contributed code must come with an appropriate unit test. Please ensure that your code follows PEP8, by running, for example, flake8 before submitting a pull request. Also, please squash multiple commits into a single commit in your pull request by rebasing onto the master branch.

By contributing to this project, you are agreeing to license your code contributions under both the GNU Affero General Public License, either version 3 or any later version, and the 3-clause BSD License, as described in the copyright license section above.

Authors

See the AUTHORS file for a list of people who have contributed to this code.

Artwork

The artwork/flask-restless-small.svg and docs/_static/flask-restless-small.png are licensed under the Creative Commons Attribute-ShareAlike 3.0 license. The original image is a scan of a (now public domain) illustration by Arthur Hopkins in a serial edition of "The Return of the Native" by Thomas Hardy published in October 1878.

The artwork/flask-restless.svg and docs/_static/flask-restless.png are licensed under the Flask Artwork License.

Contact

Jeffrey Finkelstein [email protected]