Skip to content

QList

Bases: list

QList is a python list extension that adds several chainable, lazy evaluated methods to the standard list.

Found in qwlist.QList

Source code in src\qwlist\qwlist.py
 666
 667
 668
 669
 670
 671
 672
 673
 674
 675
 676
 677
 678
 679
 680
 681
 682
 683
 684
 685
 686
 687
 688
 689
 690
 691
 692
 693
 694
 695
 696
 697
 698
 699
 700
 701
 702
 703
 704
 705
 706
 707
 708
 709
 710
 711
 712
 713
 714
 715
 716
 717
 718
 719
 720
 721
 722
 723
 724
 725
 726
 727
 728
 729
 730
 731
 732
 733
 734
 735
 736
 737
 738
 739
 740
 741
 742
 743
 744
 745
 746
 747
 748
 749
 750
 751
 752
 753
 754
 755
 756
 757
 758
 759
 760
 761
 762
 763
 764
 765
 766
 767
 768
 769
 770
 771
 772
 773
 774
 775
 776
 777
 778
 779
 780
 781
 782
 783
 784
 785
 786
 787
 788
 789
 790
 791
 792
 793
 794
 795
 796
 797
 798
 799
 800
 801
 802
 803
 804
 805
 806
 807
 808
 809
 810
 811
 812
 813
 814
 815
 816
 817
 818
 819
 820
 821
 822
 823
 824
 825
 826
 827
 828
 829
 830
 831
 832
 833
 834
 835
 836
 837
 838
 839
 840
 841
 842
 843
 844
 845
 846
 847
 848
 849
 850
 851
 852
 853
 854
 855
 856
 857
 858
 859
 860
 861
 862
 863
 864
 865
 866
 867
 868
 869
 870
 871
 872
 873
 874
 875
 876
 877
 878
 879
 880
 881
 882
 883
 884
 885
 886
 887
 888
 889
 890
 891
 892
 893
 894
 895
 896
 897
 898
 899
 900
 901
 902
 903
 904
 905
 906
 907
 908
 909
 910
 911
 912
 913
 914
 915
 916
 917
 918
 919
 920
 921
 922
 923
 924
 925
 926
 927
 928
 929
 930
 931
 932
 933
 934
 935
 936
 937
 938
 939
 940
 941
 942
 943
 944
 945
 946
 947
 948
 949
 950
 951
 952
 953
 954
 955
 956
 957
 958
 959
 960
 961
 962
 963
 964
 965
 966
 967
 968
 969
 970
 971
 972
 973
 974
 975
 976
 977
 978
 979
 980
 981
 982
 983
 984
 985
 986
 987
 988
 989
 990
 991
 992
 993
 994
 995
 996
 997
 998
 999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
