Contributing code
Structure of the package
The functionality of the droplets
package is split into multiple modules.
In particular, we distinguish classes that deal with single droplets from those
classes that represent collections (emulsions).
The functions analyzing images are collected in a separate module.
Extending functionality
All code is build on a modular basis, making it easy to introduce new classes
that integrate with the rest of the package. For instance, it is simple to
define a droplet class that stores additional information by subclassing
SphericalDroplet
.
Coding style
The coding style is enforced using isort
and black. Moreover, we use Google Style docstrings,
which might be best learned by example.
The documentation, including the docstrings, are written using reStructuredText, with examples in the
following cheatsheet.
To ensure the integrity of the code, we also try to provide many test functions,
which are typically contained in separate modules in sub-packages called
tests
.
These tests can be ran using scripts in the tests
subfolder in the root
folder.
This folder also contain a script tests_types.sh
, which uses mypy
to check the consistency of the python type annotations.
We use these type annotations for additional documentation and they have also
already been useful for finding some bugs.
Running unit tests
The droplets
package contains several unit tests, typically contained in
sub-module tests
in the folder of a given module. These tests ensure that
basic functions work as expected, in particular when code is changed in future
versions. To run all tests, there are a few convenience scripts in the root
directory tests
. The most basic script is tests_run.sh
, which
uses pytest
to run the tests in the sub-modules of the droplets
package. Clearly, the python package pytest
needs to be installed. There
are also additional scripts that for instance run tests in parallel (need the
python package pytest-xdist
installed), measure test coverage (need
package pytest-cov
installed), and make simple performance measurements.
Moreover, there is a script test_types.sh
, which uses mypy
to
check the consistency of the python type annotations and there is a script
codestyle.sh
, which checks the coding style.
Before committing a change to the code repository, it is good practice to run the tests, check the type annotations, and the coding style with the scripts described above.