Skip to content

Commit c64ffe1

Browse files
authored
Merge pull request #48 from petercorke/feat/edges-to
feat: Vertex.edges_to() lists every edge from a vertex to another
2 parents 1a424e6 + 238b616 commit c64ffe1

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)