1137
1138
1139
1140
1141
1142
1143
1144
1145
1146
1147
1148
1149
1150
1151
1152
1153
1154
1155
1156
1157
1158
1159
1160
1161
1162
1163
1164
1165
1166
1167
1168
1169
1170
1171
1172
1173
1174
1175
1176
1177
1178
1179
1180
1181
1182
1183
1184
1185
1186
1187
1188
1189
1190
1191
1192
1193
1194
1195
1196
1197
1198
1199
1200
1201
1202
1203
1204
1205
1206
1207
1208
1209
1210
1211
1212
1213
1214
1215
1216
1217
1218
1219
1220
1221
1222
1223
1224
1225
1226
1227
1228
1229
1230
1231
1232
1233
1234
1235
1236
1237
1238
1239
1240
1241
1242
1243
1244
1245
1246
1247
1248
1249
1250
1251
1252
1253
1254
1255
1256
1257
1258
1259
1260
1261
1262
1263
1264
1265
1266
1267
1268
1269
1270
1271
1272
1273
1274
1275
1276
1277
1278
1279
1280
1281
1282
1283
1284
1285
1286
1287
1288
1289
1290
1291
1292
1293
1294
1295
1296
1297
1298
1299
1300
1301
1302
1303
1304
1305
1306
1307
1308
1309
1310
1311
1312
1313
1314
1315
1316
1317
1318
1319
1320
1321
1322
1323
1324
1325
1326
1327
1328
1329
1330
1331
1332
1333
1334
1335
1336
1337
1338
1339
1340
1341
1342
1343
1344
1345
1346
1347
1348
1349
1350
1351
1352
1353
1354
class QList(list):
    """
    `QList` is a python list extension that adds several chainable, lazy
    evaluated methods to the standard `list`.

    Found in `qwlist.QList`
    """

    @overload
    def __getitem__(self, item: slice) -> "QList[T]":
        ...

    @overload
    def __getitem__(self, item: int) -> T:
        ...

    def __getitem__(self, item):
        if isinstance(item, slice):
            return QList(super().__getitem__(item))
        return super().__getitem__(item)

    def iter(self) -> Iterator[T]:
        """
        Changes `self` into `Iterator[T]` by calling the `iter()` function.

        Returns:
            iterator over the elements of `self`.
        """
        return iter(self)

    def slice(self, s: slice) -> Lazy[T]:
        """
        Calling this method with `s` equal to `slice(3)` works similarly to
        `list[:3]` but is lazy evaluated.

        Args:
            s: slice object

        Returns: `Lazy[T]`
        """
        assert isinstance(s, slice), f"slice method argument must be a slice object. Got {type(s)}."

        def inner():
            for elem in self[s]:
                yield elem
        return Lazy(inner())

    def list(self) -> List[T]:
        """
        Changes `QList` into standard Python `list`.

        Returns:
            Standard Python `list`.
        """
        return list(self)

    def eager(self) -> "EagerQList[T]":
        """
        Changes `QList` into `EagerQList`.

        Returns:
            Eagerly evaluated version of `QList`.
        """
        from .eager import EagerQList
        return EagerQList(self)

    def filter(self, pred: Callable[[T], bool]) -> Lazy[T]:
        """
        Returns a `Lazy` object containing all values from `self` for which
        the predicate holds true.

        Args:
            pred: `function: (T) -> bool`

        Returns:
            New `Lazy[T]` with elements for which the predicate holds true.

        Examples:
            >>> QList([0, 1, 2, 3]).filter(lambda x: x < 2).collect()
            [0, 1]
        """
        def inner():
            for elem in self:
                if pred(elem):
                    yield elem
        return Lazy(inner())

    def map(self, mapper: Callable[[T], K]) -> Lazy[K]:
        """
        Returns a `Lazy` object containing all values from `self` with
        the mapping function applied on them.

        Args:
            mapper: `function: (T) -> K`

        Returns:
            New `Lazy[K]` with mapped elements from `self`.
        """
        def inner():
            for elem in self:
                yield mapper(elem)
        return Lazy(inner())

    def foreach(self, action: Callable[[T], None]):
        """
        Applies the given function to each of the `QList` elements.

        Args:
            action: `function: (T) -> None`

        Returns:
            `None`
        """
        for elem in self:
            action(elem)

    def fold(self, operation: Callable[[K, T], K], init: K) -> K:
        """
        Given the combination operator reduces `self` by processing
        its constituent parts, building up the final value.

        **Other names:** fold_left, reduce, accumulate, aggregate.

        Args:
            operation: `function: (K, T) -> K`. Given the initial value `init` applies the
                given combination operator on each element yielded by `self`,
                treating the result as the first argument in the next step.
            init (K): initial value for the combination operator.

        Returns:
            The final value created from calling the `operation` on consecutive elements of `self`.

        Examples:
            >>> QList([1, 2, 3]).fold(lambda acc, x: acc + x, 0)
            6
        """
        acc = init
        for elem in self:
            acc = operation(acc, elem)
        return acc

    def fold_right(self, operation: Callable[[K, T], K], init: K) -> K:
        """
        Given the combination operator reduces `self` by processing
        its constituent parts, building up the final value.

        Args:
            operation: `function: (K, T) -> K`
                Given the initial value `init` applies the
                given combination operator on each element of `self`, starting from the
                last element, treating the result as a first argument in the next step.
            init: initial value for the combination operator.

        Returns:
            The final value created from calling the `operation` on consecutive elements of `self`
             starting from the last element.

        Examples:
            >>> QList([1, 2, 3]).fold_right(lambda acc, x: acc + x, 0)
            6
        """
        acc = init
        for elem in self[::-1]:
            acc = operation(acc, elem)
        return acc

    def scan(self, operation: Callable[[K, T], K], state: K) -> "Lazy[K]":
        """
        Given the combination operator creates a `Lazy[K]` object by processing
        constituent parts of `self`, yielding intermediate steps and building up the final value.
        Scan is similar to fold but returns all intermediate states instead of just the final result.

        Args:
            operation: `function: (K, T) -> K`. Given the initial `state` applies the given
             combination operator on each element yielded by the `Lazy` object, yielding the result and
             then treating it as the first argument in the next step.
            state (K): initial value for the state.

        Returns:
            New `Lazy[K]` with all intermediate steps of the `operation`.

        Examples:
            >>> QList([1, 2, 3]).scan(lambda acc, x: acc + x, 0).collect()
            [1, 3, 6]
        """
        def inner(s):
            for elem in self:
                s = operation(s, elem)
                yield s
        return Lazy(inner(state))

    def len(self) -> int:
        """
        Returns the length of `self`.

        (time complexity: `O(1)`)

        Returns:
            Length of the `QList`
        """
        return len(self)

    def flatmap(self, mapper: Callable[[T], Iterable[K]]) -> Lazy[K]:
        """
        Applies the mapper function to each of the yielded elements and flattens the results.

        Args:
            mapper: `function: (T) -> Iterable[K]`.

        Returns:
            New `Lazy` with elements from `self` mapped to an iterable and then flattened.

        Examples:
            >>> QList([1, 2]).flatmap(lambda x: [x, x]).qlist()
            [1, 1, 2, 2]
        """
        def inner():
            for elem in self:
                yield from mapper(elem)
        return Lazy(inner())

    def zip(self, other: Iterable[K]) -> Lazy[tuple[T, K]]:
        """
        Combines `self` with the given `Iterable` elementwise as tuples.
         The returned `Lazy` objects yields at most the number of elements of
         the shorter sequence (`self` or `other`).

        Args:
            other (Iterable[K]): iterable to zip with `self`.

        Returns:
            New `Lazy` with pairs of elements from `self` and `other`.

        Examples:
            >>> Lazy([1, 2, 3]).zip(['a', 'b', 'c']).collect()
            [(1, 'a'), (2, 'b'), (3, 'c')]
        """
        return Lazy(zip(self, other))

    def sorted(self, key: Callable[[T], SupportsLessThan] = None, reverse: bool = False) -> "QList[T]":
        """
        Returns a new `QList` containing all items from the original list in ascending order.

        A custom key function can be supplied to customize the sort order, and the reverse
        flag can be set to request the result in descending order.

        Args:
            key (Callable[[T], SupportsLessThan]): `function: (T) -> SupportsLessThan`. Defaults to `None`.
            reverse (bool): if set to `True` sorts values in descending order. Defaults to `False`.

        Returns:
            Sorted `QList`.
        """
        return QList(sorted(self, key=key, reverse=reverse))

    def skip(self, n: int) -> Lazy[T]:
        """
        Skips `n` first elements of `self`.

        Args:
            n (int): numbers of elements to skip. Should be non-negative.

        Returns:
            New `Lazy` with `n` first elements of `self` skipped.

        Examples:
            >>> QList(range(10)).skip(2).collect()
            [2, 3, 4, 5, 6, 7, 8, 9]
        """
        def inner():
            for i, elem in enumerate(self):
                if i >= n:
                    yield elem
        return Lazy(inner())

    def take(self, n: int) -> Lazy[T]:
        """
        Takes `n` first elements of `self`.
        Args:
            n (int): numbers of elements to take. Should be non-negative.

        Returns:
            New `Lazy` with only `n` first elements from `self`.

        Examples:
            >>> QList(range(10)).take(2).collect()
            [0, 1]
        """
        def inner():
            for i, elem in enumerate(self):
                if i >= n:
                    return None
                yield elem
        return Lazy(inner())

    def flatten(self) -> Lazy[T]:
        """
        If `self` is a `QList` object of `Iterable[T]`, flatten concatenates all iterables into a
        single list and returns a `Lazy[T]` object.

        Returns:
            Concatenation of all elements from `self`.

        Raises:
            TypeError: when elements of Lazy are not iterables.

        Examples:
            >>> QList([[1, 2], [3, 4]]).flatten().collect()
            [1, 2, 3, 4]
        """
        def inner():
            for elem in self:
                if not isinstance(elem, Iterable):
                    type_name = type(elem).__name__
                    raise TypeError(f'could not flatten {self.__class__.__name__}[{type_name}] because {type_name} is not iterable.')
                yield from elem
        return Lazy(inner())

    def cycle(self) -> Lazy[T]:
        """
        Returns a `Lazy[T]` that cycles through the elements of `self`, which means
        on achieving the last element the iteration starts from the beginning. The
        returned `Lazy` object has no end (infinite iterator) unless `self` is empty
        in which case cycle returns an empty `Lazy` object (empty iterator).

        Returns:
            Infinite `Lazy` that loops through elements of `self`, or empty iterator if `self` is emtpy.

        Examples:
            >>> QList([1, 2, 3]).cycle().take(7).collect()
            [1, 2, 3, 1, 2, 3, 1]
        """
        def inner():
            saved = []
            for elem in self:
                saved.append(elem)
                yield elem
            while saved:
                for elem in saved:
                    yield elem
        return Lazy(inner())

    def enumerate(self, start: int = 0) -> Lazy[tuple[int, T]]:
        """
        Returns a `Lazy` object with index-value pairs as its elements. Index starts at
        the given position `start` (defaults to 0).

        Args:
            start (int): starting index. Defaults to 0.

        Returns:
            New `Lazy` with pairs of index and value.

        Examples:
            >>> QList(['a', 'b', 'c']).enumerate().collect()
            [(0, 'a'), (1, 'b'), (2, 'c')]
        """
        def inner():
            for i, elem in enumerate(self, start=start):
                yield i, elem
        return Lazy(inner())

    def batch(self, size: int) -> Lazy["QList[T]"]:
        """
        Groups elements into batches of given `size`. The last batch may have fewer elements.

        Args:
            size (int): size of one batch.

        Returns:
            New `Lazy` of batches (`QList`) of given `size`. Last batch may have fewer elements.

        Examples:
            >>> QList(range(5)).batch(2).collect()
            [[0, 1], [2, 3], [4]]
        """
        assert size > 0, f'batch size must be greater then 0 but got {size}'
        def inner():
            for i in range(0, self.len(), size):
                yield QList(self[i:i+size])
        return Lazy(inner())

    def batch_by(self, grouper: Callable[[T], SupportsEq]) -> "Lazy[QList[T]]":
        """
        Batches elements of `self` based on the output of the grouper function. Elements are thrown
        to the same group as long as the grouper function returns the same key (keys must support equality checks).
        When a new key is returned a new batch (group) is created.

        Args:
            grouper (Callable[[T], SupportsEq]): `function: (T) -> SupportsEq` that provides the keys
             used to group elements, where the key type must support equality comparisons.

        Returns:
            New `Lazy[QList[T]]` with elements batched based on the `grouper` key.

        Examples:
            >>> QList(['a1', 'b1', 'b2', 'a2', 'a3', 'b3']).batch_by(lambda s: s[0]).collect()
            [['a1'], ['b1', 'b2'], ['a2', 'a3'], ['b3']]
            >>> QList(['a1', 'b1', 'b2', 'a2', 'a3', 'b3']).batch_by(lambda s: s[1]).collect()
            [['a1', 'b1'], ['b2', 'a2'], ['a3', 'b3']]
        """
        def inner():
            if self.len() == 0:
                return
            batch = QList([self[0]])
            key = grouper(self[0])
            for elem in self[1:]:
                new_key = grouper(elem)
                if new_key == key:
                    batch.append(elem)
                else:
                    yield batch
                    batch = QList([elem])
                    key = new_key
            if batch:
                yield batch
        return Lazy(inner())

    def chain(self, other: Iterable[T]) -> Lazy[T]:
        """
        Chains `self` with `other`, returning a new `Lazy[T]` with all elements from both iterables.

        Args:
            other (Iterable[T]):  an iterable of elements to be "attached" after `self` is exhausted.

        Returns:
            New `Lazy` with elements from `self` and `other`.

        Examples:
            >>> QList(range(0, 3)).chain(range(3, 6)).collect()
            [0, 1, 2, 3, 4, 5]
        """
        def inner():
            yield from self
            yield from other
        return Lazy(inner())

    def merge(self, other: Iterable[T], merger: Callable[[T, T], bool]) -> Lazy[T]:
        """
        Merges `self` with `other`, maintaining the order of elements based on the merger function. It starts by
         taking the first elements from `self` and `other`, calling the merger function with these elements as arguments.
         If the output is True, the first element is yielded; otherwise, the second element is yielded. If `self` is
         empty, the remaining elements from `other` are yielded, and vice versa.

        Args:
            other (Iterable[T]): an iterable to be merged with `self`.
            merger (Callable[[T, T], bool]): `function: (T, T) -> bool` that takes two arguments (left and right).
             If the output is True, the left argument is yielded; otherwise, the right argument is yielded.

        Returns:
            New `Lazy` containing the merged elements.

        Examples:
            >>> QList([1, 3, 5]).merge([2, 4, 6], lambda left, right: left < right).collect()
            [1, 2, 3, 4, 5, 6]
        """
        it1 = iter(self)
        it2 = iter(other)

        try:
            elem1 = next(it1)
        except StopIteration:
            return Lazy(it2)
        try:
            elem2 = next(it2)
        except StopIteration:
            return Lazy([elem1]).chain(it1)

        def inner():
            left = elem1
            right = elem2
            while True:
                if merger(left, right):
                    yield left
                    try:
                        left = next(it1)
                    except StopIteration:
                        yield right
                        yield from it2
                        return
                else:
                    yield right
                    try:
                        right = next(it2)
                    except StopIteration:
                        yield left
                        yield from it1
                        return
        return Lazy(inner())

    def all(self, mapper: Optional[Callable[[T], Booly]] = None) -> bool:
        """
        Goes through the entire generator and checks if all elements are `Truthy`.
        `Booly` is a type that evaluates to something that is either `True` (`Truthy`) or `False` (`Falsy`).
        For example in Python an empty list evaluates to `False` (empty list is `Falsy`).

        Args:
            mapper (Optional[Callable[[T], Booly]]): `function: (T) -> Booly` that maps `T` to `Booly` which is a type that
             can be interpreted as either True or False. If not passed, identity function is used.

        Returns:
            `True` if all elements of `self` are `Truthy`. `False` otherwise.
        """
        def identity(x):
            return x
        mapper = identity if mapper is None else mapper
        for elem in self:
            if not mapper(elem):
                return False
        return True

    def any(self, mapper: Optional[Callable[[T], Booly]] = None) -> bool:
        """
        Goes through the entire generator and checks if any element is `Truthy`.
        `Booly` is a type that evaluates to something that is either `True` (`Truthy`) or `False` (`Falsy`).
        For example in Python an empty list evaluates to `False` (empty list is `Falsy`).

        Args:
            mapper (Optional[Callable[[T], Booly]]): `function: (T) -> Booly` that maps `T` to `Booly` which is a type that
             can be interpreted as either True or False. If not passed, identity function is used.

        Returns:
            `True` if there is at least one element in `self` that is `Truthy`. `False` otherwise.
        """
        def identity(x):
            return x

        mapper = identity if mapper is None else mapper
        for elem in self:
            if mapper(elem):
                return True
        return False

    def min(self, key: Optional[Callable[[T], SupportsLessThan]] = None) -> Optional[T]:
        """
        Returns the smallest element from `self`. If the key function is not passed, identity
        function is used in which case `T` must support `LessThan` operator.

        Args:
            key (Optional[Callable[[T], SupportsLessThan]): `function: (T) -> SupportsLessThan` that represents
             the relation of partial order between elements.

        Returns:
            The smallest element from `self` or `None` if `self` is empty.
        """
        def identity(x):
            return x
        key = identity if key is None else key

        if self.len() == 0:
            return None
        best = self[0]
        for elem in self[1:]:
            if key(elem) < key(best):
                best = elem
        return best

    def max(self, key: Optional[Callable[[T], SupportsLessThan]] = None) -> Optional[T]:
        """
        Returns the biggest element from `self`. If the key function is not passed, identity
        function is used in which case `T` must support `LessThan` operator.

        Args:
            key (Optional[Callable[[T], SupportsLessThan]): `function: (T) -> SupportsLessThan` that represents
             the relation of partial order between elements.

        Returns:
            the biggest element from `self` or `None` if `self` is empty.
        """

        def identity(x):
            return x
        key = identity if key is None else key

        if self.len() == 0:
            return None
        best = self[0]
        for elem in self[1:]:
            if key(best) < key(elem):
                best = elem
        return best

    def full_flatten(self, break_str: bool = True, preserve_type: Optional[Type] = None) -> Lazy[T]:
        """
        When `self` is an iterable of nested iterables, all the iterables are flattened to a single iterable.
        Recursive type annotation of `self` may be imagined to look like this: `QList[T | Iterable[T | Iterable[T | ...]]].`


        Args:
            break_str (bool): If `True`, strings are flattened into individual characters. Defaults to `True`.
            preserve_type (Optional[Type]): Type to exclude from flattening (i.e., treated as non-iterable). For example,
             setting this to `str` makes `break_str` effectively `False`. Defaults to `None`.

        Returns:
            New `Lazy` with all nested iterables flattened to a single iterable.

        Examples:
            >>> QList(['abc', ['def', 'ghi']]).full_flatten().collect()
            ['a', 'b', 'c', 'd', 'e', 'f', 'g', 'h', 'i']

            >>> QList(['abc', ['def', 'ghi']]).full_flatten(break_str=False).collect()
            ['abc', 'def', 'ghi']

            >>> QList(['abc', ['def', 'ghi']]).full_flatten(preserve_type=list).collect()
            ['a', 'b', 'c', ['def', 'ghi']]
        """

        def inner():
            for elem in self:
                if preserve_type is not None and isinstance(elem, preserve_type):
                    yield elem
                elif isinstance(elem, str):
                    if break_str:
                        if len(elem) == 1:
                            yield elem
                        else:
                            yield from Lazy(elem).full_flatten(break_str=break_str, preserve_type=preserve_type)
                    else:
                        yield elem
                elif isinstance(elem, Iterable):
                    yield from Lazy(elem).full_flatten(break_str=break_str, preserve_type=preserve_type)
                else:
                    yield elem
        return Lazy(inner())

    def take_while(self, pred: Callable[[T], bool]) -> "Lazy[T]":
        """
        Creates a `Lazy` that yields elements based on a predicate. Takes a function as an argument.
        It will call this function on each element of `self`, and yield elements while the function
        returns `True`. After `False` is returned, iteration stops, and the rest of the elements is ignored.

        Args:
            pred (Callable[[T], bool]): `function: (T) -> bool`

        Returns:
            New `Lazy` containing elements from the original sequence, stopping at the first element for which the
             predicate returns `False`.
        """
        def inner():
            for elem in self:
                if not pred(elem):
                    return
                yield elem
        return Lazy(inner())

    def sum(self) -> Optional[SupportsAdd]:
        """
        Sums all the elements and returns the sum. Returns `None` if `self` is empty.
        Elements of `self` must support addition.

        Returns:
            The sum of all elements of `self`.
        """
        it = self.iter()
        acc = None
        try:
            acc = next(it)
        except StopIteration:
            return acc
        for elem in it:
            acc = acc + elem
        return acc

    def window(self, window_size: int) -> "Lazy[QList[T]]":
        """
        Creates a `Lazy` of sliding windows of size `window_size`. If `window_size`
        is greater than the total length of `self` an empty iterator is returned.

        Args:
            window_size (int): the size of the sliding window. Must be greater than 0.

        Returns:
            New `Lazy` of all sliding windows.
        """
        assert window_size > 0, f'window size must be greater than 0 but got {window_size}.'
        def inner(n: int):
            if self.len() < n:
                return
            if self.len() == n:
                yield self
                return
            window = deque(maxlen=n)
            for elem in self[:n]:
                window.append(elem)
            yield QList(window)
            for elem in self[n:]:
                window.append(elem)
                yield QList(window)
        return Lazy(inner(n=window_size))

