@@ -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
0 commit comments