README.md

iterpy

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 🔥:

from iterpy import Iter

result = Iter([1,2,3]).map(multiply_by_2).filter(is_even)

Instead of this:

sequence = [1,2,3]
multiplied = [multiply_by_2(x) for x in sequence]
result = [x for x in multiplied if is_even(x)]

Or this:

result = filter(is_even, map(multiply_by_2, [1,2,3]))

Install

pip install iterpy

Usage

from iterpy import Iter

result = (Iter([1, 2])
            .filter(lambda x: x % 2 == 0)
            .map(lambda x: x * 2)
            .to_list()
)
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:

from iterpy import Arr

result = Arr([1, 2, 3]).map(lambda x: x * 2).to_list()
assert result == [2, 4, 6]

To access lazy evaluation, just rename Arr to Iter:

from iterpy import Iter

result = Iter([1, 2, 3]).map(lambda x: x * 2).to_list()
assert result == [2, 4, 6]

Prior art

iterpy stands on the shoulders of Scala, Rust etc.

Other Python projects have had similar ideas:

• 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.
• 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 for environment management. Once it is installed, set up your virtual environment using rye sync.

Or, use the devcontainer.

1. Install Orbstack or Docker Desktop. Make sure to complete the full install process before continuing.
2. If not installed, install VSCode
3. Press this link

Changes

2. Make your changes

3. See the makefile for tests, linting, and formatting.

Conventions

• 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
• Rust's itertools

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
🚨 Bug Reports	GitHub Issue Tracker
🎁 Feature Requests & Ideas	GitHub Issue Tracker
👩‍💻 Usage Questions	GitHub Discussions
🗯 General Discussion	GitHub Discussions