pyvalhalla-git 3.5.1.post187__cp311-cp311-macosx_14_0_arm64.whl → 3.6.0.post0__cp311-cp311-macosx_14_0_arm64.whl

{pyvalhalla_git-3.5.1.post187.dist-info → pyvalhalla_git-3.6.0.post0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pyvalhalla-git
-Version: 3.5.1.post187
+Version: 3.6.0.post0
 Summary: High-level bindings to the Valhalla C++ library
 Home-page: https://github.com/valhalla/valhalla
 Author: Nils Nolde
@@ -26,7 +26,7 @@ Dynamic: summary
 
 ## Valhalla Python bindings
 
-This package contains the Python bindings to [Valhalla routing engine](https://github.com/valhalla/valhalla).
+This folder contains the Python bindings to [Valhalla routing engine](https://github.com/valhalla/valhalla).
 
 > [!NOTE]
 > `pyvalhalla(-git)` packages are currently only published for:
@@ -34,9 +34,7 @@ This package contains the Python bindings to [Valhalla routing engine](https://g
 > - `win-amd64`
 > - `macos-arm64`
 
-### License
-
-Due to the dependencies we package, the Python bindings are licensed under GNU Lesser General Public License v2 or later (LGPLv2+).
+On top of the (very) high-level Python bindings, we package some data-building Valhalla executables to ease the process of graph creation.
 
 ### Installation
 
@@ -47,7 +45,9 @@ We distribute all currently maintained CPython versions as **binary wheels** for
 
 ### Usage
 
-Find a more extended notebook in `./examples`, e.g. how to [use the actor](./examples/actor_examples.ipynb).
+#### Bindings
+
+Find a more extended notebook in `./examples`, e.g. how to [use the actor](https://github.com/valhalla/valhalla/blob/master/src/bindings/python/examples/actor_examples.ipynb).
 
 Before using the Python bindings you need to have access to a routable Valhalla graph. Either install Valhalla from source and built the graph from OSM compatible data or use our [Valhalla docker image](https://github.com/gis-ops/docker-valhalla) for a painless experience, e.g. this will build the routing graph for Andorra in `./custom_files`:
 
@@ -71,6 +71,24 @@ actor = Actor(config)
 route = actor.route({"locations": [...]})
 ```
 
+#### Valhalla executables (**`linux-x86_x64` only**)
+
+To access the C++ (native) executables, there are 2 options:
+- (recommended) execute the module, e.g. `python -m valhalla valhalla_build_tiles -h`
+- execute the Python wrapper scripts directly, e.g. `valhalla_build_tiles -h`
+
+> [!NOTE]
+> For the latter option to work, the Python environment's `bin/` folder has to be in the `$PATH`. Inside virtual environments, that's always the case.
+
+Executing the scripts directly might also not work properly if there's a system-wide Valhalla installation, unless the Python environment's `bin/` folder has higher priority than system folders in `$PATH`. The module execution uses an explicit Python executable which should be preferred.
+
+There are also some additional commands we added:
+- `--help`: print the help for `python -m valhalla` explicitly
+- `--quiet`: redirect `stdout` of the C++ executables to `/dev/null`; can be added **once** anywhere in the command, will not be forwarded to a C++ executable
+- `print_bin_path`: simply prints the absolute path to the package-internal `bin/` directory where the C++ executables are; useful if the executables should be accessed directly in some script
+
+To find out which Valhalla executables are currently included, run `python -m valhalla --help`. We limit the number of executables to control the wheel size. However, we're open to include any other executable if there's a good reason.
+
 ### Building from source
 
 #### Linux
@@ -94,7 +112,7 @@ Once built, start a container to actually build Valhalla using AlmaLinux 8:
 ```shell
 cd valhalla
 docker run -dt -v $PWD:/valhalla-py --name valhalla-py --workdir /valhalla-py ghcr.io/valhalla/manylinux:2_28_valhalla_python
-docker exec -t valhalla-py /valhalla-py/src/bindings/python/build_linux.sh build_manylinux 3.12
+docker exec -t valhalla-py /valhalla-py/src/bindings/python/build_linux.sh build_manylinux 3.13
 ```
 
 This will also build & install `libvalhalla` before building the bindings. At this point there should be a `wheelhouse` folder with the fixed python wheel, ready to be installed or distributed to arbitrary python 3.12 installations.
@@ -104,11 +122,16 @@ This will also build & install `libvalhalla` before building the bindings. At th
 On our CI, this orchestrates the packaging of all `pyvalhalla` wheels for every supported, minor Python version and every platform. It can also be run locally (obviously only being able to build wheels for _your_ platform), e.g.
 
 ```shell
-# specifiers from https://cibuildwheel.pypa.io/en/stable/options/#build-skip
+python -m pip install cibuildwheel
+cibuildwheel --print-build-identifiers
 cibuildwheel --only cp313-manylinux_x86_64
 
 # for windows you'll have to set an env var to the vcpkg win root
 VCPKG_ARCH_ROOT="build/vcpkg_installed/custom-x64-windows" cibuildwheel --only cp313-manylinux_x86_64
 ```
 
-On Linux, this might download the `manylinux` docker image. In the end, you'll find the wheel in `./wheelhouse`.
+On Linux, this might download the [`manylinux` docker image](https://github.com/valhalla/manylinux/pkgs/container/manylinux). In the end, you'll find the wheel in `./wheelhouse`.
+
+### Testing (**`linux-x86_x64` only**)
+
+We have a small [test script](https://github.com/valhalla/valhalla/blob/master/src/bindings/python/test/test_pyvalhalla_package.sh) which makes sure that all the executables are working properly. If run locally for some reason, install a `pyvalhalla` wheel first. We run this in CI in a fresh Docker container with no dependencies installed, mostly to verify dynamic linking of the vendored dependencies.

{pyvalhalla_git-3.5.1.post187.dist-info → pyvalhalla_git-3.6.0.post0.dist-info}/RECORD

@@ -1,17 +1,20 @@
 _valhalla.cpython-311-darwin.so,sha256=G6uefdkhtibfTw88P2RrKWv43FJGjBK6bToQRSvnTWA,11478848
-pyvalhalla_git-3.5.1.post187.dist-info/RECORD,,
-pyvalhalla_git-3.5.1.post187.dist-info/WHEEL,sha256=IDSs5FX6_bA_Je6GNgVyz6rcn2XC7t_ySnnLoSan-5o,136
-pyvalhalla_git-3.5.1.post187.dist-info/top_level.txt,sha256=mU472JpF5fOfpVQ8UxZ_dwLmecLogajAMO5RmYsU1gw,19
-pyvalhalla_git-3.5.1.post187.dist-info/METADATA,sha256=U5_omjLt3jjVJGrYfLlGB3sMSLKg0x5nN37ddO_rhVc,4773
-pyvalhalla_git-3.5.1.post187.dist-info/licenses/LICENSE.md,sha256=sZlxfQFAuJ8ba_1E8G3hYQ7eC770tBIywEWAg3rrixM,44
-pyvalhalla_git-3.5.1.post187.dist-info/licenses/AUTHORS,sha256=IGm6Dg1NRkmFHV2GWvlPdfiqVoc1kfoc0pMbcKiCs30,171
-pyvalhalla_git-3.5.1.post187.dist-info/licenses/COPYING,sha256=i9sUrrsAX_p17jiQqhCyQrMMhAyqAbmWxWM4yiefN80,1135
+pyvalhalla_git-3.6.0.post0.dist-info/RECORD,,
+pyvalhalla_git-3.6.0.post0.dist-info/WHEEL,sha256=IDSs5FX6_bA_Je6GNgVyz6rcn2XC7t_ySnnLoSan-5o,136
+pyvalhalla_git-3.6.0.post0.dist-info/top_level.txt,sha256=mU472JpF5fOfpVQ8UxZ_dwLmecLogajAMO5RmYsU1gw,19
+pyvalhalla_git-3.6.0.post0.dist-info/METADATA,sha256=uzpMMvlVTOF183ebKJqt4o2qAYAGemUQg52C1UR2LNI,6790
+pyvalhalla_git-3.6.0.post0.dist-info/licenses/LICENSE.md,sha256=sZlxfQFAuJ8ba_1E8G3hYQ7eC770tBIywEWAg3rrixM,44
+pyvalhalla_git-3.6.0.post0.dist-info/licenses/AUTHORS,sha256=IGm6Dg1NRkmFHV2GWvlPdfiqVoc1kfoc0pMbcKiCs30,171
+pyvalhalla_git-3.6.0.post0.dist-info/licenses/COPYING,sha256=i9sUrrsAX_p17jiQqhCyQrMMhAyqAbmWxWM4yiefN80,1135
 valhalla/config.py,sha256=kpYm-7RS4Mz3plcfGWNDx1s6tfXjnBGMei1uxhQ7VJM,1488
-valhalla/__init__.py,sha256=TQKBm2DP8mNh3OYJ-orTqk1KWGOum2U8fJo27IwQrBk,194
-valhalla/__version__.py,sha256=fUJPudoAYydBLozK46W_lClD7MtK4kD3D24zHiwVYDg,530
+valhalla/_valhalla.cc,sha256=3OorCxyOun1-Q9olHlHw75q3XlprX4Lgd4UKQSHahsY,3699
+valhalla/__init__.py,sha256=jxEX6PBKomyDW1D0On57Y52MIzBmmRQ8gnKb04p8tWg,374
+valhalla/__version__.py,sha256=3CR9tHm_p_sRxPJJWnncp-FiRECKyV5HyHanX3vMSMY,526
 valhalla/utils.py,sha256=VCxJ5rNX4Ha8Ey4T81y1b3Ke2svUwGn5TNyW8nC_8p8,1923
 valhalla/actor.py,sha256=MviJjb6ui1KwIzJbACHncuLNDdHkj1hyzCHlDD_yEjw,4077
+valhalla/_scripts.py,sha256=-zpCo07ckNy9yQFs2BymmmYwKS94ZAhlRyHLPUsfEKg,1504
 valhalla/valhalla_build_config.py,sha256=WJJG6t6I8NnkGc_Wd4vSwI2mgZcwQqPrwvKph2AjfGc,42507
+valhalla/__main__.py,sha256=2X-2Wd8BOXKG63pI8M-nA2nMya2eJGU16aFK3ye0UMQ,2069
 valhalla/.dylibs/libsnappy.1.2.2.dylib,sha256=1D_MdNjNSmrGYQG30ZlmqXb2H1xTbacCevELbUEtRk0,79184
 valhalla/.dylibs/libhwy.1.2.0.dylib,sha256=Yrg_gB_yAOrT3Y494y1ePdkxz4-uSWDcin5WVWEmba4,96928
 valhalla/.dylibs/libIlmThread-3_3.32.3.3.3.dylib,sha256=Cbc2qNJa6hSvnHc_LWttt6wsd3ZgyI6CoCEd3yUlkXs,69744
@@ -86,7 +89,7 @@ valhalla/.dylibs/libssl.3.dylib,sha256=XbtHxY-Fp8FxFknYWDnlyKjSTUI44tPzH07xVDIzF
 valhalla/.dylibs/libabsl_log_internal_format.2407.0.0.dylib,sha256=1KEcZ4z8p2nlMUztcWAaZMEpQC1VDa3-Phv9cixj4Js,72112
 valhalla/.dylibs/libabsl_log_sink.2407.0.0.dylib,sha256=wmmSP56bkIXGQSKmKvqhXgp19sXigY12wt8boXNwxSU,68624
 valhalla/.dylibs/libarrow_dataset.2000.0.0.dylib,sha256=dIUWH4uFDQA5lC5-TLx_UyE6oF2HYWWV3hH9FVJ82dM,2432768
-valhalla/.dylibs/libprime_server.0.dylib,sha256=o3FpwXopxed6JBUPbPJTjHHn_Q-4uPOhHc14gHgH9kw,393168
+valhalla/.dylibs/libprime_server.0.dylib,sha256=US-Ens9ctYyEqCRrDC9BdptthSkGj53XEQfNeZxAjMo,393168
 valhalla/.dylibs/libabsl_strerror.2407.0.0.dylib,sha256=p_NTirDupMktySlY_NFWEw-9vf3Q_mnDwvD2zO2uugI,53872
 valhalla/.dylibs/libnetcdf.22.dylib,sha256=B2gbziNwPMxNBjwrhgkAwpJeo76uXpxSGzHSWE9h1zc,1309456
 valhalla/.dylibs/libabsl_time.2407.0.0.dylib,sha256=4jzEGP5uO8FeGeMnPpxPiX2oDl_eiknqIDWaB93ENDU,111456

valhalla/__init__.py

@@ -1,8 +1,16 @@
+from pathlib import Path
+
 try:
     from ._valhalla import *
 except ModuleNotFoundError:
     from _valhalla import *
-
 from .actor import Actor
 from .config import get_config, get_help
-from .__version__ import __version__
+
+# if run from CMake, Docker or tests
+try:
+    from .__version__ import __version__
+except ModuleNotFoundError:
+    __version__ = "undefined"
+
+PYVALHALLA_DIR = Path(__file__).parent.resolve()

valhalla/__main__.py

@@ -0,0 +1,68 @@
+import subprocess
+import sys
+from typing import Optional
+
+from ._scripts import PYVALHALLA_BIN_DIR, run
+from . import __version__
+
+PRINT_BIN_PATH = "print_bin_path"
+
+
+def print_help():
+    # left-align executable names
+    exe_names = [p.name for p in PYVALHALLA_BIN_DIR.iterdir()]
+    fixed_width = len(max(exe_names, key=lambda x: len(x)))
+
+    # TODO: we also want the git commit to show here, probably written to __version__.py by setup.py's BDistWheelCommand
+    print(
+        F"""
+valhalla Python package {__version__}
+
+pyvalhalla package provides a CLI to run Valhalla C++ executables. Arguments are simply passed on as they are.
+One notable exception is --quiet/-q, which will forward the C++ executable's stdout to /dev/null.
+'python -m valhalla --help' will print this help.
+
+Example usage: 'python -m valhalla --quiet valhalla_build_tiles -c valhalla.json -s initialize -e build test.pbf'
+
+Available commands (in {PYVALHALLA_BIN_DIR}):
+\t{PRINT_BIN_PATH:<{fixed_width}} - Print the absolute path of directory containing the C++ executables
+"""
+    )
+
+
+def main():
+    if len(sys.argv) < 2:
+        print("[FATAL] command needs arguments, see 'python -m valhalla --help': \n")
+        print_help()
+        sys.exit(1)
+
+    prog_or_opt = sys.argv[1]
+
+    if prog_or_opt in ("--help", "-h"):
+        print_help()
+        sys.exit(0)
+    elif prog_or_opt == PRINT_BIN_PATH:
+        # useful when another script wants to run the executables directly for some reason
+        print(PYVALHALLA_BIN_DIR)
+    else:
+        exc: Optional[Exception] = None
+        try:
+            run(from_main=True)
+        except (FileNotFoundError, subprocess.CalledProcessError) as e:
+            exc = e
+        finally:
+            if not exc:
+                sys.exit(0)
+
+            if isinstance(exc, subprocess.CalledProcessError):
+                print(f"Failed calling command '{exc.cmd}'\n")
+
+            print_help()
+            print("Sub-command failed with:\n")
+            print(exc, file=sys.stderr)
+
+            sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()

valhalla/__version__.py

@@ -17,5 +17,5 @@ __version__: str
 __version_tuple__: VERSION_TUPLE
 version_tuple: VERSION_TUPLE
 
-__version__ = version = '3.5.1.post187'
-__version_tuple__ = version_tuple = (3, 5, 1, 'post187')
+__version__ = version = '3.6.0.post0'
+__version_tuple__ = version_tuple = (3, 6, 0, 'post0')

valhalla/_scripts.py

@@ -0,0 +1,46 @@
+from pathlib import Path
+from shutil import which
+import subprocess
+import sys
+
+from . import PYVALHALLA_DIR
+
+PYVALHALLA_BIN_DIR = PYVALHALLA_DIR.joinpath("bin").resolve()
+
+
+def run(from_main=False) -> None:
+    """
+    Parses the command line arguments and runs the Valhalla executables with the
+    provided arguments. Note, by default we assume this is not being called by
+    __main__.py via e.g. 'python -m valhalla ...', but directly with e.g.d
+    'valhalla_build_tiles -h'. sys.argv relates to different executables for
+    both scenarios.
+
+    :param from_main: We parse sys.argv differently if it's called from __main__.py
+    """
+    prog = sys.argv[1] if from_main else Path(sys.argv[0]).name
+    prog_args = sys.argv[2:] if from_main else sys.argv[1:]
+
+    if not which(prog):
+        raise FileNotFoundError(f"Can't find executable at {prog}")
+    prog_path = PYVALHALLA_BIN_DIR.joinpath(prog).resolve()
+
+    print(f"[INFO] Running {prog_path} with args: {prog_args}...")
+
+    # --quiet/-q is our option, don't pass it to the executables
+    is_quiet = False
+    for arg in prog_args:
+        if arg not in ("--quiet", "-q"):
+            continue
+        prog_args.pop(prog_args.index(arg))
+        is_quiet = True
+
+    # recommended way to call exe
+    proc = subprocess.run(
+        [str(prog_path)] + prog_args,
+        stderr=sys.stderr,
+        stdout=subprocess.DEVNULL if is_quiet else sys.stdout,
+    )
+
+    # raises CalledProcessError if not successful
+    proc.check_returncode()

valhalla/_valhalla.cc

@@ -0,0 +1,81 @@
+#include "baldr/rapidjson_utils.h"
+#include "midgard/logging.h"
+#include "midgard/util.h"
+#include "tyr/actor.h"
+
+#include <boost/make_shared.hpp>
+#include <boost/noncopyable.hpp>
+#include <boost/property_tree/ptree.hpp>
+#include <pybind11/pybind11.h>
+
+#include <string>
+
+namespace vt = valhalla::tyr;
+namespace {
+
+// configuring multiple times is wasteful/ineffectual but not harmful
+// TODO: make this threadsafe just in case its abused
+const boost::property_tree::ptree configure(const std::string& config) {
+  boost::property_tree::ptree pt;
+  try {
+    // parse the config and configure logging
+    rapidjson::read_json(config, pt);
+
+    auto logging_subtree = pt.get_child_optional("mjolnir.logging");
+    if (logging_subtree) {
+      auto logging_config = valhalla::midgard::ToMap<const boost::property_tree::ptree&,
+                                                     std::unordered_map<std::string, std::string>>(
+          logging_subtree.get());
+      valhalla::midgard::logging::Configure(logging_config);
+    }
+  } catch (...) { throw std::runtime_error("Failed to load config from: " + config); }
+
+  return pt;
+}
+} // namespace
+
+namespace py = pybind11;
+
+PYBIND11_MODULE(_valhalla, m) {
+  py::class_<vt::actor_t>(m, "_Actor", "Valhalla Actor class")
+      .def(py::init<>([](std::string config) { return vt::actor_t(configure(config), true); }))
+      .def(
+          "route", [](vt::actor_t& self, std::string& req) { return self.route(req); },
+          "Calculates a route.")
+      .def(
+          "locate", [](vt::actor_t& self, std::string& req) { return self.locate(req); },
+          "Provides information about nodes and edges.")
+      .def(
+          "optimized_route",
+          [](vt::actor_t& self, std::string& req) { return self.optimized_route(req); },
+          "Optimizes the order of a set of waypoints by time.")
+      .def(
+          "matrix", [](vt::actor_t& self, std::string& req) { return self.matrix(req); },
+          "Computes the time and distance between a set of locations and returns them as a matrix table.")
+      .def(
+          "isochrone", [](vt::actor_t& self, std::string& req) { return self.isochrone(req); },
+          "Calculates isochrones and isodistances.")
+      .def(
+          "trace_route", [](vt::actor_t& self, std::string& req) { return self.trace_route(req); },
+          "Map-matching for a set of input locations, e.g. from a GPS.")
+      .def(
+          "trace_attributes",
+          [](vt::actor_t& self, std::string& req) { return self.trace_attributes(req); },
+          "Returns detailed attribution along each portion of a route calculated from a set of input locations, e.g. from a GPS trace.")
+      .def(
+          "height", [](vt::actor_t& self, std::string& req) { return self.height(req); },
+          "Provides elevation data for a set of input geometries.")
+      .def(
+          "transit_available",
+          [](vt::actor_t& self, std::string& req) { return self.transit_available(req); },
+          "Lookup if transit stops are available in a defined radius around a set of input locations.")
+      .def(
+          "expansion", [](vt::actor_t& self, std::string& req) { return self.expansion(req); },
+          "Returns all road segments which were touched by the routing algorithm during the graph traversal.")
+      .def(
+          "centroid", [](vt::actor_t& self, std::string& req) { return self.centroid(req); },
+          "Returns routes from all the input locations to the minimum cost meeting point of those paths.")
+      .def(
+          "status", [](vt::actor_t& self, std::string& req) { return self.status(req); },
+          "Returns nothing or optionally details about Valhalla's configuration.");
+}