aleff

Algebraic effects for Python — deep and shallow, stateful, composable, multi-shot handlers.

from aleff import effect, create_handler

choose = effect("choose")
h = create_handler(choose)

@h.on(choose)
def _(k, *values):
    return sum((k(v) for v in values), [])

print(h(lambda: [choose("A", "B") + choose("C", "D")]))
# ['AC', 'AD', 'BC', 'BD']

Features

Deep handlers — effects propagate through nested function calls without annotation
Shallow handlers — handle an effect once, then delegate re-installation to the handler function; enables state machines, shift0/reset0, and strategy changes between invocations
Stateful handlers — handlers can maintain and update state across multiple effect invocations, either via mutable variables (deep) or re-installation with new state (shallow); enables get/put state, transactions, and reverse-mode AD
Multi-shot continuations — resume can be called multiple times in a single handler, enabling backtracking search, non-determinism, and other advanced patterns
Sync and async — both synchronous (Handler) and asynchronous (AsyncHandler) handlers are supported, with transparent bridging between the two
Effect composition — handler functions can perform effects themselves, dispatched to enclosing handlers; enables layered architectures and modular effect stacking
Dynamic wind — wind context manager establishes before/after guards that are re-invoked on multi-shot re-entry, with optional auto-management of context managers returned by before
Effect annotation — @effect(step1, step2) collects effect sets transitively from decorated functions
Introspection — effects(fn) and unhandled_effects(fn, h) for querying and validating effect coverage
Typed — effect parameters and return types are checked by type checkers (pyright)
No macros, no code generation — pure Python library built on greenlet and a small CPython C extension
Unsafe C-extension boundary — aleffy() can opt compatible C-extension calls into exact-point native continuation capture on supported builds

Requirements

CPython >=3.12
- Tested versions:
  - 3.12.13
  - 3.13.12
  - 3.14.3
  - 3.14.3t (free-threaded)
greenlet >= 3.3.2
Linux / macOS / Windows

Installation

# uv
uv add aleff

# pip
pip install aleff

Quick start

from aleff import effect, Effect, Resume, create_handler

# Define effects
read: Effect[[], str] = effect("read")
write: Effect[[str], int] = effect("write")

# Write business logic using effects
def run():
    s = read()
    return write(s)

# Provide handler implementations
h = create_handler(read, write)

@h.on(read)
def _read(k: Resume[str, int]):
    return k("file contents")

@h.on(write)
def _write(k: Resume[int, int], contents: str):
    print(f"writing: {contents}")
    return k(len(contents))

result = h(run)
print(result)  # 13

Multi-shot example

from aleff import effect, Effect, Handler, Resume, create_handler

choose: Effect[[int], int] = effect("choose")

h: Handler[list[int]] = create_handler(choose)

@h.on(choose)
def _choose(k: Resume[int, list[int]], n: int):
    # Resume once for each choice and collect all results
    results: list[int] = []
    for i in range(n):
        results += k(i)
    return results

def computation():
    x = choose(3)  # 0, 1, or 2
    y = choose(2)  # 0 or 1
    return [x * 10 + y]

result = h(computation)
print(result)  # [0, 1, 10, 11, 20, 21]

Effect composition

Handler functions can perform effects that are handled by enclosing handlers:

from aleff import effect, Effect, Resume, create_handler

log: Effect[[str], None] = effect("log")
parse: Effect[[str], int] = effect("parse")

# Outer handler: logging
h_log = create_handler(log)

@h_log.on(log)
def _log(k: Resume[None, int], msg: str):
    print(f"[LOG] {msg}")
    return k(None)

# Inner handler: parsing with logging
h_parse = create_handler(parse)

@h_parse.on(parse)
def _parse(k: Resume[int, int], s: str):
    log(f"parsing: {s}")       # handled by the outer handler
    return k(int(s))

result = h_log(lambda: h_parse(lambda: parse("42") + 1))
# prints: [LOG] parsing: 42
print(result)  # 43

