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!
The code comprising this program is copyright 2011 Lincoln de Sousa and copyright 2012 Jeffrey Finkelstein, 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.BSD in this
This is a partial listing of the contents of this package.
COPYING- the copyright license under which this program is distributed to you (the GNU Affero General Public License version 3)
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
flask_restless directory is a Python package containing the following
views.py- the view class which implements the ReSTful API
manager.py- 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
This application requires Python version 2.5, 2.6, or 2.7.
This application requires the following libraries to be installed:
- Flask version 0.7 or greater
- python-dateutil version less than 2.0
- simplejson only in Python 2.5
- Flask-SQLAlchemy only if your models are defined using Flask-SQLAlchemy
These requirements are also listed in the
requirements.txt file. Using
is probably the easiest way to install these:
pip install -r requirements.txt
pip install Flask Flask-SQLAlchemy python-dateutil simplejson sqlalchemy
Technical note: simplejson is only required if you are using Python 2.5. The built-in json module will suffice in later Python versions.
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.
Running the unit tests requires the nosetests library. This requirement is
also listed in the
pip is probably the easiest way to install this:
pip install -r requirements-test.txt
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
You can measure the test coverage by running
nosetests --with-coverage --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
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 -e "hg+http://bitbucket.org/blazelibs/sqlalchemy-validation#egg=savalidation-dev"
The test suite will automatically skip these tests if it is not installed.
Flask-Restless requires the following program and supporting library to build the documentation:
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
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
AUTHORS file for a list of people who have contributed to this code.
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
licensed under the Flask Artwork License.
Jeffrey Finkelstein email@example.com