Development¶
The API is built with Python using Django and Django Rest Framework.
Recommended Development Environment¶
If you are comfortable with setting up a python development environment and cloning the project, feel free to skip to the development environment overview.
Prerequisites¶
We use git for version control and generally follow the development model laid out here. If you are looking for a tool to assist in following this model, we recommend git-flow, a tool made by the same people that created the development model.
Since this is a Python project, we recommend using a virtualenv to manage the environment for the project. If you want to simplify the management of these virtual environments, we recommend using virtualenvwrapper.
This project runs on Python 3.4, since that’s the Python version available on Elastic Beanstalk, our hosting platform. Ideally your development environment also has Python 3.4 installed. If not, you can find it here
Project Setup¶
Note
The following commands assume the virtualenvwrapper
package is installed.
Before cloning the environment, create a virtual environment for the project’s dependencies:
$ mkproject --python=python3.4 km-api
$ workon km-api
You can now clone the project. Since the directory will have already been created, we initialize an empty git repository and then add the project as a remote:
$ git init
$ git remote add origin https://github.com/knowmetools/km-api
$ git pull origin develop
If you installed the git-flow
extension, you can now setup the repository to use it:
$ git flow init -d
Finally, install the project requirements appropriate for what you need. The test
requirements should cover what you need. If all you want to do is run the project locally, the base
requirements are all you need.:
$ pip install -r requirements/[base|test].txt
Linting¶
We use flake8 to lint our code, which is a tool for checking compliance with python’s style guide: pep8. To lint the source code, run flake8 from the project root:
$ flake8
If you want to run the linter on every commit, which is useful because our CI tool fails a build with linting errors, you can install flake8’s git hook:
$ flake8 --install-hook git
$ git config flake8.lazy true
$ git config flake8.strict true
The configuration options ensure that only the code being committed is linted, and that linting errors will stop the commit process.
Dev Environment Overview¶
If you have not yet cloned the repository, do so and install the requirements:
$ git clone https://github.com/knowmetools/km-api
$ cd km-api
$ pip install -r requirements/base.txt
Local Dev Server¶
The development server can be run using the following command:
$ km_api/manage.py runserver
Running Tests¶
Tests are run with pytest. To run the tests, make sure the requirements are installed and run the tests:
$ pip install -r requirements/test.txt
$ pytest km_api/
Building Docs¶
We use sphinx for building documentation, and the docs are automatically published using ReadTheDocs. If you want to build the docs locally, install the requirements and run the build command:
$ pip install -r requirements/docs.txt
$ cd docs
$ make html