Dynamic wind

The wind context manager establishes before/after guards around a dynamic extent. When a multi-shot continuation captured inside the with block is resumed, the before thunk is called again; when it exits, the after thunk runs.

from aleff import effect, Effect, Resume, Handler, create_handler, wind

choose: Effect[[], int] = effect("choose")
h: Handler[list[int]] = create_handler(choose)

@h.on(choose)
def _choose(k: Resume[int, list[int]]):
    return k(1) + k(2)

log: list[str] = []

def run() -> list[int]:
    with wind(lambda: log.append("before"), lambda: log.append("after")):
        return [choose() * 10]

result = h(run)
print(result)  # [10, 20]
print(log)     # ['before', 'after', 'before', 'after']

If before returns a context manager and auto_exit=True (the default), __enter__ and __exit__ are called automatically:

with wind(lambda: open("data.txt")) as ref:
    ref.unwrap().read()
# file is closed on exit

wind_range is a multi-shot-safe replacement for range() in for loops. Python's range() iterator is shared across shots and exhausted after the first; wind_range saves and restores the iterator position automatically:

with wind_range(n) as r:
    for i in r:
        v = choose()  # multi-shot safe

How it works

Effects are declared as typed values and invoked like regular function calls. A Handler intercepts these calls via greenlet-based context switching:

Business logic runs in a greenlet
When an effect is invoked, control switches to the handler
The handler processes the effect and calls resume(value) to return a value
If resume is called multiple times, each call restores a snapshot of the continuation's frames (multi-shot)
If the handler returns without calling resume, the computation is aborted (early exit)

Because handlers use greenlets (not exceptions), the control flow is:

Transparent — no yield, await, or special syntax in business logic
Non-stack-cutting — code after resume in the handler runs after the continuation completes, enabling reverse-order execution (useful for backpropagation, transactions, etc.)

Multi-shot continuations are implemented via a CPython C extension (aleff._multishot.v1._aleff) that snapshots and restores interpreter frame chains.

C-extension boundaries

When an effect is performed while a C-extension call is active, that boundary must have an Aleff continuation adapter or an explicitly audited aleffy() wrapper; otherwise Aleff emits CFrameContinuationWarning. See the Effects & Handlers documentation for the aleffy() contract.

Package structure

Package	Description
`aleff`	Default: re-exports `aleff.multishot` (multi-shot handlers)
`aleff.multishot`	Multi-shot handlers with frame snapshot/restore
`aleff.oneshot`	One-shot handlers (no C extension required)

Examples

See examples/ for demonstrations:

N-Queens — backtracking search via multi-shot continuations
Amb / Logic puzzle — Scheme-style amb operator and constraint solving (SICP Exercise 4.42)
Probability — exact discrete probability distributions via weighted multi-shot
Dependency injection — swap DB/email/logging implementations
Record/Replay — record effect results, replay without side effects
Transactions — buffer writes, commit on success, rollback on failure
Automatic differentiation — forward-mode (dual numbers) and reverse-mode (backpropagation) with the same math expressions
Shallow state machine — mutable state (get/put) and traffic light controller via shallow handler re-installation
shift/reset, shift0/reset0 — delimited continuations: deep = shift/reset, shallow = shift0/reset0, with generator example

API reference

