tinystream 0.1.17__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,252 @@
1
+ Metadata-Version: 2.4
2
+ Name: tinystream
3
+ Version: 0.1.17
4
+ Summary: Yet another python streams library
5
+ Home-page: https://github.com/mreiche/python-streams
6
+ Author: Mike Reiche
7
+ Description-Content-Type: text/markdown
8
+ License-File: LICENSE
9
+ Dynamic: author
10
+ Dynamic: description
11
+ Dynamic: description-content-type
12
+ Dynamic: home-page
13
+ Dynamic: license-file
14
+ Dynamic: summary
15
+
16
+ ![Tests Status](https://github.com/mreiche/python-streams/actions/workflows/tests.yml/badge.svg)
17
+ [![Code Coverage Status](https://codecov.io/github/mreiche/python-streams/branch/main/graph/badge.svg)](https://app.codecov.io/github/mreiche/python-streams)
18
+
19
+ # tinystream / python-streams
20
+
21
+ This is a simple and lightweight Streams API inspired by Java Streams with support for type hinting.
22
+
23
+ This package is released as `tinystream` at pypi.
24
+
25
+ ## Basic API
26
+
27
+ ```python
28
+ from tinystream import Stream
29
+
30
+ stream = Stream([1, 2, 3, 4, 5]) # Stream.of_many(*), Stream.of_dict()
31
+
32
+ stream \
33
+ .map(lambda x: x + 1) \ # flatmap(), peek(), map_key(), map_kwargs(), map_keys()
34
+ .filter(lambda x: x > 2) \ # filter_key(), filter_type()
35
+ .sorted(reverse=True) \ # sort()
36
+ .reverse() \
37
+ .limit(2) \
38
+ .concat([4]) \
39
+ .sum() # reduce(), max(), min(), collect(), count(), find()
40
+ ```
41
+
42
+ ## Aggregators
43
+
44
+ Aggregators like `sum()`, `count()`, `max()` will `collect()` the data and end the stream. `collect()` also caches the data and can be called multiple times, since it returns only a `list`.
45
+
46
+ ## Built-in Optional support
47
+
48
+ Some aggregators like `sum()`, `max()` are `Opt`:
49
+
50
+ ```python
51
+ assert Stream((1, 2, 3, 4, 5)).sum().get() == 15
52
+ ```
53
+
54
+ ## More features
55
+
56
+ ### Type hinting
57
+
58
+ You can typehint datatypes like:
59
+
60
+ ```python
61
+ from dataclasses import dataclass
62
+
63
+ @dataclass
64
+ class Node:
65
+ name: str
66
+ parent: "Node" = None
67
+
68
+ parent = Node(name="B")
69
+ child = Node(name="A", parent=parent)
70
+ ```
71
+
72
+ for lambdas:
73
+
74
+ ```python
75
+ stream = Stream([child])
76
+ assert stream.map(lambda x: x.parent).type(Node).next().get().name == "B"
77
+ ```
78
+
79
+ This is not necessary when you pass a mapping function:
80
+ ```python
81
+ def map_parent(n: Node):
82
+ return n.parent
83
+
84
+ assert stream.map(map_parent).next().get().name == "B"
85
+ ```
86
+
87
+ ### Typed dictionaries
88
+
89
+ Dictionaries are streamed as `tuple(key, value)`
90
+
91
+ ```python
92
+ children = {"a": Node(name="Child")}
93
+ stream = Stream.of_dict(children)
94
+ for item in stream:
95
+ # item[0] is known as str
96
+ # item[1] is known as Node
97
+ ```
98
+
99
+ This is the same like (but without known types):
100
+ ```python
101
+ stream = Stream(children)
102
+ ```
103
+
104
+ ### Filter by existing key
105
+ ```python
106
+ items_with_name = Stream([child]).filter_key("name")
107
+ ```
108
+
109
+ ### Filter by key value
110
+ ```python
111
+ items_with_name = Stream([child]).filter_key_value("name", "Child")
112
+ ```
113
+
114
+ ### Filter by type
115
+ ```python
116
+ nodes_only = Stream([child]).filter_type(Node)
117
+ ```
118
+
119
+ ### Map object name attribute
120
+ ```python
121
+ names = Stream([child]).map_key("name")
122
+ ```
123
+
124
+ ### Deep mapping of name attributes
125
+ ```python
126
+ list = [
127
+ {"node": Node(name="Node A")},
128
+ {"node": Node(name="Node B")},
129
+ {"node": Node(name="Node C")},
130
+ {"node": Node(name="Node D")},
131
+ ]
132
+ names = Stream(list).map_keys("node", "name")
133
+ ```
134
+
135
+ ### Collected join
136
+
137
+ ```python
138
+ all_names = Stream([child]).map_key("name").join(", ")
139
+ ```
140
+
141
+ ### Map kwargs
142
+ ```python
143
+ list = [
144
+ {"name": "Node A"},
145
+ {"name": "Node B"},
146
+ ]
147
+ # Short cut for map(lambda x: Node(**x))
148
+ nodes = Stream(list).map_kwargs(Node)
149
+ ```
150
+
151
+ ### Stream many
152
+
153
+ ```python
154
+ many = Stream.of_many([1, 2, 3], (4, 5, 6))
155
+ many = many.concat([7, 8, 9])
156
+ ```
157
+
158
+ ### End of stream
159
+ ```python
160
+ stream = Stream(["a", "b", "c"]).on_end(lambda: print("Finished"))
161
+ char = stream.next().get()
162
+ if char == "a":
163
+ stream.end()
164
+ ```
165
+
166
+ ### Opt usage
167
+
168
+ Get next value as `Opt`:
169
+
170
+ ```python
171
+ assert Stream((1, 2, 3, 4, 5)).next().present
172
+ ```
173
+
174
+ Mapping:
175
+ ```python
176
+ assert Opt("String").map(str.lower).len == 6
177
+ ```
178
+
179
+ Get default value:
180
+ ```python
181
+ assert Opt(None).get(6) == 6
182
+ assert Opt(None).get(lambda: 6) == 6
183
+ assert Opt(None).if_absent(lambda: 3).present
184
+ ```
185
+
186
+ Filter value:
187
+ ```python
188
+ assert Opt(0).filter(lambda x: x > 0).absent
189
+ ```
190
+
191
+ You can also access optional index elements of the stream, but this will `collect()` and end the stream.
192
+ ```python
193
+ assert Stream([])[2].absent
194
+ ```
195
+
196
+ ## Examples
197
+
198
+ ### Write better code with `Stream`
199
+
200
+ ```python
201
+ data = {
202
+ "ranges": [
203
+ {"days": 3},
204
+ {"weeks": 1},
205
+ ]
206
+ }
207
+
208
+ # With tinystream Stream
209
+ for range_data in Opt(data).map_key("ranges").stream().map_kwargs(timedelta):
210
+ pass
211
+
212
+ # Vanilly Python
213
+ if "ranges" in data:
214
+ range_data: timedelta
215
+ for range_data in map(lambda x: timedelta(**x), data["ranges"]):
216
+ pass
217
+ ```
218
+
219
+ ### Write better code with `Opt`
220
+ ```python
221
+ # tinystream Opt
222
+ var = Opt(my_dict).kmap("key").filter(not_empty).get("default")
223
+
224
+ # Vanilla Python
225
+ var = my_dict["key"] if "key" in my_dict and not_empty(my_dict["key"]) else "default"
226
+ ```
227
+
228
+
229
+ ## Comparison with other libraries
230
+
231
+ There are a couple of other implementation to fulfill similar requirements.
232
+
233
+ - https://github.com/vxgmichel/aiostream
234
+ - https://github.com/python-streamz/streamz
235
+ - https://pypi.org/project/fluentpy
236
+ - https://github.com/ramsteak/streams
237
+ - https://github.com/alemazzo/Python-Java-Stream (*outdated*)
238
+ - https://github.com/JaviOverflow/python-streams (*outdated*)
239
+ - https://github.com/9seconds/streams/ (*outdated*)
240
+ - https://github.com/tolsac/streampy (*outdated*)
241
+ - Apache Spark
242
+
243
+ ## Run the tests
244
+
245
+ ```shell
246
+ PYTHONPATH="." pytest --cov=tinystream -n 4 tests/
247
+ ```
248
+
249
+ ## References
250
+
251
+ - https://github.com/MichaelKim0407/tutorial-pip-package
252
+ - https://packaging.python.org/en/latest/guides/making-a-pypi-friendly-readme/
@@ -0,0 +1,6 @@
1
+ tinystream.py,sha256=NzcMRXbhow3e4Uj7BsBpofNylstVsVFEQmUI0cFtGOU,9916
2
+ tinystream-0.1.17.dist-info/licenses/LICENSE,sha256=E21_g23tuamVhgr0PEu_kLNrOxi-ydv9AFmO1m-A3fY,1068
3
+ tinystream-0.1.17.dist-info/METADATA,sha256=6DKJKG8OqNTGySNfZ-fFGbLkPd4Lg9DLXrf4-B6XILQ,5560
4
+ tinystream-0.1.17.dist-info/WHEEL,sha256=zaaOINJESkSfm_4HQVc5ssNzHCPXhJm0kEUakpsEHaU,91
5
+ tinystream-0.1.17.dist-info/top_level.txt,sha256=LDq4pQ-mnJ8zudSdIX7uPCaj1cnr3cFk5ZV-DHtgpqE,11
6
+ tinystream-0.1.17.dist-info/RECORD,,
@@ -0,0 +1,5 @@
1
+ Wheel-Version: 1.0
2
+ Generator: setuptools (80.8.0)
3
+ Root-Is-Purelib: true
4
+ Tag: py3-none-any
5
+
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2022 Mike Reiche
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1 @@
1
+ tinystream
tinystream.py ADDED
@@ -0,0 +1,362 @@
1
+ import functools
2
+ import itertools
3
+ from typing import Iterable, TypeVar, Callable, List, Dict, Tuple, Iterator, Generic, Type
4
+ from warnings import warn
5
+
6
+ T = TypeVar("T")
7
+ R = TypeVar("R")
8
+ K = TypeVar("K")
9
+
10
+
11
+ Mapper = Callable[[T], R] | Type[R]
12
+ FlatMapper = Callable[[T], Iterable[R]]
13
+ Consumer = Callable[[T], None]
14
+ Comparator = Callable[[T, T], int]
15
+ Reducer = Callable[[T, T], R]
16
+ Predicate = Callable[[T], bool]
17
+ Supplier = Callable[[], T]
18
+ Key = int|str
19
+
20
+
21
+ def _key_exists(x: any, key: Key, invert: bool = False):
22
+ if isinstance(x, (list, tuple)):
23
+ size = len(x)
24
+ if invert:
25
+ return key >= size
26
+ else:
27
+ return key < size
28
+ elif isinstance(x, (dict, Iterable)):
29
+ if invert:
30
+ return key not in x
31
+ else:
32
+ return key in x
33
+ else:
34
+ if invert:
35
+ return not hasattr(x, key)
36
+ else:
37
+ return hasattr(x, key)
38
+
39
+
40
+ def _get_key_value(x: any, key: Key) -> any:
41
+ if isinstance(x, (list, dict, tuple)):
42
+ return x[key]
43
+ else:
44
+ return getattr(x, key)
45
+
46
+
47
+ class Opt(Generic[T]):
48
+ def __init__(self, value: T):
49
+ self.__val = value
50
+
51
+ @property
52
+ def empty(self):
53
+ warn("Please use absent property instead", DeprecationWarning)
54
+ return self.absent
55
+
56
+ @property
57
+ def absent(self):
58
+ return self.__val is None
59
+
60
+ @property
61
+ def present(self):
62
+ return not self.absent
63
+
64
+ def get(self, *args) -> T:
65
+ if self.present:
66
+ return self.__val
67
+ elif len(args) > 0:
68
+ if isinstance(args[0], Callable):
69
+ return args[0]()
70
+ else:
71
+ return args[0]
72
+ else:
73
+ raise Exception("Cannot get value of empty Opt without default value")
74
+
75
+ def if_present(self, consumer: Consumer[T]):
76
+ if self.present:
77
+ consumer(self.get())
78
+
79
+ def filter(self, predicate: Predicate[T]):
80
+ if predicate(self.__val):
81
+ return self
82
+ else:
83
+ return EmptyOpt()
84
+
85
+ def map(self, mapper: Mapper[T, R]) -> "Opt[R]":
86
+ if self.absent:
87
+ return EmptyOpt()
88
+ else:
89
+ return Opt[R](mapper(self.__val))
90
+
91
+ def if_empty(self, supplier: Supplier[R] | any):
92
+ warn("Please use if_absent() method instead", DeprecationWarning)
93
+ return self.if_absent(supplier)
94
+
95
+ def if_absent(self, supplier: Supplier[R] | any):
96
+ if self.absent:
97
+ if isinstance(supplier, Callable):
98
+ return Opt[R](supplier())
99
+ else:
100
+ return Opt[R](supplier)
101
+ else:
102
+ return self
103
+
104
+ def type(self, typehint: Type[R]) -> "Opt[R]":
105
+ return self
106
+
107
+ def filter_type(self, typehint: Type[R]) -> "Opt[R]":
108
+ return self.filter(lambda x: isinstance(x, typehint))
109
+
110
+ def filter_key(self, key: Key, invert: bool = False):
111
+ if _key_exists(self.__val, key, invert):
112
+ return self
113
+ else:
114
+ return EmptyOpt()
115
+
116
+ def filter_key_value(self, key: Key, value: any):
117
+ if _key_exists(self.__val, key, False) and _get_key_value(self.__val, key) == value:
118
+ return self
119
+ else:
120
+ return EmptyOpt()
121
+
122
+ def map_key(self, key: Key):
123
+ if _key_exists(self.__val, key):
124
+ return Opt(_get_key_value(self.__val, key))
125
+ else:
126
+ return EmptyOpt()
127
+
128
+ def kmap(self, key: Key):
129
+ """This is an alias for map_key"""
130
+ return self.map_key(key)
131
+
132
+ def map_keys(self, *iterables):
133
+ inst = self
134
+ for key in iterables:
135
+ inst = inst.map_key(key)
136
+ return inst
137
+
138
+ def stream(self):
139
+ return Stream(self.__val)
140
+
141
+ @property
142
+ def len(self):
143
+ if self.absent:
144
+ return 0
145
+ else:
146
+ return len(self.__val)
147
+
148
+ def map_kwargs(self, mapper: Type[R]) -> "Opt[R]":
149
+ return self.map(lambda x: mapper(**x))
150
+
151
+
152
+ class EmptyOpt(Opt[None]):
153
+ def __init__(self):
154
+ super().__init__(None)
155
+
156
+ def map(self, mapper: Mapper[T, R]):
157
+ return self
158
+
159
+ def filter(self, predicate: Predicate[T]):
160
+ return self
161
+
162
+ def map_key(self, key: Key):
163
+ return self
164
+
165
+ def filter_key(self, key: Key, invert: bool = False):
166
+ return self
167
+
168
+ def filter_key_value(self, key: Key, value: any):
169
+ return self
170
+
171
+ @property
172
+ def absent(self):
173
+ return True
174
+
175
+ def stream(self):
176
+ return Stream([])
177
+
178
+ @property
179
+ def len(self):
180
+ return 0
181
+
182
+
183
+ class Stream(Iterator[T]):
184
+
185
+ def __init__(self, iterable: Iterable[T]):
186
+ self.__iterable = self.__normalize_iterator(iterable)
187
+ self.__collected: List[T] = None
188
+ self.__on_end: Callable = None
189
+
190
+ @staticmethod
191
+ def of(iterable: Iterable[T]):
192
+ warn("Use constructor", DeprecationWarning)
193
+ return Stream[T](iterable)
194
+
195
+ @staticmethod
196
+ def of_dict(source_dict: Dict[K, T]):
197
+ return Stream[Tuple[K, T]](source_dict)
198
+
199
+ @staticmethod
200
+ def of_many(*iterables):
201
+ return Stream([]).concat(*iterables)
202
+
203
+ def on_end(self, cb: Callable) -> "Stream[R]":
204
+ if self.__on_end:
205
+ raise AttributeError("on_end is immutable")
206
+ self.__on_end = cb
207
+ return self
208
+
209
+ def end(self):
210
+ if self.__on_end:
211
+ self.__on_end()
212
+ self.__iterable = iter([])
213
+ self.__on_end = None
214
+
215
+ def __next__(self) -> T | None:
216
+ try:
217
+ return next(self.__iterable)
218
+ except StopIteration as e:
219
+ self.end()
220
+ raise e
221
+
222
+ def __iter__(self) -> Iterator[T]:
223
+ return self
224
+
225
+ def __normalize_iterator(self, iterable: Iterable[T]) -> Iterable[T]:
226
+ if isinstance(iterable, list):
227
+ return iter(iterable)
228
+ elif isinstance(iterable, dict):
229
+ return iter(iterable.items())
230
+ elif isinstance(iterable, str):
231
+ return iter(iterable)
232
+ else:
233
+ return iterable
234
+
235
+ def map(self, mapper: Mapper[T, R]):
236
+ return Stream[R](map(mapper, self))
237
+
238
+ def map_kwargs(self, mapper: Type[R]) -> "Stream[R]":
239
+ return self.map(lambda x: mapper(**x))
240
+
241
+ def map_key(self, key: Key):
242
+ return self.filter_key(key).map(lambda x: _get_key_value(x, key))
243
+
244
+ def kmap(self, key: Key):
245
+ """This is an alias for map_key"""
246
+ return self.map_key(key)
247
+
248
+ def map_keys(self, *iterables):
249
+ inst = self
250
+ for key in iterables:
251
+ inst = inst.map_key(key)
252
+ return inst
253
+
254
+ def type(self, typehint: Type[R]) -> "Stream[R]":
255
+ return self
256
+
257
+ def filter_type(self, typehint: Type[R]) -> "Stream[R]":
258
+ return self.filter(lambda x: isinstance(x, typehint))
259
+
260
+ def filter(self, predicate: Predicate[T]):
261
+ return Stream[T](filter(predicate, self.__iterable))
262
+
263
+ def filter_key(self, key: Key, invert: bool = False):
264
+ return self.filter(lambda x: _key_exists(x, key, invert))
265
+
266
+ def filter_key_value(self, key: Key, value: any):
267
+ return self.filter(lambda x: _key_exists(x, key, False) and _get_key_value(x, key) == value)
268
+
269
+ def flatmap(self, mapper: FlatMapper[T, R] = None):
270
+
271
+ def __flatmap(f, xs):
272
+ return (y for ys in xs for y in f(ys))
273
+
274
+ def __flatten(xs):
275
+ return (y for ys in xs for y in ys)
276
+
277
+ if mapper is not None:
278
+ return Stream[R](__flatmap(mapper, self))
279
+ else:
280
+ return Stream[R](__flatten(self))
281
+
282
+ def peek(self, consumer: Consumer[T]):
283
+ def __peek(x: T):
284
+ consumer(x)
285
+ return x
286
+
287
+ return Stream[T](map(__peek, self))
288
+
289
+ def sort(self, compare: Comparator[T], reverse: bool = False):
290
+ key = functools.cmp_to_key(compare)
291
+ sort = sorted(self.__iterable, key=key, reverse=reverse)
292
+ return Stream[T](sort)
293
+
294
+ def sorted(self, key: any = None, reverse: bool = False):
295
+ sort = sorted(self.__iterable, key=key, reverse=reverse)
296
+ return Stream[T](sort)
297
+
298
+ def next(self) -> Opt[T]:
299
+ try:
300
+ next = self.__next__()
301
+ except StopIteration as e:
302
+ next = None
303
+ return Opt(next)
304
+
305
+ def collect(self):
306
+ """Collects all items to a list and ends the stream"""
307
+ if not self.__collected:
308
+ self.__collected = list(self)
309
+ return self.__collected
310
+
311
+ def __getitem__(self, index: int) -> Opt[T]:
312
+ collection = self.collect()
313
+ if 0 <= index < len(collection):
314
+ return Opt(collection[index])
315
+ else:
316
+ return EmptyOpt()
317
+
318
+ def join(self, separator: str) -> str:
319
+ """Joins the string to the elements and ends the stream"""
320
+ return separator.join(map(str, self))
321
+
322
+ def count(self):
323
+ """Collects and counts all items and ends the stream"""
324
+ return len(self.collect())
325
+
326
+ def reverse(self):
327
+ copy = self.collect().copy()
328
+ copy.reverse()
329
+ return Stream[T](copy)
330
+
331
+ def reduce(self, cb: Reducer) -> Opt[R]:
332
+ try:
333
+ return Opt(functools.reduce(cb, self))
334
+ except TypeError:
335
+ return Opt(None)
336
+
337
+ def sum(self) -> Opt[T]:
338
+ """Sums all numbers and ends the stream"""
339
+ return self.reduce(lambda x, y: x + y)
340
+
341
+ def max(self) -> Opt[T]:
342
+ return self.reduce(lambda x, y: x if x > y else y)
343
+
344
+ def min(self) -> Opt[T]:
345
+ return self.reduce(lambda x, y: x if x < y else y)
346
+
347
+ def limit(self, limit: int):
348
+ def __limit():
349
+ for i in range(limit):
350
+ yield self.__next__()
351
+
352
+ return Stream[T](__limit())
353
+
354
+ def concat(self, *iterables):
355
+ iterators = [self]
356
+ for iterator in iterables:
357
+ iterators.append(self.__normalize_iterator(iterator))
358
+
359
+ return Stream[T](itertools.chain(*iterators))
360
+
361
+ def find(self, predicate: Predicate[T]) -> Opt[T]:
362
+ return self.filter(predicate).next()