Skip to content

Commit 238b616

Browse files
petercorkeclaude
andcommitted
feat: Vertex.edges_to() lists every edge from a vertex to another
edgeto() returns the one edge a path would use, the cheapest of any parallel edges. There was no way to see the parallel edges themselves other than filtering incidences() by hand. edges_to() returns all of them, in connection order, as a new list: empty rather than an error when there are none, only the edges from self to dest for a directed graph, and an undirected self-loop once, not once per end. edgeto() is now built on it with the same result, and says adjacent rather than neighbour. The seealso links join the two and the edge-list family. Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
1 parent 1a424e6 commit 238b616

2 files changed

Lines changed: 161 additions & 6 deletions

File tree

‎src/pgraph/PGraph.py‎

Lines changed: 58 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -3902,6 +3902,7 @@ def incidences(self) -> list[tuple[Vertex, Edge]]:
39023902
39033903
:seealso: :meth:`adjacent` :meth:`isadjacent` :meth:`successors`
39043904
:meth:`out_edges` :meth:`in_edges` :meth:`predecessors`
3905+
:meth:`edgeto` :meth:`edges_to`
39053906
:meth:`edges` :meth:`edgeto` :attr:`degree`
39063907
:meth:`Graph.adjacency`
39073908
"""
@@ -4016,11 +4017,11 @@ def _bind_edge(self, edge: Edge, dest: Vertex) -> None:
40164017

40174018
def edgeto(self, dest: Vertex) -> Edge:
40184019
"""
4019-
Get edge connecting vertex to specific neighbour
4020+
The edge from this vertex to an adjacent vertex
40204021
4021-
:param dest: a neigbouring vertex
4022+
:param dest: an adjacent vertex
40224023
:type dest: ``Vertex`` subclass
4023-
:raises ValueError: ``dest`` is not a neighbour
4024+
:raises ValueError: ``dest`` is not adjacent to this vertex
40244025
:return: the edge from this vertex to ``dest``
40254026
:rtype: Edge
40264027
@@ -4038,15 +4039,65 @@ def edgeto(self, dest: Vertex) -> Edge:
40384039
>>> v2 = g.add_vertex(coord=[1,1], name='v2')
40394040
>>> g.add_edge(v1, v2, cost=1.414)
40404041
>>> print(v1.edgeto(v2))
4042+
4043+
:seealso: :meth:`edges_to` :meth:`incidences` :meth:`adjacent`
40414044
"""
4042-
edges = [e for n, e in self.incidences() if n is dest]
4045+
edges = self.edges_to(dest)
40434046
if not edges:
40444047
raise ValueError("dest is not a neighbour")
40454048
costed = [e for e in edges if e.cost is not None]
40464049
if costed:
40474050
return min(costed, key=lambda e: e.cost) # type: ignore[arg-type,return-value]
40484051
return edges[0]
40494052

4053+
def edges_to(self, dest: Vertex) -> list[Edge]:
4054+
"""
4055+
All the edges from this vertex to another vertex
4056+
4057+
:param dest: the vertex at the far end
4058+
:type dest: ``Vertex`` subclass
4059+
:return: every edge from this vertex to ``dest``, in the order they
4060+
were connected, which is empty if there are none
4061+
:rtype: list of Edge
4062+
4063+
This is how to see parallel edges. :meth:`edgeto` returns the one
4064+
edge that a path would use, the cheapest, whereas this returns them
4065+
all.
4066+
4067+
.. note::
4068+
4069+
- For a directed graph only the edges leaving this vertex for
4070+
``dest`` are included, so ``a.edges_to(b)`` and
4071+
``b.edges_to(a)`` are different lists
4072+
- For an undirected graph the edges are found from either end,
4073+
whichever vertex they were connected from
4074+
- A self-loop is listed once, although its vertex holds it twice
4075+
(see :meth:`edges`)
4076+
- Unlike :meth:`edgeto`, there being no edge is not an error, the
4077+
list is empty
4078+
- The list is a new one, so changing it does not change the graph
4079+
4080+
.. runblock:: pycon
4081+
4082+
>>> from pgraph import UGraph
4083+
>>> g = UGraph()
4084+
>>> v1 = g.add_vertex(coord=[0,0], name='v1')
4085+
>>> v2 = g.add_vertex(coord=[1,1], name='v2')
4086+
>>> g.add_edge(v1, v2, cost=3)
4087+
>>> g.add_edge(v1, v2, cost=1)
4088+
>>> print(v1.edges_to(v2))
4089+
>>> print(v1.edgeto(v2))
4090+
4091+
:seealso: :meth:`edgeto` :meth:`edges` :meth:`out_edges`
4092+
:meth:`incidences` :meth:`adjacent`
4093+
"""
4094+
found: list[Edge] = []
4095+
for vertex, edge in self.incidences():
4096+
# a self-loop is held twice by its vertex, so is met twice
4097+
if vertex is dest and not any(edge is e for e in found):
4098+
found.append(edge)
4099+
return found
4100+
40504101
def edges(self) -> list[Edge]:
40514102
"""
40524103
Return a list of the edges for vertex
@@ -4074,7 +4125,8 @@ def edges(self) -> list[Edge]:
40744125
>>> print(v1.edges())
40754126
40764127
:seealso: :meth:`out_edges` :meth:`in_edges` :meth:`adjacent`
4077-
:meth:`incidences` :attr:`degree` :meth:`Graph.edges`
4128+
:meth:`incidences` :meth:`edges_to` :attr:`degree`
4129+
:meth:`Graph.edges`
40784130
"""
40794131
return list(self._edgelist)
40804132

@@ -4226,7 +4278,7 @@ def out_edges(self) -> list[Edge]:
42264278
graph every incident edge is outgoing.
42274279
42284280
:seealso: :meth:`in_edges` :meth:`edges` :meth:`adjacent` :meth:`successors`
4229-
:meth:`incidences` :attr:`out_degree`
4281+
:meth:`incidences` :meth:`edges_to` :attr:`out_degree`
42304282
"""
42314283
return list(self._edgelist)
42324284

