Skip to content

Commit 1a424e6

Browse files
authored
Merge pull request #47 from petercorke/refactor/unified-graph-vertex
feat: one Vertex class; Graph(directed=...) chooses the kind of graph
2 parents c57db9a + 0182c19 commit 1a424e6

22 files changed

Lines changed: 745 additions & 458 deletions

‎README.md‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -96,7 +96,7 @@ Graphs belong to the class `UGraph` or `DGraph` for undirected or directed graph
9696
- `g.incidence()` incidence matrix
9797

9898
### Properties and methods of a vertex
99-
Vertices belong to the class `UVertex` (for undirected graphs) or `DVertex` (for directed graphs), which are each subclasses of `Vertex`.
99+
Vertices are instances of the class `Vertex`, for both undirected and directed graphs.
100100

101101
- `v.coord` the coordinate vector for embedded graph (optional)
102102
- `v.name` the name of the vertex (optional)
@@ -123,11 +123,11 @@ Each edge references a pair of vertices, the graph lists all of its edges in `g.
123123
Consider a user class `Foo` that we would like to connect using a graph _overlay_, ie.
124124
instances of `Foo` becomes vertices in a graph.
125125

126-
- Have it subclass either `DVertex` or `UVertex` depending on graph type
126+
- Have it subclass `Vertex`
127127
- Then place instances of `Foo` into the graph using `add_vertex` and create edges as required
128128

129129
```
130-
class Foo(UVertex):
130+
class Foo(Vertex):
131131
# foo stuff goes here
132132
133133
f1 = Foo(...)

‎docs/source/common.rst‎

Lines changed: 8 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -11,18 +11,14 @@ The graph classes represent a single graph, either directed or undirected, and t
1111
:private-bases:
1212
:top-classes: pgraph.PGraph.Graph
1313

14-
The vertices in a directed graph (``DGraph``) inherit from :class:`DVertex` and the
15-
vertices in an undirected graph (``UGraph``) inherit from :class:`UVertex`.
16-
17-
.. inheritance-diagram:: pgraph.PGraph.UVertex pgraph.PGraph.DVertex
18-
:parts: 1
19-
20-
The vertex classes share
21-
almost their entire interface, defined once on their common base classes
22-
(:class:`Graph`, :class:`Vertex`). This section documents that
23-
shared interface by task rather than by class; see :doc:`construction` for
24-
the :class:`DGraph` and :class:`UGraph` classes and :doc:`edges_vertices` for
25-
what's specific to directed vs. undirected vertices.
14+
The vertices of both kinds of graph are :class:`Vertex` objects: a vertex has
15+
no direction of its own, the graph it belongs to decides how an edge is
16+
recorded at its ends.
17+
18+
The graph classes share almost their entire interface, defined once on their
19+
common base class :class:`Graph`. This section documents that shared interface
20+
by task rather than by class; see :doc:`construction` for the :class:`DGraph`
21+
and :class:`UGraph` classes and :doc:`edges_vertices` for vertices and edges.
2622

2723
Edges are represented by the :class:`Edge` class, which is used by both directed and undirected graphs.
2824

‎docs/source/dvertex.rst‎

Lines changed: 0 additions & 9 deletions
This file was deleted.

‎docs/source/edges_vertices.rst‎

Lines changed: 5 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -22,7 +22,7 @@ and to add them to the graph.
2222
.. runblock:: pycon
2323
:session:
2424

25-
>>> from pgraph import UGraph, UVertex, Edge
25+
>>> from pgraph import UGraph, Vertex, Edge
2626
>>> import numpy as np
2727
>>> g = UGraph()
2828

@@ -31,8 +31,8 @@ Next, we will explicitly create two vertices
3131
.. runblock:: pycon
3232
:session:
3333

34-
>>> v1 = UVertex(np.random.rand(2))
35-
>>> v2 = UVertex(np.random.rand(2))
34+
>>> v1 = Vertex(np.random.rand(2))
35+
>>> v2 = Vertex(np.random.rand(2))
3636

3737

3838
and then add them to the graph
@@ -77,7 +77,7 @@ Alternatively, we can create a vertex and *connect* it to an existing vertex, wh
7777
.. runblock:: pycon
7878
:session:
7979

