Document the fact OrderedSet.remove is linear

This has potential to cause quadratic blowup.

Add a test to check this (in case we ever fix it).

Author: Techcable

src/techcable/orderedset/_orderedset.py

@@ -70,6 +70,11 @@ class OrderedSet(MutableSet[T], Sequence[T]):
     because [`OrderedSet.append`] ignores duplicate elements
     and returns `bool` instead of `None`.
 
+    The [`OrderedSet.remove`] method takes linear time to remove an element,
+    not constant time like `set.remove` does.
+    Calling it in a loop will trigger quadratic blow up just like use of [`list.remove`] would.
+    To avoid this, bulk-remove elements using the set subtraction operator (`-=`).
+
     ### Thread Safety
     This type is *NOT* safe to mutate from multiple threads.
 
@@ -167,6 +172,11 @@ def remove(self, value: T, /) -> None:
         """
         Remove an element from the set, throwing a KeyError if not present.
 
+        This method preserves the original order of the set.
+        However, it takes linear time like [`list.remove`],
+        instead of the constant time that [`set.remove`] takes.
+        Invoking it repeatedly may cause quadratic blowup, just like `list.remove` would.
+
         See [`OrderedSet.discard`] for a variant that does nothing if the item is not present.
         """
         # set.remove will raise a KeyError for us
@@ -178,6 +188,11 @@ def discard(self, value: T, /) -> None:
         """
         Remove an element from the set if it exists.
 
+        This method preserves the original order of the set.
+        However, it takes linear time (`O(n)`) instead of the constant time.
+        Invoking it repeatedly may cause quadratic blowup.
+        See [`OrderedSet.remove`] for more details on this.
+
         Unlike [`OrderedSet.remove`], this method does not raise
         an exception if this element is missing.
         """

tests/test_remove_complexity.py

@@ -0,0 +1,60 @@
+"""
+Ensures the [`OrderedSet.remove`] function runs in constant time instead of linear time.
+"""
+
+import threading
+from typing import ClassVar
+
+import pytest
+
+from techcable.orderedset import OrderedSet
+
+
+class UnexpectedComplexityError(AssertionError):
+    pass
+
+
+class EqualityCounter(threading.local):
+    comparisons: int
+    hashes: int = 0
+
+    def __init__(self) -> None:
+        super().__init__()
+        self.reset()
+
+    def reset(self) -> None:
+        self.comparisons = 0
+        self.hashes = 0
+
+
+class EqualityCounted:
+    """A type that counts the number of times it has been compared against."""
+
+    value: int
+    COUNTER: ClassVar = EqualityCounter()
+
+    def __init__(self, value: int, /):
+        self.value = value
+
+    def __eq__(self, other: object) -> bool:
+        if isinstance(other, EqualityCounted):
+            self.COUNTER.comparisons += 1
+            return self.value == other.value
+        else:
+            return NotImplemented
+
+    def __hash__(self) -> int:
+        self.COUNTER.hashes += 1
+        return hash(self.value)
+
+    def __repr__(self) -> str:
+        return f"EqualityCounter({self.value})"
+
+
+@pytest.mark.xfail(raises=UnexpectedComplexityError, reason="Remove is still linear")
+def test_const_remove():
+    oset = OrderedSet(EqualityCounted(i) for i in range(10_000))
+    EqualityCounted.COUNTER.reset()
+    oset.remove(EqualityCounted(5000))
+    if (comparison_count := EqualityCounted.COUNTER.comparisons) > 10:
+        raise UnexpectedComplexityError(f"oset.remove: {comparison_count}")