From c3c614a363612800e7af8f09e8418b85444e4dae Mon Sep 17 00:00:00 2001 From: Martin Bernstorff Date: Fri, 21 Jun 2024 11:44:26 +0200 Subject: [PATCH] docs: update readme --- README.md | 77 +++++++++++++++++++++++++++++++++---------------------- 1 file changed, 47 insertions(+), 30 deletions(-) diff --git a/README.md b/README.md index 7ab4460..35f2659 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,5 @@ # iterpy + [![Open in Dev Container](https://img.shields.io/static/v1?label=Dev%20Containers&message=Open&color=blue&logo=visualstudiocode)][dev container] [![PyPI](https://img.shields.io/pypi/v/iterpy.svg)][pypi status] [![Python Version](https://img.shields.io/pypi/pyversions/iterpy)][pypi status] @@ -8,9 +9,9 @@ [dev container]: https://vscode.dev/redirect?url=vscode://ms-vscode-remote.remote-containers/cloneInVolume?url=https://github.com/MartinBernstorff/iterpy/ [roadmap]: https://github.com/users/MartinBernstorff/projects/3/views/1?groupedBy%5BcolumnId%5D=70727793&sliceBy%5BcolumnId%5D=Status&filterQuery=-status%3ADone - -Python has implemented `map`, `filter` etc. as functions, rather than methods on a sequence. Since it does not contain a pipe operator, this makes the result harder to read. iterpy exists to change that. + +Python has implemented `map`, `filter` etc. as functions, rather than methods on a sequence. Since it does not contain a pipe operator, this makes the result harder to read. iterpy exists to change that. You get this 🔥: @@ -33,14 +34,17 @@ Or this: ```python result = filter(is_even, map(multiply_by_2, [1,2,3])) ``` + ## Install + ```bash pip install iterpy ``` ## Usage + ```python from iterpy import Iter @@ -53,6 +57,7 @@ assert result == [4] ``` ### Lazy vs eager evaluation + Inspired by Polars, iterpy supports eager evaluation for easier debugging using `Arr`, and lazy evaluation for better performance using `Iter`. To access eager evaluation: ```python @@ -72,48 +77,60 @@ assert result == [2, 4, 6] ``` ## Prior art -iterpy stands on the shoulders of Scala, Rust etc. + +iterpy stands on the shoulders of Scala, Rust etc. Other Python projects have had similar ideas: -* [PyFunctional](https://github.com/EntilZha/PyFunctional) has existed for 7+ years with a comprehensive feature set. It is performant, with built-in lineage and caching. Unfortunately, this makes typing [non-trivial, with a 4+ year ongoing effort to add types](https://github.com/EntilZha/PyFunctional/issues/118). -* [flupy](https://github.com/olirice/flupy) is highly similar, well typed, and mature. I had some issues with `.flatten()` not being type-hinted correctly, but but your mileage may vary. -* Your library here? Feel free to make an issue if you have a good alternative! + +- [PyFunctional](https://github.com/EntilZha/PyFunctional) has existed for 7+ years with a comprehensive feature set. It is performant, with built-in lineage and caching. Unfortunately, this makes typing [non-trivial, with a 4+ year ongoing effort to add types](https://github.com/EntilZha/PyFunctional/issues/118). +- [flupy](https://github.com/olirice/flupy) is highly similar, well typed, and mature. I had some issues with `.flatten()` not being type-hinted correctly, but but your mileage may vary. +- Your library here? Feel free to make an issue if you have a good alternative! ## Contributing + +### Setup + +1. We use [`rye`](https://rye.astral.sh/) for environment management. Once it is installed, set up your virtual environment using `rye sync`. + +Or, use the devcontainer. + +1. Install [Orbstack](https://orbstack.dev/) or Docker Desktop. Make sure to complete the full install process before continuing. +1. If not installed, install VSCode +1. Press this [link](https://vscode.dev/redirect?url=vscode://ms-vscode-remote.remote-containers/cloneInVolume?url=https://github.com/MartinBernstorff/iterpy/) + +### Changes + +2. Make your changes + +3. See the makefile for tests, linting, and formatting. + ### Conventions -#### Philosophy -* Make it work: Concise syntax borrowed from Scala, Rust etc. -* Make it right: Fully typed, no exceptions -* Make it fast: - * Concurrency through `.pmap` - * (Future): Caching - * (Future): Refactor operations to use generators -* Keep it simple: No dependencies - -#### API design + +- Make it work: Concise syntax borrowed from Scala, Rust etc. +- Make it right: Fully typed, no exceptions +- Make it fast: + - Concurrency through `.pmap` + - (Future): Caching + - (Future): Refactor operations to use generators +- Keep it simple: No dependencies + +### API design + As a heuristic, we follow the APIs of: -* Rust's [std::iter](https://doc.rust-lang.org/stable/std/iter/) -* Rust's [itertools](https://docs.rs/itertools/latest/itertools/index.html) -In cases where this conflicts with typical python implementations, the API should be as predictable as possible for Python users. +- Rust's [std::iter](https://doc.rust-lang.org/stable/std/iter/) +- Rust's [itertools](https://docs.rs/itertools/latest/itertools/index.html) -#### Devcontainer -1. Install [Orbstack](https://orbstack.dev/) or Docker Desktop. Make sure to complete the full install process before continuing. -2. If not installed, install VSCode -3. Press this [link](https://vscode.dev/redirect?url=vscode://ms-vscode-remote.remote-containers/cloneInVolume?url=https://github.com/MartinBernstorff/iterpy/) -4. Complete the setup process -5. Done! Easy as that. +In cases where this conflicts with typical python implementations, the API should be as predictable as possible for Python users. ## 💬 Where to ask questions -| Type | | -| ------------------------------ | ---------------------- | +| Type | | +| ------------------------------- | ---------------------- | | 🚨 **Bug Reports** | [GitHub Issue Tracker] | | 🎁 **Feature Requests & Ideas** | [GitHub Issue Tracker] | | 👩‍💻 **Usage Questions** | [GitHub Discussions] | -| 🗯 **General Discussion** | [GitHub Discussions] | +| 🗯 **General Discussion** | [GitHub Discussions] | [github issue tracker]: https://github.com/MartinBernstorff/iterpy/issues [github discussions]: https://github.com/MartinBernstorff/iterpy/discussions - -