laurel.routing package

Submodules

laurel.routing.client module

class laurel.routing.client.AsyncClient(*args: Any, **kwargs: Any)

Bases: BaseClient

Asynchronous client class for requests handling, which is passed to each router. Uses the aiohttp package.

__init__(base_url, user_agent=None, timeout=routingpy.client_base.DEFAULT, retry_timeout=None, retry_over_query_limit=None, skip_api_error=None, max_concurrent_requests=10, **kwargs)

Parameters:

• base_url (string) – The base URL for the request. All routers must provide a default. Should not have a trailing slash.

• user_agent (string) – User-Agent to send with the requests to routing API. Overrides options.default_user_agent.

• timeout (int) – Combined connect and read timeout for HTTP requests, in seconds. Specify “None” for no timeout.

• retry_timeout (int) – Timeout across multiple retriable requests, in seconds.

• retry_over_query_limit (bool) – If True, client will not raise an exception on HTTP 429, but instead jitter a sleeping timer to pause between requests until HTTP 200 or retry_timeout is reached.

• skip_api_error (bool) – Continue with batch processing if a routingpy.exceptions.RouterApiError is encountered (e.g. no route found). If False, processing will discontinue and raise an error. Default False.

• kwargs (dict) – Additional arguments, such as headers or proxies.

property req

Holds the requests.PreparedRequest property for the last request.

class laurel.routing.client.TrackedSemaphore(value)

Bases: Semaphore

__init__(value)

async acquire()

Acquire a semaphore.

If the internal counter is larger than zero on entry, decrement it by one and return True immediately. If it is zero on entry, block, waiting until some other coroutine has called release() to make it larger than 0, and then return True.

property current_tasks

release()

Release a semaphore, incrementing the internal counter by one.

When it was zero on entry and another coroutine is waiting for it to become larger than zero again, wake up that coroutine.

laurel.routing.containers module

class laurel.routing.containers.AbstractContainerRunner(name, image, port_map=None, bind_map=None, env_vars=None)

Bases: ABC

An abstract runner for containers. It assumes that there is a single container that is running or not running.

__init__(name, image, port_map=None, bind_map=None, env_vars=None)

Initialize the container runner, but do not start the container yet.

port_map and bind_map give the ports and directories, respectively to map. The keys of these dicts represent the local machine (source), and the values represent the container (target).

abstract build_command(wait_for_completion=False)

Build the container run command.

Return type:

list[str]

check_is_running()

Report if the container is running.

Return type:

None

abstract is_running()

Check if the container is running.

Return type:

bool

start(cmd, wait_for_completion=False, startup_delay_secs=5)

Start the container running using the command passed.

Return type:

None

abstract stop_existing()

Stop the container if it’s running.

Return type:

None

class laurel.routing.containers.ApptainerContainerRunner(name, image, port_map=None, bind_map=None, env_vars=None)

Bases: AbstractContainerRunner

Apptainer implementation of container runner.

build_command(wait_for_completion=False)

Build the Apptainer run command.

Return type:

list[str]

is_running()

Check if the Apptainer container is running.

Return type:

bool

stop_existing()

Stop the Apptainer container if it’s running.

Return type:

None

class laurel.routing.containers.DockerContainerRunner(name, image, port_map=None, bind_map=None, env_vars=None)

Bases: AbstractContainerRunner

Docker implementation of container runner.

build_command(wait_for_completion=False)

Build the docker run command.

Return type:

list[str]

is_running()

Check if the docker container is running.

Return type:

bool

stop_existing()

Stop the docker container if it’s running.

Return type:

None

laurel.routing.nodes module

laurel.routing.nodes.start_routing_server_node(params)

Start the routing server and return the server object.

Return type:

GraphhopperContainerRouter

laurel.routing.nodes.stop_routing_server_node(server, result)

Stop the routing server.

result is used to ensure that this node runs last, after all desired results have been computed. Pass the final dataset which requires the routing server to this node.

Return type:

None

laurel.routing.parser module

class laurel.routing.parser.AsyncGraphhopper(api_key=None, base_url='https://graphhopper.com/api/1', user_agent=None, timeout=10, retry_timeout=None, retry_over_query_limit=False, skip_api_error=None, client=<class 'laurel.routing.client.AsyncClient'>, **client_kwargs)