80-
>>> v3 = UVertex(np.random.rand(2))
80+
>>> v3 = Vertex(np.random.rand(2))
8181
>>> g.add_vertex(v3)
8282
>>> v2.connect(v3)
8383
>>> print(g)
@@ -88,11 +88,9 @@ The ``connect`` method is available on both the
8888
directed and undirected vertex classes.
8989

9090

91-
.. note:: Where ever a vertex or edge is required, a subclass of the appropriate base class can be used. For example, we can create a subclass of ``UVertex`` called ``MyVertex`` and a subclass of ``Edge`` called ``MyEdge`` and then create a new graph using these classes.
91+
.. note:: Where ever a vertex or edge is required, a subclass of the appropriate base class can be used. For example, we can create a subclass of ``Vertex`` called ``MyVertex`` and a subclass of ``Edge`` called ``MyEdge`` and then create a new graph using these classes.
9292

9393
.. toctree::
9494
:maxdepth: 2
9595

96-
dvertex
97-
uvertex
9896
edge

‎docs/source/intro.rst‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -60,7 +60,7 @@ we can obtain the reference by indexing the graph object. For example vertex 1 i
6060

6161
>>> g[1]
6262

63-
and is an instance of ``UVertex``, a vertex in an undirected graph; it has the coordinate
63+
and is an instance of ``Vertex``; it has the coordinate
6464
:math:`(0.6028, 0.5449)` and has been assigned a default name ``"#1"`` but we could specify
6565
an explicit name to ``add_vertex``.
6666
We can also reference a vertex by its name
@@ -201,15 +201,15 @@ Arbitrary data can be attached to any vertex or edge by assigning values to attr
201201

202202
This exploits the flexible nature of Python, but care must be taken to avoid name clashes with existing attributes.
203203

204-
A more robust and Pythonic approach is to create a subclass of the ``UVertex`` or ``DVertex`` classes class and
205-
declare them at graph creation time. For example, we can create a subclass of ``UVertex`` called ``MyVertex`` and a subclass of ``Edge`` called ``MyEdge`` and then create a new graph using these classes.
204+
A more robust and Pythonic approach is to create a subclass of the ``Vertex`` class and
205+
declare them at graph creation time. For example, we can create a subclass of ``Vertex`` called ``MyVertex`` and a subclass of ``Edge`` called ``MyEdge`` and then create a new graph using these classes.
206206

207207
.. runblock:: pycon
208208
:session:
209209

210210
>>> import pgraph
211211
>>> import numpy as np
212-
>>> class MyVertex(pgraph.UVertex):
212+
>>> class MyVertex(pgraph.Vertex):
213213
... pass
214214
>>> class MyEdge(pgraph.Edge):
215215
... pass

‎docs/source/modification.rst‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,10 @@
11
Adding and removing vertices and edges
22
========================================
33

4-
Building up and tearing down a graph's structure. ``connect()`` is shown
5-
here in its base-class form; :doc:`DVertex <dvertex>` and
6-
:doc:`UVertex <uvertex>` override it with different edge-list bookkeeping
7-
-- see those pages for the concrete behaviour. See :class:`Edge` for
4+
Building up and tearing down a graph's structure. ``connect()`` is the same
5+
for both kinds of graph: the graph decides how the edge is recorded at its
6+
vertices, so an undirected edge is found from either end and a directed one
7+
leaves its start vertex and enters its end vertex. See :class:`Edge` for
88
constructing/removing an edge directly rather than via a vertex or graph.
99

1010
Graph

‎docs/source/policy.rst‎

Lines changed: 19 additions & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
Object lifecycle and graph-membership policy
22
=============================================
33

4-
``Vertex``, ``UVertex``, ``DVertex`` and ``Edge`` can all be constructed
4+
``Vertex`` and ``Edge`` can both be constructed
55
directly, independent of any graph. This is deliberate -- it is not an
66
oversight and not a "factory-only" design -- but it means the rules for what
77
those objects can and can't do *before* they belong to a graph need to be
@@ -10,7 +10,7 @@ stated explicitly rather than left implicit.
1010
Standalone construction
1111
------------------------
1212

