Developer notes

The following is a list of notes for developers who want to contribute to AIgarMIC. AIgarMIC is written in Python 3.9 and uses tensorflow and keras 2 for modelling. Models have been tested only on keras 2 therefore the project’s dependencies require tensorflow < 2.16 to maintain this compatibility.

Contributing

We welcome contributions to AIgarMIC. Please follow our [contributing guidelines](https://github.com/agerada/AIgarMIC/blob/paper/CONTRIBUTING.md).

Installation

Follow instructions to clone and install AIgarMIC from source, see: Install from source. Additionally, it is highly recommended that the optional assets are also downloaded and extracted to the project root directory, see: Assets installation. These assets are required to run the full suite of tests.

Running tests

AIgarMIC uses pytest for its testing framework. To run the full suite of tests, navigate to the project root directory and run:

pytest

The suite requires the optional assets to be present in the root directory. Tests that require the assets are marked with @pytest.mark.assets_required, therefore, it is possible to run a limited set of tests that do not require the assets by running:

pytest -m "not assets_required"

Although this will not test the full functionality of AIgarMIC, it can be useful for quickly testing that the installation succeeded.

Test coverage

pytest-cov is recommended for measuring tes coverage. Checking coverage for AIgarMIC requires use of coverage. Since some tests require the running of subprocesses (to test the CLI), coverage must be configured to monitor subprocesses. To run a test coverage report, navigate to the project root directory and run:

export COVERAGE_PROCESS_START=$(pwd)/.coveragerc
export PYTHONPATH=$(pwd)

coverage run -m pytest --cov=aigarmic

Note

Test coverage will import AIgarMIC from the current environment, therefore make sure to install the version you are testing. Scripts, such as main, are executed from the current path.

To generate an HTML report of the coverage, run:

coverage html

Note

It may be necessary to use the error ignore flag (-i) to ignore errors depending on local configuration.

Now open the htmlcov/index.html file in a browser to view the coverage report.

Warning

Use of coverage combine is not currently supported, therefore note that command line scripts (such as main) are covered separately in the report.

Note

As a minimum, >60% test coverage in the core parts of AIgarMIC is required for a contribution. The core parts are in: file_handlers.py, model.py, plate.py, and process_plate_image.py.

Build process

To build a release of AIgarMIC, we recommend using poetry: https://python-poetry.org/. The following general steps should be followed:

  1. Check pep8 compliance by running:

pylint -d=R,C src/aigarmic

Errors related to cv2 and tensorflow import can be ignored.

  1. Run tests by running (including the optional assets):

pytest

  1. Test and build documentation by running:

cd docs
make doctest
make html

  1. Update dependencies in requirements.txt by running (suggest use pip-chill rather than pip freeze to avoid clashes in dependencies):

pip-chill > requirements.txt
pip-chill > docs/source/requirements.txt

If developing using macOS, change the following line:

tensorflow==2.15.0

to:

tensorflow==2.15.0; sys_platform != 'darwin' or platform_machine != 'arm64'

tensorflow-macos==2.15.0; sys_platform == 'darwin' and platform_machine == 'arm64'

This allows platform-agnostic use.

  1. Update release version in pyproject.toml:

poetry version patch

  1. Build the package by running:

poetry build

  1. Commit changes and push to the repository.

  2. Create a new release on GitHub and upload the built package.

Check that documentation has updated correctly on readthedocs.io: https://aigarmic.readthedocs.io/en/latest/ (note that it may take a few minutes to update).