StableSet

Bases: PyoMutableSet[T], ArgsWrapper[T]

              flowchart TD
              pyochain.collections._stableset.StableSet[StableSet]
              pyochain.abc._mutable_set.PyoMutableSet[PyoMutableSet]
              pyochain.abc._set.PyoSet[PyoSet]
              pyochain.abc._collection.PyoCollection[PyoCollection]
              pyochain.abc._iterable.PyoIterable[PyoIterable]
              pyochain.abc._collection.PyoContainer[PyoContainer]
              pyochain.abc._collection.PyoSized[PyoSized]
              pyochain.abc._mixins.Checkable[Checkable]
              pyochain.abc._mixins.Fluent[Fluent]
              pyochain.abc._mixins.Pipe[Pipe]
              pyochain.abc._mixins.Tap[Tap]
              pyochain.abc.constructors.ArgsWrapper[ArgsWrapper]
              pyochain.abc.constructors.FromArgs[FromArgs]
              pyochain.abc.constructors.FromIter[FromIter]
              pyochain.abc.constructors.Wrapper[Wrapper]

                              pyochain.abc._mutable_set.PyoMutableSet --> pyochain.collections._stableset.StableSet
                                pyochain.abc._set.PyoSet --> pyochain.abc._mutable_set.PyoMutableSet
                                pyochain.abc._collection.PyoCollection --> pyochain.abc._set.PyoSet
                                pyochain.abc._iterable.PyoIterable --> pyochain.abc._collection.PyoCollection
                                pyochain.abc._mixins.Checkable --> pyochain.abc._iterable.PyoIterable
                
                pyochain.abc._mixins.Fluent --> pyochain.abc._iterable.PyoIterable
                                pyochain.abc._mixins.Pipe --> pyochain.abc._mixins.Fluent
                
                pyochain.abc._mixins.Tap --> pyochain.abc._mixins.Fluent
                


                pyochain.abc._collection.PyoContainer --> pyochain.abc._collection.PyoCollection
                                pyochain.abc._mixins.Checkable --> pyochain.abc._collection.PyoContainer
                

                pyochain.abc._collection.PyoSized --> pyochain.abc._collection.PyoCollection
                                pyochain.abc._mixins.Checkable --> pyochain.abc._collection.PyoSized
                




                pyochain.abc.constructors.ArgsWrapper --> pyochain.collections._stableset.StableSet
                                pyochain.abc.constructors.FromArgs --> pyochain.abc.constructors.ArgsWrapper
                                pyochain.abc.constructors.FromIter --> pyochain.abc.constructors.FromArgs
                

                pyochain.abc.constructors.Wrapper --> pyochain.abc.constructors.ArgsWrapper
                



              click pyochain.collections._stableset.StableSet href "" "pyochain.collections._stableset.StableSet"
              click pyochain.abc._mutable_set.PyoMutableSet href "" "pyochain.abc._mutable_set.PyoMutableSet"
              click pyochain.abc._set.PyoSet href "" "pyochain.abc._set.PyoSet"
              click pyochain.abc._collection.PyoCollection href "" "pyochain.abc._collection.PyoCollection"
              click pyochain.abc._iterable.PyoIterable href "" "pyochain.abc._iterable.PyoIterable"
              click pyochain.abc._collection.PyoContainer href "" "pyochain.abc._collection.PyoContainer"
              click pyochain.abc._collection.PyoSized href "" "pyochain.abc._collection.PyoSized"
              click pyochain.abc._mixins.Checkable href "" "pyochain.abc._mixins.Checkable"
              click pyochain.abc._mixins.Fluent href "" "pyochain.abc._mixins.Fluent"
              click pyochain.abc._mixins.Pipe href "" "pyochain.abc._mixins.Pipe"
              click pyochain.abc._mixins.Tap href "" "pyochain.abc._mixins.Tap"
              click pyochain.abc.constructors.ArgsWrapper href "" "pyochain.abc.constructors.ArgsWrapper"
              click pyochain.abc.constructors.FromArgs href "" "pyochain.abc.constructors.FromArgs"
              click pyochain.abc.constructors.FromIter href "" "pyochain.abc.constructors.FromIter"
              click pyochain.abc.constructors.Wrapper href "" "pyochain.abc.constructors.Wrapper"
            

A mutable collection of unique elements which remember their insertion order.

Uses a dict as the underlying data structure to maintain insertion order while ensuring uniqueness of elements.

Thus, it has the same characteristics of "standard" sets, with lookup and iteration speed the same as a dict.

This is very similar to using Dict::from_keys with None values, but with a specialized interface for set operations.

from pyochain import Some
from pyochain.collections import StableSet

s = StableSet("a", "b", "c")
assert repr(s) == "StableSet('a', 'b', 'c')"

# Mutation preserves insertion order

s.add("d")
assert s.iter().next() == Some("a")
assert s.iter().last() == "d"
assert repr(s) == "StableSet('a', 'b', 'c', 'd')"

s.discard("b")
assert s.iter().next() == Some("a")
assert s.iter().skip(1).next() == Some("c")
assert s.iter().last() == "d"
assert repr(s) == "StableSet('a', 'c', 'd')"

  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118

