Skip to content

SortedKeyList

Bases: BaseSortedList[T]


              flowchart TD
              pyochain.collections._sorted._keylist.SortedKeyList[SortedKeyList]
              pyochain.collections._sorted._list.BaseSortedList[BaseSortedList]
              pyochain.collections._sorted._core.BaseSortedListSet[BaseSortedListSet]
              pyochain.collections._sorted._core.SortedCollection[SortedCollection]
              pyochain.abc._sequences.PyoMutableSequence[PyoMutableSequence]
              pyochain.abc._sequences.PyoSequence[PyoSequence]
              pyochain.abc._sequences.PyoReversible[PyoReversible]
              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.collections._sorted._list.BaseSortedList --> pyochain.collections._sorted._keylist.SortedKeyList
                                pyochain.collections._sorted._core.BaseSortedListSet --> pyochain.collections._sorted._list.BaseSortedList
                                pyochain.collections._sorted._core.SortedCollection --> pyochain.collections._sorted._core.BaseSortedListSet
                

                pyochain.abc._sequences.PyoMutableSequence --> pyochain.collections._sorted._list.BaseSortedList
                                pyochain.abc._sequences.PyoSequence --> pyochain.abc._sequences.PyoMutableSequence
                                pyochain.abc._sequences.PyoReversible --> pyochain.abc._sequences.PyoSequence
                                pyochain.abc._iterable.PyoIterable --> pyochain.abc._sequences.PyoReversible
                                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.PyoCollection --> pyochain.abc._sequences.PyoSequence
                                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
                







              click pyochain.collections._sorted._keylist.SortedKeyList href "" "pyochain.collections._sorted._keylist.SortedKeyList"
              click pyochain.collections._sorted._list.BaseSortedList href "" "pyochain.collections._sorted._list.BaseSortedList"
              click pyochain.collections._sorted._core.BaseSortedListSet href "" "pyochain.collections._sorted._core.BaseSortedListSet"
              click pyochain.collections._sorted._core.SortedCollection href "" "pyochain.collections._sorted._core.SortedCollection"
              click pyochain.abc._sequences.PyoMutableSequence href "" "pyochain.abc._sequences.PyoMutableSequence"
              click pyochain.abc._sequences.PyoSequence href "" "pyochain.abc._sequences.PyoSequence"
              click pyochain.abc._sequences.PyoReversible href "" "pyochain.abc._sequences.PyoReversible"
              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"

a MutableSequence that maintains its values in sorted order based on a key function.

The sorted-key list maintains values in comparison order based on the result of a key function applied to every value.

Optional iterable argument provides an initial iterable of values to initialize the sorted-key list.

key argument defines a callable that, like the key argument to Python's sorted function, extracts a comparison key from each value.

The default is the identity function.

Runtime complexity: O(n*log(n))

from pyochain.collections import SortedKeyList
from operator import neg