Bases: object

Performs requests to the Graphhopper API services.

__init__(api_key=None, base_url='https://graphhopper.com/api/1', user_agent=None, timeout=10, retry_timeout=None, retry_over_query_limit=False, skip_api_error=None, client=<class 'laurel.routing.client.AsyncClient'>, **client_kwargs)

Initializes an graphhopper client.

Parameters:

• api_key (str) – GH API key. Required if https://graphhopper.com/api is used.

• base_url (str) – The base URL for the request. Defaults to the ORS API server. Should not have a trailing slash.

• user_agent (str) – User Agent to be used when requesting. Default routingpy.routers.options.default_user_agent.

• timeout (int or None) – Combined connect and read timeout for HTTP requests, in seconds. Specify None for no timeout. Default routingpy.routers.options.default_timeout.

• retry_timeout (int) – Timeout across multiple retriable requests, in seconds. Default routingpy.routers.options.default_retry_timeout.

• retry_over_query_limit (bool) – If True, client will not raise an exception on HTTP 429, but instead jitter a sleeping timer to pause between requests until HTTP 200 or retry_timeout is reached. Default routingpy.routers.options.default_retry_over_query_limit.

• skip_api_error (bool) – Continue with batch processing if a routingpy.exceptions.RouterApiError is encountered (e.g. no route found). If False, processing will discontinue and raise an error. Default routingpy.routers.options.default_skip_api_error.

• client (abc.ABCMeta) – A client class for request handling. Needs to be derived from routingpy.client_base.BaseClient

• client_kwargs (dict) – Additional arguments passed to the client, such as headers or proxies.

async directions(locations, profile, format=None, optimize=None, instructions=None, locale=None, elevation=None, points_encoded=True, calc_points=None, debug=None, point_hints=None, details=None, ch_disable=None, custom_model=None, headings=None, heading_penalty=None, pass_through=None, algorithm=None, round_trip_distance=None, round_trip_seed=None, alternative_route_max_paths=None, alternative_route_max_weight_factor=None, alternative_route_max_share_factor=None, dry_run=None, snap_preventions=None, curbsides=None, **direction_kwargs)

Get directions between an origin point and a destination point.

Use direction_kwargs for any missing directions request options.

For more information, visit https://docs.graphhopper.com/#operation/postRoute.

Parameters:

• locations (list of list or tuple of tuple) – The coordinates tuple the route should be calculated from in order of visit.

• profile (str) – The vehicle for which the route should be calculated. One of [“car” “bike” “foot” “hike” “mtb” “racingbike” “scooter” “truck” “small_truck”]. Default “car”.

• format (str) – Specifies the resulting format of the route, for json the content type will be application/json. Default “json”.

• locale (str) – Language for routing instructions. The locale of the resulting turn instructions. E.g. pt_PT for Portuguese or de for German. Default “en”.

• optimize (bool) – If false the order of the locations will be identical to the order of the point parameters. If you have more than 2 points you can set this optimize parameter to True and the points will be sorted regarding the minimum overall time - e.g. suiteable for sightseeing tours or salesman. Keep in mind that the location limit of the Route Optimization API applies and the credit costs are higher! Note to all customers with a self-hosted license: this parameter is only available if your package includes the Route Optimization API. Default False.

• instructions (bool) – Specifies whether to return turn-by-turn instructions. Default True.

• elevation (bool) – If true a third dimension - the elevation - is included in the polyline or in the GeoJson. IMPORTANT: If enabled you have to use a modified version of the decoding method or set points_encoded to false. See the points_encoded attribute for more details. Additionally a request can fail if the vehicle does not support elevation. See the features object for every vehicle. Default False.

• points_encoded (bool) – If False the coordinates in point and snapped_waypoints are returned as array using the order [lon,lat,elevation] for every point. If true the coordinates will be encoded as string leading to less bandwith usage. Default True.

• calc_points (bool) – If the points for the route should be calculated at all, printing out only distance and time. Default True.

• debug (bool) – If True, the output will be formated. Default False.

