FazBrowse GitHub Viewer | Trending |
URL:
| Home
Tools: [Download Repo ZIP]   [Original HTTPS Page]

Add modern type hints and reST docstrings throughout PGraph.py · petercorke/pgraph-python@0768f97 · GitHub

  1. petercorke
  2. pgraph-python

Repository navigation

Commit 0768f97

Browse files
petercorke
and
claude
committed
Add modern type hints and reST docstrings throughout PGraph.py
Type-hints every public and most private members using PEP 604 union syntax (X | Y) and numpy.typing (ArrayLike/NDArray), with matching reST docstrings including runblock examples that are actually executed at doc build time. Adds mypy as an informational (non-blocking) CI job, and sphinx-pyrunblock/sphinx-codeautolink to the docs toolchain, replacing the unmaintained sphinx-autorun. Fixes a handful of small, incidental bugs surfaced while typing this pass touched: _metricfunc silently swallowing an unrecognized metric string instead of raising, and a missing __iter__/abstract _graphcolor that mypy couldn't otherwise see. No behavioural changes to any bugfix-cluster method (add_vertex, connect, remove, the path_* search methods, the matrix methods) -- those are typed together with their fixes in a follow-up branch, since the fix and the type hints land on the same lines for those methods. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
1 parent b6f513f commit 0768f97

12 files changed

Lines changed: 588 additions & 119 deletions

File tree

‎.github/workflows/ci.yml‎

Lines changed: 21 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -25,6 +25,27 @@ jobs:
2525
- name: Test with pytest
2626
run: pytest
2727

28+
mypy:
29+
runs-on: ubuntu-latest
30+
steps:
31+
- uses: actions/checkout@v4
32+
- name: Set up Python 3.11
33+
uses: actions/setup-python@v5
34+
with:
35+
python-version: "3.11"
36+
- name: Install dependencies
37+
run: |
38+
python -m pip install --upgrade pip
39+
pip install .[dev]
40+
- name: Run mypy
41+
# Informational only for now: the type-hinting pass surfaced a
42+
# baseline of pre-existing design tensions (Liskov-incompatible
43+
# overrides, embedded-graph invariants not visible to the type
44+
# checker) that are tracked separately, not fixed here. Don't fail
45+
# the build on them yet.
46+
continue-on-error: true
47+
run: mypy src/pgraph/PGraph.py
48+
2849
codecov:
2950
needs: unittest
3051
runs-on: ubuntu-latest
@@ -62,7 +83,6 @@ jobs:
6283
run: |
6384
python -m pip install --upgrade pip
6485
pip install .[docs]
65-
pip install git+https://github.com/petercorke/sphinx-autorun.git
6686
sudo apt-get update
6787
sudo apt-get install -y graphviz
6888
- name: Build docs

‎docs/source/PGraph.rst‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
PGraph module
22
=============
33

4-
.. automodule:: PGraph
4+
.. automodule:: pgraph.PGraph
55
:members:
66
:undoc-members:
77
:show-inheritance:

‎docs/source/conf.py‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -30,13 +30,33 @@
3030
# ones.
3131
extensions = [
3232
"sphinx.ext.autodoc",
33+
"sphinx.ext.autosummary",
3334
"sphinx.ext.todo",
3435
"sphinx.ext.viewcode",
3536
"sphinx.ext.mathjax",
3637
"sphinx.ext.coverage",
38+
"sphinx.ext.intersphinx",
3739
"sphinx.ext.inheritance_diagram",
40+
"sphinx_autodoc_typehints",
41+
"sphinx_copybutton",
42+
"sphinx_pyrunblock",
43+
"sphinx_codeautolink",
3844
]
3945

46+
autosummary_generate = True
47+
48+
# copybutton configuration: strip >>> and ... prompts when copying
49+
copybutton_prompt_text = r">>> |\.\.\. "
50+
copybutton_prompt_is_regexp = True
51+
52+
# sphinx_codeautolink: link names in code blocks to their API docs
53+
codeautolink_autodoc_inject = False
54+
55+
intersphinx_mapping = {
56+
"python": ("https://docs.python.org/3", None),
57+
"numpy": ("https://numpy.org/doc/stable/", None),
58+
}
59+
4060
html_theme_options = {
4161
"logo_only": False,
4262
"display_version": True,

‎docs/source/dgraph.rst‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@ Directed graph
22
--------------
33

44

5-
.. autoclass:: PGraph.DGraph
5+
.. autoclass:: pgraph.PGraph.DGraph
66
:undoc-members:
77
:show-inheritance:
88
:inherited-members:

‎docs/source/dvertex.rst‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
Directed graph vertex
22
---------------------
33

4-
.. autoclass:: PGraph.DVertex
4+
.. autoclass:: pgraph.PGraph.DVertex
55
:undoc-members:
66
:show-inheritance:
77
:inherited-members:

‎docs/source/edge.rst‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
Edge
22
----
33

4-
.. autoclass:: PGraph.Edge
4+
.. autoclass:: pgraph.PGraph.Edge
55
:undoc-members:
66
:show-inheritance:
77
:inherited-members:

‎docs/source/matrices.rst‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3,5 +3,5 @@ Convert graph to matrix form
33

44
These methods convert a graph to a matrix representation .
55

6-
.. autoclass:: PGraph.PGraph
6+
.. autoclass:: pgraph.PGraph.PGraph
77
:members: distance, adjacency, degree, incidence, Laplacian

‎docs/source/planning.rst‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3,5 +3,5 @@ Path planning
33

44
These methods find optimal paths from a start vertex to a goal vertex.
55

6-
.. autoclass:: PGraph.PGraph
6+
.. autoclass:: pgraph.PGraph.PGraph
77
:members: path_BFS, path_UCS, path_Astar

‎docs/source/ugraph.rst‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@ Undirected graph
22
----------------
33

44

5-
.. autoclass:: PGraph.UGraph
5+
.. autoclass:: pgraph.PGraph.UGraph
66
:undoc-members:
77
:show-inheritance:
88
:inherited-members:

‎docs/source/uvertex.rst‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
Undirected graph vertex
22
-----------------------
33

4-
.. autoclass:: PGraph.UVertex
4+
.. autoclass:: pgraph.PGraph.UVertex
55
:undoc-members:
66
:show-inheritance:
77
:inherited-members:

0 commit comments

Comments
 (0)
Back | FazBrowse Home | New Git URL