skl = SortedKeyList(key=neg)
assert repr(skl) == "SortedKeyList([], key=<built-in function neg>)"
skl = SortedKeyList([3, 1, 2], key=neg)
assert repr(skl) == "SortedKeyList([3, 2, 1], key=<built-in function neg>)"
Source code in pyochain/collections/_sorted/_keylist.pyi 
 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
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
class SortedKeyList[T, OT: SupportsRichComparison](BaseSortedList[T]):
    """a `MutableSequence` that maintains its values in sorted order based on a key function.

    The sorted-key list maintains values in comparison order based on the result of a key function applied to every value.

    Optional `iterable` argument provides an initial iterable of values to initialize the sorted-key list.

    `key` argument defines a callable that, like the `key` argument to Python's `sorted` function, extracts a comparison key from each value.

    The default is the identity function.

    Runtime complexity: `O(n*log(n))`

    ```python
    from pyochain.collections import SortedKeyList
    from operator import neg

    skl = SortedKeyList(key=neg)
    assert repr(skl) == "SortedKeyList([], key=<built-in function neg>)"
    skl = SortedKeyList([3, 1, 2], key=neg)
    assert repr(skl) == "SortedKeyList([3, 2, 1], key=<built-in function neg>)"
    ```
    """
    @overload
    def __new__(
        cls, iterable: Iterable[OT], key: None = None
    ) -> SortedKeyList[OT, OT]: ...
    @overload
    def __new__(
        cls, iterable: Iterable[T] | None = None, key: KeyFunc[T, OT] = ...
    ) -> Self: ...
    def __new__(
        cls, iterable: Iterable[T] | None = None, key: KeyFunc[T, OT] | None = None
    ) -> Self:
        """Create a new sorted-key list.

        Args:
            iterable (Iterable[T] | None): initial values (optional)
            key (KeyFunc[T, OT] | None): function used to extract comparison key (optional)

        Returns:
            Self: new sorted-key list
        """

    @override
    def __add__(self, other: Iterable[T]) -> Self: ...
    @override
    def __mul__(self, num: int) -> Self: ...
    @override
    def __reduce__(self) -> tuple[type[Self], tuple[Vec[T], KeyFunc[T, OT]]]: ...
    def irange_key(
        self,
        min_key: OT | None = None,
        max_key: OT | None = None,
        inclusive: tuple[bool, bool] = (True, True),
        *,
        reverse: bool = False,
    ) -> PyoIterator[T]:
        """Create an iterator of values between `min_key` and `max_key`.

        Both `min_key` and `max_key` default to `None` which is automatically inclusive of the beginning and end of the sorted-key list.

        Args:
            min_key (OT | None): minimum key to start iterating
            max_key (OT | None): maximum key to stop iterating
            inclusive (tuple[bool, bool]): Whether the minimum and maximum ought to be included in the range, respectively. The default is ``(True, True)`` such that the range is inclusive of both minimum and maximum.
            reverse (bool): When `True` the values are yielded in reverse order. Defaults to `False`.

        Returns:
            PyoIterator[T]: iterator of values between `min_key` and `max_key`

        Examples:
        ```python
        from pyochain.collections import SortedKeyList
        from operator import neg

        skl = SortedKeyList([11, 12, 13, 14, 15], key=neg)
        it = skl.irange_key(-14, -12)
        assert list(it) == [14, 13, 12]
        ```

        """

    def bisect_key_left(self, key: OT) -> int:
        """Return an index to insert `key` in the `SortedKeyList`.

        If the `key` is already present, the insertion point will be before (to the left of) any existing keys.

        Similar to the `bisect` module in the standard library.

        Runtime complexity: `O(log(n))` -- approximate.


        Args:
            key (OT): insertion index of key in sorted-key list

        Returns:
            int: index

        Examples:
        ```python
        from pyochain.collections import SortedKeyList
        from operator import neg

        skl = SortedKeyList([5, 4, 3, 2, 1], key=neg)
        assert skl.bisect_key_left(-1) == 4
        ```
        """

    def bisect_key_right(self, key: OT) -> int:
        """Return an index to insert `key` in the `SortedKeyList`.

        Similar to `bisect_key_left`, but if `key` is already present, the insertion point will be after (to the right of) any existing keys.

        Similar to the `bisect` module in the standard library.

        Runtime complexity: `O(log(n))` -- approximate.


        Args:
            key (OT): insertion index of key in sorted-key list

        Returns:
            int: index

        Examples:
        ```python
        from pyochain.collections import SortedKeyList
        from operator import neg

        skl = SortedKeyList([5, 4, 3, 2, 1], key=neg)
        assert skl.bisect_key_right(-1) == 5
        ```
        """

    @override
    def copy(self) -> Self: ...

__new__(iterable=None, key=None) 

__new__(
    iterable: Iterable[OT], key: None = None
) -> SortedKeyList[OT, OT]

__new__(
    iterable: Iterable[T] | None = None,
    key: KeyFunc[T, OT] = ...,
) -> Self

Create a new sorted-key list.

Parameters:

Name Type Description Default
iterable Iterable[T] | None

initial values (optional)

 None
key KeyFunc[T, OT] | None

function used to extract comparison key (optional)

 None

Returns:

Name Type Description
Self Self

new sorted-key list
Source code in pyochain/collections/_sorted/_keylist.pyi 
46
47
48
49
50
51
52
53
54
55
56
57
def __new__(
    cls, iterable: Iterable[T] | None = None, key: KeyFunc[T, OT] | None = None
) -> Self:
    """Create a new sorted-key list.

    Args:
        iterable (Iterable[T] | None): initial values (optional)
        key (KeyFunc[T, OT] | None): function used to extract comparison key (optional)

    Returns:
        Self: new sorted-key list
    """

irange_key(min_key=None, max_key=None, inclusive=(True, True), *, reverse=False)

Create an iterator of values between min_key and max_key.

Both min_key and max_key default to None which is automatically inclusive of the beginning and end of the sorted-key list.

Parameters:

Name Type Description Default
min_key OT | None

minimum key to start iterating

 None
max_key OT | None

