pgraph-python 0.6.4__tar.gz → 1.0.0__tar.gz

pgraph_python-1.0.0/.codacy.yml

@@ -0,0 +1,7 @@
+---
+exclude_paths:
+  # Developer scripts that regenerate documentation assets (e.g. the README
+  # logo), not part of the installed package. They shell out to fixed
+  # commands like rsvg-convert, which Bandit flags (B404/B603/B607) even
+  # though no untrusted input is involved.
+  - "docs/figs/**"

pgraph_python-1.0.0/.github/dependabot.yml

@@ -0,0 +1,8 @@
+version: 2
+updates:
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "monthly"
+    labels:
+      - "dependencies"

pgraph_python-1.0.0/.github/workflows/ci.yml

@@ -0,0 +1,121 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+  workflow_dispatch:
+
+jobs:
+  unittest:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.9", "3.10", "3.11", "3.12", "3.13", "3.14"]
+    steps:
+      - uses: actions/checkout@v7
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v7
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install .[dev]
+          sudo apt-get update
+          sudo apt-get install -y graphviz
+      - name: Test with pytest
+        run: pytest
+
+  mypy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - name: Set up Python 3.11
+        uses: actions/setup-python@v7
+        with:
+          python-version: "3.11"
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install .[dev]
+      - name: Run mypy
+        run: mypy src/pgraph/PGraph.py
+
+  all-tests-passed:
+    name: All tests passed
+    needs: unittest
+    runs-on: ubuntu-latest
+    if: always()
+    steps:
+      - name: Check test matrix result
+        run: |
+          if [ "${{ needs.unittest.result }}" != "success" ]; then
+            echo "test matrix did not succeed: ${{ needs.unittest.result }}"
+            exit 1
+          fi
+
+  codecov:
+    needs: unittest
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - name: Set up Python 3.11
+        uses: actions/setup-python@v7
+        with:
+          python-version: "3.11"
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e .[dev]
+          sudo apt-get update
+          sudo apt-get install -y graphviz
+      - name: Run coverage
+        run: |
+          pytest --cov=pgraph --cov-report=xml:coverage.xml
+          coverage report
+      - name: Upload coverage to Codecov
+        uses: codecov/codecov-action@v7
+        with:
+          files: ./coverage.xml
+          verbose: true
+
+  docs:
+    if: github.event_name == 'push' || (github.event_name == 'workflow_dispatch' && github.ref == 'refs/heads/main')
+    needs: unittest
+    runs-on: ubuntu-latest
+    # The site is served from a GitHub Pages deployment, not from the gh-pages
+    # branch, so the artifact is deployed with the Pages actions.
+    permissions:
+      contents: read
+      pages: write
+      id-token: write
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - uses: actions/checkout@v7
+      - name: Set up Python 3.11
+        uses: actions/setup-python@v7
+        with:
+          python-version: "3.11"
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install .[docs]
+          sudo apt-get update
+          sudo apt-get install -y graphviz
+      - name: Build docs
+        run: |
+          make -C docs html llms
+          touch docs/build/html/.nojekyll
+      - name: Setup Pages
+        uses: actions/configure-pages@v6
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v5
+        with:
+          path: docs/build/html
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v5

pgraph_python-1.0.0/.github/workflows/dependabot-auto-merge.yml

@@ -0,0 +1,25 @@
+name: Dependabot auto-merge
+
+on: pull_request
+
+permissions:
+  contents: write
+  pull-requests: write
+
+jobs:
+  dependabot:
+    runs-on: ubuntu-latest
+    if: ${{ github.actor == 'dependabot[bot]' }}
+    steps:
+      - name: Dependabot metadata
+        id: metadata
+        uses: dependabot/fetch-metadata@v3
+        with:
+          github-token: "${{ secrets.GITHUB_TOKEN }}"
+
+      - name: Enable auto-merge for patch/minor bumps
+        if: ${{ steps.metadata.outputs.update-type == 'version-update:semver-patch' || steps.metadata.outputs.update-type == 'version-update:semver-minor' }}
+        run: gh pr merge --auto --merge "$PR_URL"
+        env:
+          PR_URL: ${{ github.event.pull_request.html_url }}
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}

