jaraco.functools

jaraco.functools is a small, widely-depended-on Python library that extends the stdlib functools module with decorators for method caching, throttling, retrying, function composition, and argument transformation. It is one of the foundational ‘jaraco’ namespace packages maintained by Jason R. Coombs, and is pulled in transitively by many popular packages (including setuptools and keyring) as a lightweight dependency.

The library favors small, composable, well-tested decorators over a large framework surface, making it easy to adopt piecemeal without committing to a particular architecture.

What You Get

• method_cache for per-instance memoization of instance methods (unlike functools.lru_cache, which leaks across instances)
• retry and retry_call decorators for automatic retry-with-backoff semantics
• compose for chaining multiple callables into a single function
• pass_none and none_as for cleanly handling optional/None arguments without boilerplate checks
• Throttler class for rate-limiting repeated calls to a function

Common Use Cases

• Caching expensive per-instance computed properties without cross-instance cache leakage
• Wrapping flaky I/O calls (network, filesystem) with retry logic
• Composing small transform functions into a single pipeline callable
• Building other jaraco/setuptools-ecosystem packages that need lightweight functional utilities

Under The Hood

Architecture - The entire library lives in a single jaraco/functools/__init__.py module (~770 lines) organized as a flat collection of independent decorator functions and one Throttler class, deliberately avoiding cross-function coupling so utilities can be imported individually. Tech Stack - Pure Python with a single runtime dependency (more_itertools), built with the modern coherent.licensed build backend declared in pyproject.toml, and distributed under the MIT license. Code Quality - Tested via test_functools.py using pytest, linted with Ruff, type-checked via mypy.ini, and following the jaraco ‘skeleton’ project template shared across Jason Coombs’ many packages, giving it consistent CI, changelog (towncrier), and release tooling. API Design - Each utility is a small, independently-importable decorator with a narrow, predictable contract (e.g., pass_none only changes None-handling, compose only chains callables), which keeps the learning curve low despite sparse standalone documentation beyond docstrings and the changelog.