maximum key to stop iterating

 None
inclusive tuple[bool, bool]

Whether the minimum and maximum ought to be included in the range, respectively. The default is (True, True) such that the range is inclusive of both minimum and maximum.

 (True, True)
reverse bool

When True the values are yielded in reverse order. Defaults to False.

 False

Returns:

Type Description
PyoIterator[T]

PyoIterator[T]: iterator of values between min_key and max_key

Examples: 

from pyochain.collections import SortedKeyList
from operator import neg

skl = SortedKeyList([11, 12, 13, 14, 15], key=neg)
it = skl.irange_key(-14, -12)
assert list(it) == [14, 13, 12]

Source code in pyochain/collections/_sorted/_keylist.pyi 
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
def irange_key(
    self,
    min_key: OT | None = None,
    max_key: OT | None = None,
    inclusive: tuple[bool, bool] = (True, True),
    *,
    reverse: bool = False,
) -> PyoIterator[T]:
    """Create an iterator of values between `min_key` and `max_key`.

    Both `min_key` and `max_key` default to `None` which is automatically inclusive of the beginning and end of the sorted-key list.

    Args:
        min_key (OT | None): minimum key to start iterating
        max_key (OT | None): maximum key to stop iterating
        inclusive (tuple[bool, bool]): Whether the minimum and maximum ought to be included in the range, respectively. The default is ``(True, True)`` such that the range is inclusive of both minimum and maximum.
        reverse (bool): When `True` the values are yielded in reverse order. Defaults to `False`.

    Returns:
        PyoIterator[T]: iterator of values between `min_key` and `max_key`

    Examples:
    ```python
    from pyochain.collections import SortedKeyList
    from operator import neg

    skl = SortedKeyList([11, 12, 13, 14, 15], key=neg)
    it = skl.irange_key(-14, -12)
    assert list(it) == [14, 13, 12]
    ```

    """

bisect_key_left(key)

Return an index to insert key in the SortedKeyList.

If the key is already present, the insertion point will be before (to the left of) any existing keys.

Similar to the bisect module in the standard library.

Runtime complexity: O(log(n)) -- approximate.

Parameters:

Name Type Description Default
key OT

insertion index of key in sorted-key list

 required

Returns:

Name Type Description
int int

index

Examples: 

from pyochain.collections import SortedKeyList
from operator import neg

skl = SortedKeyList([5, 4, 3, 2, 1], key=neg)
assert skl.bisect_key_left(-1) == 4

Source code in pyochain/collections/_sorted/_keylist.pyi 
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
def bisect_key_left(self, key: OT) -> int:
    """Return an index to insert `key` in the `SortedKeyList`.

    If the `key` is already present, the insertion point will be before (to the left of) any existing keys.

    Similar to the `bisect` module in the standard library.

    Runtime complexity: `O(log(n))` -- approximate.


    Args:
        key (OT): insertion index of key in sorted-key list

    Returns:
        int: index

    Examples:
    ```python
    from pyochain.collections import SortedKeyList
    from operator import neg

    skl = SortedKeyList([5, 4, 3, 2, 1], key=neg)
    assert skl.bisect_key_left(-1) == 4
    ```
    """

bisect_key_right(key)

Return an index to insert key in the SortedKeyList.

Similar to bisect_key_left, but if key is already present, the insertion point will be after (to the right of) any existing keys.

Similar to the bisect module in the standard library.

Runtime complexity: O(log(n)) -- approximate.

Parameters:

Name Type Description Default
key OT

insertion index of key in sorted-key list

 required

Returns:

Name Type Description
int int

index

Examples: 

from pyochain.collections import SortedKeyList
from operator import neg

skl = SortedKeyList([5, 4, 3, 2, 1], key=neg)
assert skl.bisect_key_right(-1) == 5

Source code in pyochain/collections/_sorted/_keylist.pyi 
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
def bisect_key_right(self, key: OT) -> int:
    """Return an index to insert `key` in the `SortedKeyList`.

    Similar to `bisect_key_left`, but if `key` is already present, the insertion point will be after (to the right of) any existing keys.

    Similar to the `bisect` module in the standard library.

    Runtime complexity: `O(log(n))` -- approximate.


    Args:
        key (OT): insertion index of key in sorted-key list

    Returns:
        int: index

    Examples:
    ```python
    from pyochain.collections import SortedKeyList
    from operator import neg

    skl = SortedKeyList([5, 4, 3, 2, 1], key=neg)
    assert skl.bisect_key_right(-1) == 5
    ```
    """