feat: integrate https://github.com/nilsnolde/osrm-bindings

[nilsnolde]

getting to build linux was less of a hassle than I imagined. it's more of a hassle to review I guess.. my proposal: since it's mostly copy/paste from https://github.com/nilsnolde/osrm-bindings, it's not too bad to not review the code toooo much. one can somewhat trust the python packaging pipeline. I'll add more details later. IMO it's more important to understand how things work conceptually, so I'll add quite some more text to the PR description once this is a final PR. and of course feel free to ask any understanding question you have:) packaging is always awful, but honestly, python got really usable after they introduced (and widely supported) pyproject.toml.

General

• nanobind for C++ binding (i.e. no setup.py, all CMake based), very close to libosrm API, only some plumbing python code
• for PyPI distribution, we only build python 3.12 SABI (stable ABI) wheels, older version build from source

Repo Layout

everything is properly namespaced to python:

src/python/
├── CMakeLists.txt
├── README.md
├── include/
│   └── python/
│       ├── engineconfig_nb.hpp
│       ├── parameters/
│       ├── types/
│       └── utility/
├── osrm/
│   ├── __init__.py
│   ├── __main__.py
│   └── osrm_ext.pyi
└── src/
    ├── engineconfig_nb.cpp
    ├── osrm_nb.cpp
    ├── parameters/
    ├── types/
    └── utility/

test/python/
├── constants.py
├── test_index.py
├── test_match.py
├── test_nearest.py
├── test_route.py
├── test_table.py
├── test_tile.py
└── test_trip.py

Packaging Architecture

• we distribute both sdist & wheels from python-bindings.yml
• cibuildwheel to orchestrate the build, packaging, repairing (mostly vendor dynamic libs into the wheel), can be run locally too
• cibuildwheel does the build directly on the system for macos & win; however, for linux it needs an old-ish glibc version which is the ABI compatibility barrier for python extensions. this project uses a manylinux_2_28 docker image based on almalinux 8. I forked https://github.com/pypa/manylinux a while ago to https://github.com/nilsnolde/manylinux, where I added the OSRM build dependencies for both aarch64 & x86: https://github.com/nilsnolde/manylinux/pkgs/container/manylinux.
• we auth with PyPI over a "trusted publisher" so no secrets needed
• versioning is done with setuptools_scm which inspects .git to derive a semver version at packaging time

Open Questions

1. what should we do about the package name? osrm-bindings is ok-ish, osrm would of course be much nicer:)
2. we should probably open a osrm account on PyPI?
3. is it ok to transfer fix map matching test on windows nilsnolde/osrm-bindings#40 here and have someone from the community solve the win map-matching failure? I really don't feel like going back to win and figure out how to properly debug there;)

[nilsnolde]

I tried to be really thorough, so I had claude add some python development and API docs. python doesn't work very well with vitepress with pulling out docstrings etc. it's mostly mkdocs these days in python land. not sure, but I could imagine mkdocs support JS docstrings as well. I guess you just switched to vitepress @DennisOSRM , not sure you'd be open to ditch it again potentially?

[nilsnolde]

for reference, this is the mkdocs based documentation I configured for valhalla: https://valhalla.github.io/valhalla/

[nilsnolde]

this file is the project page on pypi.org

[nilsnolde]

could probably use the standard Makefile instead of duplicating the same logic here. I know there gmake for windows, could just work..

[DennisOSRM]

The PR probably needs a rebase onto latest master to pick up a fix for macOS ci.

[nilsnolde]

jeez, thanks, was just about to diagnose!