Development and maintenance¶
For development on the
openeo package itself,
it is recommended to install a local git checkout of the project
in development mode (
with additional development related dependencies (
pip install -e .[dev]
Running the unit tests¶
The test suite of the openEO Python Client leverages
the nice pytest framework.
It is installed automatically when installing the openEO Python Client
[dev] extra as shown above.
Running the whole tests is as simple as executing:
There are a ton of command line options for fine-tuning
(e.g. select a subset of tests, how results should be reported, …).
pytest -h for a quick overview
or check the pytest documentation for more information.
# Skip tests that are marked as slow pytest -m "not slow"
Building the documentation¶
Building the documentation requires Sphinx
and some plugins
(which are installed automatically as part of the
To building the documentation locally as HTML:
python setup.py build_sphinx -c docs
or as LaTeX documents:
python setup.py build_sphinx -c docs -b latex
Creating a release¶
This section describes the procedure to create
properly versioned releases of the
that can be downloaded by end users (e.g. through
pip from pypi.org)
and depended on by other projects.
The releases will end up on:
VITO Artifactory: https://artifactory.vgt.vito.be/api/pypi/python-openeo/simple/openeo/
You have permissions to push branches and tags and maintain releases on the openeo-python-client project on GitHub.
You have permissions to upload releases to the openeo project on pypi.org
The Python virtual environment you work in has the latest versions of the
twinepackage installed. If you plan to build the wheel yourself (instead of letting Jenkins do this), you also need recent enough versions of the
describes the metadata of the package, like package name
openeoand version (which is extracted from
defines the version of the package. During general development, this version string should contain a pre-release segment (e.g.
a1for alpha releases,
b1for beta releases, etc) to avoid collision with final releases. For example:
__version__ = '0.4.7a1'
As discussed below, this pre-release suffix should only be removed during the release procedure and restored when bumping the version after the release procedure.
keeps track of important changes associated with each release. It follows the Keep a Changelog convention and should be properly updated with each bug fix, feature addition/removal, … under the
Unreleasedsection during development.
These are the steps to create and publish a new release of the
To be as concrete as possible, we will assume that we are about to release version
Make sure you are working on latest master branch, without uncommitted changes and all tests are properly passing.
Drop the pre-release suffix from the version string in
openeo/_version.pyso that it just a “final” semantic versioning string, e.g.
Update CHANGELOG.md: rename the “Unreleased” section title to contain version and date, e.g.:
## [0.4.7] - 2020-12-15
remove empty subsections and start a new “Unreleased” section above it, like:
## [Unreleased] ### Added ### Changed ### Removed ### Fixed
Commit these changes in git with a commit message like
Release 0.4.7and push to GitHub
Preferably: wait for Jenkins to build this updated master (trigger it manually if necessary), so that a build of final release
0.4.7is properly uploaded to VITO artifactory.
Obtain a wheel archive of the package:
Path of least surprise: build wheel through GitHub Actions. Go to workflow “Build wheel”, manually trigger a build with “Run workflow” button, wait for it to finish successfully, download generated
artifact.zip, and finally: unzip it to obtain
Or, if you know what you are doing and you’re sure your local checkout is clean without temporary source files all over the place, you can also build it locally:
python setup.py sdist bdist_wheel
This should create
Upload this wheel archive to PyPI:
python -m twine upload openeo-0.4.7-py3-none-any.whl
Create a git version tag and push it to GitHub:
git tag v0.4.7 git push origin v0.4.7
Create a release in GitHub: Go to https://github.com/Open-EO/openeo-python-client/releases/new, Enter
v0.4.7under “tag”, enter title:
openEO Python Client v0.4.7, use the corresponding
CHANGELOG.mdsection as description and publish it (no need to attach binaries).
Bump version in
openeo/_version.py, and append a pre-release “a1” suffix again, for example:
__version__ = '0.4.8a1'
Commit this (e.g. with message
_version.py: next alpha version 0.4.8a1) and push to GitHub.
The new release should now be available/listed at:
Here is a bash oneliner to verify that the PyPI release works properly:
(cd /tmp &&\ python -m venv tmp-venv-openeo &&\ . tmp-venv-openeo/bin/activate &&\ pip install openeo==0.4.7 &&\ python -c "import openeo;print(openeo);print(openeo.__version__)"\ )
It tries to install the package in a temporary virtual env, import it and print the package version.