• point_hints (list of str) – The point_hints is typically a road name to which the associated point parameter should be snapped to. Specify no point_hint parameter or the same number as you have locations. Optional.

• details (list of str) – Optional parameter to retrieve path details. You can request additional details for the route: street_name, time, distance, max_speed, toll, road_class, road_class_link, road_access, road_environment, lanes, and surface.

• ch_disable (bool) – Always use ch_disable=true in combination with one or more parameters of this table. Default False.

• custom_model (dict) – The custom_model modifies the routing behaviour of the specified profile. See https://docs.graphhopper.com/#section/Custom-Model

• headings (list of int) – Optional parameter. Favour a heading direction for a certain point. Specify either one heading for the start point or as many as there are points. In this case headings are associated by their order to the specific points. Headings are given as north based clockwise angle between 0 and 360 degree.

• heading_penalty (int) – Optional parameter. Penalty for omitting a specified heading. The penalty corresponds to the accepted time delay in seconds in comparison to the route without a heading. Default 120.

• pass_through (bool) – Optional parameter. If true u-turns are avoided at via-points with regard to the heading_penalty. Default False.

• algorithm (str) – Optional parameter. round_trip or alternative_route.

• round_trip_distance (int) – If algorithm=round_trip this parameter configures approximative length of the resulting round trip. Default 10000.

• round_trip_seed (int) – If algorithm=round_trip this parameter introduces randomness if e.g. the first try wasn’t good. Default 0.

• alternative_route_max_paths (int) – If algorithm=alternative_route this parameter sets the number of maximum paths which should be calculated. Increasing can lead to worse alternatives. Default 2.

• alternative_route_max_weight_factor (float) – If algorithm=alternative_route this parameter sets the factor by which the alternatives routes can be longer than the optimal route. Increasing can lead to worse alternatives. Default 1.4.

• alternative_route_max_share_factor (float) – If algorithm=alternative_route this parameter specifies how much alternatives routes can have maximum in common with the optimal route. Increasing can lead to worse alternatives. Default 0.6.

• dry_run (bool) – Print URL and parameters without sending the request.

• snap_preventions (list of str) – Optional parameter to avoid snapping to a certain road class or road environment. Currently supported values are motorway, trunk, ferry, tunnel, bridge and ford. Optional.

• curbsides (list of str) – One of “any”, “right”, “left”. It specifies on which side a point should be relative to the driver when she leaves/arrives at a start/target/via point. You need to specify this parameter for either none or all points. Only supported for motor vehicles and OpenStreetMap.

Returns:

One or multiple route(s) from provided coordinates and restrictions.

Return type:

routingpy.direction.Direction or routingpy.direction.Directions

Changed in version 0.3.0: point_hint used to be bool, which was not the right usage.

Added in version 0.3.0: snap_prevention, curb_side, turn_costs parameters

Changed in version 1.2.0: Renamed point_hint to point_hints, heading to headings, snap_prevention to snap_preventions, curb_side to curbsides,

Added in version 1.2.0: Added custom_model parameter

Deprecated since version 1.2.0: Removed weighting, block_area, avoid, turn_costs parameters

static parse_directions_json(response, algorithm, elevation, points_encoded)

laurel.routing.router module

laurel.routing.router.get_routes(gdf, **kwargs)

Get routes for an individual GeoPandas dataframe.

Return type:

GeoDataFrame

laurel.routing.server module

class laurel.routing.server.GraphhopperContainerRouter(image, graph_dir, config_path, port=8989, container_name='graphhopper', startup_delay=5, mem_max_gb=32, mem_start_gb=2, runner_class=<class 'laurel.routing.containers.ApptainerContainerRunner'>, **cmd_kwargs)

Bases: ABC

Abstract base class for container-based routing services.

__init__(image, graph_dir, config_path, port=8989, container_name='graphhopper', startup_delay=5, mem_max_gb=32, mem_start_gb=2, runner_class=<class 'laurel.routing.containers.ApptainerContainerRunner'>, **cmd_kwargs)

import_graph(input_file)

Import the graph from the given input file (.pbf) and process it.

Return type:

None

target_graph_dir: str = '/data/default-gh'

target_port: int = 8989

Module contents