Python bindings for libosmium
Provides Python bindings for the Libosmium C++ library, a library for working with OpenStreetMap data in a fast and flexible manner.
Pyosmium works with Python >= 3.8. Pypy is known to not work. Support for free-threading Python is currently in an experimental state.
Compiling and using pyosmium on 32bit architectures still works but is not officially supported anymore. There are known issues around working with large OSM IDs on 32bit systems.
The recommended way to install pyosmium is via pip:
pip install osmiumWe provide binary wheels for Linux, MacOS and Windows 64bit architectures for all actively maintained Python versions.
For other versions, a source wheel is provided. Make sure to install all external dependencies first. On Debian/Ubuntu-like systems, the following command installs all required packages:
sudo apt-get install build-essential cmake libexpat1-dev zlib1g-dev libbz2-devpyosmium has the following dependencies:
Make sure to install the development packages for expat, libz and libbz2.
The appropriate versions for Libosmium and Protozero will be downloaded into
the contrib directory when building the source package:
python3 -m build -sAlternatively, provide custom locations for these libraries by setting
Libosmium_ROOT and Protozero_ROOT.
To compile and install the bindings, run
pip install .To compile during development, you can use the experimental Editable install mode of scikit-build-core:
Create a virtualenv with scikit-build-core and pybind11 preinstalled:
virtualenv /tmp/dev-venv
/tmp/dev-venv/bin/pip install scikit-build-core pybind11Now compile pyosmium with:
/tmp/dev-venv/bin/pip --no-build-isolation --config-settings=editable.rebuild=true -Cbuild-dir=/tmp/build -ve.The example directory contains small examples on how to use the library.
They are mostly ports of the examples in Libosmium and osmium-contrib.
There is a small test suite in the test directory. This provides unit test for the python bindings, it is not meant to be a test suite for Libosmium.
Testing requires pytest and pytest-httpserver and optionally
pytest-run-parallel and shapely. Install those into your dev environment:
/tmp/dev-venv/bin/pip install --no-build-isolation --config-settings=editable.rebuild=true -Cbuild-dir=build -ve.[tests]The test suite can be run with:
/tmp/dev-venv/bin/pytest testTo test parallel execution on free-threaded Python, run:
/tmp/dev-venv/bin/pytest test --parallel-threads 10 --iterations 100To build the documentation you need mkdocs with the mkdocstrings and jupyter extensions and the material theme.
All necessary packages can be installed via pip:
pip install osmium[docs]To build the documentation run:
mkdocs buildor to few it locally, you can use:
mkdocs servePregenerated man pages for the tools are available in docs/man. For rebuilding
the man pages run:
cd docs
make manIf you find bugs or have feature requests, please report those in the github issue tracker.
For general questions about using pyosmium you can use the OSM development mailing list or ask on OSM help.
Pyosmium is available under the BSD 2-Clause License. See LICENSE.TXT.
Sarah Hoffmann ([email protected]) and otheres. See commit logs for a full list.
No open issues yet, or sync has not completed.