13-
A vertex or edge built directly, e.g. ``UVertex(coord=[1, 2], name="A")`` or
13+
A vertex or edge built directly, e.g. ``Vertex(coord=[1, 2], name="A")`` or
1414
``Edge(v1, v2, cost=5.0)``, is a fully valid object in its own right. The
1515
main supported use of this is lightweight, graph-independent work: building a
1616
couple of vertices purely to demonstrate or test :class:`Edge` cost
@@ -23,17 +23,17 @@ anything (see below) until it is added to a graph via
2323
Adding a vertex to a graph
2424
---------------------------
2525

26-
:meth:`UGraph.add_vertex` and :meth:`DGraph.add_vertex` each only accept
27-
their own matching vertex subclass -- a ``UVertex`` (or coordinate data, from
28-
which one is built) for :class:`UGraph`, a ``DVertex`` for :class:`DGraph`.
29-
Passing the wrong kind of vertex -- a plain ``Vertex``, or the other
30-
graph's subclass -- raises ``TypeError`` rather than being silently accepted
31-
or converted.
26+
A vertex is the same for undirected and directed graphs: it has no
27+
direction of its own, and the graph it belongs to decides how an edge is
28+
recorded at its ends. :meth:`Graph.add_vertex` accepts coordinate data, from
29+
which a vertex is built, or an existing ``Vertex`` that does not belong to a
30+
graph. A graph given a ``vertex_class`` only accepts instances of that class;
31+
passing any other vertex raises ``TypeError`` rather than being silently
32+
accepted or converted. A vertex that already belongs to a graph raises
33+
``ValueError``; remove it from that graph first.
3234

3335
This is the mechanism that makes graph membership meaningful: once added, a
34-
vertex's ``._graph`` is fixed to that specific graph instance, and its
35-
concrete type (``UVertex`` or ``DVertex``) is guaranteed correct for that
36-
graph's edge semantics (undirected vs. directed edge-list bookkeeping).
36+
vertex's ``._graph`` is fixed to that specific graph instance.
3737

3838
Connecting two vertices
3939
-------------------------
@@ -46,12 +46,9 @@ Connecting two vertices
4646
- If the two vertices belong to different graph instances, ``connect()``
4747
raises ``ValueError``.
4848

49-
There is deliberately no separate check for "same vertex subclass" (e.g.
50-
rejecting a ``UVertex``-to-``DVertex`` connection directly). It doesn't need
51-
one: since a ``UVertex`` can only ever belong to a ``UGraph`` and a
52-
``DVertex`` only to a ``DGraph`` (enforced by ``add_vertex()`` above), the
53-
same-graph check above already makes a ``UVertex``-to-``DVertex`` connection
54-
impossible as a structural consequence, not as a separately-maintained rule.
49+
There is no such thing as connecting an "undirected" vertex to a "directed"
50+
one, since a vertex is neither: the kind of edge is the graph's, so the
51+
same-graph check above is the only one needed.
5552

5653
Constructing an ``Edge`` directly
5754
-----------------------------------
@@ -79,15 +76,17 @@ Summary
7976
* - Operation
8077
- Requires graph membership?
8178
- Failure mode
82-
* - ``UVertex()`` / ``DVertex()`` / ``Vertex()``
79+
* - ``Vertex()``
8380
- No
8481
- --
8582
* - ``Edge(v1, v2)``
8683
- No (cost falls back to ``None`` if ungraphed/cross-graph)
8784
- --
8885
* - ``graph.add_vertex(v)``
89-
- ``v`` must be the graph's own vertex subclass, or coordinate data
90-
- ``TypeError`` on wrong vertex subclass
86+
- ``v`` must be of the graph's ``vertex_class`` and not already in a
87+
graph, or coordinate data
88+
- ``TypeError`` on a vertex of another class, ``ValueError`` if it is
89+
already in a graph
9190
* - ``v1.connect(v2)`` / ``graph.add_edge(v1, v2)``
9291
- Both vertices must already belong to the same graph
9392
- ``ValueError`` if either is ungraphed or they belong to different

‎docs/source/uvertex.rst‎

Lines changed: 0 additions & 9 deletions
This file was deleted.

0 commit comments

Comments
 (0)