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