wip: Improve documentation

TODO: Issues with pdoc not understanding markdown reference links
TODO: Deploy to github-pages

Author: Techcable

README.md

@@ -5,14 +5,30 @@ techcable.orderedset
 [![pypi](https://img.shields.io/pypi/v/techcable.orderedset)](https://pypi.org/project/techcable.orderedset/)
 ![types](https://img.shields.io/pypi/types/techcable.orderedset)]
 
-A simple and efficient pure-python ordered set.
+A simple and efficient `OrderedSet` in pure python. Implements both [`MutableSet`] and [`Sequence`].
+
+[`MutableSet`]: https://docs.python.org/3/library/collections.abc.html#collections.abc.MutableSet 
+[`Sequence`]: https://docs.python.org/3/library/collections.abc.html#collections.abc.Sequence 
+
 
 ## Example Usage
 ```python
 from techcable.orderedset import OrderedSet
 
 # prints {1, 2, 7, 3}
 print(OrderedSet([1, 2, 7, 2, 3]))
+# Implements all standard set methods, still preserves order
+print(OrderedSet([1,2]) | OrderedSet([3,2,4]))  # {1,2,3,4}
+
+
+# Implements `append` method, returning True on success
+# and False if the item was a duplicate
+oset = OrderedSet()
+oset.append(1) # True
+oset.append(2) # True
+oset.append(1) # False - already in set, did nothing
+oset.extend([2,3]) # True - at least one success
+oset.append([2,3]) # False - all duplicates
 ```
 
 Supports [pydantic](pydantic.org) validation & serialization:
@@ -27,9 +43,9 @@ assert model.dump_python(OrderedSet([1,2,7,8])) == [1,2,7,8]
 ```
 
 ## Potential Future Features
-- Add [acceleration module] using C/Rust/Cython
-- Implemented `OrderedFrozenSet`
-- Publish HTML documentation using Sphinx or [pdoc](https://pdoc.dev/)
+- Implement `OrderedFrozenSet`
+- Consider [acceleration module] using C/Rust/Cython
+   - Probably unnecessary since this has library has very little overhead compared to the builtin `set`/`list`
 
 [acceleration module]: https://peps.python.org/pep-0399/
 

src/techcable/orderedset/__init__.py

@@ -1,3 +1,12 @@
+"""
+Implements `OrderedSet`, a [`MutableSet`] that preserves insertion order and is also a [`Sequence`].
+
+[`MutableSet`]: https://docs.python.org/3/library/collections.abc.html#collections.abc.MutableSet
+[`Sequence`]: https://docs.python.org/3/library/collections.abc.html#collections.abc.Sequence
+
+The implementation is pure-python and does not require any native code.
+"""
+
 from ._orderedset import OrderedSet
 from ._version import __version__
 

src/techcable/orderedset/_orderedset.py

@@ -54,10 +54,36 @@ def override(v):
 
 
 class OrderedSet(MutableSet[T], Sequence[T]):
-    """A Set of elements, which preserves insertion order.
+    """
+    A [`MutableSet`] that preserves insertion order and is also a [`Sequence`].
 
-    This type cannot implement `MutableSequence` because OrderedSet.append
-    ignores duplicate elements and returns a `bool` instead of `None`."""
+    [`MutableSet`]: https://docs.python.org/3/library/collections.abc.html#collections.abc.MutableSet
+    [`Sequence`]: https://docs.python.org/3/library/collections.abc.html#collections.abc.Sequence
+
+    ## Conveniences
+    Calling `OrderedSet.append` returns `True` if the element was successfully added,
+    and `False` if the element is a duplicate.
+
+    Calling `str(OrderedSet([x, y]))` is equivalent to `f"{x!r, y!r}"`.
+    This is much prettier than using `repr`,
+    which is expected to roundtrip through `eval`.
+
+    ## Gotchas
+    This type does not implement [`MutableSequence`]
+    because `OrderedSet.append` ignores duplicate elements
+    and returns `bool` instead of `None`.
+
+    [`MutableSequence`]: https://docs.python.org/3/library/collections.abc.html#collections.abc.MutableSequence
+
+    Pickling is currently not supported.
+
+    ### Thread Safety
+    This type is *NOT* thread safe.
+    Concurrent mutation will result in unexpected behavior unless you use a lock.
+
+    Concurrent reads are fully supported,
+    as long as no modifications are being made.
+    """
 
     __slots__ = ("_unique", "_elements")
 
@@ -66,7 +92,12 @@ class OrderedSet(MutableSet[T], Sequence[T]):
 
     @override
     def __init__(self, source: Iterable[T] | None = None, /) -> None:
-        """Create an ordered set containing the specified elements"""
+        """
+        Create an `OrderedSet` containing the specified elements.
+
+        This preserves the order of the original input
+        and implicitly ignores duplicates.
+        """
         self._unique = set()
         self._elements = []
         if source is None:
@@ -83,10 +114,15 @@ def __init__(self, source: Iterable[T] | None = None, /) -> None:
         assert len(self._unique) == len(self._elements)
 
     def append(self, value: T, /) -> bool:
-        """Append a value to the set if it doesn't already exist.
+        """
+        Append a value to the set if it doesn't already exist.
 
         Returns `True` if successfully added, or `False` if already exists.
-        Note that the return value doesn't match list.append, which always returns `None`"""
+
+        There are two important differences between this method and `list.append`:
+        1. This method does nothing if the value is a duplicate
+        2. This method returns a `bool` instead of `None`
+        """
         is_new = value not in self._unique
         if is_new:
             self._unique.add(value)
@@ -98,7 +134,7 @@ def extend(self, values: Iterable[T], /) -> bool:
         """
         Add all the specified values to the set.
 
-        Returns True if at least one element was added,
+        Returns `True` if at least one element was added,
         or `False` if every element is a duplicate.
 
         Roughly equivalent to `any(oset.append(v) for v in values)`.
@@ -110,26 +146,47 @@ def extend(self, values: Iterable[T], /) -> bool:
 
     @override
     def add(self, value: T, /) -> None:
-        """Add a value to the set if it doesn't already exist.
+        """
+        Add a value to the set if it doesn't already exist.
 
         Return value is `None` for consistency with `set.add`.
-        Use `OrderedSet.append` if you want to know if the element already existed."""
+        Use `OrderedSet.append` if you want to know if the element already existed.
+        """
         self.append(value)
 
     @override
     def discard(self, value: T, /) -> None:
-        """Remove the element from the set if it exists."""
+        """
+        Remove an element from the set if it exists.
+
+        Unlike `OrderedSet.remove`, this method does not raise
+        an exception if this element is missing.
+        """
         if value in self._unique:
             self._elements.remove(value)
             self._unique.remove(value)
 
     def update(self, values: Iterable[T], /) -> None:
-        """Add all the"""
+        """
+        Add all the specified values to this set.
+
+        Equivalent to running
+        ```
+        for val in values:
+            oset.append(val)
+        ```
+        """
         self.extend(values)
 
     @override
     def pop(self, index: int = -1) -> T:
-        """Pop an item from the end of the list (or at `index`)"""
+        """
+        Remove and return an item from the end of the list (or from `self[index]`).
+
+        Raises `IndexError` if the list is empty or `index` is out of bounds.
+
+        Equivalent to `list.pop`.
+        """
         item = self._elements.pop(index)
         self._unique.remove(item)
         return item
@@ -209,15 +266,19 @@ def __ge__(self, other: object) -> bool:
     def sort(
         self, key: Optional[Callable[[T], U]] = None, reverse: bool = False
     ) -> None:
-        """Sort the elements in the set, as if calling list.sort"""
+        """Sort the elements of the set in-place, as if calling `list.sort`."""
         self._elements.sort(key=key, reverse=reverse)
 
     def reverse(self) -> None:
-        """Reverse the elements in the set, as if calling list.reverse"""
+        """Reverse the elements of the set in-place, as if calling `list.reverse`."""
         self._elements.reverse()
 
     def copy(self) -> OrderedSet[T]:
-        """Create a copy of the set"""
+        """
+        Create a shallow copy of the set.
+
+        Equivalent to `OrderedSet(self)`
+        """
         return OrderedSet(self)
 
     @override
@@ -261,12 +322,20 @@ def __get_pydantic_core_schema__(
 
     @classmethod
     def dedup(self, source: Iterable[T], /) -> Generator[T]:
-        """A utility method to deduplicate the specified iterable,
-        while preserving the original order.
+        """
+        Yield unique elements, preserving order.
 
-        This is a generator, so does not need to wait for the entire input,
+        This is a an iterator combinator (generator) similar to those in [`itertools`].
+        It does not need to wait for the entire input,
         and will return items as soon as they are available.
 
+        [`itertools`]: https://docs.python.org/3/library/itertools.html
+
+        This is similar to [`more_itertools.unique_everseen`],
+        although it uses an `OrderedSet` internally and does not support the `key` argument.
+
+        [`more_itertools.unique_everseen`]: https://more-itertools.readthedocs.io/en/v10.7.0/api.html#more_itertools.unique_everseen
+
         Since: v0.1.4
         """
         oset: OrderedSet[T] = OrderedSet()
@@ -277,14 +346,23 @@ def dedup(self, source: Iterable[T], /) -> Generator[T]:
 
     @classmethod
     async def dedup_async(self, source: AsyncIterable[T], /) -> AsyncGenerator[T]:
-        """A utility method to deduplicate the specified iterable,
-        while preserving the original order.
+        """
+        Yield unique elements, preserving order.
 
-        This is a generator, so does not need to wait for the entire input.
+        This is a an iterator combinator (generator) similar to those in [`itertools`].
+        It does not need to wait for the entire input,
+        and will return items as soon as they are available.
         Because it is asynchronous, it does not block the thread while waiting.
 
         This is an asynchronous version of `OrderedSet.dedup`.
 
+        It is similar to [`more_itertools.unique_everseen`],
+        but is asynchronous, uses an `OrderedSet` internally,
+        and does not support the `key` argument.
+
+        [`itertools`]: https://docs.python.org/3/library/itertools.html
+        [`more_itertools.unique_everseen`]: https://more-itertools.readthedocs.io/en/v10.7.0/api.html#more_itertools.unique_everseen
+
         Since: v0.1.4
         """
         # Defined in PEP 525