linkedset 0.1.0__py3-none-any.whl

linkedset/__init__.py

@@ -0,0 +1,606 @@
+# Copyright (c) ONNX Project Contributors
+# SPDX-License-Identifier: Apache-2.0
+# Modifications Copyright (c) Justin Chu
+# SPDX-License-Identifier: MIT
+"""Mutable, ordered set with safe mutation properties."""
+
+from __future__ import annotations
+
+from collections.abc import Iterable, Iterator, MutableSet, Sequence
+from typing import Generic, TypeVar, overload
+
+__all__ = ["DoublyLinkedSet"]
+
+_T = TypeVar("_T")
+
+
+class _LinkBox(Generic[_T]):
+    """A link in a doubly linked list that has a reference to the actual object in the link.
+
+    The :class:`_LinkBox` is a container for the actual object in the list. It is used to
+    maintain the links between the elements in the linked list. The actual object is stored in the
+    :attr:`value` attribute.
+
+    By using a separate container for the actual object, we can safely remove the object from the
+    list without losing the links. This allows us to remove the object from the list during
+    iteration and place the object into a different list without breaking any chains.
+
+    This is an internal class and should only be initialized by the :class:`DoublyLinkedSet`.
+
+    Attributes:
+        prev: The previous box in the list.
+        next: The next box in the list.
+        erased: A flag to indicate if the box has been removed from the list.
+        owning_list: The :class:`DoublyLinkedSet` to which the box belongs.
+        value: The actual object in the list.
+    """
+
+    __slots__ = ("next", "owning_list", "prev", "value")
+
+    def __init__(self, owner: DoublyLinkedSet[_T], value: _T | None) -> None:
+        """Create a new link box.
+
+        Args:
+            owner: The linked list to which this box belongs.
+            value: The value to be stored in the link box. When the value is None,
+                the link box is considered erased (default). The root box of the list
+                should be created with a None value.
+        """
+        self.prev: _LinkBox[_T] = self
+        self.next: _LinkBox[_T] = self
+        self.value: _T | None = value
+        self.owning_list: DoublyLinkedSet[_T] = owner
+
+    @property
+    def erased(self) -> bool:
+        return self.value is None
+
+    def erase(self) -> None:
+        """Remove the link from the list and detach the value from the box."""
+        if self.value is None:
+            raise ValueError("_LinkBox is already erased")
+        # Update the links
+        prev, next_ = self.prev, self.next
+        prev.next, next_.prev = next_, prev
+        # Detach the value
+        self.value = None
+
+    def __repr__(self) -> str:
+        return (
+            f"_LinkBox({self.value!r}, erased={self.erased}, "
+            f"prev={self.prev.value!r}, next={self.next.value!r})"
+        )
+
+
+class DoublyLinkedSet(Sequence[_T], MutableSet[_T], Generic[_T]):
+    """A doubly linked ordered set of nodes.
+
+    The container is both a :class:`collections.abc.Sequence` (ordered, indexable) and a
+    :class:`collections.abc.MutableSet`. It does not allow duplicate values and maintains
+    insertion order. One can treat it as a doubly linked list with list-like methods, or as
+    a mutable set supporting ``&``, ``|``, ``-``, ``^`` and their in-place variants.
+
+    Adding and removing elements from the set during iteration is safe. Moving elements
+    from one set to another is also safe.
+
+    During the iteration:
+
+    - If new elements are inserted after the current node, the iterator will
+      iterate over them as well.
+    - If new elements are inserted before the current node, they will
+      not be iterated over in this iteration.
+    - If the current node is lifted and inserted in a different location,
+      iteration will start from the "next" node at the _original_ location.
+
+    Time complexity:
+        Inserting and removing nodes from the set is O(1). Accessing nodes by index is O(n),
+        although accessing nodes at either end of the set is O(1). I.e.
+        ``linked_set[0]`` and ``linked_set[-1]`` are O(1).
+
+    Membership, uniqueness and set operations are based on object **identity** (``id(value)``),
+    not equality. Two distinct objects that compare equal are treated as different elements.
+    Because it is a mutable set, instances are not hashable. Since the set is *ordered*, ``==``
+    is order-sensitive: two sets are equal only when they hold the same elements (by identity)
+    in the same order. ``None`` is not a valid value in the set.
+    """
+
+    __slots__ = ("_length", "_root", "_value_ids_to_boxes")
+
+    def __init__(self, values: Iterable[_T] | None = None) -> None:
+        # Using the root node simplifies the mutation implementation a lot
+        # The list is circular. The root node is the only node that is not a part of the list values
+        root_ = _LinkBox(self, None)
+        self._root: _LinkBox = root_
+        self._length = 0
+        self._value_ids_to_boxes: dict[int, _LinkBox] = {}
+        if values is not None:
+            self.extend(values)
+
+    def __iter__(self) -> Iterator[_T]:
+        """Iterate over the elements in the list.
+
+        - If new elements are inserted after the current node, the iterator will
+          iterate over them as well.
+        - If new elements are inserted before the current node, they will
+          not be iterated over in this iteration.
+        - If the current node is lifted and inserted in a different location,
+          iteration will start from the "next" node at the _original_ location.
+        """
+        box = self._root.next
+        while box is not self._root:
+            if box.owning_list is not self:
+                raise RuntimeError(f"Element {box!r} is not in the list")
+            if not box.erased:
+                assert box.value is not None
+                yield box.value
+            box = box.next
+
+    def __reversed__(self) -> Iterator[_T]:
+        """Iterate over the elements in the list in reverse order."""
+        box = self._root.prev
+        while box is not self._root:
+            if not box.erased:
+                assert box.value is not None
+                yield box.value
+            box = box.prev
+
+    def __len__(self) -> int:
+        assert self._length == len(self._value_ids_to_boxes), (
+            "Bug in the implementation: length mismatch"
+        )
+        return self._length
+
+    def __contains__(self, value: object) -> bool:
+        """Return whether ``value`` is in the set, using object identity."""
+        return id(value) in self._value_ids_to_boxes
+
+    def __eq__(self, other: object) -> bool:
+        """Return whether ``other`` is an equal, equally-ordered set.
+
+        Because :class:`DoublyLinkedSet` is *ordered*, equality is order-sensitive
+        (unlike a plain :class:`set`). Two sets are equal only when they contain the same
+        elements, by object identity, in the same order. Only another
+        :class:`DoublyLinkedSet` can compare equal.
+        """
+        if self is other:
+            return True
+        if not isinstance(other, DoublyLinkedSet):
+            return NotImplemented
+        if self._length != other._length:
+            return False
+        return all(a is b for a, b in zip(self, other))
+
+    __hash__ = None  # type: ignore[assignment]  # ordered, mutable -> unhashable
+
+    def count(self, value: object) -> int:
+        """Return the number of occurrences of ``value`` (0 or 1), using object identity."""
+        return 1 if id(value) in self._value_ids_to_boxes else 0
+
+    def index(self, value: object, start: int = 0, stop: int | None = None) -> int:
+        """Return the index of ``value`` in the set, using object identity.
+
+        Raises:
+            ValueError: If ``value`` is not present in ``self[start:stop]``.
+        """
+        length = self._length
+        if start < 0:
+            start = max(length + start, 0)
+        if stop is None:
+            stop = length
+        elif stop < 0:
+            stop += length
+        for i, item in enumerate(self):
+            if i >= stop:
+                break
+            if i >= start and item is value:
+                return i
+        raise ValueError(f"{value!r} is not in the set")
+
+    @overload
+    def __getitem__(self, index: int) -> _T: ...
+    @overload
+    def __getitem__(self, index: slice) -> Sequence[_T]: ...
+
+    def __getitem__(self, index):
+        """Get the node at the given index.
+
+        Complexity is O(n).
+        """
+        if isinstance(index, slice):
+            return tuple(self)[index]
+        if index >= self._length or index < -self._length:
+            raise IndexError(
+                f"Index out of range: {index} not in range [-{self._length}, {self._length})"
+            )
+        if index < 0:
+            # Look up from the end of the list
+            iterator = reversed(self)
+            item = next(iterator)
+            for _ in range(-index - 1):
+                item = next(iterator)
+        else:
+            iterator = iter(self)  # type: ignore[assignment]
+            item = next(iterator)
+            for _ in range(index):
+                item = next(iterator)
+        return item
+
+    def _insert_one_after(
+        self,
+        box: _LinkBox[_T],
+        new_value: _T,
+    ) -> _LinkBox[_T]:
+        """Insert a new value after the given box.
+
+        All insertion methods should call this method to ensure that the list is updated correctly.
+
+        Example::
+            Before: A  <->  B  <->  C
+                    ^v0     ^v1     ^v2
+            Call: _insert_one_after(B, v3)
+            After:  A  <->  B  <->  new_box  <->  C
+                    ^v0     ^v1       ^v3         ^v2
+
+        Args:
+            box: The box which the new value is to be inserted.
+            new_value: The new value to be inserted.
+        """
+        if new_value is None:
+            raise TypeError(f"{self.__class__.__name__} does not support None values")
+        if box.value is new_value:
+            # Do nothing if the new value is the same as the old value
+            return box
+        if box.owning_list is not self:
+            raise ValueError(f"Value {box.value!r} is not in the list")
+
+        if (new_value_id := id(new_value)) in self._value_ids_to_boxes:
+            # If the value is already in the list, remove it first
+            self.remove(new_value)
+
+        # Create a new _LinkBox for the new value
+        new_box = _LinkBox(self, new_value)
+        # original_box <=> original_next
+        # becomes
+        # original_box <=> new_box <=> original_next
+        original_next = box.next
+        box.next = new_box
+        new_box.prev = box
+        new_box.next = original_next
+        original_next.prev = new_box
+
+        # Be sure to update the length and mapping
+        self._length += 1
+        self._value_ids_to_boxes[new_value_id] = new_box
+
+        return new_box
+
+    def _insert_many_after(
+        self,
+        box: _LinkBox[_T],
+        new_values: Iterable[_T],
+    ):
+        """Insert multiple new values after the given box."""
+        insertion_point = box
+        for new_value in new_values:
+            insertion_point = self._insert_one_after(insertion_point, new_value)
+
+    def remove(self, value: _T) -> None:
+        """Remove a node from the list."""
+        if (value_id := id(value)) not in self._value_ids_to_boxes:
+            raise ValueError(f"Value {value!r} is not in the list")
+        box = self._value_ids_to_boxes[value_id]
+        # Remove the link box and detach the value from the box
+        box.erase()
+
+        # Be sure to update the length and mapping
+        self._length -= 1
+        del self._value_ids_to_boxes[value_id]
+
+    def add(self, value: _T) -> None:
+        """Add ``value`` to the end of the set if it is not already present.
+
+        Unlike :meth:`append`, this is idempotent: if ``value`` (by identity) is already
+        in the set, its position is left unchanged. This implements
+        :meth:`collections.abc.MutableSet.add`.
+        """
+        if id(value) not in self._value_ids_to_boxes:
+            self.append(value)
+
+    def discard(self, value: _T) -> None:
+        """Remove ``value`` from the set if it is present, without raising otherwise.
+
+        This implements :meth:`collections.abc.MutableSet.discard`.
+        """
+        if id(value) in self._value_ids_to_boxes:
+            self.remove(value)
+
+    def append(self, value: _T) -> None:
+        """Append a node to the list."""
+        _ = self._insert_one_after(self._root.prev, value)
+
+    def extend(
+        self,
+        values: Iterable[_T],
+    ) -> None:
+        for value in values:
+            self.append(value)
+
+    def appendleft(self, value: _T) -> None:
+        """Add ``value`` to the front of the set (deque-style).
+
+        If ``value`` is already present (by identity), it is moved to the front.
+        """
+        _ = self._insert_one_after(self._root, value)
+
+    def extendleft(self, values: Iterable[_T]) -> None:
+        """Prepend each value in ``values`` to the front of the set (deque-style).
+
+        As with :meth:`collections.deque.extendleft`, the prepended items end up in reverse
+        order relative to ``values``.
+        """
+        for value in values:
+            self.appendleft(value)
+
+    def _box_at(self, index: int) -> _LinkBox[_T]:
+        """Return the live link box at ``index`` in ``[0, len)``, walking from the nearer end."""
+        if index <= self._length - 1 - index:
+            box = self._root.next
+            for _ in range(index):
+                box = box.next
+        else:
+            box = self._root.prev
+            for _ in range(self._length - 1 - index):
+                box = box.prev
+        return box
+
+    def insert(self, index: int, value: _T) -> None:
+        """Insert ``value`` before position ``index`` (list/deque-style).
+
+        ``index`` is clamped like :meth:`list.insert`. If ``value`` is already present it is
+        removed first, so ``index`` refers to a position in the resulting sequence.
+        """
+        if value is None:
+            raise TypeError(f"{self.__class__.__name__} does not support None values")
+        if id(value) in self._value_ids_to_boxes:
+            self.remove(value)
+        length = self._length
+        if index < 0:
+            index = max(length + index, 0)
+        if index >= length:
+            self.append(value)
+            return
+        target = self._box_at(index)
+        self._insert_one_after(target.prev, value)
+
+    def pop(self, index: int = -1) -> _T:
+        """Remove and return the value at ``index`` (default: the last one, list-style).
+
+        Raises:
+            IndexError: If the set is empty or ``index`` is out of range.
+        """
+        if self._length == 0:
+            raise IndexError("pop from empty DoublyLinkedSet")
+        value = self[index]
+        self.remove(value)
+        return value
+
+    def popleft(self) -> _T:
+        """Remove and return the first value (deque-style).
+
+        Raises:
+            IndexError: If the set is empty.
+        """
+        if self._length == 0:
+            raise IndexError("popleft from empty DoublyLinkedSet")
+        value = self[0]
+        self.remove(value)
+        return value
+
+    def clear(self) -> None:
+        """Remove all elements from the set.
+
+        Safe to call during iteration: existing nodes are marked erased (so a live iterator
+        stops yielding them) before the set is reset.
+        """
+        box = self._root.next
+        while box is not self._root:
+            # Detach the value but keep next/prev intact so a live iterator can still advance.
+            nxt = box.next
+            box.value = None
+            box = nxt
+        self._root.prev = self._root
+        self._root.next = self._root
+        self._length = 0
+        self._value_ids_to_boxes.clear()
+
+    def reverse(self) -> None:
+        """Reverse the elements of the set in place.
+
+        Note:
+            Unlike per-element mutation, this is a global reorder and is **not** safe to call
+            while iterating over the set: an in-progress iterator may then skip or repeat
+            elements.
+        """
+        node = self._root.next
+        while node is not self._root:
+            nxt = node.next
+            node.next, node.prev = node.prev, node.next
+            node = nxt
+        self._root.next, self._root.prev = self._root.prev, self._root.next
+
+    def rotate(self, n: int = 1) -> None:
+        """Rotate the set ``n`` steps to the right (deque-style).
+
+        Negative ``n`` rotates to the left. ``rotate(1)`` moves the last element to the front.
+
+        Note:
+            Like :meth:`reverse`, this is a global reorder and is **not** safe to call while
+            iterating over the set.
+        """
+        length = self._length
+        if length <= 1:
+            return
+        n %= length
+        if n == 0:
+            return
+        # The new first element is the n-th element counted from the end.
+        new_head = self._root.prev
+        for _ in range(n - 1):
+            new_head = new_head.prev
+        new_tail = new_head.prev
+        old_head = self._root.next
+        old_tail = self._root.prev
+        # Close the value ring, removing the root sentinel from between old_tail and old_head.
+        old_tail.next = old_head
+        old_head.prev = old_tail
+        # Splice the root sentinel back in between new_tail and new_head.
+        new_tail.next = self._root
+        self._root.prev = new_tail
+        self._root.next = new_head
+        new_head.prev = self._root
+
+    def copy(self) -> DoublyLinkedSet[_T]:
+        """Return a shallow copy of the set, preserving order."""
+        return DoublyLinkedSet(self)
+
+    # -- Set algebra -------------------------------------------------------------------------
+    # These override the collections.abc.Set mixins so that they use identity (``id``)
+    # semantics consistently and preserve this set's (left-operand) order, even when the other
+    # operand is an equality-based container such as a built-in ``set``.
+
+    @staticmethod
+    def _ids_of(iterable: Iterable[object]) -> set[int]:
+        return {id(value) for value in iterable}
+
+    def __and__(self, other: Iterable[_T]) -> DoublyLinkedSet[_T]:
+        if not isinstance(other, Iterable):
+            return NotImplemented
+        other_ids = self._ids_of(other)
+        result: DoublyLinkedSet[_T] = DoublyLinkedSet()
+        for value in self:
+            if id(value) in other_ids:
+                result.append(value)
+        return result
+
+    def __rand__(self, other: Iterable[_T]) -> DoublyLinkedSet[_T]:
+        # Reflected: ``other`` is the left operand, so honour its order.
+        if not isinstance(other, Iterable):
+            return NotImplemented
+        result: DoublyLinkedSet[_T] = DoublyLinkedSet()
+        for value in other:
+            if id(value) in self._value_ids_to_boxes:
+                result.append(value)
+        return result
+
+    def __or__(self, other: Iterable[_T]) -> DoublyLinkedSet[_T]:
+        if not isinstance(other, Iterable):
+            return NotImplemented
+        result = self.copy()
+        for value in other:
+            result.add(value)
+        return result
+
+    def __ror__(self, other: Iterable[_T]) -> DoublyLinkedSet[_T]:
+        if not isinstance(other, Iterable):
+            return NotImplemented
+        result: DoublyLinkedSet[_T] = DoublyLinkedSet(other)
+        for value in self:
+            result.add(value)
+        return result
+
+    def __sub__(self, other: Iterable[_T]) -> DoublyLinkedSet[_T]:
+        if not isinstance(other, Iterable):
+            return NotImplemented
+        other_ids = self._ids_of(other)
+        result: DoublyLinkedSet[_T] = DoublyLinkedSet()
+        for value in self:
+            if id(value) not in other_ids:
+                result.append(value)
+        return result
+
+    def __rsub__(self, other: Iterable[_T]) -> DoublyLinkedSet[_T]:
+        if not isinstance(other, Iterable):
+            return NotImplemented
+        result: DoublyLinkedSet[_T] = DoublyLinkedSet()
+        for value in other:
+            if id(value) not in self._value_ids_to_boxes:
+                result.append(value)
+        return result
+
+    def __xor__(self, other: Iterable[_T]) -> DoublyLinkedSet[_T]:
+        if not isinstance(other, Iterable):
+            return NotImplemented
+        other_values = list(other)
+        other_ids = self._ids_of(other_values)
+        result: DoublyLinkedSet[_T] = DoublyLinkedSet()
+        for value in self:
+            if id(value) not in other_ids:
+                result.append(value)
+        for value in other_values:
+            if id(value) not in self._value_ids_to_boxes:
+                result.add(value)
+        return result
+
+    def __rxor__(self, other: Iterable[_T]) -> DoublyLinkedSet[_T]:
+        # Reflected: ``other`` is the left operand, so emit its unique values first, in order.
+        if not isinstance(other, Iterable):
+            return NotImplemented
+        other_values = list(other)
+        other_ids = self._ids_of(other_values)
+        result: DoublyLinkedSet[_T] = DoublyLinkedSet()
+        for value in other_values:
+            if id(value) not in self._value_ids_to_boxes:
+                result.append(value)
+        for value in self:
+            if id(value) not in other_ids:
+                result.add(value)
+        return result
+
+    def isdisjoint(self, other: Iterable[_T]) -> bool:
+        """Return ``True`` if the set has no elements (by identity) in common with ``other``."""
+        return not any(id(value) in self._value_ids_to_boxes for value in other)
+
+    def _unsupported_ordering(self, _other: object) -> bool:
+        raise TypeError(
+            f"{type(self).__name__} does not support ordering/subset comparisons "
+            "(<, <=, >, >=) because '==' is order-sensitive; "
+            "use set algebra (&, |, -, ^) or isdisjoint() instead"
+        )
+
+    # Subset/superset ordering would clash with the order-sensitive ``==``, so it is disabled.
+    __lt__ = __le__ = __gt__ = __ge__ = _unsupported_ordering
+
+    def insert_after(
+        self,
+        value: _T,
+        new_values: Iterable[_T],
+    ) -> None:
+        """Insert new nodes after the given node.
+
+        Args:
+            value: The value after which the new values are to be inserted.
+            new_values: The new values to be inserted.
+        """
+        if (value_id := id(value)) not in self._value_ids_to_boxes:
+            raise ValueError(f"Value {value!r} is not in the list")
+        insertion_point = self._value_ids_to_boxes[value_id]
+        return self._insert_many_after(insertion_point, new_values)
+
+    def insert_before(
+        self,
+        value: _T,
+        new_values: Iterable[_T],
+    ) -> None:
+        """Insert new nodes before the given node.
+
+        Args:
+            value: The value before which the new values are to be inserted.
+            new_values: The new values to be inserted.
+        """
+        if (value_id := id(value)) not in self._value_ids_to_boxes:
+            raise ValueError(f"Value {value!r} is not in the list")
+        insertion_point = self._value_ids_to_boxes[value_id].prev
+        return self._insert_many_after(insertion_point, new_values)
+
+    def __repr__(self) -> str:
+        return f"DoublyLinkedSet({list(self)})"

