pyvalhalla-git 3.5.1.post187__cp312-cp312-macosx_14_0_arm64.whl → 3.5.1.post193__cp312-cp312-macosx_14_0_arm64.whl

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pyvalhalla-git
-Version: 3.5.1.post187
+Version: 3.5.1.post193
 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,6 +34,8 @@ This package contains the Python bindings to [Valhalla routing engine](https://g
 > - `win-amd64`
 > - `macos-arm64`
 
+On top of the (very) high-level Python bindings, we package some data-building Valhalla executables to ease the process of graph creation.
+
 ### License
 
 Due to the dependencies we package, the Python bindings are licensed under GNU Lesser General Public License v2 or later (LGPLv2+).
@@ -47,6 +49,8 @@ We distribute all currently maintained CPython versions as **binary wheels** for
 
 ### Usage
 
+#### Bindings
+
 Find a more extended notebook in `./examples`, e.g. how to [use the actor](./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 +75,24 @@ actor = Actor(config)
 route = actor.route({"locations": [...]})
 ```
 
+#### Valhalla executables
+
+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 +116,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.

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

@@ -1,17 +1,20 @@
 _valhalla.cpython-312-darwin.so,sha256=yRMF10AknDjRFSuzbFdm2VpKKWXSTvObE0BkvRzzQgI,11478864
-pyvalhalla_git-3.5.1.post187.dist-info/RECORD,,
-pyvalhalla_git-3.5.1.post187.dist-info/WHEEL,sha256=VrhWOWJdu4wN9IKhAFBqWPMo6yuww-SFg9GbWc0qbmI,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.5.1.post193.dist-info/RECORD,,
+pyvalhalla_git-3.5.1.post193.dist-info/WHEEL,sha256=VrhWOWJdu4wN9IKhAFBqWPMo6yuww-SFg9GbWc0qbmI,136
+pyvalhalla_git-3.5.1.post193.dist-info/top_level.txt,sha256=mU472JpF5fOfpVQ8UxZ_dwLmecLogajAMO5RmYsU1gw,19
+pyvalhalla_git-3.5.1.post193.dist-info/METADATA,sha256=yE_nUq5JEu1Gdl7hI9obCXKTop4bRF0UoIMwrtDaK7U,6335
+pyvalhalla_git-3.5.1.post193.dist-info/licenses/LICENSE.md,sha256=sZlxfQFAuJ8ba_1E8G3hYQ7eC770tBIywEWAg3rrixM,44
+pyvalhalla_git-3.5.1.post193.dist-info/licenses/AUTHORS,sha256=IGm6Dg1NRkmFHV2GWvlPdfiqVoc1kfoc0pMbcKiCs30,171
+pyvalhalla_git-3.5.1.post193.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=hkaH-hN0yQ4NLDcAD-d5Jm1Qne6rc7HcDJimDZ92-B8,269
+valhalla/__version__.py,sha256=Ayqd5H42DgZ_KBT7ApCl3-fCyWjKpNYrTUjrUdD0Qz4,530
 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=X6B0ffW0-hWWJ-ZowzWnK9tFCF1himT3eQkTWyJ_xL0,2273
 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=h_ScEhTzdwdHHS5UCpDq60I9j423In1XM84PM_MwIjY,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,11 @@
+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__
+
+PYVALHALLA_DIR = Path(__file__).parent.resolve()

valhalla/__main__.py

@@ -0,0 +1,69 @@
+import subprocess
+import sys
+from typing import Optional
+
+from ._scripts import PYVALHALLA_BIN_DIR, run
+
+PRINT_BIN_PATH = "print_bin_path"
+
+
+def print_help():
+    print(
+        "\npyvalhalla package provides a CLI to run Valhalla C++ executables. Arguments are simply passed on as they are."
+    )
+    print(
+        "One notable exception is --quiet/-q, which will forward the C++ executable's stdout to /dev/null."
+    )
+    print("'python -m valhalla --help' will print this help.")
+    print(
+        "\nExample usage: 'python -m valhalla --quiet valhalla_build_tiles -c valhalla.json -s initialize -e build test.pbf'"
+    )
+    print("\nAvailable commands:")
+    # 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)))
+    print(
+        f"\t{PRINT_BIN_PATH:<{fixed_width}} - Print the absolute path of directory containing the C++ executables"
+    )
+    for command in exe_names:
+        print(f"\t{command:<{fixed_width}} - see usage with 'python -m pyvalhalla {command} --help' ")
+
+
+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
+        # in theory one doesn't even need a python installation for the Valhalla executables
+        # to still work, provided the correct wheel is used for the specific platform
+        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.5.1.post193'
+__version_tuple__ = version_tuple = (3, 5, 1, 'post193')

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.");
+}