class StableSet[T](PyoMutableSet[T], ArgsWrapper[T]):
    """A mutable collection of unique elements which remember their insertion order.

    Uses a `dict` as the underlying data structure to maintain insertion order while ensuring uniqueness of elements.

    Thus, it has the same characteristics of "standard" sets, with lookup and iteration speed the same as a `dict`.

    This is very similar to using `Dict::from_keys` with `None` values, but with a specialized interface for set operations.

    Note:
        This is not the same as `sortedcontainers`, i.e it does not maintain the elements in sorted order, but rather in the order they were inserted.

    Example:
        ```python
        from pyochain import Some
        from pyochain.collections import StableSet

        s = StableSet("a", "b", "c")
        assert repr(s) == "StableSet('a', 'b', 'c')"

        # Mutation preserves insertion order

        s.add("d")
        assert s.iter().next() == Some("a")
        assert s.iter().last() == "d"
        assert repr(s) == "StableSet('a', 'b', 'c', 'd')"

        s.discard("b")
        assert s.iter().next() == Some("a")
        assert s.iter().skip(1).next() == Some("c")
        assert s.iter().last() == "d"
        assert repr(s) == "StableSet('a', 'c', 'd')"
        ```
    """
    def __new__(cls, data: Iterable[T] | T = (), /, *elements: T) -> Self:
        """Create a new `StableSet` instance.

        If data is
        - not provided, or an empty `Iterable`, an empty `StableSet` is created.
        - a non-empty `Iterable`, the elements of the iterable are added to the set.
        - a single non-iterable element, it creates a `StableSet` with that element.

        Additional elements can be provided as positional arguments.

        Args:
            data (Iterable[T] | T): initial data to populate the `StableSet`. Defaults to `()`.
            *elements (T): Additional elements to add to the set.

        Returns:
            Self: A new `StableSet` instance.

        Examples:
            ```python
            from pyochain.collections import StableSet

            data = ("a", "b", "c")
            # Creates an empty `StableSet`
            assert StableSet() == StableSet(()) == StableSet([]) == frozenset()
            # Create a `StableSet` from an iterable
            assert StableSet(data) == StableSet(list(data)) == frozenset(data)
            # Create a `StableSet` from a single non-iterable element
            assert StableSet(1) == StableSet([1]) == frozenset([1])
            # Create a `StableSet` from multiple elements
            assert StableSet("a", "b", "c") == StableSet(*data) == frozenset(data)
            ```
        """
    @override
    def __iter__(self) -> Iterator[T]: ...
    @override
    def __len__(self) -> int: ...
    @override
    def __contains__(self, item: object) -> bool: ...
    @override
    def __eq__(self, other: object) -> bool: ...
    @override
    @staticmethod
    def from_iter[T1](iterable: Iterable[T1], /) -> StableSet[T1]: ...
    @override
    @staticmethod
    def of[T1](*elements: T1) -> StableSet[T1]: ...
    @override
    @staticmethod
    def wrap[V](data: dict[V, Any]) -> StableSet[V]: ...  # pyright: ignore[reportIncompatibleMethodOverride]
    @override
    def add(self, value: T) -> None: ...
    def copy(self) -> StableSet[T]:
        """Return a shallow copy of the `StableSet`.

        Returns:
            StableSet[T]: A new `StableSet` instance that is a shallow copy of the original.

        Example:
            ```python
            from pyochain.collections import StableSet

            s = StableSet("a", "b", "c")
            s_copy = s.copy()
            assert s_copy == StableSet("a", "b", "c")
            ```
        """

    @override
    def discard(self, value: T) -> None: ...
    @override
    def intersection(self, other: Iterable[Any]) -> SetMut[T]: ...
    @override
    def union[S](self, other: Iterable[S]) -> SetMut[T | S]: ...
    @override
    def difference(self, other: Iterable[Any]) -> SetMut[T]: ...
    @override
    def symmetric_difference[S](self, other: Iterable[S]) -> SetMut[T | S]: ...

from pyochain.collections import StableSet

data = ("a", "b", "c")
# Creates an empty `StableSet`
assert StableSet() == StableSet(()) == StableSet([]) == frozenset()
# Create a `StableSet` from an iterable
assert StableSet(data) == StableSet(list(data)) == frozenset(data)
# Create a `StableSet` from a single non-iterable element
assert StableSet(1) == StableSet([1]) == frozenset([1])
# Create a `StableSet` from multiple elements
assert StableSet("a", "b", "c") == StableSet(*data) == frozenset(data)

42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73

def __new__(cls, data: Iterable[T] | T = (), /, *elements: T) -> Self:
    """Create a new `StableSet` instance.

    If data is
    - not provided, or an empty `Iterable`, an empty `StableSet` is created.
    - a non-empty `Iterable`, the elements of the iterable are added to the set.
    - a single non-iterable element, it creates a `StableSet` with that element.

    Additional elements can be provided as positional arguments.

    Args:
        data (Iterable[T] | T): initial data to populate the `StableSet`. Defaults to `()`.
        *elements (T): Additional elements to add to the set.

    Returns:
        Self: A new `StableSet` instance.

    Examples:
        ```python
        from pyochain.collections import StableSet

        data = ("a", "b", "c")
        # Creates an empty `StableSet`
        assert StableSet() == StableSet(()) == StableSet([]) == frozenset()
        # Create a `StableSet` from an iterable
        assert StableSet(data) == StableSet(list(data)) == frozenset(data)
        # Create a `StableSet` from a single non-iterable element
        assert StableSet(1) == StableSet([1]) == frozenset([1])
        # Create a `StableSet` from multiple elements
        assert StableSet("a", "b", "c") == StableSet(*data) == frozenset(data)
        ```
    """

from pyochain.collections import StableSet

s = StableSet("a", "b", "c")
s_copy = s.copy()
assert s_copy == StableSet("a", "b", "c")

 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107

def copy(self) -> StableSet[T]:
    """Return a shallow copy of the `StableSet`.

    Returns:
        StableSet[T]: A new `StableSet` instance that is a shallow copy of the original.

    Example:
        ```python
        from pyochain.collections import StableSet

        s = StableSet("a", "b", "c")
        s_copy = s.copy()
        assert s_copy == StableSet("a", "b", "c")
        ```
    """