all(mapper=None)

Goes through the entire generator and checks if all elements are Truthy. Booly is a type that evaluates to something that is either True (Truthy) or False (Falsy). For example in Python an empty list evaluates to False (empty list is Falsy).

Parameters:

Name Type Description Default
mapper Optional[Callable[[T], Booly]]

function: (T) -> Booly that maps T to Booly which is a type that can be interpreted as either True or False. If not passed, identity function is used.

None

Returns:

Type Description
bool

True if all elements of self are Truthy. False otherwise.

Source code in src\qwlist\qwlist.py
1156
1157
1158
1159
1160
1161
1162
1163
1164
1165
1166
1167
1168
1169
1170
1171
1172
1173
1174
1175
def all(self, mapper: Optional[Callable[[T], Booly]] = None) -> bool:
    """
    Goes through the entire generator and checks if all elements are `Truthy`.
    `Booly` is a type that evaluates to something that is either `True` (`Truthy`) or `False` (`Falsy`).
    For example in Python an empty list evaluates to `False` (empty list is `Falsy`).

    Args:
        mapper (Optional[Callable[[T], Booly]]): `function: (T) -> Booly` that maps `T` to `Booly` which is a type that
         can be interpreted as either True or False. If not passed, identity function is used.

    Returns:
        `True` if all elements of `self` are `Truthy`. `False` otherwise.
    """
    def identity(x):
        return x
    mapper = identity if mapper is None else mapper
    for elem in self:
        if not mapper(elem):
            return False
    return True

