All the code should be compliant with the PEP 8.
The code should also be thoroughly documented. We follow the numpy style. See the existing documentation.
Every part of the code should be tested and should run at least under python >=2.7 and >=3.4
The tests are written using the pytest framework.
The preferred way to run the tests is using tox, an automatised test help package. If you have installed tox, with e.g. pip install tox, you can run it typing:
tox
It will take care of creating virtual environments for every supported version of python, if it exists on the system, install vdat, its dependences and the packages necessary to run the tests and runs py.test
We also provide a setuptools command to run tox. If you run:
python setup.py tox
all the needed dependences, among others tox itself, will be fetched and installed in a .eggs directory. Then it will run tox. This command might fail when running in a virtual environment. If you get ImportError: No module named 'numpy' while installing scipy, install numpy by hand pip install [--user] numpy and rerun it again.
You can run the tests for a specific python version using:
py.test
or:
python setup.py test
You can run specific tests providing the file name(s) and, optionally the name of a test. E.g.:
py.test tests/test_flat.py # runs only the tests in the flat file
py.test tests/test_flat.py::TestFlat # runs only the tests in the TestFlat class
Relevant command line options:
-v verbose output: print the names and parameters of the
tests
-s capture standard output: can cause weird interactions
with the logging module
--noremove Do not remove output created output files when
tearing down the tests. Useful to inspect the log
files created by vhc when updating the tests
--singleproc Run tests only in single processor mode; useful for
debugging
A code coverage report is also created thanks to the pytest-cov plugin and can be visualized opening into a browser cover/index.html. If you want a recap of the coverage directly in the terminal you can provide one of the following options when running py.test:
--cov-report term
--cov-report term-missing
For other command line arguments type:
py.test -h
For a list of available fixtures type:
py.test --fixtures tests/
To build the documentation you need the additional dependences described in Optional dependences. They can be installed by hand or during vhc installation executing one of the following commands on a local copy:
pip install /path/to/vhc[doc]
pip install /path/to/vhc[livedoc]
The first install sphinx, the alabaster theme and the numpydoc extension; the second also sphinx-autobuild.
To build the documentation in html format go to the doc directory and run:
make html
The output is saved in doc/build/html. For the full list of available targets.
If you are updating the documentation and want avoid the edit-compile-browser refresh cycle, and you have installed sphinx-autobuild, type:
make livehtml
then visit http://127.0.0.1:8000. The html documentation is automatically rebuilt after every change of the source and the browser reloaded.