Deprecate pairwise() in favour of itertools.pairwise()

jsonpointer-stubs/__init__.pyi

@@ -2,7 +2,7 @@ from collections.abc import Iterable, Iterator
 from re import Pattern
 from typing import Any, Final, TypeVar
 
-from typing_extensions import Self
+from typing_extensions import Self, deprecated
 
 _T = TypeVar("_T")
 
@@ -21,6 +21,7 @@ def set_pointer(
     create: bool = False,
 ) -> Any: ...
 def resolve_pointer(doc: Any, pointer: str, default: Any = ...) -> Any: ...
+@deprecated("Use itertools.pairwise() instead")
 def pairwise(iterable: Iterable[_T]) -> Iterator[tuple[_T, _T]]: ...
 
 class JsonPointerException(Exception): ...

jsonpointer.py

@@ -37,9 +37,11 @@
 __license__ = 'Modified BSD License'
 
 import copy
+import itertools
 import re
+import warnings
 from collections.abc import Mapping, Sequence
-from itertools import tee, chain
+from itertools import chain
 
 _nothing = object()
 
@@ -128,19 +130,13 @@ def pairwise(iterable):
 
     s -> (s0,s1), (s1,s2), (s2, s3), ...
 
-    >>> list(pairwise([]))
-    []
-
-    >>> list(pairwise([1]))
-    []
-
-    >>> list(pairwise([1, 2, 3, 4]))
-    [(1, 2), (2, 3), (3, 4)]
+    .. deprecated:: 3.12
+       Use :func:`itertools.pairwise` instead.
     """
-    a, b = tee(iterable)
-    for _ in b:
-        break
-    return zip(a, b)
+    warnings.warn('jsonpointer.pairwise() is deprecated, '
+                  'use itertools.pairwise() instead',
+                  DeprecationWarning, stacklevel=2)
+    return itertools.pairwise(iterable)
 
 
 class JsonPointerException(Exception):

tests.py

@@ -307,6 +307,17 @@ def test_string_not_indexable(self):
 
 @unittest.skipUnless(hasattr(sys, 'get_int_max_str_digits'),
                      'Integer string conversion limits are not available')
+class PairwiseTests(unittest.TestCase):
+
+    def test_pairwise_is_deprecated(self):
+        for items, expected in (([], []), ([1], []),
+                                ([1, 2, 3, 4], [(1, 2), (2, 3), (3, 4)])):
+            with self.subTest(items=items):
+                with self.assertWarns(DeprecationWarning):
+                    result = jsonpointer.pairwise(items)
+                self.assertEqual(list(result), expected)
+
+
 class LargeIndexTests(unittest.TestCase):
 
     def setUp(self):