any(mapper=None)

Goes through the entire generator and checks if any element is Truthy. Booly is a type that evaluates to something that is either True (Truthy) or False (Falsy). For example in Python an empty list evaluates to False (empty list is Falsy).

Parameters:

Name Type Description Default
mapper Optional[Callable[[T], Booly]]

function: (T) -> Booly that maps T to Booly which is a type that can be interpreted as either True or False. If not passed, identity function is used.

None

Returns:

Type Description
bool

True if there is at least one element in self that is Truthy. False otherwise.

Source code in src\qwlist\qwlist.py
1177
1178
1179
1180
1181
1182
1183
1184
1185
1186
1187
1188
1189
1190
1191
1192
1193
1194
1195
1196
1197
def any(self, mapper: Optional[Callable[[T], Booly]] = None) -> bool:
    """
    Goes through the entire generator and checks if any element is `Truthy`.
    `Booly` is a type that evaluates to something that is either `True` (`Truthy`) or `False` (`Falsy`).
    For example in Python an empty list evaluates to `False` (empty list is `Falsy`).

    Args:
        mapper (Optional[Callable[[T], Booly]]): `function: (T) -> Booly` that maps `T` to `Booly` which is a type that
         can be interpreted as either True or False. If not passed, identity function is used.

    Returns:
        `True` if there is at least one element in `self` that is `Truthy`. `False` otherwise.
    """
    def identity(x):
        return x

    mapper = identity if mapper is None else mapper
    for elem in self:
        if mapper(elem):
            return True
    return False

batch(size)

Groups elements into batches of given size. The last batch may have fewer elements.

Parameters:

Name Type Description Default
size int

size of one batch.

required

Returns:

Type Description
Lazy[QList[T]]

New Lazy of batches (QList) of given size. Last batch may have fewer elements.

Examples:

>>> QList(range(5)).batch(2).collect()
[[0, 1], [2, 3], [4]]
Source code in src\qwlist\qwlist.py
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
def batch(self, size: int) -> Lazy["QList[T]"]:
    """
    Groups elements into batches of given `size`. The last batch may have fewer elements.

    Args:
        size (int): size of one batch.

    Returns:
        New `Lazy` of batches (`QList`) of given `size`. Last batch may have fewer elements.

    Examples:
        >>> QList(range(5)).batch(2).collect()
        [[0, 1], [2, 3], [4]]
    """
    assert size > 0, f'batch size must be greater then 0 but got {size}'
    def inner():
        for i in range(0, self.len(), size):
            yield QList(self[i:i+size])
    return Lazy(inner())

batch_by(grouper)

Batches elements of self based on the output of the grouper function. Elements are thrown to the same group as long as the grouper function returns the same key (keys must support equality checks). When a new key is returned a new batch (group) is created.

Parameters:

Name Type Description Default
grouper Callable[[T], SupportsEq]

function: (T) -> SupportsEq that provides the keys used to group elements, where the key type must support equality comparisons.

required

Returns:

Type Description
Lazy[QList[T]]

New Lazy[QList[T]] with elements batched based on the grouper key.

Examples:

>>> QList(['a1', 'b1', 'b2', 'a2', 'a3', 'b3']).batch_by(lambda s: s[0]).collect()
[['a1'], ['b1', 'b2'], ['a2', 'a3'], ['b3']]
>>> QList(['a1', 'b1', 'b2', 'a2', 'a3', 'b3']).batch_by(lambda s: s[1]).collect()
[['a1', 'b1'], ['b2', 'a2'], ['a3', 'b3']]
Source code in src\qwlist\qwlist.py
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
def batch_by(self, grouper: Callable[[T], SupportsEq]) -> "Lazy[QList[T]]":
    """
    Batches elements of `self` based on the output of the grouper function. Elements are thrown
    to the same group as long as the grouper function returns the same key (keys must support equality checks).
    When a new key is returned a new batch (group) is created.

    Args:
        grouper (Callable[[T], SupportsEq]): `function: (T) -> SupportsEq` that provides the keys
         used to group elements, where the key type must support equality comparisons.

    Returns:
        New `Lazy[QList[T]]` with elements batched based on the `grouper` key.

    Examples:
        >>> QList(['a1', 'b1', 'b2', 'a2', 'a3', 'b3']).batch_by(lambda s: s[0]).collect()
        [['a1'], ['b1', 'b2'], ['a2', 'a3'], ['b3']]
        >>> QList(['a1', 'b1', 'b2', 'a2', 'a3', 'b3']).batch_by(lambda s: s[1]).collect()
        [['a1', 'b1'], ['b2', 'a2'], ['a3', 'b3']]
    """
    def inner():
        if self.len() == 0:
            return
        batch = QList([self[0]])
        key = grouper(self[0])
        for elem in self[1:]:
            new_key = grouper(elem)
            if new_key == key:
                batch.append(elem)
            else:
                yield batch
                batch = QList([elem])
                key = new_key
        if batch:
            yield batch
    return Lazy(inner())

