Add from_iterable

Author: Maciej Rapacz

README.md

@@ -9,54 +9,98 @@
 
 ## Prerequisites
 
-The only requirement is having Python 3.8+ installed, you can verify this by running:
+The only requirement is using **Python 3.8+**. You can verify this by running:
+
 ```bash
 $ python --version
-Python 3.8.16
+Python 3.8.18
 ```
 
 ## Installation
+
 ```
 pip install disjoint-set
 ```
 
 You can verify you're running the latest package version by running:
+
 ```python
 >>> import disjoint_set
 >>> disjoint_set.__version__
-'0.7.4'
+'0.8.0'
 
 ```
 
 ## Usage
 
+### Import & instantiate
+
 ```python
 >>> from disjoint_set import DisjointSet
+>>> DisjointSet()
+DisjointSet({})
+
+>>> DisjointSet({1: 1})
+DisjointSet({1: 1})
+
+>>> DisjointSet.from_iterable([1,2,3])
+DisjointSet({1: 1, 2: 2, 3: 3})
+
+```
+
+### Perform find & union operations
+
+```python
 >>> ds = DisjointSet()
 >>> ds.find(1)
 1
+
 >>> ds.union(1,2)
 >>> ds.find(1)
 2
+
 >>> ds.find(2)
 2
+
+```
+
+### Check if values belong to the same set
+
+```python
+>>> ds = DisjointSet({1: 2, 2: 2, 3: 3})
 >>> ds.connected(1,2)
 True
+
 >>> ds.connected(1,3)
 False
 
+```
+
+### Check if values are present within the data structure
+
+```python
+>>> ds = DisjointSet()
 >>> "a" in ds
 False
+
 >>> ds.find("a")
 'a'
+
 >>> "a" in ds
 True
 
+```
+
+### List elements and sets within the disjoint set
+
+```python
+>>> ds = DisjointSet({1: 2, 2: 2, 3: 3})
 >>> list(ds)
-[(1, 2), (2, 2), (3, 3), ('a', 'a')]
+[(1, 2), (2, 2), (3, 3)]
 
+>>> ds = DisjointSet({1: 2, 2: 2, 3: 3})
 >>> list(ds.itersets())
-[{1, 2}, {3}, {'a'}]
+[{1, 2}, {3}]
 
 ```
 
@@ -66,8 +110,7 @@ Feel free to open any issues on github.
 
 ## Authors
 
-* [Maciej Rapacz](https://github.com/mrapacz/)
-
+- [Maciej Rapacz](https://github.com/mrapacz/)
 
 ## License
 

disjoint_set/__init__.py

@@ -3,4 +3,4 @@
 
 name = "disjoint_set"
 __all__ = ["DisjointSet", "InvalidInitialMappingError"]
-__version__ = "0.7.4"
+__version__ = "0.8.0"

disjoint_set/main.py

@@ -1,12 +1,12 @@
+from __future__ import annotations
+
 from collections import defaultdict
 from typing import Any
 from typing import DefaultDict
 from typing import Generic
+from typing import Iterable
 from typing import Iterator
-from typing import Set
-from typing import Tuple
 from typing import TypeVar
-from typing import Union
 
 from disjoint_set.utils import IdentityDict
 
@@ -32,12 +32,34 @@ class DisjointSet(Generic[T]):
     """A disjoint set data structure."""
 
     def __init__(self, *args, **kwargs) -> None:
+        """
+        Disjoint set data structure.
+
+        The data structure can be initialized as an empty disjoint set:
+        >>> DisjointSet()
+        DisjointSet({})
+
+        But it can also be instantiated from an existing mapping such as:
+        >>> DisjointSet({1: 2, 2: 2})
+        DisjointSet({1: 2, 2: 2})
+        """
         self._data: IdentityDict[T] = IdentityDict(*args, **kwargs)
 
+    @classmethod
+    def from_iterable(cls, iterable: Iterable[T]) -> DisjointSet[T]:
+        """Instantiate a DistjointSet instance by transforming each element from an interable to a canonical element."""
+        return cls({x: x for x in iterable})
+
+    def __len__(self) -> int:
+        """Return the number of elements in the disjoint set."""
+        return len(self._data)
+
     def __contains__(self, item: T) -> bool:
+        """Return True if `item` is an element of the disjoint set (not necessarily a canonical one)."""
         return item in self._data
 
     def __bool__(self) -> bool:
+        """Return True if disjoint set contains at least one element."""
         return bool(self._data)
 
     def __getitem__(self, element: T) -> T:
@@ -72,15 +94,15 @@ def __str__(self) -> str:
             values=", ".join(str(dset) for dset in self.itersets()),
         )
 
-    def __iter__(self) -> Iterator[Tuple[T, T]]:
+    def __iter__(self) -> Iterator[tuple[T, T]]:
         """Iterate over items and their canonical elements."""
         try:
             for key in self._data.keys():
                 yield key, self.find(key)
         except RuntimeError as e:
             raise InvalidInitialMappingError() from e
 
-    def itersets(self, with_canonical_elements: bool = False) -> Iterator[Union[Set[T], Tuple[T, Set[T]]]]:
+    def itersets(self, with_canonical_elements: bool = False) -> Iterator[set[T] | tuple[T, set[T]]]:
         """
         Yield sets of connected components.
 
@@ -92,7 +114,7 @@ def itersets(self, with_canonical_elements: bool = False) -> Iterator[Union[Set[
         >>> list(ds.itersets(with_canonical_elements=True))
         [(2, {1, 2})]
         """
-        element_classes: DefaultDict[T, Set[T]] = defaultdict(set)
+        element_classes: DefaultDict[T, set[T]] = defaultdict(set)
         for element in self._data:
             element_classes[self.find(element)].add(element)
 

tests/test_disjoint_set.py

@@ -77,3 +77,15 @@ def test_raises_on_invalid_init_params():
     dset = DisjointSet({1: 2, 2: 3})
     with pytest.raises(InvalidInitialMappingError):
         list(dset)
+
+
+@pytest.mark.parametrize(
+    argnames=("iterable", "expected_value"),
+    argvalues=(
+        pytest.param([], DisjointSet({}), id="empty list"),
+        pytest.param(range(3), DisjointSet({2: 2, 1: 1, 0: 0}), id="range(3)"),
+        pytest.param("abc", DisjointSet({"a": "a", "b": "b", "c": "c"}), id="string"),
+    ),
+)
+def test_from_iterable(iterable, expected_value):
+    assert DisjointSet.from_iterable(iterable=iterable) == expected_value