README: shorten

Author: ebonnal

README.md

@@ -8,19 +8,16 @@
 
 - 🔗 ***Fluent*** chainable lazy operations
 - 🔀 ***Concurrent*** via *threads*/*processes*/`async`
-- 🇹 ***Typed***, fully annotated, `Stream[T]` is both an `Iterable[T]` and an `AsyncIterable[T]`
-- 🛡️ ***Tested*** extensively with **Python 3.7 to 3.14**
-- 🪶 ***Light***, no dependencies
-
+- 🇹 Fully ***Typed***, `Stream[T]` is both an `Iterable[T]` and an `AsyncIterable[T]`
+- 🛡️ ***Battle-tested*** for prod, extensively tested with **Python 3.7 to 3.14**.
 
 
 ## 1. install
 
+> no dependencies
 ```bash
 pip install streamable
-```
-*or*
-```bash
+# or
 conda install conda-forge::streamable 
 ```
 
@@ -52,7 +49,7 @@ inverses: Stream[float] = (
 
 ## 5. iterate
 
-Iterate over a `Stream[T]` just as you would over any other `Iterable[T]`/`AsyncIterable`, elements are processed *on-the-fly*:
+Iterate over a `Stream[T]` just as you would over any other `Iterable[T]` (or `AsyncIterable`), elements are processed *on-the-fly*:
 
 
 ### as `Iterable[T]`
@@ -113,9 +110,7 @@ Iterate over a `Stream[T]` just as you would over any other `Iterable[T]`/`Async
 
 # ↔ example: Extract-Transform-Load
 
-Let's take an example showcasing most of the `Stream`'s operations:
-
-**ETL scripts** can benefit from the expressiveness of this library. Below is a pipeline that extracts the 67 quadruped Pokémon from the first three generations using [PokéAPI](https://pokeapi.co/) and loads them into a CSV:
+Let's take an example showcasing most of the `Stream`'s operations: Below is a pipeline that extracts the 67 quadruped Pokémon from the first three generations using [PokéAPI](https://pokeapi.co/) and loads them into a CSV:
 
 ```python
 import csv
@@ -164,7 +159,7 @@ with open("./quadruped_pokemons.csv", mode="w") as file:
 
 ## or the `async` way
 
-- use `.amap`: the `.map`'s `async` counterpart, see [`async` Operations](#-async-operations).
+- use the `.amap` operation: the `.map`'s `async` counterpart, see [`async` Operations](#-async-operations).
 - `await` the `Stream`: runs a full iteration over it as an `AsyncIterable[T]`.
 
 ```python
@@ -219,8 +214,6 @@ asyncio.run(main())
 
 # 📒 ***Operations***
 
-*A dozen expressive lazy operations and that’s it!*
-
 ## `.map`
 
 > Applies a transformation on elements:
@@ -234,14 +227,9 @@ assert list(integer_strings) == ['0', '1', '2', '3', '4', '5', '6', '7', '8', '9
 ```
 </details>
 
-### concurrency
-
-> [!NOTE]
-> By default, all the concurrency modes presented below yield results in the upstream order (FIFO). Set the parameter `ordered=False` to yield results as they become available (***First Done, First Out***).
-
 ### thread-based concurrency
 
-> Applies the transformation via `concurrency` threads:
+> Applies the transformation via `concurrency` threads, yielding results in the upstream order (FIFO), set the parameter `ordered=False` to yield results as they become available (*First Done, First Out*).
 
 <details ><summary style="text-indent: 40px;">👀 show snippet</summary></br>
 
@@ -260,10 +248,7 @@ assert list(pokemon_names) == ['bulbasaur', 'ivysaur', 'venusaur']
 </details>
 
 > [!NOTE]
-> `concurrency` is also the size of the buffer containing not-yet-yielded results. **If the buffer is full, the iteration over the upstream is paused** until a result is yielded from the buffer.
-
-> [!TIP]
-> The performance of thread-based concurrency in a CPU-bound script can be drastically improved by using a [Python 3.13+ free-threading build](https://docs.python.org/3/using/configure.html#cmdoption-disable-gil).
+> **Memory-efficient**: Only `concurrent` upstream elements are pulled for processing; the next upstream element is pulled only when a result is yielded downstream.
 
 ### process-based concurrency
 
@@ -281,9 +266,9 @@ if __name__ == "__main__":
 ```
 </details>
 
-### `async`-based concurrency: [see `.amap`](#amap)
+### `async`-based concurrency: [`.amap`](#amap)
 
-> [The `.amap` operation can apply an `async` function concurrently.](#amap)
+> The [`.amap`](#amap) operation can apply an `async` function concurrently.
 
 ### "starmap"
 
@@ -304,7 +289,6 @@ assert list(zeros) == [0, 0, 0, 0, 0, 0, 0, 0, 0, 0]
 </details>
 
 
-
 ## `.foreach`
 
 > Applies a side effect on elements:
@@ -326,7 +310,7 @@ assert state == [0, 1, 2, 3, 4, 5, 6, 7, 8, 9]
 > - set the `concurrency` parameter for **thread-based concurrency**
 > - set `via="process"` for **process-based concurrency**
 > - set `ordered=False` for ***First Done First Out***
-> - [The `.aforeach` operation can apply an `async` effect concurrently.](#aforeach)
+> - The [`.aforeach`](#aforeach) operation can apply an `async` effect concurrently.
 
 ## `.group`
 
@@ -590,7 +574,7 @@ assert list(status_codes_ignoring_resolution_errors) == [200, 404]
 > It has an optional `finally_raise: bool` parameter to raise the first exception caught (if any) when the iteration terminates.
 
 > [!TIP]
-> Apply side effects when catching an exception by integrating them into `when`:
+> Leverage `when` to apply side effects on catch:
 
 <details ><summary style="text-indent: 40px;">👀 show snippet</summary></br>
 
@@ -675,7 +659,6 @@ assert list(integers + integers) == [0, 1, 2, 3 ,4, 5, 6, 7, 8, 9, 0, 1, 2, 3 ,4
 
 ## `zip`
 
-> [!TIP]
 > Use the standard `zip` function:
 
 <details ><summary style="text-indent: 40px;">👀 show snippet</summary></br>
@@ -694,8 +677,8 @@ assert list(cubes) == [0, 1, 8, 27, 64, 125, 216, 343, 512, 729]
 
 
 ## Shorthands for consuming the stream
-> [!NOTE]
-> Although consuming the stream is beyond the scope of this library, it provides two basic shorthands to trigger an iteration:
+
+Although consuming the stream is beyond the scope of this library, it provides two basic shorthands to trigger an iteration:
 
 ## `.count`
 
@@ -723,7 +706,7 @@ assert state == [0, 1, 2, 3, 4, 5, 6, 7, 8, 9]
 
 ## `.pipe`
 
-> Calls a function, passing the stream as first argument, followed by `*args/**kwargs` if any:
+> Calls a function, passing the stream as first argument, followed by `*args/**kwargs` if any (inspired by the `.pipe` from [pandas](https://pandas.pydata.org/docs/reference/api/pandas.DataFrame.pipe.html) or [polars](https://docs.pola.rs/api/python/stable/reference/dataframe/api/polars.DataFrame.pipe.html)):
 
 <details ><summary style="text-indent: 40px;">👀 show snippet</summary></br>
 
@@ -739,24 +722,20 @@ import pandas as pd
 ```
 </details>
 
-> Inspired by the `.pipe` from [pandas](https://pandas.pydata.org/docs/reference/api/pandas.DataFrame.pipe.html) or [polars](https://docs.pola.rs/api/python/stable/reference/dataframe/api/polars.DataFrame.pipe.html).
-
 ---
 ---
 
 # 📒 ***`async` Operations***
 
-Operations that accept a function as an argument have an `async` counterpart, which has the same signature but accepts `async` functions instead. These `async` operations are named the same as the original ones but with an `a` prefix.
+The operations accepting a function as an argument have an `async` counterpart operation, which has the same signature but accepts `async` functions instead.
 
-> [!TIP]
-> One can mix regular and `async` operations on the same `Stream`, and then consume it as a regular `Iterable` or as an `AsyncIterable`.
+**inter-operability**: Both regular and `async` operations can be mixed on the same `Stream`, and it can then be consumed as regular `Iterable` or as `AsyncIterable`.
 
-## `.amap`
+## `.amap` 
 
 > Applies an `async` transformation on elements:
 
-
-> consumed as an `Iterable[T]`:
+- consume as `Iterable[T]`:
 
 <details ><summary style="text-indent: 40px;">👀 show snippet</summary></br>
 
@@ -779,7 +758,7 @@ asyncio.run(http_async_client.aclose())
 ```
 </details>
 
-> or consumed as an `AsyncIterable[T]`:
+- consume as `AsyncIterable[T]`:
 
 <details ><summary style="text-indent: 40px;">👀 show snippet</summary></br>
 
@@ -802,29 +781,29 @@ asyncio.run(main())
 ```
 </details>
 
-## Other `async` operations
+## Others
 
-> `.aforeach`: Applies an `async` side effect on elements. Supports `concurrency` like `.amap`.
+> **`.aforeach`**: Applies an `async` side effect on elements. Supports `concurrency` like `.amap`.
 
-> `.agroup`: Groups into `List`s according to an `async` grouping function.
+> **`.agroup`**: Groups into `List`s according to an `async` grouping function.
 
-> `.agroupby`: Groups into `(key, elements)` tuples, according to an `async` grouping function.
+> **`.agroupby`**: Groups into `(key, elements)` tuples, according to an `async` grouping function.
 
-> `.aflatten`: Ungroups elements assuming that they are `AsyncIterable`s. Like for `.flatten` you can set the `concurrency` parameter.
+> **`.aflatten`**: Ungroups elements assuming that they are `AsyncIterable`s. Like for `.flatten` you can set the `concurrency` parameter.
 
-> `.afilter`: Keeps only the elements that satisfy an `async` condition.
+> **`.afilter`**: Keeps only the elements that satisfy an `async` condition.
 
-> `.adistinct`: Removes duplicates according to an `async` deduplication `key`.
+> **`.adistinct`**: Removes duplicates according to an `async` deduplication `key`.
 
-> `.atruncate`: Ends iteration once a given number of elements have been yielded or `when` an `async` condition is satisfied.
+> **`.atruncate`**: Ends iteration once a given number of elements have been yielded or `when` an `async` condition is satisfied.
 
-> `.askip`: Skips the specified number of elements or `until` an `async` predicate is satisfied.
+> **`.askip`**: Skips the specified number of elements or `until` an `async` predicate is satisfied.
 
-> `.acatch`: Catches a given type of exception `when` an `async` condition is satisfied.
+> **`.acatch`**: Catches a given type of exception `when` an `async` condition is satisfied.
 
 ## Shorthands for consuming the stream as an `AsyncIterable[T]`
 
-## `.acount`
+### `.acount`
 
 > Iterates over the stream until exhaustion and returns the number of elements yielded:
 
@@ -836,7 +815,7 @@ assert asyncio.run(integers.acount()) == 10
 </details>
 
 
-## `await`
+### `await`
 
 > *Awaiting* the stream iterates over it until exhaustion and returns it: