From c29e3f377d626527f77cab4a072affa88dcb8b91 Mon Sep 17 00:00:00 2001
From: Peter Corke <peter.i.corke@gmail.com>
Date: Sun, 16 Aug 2026 11:14:02 +1000
Subject: [PATCH] fix: deprecate adjacent()/vertices() properly instead of
 hard-breaking

UVertex.adjacent() had been removed outright with no migration path --
renamed to neighbours()/neighbors() with zero deprecation phase, so any
caller still using the old name got a bare AttributeError. Restored it
as a thin wrapper: still calls neighbours() and returns its result, but
now emits a DeprecationWarning first, giving callers a working upgrade
path instead of an immediate break.

Also fixed the same underlying anti-pattern already present nearby in
Edge.vertices(): it did `raise DeprecationWarning(...)`, which aborts
the call exactly like a missing method would (DeprecationWarning is
just an Exception subclass when raised directly) -- no backward
compatibility at all, and it never goes through the actual warnings
machinery (no -W flag control, no filterwarnings support). Now uses
warnings.warn(..., DeprecationWarning, stacklevel=2) and still returns
self.endpoints, matching the same real deprecation pattern as
adjacent() above.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
---
 src/pgraph/PGraph.py | 32 +++++++++++++++++++++++++++++++-
 tests/test_graph.py  | 26 ++++++++++++++++++++++++++
 2 files changed, 57 insertions(+), 1 deletion(-)

diff --git a/src/pgraph/PGraph.py b/src/pgraph/PGraph.py
index 9f1c50da..a89dab33 100644
--- a/src/pgraph/PGraph.py
+++ b/src/pgraph/PGraph.py
@@ -1,5 +1,6 @@
 from abc import ABC
 import sys
+import warnings
 import numpy as np
 import matplotlib.pyplot as plt
 import copy
@@ -1582,7 +1583,20 @@ def next(self, vertex):
             raise ValueError("shouldnt happen")
 
     def vertices(self):
-        raise DeprecationWarning("use endpoints instead")
+        """
+        Vertices of an edge (deprecated)
+
+        :return: the two vertices of this edge
+        :rtype: list of Vertex subclass
+
+        .. deprecated:: use :attr:`endpoints` instead
+        """
+        warnings.warn(
+            "vertices() is deprecated, use endpoints instead",
+            DeprecationWarning,
+            stacklevel=2,
+        )
+        return self.endpoints
 
     @property
     def endpoints(self):
@@ -1673,6 +1687,22 @@ def neighbors(self):
         """
         return [e.next(self) for e in self._edgelist]
 
+    def adjacent(self):
+        """
+        Neighbours of a vertex (deprecated)
+
+        :return: a list of neighbours of this vertex
+        :rtype: list of Vertex subclass
+
+        .. deprecated:: use :meth:`neighbours` instead
+        """
+        warnings.warn(
+            "adjacent() is deprecated, use neighbours() instead",
+            DeprecationWarning,
+            stacklevel=2,
+        )
+        return self.neighbours()
+
     def isneighbour(self, vertex):
         """
         Test if vertex is a neigbour
diff --git a/tests/test_graph.py b/tests/test_graph.py
index f0541b24..812ef9d0 100644
--- a/tests/test_graph.py
+++ b/tests/test_graph.py
@@ -151,6 +151,18 @@ def test_neighbours(self):
         self.assertFalse(v1.isneighbour(v3))
         self.assertFalse(v3.isneighbour(v1))
 
+    def test_adjacent_deprecated(self):
+        # adjacent() must still work (same result as neighbours()) but
+        # emit a DeprecationWarning, not a hard failure
+        g = UGraph()
+        v1 = g.add_vertex(name='v1')
+        v2 = g.add_vertex(name='v2')
+        v1.connect(v2)
+
+        with self.assertWarns(DeprecationWarning):
+            n = v1.adjacent()
+        self.assertEqual(n, v1.neighbours())
+
     def test_getitem(self):
         g = UGraph()
         v1 = g.add_vertex(name='v1')
@@ -282,6 +294,20 @@ def test_edge2(self):
         self.assertTrue(v3 in v1.neighbours())
         self.assertFalse(v4 in v1.neighbours())
 
+    def test_edge_vertices_deprecated(self):
+        # vertices() must still work (same result as endpoints) but emit
+        # a DeprecationWarning, not raise DeprecationWarning as a hard
+        # failure (raising it aborts the call exactly like a missing
+        # method would -- no backward compatibility at all)
+        g = UGraph()
+        v1 = g.add_vertex(name='v1')
+        v2 = g.add_vertex(name='v2')
+        e = v1.connect(v2)
+
+        with self.assertWarns(DeprecationWarning):
+            verts = e.vertices()
+        self.assertEqual(verts, e.endpoints)
+
     def test_edge3(self):
 
         g = UGraph()