Skip to content

Commit 8cd5f28

Browse files
petercorkeclaude
andcommitted
docs: docstring corrections
Class docstring for Graph (so the construction table has a precis), Edge's cost and data are documented attributes, the precis of edges, Vertex.edges and edgeto say what they return, cross references that did not resolve, and typos. The only change to code is the text of an internal error message. Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
1 parent 6631f57 commit 8cd5f28

2 files changed

Lines changed: 46 additions & 26 deletions

File tree

‎src/pgraph/PGraph.py‎

Lines changed: 42 additions & 23 deletions
Original file line numberDiff line numberDiff line change
@@ -46,6 +46,17 @@ def _SE2(v: NDArray) -> float:
4646

4747

4848
class Graph:
49+
"""
50+
Base class for all graphs
51+
52+
A graph is a set of :class:`Vertex` objects joined by :class:`Edge`
53+
objects, which are directed or not according to the kind of graph:
54+
:class:`UGraph` is undirected and :class:`DGraph` is directed. This
55+
class holds everything they share, and ``Graph(directed=flag)`` makes one
56+
or the other. The constructor arguments are described below.
57+
58+
:seealso: :class:`UGraph` :class:`DGraph` :class:`Vertex` :class:`Edge`
59+
"""
4960

5061
#: whether the edges of this kind of graph are directed, set by
5162
#: :class:`UGraph` and :class:`DGraph`
@@ -218,7 +229,7 @@ def Dict(cls, d: dict, reverse: bool = False, **kwargs: Any) -> Graph:
218229
:param kwargs: optional arguments passed to the graph constructor, for
219230
example ``vertex_class`` or ``edge_class``
220231
:raises TypeError: ``vertex_class`` or ``edge_class`` is not a
221-
suitable class, see :meth:`Graph.__init__`
232+
suitable class, see :class:`~pgraph.PGraph.Graph`
222233
:return: graph
223234
:rtype: UGraph or DGraph
224235
@@ -290,7 +301,7 @@ def Adjacency(
290301
:raises ValueError: ``A`` is not square, or the length of ``names`` or
291302
the number of rows of ``coords`` does not match ``A``
292303
:raises TypeError: ``vertex_class`` or ``edge_class`` is not a
293-
suitable class, see :meth:`Graph.__init__`
304+
suitable class, see :class:`~pgraph.PGraph.Graph`
294305
:return: graph
295306
:rtype: UGraph or DGraph
296307
@@ -446,7 +457,7 @@ def vertex_class(self) -> type[Vertex]:
446457
:rtype: subclass of ``Vertex``
447458
448459
This is read-only. It is set by the ``vertex_class`` argument of the
449-
graph constructor, see :meth:`__init__`, and is :class:`Vertex` if not
460+
graph constructor, see :class:`Graph`, and is :class:`Vertex` if not
450461
given.
451462
452463
.. runblock:: pycon
@@ -470,7 +481,7 @@ def edge_class(self) -> type[Edge]:
470481
:rtype: subclass of ``Edge``
471482
472483
This is read-only. It is set by the ``edge_class`` argument of the
473-
graph constructor, see :meth:`__init__`, and is :class:`Edge` if not
484+
graph constructor, see :class:`Graph`, and is :class:`Edge` if not
474485
given.
475486
476487
.. runblock:: pycon
@@ -865,7 +876,7 @@ def add_vertex(
865876
>>> g['v2']
866877
867878
If the graph was constructed with a required ``dim`` (see
868-
:meth:`Graph.__init__`), every embedded vertex must have a
879+
:class:`Graph`), every embedded vertex must have a
869880
coordinate of exactly that length -- adding one of the wrong length
870881
raises ``ValueError``:
871882
@@ -1079,7 +1090,7 @@ def add_edge(
10791090
>>> e = g.add_edge(MyEdge(v1, v2, data="a road"))
10801091
>>> print(type(e).__name__, e.data)
10811092
1082-
.. note:: Vertices have coordinates and the edge ``cost`` defaults to the distance between them, but if the vertices have no coordinates the edge cost must be set explicitly, otherwise it will be ``None`` and path planning will fail with a ``ValueError``. See :meth:`_require_cost` for details.
1093+
.. note:: Vertices have coordinates and the edge ``cost`` defaults to the distance between them, but if the vertices have no coordinates the edge cost must be set explicitly, otherwise it will be ``None`` and path planning will fail with a ``ValueError``.
10831094
10841095
.. note:: To supply an edge that does not yet have vertices use
10851096
``g.add_edge(v1, v2, edge=e)`` or ``e.connect(v1, v2)``.
@@ -1616,7 +1627,7 @@ def closest(self, coord: ArrayLike) -> tuple[Vertex | None, float]:
16161627

16171628
def edges(self) -> list[Edge]:
16181629
"""
1619-
Return a set of all edges in graph (base class method)
1630+
All edges in the graph, in the order they were added
16201631
16211632
:return: All edges in the graph
16221633
:rtype: list of Edge references
@@ -2137,7 +2148,7 @@ def dotfile(
21372148
- The graph is directed if it is a :class:`DGraph`
21382149
21392150
.. note:: The ``graphviz`` formatters ``dot`` and ``neato`` can be used to render the
2140-
graph in various formats including PDF, PNG, JPG, GIF, SVG, etc. The formmatters are
2151+
graph in various formats including PDF, PNG, JPG, GIF, SVG, etc. The formatters are
21412152
similar, but ``dot`` is better suited for directed graphs while ``neato`` is better
21422153
suited for undirected graphs.
21432154
@@ -2304,7 +2315,7 @@ def average_degree(self) -> float:
23042315

23052316
def laplacian(self) -> NDArray:
23062317
"""
2307-
Convert the graph to a Laplacian matrix
2318+
Convert graph to a Laplacian matrix
23082319
23092320
:return: Laplacian matrix
23102321
:rtype: NumPy ndarray
@@ -2652,7 +2663,7 @@ def component(self, c: int) -> list[Vertex]:
26522663
26532664
:seealso: :attr:`nc` :meth:`samecomponent`
26542665
"""
2655-
self._graphcolor() # ensure labels are uptodate
2666+
self._graphcolor() # ensure labels are up to date
26562667
return [v for v in self if v.label == c]
26572668

26582669
def samecomponent(self, v1: Vertex, v2: Vertex) -> bool:
@@ -2684,7 +2695,7 @@ def samecomponent(self, v1: Vertex, v2: Vertex) -> bool:
26842695
26852696
:seealso: :meth:`component` :attr:`nc`
26862697
"""
2687-
self._graphcolor() # ensure labels are uptodate
2698+
self._graphcolor() # ensure labels are up to date
26882699

26892700
return v1.label == v2.label
26902701

@@ -3289,13 +3300,21 @@ class Edge:
32893300
"""
32903301
Edge class
32913302
3292-
Is used to represent directed directed and undirected edges.
3303+
Is used to represent directed and undirected edges.
3304+
3305+
Each edge has a cost, arbitrary data, and two vertices :attr:`v1` and
3306+
:attr:`v2`, which are read-only: the start and end vertex for a directed
3307+
edge.
32933308
3294-
Each edge has:
3295-
- ``cost`` cost of traversing this edge, required for planning methods
3296-
- ``data`` reference to arbitrary data associated with the edge
3297-
- ``v1`` first vertex, start vertex for a directed edge (read-only)
3298-
- ``v2`` second vertex, end vertex for a directed edge (read-only)
3309+
.. attribute:: cost
3310+
:type: float | None
3311+
3312+
cost of traversing this edge, required for planning methods
3313+
3314+
.. attribute:: data
3315+
:type: Any
3316+
3317+
reference to arbitrary data associated with the edge
32993318
33003319
.. note::
33013320
@@ -3326,9 +3345,9 @@ def __init__(
33263345
Create an edge object
33273346
33283347
:param v1: start of the edge, defaults to None
3329-
:type v1: Vertex subclass, optional
3348+
:type v1: :class:`Vertex`, optional
33303349
:param v2: end of the edge, defaults to None
3331-
:type v2: Vertex subclass, optional
3350+
:type v2: :class:`Vertex`, optional
33323351
:param cost: edge cost, defaults to None
33333352
:type cost: any, optional
33343353
:param data: edge data, defaults to None
@@ -3563,7 +3582,7 @@ def next(self, vertex: Vertex) -> Vertex:
35633582
assert self.v1 is not None
35643583
return self.v1
35653584
else:
3566-
raise ValueError("shouldnt happen")
3585+
raise ValueError("should not happen")
35673586

35683587
def vertices(self) -> list[Vertex]:
35693588
"""
@@ -3772,7 +3791,7 @@ def copy(self, cls: type[Graph] | None = None) -> Vertex:
37723791
>>> v2 = v.copy(cls=DGraph)
37733792
>>> print(v2)
37743793
3775-
:seealso: :meth:`UGraph.vertex_copy` :meth:`DGraph.vertex_copy`
3794+
:seealso: :meth:`Graph.vertex_copy`
37763795
"""
37773796
if cls is not None:
37783797
return cls.vertex_copy(self)
@@ -4100,7 +4119,7 @@ def edges_to(self, dest: Vertex) -> list[Edge]:
41004119

41014120
def edges(self) -> list[Edge]:
41024121
"""
4103-
Return a list of the edges for vertex
4122+
The edges at the vertex, in the order they were connected
41044123
41054124
:return: the edges at this vertex
41064125
:rtype: list of ``Edge``
@@ -4180,7 +4199,7 @@ def distance(self, coord: ArrayLike | Vertex) -> float:
41804199
>>> v2 = g.add_vertex(coord=[3,4], name='v2')
41814200
>>> print(v1.distance(v2))
41824201
4183-
:seealso: :meth:`metric`
4202+
:seealso: :attr:`Graph.metric`
41844203
"""
41854204
if self._graph is None:
41864205
raise ValueError("vertex is not connected to a graph")

‎src/pgraph/exporters.py‎

Lines changed: 4 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22
Export a graph as text (GraphViz DOT, Mermaid, GraphML, ELK JSON) or as a
33
rendered image (via the GraphViz command line tools).
44
5-
This module is reached through :meth:`pgraph.PGraph.Graph.export`, which
5+
This module is reached through :meth:`~pgraph.PGraph.Graph.export`, which
66
dispatches on the format name or the file extension. Each text exporter is a
77
plain function ``f(graph, **options) -> str``, registered with
88
:func:`register_exporter`, so a user can add a format without touching the
@@ -160,7 +160,7 @@ def _ordered_edges(graph: Graph) -> list[tuple[Edge, Vertex, Vertex]]:
160160

161161
def _component_colors(graph: Graph) -> dict[Vertex, str]:
162162
"""
163-
Map each vertex to a ``#rrggbb`` colour for its component, as plot() does
163+
Map each vertex to a ``#rrggbb`` color for its component, as plot() does
164164
"""
165165
import matplotlib.pyplot as plt
166166
import numpy as np
@@ -270,7 +270,8 @@ def mermaid(
270270
:param direction: ``"TB"``, ``"BT"``, ``"LR"`` or ``"RL"``
271271
:param colorcomponents: fill vertices by connected component
272272
:param costs: label edges with their cost
273-
:param fence: wrap in a Markdown ```` ```mermaid ```` code fence
273+
:param fence: wrap in a Markdown code fence, three backticks followed by
274+
``mermaid``
274275
275276
Mermaid flowcharts are laid out automatically and cannot pin node
276277
positions, so vertex coordinates are not represented. Vertices are given

0 commit comments

Comments
 (0)