Function / Class	Description
`effect("name")`	Create a new `Effect`
`@effect(e1, e2, ...)`	Decorate a function to declare its effects
`create_handler(*effects, shallow=False)`	Create a synchronous handler
`create_async_handler(*effects, shallow=False)`	Create an asynchronous handler
`h.on(effect)`	Register a handler function (decorator)
`h(caller)`	Run caller with the handler active
`effects(fn)`	Get the declared effect set of a function
`unhandled_effects(fn, *handlers)`	Get effects not covered by the given handlers
`Effect[P, R]`	Effect protocol (parameters `P`, return type `R`)
`Handler[V]`	Sync handler protocol
`AsyncHandler[V]`	Async handler protocol
`Resume[R, V]`	Sync continuation (`k(value) -> V`)
`ResumeAsync[R, V]`	Async continuation (`await k(value) -> V`)
`wind(before, after, *, auto_exit=True)`	Dynamic wind context manager
`wind_range(stop)` / `wind_range(start, stop, step)`	Multi-shot-safe `range()` for `for` loops
`Ref[T]`	Reference wrapper returned by `wind`; call `unwrap()` to get the value
`aleffy(func)`	Opt a compatible C-extension callable into experimental native continuation capture
`CFrameContinuationWarning`	Warning emitted when a snapshot crosses an unsupported C boundary
`enable_c_warnings()` / `disable_c_warnings()`	Enable or disable C-boundary diagnostics
`c_warnings_enabled()`	Report whether C-boundary diagnostics are active

Development

From source:

git clone https://github.com/hnmr293/aleff.git
cd aleff
uv sync

# Run tests
uv run pytest

# Run tests on all supported Python versions
./run_tests.sh

# Format
uv run ruff format

# Lint
uv run pyright

License

aleff's original code is licensed under Apache-2.0. Portions of the CPython integration and continuation adapters are derived from CPython and remain subject to PSF-2.0. See LICENSE, NOTICE, and LICENSES/CPython.txt.

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

aleff-0.5.0.tar.gz (544.0 kB view details)

Uploaded Sep 5, 2026 Source

Built Distributions

If you're not sure about the file name format, learn more about wheel file names.

The dropdown lists show the available interpreters, ABIs, and platforms. Enable javascript to be able to filter the list of wheel files.

aleff-0.5.0-cp314-cp314t-win_amd64.whl (701.0 kB view details)

Uploaded Sep 5, 2026 CPython 3.14tWindows x86-64

aleff-0.5.0-cp314-cp314t-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl (2.9 MB view details)

Uploaded Sep 5, 2026 CPython 3.14tmanylinux: glibc 2.17+ x86-64manylinux: glibc 2.28+ x86-64

aleff-0.5.0-cp314-cp314t-macosx_11_0_arm64.whl (691.6 kB view details)

Uploaded Sep 5, 2026 CPython 3.14tmacOS 11.0+ ARM64

aleff-0.5.0-cp314-cp314t-macosx_10_15_x86_64.whl (699.5 kB view details)

Uploaded Sep 5, 2026 CPython 3.14tmacOS 10.15+ x86-64

aleff-0.5.0-cp314-cp314-win_amd64.whl (677.2 kB view details)

Uploaded Sep 5, 2026 CPython 3.14Windows x86-64

aleff-0.5.0-cp314-cp314-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl (2.2 MB view details)

Uploaded Sep 5, 2026 CPython 3.14manylinux: glibc 2.17+ x86-64manylinux: glibc 2.28+ x86-64

aleff-0.5.0-cp314-cp314-macosx_11_0_arm64.whl (652.6 kB view details)

Uploaded Sep 5, 2026 CPython 3.14macOS 11.0+ ARM64

aleff-0.5.0-cp314-cp314-macosx_10_15_x86_64.whl (663.3 kB view details)

Uploaded Sep 5, 2026 CPython 3.14macOS 10.15+ x86-64

aleff-0.5.0-cp313-cp313-win_amd64.whl (669.9 kB view details)

Uploaded Sep 5, 2026 CPython 3.13Windows x86-64

aleff-0.5.0-cp313-cp313-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl (2.2 MB view details)

Uploaded Sep 5, 2026 CPython 3.13manylinux: glibc 2.17+ x86-64manylinux: glibc 2.28+ x86-64

aleff-0.5.0-cp313-cp313-macosx_11_0_arm64.whl (648.6 kB view details)

Uploaded Sep 5, 2026 CPython 3.13macOS 11.0+ ARM64