chain(other)

Chains self with other, returning a new Lazy[T] with all elements from both iterables.

Parameters:

Name Type Description Default
other Iterable[T]

an iterable of elements to be "attached" after self is exhausted.

required

Returns:

Type Description
Lazy[T]

New Lazy with elements from self and other.

Examples:

>>> QList(range(0, 3)).chain(range(3, 6)).collect()
[0, 1, 2, 3, 4, 5]
Source code in src\qwlist\qwlist.py
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
def chain(self, other: Iterable[T]) -> Lazy[T]:
    """
    Chains `self` with `other`, returning a new `Lazy[T]` with all elements from both iterables.

    Args:
        other (Iterable[T]):  an iterable of elements to be "attached" after `self` is exhausted.

    Returns:
        New `Lazy` with elements from `self` and `other`.

    Examples:
        >>> QList(range(0, 3)).chain(range(3, 6)).collect()
        [0, 1, 2, 3, 4, 5]
    """
    def inner():
        yield from self
        yield from other
    return Lazy(inner())

cycle()

Returns a Lazy[T] that cycles through the elements of self, which means on achieving the last element the iteration starts from the beginning. The returned Lazy object has no end (infinite iterator) unless self is empty in which case cycle returns an empty Lazy object (empty iterator).

Returns:

Type Description
Lazy[T]

Infinite Lazy that loops through elements of self, or empty iterator if self is emtpy.

Examples:

>>> QList([1, 2, 3]).cycle().take(7).collect()
[1, 2, 3, 1, 2, 3, 1]
Source code in src\qwlist\qwlist.py
 984
 985
 986
 987
 988
 989
 990
 991
 992
 993
 994
 995
 996
 997
 998
 999
1000
1001
1002
1003
1004
1005
1006
def cycle(self) -> Lazy[T]:
    """
    Returns a `Lazy[T]` that cycles through the elements of `self`, which means
    on achieving the last element the iteration starts from the beginning. The
    returned `Lazy` object has no end (infinite iterator) unless `self` is empty
    in which case cycle returns an empty `Lazy` object (empty iterator).

    Returns:
        Infinite `Lazy` that loops through elements of `self`, or empty iterator if `self` is emtpy.

    Examples:
        >>> QList([1, 2, 3]).cycle().take(7).collect()
        [1, 2, 3, 1, 2, 3, 1]
    """
    def inner():
        saved = []
        for elem in self:
            saved.append(elem)
            yield elem
        while saved:
            for elem in saved:
                yield elem
    return Lazy(inner())

eager()

Changes QList into EagerQList.

Returns:

Type Description
EagerQList[T]

Eagerly evaluated version of QList.

Source code in src\qwlist\qwlist.py
722
723
724
725
726
727
728
729
730
def eager(self) -> "EagerQList[T]":
    """
    Changes `QList` into `EagerQList`.

    Returns:
        Eagerly evaluated version of `QList`.
    """
    from .eager import EagerQList
    return EagerQList(self)

enumerate(start=0)

Returns a Lazy object with index-value pairs as its elements. Index starts at the given position start (defaults to 0).

Parameters:

Name Type Description Default
start int

starting index. Defaults to 0.

0

Returns:

Type Description
Lazy[tuple[int, T]]

New Lazy with pairs of index and value.

Examples:

>>> QList(['a', 'b', 'c']).enumerate().collect()
[(0, 'a'), (1, 'b'), (2, 'c')]
Source code in src\qwlist\qwlist.py
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
def enumerate(self, start: int = 0) -> Lazy[tuple[int, T]]:
    """
    Returns a `Lazy` object with index-value pairs as its elements. Index starts at
    the given position `start` (defaults to 0).

    Args:
        start (int): starting index. Defaults to 0.

    Returns:
        New `Lazy` with pairs of index and value.

    Examples:
        >>> QList(['a', 'b', 'c']).enumerate().collect()
        [(0, 'a'), (1, 'b'), (2, 'c')]
    """
    def inner():
        for i, elem in enumerate(self, start=start):
            yield i, elem
    return Lazy(inner())

filter(pred)

Returns a Lazy object containing all values from self for which the predicate holds true.

Parameters:

Name Type Description Default
pred Callable[[T], bool]

function: (T) -> bool

required

Returns:

Type Description
Lazy[T]

New Lazy[T] with elements for which the predicate holds true.

Examples:

>>> QList([0, 1, 2, 3]).filter(lambda x: x < 2).collect()
[0, 1]
Source code in src\qwlist\qwlist.py
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
def filter(self, pred: Callable[[T], bool]) -> Lazy[T]:
    """
    Returns a `Lazy` object containing all values from `self` for which
    the predicate holds true.

    Args:
        pred: `function: (T) -> bool`

    Returns:
        New `Lazy[T]` with elements for which the predicate holds true.

    Examples:
        >>> QList([0, 1, 2, 3]).filter(lambda x: x < 2).collect()
        [0, 1]
    """
    def inner():
        for elem in self:
            if pred(elem):
                yield elem
    return Lazy(inner())

flatmap(mapper)

Applies the mapper function to each of the yielded elements and flattens the results.

Parameters:

Name Type Description Default
mapper Callable[[T], Iterable[K]]

function: (T) -> Iterable[K].

required

Returns:

Type Description
Lazy[K]

New Lazy with elements from self mapped to an iterable and then flattened.

Examples:

>>> QList([1, 2]).flatmap(lambda x: [x, x]).qlist()
[1, 1, 2, 2]
Source code in src\qwlist\qwlist.py
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
def flatmap(self, mapper: Callable[[T], Iterable[K]]) -> Lazy[K]:
    """
    Applies the mapper function to each of the yielded elements and flattens the results.

    Args:
        mapper: `function: (T) -> Iterable[K]`.

    Returns:
        New `Lazy` with elements from `self` mapped to an iterable and then flattened.

    Examples:
        >>> QList([1, 2]).flatmap(lambda x: [x, x]).qlist()
        [1, 1, 2, 2]
    """
    def inner():
        for elem in self:
            yield from mapper(elem)
    return Lazy(inner())

flatten()

If self is a QList object of Iterable[T], flatten concatenates all iterables into a single list and returns a Lazy[T] object.

Returns:

Type Description
Lazy[T]

Concatenation of all elements from self.

Raises:

Type Description
TypeError

when elements of Lazy are not iterables.

Examples:

>>> QList([[1, 2], [3, 4]]).flatten().collect()
[1, 2, 3, 4]
Source code in src\qwlist\qwlist.py
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
def flatten(self) -> Lazy[T]:
    """
    If `self` is a `QList` object of `Iterable[T]`, flatten concatenates all iterables into a
    single list and returns a `Lazy[T]` object.

    Returns:
        Concatenation of all elements from `self`.

    Raises:
        TypeError: when elements of Lazy are not iterables.

    Examples:
        >>> QList([[1, 2], [3, 4]]).flatten().collect()
        [1, 2, 3, 4]
    """
    def inner():
        for elem in self:
            if not isinstance(elem, Iterable):
                type_name = type(elem).__name__
                raise TypeError(f'could not flatten {self.__class__.__name__}[{type_name}] because {type_name} is not iterable.')
            yield from elem
    return Lazy(inner())

