ga-graph 0.1.0__tar.gz

ga_graph-0.1.0/CHANGELOG.md

@@ -0,0 +1,11 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+## 0.1.0 - 2026-09-01
+
+- Prepared the package for GitHub and PyPI publication as `ga-graph`.
+- Added README, documentation, changelog, MIT license, gitignore, manifest, and typed package marker.
+- Corrected packaging metadata, project URLs, coverage source, and GitHub Actions imports.
+- Added a focused `pytest` suite for graph operations, path containers, turn helpers, routing, and version exports.
+- Fixed graph neighbor filtering, cascade removals, redundant cleanup, filtered removals, k-path lookup, and time-dependent routing turn handling.

ga_graph-0.1.0/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/MANIFEST.in

@@ -0,0 +1,2 @@
+include CHANGELOG.md
+recursive-include docs *.md

ga_graph-0.1.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,164 @@
+# 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/docs/api.md

@@ -0,0 +1,67 @@
+# API Reference
+
+## `Graph`
+
+```python
+Graph(t0=0, total_time=60, delta_t=15, **kwargs)
+```
+
+Stores nodes, directed links, and turns. Nodes, links, and turns are dictionary
+subclasses, so custom attributes can be attached directly.
+
+Main methods:
+
+- `add_node(idx, on_existing=ActionPolicy.RAISE, **kwargs)`
+- `add_link(idx, i, j, on_existing=..., on_missing_node=..., **kwargs)`
+- `add_turn(idx, in_link, out_link, on_existing=..., on_missing_link=..., **kwargs)`
+- `get_node(idx)`, `get_link(idx)`, `get_turn(idx)`
+- `get_all_nodes()`, `get_all_links()`, `get_all_turns()`
+- `remove_node(idx, cascade=False)`, `remove_link(idx, cascade=False)`
+- `remove_redundants()`
+- `resize_attributes(new_total_time=None, new_delta_t=None)`
+
+## `Path`, `PathList`, and `KPathList`
+
+```python
+Path(source, target, t_start, links=None, costs=None, tot_cost=0.0, mode=None)
+PathList()
+KPathList()
+```
+
+`Path` stores the labels and cumulative costs for a route. `PathList` keeps one
+path per `(source, target, t_start, mode)` key. `KPathList` keeps multiple
+k-ranked paths for the same key.
+
+Main methods:
+
+- `Path.key()`
+- `Path.get_links()`
+- `Path.get_costs()`
+- `Path.has_link(id_link)`
+- `Path.counts_link(id_link)`
+- `PathList.add_path(path)`
+- `PathList.path(source, target, t_start=0, mode=None)`
+- `KPathList.add_path(path, k=None)`
+- `KPathList.path(source, target, t_start=None, mode=None, k=0)`
+- `KPathList.paths(source, target, t_start, mode=None)`
+
+## `TurnType`
+
+```python
+TurnType.parse(value)
+TurnType.classify_turn(in_edge_geometry, out_edge_geometry, angles=(30, 60, 120, 150))
+```
+
+Provides semantic labels for straight, left, right, sharp, and U-turn
+movements. Geometries must expose a `.coords` sequence.
+
+## `TimeDependentLinkBasedShortestPath`
+
+```python
+TimeDependentLinkBasedShortestPath.from_graph(graph, ...)
+router.shortest_paths(source, targets=None, t_start=0)
+```
+
+Builds a dense link-based routing view from `Graph`. It supports scalar or
+sequence cost fields on nodes, links, and turns, mode filters, and prohibited
+turn fields.

ga_graph-0.1.0/docs/index.md

@@ -0,0 +1,8 @@
+# GA Graph Documentation
+
+GA Graph contains lightweight graph containers, path collections, turn helpers,
+and a link-based time-dependent shortest-path router.
+
+- See [API Reference](api.md) for the public classes and methods.
+- See the project [README](../README.md) for installation, quick start, and
+  release instructions.

ga_graph-0.1.0/pyproject.toml

@@ -0,0 +1,86 @@
+[build-system]
+requires = ["setuptools>=77", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "ga-graph"
+dynamic = ["version"]
+description = "Lightweight graph, turn, path, and time-dependent routing utilities."
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [
+  { name = "GA Graph contributors" }
+]
+keywords = ["ga-graph", "graph", "routing", "shortest-path", "transport-network"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Developers",
+  "Programming Language :: Python :: 3 :: Only",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Programming Language :: Python :: 3.14",
+  "Topic :: Software Development :: Libraries :: Python Modules",
+  "Typing :: Typed"
+]
+dependencies = [
+  "dill>=0.3.8"
+]
+
+[project.optional-dependencies]
+test = [
+  "pytest>=8.0",
+  "pytest-cov>=5.0"
+]
+dev = [
+  "build>=1.2",
+  "mypy>=1.10",
+  "pytest>=8.0",
+  "pytest-cov>=5.0",
+  "ruff>=0.5",
+  "twine>=5.1"
+]
+
+[project.urls]
+Documentation = "https://github.com/andreagemma/graph#readme"
+Issues = "https://github.com/andreagemma/graph/issues"
+Source = "https://github.com/andreagemma/graph"
+
+[tool.setuptools]
+package-dir = {"" = "src"}
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+graph = ["py.typed"]
+
+[tool.setuptools.dynamic]
+version = {attr = "graph._version.__version__"}
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-ra --strict-markers"
+
+[tool.coverage.run]
+branch = true
+source = ["graph"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py310"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B", "SIM"]
+
+[tool.mypy]
+python_version = "3.10"
+files = ["src"]
+warn_unused_configs = true
+check_untyped_defs = true
+follow_imports = "skip"
+no_site_packages = true
+ignore_missing_imports = true

ga_graph-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+