Development Setup¶

This documents explains how to setup a virtual environment for developing aiomas, how to build the documentation and how to run its test suite.

Setup¶

You should use at latest version of Python 3 for your devleopment, but at least Python 3.4.

Create a fresh virtualenv with that interpreter and activate it. You can then install all development dependencies with pip:

(aiomas)$ pip install -r requirements-setup.txt

This installs the newest version of everything. If you should into problems with this, you can also install a well-tested set of all dependencies:

(aiomas)$ pip install -r requirements.txt

Note

If you are on Windows, you might want to download msgpack and blosc wheel packages from Christoph Gohlke’s website instead of compiling them on your own.

Apart from installing aiomas in editable mode, it also provides you the following list of tools:

Flake8: for checking code quality and style guides
Pytest: for running the tests and measuing the test coverage inside your virtualenv
Sphinx: for building the documentation
Tox: for running the test suite with all supported Python versions
Twine: for uploading packages to PyPI

Building the docs¶

Sphinx is used to build the docs. You can find ReST source files in the docs/ folder. The output folder for HTML documentation (and other formats) is docs/_build/. The online documentation on Read the Docs is everytime you push something to Bitbucket.

When once you’ve set-up your venv, you can build aiomas’ documentation this way:

(aiomas)$ cd docs/
(aiomas)$ make html  # For quick builds
(aiomas)$ make clean html  # For a clean/full build

For Windows user, there is a make.bat which does the same.

You can also let Sphinx check all external links:

(aiomas)$ make linkcheck

You can get a full list of make targets by running make help.

Running the tests¶

Aiomas uses pytest with the plugins pytest-asyncio and pytest-cov as testing tool. Its configuration is stored in the [pytest] sectionin of setup.cfg.

You can run all tests by executing:

(aiomas)$ py.test

By default, all doctests in README.rst and docs/, all examples in examples/ and all tests in tests/ are run.

In order to measure the test coverage, run pytest with the following arguments:

(aiomas)$ py.test --cov=src/ --cov-report=html

This will produces a folder htmlcov with the coverage results.

You can use tox to run the test suite on all supported Python interpreters. It also runs flake8 to do some code quality and style checks. Currently, you need to have python3.4 and python3.5 available in your path. Running tox is then easy:

(aiomas)$ tox
[...]
________ summary ________
  py34: commands succeeded
  py35: commands succeeded
  docs: commands succeeded
  flake8: commands succeeded
  congratulations :)

If you cannot / do not want to install all the Python versions, you can limit tox to run only a selected environment:

(aiomas)$ tox -e py35  # Only run tests on Python 3.5
(aiomas)$ tox -e flake8  # Only run flake8 checks