toolz

1.1.0 · maintenance · verified Sat Mar 28

toolz is a Python library providing a collection of utility functions for iterators, functions, and dictionaries, extending Python's standard `itertools` and `functools`. It promotes a functional programming style with features like composable, pure, and lazy operations. The current version is 1.1.0, and while the project is alive and maintained for critical bug fixes and Python version bumps, it is generally considered 'inactive' by its maintainers, who view it as mostly complete.

Warnings

gotcha Many functions, especially within `itertoolz`, are 'lazy operators' and return iterators. Their results are not computed until explicitly consumed (e.g., by wrapping with `list()`, `tuple()`, or iterating over them). Expecting immediate list-like results without explicit conversion can lead to unexpected behavior or empty outputs.
Fix: Always wrap lazy function calls with `list()`, `tuple()`, or iterate over them if an immediate, concrete collection is required, e.g., `my_list = list(toolz.itertoolz.filter(predicate, sequence))`.
gotcha `toolz` has a high-performance Cython-based counterpart called `cytoolz`. If performance is critical, `cytoolz` is a drop-in replacement that offers the same API with C-optimized speed.
Fix: To use the faster implementation, `pip install cytoolz`. Ensure `cytoolz` is installed in your environment, and `toolz` functions will often defer to the Cython versions if available.
breaking As of version 1.1.0, `toolz` officially dropped support for Python 3.8 and PyPy 3.8.
Fix: Upgrade your Python environment to Python 3.9 or newer. For projects requiring Python 3.8, use an older `toolz` version (e.g., 1.0.0 or earlier).
deprecated The `toolz` project is described as 'alive but inactive' by its maintainers. While critical bug fixes and Python version bumps are addressed, active feature development and review of new contributions are not a primary focus, as the library is considered 'mostly complete'.
Fix: Be aware that new features or significant API changes are unlikely. Rely on the existing, stable API. Contribute bug fixes or compatibility updates if needed, but major feature proposals might not be integrated.

Install

pip install toolz Install stable version

Imports

compose
```
from toolz import compose
```
Commonly imported directly for function composition.
frequencies
```
from toolz import frequencies
```
A useful function for counting element occurrences.
map
```
from toolz.curried import map
```
The `map` in `toolz.curried` is pre-curried, allowing partial application. The top-level `toolz.map` behaves like Python 3's built-in `map` (lazy iterator), which might be confused with Python 2's eager `map`.
groupby
```
from toolz.itertoolz import groupby
```
Functions from `itertoolz`, `functoolz`, and `dicttoolz` can be imported from their specific submodules or accessed via a general `import toolz`.

Quickstart

This example demonstrates how to build a word counting function using `compose`, `frequencies`, and the curried `map` from `toolz` to process a sentence.

from toolz import compose, frequencies
from toolz.curried import map

def stem(word):
    """ Stem word to primitive form """
    return word.lower().rstrip(",.!:;'-\"").lstrip("'\"")

wordcount = compose(frequencies, map(stem), str.split)
sentence = "This cat jumped over this other cat!"
result = wordcount(sentence)

print(result)
# Expected: {'this': 2, 'cat': 2, 'jumped': 1, 'over': 1, 'other': 1}

view raw JSON →