fold(operation, init)

Given the combination operator reduces self by processing its constituent parts, building up the final value.

Other names: fold_left, reduce, accumulate, aggregate.

Parameters:

Name Type Description Default
operation Callable[[K, T], K]

function: (K, T) -> K. Given the initial value init applies the given combination operator on each element yielded by self, treating the result as the first argument in the next step.

required
init K

initial value for the combination operator.

required

Returns:

Type Description
K

The final value created from calling the operation on consecutive elements of self.

Examples:

>>> QList([1, 2, 3]).fold(lambda acc, x: acc + x, 0)
6
Source code in src\qwlist\qwlist.py
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
def fold(self, operation: Callable[[K, T], K], init: K) -> K:
    """
    Given the combination operator reduces `self` by processing
    its constituent parts, building up the final value.

    **Other names:** fold_left, reduce, accumulate, aggregate.

    Args:
        operation: `function: (K, T) -> K`. Given the initial value `init` applies the
            given combination operator on each element yielded by `self`,
            treating the result as the first argument in the next step.
        init (K): initial value for the combination operator.

    Returns:
        The final value created from calling the `operation` on consecutive elements of `self`.

    Examples:
        >>> QList([1, 2, 3]).fold(lambda acc, x: acc + x, 0)
        6
    """
    acc = init
    for elem in self:
        acc = operation(acc, elem)
    return acc

fold_right(operation, init)

Given the combination operator reduces self by processing its constituent parts, building up the final value.

Parameters:

Name Type Description Default
operation Callable[[K, T], K]

function: (K, T) -> K Given the initial value init applies the given combination operator on each element of self, starting from the last element, treating the result as a first argument in the next step.

required
init K

initial value for the combination operator.

required

Returns:

Type Description
K

The final value created from calling the operation on consecutive elements of self starting from the last element.

Examples:

>>> QList([1, 2, 3]).fold_right(lambda acc, x: acc + x, 0)
6
Source code in src\qwlist\qwlist.py
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
def fold_right(self, operation: Callable[[K, T], K], init: K) -> K:
    """
    Given the combination operator reduces `self` by processing
    its constituent parts, building up the final value.

    Args:
        operation: `function: (K, T) -> K`
            Given the initial value `init` applies the
            given combination operator on each element of `self`, starting from the
            last element, treating the result as a first argument in the next step.
        init: initial value for the combination operator.

    Returns:
        The final value created from calling the `operation` on consecutive elements of `self`
         starting from the last element.

    Examples:
        >>> QList([1, 2, 3]).fold_right(lambda acc, x: acc + x, 0)
        6
    """
    acc = init
    for elem in self[::-1]:
        acc = operation(acc, elem)
    return acc

foreach(action)

Applies the given function to each of the QList elements.

Parameters:

Name Type Description Default
action Callable[[T], None]

function: (T) -> None

required

Returns:

Type Description

None

Source code in src\qwlist\qwlist.py
769
770
771
772
773
774
775
776
777
778
779
780
def foreach(self, action: Callable[[T], None]):
    """
    Applies the given function to each of the `QList` elements.

    Args:
        action: `function: (T) -> None`

    Returns:
        `None`
    """
    for elem in self:
        action(elem)

full_flatten(break_str=True, preserve_type=None)

When self is an iterable of nested iterables, all the iterables are flattened to a single iterable. Recursive type annotation of self may be imagined to look like this: QList[T | Iterable[T | Iterable[T | ...]]].

Parameters:

Name Type Description Default
break_str bool

If True, strings are flattened into individual characters. Defaults to True.

True
preserve_type Optional[Type]

Type to exclude from flattening (i.e., treated as non-iterable). For example, setting this to str makes break_str effectively False. Defaults to None.

None

Returns:

Type Description
Lazy[T]

New Lazy with all nested iterables flattened to a single iterable.

Examples:

>>> QList(['abc', ['def', 'ghi']]).full_flatten().collect()
['a', 'b', 'c', 'd', 'e', 'f', 'g', 'h', 'i']
>>> QList(['abc', ['def', 'ghi']]).full_flatten(break_str=False).collect()
['abc', 'def', 'ghi']
>>> QList(['abc', ['def', 'ghi']]).full_flatten(preserve_type=list).collect()
['a', 'b', 'c', ['def', 'ghi']]
Source code in src\qwlist\qwlist.py
1248
1249
1250
1251
1252
1253
1254
1255
1256
1257
1258
1259
1260
1261
1262
1263
1264
1265
1266
1267
1268
1269
1270
1271
1272
1273
1274
1275
1276
1277
1278
1279
1280
1281
1282
1283
1284
1285
1286
1287
1288
1289
def full_flatten(self, break_str: bool = True, preserve_type: Optional[Type] = None) -> Lazy[T]:
    """
    When `self` is an iterable of nested iterables, all the iterables are flattened to a single iterable.
    Recursive type annotation of `self` may be imagined to look like this: `QList[T | Iterable[T | Iterable[T | ...]]].`


    Args:
        break_str (bool): If `True`, strings are flattened into individual characters. Defaults to `True`.
        preserve_type (Optional[Type]): Type to exclude from flattening (i.e., treated as non-iterable). For example,
         setting this to `str` makes `break_str` effectively `False`. Defaults to `None`.

    Returns:
        New `Lazy` with all nested iterables flattened to a single iterable.

    Examples:
        >>> QList(['abc', ['def', 'ghi']]).full_flatten().collect()
        ['a', 'b', 'c', 'd', 'e', 'f', 'g', 'h', 'i']

        >>> QList(['abc', ['def', 'ghi']]).full_flatten(break_str=False).collect()
        ['abc', 'def', 'ghi']

        >>> QList(['abc', ['def', 'ghi']]).full_flatten(preserve_type=list).collect()
        ['a', 'b', 'c', ['def', 'ghi']]
    """

    def inner():
        for elem in self:
            if preserve_type is not None and isinstance(elem, preserve_type):
                yield elem
            elif isinstance(elem, str):
                if break_str:
                    if len(elem) == 1:
                        yield elem
                    else:
                        yield from Lazy(elem).full_flatten(break_str=break_str, preserve_type=preserve_type)
                else:
                    yield elem
            elif isinstance(elem, Iterable):
                yield from Lazy(elem).full_flatten(break_str=break_str, preserve_type=preserve_type)
            else:
                yield elem
    return Lazy(inner())

iter()

Changes self into Iterator[T] by calling the iter() function.

Returns:

Type Description
Iterator[T]

iterator over the elements of self.

Source code in src\qwlist\qwlist.py
687
688
689
690
691
692
693
694
def iter(self) -> Iterator[T]:
    """
    Changes `self` into `Iterator[T]` by calling the `iter()` function.

    Returns:
        iterator over the elements of `self`.
    """
    return iter(self)

len()

Returns the length of self.

(time complexity: O(1))

Returns:

Type Description
int

Length of the QList

Source code in src\qwlist\qwlist.py
857
858
859
860
861
862
863
864
865
866
def len(self) -> int:
    """
    Returns the length of `self`.

    (time complexity: `O(1)`)

    Returns:
        Length of the `QList`
    """
    return len(self)

list()

Changes QList into standard Python list.

Returns:

Type Description
List[T]

Standard Python list.

Source code in src\qwlist\qwlist.py
713
714
715
716
717
718
719
720
def list(self) -> List[T]:
    """
    Changes `QList` into standard Python `list`.

    Returns:
        Standard Python `list`.
    """
    return list(self)

