Metadata-Version: 2.1
Name: osrm-bindings
Version: 0.2.0
Summary: Python bindings for the osrm-backend project
Author: Doo Woong Chung, Nils Nolde
License: BSD 2-Clause License
         
         Copyright (c) 2026, py-osrm contributors
         
         Redistribution and use in source and binary forms, with or without
         modification, are permitted provided that the following conditions are met:
         
         1. Redistributions of source code must retain the above copyright notice, this
            list of conditions and the following disclaimer.
         
         2. Redistributions in binary form must reproduce the above copyright notice,
            this list of conditions and the following disclaimer in the documentation
            and/or other materials provided with the distribution.
         
         THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
         AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
         IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
         DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
         FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
         DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
         SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
         CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
         OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
         OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
         
Project-URL: repository, https://github.com/nilsnolde/osrm-bindings
Project-URL: osrm-backend repository, https://github.com/Project-OSRM/osrm-backend
Requires-Python: >=3.10
Provides-Extra: dev
Requires-Dist: pytest; extra == "dev"
Requires-Dist: pre-commit; extra == "dev"
Requires-Dist: ruff; extra == "dev"
Description-Content-Type: text/markdown

# osrm-bindings
[![Push Master](https://github.com/nilsnolde/osrm-bindings/actions/workflows/push_master.yml/badge.svg)](https://github.com/nilsnolde/osrm-bindings/actions/workflows/push_master.yml)
[![osrm-bindings version](https://img.shields.io/pypi/v/osrm-bindings?label=osrm-bindings)](https://pypi.org/project/osrm-bindings/)


**osrm-bindings is a Python package that binds to [osrm-backend](https://github.com/Project-OSRM/osrm-backend) using [nanobind](https://github.com/wjakob/nanobind).**

> [!WARNING]
> `osrm-bindings` on Windows might not support map matching. See [this issue](https://github.com/nilsnolde/osrm-bindings/issues/40) on progress.

---

## PyPI

```
pip install osrm-bindings
```

> [!NOTE]
> On PyPI we only distribute `abi3` wheels for each platform, i.e. one needs at least Python 3.12 to install the wheels. Of course it'll fall back to attempt an installation from source.

Platform | Arch
---|---
Linux | x86_64
MacOS | x86_64
Windows | x86_64

## From Source

osrm-bindings is (likely, didn't check) supported from **CPython 3.10+** on, and can be installed from source via running the following command in the source folder:

```
pip install .
```

## OSRM Version

When building from source, the OSRM upstream version is controlled by `OSRM_GIT_REPO` & `OSRM_GIT_TAG` in `pyproject.toml`:

```toml
[tool.scikit-build.cmake.define]
OSRM_GIT_REPO = "https://github.com/nilsnolde/osrm-backend"
OSRM_GIT_TAG = "de8a9da93aa09a4943d3964f0fb378a01a66af49"
```

This accepts any git commit hash, branch name, or tag. To override it without editing the file, pass it as a config setting at install time:

```
pip install . --config-settings cmake.define.OSRM_GIT_TAG=<commit/tag/branch>
```

## Example
The following example will showcase the process of calculating routes between two coordinates.

First, import the `osrm` library, and instantiate an instance of OSRM:
```python
import osrm

# Instantiate osrm_py instance
osrm_py = osrm.OSRM("./tests/test_data/ch/monaco.osrm")
```

Then, declare `RouteParameters`, and then pass it into the `osrm_py` instance:
```python
# Declare Route Parameters
route_params = osrm.RouteParameters(
    coordinates = [(7.41337, 43.72956), (7.41546, 43.73077)]
)

# Pass it into the osrm_py instance
res = osrm_py.Route(route_params)

# Print out result output
print(res["waypoints"])
print(res["routes"])
```

## Type Stubs

The file `src/osrm/osrm_ext.pyi` contains auto-generated type stubs for the C++ extension module. These are used by IDEs for autocompletion and by mkdocstrings to build documentation without compiling the extension.

After changing C++ bindings, rebuild the project to regenerate the stubs:

```
pip install -e .
```

Then commit the updated `.pyi` file. CI will verify that committed stubs are up to date.

## Documentation
[Documentation Page](https://nilsnolde.github.io/osrm-bindings/)