pgraph_python-1.0.0/.github/workflows/publish.yml

@@ -0,0 +1,115 @@
+# Build and publish to PyPI when a GitHub release is created, or on manual trigger.
+# Uses OIDC trusted publishing, so no PyPI token is stored.  The trusted publisher
+# on PyPI is: owner petercorke, repository pgraph-python, workflow publish.yml,
+# environment pypi.  Pure Python package, so one universal wheel and an sdist.
+#
+# To release: make sure main has the version in pyproject.toml, then create a
+# GitHub release whose tag is v<version> on main.
+
+name: Publish to PyPI
+
+on:
+  release:
+    types: [created]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  verify_version:
+    name: Verify tag matches package version
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          fetch-depth: 0
+      - name: Check version
+        # Skip on manual workflow_dispatch runs (no release tag exists)
+        if: github.event_name == 'release'
+        run: |
+          TAG="${GITHUB_REF_NAME#v}"
+          PKG=$(python3 -c "import tomllib; print(tomllib.load(open('pyproject.toml','rb'))['project']['version'])")
+          echo "Tag version    : $TAG"
+          echo "Package version: $PKG"
+          [ "$TAG" = "$PKG" ] || { echo "ERROR: tag $GITHUB_REF_NAME does not match pyproject.toml version $PKG"; exit 1; }
+      - name: Check the tagged commit is on main
+        if: github.event_name == 'release'
+        run: |
+          git fetch origin main
+          git merge-base --is-ancestor "$GITHUB_SHA" origin/main \
+            || { echo "ERROR: $GITHUB_SHA is not on main, so it was not reviewed and tested there"; exit 1; }
+
+  build:
+    name: Build sdist and wheel
+    needs: verify_version
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+
+      - uses: actions/setup-python@v7
+        with:
+          python-version: "3.12"
+
+      - name: Build sdist and wheel
+        run: pipx run build
+
+      - name: Check metadata
+        run: pipx run twine check dist/*
+
+      - uses: actions/upload-artifact@v7
+        with:
+          name: dist
+          path: dist/
+
+  smoke_test:
+    name: Smoke-test wheel
+    needs: build
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/setup-python@v7
+        with:
+          python-version: "3.12"
+
+      - uses: actions/download-artifact@v8
+        with:
+          name: dist
+          path: dist
+
+      - name: Install the wheel (pulls dependencies from PyPI)
+        run: pip install dist/*.whl
+
+      - name: Smoke test
+        run: |
+          python - <<'PY'
+          from importlib.metadata import version
+          import pgraph
+
+          g = pgraph.UGraph()
+          g.add_vertex(coord=[0, 0], name="a")
+          g.add_vertex(coord=[3, 4], name="b")
+          g.add_edge("a", "b")
+          path, length, _ = g.path_Astar("a", "b")
+          assert length == 5.0, length
+          print("OK", version("pgraph-python"), length)
+          PY
+
+  upload_pypi:
+    name: Publish to PyPI
+    needs: [build, smoke_test]
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/project/pgraph-python/
+    permissions:
+      id-token: write   # required for OIDC trusted publishing
+    steps:
+      - uses: actions/download-artifact@v8
+        with:
+          name: dist
+          path: dist
+
+      # pinned to a commit, as this action can publish to PyPI; dependabot updates it
+      - uses: pypa/gh-action-pypi-publish@dc37677b2e1c63e2034f94d8a5b11f265b73ba33  # v1.14.2
+        with:
+          skip-existing: true

pgraph_python-1.0.0/AGENTS.md

@@ -0,0 +1,29 @@
+# pgraph-python — Agent Instructions
+
+> **Audience:** agents working on pgraph's source code. If you're helping someone *use* pgraph, read https://petercorke.github.io/pgraph-python/llms.txt instead (or `llms-full.txt` for the complete documentation).
+
+Part of the RVC ecosystem. **Read [rvc-ecosystem/AGENTS.md](https://github.com/petercorke/rvc-ecosystem/blob/main/AGENTS.md) first** — it defines shared conventions: repo ownership, math invariants, dependency boundaries, git/PR workflow, code standards, tech-debt tracking. This file only adds what's specific to this repo.
+
+| | |
+|---|---|
+| PyPI package | `pgraph-python` |
+| Nickname | pgraph-python |
+| Owner | Peter Corke (`petercorke`) |
+| Default branch | `main` |
+| Contribution model | Branch → PR; `main` is protected: CI must pass and the branch must be up to date (`gh pr update-branch`) |
+
+## Notes specific to this repo
+
+- Minimal graph/path-planning package. Pure Python, builds with Hatch (`hatchling`); Python 3.9+. Depends on `numpy`, `matplotlib` and `spatialmath-python`; `ansitable` and `scipy` arrive through spatialmath. **Do not add scipy to `pyproject.toml`**: it is imported lazily, only inside `Graph.build_kdtree()`.
+- Used, unpinned (`"pgraph-python"`), by `robotics-toolbox-python` (`PRMPlanner`, `RRTPlanner`, `LatticePlanner`, `PoseGraph`, which subclass `UVertex`/`DVertex`) and `machinevision-toolbox-python` (`BundleAdjust`). A breaking change needs a deprecation cycle with a working fallback (`warnings.warn(..., DeprecationWarning, stacklevel=2)`); run their pgraph-using tests before a release.
+- **Layout.** `src/pgraph/PGraph.py` holds `Graph`, `UGraph`, `DGraph`, `Vertex`, `Edge` and `SE2Metric`; `exporters.py` the `export()` formats. There is one `Vertex` class: a vertex has no direction, the graph decides how an edge is recorded (`UGraph`/`DGraph` implement the hooks `_attach`, `_detach`, `_incoming` and `_endpoints_match`). `UVertex`/`DVertex` are deprecated aliases, by module `__getattr__`.
+- **Records that must agree.** A vertex has `_edgelist` (leaving, or incident if undirected) and `_inlist` (entering, directed only); the graph has `_vertexlist`, `_vertexdict` (names) and `_edges` (an insertion-ordered dict). `g.validate()` checks them all; use it in tests of anything that edits the structure.
+- **Two staleness flags, consumed independently.** `_connectivitychange` (components, reset by `_graphcolor`) and `_spatialchange` (the k-d tree). Set both wherever a vertex is added or removed; only connectivity cares about edges. Never share one flag.
+- **`Vertex.__setattr__` is hot.** It exists to tell the graph that `coord` was assigned. Anything run per vertex (`Vertex.__init__`, `add_vertex`, components) writes `vertex.__dict__` directly to skip it; keep doing that, and declare new attributes at class level so mypy knows them.
+- **`import pgraph` loads only numpy.** matplotlib, spatialmath and scipy are imported by the methods that need them (`plot`, `highlight_*`, `_edge_artist`, `build_kdtree`), and the classes that need matplotlib to be defined are in `_plot.py`. `tests/test_lazy_imports.py` runs a fresh interpreter to check it: do not add a module-level import of them.
+- **Pickle and `copy` use a flat description** (`__getstate__`/`__setstate__`: vertices, edges by index, replayed through `_attach`); `subgraph` reuses it. Derived or transient state on a graph (the k-d tree) must be excluded there. A bare vertex or edge refuses to be pickled or copied.
+- **Tests** are `unittest` classes in `tests/`, run with `pytest`; write expected values by hand or from an oracle in the test, never from the code under test. Import names explicitly (a star import is a Codacy `F405`); route `pickle` through one helper marked `# nosec B301 nosemgrep`. Codecov gates patch coverage, so every changed line needs a test. `mypy src` is a CI check.
+- **Performance claims are measured.** `examples/benchmark.py` (`--md`, `--directed`) produces the README tables; regenerate them after a performance change and compare with `v0.6.5` (`git archive v0.6.5 src`), not with a development build.
+- **Docs** are Sphinx (`make -C docs html`; `-n` for nitpicky) with `sphinx-pyrunblock` `.. runblock:: pycon` examples that execute at build. `docs/llms_intro.md` is the hand-written part of `llms.txt`: update it when the API changes; `docs/llms_txt.py` builds `llms.txt` and `llms-full.txt` from it and the toctrees (`make html llms`), and CI publishes them with the site.
+- **Release.** Version is in `pyproject.toml`, history in `CHANGELOG.md`. Publishing is `.github/workflows/publish.yml` on a GitHub Release (trusted publishing, environment `pypi`): it refuses unless the tag equals the version and the commit is on `main`. Don't tag or upload by hand.
+- `examples/london.json` is OpenStreetMap data (© OpenStreetMap contributors, ODbL); keep the attribution with it.

pgraph_python-1.0.0/CHANGELOG.md

@@ -0,0 +1,212 @@
+1.0.0
+
+First 1.0 release: six years of production use since the first commit in 2020
+(including as a real dependency of both the Robotics Toolbox for Python and the
+Machine Vision Toolbox for Python), and this cycle's type hints, documentation,
+testing and bug-fixing pass, felt like the right point to commit to API
+stability.  This is the first release with a considered API, so it contains
+several deliberate breaking changes, listed first with how to migrate.
+
+Breaking changes (from 0.6.5)
+
+- The `UGraph`/`DGraph` constructor arguments are keyword-only.  0.6.5 accepted
+  and silently ignored a first positional argument, so `UGraph(6)` looked as
+  though it set a dimension but did nothing.  Now it is a `TypeError`: write
+  `UGraph(dim=6)`.
+- `degree` of a `DGraph` is the graph-theory degree, in plus out, so a
+  self-loop counts 2 and the degrees sum to twice the number of edges.  It used
+  to count only the edges leaving the vertex.  This changes `vertex.degree`,
+  `graph.degree()` and `graph.connectivity()`, and `graph.average_degree()` is
+  now 2E/N for both kinds of graph (it was E/N for a `DGraph`).  The previous
+  values are `vertex.out_degree`, `[v.out_degree for v in g]` and `g.ne / g.n`.
+  `laplacian()` is unchanged (out-degree minus adjacency).  Undirected graphs
+  are unchanged.
+- `graph.edges()` is a `list` in the order the edges were added.  It was the
+  graph's own `set`, with no defined order, although documented as a list.  Both
+  `graph.edges()` and `vertex.edges()` return a new list, so changing the result
+  cannot corrupt the graph.  Use `set(g.edges())` for set operations.
+- `Edge.v1` and `Edge.v2` are read-only, and so is `Vertex.label` (the graph
+  assigns it, and reading it now finds the components, where 0.6.5 gave `None`
+  until `nc` had been asked for).  Assigning an endpoint of an edge that was in a graph left the
+  graph inconsistent and the edge impossible to remove.  Give the vertices to
+  `Edge(v1, v2)` or connect the edge with `v1.connect(v2, edge=e)`.
+- Assigning `Vertex.name` renames it in the graph (so `g[new]` works) and
+  refuses a name already in use or `None`.
+- `add_vertex` raises `ValueError` for a name already used in the graph or a
+  vertex that already belongs to a graph, instead of silently shadowing it.
+  The default name `#N` is now the first free one, which could previously
+  repeat after a removal.
+- There is one vertex class, `Vertex`: a vertex has no direction of its own, the
+  graph it belongs to decides how an edge is recorded at its ends.  `UVertex`
+  and `DVertex` are deprecated names for it (below).  A vertex given to
+  `add_vertex` is no longer checked against the kind of graph, because there is
+  no kind to mismatch.  An override of the private `_attach`/`_detach` hooks
+  moves from a vertex subclass to a `UGraph`/`DGraph` subclass.
+- The abstract base class `PGraph` is now `Graph`, and `Graph` and `Vertex` are
+  exported from the package.  `Graph` is concrete: `Graph(directed=True)` is a
+  `DGraph` and `Graph()` a `UGraph`.
+- `Adjacency()` treats a non-zero diagonal element as a self-loop.
+- The `str` of an edge between vertices that are not in a graph shows `--`,
+  because there is no kind of graph to say whether it is directed.
+
+Deprecated (still work, with a `DeprecationWarning`)
+
+- `Laplacian()` is `laplacian()`: a capital initial denotes a class method that
+  builds a graph, like `Adjacency()` and `Dict()`.
+- `UVertex` and `DVertex` are `Vertex`.
+- `remove()` is `remove_vertex()` or `remove_edge()`, which say which they do.
+- The options of `plot()` are named for what they are: `vopt` is `vertex_opt`,
+  `eopt` is `edge_opt`, `text` is `labels` and `text_opt`, `colorcomponents` is
+  `color_components` and `force2d` is `force_2d`.  The positional order is
+  unchanged; giving both an old name and its new one is a `TypeError`.
+
+Added
+
+- `adjacent()` and `isadjacent()`, the graph-theory names, which have one
+  spelling.  `neighbours()`, `neighbors()` and `isneighbour()` from 0.6.5 are
+  kept as aliases, with `isneighbor()` added, and none of them warn.
+- `plot()` draws each edge once.  A directed graph has arrowheads, which
+  `arrow_opt` styles; edges that join the same pair of vertices, in either
+  direction, are arcs that bow apart; and a loop is a circle at its vertex.  In
+  0.6.5 a directed graph looked like an undirected one, parallel edges lay
+  exactly on top of each other and a loop was a line of no length.  `plot()`
+  does the same in 3D, and `highlight_edge()` follows an arc.
+- `Graph(directed=...)`, the `directed` property, and `vertex_class` and
+  `edge_class` constructor arguments, so that user subclasses of `Vertex` and
+  `Edge` are built by the graph.
+- `add_edge()` accepts an `Edge`, and `connect()` an `edge=` argument.
+- `edges_to(dest)` lists every edge from a vertex to another, so parallel edges
+  can be seen; `edgeto(dest)` is still the cheapest.
+- Directed vertices record their incoming edges: `predecessors()`,
+  `successors()`, `in_edges()`, `out_edges()`, `in_degree` and `out_degree`.
+- `export()` writes a graph as GraphViz dot, Mermaid, GraphML or ELK JSON, or as
+  an image rendered by the GraphViz executables, with the layout preserved.  The
+  `pgraph.exporters` module can be extended with `register_exporter`.
+- `validate()` reports every way in which a graph's records disagree, for tests
+  and debugging.
+- A graph can be pickled, and `copy()` works for graphs of any size.  `copy()`
+  raised `RecursionError` for a path of about 100 vertices.
+- `iscyclic()`, `remove_edge()`, `remove_vertex()` and the `dim` argument, which
+  declares that every embedded vertex has a coordinate of exactly that length.
+- Self-loops and parallel edges are supported throughout: adjacency, incidence,
+  degree and Laplacian matrices, and planning, which takes the cheapest of
+  parallel edges.
+- `SE2Metric(weight)` is the `"SE2"` metric with a weight on the angle, the
+  length that a radian is worth, so that position and orientation need not
+  count equally.  `"SE2"` is `SE2Metric()`, a weight of 1, so existing results
+  are unchanged.  It can be the metric or the heuristic of a graph and is
+  pickled with its weight.
+- Spatial queries on an embedded graph: `coordinates()` is the matrix of vertex
+  coordinates, a column per vertex; `within(box)` the vertices inside a box;
+  `near(point, radius)` those within a distance, nearest first; and
+  `subgraph(vertices)` the graph that a set of vertices induces, given as
+  vertices, names or a boolean mask, as a new graph that shares nothing with
+  the original.
+- `build_kdtree()` makes an optional k-d tree that `closest()` and `near()` use
+  for the built-in metrics, `SE2Metric` included.  It needs scipy, which is
+  imported only then and is not a dependency; and it is dropped whenever a
+  vertex is added or removed or a coordinate is assigned, so a stale one is
+  never used.
+- `validate()` also checks that coordinates are finite vectors of one length,
+  and with `embedded=True` that every vertex has one.
+
+Faster
+
+- `path_BFS`, `path_UCS` and `path_Astar` scaled badly: they searched lists with
+  `in`, and took the minimum of the whole frontier at every step.  Results and
+  the verbose output are identical.  On a random graph of 10,000 vertices and
+  30,000 edges, the mean of six random queries is 3 ms for breadth-first search
+  where 0.6.5 took 172 ms, 18 ms for uniform cost where it took 1,500 ms, and
+  13 ms for A* where it took 410 ms.
+- The components are found by a union-find over the edges, 4 ms for that graph
+  where 0.6.5 took 15 ms after a change.
+- Creating a vertex is faster: `Vertex(coord)` takes 0.35 µs where 0.6.5 took
+  1.5 µs, and `g.add_vertex(coord)` 1.7 µs where it took 2.2 µs.  Making the
+  coordinate with `np.r_` was most of the cost.
+- `import pgraph` takes 0.04 s where it took 0.6 s, and loads neither
+  matplotlib, spatialmath nor scipy: they are imported by the methods that plot
+  or build a spatial index.  A script that only builds graphs and plans paths no
+  longer pays for them.
+- `str(g)` separates thousands: `DGraph: 4,881 vertices, 8,392 edges, 14
+  components`.
+
+Fixed
+
+- `Dict()` always created undirected vertices, even for a `DGraph`; `connect()`
+  joined vertices of two different graphs, and now also validates the
+  endpoints of a supplied edge; `path_BFS`/`path_UCS`/`path_Astar` checked the
+  type of the start vertex twice and never the goal; and `distance()` and the
+  planners packed `nan` or `None` into their results for edges with no cost
+  instead of raising.
+- `nc` never returned for many directed graphs, the smallest a 4-cycle, and
+  neither did `component()`, `samecomponent()` or `plot()`, which ask for it.
+  Components of a directed graph are weakly connected, as they were meant to
+  be, and are numbered from 0 by the first vertex of each, for both kinds of
+  graph.  They are also no longer found again by every call once the graph has
+  changed.
+- `Edge.vertices()` raised `DeprecationWarning` as an exception; it now warns
+  and returns the endpoints, as `Edge.endpoints` does.
+- `incidence()` returned the wrong matrix for every graph with an edge: a loop
+  variable overwrote the vertex index, so edges were marked in the wrong rows,
+  and for a directed graph the vertex at the end of an edge was not marked at
+  all.  The columns follow `edges()`, which is now in the order the edges were
+  added, where 0.6.5 used the order of a set.
+- `remove()` crashed for every directed edge; `dotfile()` closed `sys.stdout`
+  when called with its default arguments; and several methods raised a bare
+  `AttributeError` or `TypeError` instead of a clear message for a vertex with
+  no coordinate or no graph.
+- `highlight_edge()`, and so `highlight_path()`, raised `AttributeError` for a
+  graph of three dimensions, because it drew a flat arrow in the 3D axes (0.6.5
+  drew lines), and `highlight_vertex()` put its marker at z = 0.  They draw in
+  the dimension of the axes, so a 3D graph plotted with `force_2d` is
+  highlighted in 2D.
+- Removing a vertex left its `_graph` pointing at the graph; renaming a vertex
+  left the name table stale; `g[x]` accepted any type.
+
+Known limitations
+
+- A graph whose metric is a `lambda` or a locally defined function can be copied
+  but not pickled; the built-in `"L1"`, `"L2"` and `"SE2"` and module-level
+  functions can be.
+
+Build, tests and documentation
+
+- Modern type hints and reST docstrings throughout, most with a runnable
+  example, and `mypy` is a CI check.
+- The documentation is organized by task, with the data structures explained and
+  a policy page on object lifecycle, and builds with `sphinx-pyrunblock` (which
+  replaces the unmaintained `sphinx-autorun`) and the matplotlib plot directive.
+- The source distribution no longer contains a stale copy of the source
+  (`build/lib`, left by a setuptools build before the move to the `src` layout),
+  nor the `RELEASE` file, which held `0.6.1` and which nothing read.
+- Python 3.9 to 3.14 are tested, the unused `scipy` dependency is dropped, and
+  PyPI publishing is automated through GitHub Releases and trusted publishing.
+  The workflow checks that the tag is the version in `pyproject.toml` and that
+  the tagged commit is on `main`, and installs the built wheel and runs a path
+  query before it uploads.
+- The documentation site is deployed with the GitHub Pages actions.  It had not
+  been updated since January 2025, because the CI pushed to a branch that Pages
+  no longer served.
+- `llms.txt` and `llms-full.txt` are published with the documentation, for AI
+  assistants: a short introduction with a quick start and common mistakes, and the
+  whole documentation as one text file.  `AGENTS.md` describes the source for
+  assistants that work on it.
+- Two notebooks in `examples/`: `roads.ipynb`, the Queensland example, and
+  `london.ipynb`, the road network of central London from OpenStreetMap as a
+  directed graph with one-way streets, planned through with A*.  There is also
+  a benchmark, `examples/benchmark.py`, and the README has its results and an
+  installation section.
+- The Queensland figure in the README shows the shortest route.  It had been
+  drawn with coordinates in metres and distances in kilometres, which made the
+  A* heuristic far too large, so the route it found, 1,759 km, was not the
+  shortest, 1,659 km.
+
+0.6.3
+
+- runs with Numpy2.x
+- changed build system to .toml file
+- misc doco and changes
+- migrate package to src layout (pgraph under src/pgraph)
+- switch build backend to hatchling
+- update CI workflow for main branch and docs publish to gh-pages
+- update repository links and badges from master to main

{pgraph_python-0.6.4 → pgraph_python-1.0.0}/Makefile

@@ -9,8 +9,8 @@ help:
 	@echo " make docs - build Sphinx documentation"
 	@echo " make docupdate - upload Sphinx documentation to GitHub pages"
 	@echo " make dist - build dist files"
-	@echo " make upload - upload to PyPI"
 	@echo " make clean - remove dist and docs build files"
+	@echo " (PyPI publish is via GitHub Releases, see .github/workflows/publish.yml)"
 	@echo " make help - this message$(BLACK)"
 
 test:
@@ -34,17 +34,6 @@ dist: .FORCE
 	#$(MAKE) test
 	python -m build
 
-pypi: .FORCE
-	validate-pyproject pyproject.toml
-	@if ! git diff --quiet || ! git diff --cached --quiet; then \
-		echo "Error: uncommitted changes present, aborting upload"; exit 1; \
-	fi
-	$(eval VERSION := $(shell grep '^version' pyproject.toml | sed 's/version = "\(.*\)"/\1/'))
-	python -m build
-	twine upload dist/*
-	git tag v$(VERSION)
-	git push origin v$(VERSION)
-
 clean: .FORCE
 	(cd docs; make clean)
 	-rm -r *.egg-info