map(mapper)

Returns a Lazy object containing all values from self with the mapping function applied on them.

Parameters:

Name Type Description Default
mapper Callable[[T], K]

function: (T) -> K

required

Returns:

Type Description
Lazy[K]

New Lazy[K] with mapped elements from self.

Source code in src\qwlist\qwlist.py
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
def map(self, mapper: Callable[[T], K]) -> Lazy[K]:
    """
    Returns a `Lazy` object containing all values from `self` with
    the mapping function applied on them.

    Args:
        mapper: `function: (T) -> K`

    Returns:
        New `Lazy[K]` with mapped elements from `self`.
    """
    def inner():
        for elem in self:
            yield mapper(elem)
    return Lazy(inner())

max(key=None)

Returns the biggest element from self. If the key function is not passed, identity function is used in which case T must support LessThan operator.

Parameters:

Name Type Description Default
key Optional[Callable[[T], SupportsLessThan]

function: (T) -> SupportsLessThan that represents the relation of partial order between elements.

None

Returns:

Type Description
Optional[T]

the biggest element from self or None if self is empty.

Source code in src\qwlist\qwlist.py
1223
1224
1225
1226
1227
1228
1229
1230
1231
1232
1233
1234
1235
1236
1237
1238
1239
1240
1241
1242
1243
1244
1245
1246
def max(self, key: Optional[Callable[[T], SupportsLessThan]] = None) -> Optional[T]:
    """
    Returns the biggest element from `self`. If the key function is not passed, identity
    function is used in which case `T` must support `LessThan` operator.

    Args:
        key (Optional[Callable[[T], SupportsLessThan]): `function: (T) -> SupportsLessThan` that represents
         the relation of partial order between elements.

    Returns:
        the biggest element from `self` or `None` if `self` is empty.
    """

    def identity(x):
        return x
    key = identity if key is None else key

    if self.len() == 0:
        return None
    best = self[0]
    for elem in self[1:]:
        if key(best) < key(elem):
            best = elem
    return best

merge(other, merger)

Merges self with other, maintaining the order of elements based on the merger function. It starts by taking the first elements from self and other, calling the merger function with these elements as arguments. If the output is True, the first element is yielded; otherwise, the second element is yielded. If self is empty, the remaining elements from other are yielded, and vice versa.

Parameters:

Name Type Description Default
other Iterable[T]

an iterable to be merged with self.

required
merger Callable[[T, T], bool]

function: (T, T) -> bool that takes two arguments (left and right). If the output is True, the left argument is yielded; otherwise, the right argument is yielded.

required

Returns:

Type Description
Lazy[T]

New Lazy containing the merged elements.

Examples:

>>> QList([1, 3, 5]).merge([2, 4, 6], lambda left, right: left < right).collect()
[1, 2, 3, 4, 5, 6]
Source code in src\qwlist\qwlist.py
1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
1137
1138
1139
1140
1141
1142
1143
1144
1145
1146
1147
1148
1149
1150
1151
1152
1153
1154
def merge(self, other: Iterable[T], merger: Callable[[T, T], bool]) -> Lazy[T]:
    """
    Merges `self` with `other`, maintaining the order of elements based on the merger function. It starts by
     taking the first elements from `self` and `other`, calling the merger function with these elements as arguments.
     If the output is True, the first element is yielded; otherwise, the second element is yielded. If `self` is
     empty, the remaining elements from `other` are yielded, and vice versa.

    Args:
        other (Iterable[T]): an iterable to be merged with `self`.
        merger (Callable[[T, T], bool]): `function: (T, T) -> bool` that takes two arguments (left and right).
         If the output is True, the left argument is yielded; otherwise, the right argument is yielded.

    Returns:
        New `Lazy` containing the merged elements.

    Examples:
        >>> QList([1, 3, 5]).merge([2, 4, 6], lambda left, right: left < right).collect()
        [1, 2, 3, 4, 5, 6]
    """
    it1 = iter(self)
    it2 = iter(other)

    try:
        elem1 = next(it1)
    except StopIteration:
        return Lazy(it2)
    try:
        elem2 = next(it2)
    except StopIteration:
        return Lazy([elem1]).chain(it1)

    def inner():
        left = elem1
        right = elem2
        while True:
            if merger(left, right):
                yield left
                try:
                    left = next(it1)
                except StopIteration:
                    yield right
                    yield from it2
                    return
            else:
                yield right
                try:
                    right = next(it2)
                except StopIteration:
                    yield left
                    yield from it1
                    return
    return Lazy(inner())

min(key=None)

Returns the smallest element from self. If the key function is not passed, identity function is used in which case T must support LessThan operator.

Parameters:

Name Type Description Default
key Optional[Callable[[T], SupportsLessThan]

function: (T) -> SupportsLessThan that represents the relation of partial order between elements.

None

Returns:

Type Description
Optional[T]

The smallest element from self or None if self is empty.

Source code in src\qwlist\qwlist.py
1199
1200
1201
1202
1203
1204
1205
1206
1207
1208
1209
1210
1211
1212
1213
1214
1215
1216
1217
1218
1219
1220
1221
def min(self, key: Optional[Callable[[T], SupportsLessThan]] = None) -> Optional[T]:
    """
    Returns the smallest element from `self`. If the key function is not passed, identity
    function is used in which case `T` must support `LessThan` operator.

    Args:
        key (Optional[Callable[[T], SupportsLessThan]): `function: (T) -> SupportsLessThan` that represents
         the relation of partial order between elements.

    Returns:
        The smallest element from `self` or `None` if `self` is empty.
    """
    def identity(x):
        return x
    key = identity if key is None else key

    if self.len() == 0:
        return None
    best = self[0]
    for elem in self[1:]:
        if key(elem) < key(best):
            best = elem
    return best

scan(operation, state)

Given the combination operator creates a Lazy[K] object by processing constituent parts of self, yielding intermediate steps and building up the final value. Scan is similar to fold but returns all intermediate states instead of just the final result.

Parameters:

Name Type Description Default
operation Callable[[K, T], K]

function: (K, T) -> K. Given the initial state applies the given combination operator on each element yielded by the Lazy object, yielding the result and then treating it as the first argument in the next step.

required
state K

initial value for the state.

required

Returns:

Type Description
Lazy[K]

New Lazy[K] with all intermediate steps of the operation.

Examples:

>>> QList([1, 2, 3]).scan(lambda acc, x: acc + x, 0).collect()
[1, 3, 6]
Source code in src\qwlist\qwlist.py
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
def scan(self, operation: Callable[[K, T], K], state: K) -> "Lazy[K]":
    """
    Given the combination operator creates a `Lazy[K]` object by processing
    constituent parts of `self`, yielding intermediate steps and building up the final value.
    Scan is similar to fold but returns all intermediate states instead of just the final result.

    Args:
        operation: `function: (K, T) -> K`. Given the initial `state` applies the given
         combination operator on each element yielded by the `Lazy` object, yielding the result and
         then treating it as the first argument in the next step.
        state (K): initial value for the state.

    Returns:
        New `Lazy[K]` with all intermediate steps of the `operation`.

    Examples:
        >>> QList([1, 2, 3]).scan(lambda acc, x: acc + x, 0).collect()
        [1, 3, 6]
    """
    def inner(s):
        for elem in self:
            s = operation(s, elem)
            yield s
    return Lazy(inner(state))

skip(n)

Skips n first elements of self.

Parameters:

Name Type Description Default
n int

numbers of elements to skip. Should be non-negative.

required

Returns:

Type Description
Lazy[T]

New Lazy with n first elements of self skipped.

Examples:

>>> QList(range(10)).skip(2).collect()
[2, 3, 4, 5, 6, 7, 8, 9]
Source code in src\qwlist\qwlist.py
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
def skip(self, n: int) -> Lazy[T]:
    """
    Skips `n` first elements of `self`.

    Args:
        n (int): numbers of elements to skip. Should be non-negative.

    Returns:
        New `Lazy` with `n` first elements of `self` skipped.

    Examples:
        >>> QList(range(10)).skip(2).collect()
        [2, 3, 4, 5, 6, 7, 8, 9]
    """
    def inner():
        for i, elem in enumerate(self):
            if i >= n:
                yield elem
    return Lazy(inner())

slice(s)

Calling this method with s equal to slice(3) works similarly to list[:3] but is lazy evaluated.

Parameters:

Name Type Description Default
s slice

slice object

required

Returns: Lazy[T]

Source code in src\qwlist\qwlist.py
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
def slice(self, s: slice) -> Lazy[T]:
    """
    Calling this method with `s` equal to `slice(3)` works similarly to
    `list[:3]` but is lazy evaluated.

    Args:
        s: slice object

    Returns: `Lazy[T]`
    """
    assert isinstance(s, slice), f"slice method argument must be a slice object. Got {type(s)}."

    def inner():
        for elem in self[s]:
            yield elem
    return Lazy(inner())

sorted(key=None, reverse=False)

Returns a new QList containing all items from the original list in ascending order.

A custom key function can be supplied to customize the sort order, and the reverse flag can be set to request the result in descending order.

Parameters:

Name Type Description Default
key Callable[[T], SupportsLessThan]

function: (T) -> SupportsLessThan. Defaults to None.

None
reverse bool

if set to True sorts values in descending order. Defaults to False.

False

Returns:

Type Description
QList[T]

Sorted QList.

Source code in src\qwlist\qwlist.py
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
def sorted(self, key: Callable[[T], SupportsLessThan] = None, reverse: bool = False) -> "QList[T]":
    """
    Returns a new `QList` containing all items from the original list in ascending order.

    A custom key function can be supplied to customize the sort order, and the reverse
    flag can be set to request the result in descending order.

    Args:
        key (Callable[[T], SupportsLessThan]): `function: (T) -> SupportsLessThan`. Defaults to `None`.
        reverse (bool): if set to `True` sorts values in descending order. Defaults to `False`.

    Returns:
        Sorted `QList`.
    """
    return QList(sorted(self, key=key, reverse=reverse))

sum()

Sums all the elements and returns the sum. Returns None if self is empty. Elements of self must support addition.

Returns:

Type Description
Optional[SupportsAdd]

The sum of all elements of self.

Source code in src\qwlist\qwlist.py
1311
1312
1313
1314
1315
1316
1317
1318
1319
1320
1321
1322
1323
1324
1325
1326
1327
def sum(self) -> Optional[SupportsAdd]:
    """
    Sums all the elements and returns the sum. Returns `None` if `self` is empty.
    Elements of `self` must support addition.

    Returns:
        The sum of all elements of `self`.
    """
    it = self.iter()
    acc = None
    try:
        acc = next(it)
    except StopIteration:
        return acc
    for elem in it:
        acc = acc + elem
    return acc

take(n)

Takes n first elements of self. Args: n (int): numbers of elements to take. Should be non-negative.

Returns:

Type Description
Lazy[T]

New Lazy with only n first elements from self.

Examples:

>>> QList(range(10)).take(2).collect()
[0, 1]
Source code in src\qwlist\qwlist.py
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
def take(self, n: int) -> Lazy[T]:
    """
    Takes `n` first elements of `self`.
    Args:
        n (int): numbers of elements to take. Should be non-negative.

    Returns:
        New `Lazy` with only `n` first elements from `self`.

    Examples:
        >>> QList(range(10)).take(2).collect()
        [0, 1]
    """
    def inner():
        for i, elem in enumerate(self):
            if i >= n:
                return None
            yield elem
    return Lazy(inner())

take_while(pred)

Creates a Lazy that yields elements based on a predicate. Takes a function as an argument. It will call this function on each element of self, and yield elements while the function returns True. After False is returned, iteration stops, and the rest of the elements is ignored.

Parameters:

Name Type Description Default
pred Callable[[T], bool]

function: (T) -> bool

required

Returns:

Type Description
Lazy[T]

New Lazy containing elements from the original sequence, stopping at the first element for which the predicate returns False.

Source code in src\qwlist\qwlist.py
1291
1292
1293
1294
1295
1296
1297
1298
1299
1300
1301
1302
1303
1304
1305
1306
1307
1308
1309
def take_while(self, pred: Callable[[T], bool]) -> "Lazy[T]":
    """
    Creates a `Lazy` that yields elements based on a predicate. Takes a function as an argument.
    It will call this function on each element of `self`, and yield elements while the function
    returns `True`. After `False` is returned, iteration stops, and the rest of the elements is ignored.

    Args:
        pred (Callable[[T], bool]): `function: (T) -> bool`

    Returns:
        New `Lazy` containing elements from the original sequence, stopping at the first element for which the
         predicate returns `False`.
    """
    def inner():
        for elem in self:
            if not pred(elem):
                return
            yield elem
    return Lazy(inner())

window(window_size)

Creates a Lazy of sliding windows of size window_size. If window_size is greater than the total length of self an empty iterator is returned.

Parameters:

Name Type Description Default
window_size int

the size of the sliding window. Must be greater than 0.

required

Returns:

Type Description
Lazy[QList[T]]

New Lazy of all sliding windows.

Source code in src\qwlist\qwlist.py
1329
1330
1331
1332
1333
1334
1335
1336
1337
1338
1339
1340
1341
1342
1343
1344
1345
1346
1347
1348
1349
1350
1351
1352
1353
1354
def window(self, window_size: int) -> "Lazy[QList[T]]":
    """
    Creates a `Lazy` of sliding windows of size `window_size`. If `window_size`
    is greater than the total length of `self` an empty iterator is returned.

    Args:
        window_size (int): the size of the sliding window. Must be greater than 0.

    Returns:
        New `Lazy` of all sliding windows.
    """
    assert window_size > 0, f'window size must be greater than 0 but got {window_size}.'
    def inner(n: int):
        if self.len() < n:
            return
        if self.len() == n:
            yield self
            return
        window = deque(maxlen=n)
        for elem in self[:n]:
            window.append(elem)
        yield QList(window)
        for elem in self[n:]:
            window.append(elem)
            yield QList(window)
    return Lazy(inner(n=window_size))

zip(other)

Combines self with the given Iterable elementwise as tuples. The returned Lazy objects yields at most the number of elements of the shorter sequence (self or other).

Parameters:

Name Type Description Default
other Iterable[K]

iterable to zip with self.

required

Returns:

Type Description
Lazy[tuple[T, K]]

New Lazy with pairs of elements from self and other.

Examples:

>>> Lazy([1, 2, 3]).zip(['a', 'b', 'c']).collect()
[(1, 'a'), (2, 'b'), (3, 'c')]
Source code in src\qwlist\qwlist.py
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
def zip(self, other: Iterable[K]) -> Lazy[tuple[T, K]]:
    """
    Combines `self` with the given `Iterable` elementwise as tuples.
     The returned `Lazy` objects yields at most the number of elements of
     the shorter sequence (`self` or `other`).

    Args:
        other (Iterable[K]): iterable to zip with `self`.

    Returns:
        New `Lazy` with pairs of elements from `self` and `other`.

    Examples:
        >>> Lazy([1, 2, 3]).zip(['a', 'b', 'c']).collect()
        [(1, 'a'), (2, 'b'), (3, 'c')]
    """
    return Lazy(zip(self, other))