How to contribute

We welcome contributions!

You can help by:

  • Suggesting new features

  • Reporting/fixing bugs

  • Adding features to the codebase

  • Expanding the testing suit

  • Improving the documentation

How to Report Issues

When reporting issues, please include as many of the the following details as possible:

  • Which version of Kadlu you are using

  • The source code that generated the problem (if applicable)

  • Which platform you are using (Operating system and version)

  • A minimum example that reproduces the issue

  • What result you got

  • What you were expecting

We use GitLab as a repository, so the best way to submit issues is through the issues system.

Merge Requests

We welcome merge requests and additional features to the repository. The preferred style guide for new contributions is PEP 8. When creating a request, please include a single feature per merge, on a branch forked from master. For small updates, a description of the changes in the merge request is sufficient. For larger contributions please open a discussion thread in the issue tracker before merging. Please include tests for new features in the kadlu/tests directory - if a test generates or downloads new data, include cleanup code here as well. Finally, please run the tests before merging and ensure tests complete locally before submitting a merge request.

Thank you for your contributions!

Running the tests

Kadlu includes its own test suite. They are included in the /kadlu/tests/ directory.

To run all tests, run:

pytest --doctest-modules kadlu

You can also specify a module:

pytest kadlu/tests/geospatial/test_interpolation.py

File testing with the python debugger (PDB)

kadlu.test_files()[source]

start a debugging session for reading .nc and .tif file formats.

dynamically generates tests for a given set of input data files. pytest tests will be written to a script using files in kadlu_data/testfiles/ as inputs. this is then run in a pytest subprocess, the test script will be cleaned upon exit.

pytest config can be passed using the DEBUGOPTS environment variable: by default the script will drop into an interactive pdb debugging session. to set a breakpoint, add breakpoint() directly to the source code. otherwise, pdb will break on exceptions.

alternatively, run tests in parallel using the pytest-parallel package

Usage:

from importlib import reload
import os, kadlu

# place some files in the testfiles directory
kadlu.ifremer().fetch_ifremer_netcdf_hs2013()

# reload kadlu and run tests
reload(kadlu); kadlu.test_files()

# optionally pass args to pytest with DEBUGOPTS
os.environ.setdefault('DEBUGOPTS', '--pdb')  # default behaviour
reload(kadlu); kadlu.test_files()

From the terminal:

# set pytest options
export DEBUGOPTS='--pdb --tb=short -s'
python3 test_files.py

# run tests in parallel and log the results
pip install pytest-parallel
export DEBUGOPTS='--workers=auto --tb=line --durations=0'
python3 -B test_files.py | tee testresults.log

see the DEBUGOPTS env var and ‘man pytest’ for further usage information