‎tests/test_edges_to.py‎

Lines changed: 103 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,103 @@
1+
"""``edges_to(dest)`` lists every edge from a vertex to ``dest``.
2+
3+
``edgeto(dest)`` returns the one edge a path would use, the cheapest of any
4+
parallel edges. ``edges_to`` is the whole set, so that parallel edges can be
5+
inspected: in connection order, empty rather than an error when there are none,
6+
and with an undirected self-loop listed once, not once per end.
7+
"""
8+
9+
import unittest
10+
11+
from pgraph import DGraph, UGraph
12+
13+
14+
class _EdgesTo:
15+
Graph: type
16+
17+
def setUp(self):
18+
self.g = self.Graph()
19+
self.a, self.b, self.c = (self.g.add_vertex(name=n) for n in "abc")
20+
21+
def test_single_edge(self):
22+
e = self.a.connect(self.b, cost=3)
23+
self.assertEqual(self.a.edges_to(self.b), [e])
24+
25+
def test_parallel_edges_in_connection_order(self):
26+
e1 = self.a.connect(self.b, cost=5)
27+
e2 = self.a.connect(self.b, cost=2)
28+
e3 = self.a.connect(self.b, cost=9)
29+
self.assertEqual(self.a.edges_to(self.b), [e1, e2, e3])
30+
31+
def test_edgeto_is_the_cheapest_of_edges_to(self):
32+
edges = [self.a.connect(self.b, cost=c) for c in (5, 2, 9)]
33+
self.assertIs(self.a.edgeto(self.b), edges[1])
34+
self.assertIn(self.a.edgeto(self.b), self.a.edges_to(self.b))
35+
36+
def test_none_is_an_empty_list_not_an_error(self):
37+
self.a.connect(self.b)
38+
self.assertEqual(self.a.edges_to(self.c), [])
39+
with self.assertRaises(ValueError):
40+
self.a.edgeto(self.c) # edgeto has no edge to return
41+
42+
def test_other_destinations_are_not_included(self):
43+
e = self.a.connect(self.b)
44+
self.a.connect(self.c)
45+
self.assertEqual(self.a.edges_to(self.b), [e])
46+
47+
def test_self_loop_is_listed_once(self):
48+
loop = self.a.connect(self.a, cost=1)
49+
self.assertEqual(self.a.edges_to(self.a), [loop])
50+
51+
def test_loop_and_parallel_loops(self):
52+
l1 = self.a.connect(self.a)
53+
l2 = self.a.connect(self.a)
54+
self.assertEqual(self.a.edges_to(self.a), [l1, l2])
55+
56+
def test_is_a_new_list(self):
57+
self.a.connect(self.b)
58+
self.a.edges_to(self.b).clear()
59+
self.assertEqual(len(self.a.edges_to(self.b)), 1)
60+
self.assertEqual(self.g.validate(), [])
61+
62+
def test_removed_edge_is_gone(self):
63+
e1 = self.a.connect(self.b)
64+
e2 = self.a.connect(self.b)
65+
self.g.remove_edge(e1)
66+
self.assertEqual(self.a.edges_to(self.b), [e2])
67+
68+
def test_unconnected_vertex(self):
69+
self.assertEqual(self.a.edges_to(self.b), [])
70+
71+
72+
class TestUndirectedEdgesTo(_EdgesTo, unittest.TestCase):
73+
Graph = UGraph
74+
75+
def test_found_from_either_end(self):
76+
e = self.a.connect(self.b)
77+
self.assertEqual(self.a.edges_to(self.b), [e])
78+
self.assertEqual(self.b.edges_to(self.a), [e])
79+
80+
def test_edges_connected_from_the_other_end_are_included(self):
81+
e1 = self.a.connect(self.b)
82+
e2 = self.b.connect(self.a)
83+
self.assertEqual(self.a.edges_to(self.b), [e1, e2])
84+
self.assertEqual(self.b.edges_to(self.a), [e1, e2])
85+
86+
87+
class TestDirectedEdgesTo(_EdgesTo, unittest.TestCase):
88+
Graph = DGraph
89+
90+
def test_only_the_direction_given(self):
91+
e = self.a.connect(self.b)
92+
self.assertEqual(self.a.edges_to(self.b), [e])
93+
self.assertEqual(self.b.edges_to(self.a), [])
94+
95+
def test_opposite_edges_are_separate(self):
96+
ab = self.a.connect(self.b)
97+
ba = self.b.connect(self.a)
98+
self.assertEqual(self.a.edges_to(self.b), [ab])
99+
self.assertEqual(self.b.edges_to(self.a), [ba])
100+
101+
102+
if __name__ == "__main__":
103+
unittest.main()

0 commit comments

Comments
 (0)