aleff-0.5.0-cp313-cp313-macosx_10_13_x86_64.whl (659.2 kB view details)

Uploaded Sep 5, 2026 CPython 3.13macOS 10.13+ x86-64

aleff-0.5.0-cp312-cp312-win_amd64.whl (669.5 kB view details)

Uploaded Sep 5, 2026 CPython 3.12Windows x86-64

aleff-0.5.0-cp312-cp312-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl (2.2 MB view details)

Uploaded Sep 5, 2026 CPython 3.12manylinux: glibc 2.17+ x86-64manylinux: glibc 2.28+ x86-64

aleff-0.5.0-cp312-cp312-macosx_11_0_arm64.whl (643.9 kB view details)

Uploaded Sep 5, 2026 CPython 3.12macOS 11.0+ ARM64

aleff-0.5.0-cp312-cp312-macosx_10_13_x86_64.whl (654.8 kB view details)

Uploaded Sep 5, 2026 CPython 3.12macOS 10.13+ x86-64

File details

Details for the file aleff-0.5.0.tar.gz.

File metadata

Download URL: aleff-0.5.0.tar.gz
Upload date: Sep 5, 2026
Size: 544.0 kB
Tags: Source
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for aleff-0.5.0.tar.gz
Algorithm	Hash digest
SHA256	`9816a2e401b84648d1a4587ba9065a9aab9cce2dba1d4f992768ba398ff126d3`
MD5	`6bb54f10838649c55acb8a9ca0cc6ff5`
BLAKE2b-256	`ff1f757a56072ebf1cf27b8d9ca444ae13045b52e8b9fbb1835d3864754c16f3`

Algorithm	Hash digest
SHA256	`79ec72247bb59ab572545296303949380e5581177ca4f5da4c83b9572632a740`
MD5	`bd3f36f3a611f9319e090252a0265bc6`
BLAKE2b-256	`58687da0f2a71c9e058776485f57543eb8e1c5c0f4607b8c70583d3af1ae55dd`

Algorithm	Hash digest
SHA256	`2cd41bfa1551eba023b7b441e10ddcee864d373cc256be65627d7dbf4b1561d2`
MD5	`5d5f58ea2ec68a829bc6c45de59a115a`
BLAKE2b-256	`9ac2d472cc89ef5383b036e62a3131422522bb60ab785ef36b03818ef32c3b0b`

Algorithm	Hash digest
SHA256	`1a35b18a0873d655864a2a120419468b021d761f08a904c44672ea43544e1c2b`
MD5	`156662bfb20344536d82772e4ae53db1`
BLAKE2b-256	`c2740d6ca197c04204a0343b1be932aeb36b6db9aad3649d98c48efafd900348`

Algorithm	Hash digest
SHA256	`15de7dc2944ae178c67bc81f5114a9823db316607838bb5e38b1eb18d682b7c1`
MD5	`53ebd458aa89db44bd5c74e43608c321`
BLAKE2b-256	`32661caf0771028060c63179b5e78c2ca25e8c90a87943dc7aeeac302ca074f0`

Algorithm	Hash digest
SHA256	`5ef976db3eef0b15ec989d102f76285e3fb8a9cbae1e910f87a2e1688920d2cd`
MD5	`3fb31e77e4249d87ba9aab3a78a81a43`
BLAKE2b-256	`88d6b69e1ecef007236554be24498105d8af2922e658cbffc289a45917f86704`

Algorithm	Hash digest
SHA256	`1ed9e43e6ce5ac3547e16de286783cfe47650445fa002ba72b8158cf3b4c285e`
MD5	`fd506f481abe20dfb090ff18460e0c46`
BLAKE2b-256	`4ec48aa3f447efccf1299a9c780dd4effc55c8dc49e4a70000dc9bfd70747963`

