ga-graph 0.1.0__py3-none-any.whl

ga_graph-0.1.0.dist-info/METADATA

@@ -0,0 +1,200 @@
+Metadata-Version: 2.4
+Name: ga-graph
+Version: 0.1.0
+Summary: Lightweight graph, turn, path, and time-dependent routing utilities.
+Author: GA Graph contributors
+License-Expression: MIT
+Project-URL: Documentation, https://github.com/andreagemma/graph#readme
+Project-URL: Issues, https://github.com/andreagemma/graph/issues
+Project-URL: Source, https://github.com/andreagemma/graph
+Keywords: ga-graph,graph,routing,shortest-path,transport-network
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: dill>=0.3.8
+Provides-Extra: test
+Requires-Dist: pytest>=8.0; extra == "test"
+Requires-Dist: pytest-cov>=5.0; extra == "test"
+Provides-Extra: dev
+Requires-Dist: build>=1.2; extra == "dev"
+Requires-Dist: mypy>=1.10; extra == "dev"
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: pytest-cov>=5.0; extra == "dev"
+Requires-Dist: ruff>=0.5; extra == "dev"
+Requires-Dist: twine>=5.1; extra == "dev"
+Dynamic: license-file
+
+# GA Graph
+
+[![CI](https://github.com/andreagemma/graph/actions/workflows/ci.yml/badge.svg)](https://github.com/andreagemma/graph/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/ga-graph.svg)](https://pypi.org/project/ga-graph/)
+[![Python](https://img.shields.io/pypi/pyversions/ga-graph.svg)](https://pypi.org/project/ga-graph/)
+
+GA Graph provides lightweight dictionary-backed graph containers, path
+collections, turn classification helpers, and a link-based time-dependent
+shortest-path router.
+
+The PyPI distribution is named `ga-graph`; the import package is named `graph`.
+
+## Installation
+
+```bash
+python -m pip install ga-graph
+```
+
+Development and test tools are available as extras:
+
+```bash
+python -m pip install -e ".[test]"
+python -m pip install -e ".[dev]"
+```
+
+## Quick Start
+
+```python
+from graph import Graph
+
+network = Graph(total_time=60, delta_t=15)
+network.add_node("A")
+network.add_node("B")
+network.add_link("ab", "A", "B", cost=5)
+
+assert network.get_link("ab").i == "A"
+assert network.get_node_degree("A", include_in_links=False) == 1
+```
+
+## Graphs
+
+`Graph` stores nodes, directed links, and turns in dictionary-backed containers.
+Each entity keeps a required identifier plus arbitrary extra attributes.
+
+```python
+from graph import ActionPolicy, Graph
+
+network = Graph()
+network.add_link(
+    "ab",
+    "A",
+    "B",
+    on_missing_node=ActionPolicy.REPLACE,
+    capacity=1200,
+)
+network.add_turn("ab_bc", "ab", "bc", on_missing_link=ActionPolicy.IGNORE)
+```
+
+Duplicate and missing references can be handled with `ActionPolicy.RAISE`,
+`WARN`, `IGNORE`, `REPLACE`, or `SKIP`, depending on the method.
+
+## Paths
+
+`Path` stores a source, target, departure time, optional mode, link sequence, and
+cumulative costs. `PathList` stores one path per `(source, target, t_start,
+mode)` key. `KPathList` stores multiple ranked paths for the same key.
+
+```python
+from graph import KPathList, Path
+
+paths = KPathList()
+paths.add_path(Path("A", "C", 0, links=["ab", "bc"], costs=[5, 9], mode="car"))
+paths.add_path(Path("A", "C", 0, links=["ac"], costs=[12], mode="car"))
+
+best = paths.path("A", "C", 0, "car", k=0)
+second = paths.path("A", "C", 0, "car", k=1)
+```
+
+## Time-Dependent Routing
+
+`TimeDependentLinkBasedShortestPath` builds a dense routing view from a `Graph`.
+Scalar costs are expanded across the graph time horizon; sequence costs are used
+as piecewise-constant time profiles.
+
+```python
+from graph import Graph, TimeDependentLinkBasedShortestPath
+
+network = Graph(total_time=60, delta_t=15)
+for node in ["A", "B", "C"]:
+    network.add_node(node, cost=0)
+
+network.add_link("ab", "A", "B", cost=1)
+network.add_link("bc", "B", "C", cost=1)
+network.add_link("ac", "A", "C", cost=10)
+
+router = TimeDependentLinkBasedShortestPath.from_graph(network, link_cost_field="cost")
+path = router.shortest_paths("A", "C").path("A", "C", 0, None)
+
+assert path.get_links() == ("ab", "bc")
+assert path["tot_cost"] == 2
+```
+
+The router supports optional mode fields, node costs, turn costs, and prohibited
+turn fields.
+
+## API Summary
+
+- `Graph(t0=0, total_time=60, delta_t=15, **kwargs)`
+- `Graph.add_node(idx, on_existing=ActionPolicy.RAISE, **kwargs)`
+- `Graph.add_link(idx, i, j, on_existing=..., on_missing_node=..., **kwargs)`
+- `Graph.add_turn(idx, in_link, out_link, on_existing=..., on_missing_link=..., **kwargs)`
+- `Graph.get_node(idx)`, `Graph.get_link(idx)`, `Graph.get_turn(idx)`
+- `Graph.remove_node(idx, cascade=False)`, `Graph.remove_link(idx, cascade=False)`
+- `Graph.remove_redundants()`
+- `Path(source, target, t_start, links=None, costs=None, mode=None, ...)`
+- `PathList()`
+- `KPathList()`
+- `TurnType.parse(value)` and `TurnType.classify_turn(...)`
+- `TimeDependentLinkBasedShortestPath.from_graph(graph, ...)`
+- `TimeDependentLinkBasedShortestPath.shortest_paths(source, targets=None, t_start=0)`
+
+## Development
+
+GA Graph supports Python 3.10 and newer.
+
+```bash
+python -m pip install -e ".[dev]"
+python -m compileall -q src
+python -m pytest --cov=graph --cov-report=term-missing
+ruff format --check .
+ruff check .
+mypy
+python -m pip check
+python -m build
+python -m twine check dist/*
+```
+
+## GitHub Repository Setup
+
+This project is prepared for the future repository `andreagemma/graph`.
+
+1. Create the empty repository on GitHub.
+2. Initialize the local repository if needed and push the project to `main`.
+3. Confirm the CI workflow passes on GitHub.
+4. Configure the PyPI Trusted Publisher for project `ga-graph`, owner
+   `andreagemma`, repository `graph`, workflow `release.yml`, and environment
+   `pypi`.
+
+## Releases
+
+`src/graph/_version.py` is the only version source. To publish a release:
+
+1. Update `__version__` in `_version.py` and commit the release changes.
+2. Push `main` and wait for CI to pass.
+3. Run the **Create release** GitHub Actions workflow. With no override it
+   creates the `v<version>` tag, creates release notes, and dispatches the build
+   and PyPI publication workflow.
+
+PyPI versions are immutable. Increment `_version.py` before publishing different
+content.
+
+## License
+
+GA Graph is distributed under the MIT License. See [LICENSE](LICENSE).

ga_graph-0.1.0.dist-info/RECORD

@@ -0,0 +1,23 @@
+ga_graph-0.1.0.dist-info/licenses/LICENSE,sha256=j7vOUjtdElKsWC7AIQTwpEEe2bOMjm3F8v8bhZicToM,1078
+graph/__init__.py,sha256=FUq_wmTdQUVmmP20zAmz_0KTcu45EO1I6gmuVqM4bKg,785
+graph/_version.py,sha256=6NLIBvquSBZbsyYbuheCBbaDGP8kIXZNVc0n1fe757I,98
+graph/py.typed,sha256=AbpHGcgLb-kRsJGnwFEktk7uzpZOCcBY74-YBdrKVGs,1
+graph/algorithms/TD_LBSP.py,sha256=AVMrFhHAviNBUlAsa6L4dWCvjk-pvIQ2qKL4dr32QEw,11794
+graph/algorithms/__init__.py,sha256=0DJDv3U9Wub3qxnz-F1XldP80rcq9MQXi-s9qLvdksQ,106
+graph/graphs/__init__.py,sha256=9s39NZ4VNKiUcmKVCj87kMbUuyHfE90kZtsF0PYRYHQ,542
+graph/graphs/action_policy.py,sha256=5SNn1eJTcu2w7SbCzOsgGpNxOlOPM9NrwpNcMx4Df2s,705
+graph/graphs/exceptions.py,sha256=Hc1FbqklxquqjZV9AbGzgM89b-7oeWTC5H3m9thVwZQ,916
+graph/graphs/graph.py,sha256=qJK-H8ABkOcTseFRJaz-ck2V1hnAe-qtwB0DElBV9O4,16145
+graph/graphs/link.py,sha256=s4Idwj2aTVGAdxEF8cVAITV7bll91jFIbaPOEVAkSMo,1483
+graph/graphs/node.py,sha256=5dz4TCUM7oytGSs5VglVxm-w5QPDiOEJFA9QvLlFVJA,1152
+graph/graphs/turn.py,sha256=3p8jcnmCxHkSHdO0T0Py77jHbVCpUkmkEDv0DuXCdU0,6976
+graph/paths/__init__.py,sha256=ppAKzoV7JWUU0QeKXMVwsyNqgJiARhrEO_NeTAiXZ2c,280
+graph/paths/k_path_container.py,sha256=s4zvBJvOWqwSIm2VkNGZeNWY0DLNy-LqTThKtDtdXuU,2849
+graph/paths/k_path_list.py,sha256=nc9_HNAFqKWqWnXJqxV5-CrUnRUIvL_-1CqLELOcT-o,5944
+graph/paths/path.py,sha256=8hMzb97H4dT-6htyTfVXlPNW6N5gkkJZPzBo9P5el_0,2862
+graph/paths/path_container.py,sha256=h7vM-7ArWXqBs_V_zBEibPSAPZBKvnnJHsTe3Iia1jU,3571
+graph/paths/path_list.py,sha256=Ir4e1BVrEhdWScqDujE4uhyJ-giQfZKO2U73deiXp38,4152
+ga_graph-0.1.0.dist-info/METADATA,sha256=xNPa9tce-RUarmAwGxPSFThiZ37FBYdVoUyKRMo1Qk8,6604
+ga_graph-0.1.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+ga_graph-0.1.0.dist-info/top_level.txt,sha256=_Z1j8Ab-1JfYNhOLenOKxKxm9WCTc_kVydsPHuFI0zk,6
+ga_graph-0.1.0.dist-info/RECORD,,

ga_graph-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

ga_graph-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 GA Graph contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

ga_graph-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+graph

graph/__init__.py

@@ -0,0 +1,39 @@
+from ._version import __version__
+from .algorithms import TimeDependentLinkBasedShortestPath
+from .graphs import (
+    ActionPolicy,
+    ExistingLinkError,
+    ExistingNodeError,
+    ExistingTurnError,
+    Graph,
+    GraphError,
+    Link,
+    MissingLinkError,
+    MissingNodeError,
+    Node,
+    Turn,
+    TurnType,
+)
+from .paths import KPathContainer, KPathList, Path, PathContainer, PathList
+
+__all__ = [
+    "ActionPolicy",
+    "ExistingLinkError",
+    "ExistingNodeError",
+    "ExistingTurnError",
+    "Graph",
+    "GraphError",
+    "KPathContainer",
+    "KPathList",
+    "Link",
+    "MissingLinkError",
+    "MissingNodeError",
+    "Node",
+    "Path",
+    "PathContainer",
+    "PathList",
+    "TimeDependentLinkBasedShortestPath",
+    "Turn",
+    "TurnType",
+    "__version__",
+]

graph/_version.py

@@ -0,0 +1,3 @@
+"""Package version: the single source of truth for builds and releases."""
+
+__version__ = "0.1.0"

graph/algorithms/TD_LBSP.py

@@ -0,0 +1,302 @@
+"""Link-based, time-dependent shortest-path routing.
+
+The :class:`TimeDependentLinkBasedShortestPath` router is a routing-only view of
+``Graph``. Nodes and links are converted to dense integer indices, while the
+original hashable identifiers stay at the public API boundary.
+
+Costs are interpreted as durations and must use the same time unit as
+``Graph.delta_t`` and ``departure_time``. A vector cost is piecewise constant:
+element ``k`` applies on ``[k * delta_t, (k + 1) * delta_t)`` relative to
+``Graph.t0``.
+
+The shortest-path method implements link-based time-dependent Dijkstra. It is
+correct for FIFO cost functions; waiting at nodes is not modelled.
+"""
+
+from __future__ import annotations
+
+from collections import defaultdict
+from collections.abc import Hashable, Iterable
+from heapq import heappop as pop
+from heapq import heappush as push
+from itertools import count
+from typing import Any
+
+from ..graphs.graph import Graph
+from ..graphs.link import Link
+from ..graphs.node import Node
+from ..graphs.turn import Turn
+from ..paths import Path, PathContainer, PathList
+
+CostProfile = tuple[float, ...]
+NodeRow = tuple[int, Hashable, CostProfile]
+LinkRow = tuple[int, Hashable, int, int, CostProfile]
+TurnRow = tuple[int, Hashable, int, int, CostProfile]
+
+
+class TimeDependentLinkBasedShortestPath:
+    """Compute link-based shortest paths on a time-dependent graph."""
+
+    def __init__(self) -> None:
+        """Create an empty router. Use ``from_graph`` to populate it."""
+        self.delta_t: int | float = 1
+        self.total_time: int | float = 10
+        self.n_intervals: int = 0
+        self.t0: int | float = 0
+        self.mode: str | None = None
+        self.nodes: tuple[NodeRow, ...] = tuple()
+        self.links: tuple[LinkRow, ...] = tuple()
+        self.turns: dict[tuple[int, int], set[TurnRow]] = {}
+        self.turns_prohibited: set[tuple[int, int]] = set()
+        self.fws: dict[int, set[LinkRow]] = {}
+        self.links_fws: dict[int, set[LinkRow]] = {}
+        self.n_nodes: int = 0
+        self.n_links: int = 0
+        self.n_turns: int = 0
+        self._nodes_idx: dict[Hashable, int] = {}
+        self._links_idx: dict[Hashable, int] = {}
+
+    @staticmethod
+    def from_graph(
+        graph: Graph,
+        mode: str | None = None,
+        link_mode_field: str | None = None,
+        node_mode_field: str | None = None,
+        turn_mode_field: str | None = None,
+        link_cost_field: str | None = None,
+        node_cost_field: str | None = None,
+        turn_cost_field: str | None = None,
+        turn_prohibited_field: str | None = None,
+    ) -> TimeDependentLinkBasedShortestPath:
+        """Build a router from a ``Graph`` instance."""
+        router = TimeDependentLinkBasedShortestPath()
+        router.delta_t = graph.delta_t
+        router.total_time = graph.total_time
+        router.t0 = graph.t0
+        router.n_intervals = int(graph.num_intervals)
+        router.mode = mode
+
+        def has_mode(element: Node | Link | Turn, field: str | None) -> bool:
+            if mode is None or field is None:
+                return True
+            available_modes = element.get(field)
+            if available_modes is None:
+                return True
+            if isinstance(available_modes, str):
+                available_modes = {available_modes}
+            return "all" in available_modes or mode in available_modes
+
+        def expand_cost(
+            element: Node | Link | Turn,
+            field: str | None,
+            default: float | int = 0,
+        ) -> CostProfile:
+            if field is None or field not in element:
+                return tuple([float(default)] * router.n_intervals)
+
+            value = element.get(field)
+            if value is None:
+                return tuple([float(default)] * router.n_intervals)
+            if isinstance(value, int | float | str):
+                return tuple([float(value)] * router.n_intervals)
+
+            try:
+                values = tuple(float(item) for item in value)
+            except TypeError:
+                return tuple([float(value)] * router.n_intervals)
+
+            if not values:
+                return tuple([float(default)] * router.n_intervals)
+            if len(values) < router.n_intervals:
+                values = values + tuple([values[-1]] * (router.n_intervals - len(values)))
+            return values[: router.n_intervals]
+
+        def is_turn_prohibited(turn: Turn) -> bool:
+            if turn_prohibited_field is None:
+                return False
+            return bool(turn.get(turn_prohibited_field, False))
+
+        node_data = (
+            (node.idx, expand_cost(node, node_cost_field))
+            for node in graph.get_all_nodes()
+            if has_mode(node, node_mode_field)
+        )
+        router.nodes = tuple((dense_id, *node) for dense_id, node in enumerate(node_data))
+        router._nodes_idx = {node[1]: dense_id for dense_id, node in enumerate(router.nodes)}
+
+        link_data = (
+            (
+                link.idx,
+                router._nodes_idx[link.i],
+                router._nodes_idx[link.j],
+                expand_cost(link, link_cost_field),
+            )
+            for link in graph.get_all_links()
+            if link.i in router._nodes_idx
+            and link.j in router._nodes_idx
+            and has_mode(link, link_mode_field)
+        )
+        router.links = tuple((dense_id, *link) for dense_id, link in enumerate(link_data))
+        router._links_idx = {link[1]: dense_id for dense_id, link in enumerate(router.links)}
+
+        turn_rows: list[TurnRow] = []
+        prohibited_pairs: set[tuple[int, int]] = set()
+        for turn in graph.get_all_turns():
+            if (
+                turn.in_link not in router._links_idx
+                or turn.out_link not in router._links_idx
+                or not has_mode(turn, turn_mode_field)
+            ):
+                continue
+
+            pair = (router._links_idx[turn.in_link], router._links_idx[turn.out_link])
+            if is_turn_prohibited(turn):
+                prohibited_pairs.add(pair)
+                continue
+
+            turn_rows.append(
+                (
+                    len(turn_rows),
+                    turn.idx,
+                    pair[0],
+                    pair[1],
+                    expand_cost(turn, turn_cost_field),
+                )
+            )
+
+        turns_by_pair: defaultdict[tuple[int, int], set[TurnRow]] = defaultdict(set)
+        for turn_row in turn_rows:
+            turns_by_pair[(turn_row[2], turn_row[3])].add(turn_row)
+
+        router.turns = dict(turns_by_pair)
+        router.turns_prohibited = prohibited_pairs
+        router.n_nodes = len(router.nodes)
+        router.n_links = len(router.links)
+        router.n_turns = len(turn_rows)
+
+        fws: defaultdict[int, set[LinkRow]] = defaultdict(set)
+        for link in router.links:
+            fws[link[2]].add(link)
+        router.fws = dict(fws)
+
+        links_fws: dict[int, set[LinkRow]] = {}
+        for link in router.links:
+            links_fws[link[0]] = set(fws.get(link[3], set())) - {link}
+
+        for incoming_link_id, outgoing_link_id in router.turns_prohibited:
+            if incoming_link_id in links_fws:
+                links_fws[incoming_link_id] = {
+                    link for link in links_fws[incoming_link_id] if link[0] != outgoing_link_id
+                }
+        router.links_fws = links_fws
+
+        return router
+
+    def shortest_paths(
+        self,
+        source: Node | Hashable,
+        targets: Iterable[Hashable] | Hashable | None = None,
+        t_start: int | float = 0,
+        **kwargs: Any,
+    ) -> PathContainer:
+        """Compute shortest paths from ``source`` to one or more targets."""
+        del kwargs
+        source_label = source.idx if isinstance(source, Node) else source
+        source_id = self._nodes_idx[source_label]
+
+        target_labels = self._normalize_targets(targets)
+        target_ids = {self._nodes_idx[target] for target in target_labels}
+        residual_targets = target_ids.copy()
+
+        paths = PathList()
+        paths_links: list[list[Hashable]] = [[] for _ in self.links]
+        paths_costs = [float("inf")] * self.n_links
+        best_target_link: dict[int, int] = {}
+
+        queue: list[tuple[float, int, LinkRow]] = []
+        tie_breaker = count()
+        departure_time = self.t0 + t_start
+
+        for start_link in self.fws.get(source_id, set()):
+            start_link_id, start_link_idx, _, _, link_costs = start_link
+            cost_index = self._time_index(departure_time)
+            arrival_time = departure_time + link_costs[cost_index]
+            paths_costs[start_link_id] = arrival_time
+            paths_links[start_link_id] = [start_link_idx]
+            push(queue, (arrival_time, next(tie_breaker), start_link))
+
+        while queue:
+            current_time, _, incoming_link = pop(queue)
+            incoming_link_id, _, _, current_node, _ = incoming_link
+
+            if current_time > paths_costs[incoming_link_id]:
+                continue
+
+            if current_node in residual_targets:
+                best_target_link[current_node] = incoming_link_id
+                residual_targets.discard(current_node)
+                if not residual_targets:
+                    break
+
+            for outgoing_link in self.links_fws.get(incoming_link_id, set()):
+                outgoing_link_id, outgoing_link_idx, _, _, outgoing_link_costs = outgoing_link
+                cost_index = self._time_index(current_time)
+                node_costs = self.nodes[current_node][2]
+                transition_cost = node_costs[cost_index]
+
+                for turn in self.turns.get((incoming_link_id, outgoing_link_id), set()):
+                    transition_cost += turn[4][cost_index]
+
+                outgoing_departure_time = current_time + transition_cost
+                link_cost_index = self._time_index(outgoing_departure_time)
+                candidate_time = outgoing_departure_time + outgoing_link_costs[link_cost_index]
+
+                if candidate_time < paths_costs[outgoing_link_id]:
+                    paths_costs[outgoing_link_id] = candidate_time
+                    paths_links[outgoing_link_id] = paths_links[incoming_link_id] + [
+                        outgoing_link_idx
+                    ]
+                    push(queue, (candidate_time, next(tie_breaker), outgoing_link))
+
+        for target_id in target_ids:
+            last_link_id = best_target_link.get(target_id)
+            if last_link_id is None:
+                continue
+            link_ids = paths_links[last_link_id]
+            path_costs = [paths_costs[self._links_idx[link_id]] for link_id in link_ids]
+            paths.add_path(
+                Path(
+                    source=source_label,
+                    target=self.nodes[target_id][1],
+                    t_start=t_start,
+                    links=link_ids,
+                    costs=path_costs,
+                    mode=self.mode,
+                    t_base=self.t0,
+                )
+            )
+
+        return paths
+
+    def _normalize_targets(
+        self,
+        targets: Iterable[Hashable] | Hashable | None,
+    ) -> set[Hashable]:
+        if targets is None:
+            return {node[1] for node in self.nodes}
+        try:
+            if targets in self._nodes_idx:
+                return {targets}
+        except TypeError:
+            pass
+        if isinstance(targets, Iterable) and not isinstance(targets, str | bytes):
+            return set(targets)
+        return {targets}
+
+    def _time_index(self, time_value: float | int) -> int:
+        if self.n_intervals <= 0:
+            return 0
+        return max(0, min(int((time_value - self.t0) // self.delta_t), self.n_intervals - 1))
+
+
+__all__ = ["TimeDependentLinkBasedShortestPath"]

graph/algorithms/__init__.py

@@ -0,0 +1,3 @@
+from .TD_LBSP import TimeDependentLinkBasedShortestPath
+
+__all__ = ["TimeDependentLinkBasedShortestPath"]

graph/graphs/__init__.py

@@ -0,0 +1,28 @@
+from .action_policy import ActionPolicy
+from .exceptions import (
+    ExistingLinkError,
+    ExistingNodeError,
+    ExistingTurnError,
+    GraphError,
+    MissingLinkError,
+    MissingNodeError,
+)
+from .graph import Graph
+from .link import Link
+from .node import Node
+from .turn import Turn, TurnType
+
+__all__ = [
+    "ActionPolicy",
+    "ExistingLinkError",
+    "ExistingNodeError",
+    "ExistingTurnError",
+    "Graph",
+    "GraphError",
+    "Link",
+    "MissingLinkError",
+    "MissingNodeError",
+    "Node",
+    "Turn",
+    "TurnType",
+]

graph/graphs/action_policy.py

@@ -0,0 +1,27 @@
+from __future__ import annotations
+
+from enum import Enum
+
+
+class ActionPolicy(str, Enum):
+    """Behaviour for duplicate, missing, or dependent entities."""
+
+    RAISE = "raise"
+    WARN = "warn"
+    IGNORE = "ignore"
+    REPLACE = "replace"
+    SKIP = "skip"
+
+    @classmethod
+    def parse(cls, value: ActionPolicy | str) -> ActionPolicy:
+        """Return an ``ActionPolicy`` from an enum value or string."""
+        if isinstance(value, cls):
+            return value
+        try:
+            return cls(value)
+        except ValueError as exc:
+            msg = "policy must be 'raise', 'warn', 'ignore', 'replace', or 'skip'"
+            raise ValueError(msg) from exc
+
+
+__all__ = ["ActionPolicy"]