ohra

Apache Pekko Typed actors on asyncio, for Python 3.12+. No dependencies. Ohra is Finnish for barley, the crop of Pekko, the Finnish god of barley and brewing.

ohra is an independent project, built on the design of Apache Pekko and, before it, Akka, with thanks to both communities. It follows their semantics and names closely, but it is not part of the Apache Software Foundation.

An actor is a function from a message to the next behavior. Typed refs make wrong messages a type error under pyright strict. Everything runs on one event loop, so a handler can await without losing the guarantee that an actor handles one message at a time. numpy work goes to threads and comes back as a message. ohra.testkit, Pekko's test kit, tests actors with probes and fires timers on a manual clock.

import asyncio
from dataclasses import dataclass
from ohra import ActorRef, ActorSystem, Behavior, Behaviors


@dataclass(frozen=True)
class Increment:
    by: int


@dataclass(frozen=True)
class GetTotal:
    reply_to: ActorRef[int]


type Command = Increment | GetTotal


def counter(total: int = 0) -> Behavior[Command]:
    @Behaviors.receive_message
    def on_message(msg: Command) -> Behavior[Command]:
        match msg:
            case Increment(by):
                return counter(total + by)  # state is the next behavior
            case GetTotal(reply_to):
                reply_to.tell(total)
                return Behaviors.same

    return on_message


async def main() -> None:
    async with ActorSystem(counter(), "demo") as system:
        system.tell(Increment(5))
        print(await system.ask(GetTotal, timeout=1))  # 5


if __name__ == "__main__":
    asyncio.run(main())

If you know Apache Pekko or Akka Typed, the names are the same in snake_case, and the semantics are checked against the Apache Pekko source. If you don't, the book explains everything from the first actor to a sharded web app on Kubernetes.

Install

pip install ohra               # the library
pip install 'ohra[numpy]'      # plus numpy, for ohra.ext.shm and the examples that use it
pip install 'ohra[web]'        # plus FastAPI and uvicorn, for ohra.ext.fastapi and the fastapi_* examples
pip install 'ohra[postgres]'   # plus psycopg, for ohra.ext.postgres, the durable state store for clusters
pip install 'ohra[torch]'      # plus PyTorch, for the purchase predictor example
pip install 'ohra[numba]'      # plus numba, for compiled loops in threads and examples/stockouts.py
pip install 'ohra[testkit]'    # plus pytest and pytest-asyncio, for ohra.testkit and its pytest fixtures

The examples and tests live in the repository, not the package. To run them, clone it and install it in editable mode, with the dev extra for pytest, pytest-asyncio, pyright, httpx and ruff:

git clone https://github.com/hanishi/ohra.git && cd ohra
pip install -e '.[dev,numpy,web,postgres,torch,numba,testkit]'   # or: uv sync --all-extras

Testing

ohra.testkit is Apache Pekko's actor test kit: a test probe stands in for the actor on the other end, and manual time fires timers without waiting for them. Install 'ohra[testkit]', then turn on the pytest plugin in conftest.py and pytest-asyncio's auto mode in pyproject.toml:

# conftest.py
pytest_plugins = ["ohra.testkit.pytest_plugin"]

[tool.pytest.ini_options]
asyncio_mode = "auto"

A test for the counter above, saved as counter.py:

from counter import GetTotal, Increment, counter
from ohra.testkit import ActorTestKit, TestProbe


async def test_counter_adds_up(testkit: ActorTestKit):
    ref = testkit.spawn(counter())
    probe: TestProbe[int] = testkit.create_test_probe()
    ref.tell(Increment(2))
    ref.tell(Increment(3))
    ref.tell(GetTotal(probe.ref))
    await probe.expect_message(5)

The testkit fixture gives each test its own actor system and shuts it down afterwards. probe.ref goes where the actor replies, and expect_message waits up to 3 seconds for the next message, failing with expected 5, found 4 or timeout (3s) during expect_message while waiting for 5. Mark a test @pytest.mark.manual_time and its manual_time fixture moves the clock: await manual_time.time_passes(3600) fires an hour-long timer at once. Chapter 12 has the full guide and recipes for DeathWatch, restarts, backoff, persistence and sharding; the tests in examples/testing/ run with pytest examples/testing.

The book

How ohra works is the guide and the reference, one chapter per layer, with diagrams:

1. Actors: behaviors, ask, children and DeathWatch, supervision, timers and stash, routers, the runtime model
2. The actor system: guardians, extensions, the receptionist, coordinated shutdown
3. Persistence: write, then install, then reply; recovery in one read
4. Remoting: addresses, @remotable messages, connections
5. Cluster membership: gossip, the member lifecycle, failure detection, the split-brain resolver
6. Cluster singleton: one actor on the oldest member, and the hand-over
7. Sharding: regions, shards and the coordinator, in one process and across nodes
8. Management and Kubernetes: health checks, bootstrap, discovery, running on Docker Desktop
9. FastAPI: the actor system owned by the app, routes that ask actors
10. numpy and shared memory: blocking work in a thread, loops compiled with numba, large arrays to another process without a copy
11. Putting it together: one cart request through every layer
12. Testing: the test kit, probes, manual time for timers, pytest fixtures

Appendices: Apache Pekko names, known deviations from Apache Pekko, performance, and a glossary.

Examples

bandit, compute, batching, population and shared_memory need numpy: uv run --extra numpy python examples/bandit.py. The fastapi_* examples need the web extra and run under uvicorn: uv run --extra web uvicorn examples.fastapi_carts:app --port 8000.

Development

Layout follows Apache Pekko's modules: ohra is the actor core, ohra.remote the transport and serialization, ohra.cluster membership and the singleton, ohra.cluster.sharding the Shard, region and coordinator, ohra.ext the FastAPI, Postgres and shared-memory integrations, ohra.testkit the test kit. Every public name is importable from ohra and from its own subpackage, except the test kit's, which come from ohra.testkit only.

pytest      # every test fails if any asyncio task outlives it
pyright     # strict; tests/typing_check.py asserts type errors that must occur

See CONTRIBUTING.md for setup, the runtime invariants and how to port from Apache Pekko. Report vulnerabilities as described in SECURITY.md.

License

Apache-2.0, the same as Apache Pekko. The chat room and interaction-pattern examples are derived from the Apache Pekko documentation; see NOTICE.

ohra is an independent project, not affiliated with or endorsed by the Apache Software Foundation or the Apache Pekko project. Apache Pekko is a trademark of the Apache Software Foundation.