Algorithm	Hash digest
SHA256	`49497e7d28cfb5b00f6a59a5540701d0af4c7dec8cf3de0ad8f3e87814b84a35`
MD5	`3b98fb2eacaddce95eed59bf6ee62514`
BLAKE2b-256	`c5b1de049b64d88bb8d11ca1dbf2235f2e95e97a131af8a9a220abf700221257`

Algorithm	Hash digest
SHA256	`9b384c9fc958d1fcf36e59cf7394b56cfe38a52db894b78638fd88f7404f4b9d`
MD5	`767de270347c97edb0452f9c0d66810e`
BLAKE2b-256	`5c970ffbba89812a09fe83ba528e46a45518cd665679a6a7f46b0b13965386ad`

Algorithm	Hash digest
SHA256	`37bda2f2bc66d97aff70b80198f20ca71b8d95b7b82ce17343fb74affa1abc20`
MD5	`8e300d0ee691bda966851b4ef5fbda05`
BLAKE2b-256	`83259dae56c8cd5c765560e8e0027924dfedab7a64c0a52f494bdf7aa7d8a9b6`

Algorithm	Hash digest
SHA256	`9a935ee2f8134f90f52bc268a2f0a8b1275e43c23b411226ab3615407f5a3818`
MD5	`f2a085ad17d3cc46827badaf504ffbf4`
BLAKE2b-256	`1a45da6aeaa1a768939b6a0803ea55d3a33b4e9842a8eae4416b0d8ba70d3169`

Algorithm	Hash digest
SHA256	`6ebc6cdfd29377228c0cb659afd51045d7ee1821df44f153aafee48e91a082e3`
MD5	`0389f464c4ca8e3eca9346286f5fc9cc`
BLAKE2b-256	`9ea4a7052483b7b6d03724a1dd83ec41c1c635d3c2eff1758f034331c348e37f`

Algorithm	Hash digest
SHA256	`5f7c6792ce0a8c1961b5a98f84e7150f8291e6827e39c2c50c35acad757d89e6`
MD5	`27d66648485429a65b8a1ff5f320040f`
BLAKE2b-256	`b1d02c881eda60fa036a8b782f6459be6d45adfb7c31cb67add1d5b3b9fae0a4`

Algorithm	Hash digest
SHA256	`fb04fc3c2a03c610c8a4b098393a487ec55326b60d0dc5e95ce5a6f00101f21f`
MD5	`c4c904c8c37fa3499f99fd6e4ee4cec7`
BLAKE2b-256	`e839c5332acf216dfdb542b7a969b82187b30eda70969948583bbba940828cd3`

Algorithm	Hash digest
SHA256	`bff1fe92a6b92ddb5aa17c1ce4e641d564573d91e953852dfab7162676c5c781`
MD5	`01779b4277a104dbd545395dc722bbe7`
BLAKE2b-256	`652d95ea33dc6ecb53e0c5c076324ddc94f08de9c0f6217a3926e838dd066f59`

Algorithm	Hash digest
SHA256	`6a5abd9dd32de7b58eb5b5868f7af1e8510c098e6120a1f5a328f6dc6cca3fc4`
MD5	`750491620da8b9eb0a3d761aa949f72b`
BLAKE2b-256	`9ca8009b4358e7544f7d309a10643df663c11bc0e74cc9391127933ffef792ab`

Algorithm	Hash digest
SHA256	`73d249aaf66e284e9fdc12361780759fa656b3d96d44abb61e51ecf722930903`
MD5	`f2cf8baf767906108fd68e826933022a`
BLAKE2b-256	`a3bc29e3508c9b1f4df9cd749ab629141ba2e9026c2a0b14184257e5b90516fc`

aleff 0.5.0

aleff

Features

Requirements

Installation

Quick start

Multi-shot example

Effect composition

Dynamic wind

How it works

C-extension boundaries

Package structure

Examples

API reference

Development

License

Project links

Key dates

1 maintainer

Credits

GitHub Statistics

License expression

Requires

Tags

Classifiers

Download files

Source Distribution

Built Distributions

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance