Development setup and tests¶
This guide will show you how to set up a development environment for mosaik or components of its ecosystem (like the Python API), how to run the tests, check the code coverage and quality, and build the documentation.
- You should use Linux or OS X as your main development platform – most tools are working much better there than on Windows. However, you should still make sure that mosaik keeps working on Windows. ;-)
- You should create a separate virtualenv for each project, that you are going to work on (e.g., one for mosaik, another one for mosaik-api-python and so forth). This will make it easier for you to track their dependencies.
- You should install and use virtualenvwrapper. It will make working with multiple virtualenvs much easier.
- You may need to change some absolute paths from the code blocks depending on you system.
- I’ll only explain the necessary steps for mosaik, because its the most complex project (e.g., mosaik-api-python has no separate documentation).
- You should have worked through the general installation instructions and got the demo running. Afterwards delete the virtualenv mosaik (rmvirtualenv mosaik) – you can later recreate it as moaik-demo.
Change to the directory where you keep your code and clone the mosaik-repository. Create a virtualenv with a Python 3 interpreter and install all development dependencies. Finally, install mosaik in editable mode:
$ cd ~/Code $ git clone https://gitlab.com/mosaik/mosaik.git $ cd mosaik $ mkvirtualenv -p /usr/bin/python3 mosaik (mosaik)$ pip install -r requirements.txt (mosaik)$ pip install -e . # Install mosaik in "editable"
An “editable” installation just means, that changes you introduce in the repository are automatically reflected in you installation (and thus in your tests).
Tests and coverage¶
To run all tests, simply execute py.test:
It will automatically run all code examples in the
docs/ as well as the
actual tests from
tests/. Pytest’s behavior can be controlled via
[pytest] section in the setup.cfg file and via command line arguments
(see its documentation or py.test
You should also regularly check the code/branch coverage:
$ py.test --cov=mosaik
You can also generate HTML files from your source that highlight uncovered lines:
$ py.test --cov=mosaik --cov-report=html $ [kde-]open htmlcov/index.html
Take a look at the docs of pytest-cov for more help.
Before making a release (and in between) you should make sure that the tests
are passing on all supported Python versions. You do this with tox. Tox’ config file
will show you which versions we support. Every interpreter listed here (e.g.,
Python 3.6 or PyPy) should be installed on your system. Running tox is than
$ tox ... _______ summary ________ py36: commands succeeded py37: commands succeeded congratulations :)
Mosaik follows – as most Python projects – relatively strict coding standards.
- All source files are encoded with UTF-8
- LF (
\n) is used to represent a new line (Unix style).
- Four spaces are used for indentation (three spaces for reStructuredText directives).
- Trailing whitespaces should always be stripped.
- Lines should be no longer than 79 characters.
- Python files should be formatted according to PEP 8 and PEP 257.
You should regularly run flake8 to perform PEP8 style checks and and run some analyses to find things like unused imports:
$ flake8 mosaik
It takes its configuration from
Build the documentation¶
We use Sphinx to create mosaik’s documentation:
$ cd docs/ $ make html
This will build the documentation to
When you push new revisions to the develop branch of mosaik’s main repo
gitlab.com/mosaik/mosaik) the official documentation is automatically updated via a hook.