Notes for developers of geoextent.


All commands in this file assume you work in a virtual environment created with virtualenvwrapper as follows (please keep up to date!):

# pip install virtualenvwrapper

# Add to .bashrc:
# export WORKON_HOME=$HOME/.virtualenvs
# source ~/.local/bin/

# Where are my virtual envs stored?

# Create environment using Python 3
#mkvirtualenv -p $(which python3) geoextent

# Activate env
workon geoextent

# Deactivate env


Required packages

In the environment created above, run

pip install -r requirements.txt

Install a matching version of gdal-python into the virtual environment:

gdal-config --version

CPLUS_INCLUDE_PATH=/usr/include/gdal C_INCLUDE_PATH=/usr/include/gdal pip install gdal==`gdal-config --version`

For the installation to suceed you need the following system packages (on Debian/Ubuntu):

  • libproj-dev

  • libgdal-dev

  • libgeos-dev

  • gdal-bin

Run tests

To install development requirements, run

pip install -r requirements-dev.txt

Either install the lib and run pytest, or run python -m pytest. You can also run individual files:


pytest tests/


The documentation is based on Sphinx. The source files can be found in the directory docs/ and the rendered online documentation is at

Build documentation locally

cd docs/
pip install -r requirements-docs.txt
make html

Build documentation website

The deployed documentation website is built on Travis CI, see file .travis.yml for details. In short, an extra stage build docs is executed only on the master branch and not for pull requests.



Required tools:

  • setuptools

  • wheel

  • twine

pip install --upgrade setuptools wheel twine

Run tests

Make sure that all tests work locally by running


and check the tests on Travis CI o2r-project/geoextent before continuing with the following tasks.

Bump version for release

Follow the Semantic Versioning specification to clearly mark changes as a new major version, minor changes, or patches. The version number is centrally managed in the file geoextent/

Update changelog

Update the changelog in file docs/source/changelog.rst, use the sphinx-issues syntax for referring to pull requests and contributors for changes where appropriate.

Update citation and authors information

Make sure the following files have the current information (version, commit, contributors, dates, …):

Build distribution archive

See the PyPI documentation on generating a distribution archive,, for details.

# remove previous releases and builds
rm dist/*
rm -rf build *.egg-info

python3 sdist bdist_wheel

Upload to test repository

First upload to the test repository and check everything is in order.

# upload with twine, make sure only one wheel is in dist/
twine upload --repository-url dist/*

Check if the information on is correct. Then switch to a new Python environment or use a Python 3 container to get an “empty” setup. Install geoextent from TestPyPI and ensure the package is functional:

docker run --rm -it -v $(pwd)/tests/testdata/:/testdata python:3-buster /bin/bash

# install system deps
apt-get update
apt-get install gdal-bin libgdal-dev libproj-dev libgeos-dev libspatialite-dev netcdf-bin

# in the container, first install packages not on TestPyPI or where we need a specific version (you might have to manually identify the closest matching pygdal version
pip install geojson pyproj pygdal==`gdal-config --version`

pip install -i geoextent
geoextent --help
geoextent --version

geoextent -b -t /testdata/geojson/muenster_ring_zeit.geojson
geoextent -b -t /testdata/shapefile/gis_osm_buildings_a_free_1.shp

Alternatively, use Debian Testing container to try out a more recent version of GDAL which matches the current release of the GDAL package on PyPI:

docker run --rm -it -v $(pwd)/tests/testdata/:/testdata debian:testing

# Python + PIP
apt-get update
apt-get install python3 python3-pip wget

# System dependencies
apt-get install gdal-bin libgdal-dev libproj-dev libgeos-dev

pip install geojson pyproj pygdal==`gdal-config --version`

pip install -i geoextent
geoextent --help
geoextent --version


geoextent -b wf_100m_klas.tif

Upload to PyPI

twine upload dist/*

Check if information on is all correct. Install the library from PyPI into a new environment, e.g., by reusing the container session from above, and check that everything works.

Add tag

Add a version tag to the commit of the release and push it to the main repository. Go to GitHub and create a new release by using the “Draft a new release” button and using the just pushed tag. Releases are automatically stored on Zenodo - double-check that the release is also available on Zenodo