pyochain 0.6.1.72

Method chaining for iterables and dictionaries in Python.

pyochain ⛓️

Fluent method chaining for Python.

Inspired by Rust's Iterator, Result, Option, and DataFrame libraries like Polars, pyochain provide a set of classes with a fluent and declarative API, to work with collections, handle optional values, or manage errors.

Installation

uv add pyochain # or pip install pyochain

See the package page on Pypi

Quick Start

>>> import pyochain as pc
>>> # Lazy processing with Iter
>>> res: pc.Seq[int] = (
...     pc.Iter.from_count(1)
...     .filter(lambda x: x % 2 != 0)
...     .map(lambda x: x**2)
...     .take(5)
...     .collect()
... )
>>> res
Seq(1, 9, 25, 49, 81)
>>> # Type-safe error handling with Result
>>> def divide(a: int, b: int) -> pc.Result[float, str]:
...     return pc.Err("Division by zero") if b == 0 else pc.Ok(a / b)
>>> divide(10, 0).unwrap_or(0.0)
0.0

Key Features

• ⛓️ Declarative & fluent chaining — Replace for loops with chainable methods (map, filter, group_by, etc.).
• 🦥 Lazy-first design — Iter[T] for lazy processing; Seq, Vec, Set for materialized collections.
• 🔒 Explicit mutability — Seq and Set for immutable data; Vec and SetMut when you need to mutate.
• 🛡️ 100% type-safe — Full generic support and autocompletion in your IDE.
• 📚 Accurate Documentation — Every method is documented and tested with runnable examples. Every code example in the website (or this README) is also tested, ensuring accuracy and reliability.
• ⚡ Performance-conscious — Built on cytoolz (Cython), more-itertools, and stdlib itertools for efficiency.
• 🔄 Interoperable — Seamlessly convert to/from types with various methods like .into() and .collect()
• 🐍 Mixins traits — Extend your own classes with the methods in the mixins provided by the traits module.

Documentation

For comprehensive guides and examples:

🔍 Core Types Overview — Type overview, comparisons and visual relationships 📚 Full API Reference — Complete API documentation 📖 Examples & Cookbook — Practical patterns and recipes

Notice on Stability ⚠️

pyochain is currently in early development (< 1.0), and the API may undergo significant changes multiple times before reaching a stable 1.0 release.

Contributing

Want to contribute? Read our contributing guide

Key Dependencies and credits

Most of the computations are done with implementations from, itertools, cytoolz and more-itertools.

pyochain acts as a unifying API layer over these powerful tools.

https://github.com/pytoolz/cytoolz

https://github.com/more-itertools/more-itertools

The stubs used for the development, made by the maintainer of pyochain, can be found here:

https://github.com/OutSquareCapital/cytoolz-stubs