linkedset-0.1.0.dist-info/METADATA

@@ -0,0 +1,199 @@
+Metadata-Version: 2.4
+Name: linkedset
+Version: 0.1.0
+Summary: Ordered set robust against mutation during iteration in Python
+Project-URL: Homepage, https://github.com/justinchuby/linkedset
+Project-URL: Documentation, https://justinchuby.github.io/linkedset/
+Project-URL: Repository, https://github.com/justinchuby/linkedset
+Project-URL: Issues, https://github.com/justinchuby/linkedset/issues
+Author: Justin Chu
+License-Expression: MIT
+License-File: LICENSE
+Keywords: data-structure,iteration,linked-list,ordered-set
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == 'dev'
+Requires-Dist: ruff; extra == 'dev'
+Provides-Extra: docs
+Requires-Dist: furo; extra == 'docs'
+Requires-Dist: myst-parser; extra == 'docs'
+Requires-Dist: sphinx>=7; extra == 'docs'
+Description-Content-Type: text/markdown
+
+# linkedset
+
+An ordered set that is robust against mutation during iteration, implemented in pure Python.
+
+`DoublyLinkedSet` behaves like an ordered set backed by a doubly linked list. Inserting
+and removing elements is `O(1)`, and — unlike Python's built-in `list` or `set` — you can
+safely add, remove, or move elements *while iterating over the container*.
+
+It implements both `collections.abc.Sequence` (ordered, indexable) and
+`collections.abc.MutableSet` (set algebra and in-place updates).
+
+📖 **Documentation**: <https://justinchuby.github.io/linkedset/>
+
+## Installation
+
+```bash
+pip install linkedset
+```
+
+Or install from source:
+
+```bash
+git clone https://github.com/justinchuby/linkedset
+cd linkedset
+pip install -e ".[dev]"
+```
+
+## Usage
+
+```python
+from linkedset import DoublyLinkedSet
+
+s = DoublyLinkedSet(["a", "b", "c"])
+
+s.append("d")                 # -> a, b, c, d
+s.insert_after("a", ["x"])    # -> a, x, b, c, d
+s.insert_before("b", ["y"])   # -> a, x, y, b, c, d
+s.remove("c")                 # -> a, x, y, b, d
+
+print(s[0])    # "a"  (O(1))
+print(s[-1])   # "d"  (O(1))
+print(list(s)) # ['a', 'x', 'y', 'b', 'd']
+```
+
+### Safe mutation during iteration
+
+```python
+s = DoublyLinkedSet(["a", "b", "c"])
+for x in s:
+    if x == "a":
+        s.insert_after("a", ["d"])  # inserted after current -> iterated
+        s.remove("b")               # removed before reached -> skipped
+# Iterated: a, d, c
+```
+
+Iteration rules:
+
+- Elements inserted **after** the current node **are** iterated over.
+- Elements inserted **before** the current node are **not** iterated over in the current pass.
+- If the current node is moved to a different location, iteration continues from the node
+  that followed it at its *original* location.
+
+Per-element mutation (`add`, `remove`, `discard`, `append`, `insert`, `clear`, …) is safe
+during iteration. The **global reorders** `reverse()` and `rotate()` are *not* — calling them
+mid-iteration may cause an in-progress iterator to skip or repeat elements.
+
+### Set operations
+
+Because it is a `MutableSet`, the usual set algebra works and returns a new
+`DoublyLinkedSet` (order preserved):
+
+```python
+a = DoublyLinkedSet(["a", "b", "c"])
+b = DoublyLinkedSet(["c", "d"])
+
+a | b   # union        -> a, b, c, d
+a & b   # intersection -> c
+a - b   # difference   -> a, b
+a ^ b   # symmetric    -> a, b, d
+
+a.add("x")        # idempotent add (no-op if already present)
+a.discard("z")    # remove if present, never raises
+a.pop()           # remove and return the last element (list-style; pass an index too)
+a |= b            # in-place update
+
+# `==` is order-sensitive, because the set is ordered:
+DoublyLinkedSet(["a", "b"]) == DoublyLinkedSet(["a", "b"])  # True
+DoublyLinkedSet(["a", "b"]) == DoublyLinkedSet(["b", "a"])  # False
+```
+
+### Deque- and list-style methods
+
+Because it is ordered, it also offers the familiar `deque`/`list` mutators (all keeping the
+set's uniqueness and identity semantics):
+
+```python
+s = DoublyLinkedSet(["a", "b", "c"])
+
+s.appendleft("z")       # -> z, a, b, c
+s.extendleft(["x", "y"])# -> y, x, z, a, b, c  (prepended, reversed like deque)
+s.popleft()             # removes and returns "y"
+s.pop()                 # removes and returns the last element ("c")
+s.pop(1)                # removes and returns the element at index 1
+s.insert(1, "q")        # insert before index 1 (index clamped like list.insert)
+s.rotate(1)             # rotate right; negative rotates left
+s.reverse()             # reverse in place
+s2 = s.copy()           # shallow copy, order preserved
+```
+
+## Semantics
+
+- Membership and set operations are based on object **identity** (`id(value)`), not equality.
+  Two distinct objects that compare equal are treated as different elements.
+- `==` is **order-sensitive** (it is an *ordered* set): equal only when the same elements, by
+  identity, appear in the same order. Instances are **not hashable** (mutable set).
+  Ordering/subset comparisons (`<`, `<=`, `>`, `>=`) are **not supported** (they raise
+  `TypeError`), since a subset relation would be ambiguous next to order-sensitive equality;
+  use the set algebra (`&`, `|`, `-`, `^`) or `isdisjoint()` instead.
+- `None` is not a valid value.
+- Accessing by index is `O(n)`, except the ends (`s[0]`, `s[-1]`) which are `O(1)`.
+
+## Complexity
+
+`DoublyLinkedSet` is a doubly linked list paired with a `dict` mapping each element's
+`id()` to its list node. That combination gives set-like `O(1)` membership and endpoint
+mutation, while preserving order and safe mutation during iteration.
+
+Let `n` be the size of the set (and `m` the size of the other operand for binary set
+operations).
+
+| Operation | Complexity | Notes |
+| --- | --- | --- |
+| `x in s`, `s.count(x)` | `O(1)` | `dict` lookup by `id(x)` |
+| `len(s)` | `O(1)` | length is tracked, not counted |
+| `s.append(x)`, `s.add(x)`, `s.appendleft(x)` | `O(1)` | insert at a known end |
+| `s.remove(x)`, `s.discard(x)` | `O(1)` | unlink the node, no shifting |
+| `s.extend(xs)`, `s.extendleft(xs)` | `O(k)` | `k = len(xs)`; `O(1)` per element |
+| `s.insert_after(v, xs)`, `s.insert_before(v, xs)` | `O(k)` | `k = len(xs)`; `O(1)` per element |
+| `s.pop()`, `s.popleft()` | `O(1)` | remove from an end |
+| `s.pop(i)`, `s.insert(i, x)` | `O(\|i\|)` | walks to the index from the nearer end |
+| `s[0]`, `s[-1]` | `O(1)` | endpoints are reachable directly |
+| `s[i]` | `O(\|i\|)` | walks from the nearer end |
+| `s.index(x)` | `O(n)` | linear scan for position |
+| `s.rotate(n)` | `O(n mod len(s))` | relink only, no node churn |
+| `s.reverse()`, `s.copy()`, `s.clear()` | `O(n)` | |
+| iteration, `reversed(s)`, `s == other` | `O(n)` | |
+| `s[a:b]` (slice) | `O(n)` | materialises a tuple |
+| `s \| t`, `s & t`, `s - t`, `s ^ t` | `O(n + m)` | each membership test is `O(1)` |
+| `s.isdisjoint(t)` | `O(n)` | one pass with `O(1)` lookups |
+
+Space is `O(n)`: every element is wrapped in a small link node and referenced once from the
+`id`-keyed index.
+
+Mutating during iteration stays `O(1)` per operation. Removed nodes are unlinked from their
+neighbours immediately, so a traversal never pays to skip over dead nodes — the only cost is
+following the `next` pointer you already hold.
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+python -m pytest      # run tests
+python -m ruff check  # lint
+```
+
+## License
+
+MIT. Portions derived from the ONNX Project Contributors (Apache-2.0); see `linkedset/__init__.py`.

linkedset-0.1.0.dist-info/RECORD

@@ -0,0 +1,6 @@
+linkedset/__init__.py,sha256=56ZBs9dwjCFopipD0KZyRGZ5Hx4qGn5J3FLUjOiF_5o,23253
+linkedset/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+linkedset-0.1.0.dist-info/METADATA,sha256=X8Wk5mps2SCCDzSF7OZTHJtSdukv_4hQH5Xa1XB5M9g,7672
+linkedset-0.1.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+linkedset-0.1.0.dist-info/licenses/LICENSE,sha256=SjqpNtkAu8i5L-1mHSpuWDPmthnFqwIMpsicZMARlhM,1067
+linkedset-0.1.0.dist-info/RECORD,,

linkedset-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py3-none-any

linkedset-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Justin Chu
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.