README: add benchmark

Author: ebonnal

README.md

@@ -544,20 +544,45 @@ unique_ints: stream[int] = (
 assert list(unique_ints) == [0, 1]
 ```
 
-## vs `builtins.map/filter`
+## performance
 
 There is zero overhead during iteration compared to `builtins.map` and `builtins.filter`:
 
 ```python
 odd_int_chars = stream(range(N)).filter(lambda n: n % 2).map(str)
 ```
 
-`iter(odd_int_chars)` visits the operations lineage and returns exactly this iterator:
+`iter(odd_int_chars)` visits the operation lineage and returns exactly:
 
 ```python
 map(str, filter(lambda n: n % 2, range(N)))
 ```
 
+Throughput of each operation compared to `builtins.map`:
+
+|operation|times slower than `builtins.map(lambda _: _, range(N))`|
+|--|--|
+|`stream(range(N)).map(lambda _: _)`|1.00x|
+|`stream(range(N)).filter(lambda _: _)`|1.05x|
+|`stream(range(N)).skip(N)`|1.9x|
+|`stream(range(N)).do(lambda _: _)`|2.0x|
+|`stream(range(N)).catch(ValueError)`|2.0x|
+|`stream(range(N)).group(5)`|2.4x|
+|`stream(range(N)).take(N)`|3.0x|
+|`stream(range(N)).observe('ints', do=bool)`|4.2x|
+|`stream(range(N)).observe('ints', do=bool, every=N)`|4.4x|
+|`stream(range(N)).observe('ints', do=bool, every=timedelta(...))`|5.5x|
+|`stream(range(N)).throttle(N, per=timedelta(...))`|5.8x|
+|`stream(range(N)).group(by=bool, up_to=5)`|7.3x|
+|`stream((i,) for i in range(N)).flatten()`|17x|
+|`stream(range(N)).buffer(N)`|50x|
+|`stream(range(N)).map(lambda _: _, concurrency=2)`|330x|
+|`stream(range(N)).map(lambda _: _, concurrency=2, as_completed=True)`|340x|
+|`stream(range(N)).group(within=timedelta(...))`|350x|
+|`stream((i,) for i in range(N)).flatten(concurrency=2)`|850x|
+
+(source: `pytest -s tests/benchmark.py`)
+
 ## e.g. ETL via [`dlt`](https://github.com/dlt-hub/dlt)
 
 A `stream` is an expressive way to declare a `dlt.resource`:

tests/benchmark.py

@@ -0,0 +1,39 @@
+from collections.abc import Iterable
+from datetime import timedelta
+import timeit
+from streamable import stream
+
+N = 1_000_000
+ints = stream(range(N))
+
+
+def consume(s: Iterable):
+    for _ in s:
+        pass
+
+
+baseline = timeit.timeit(lambda: consume(map(lambda _: _, ints)), number=10) / 10
+
+for times, s in (
+    (50, ints.map(lambda _: _)),
+    (50, ints.filter(lambda _: _)),
+    (50, ints.skip(N)),
+    (50, ints.do(lambda _: _)),
+    (50, ints.catch(ValueError)),
+    (50, ints.group(5)),
+    (50, ints.take(N)),
+    (10, ints.observe("ints", do=bool)),
+    (10, ints.observe("ints", do=bool, every=N)),
+    (10, ints.observe("ints", do=bool, every=timedelta(seconds=1))),
+    (10, ints.throttle(N, per=timedelta(seconds=1))),
+    (10, ints.group(5, by=bool)),
+    (1, stream((i,) for i in range(N)).flatten()),
+    (1, ints.buffer(N)),
+    (1, ints.map(lambda _: _, concurrency=2)),
+    (1, ints.map(lambda _: _, concurrency=2, as_completed=True)),
+    (1, ints.group(within=timedelta(seconds=1))),
+    (1, stream((i,) for i in range(N)).flatten(concurrency=2)),
+):
+    duration = timeit.timeit(lambda: consume(s), number=times) / times
+    print(s)
+    print(f"is {duration / baseline:.2f}x slower than builtins.map")