tractor

Warning

Pre-release. This is an early prototype: APIs are unstable and will change without notice, and there are no published releases yet.

A simple, modern, type-safe actor framework for asynchronous, fault-tolerant systems.

tractor gives you isolated, single-threaded actors that communicate only by message passing on top of asyncio. Messages are ordinary typed objects, so your editor and type checker understand exactly which actor a message targets and what it replies with — no Any, no string dispatch.

Features

Type-safe messaging — Message[A, R] ties a message to the actor type A it's sent to and the reply type R it produces. ask returns R; tell returns nothing. Mismatches are caught statically.
ask / tell semantics — request/reply or fire-and-forget, plus non-blocking try_ask / try_tell and reply forwarding for delegation.
Lifecycle hooks — on_start, on_stop, and on_panic with a per-actor ControlFlow decision (stop or keep running).
Fault tolerance — panics are isolated to the actor and reported to a pluggable CrashPolicy.
Custom work sources — override step to await timers, futures, or streams alongside the inbox using the biased select.
Fully typed — ships py.typed; built around PEP 695 generics.

Requirements

Python 3.14+ (the API uses recent typing features).

Installation

Not yet published to PyPI (note that the tractor name on PyPI currently belongs to an unrelated project — do not pip install tractor expecting this library). For now, install from source:

uv add git+https://github.com/ShaneEverittM/tractor
# or
pip install git+https://github.com/ShaneEverittM/tractor

Quick start

importasynciofromdataclassesimportdataclassfromtypingimportoverridefromtractorimportActor, Context, Message, RuntimeclassCounter(Actor):
def__init__(self) ->None:
self.count=0@dataclassclassIncrement(Message[Counter, None]):
by: int=1@overrideasyncdefdispatch(self, actor: Counter, ctx: Context[Counter]) ->None:
actor.count+=self.by@dataclassclassGet(Message[Counter, int]):
@overrideasyncdefdispatch(self, actor: Counter, ctx: Context[Counter]) ->int:
returnactor.countasyncdefmain() ->None:
runtime=Runtime()
counter=runtime.spawn(Counter())
awaitruntime.tell(counter, Increment(by=3)) # fire-and-forgetawaitruntime.tell(counter, Increment())
total=awaitruntime.ask(counter, Get()) # request/reply -> intprint(total) # 4awaitcounter.stop()
if__name__=="__main__":
asyncio.run(main())

Concepts

Actor — your state lives here. Subclass it and add plain methods; lifecycle hooks (on_start/on_stop/on_panic) and step are all optional with sensible defaults.
Message[A, R] — a typed, dispatchable message. Implement dispatch to invoke the actor and produce the reply R.
Runtime — created once at startup; spawns actors and routes ask/tell. Inside a handler, use ctx.ask / ctx.tell so sender identity is carried through.
ActorRef[A] — an opaque handle to a spawned actor; the only way to address it.
CrashPolicy — observer invoked after every panic (defaults to logging).

Design notes

tractor borrows its shape from two places: kameo, a typed Rust actor library on tokio, which informs the Actor lifecycle (on_start / on_stop / on_panic) and the typed ask/tell surface; and an internal Rust actor runtime, which informs the explicit Runtime that every message passes through.

One deliberate inversion from kameo: Rust declares message handling on the actor (impl Message<M> for A, with an associated reply type); tractor declares it on the message (Message[A, R].dispatch). Python has no trait impls, so the message is the one place the actor/reply relationship can be stated once and checked everywhere. The trade-off is generic bounds: where Rust can constrain "any actor handling M1 and M2", tractor spells the single-message case with Sender[M, R] (kameo's Recipient<M>) or a signature generic over A shared by ActorRef[A] and Message[A, R], and multi-message capabilities with a common Actor base class.

This design is also why tractor requires Python 3.14+: typed messages lean on PEP 695 class-scoped generics, @override, Self, and strict variance checking — the pieces that make a statically-typed actor protocol expressible in Python at all.

Examples

See examples/ for a runnable pub/sub demo covering fanout, lifecycle hooks, and a custom step heartbeat:

python examples/pub_sub.py

Development

This repo uses uv and provides a Nix flake.

# with uv
uv sync
uv run pytest
# with Nix (provides Python 3.14 + uv, tractor installed editable)
nix develop
pytest

Build the PyPI artifacts (sdist + wheel) reproducibly with Nix:

nix build # -> ./result/{tractor-*.tar.gz, tractor-*.whl}

License

MIT © Shane Murphy

tractor

Warning

Pre-release. This is an early prototype: APIs are unstable and will change without notice, and there are no published releases yet.

A simple, modern, type-safe actor framework for asynchronous, fault-tolerant systems.

tractor gives you isolated, single-threaded actors that communicate only by message passing on top of asyncio. Messages are ordinary typed objects, so your editor and type checker understand exactly which actor a message targets and what it replies with — no Any, no string dispatch.

Features

Type-safe messaging — Message[A, R] ties a message to the actor type A it's sent to and the reply type R it produces. ask returns R; tell returns nothing. Mismatches are caught statically.
ask / tell semantics — request/reply or fire-and-forget, plus non-blocking try_ask / try_tell and reply forwarding for delegation.
Lifecycle hooks — on_start, on_stop, and on_panic with a per-actor ControlFlow decision (stop or keep running).
Fault tolerance — panics are isolated to the actor and reported to a pluggable CrashPolicy.
Custom work sources — override step to await timers, futures, or streams alongside the inbox using the biased select.
Fully typed — ships py.typed; built around PEP 695 generics.

Requirements

Python 3.14+ (the API uses recent typing features).

Installation

Not yet published to PyPI (note that the tractor name on PyPI currently belongs to an unrelated project — do not pip install tractor expecting this library). For now, install from source:

uv add git+https://github.com/ShaneEverittM/tractor
# or
pip install git+https://github.com/ShaneEverittM/tractor

Quick start

importasynciofromdataclassesimportdataclassfromtypingimportoverridefromtractorimportActor, Context, Message, RuntimeclassCounter(Actor):
def__init__(self) ->None:
self.count=0@dataclassclassIncrement(Message[Counter, None]):
by: int=1@overrideasyncdefdispatch(self, actor: Counter, ctx: Context[Counter]) ->None:
actor.count+=self.by@dataclassclassGet(Message[Counter, int]):
@overrideasyncdefdispatch(self, actor: Counter, ctx: Context[Counter]) ->int:
returnactor.countasyncdefmain() ->None:
runtime=Runtime()
counter=runtime.spawn(Counter())
awaitruntime.tell(counter, Increment(by=3)) # fire-and-forgetawaitruntime.tell(counter, Increment())
total=awaitruntime.ask(counter, Get()) # request/reply -> intprint(total) # 4awaitcounter.stop()
if__name__=="__main__":
asyncio.run(main())

Concepts

Actor — your state lives here. Subclass it and add plain methods; lifecycle hooks (on_start/on_stop/on_panic) and step are all optional with sensible defaults.
Message[A, R] — a typed, dispatchable message. Implement dispatch to invoke the actor and produce the reply R.
Runtime — created once at startup; spawns actors and routes ask/tell. Inside a handler, use ctx.ask / ctx.tell so sender identity is carried through.
ActorRef[A] — an opaque handle to a spawned actor; the only way to address it.
CrashPolicy — observer invoked after every panic (defaults to logging).

Design notes

tractor borrows its shape from two places: kameo, a typed Rust actor library on tokio, which informs the Actor lifecycle (on_start / on_stop / on_panic) and the typed ask/tell surface; and an internal Rust actor runtime, which informs the explicit Runtime that every message passes through.

One deliberate inversion from kameo: Rust declares message handling on the actor (impl Message<M> for A, with an associated reply type); tractor declares it on the message (Message[A, R].dispatch). Python has no trait impls, so the message is the one place the actor/reply relationship can be stated once and checked everywhere. The trade-off is generic bounds: where Rust can constrain "any actor handling M1 and M2", tractor spells the single-message case with Sender[M, R] (kameo's Recipient<M>) or a signature generic over A shared by ActorRef[A] and Message[A, R], and multi-message capabilities with a common Actor base class.

This design is also why tractor requires Python 3.14+: typed messages lean on PEP 695 class-scoped generics, @override, Self, and strict variance checking — the pieces that make a statically-typed actor protocol expressible in Python at all.

Examples

See examples/ for a runnable pub/sub demo covering fanout, lifecycle hooks, and a custom step heartbeat:

python examples/pub_sub.py

Development

This repo uses uv and provides a Nix flake.

# with uv
uv sync
uv run pytest
# with Nix (provides Python 3.14 + uv, tractor installed editable)
nix develop
pytest

Build the PyPI artifacts (sdist + wheel) reproducibly with Nix:

nix build # -> ./result/{tractor-*.tar.gz, tractor-*.whl}

License

MIT © Shane Murphy

tractor

Warning

Pre-release. This is an early prototype: APIs are unstable and will change without notice, and there are no published releases yet.

A simple, modern, type-safe actor framework for asynchronous, fault-tolerant systems.

tractor gives you isolated, single-threaded actors that communicate only by message passing on top of asyncio. Messages are ordinary typed objects, so your editor and type checker understand exactly which actor a message targets and what it replies with — no Any, no string dispatch.

Features

Type-safe messaging — Message[A, R] ties a message to the actor type A it's sent to and the reply type R it produces. ask returns R; tell returns nothing. Mismatches are caught statically.
ask / tell semantics — request/reply or fire-and-forget, plus non-blocking try_ask / try_tell and reply forwarding for delegation.
Lifecycle hooks — on_start, on_stop, and on_panic with a per-actor ControlFlow decision (stop or keep running).
Fault tolerance — panics are isolated to the actor and reported to a pluggable CrashPolicy.
Custom work sources — override step to await timers, futures, or streams alongside the inbox using the biased select.
Fully typed — ships py.typed; built around PEP 695 generics.

Requirements

Python 3.14+ (the API uses recent typing features).

Installation

Not yet published to PyPI (note that the tractor name on PyPI currently belongs to an unrelated project — do not pip install tractor expecting this library). For now, install from source:

uv add git+https://github.com/ShaneEverittM/tractor
# or
pip install git+https://github.com/ShaneEverittM/tractor

Quick start

importasynciofromdataclassesimportdataclassfromtypingimportoverridefromtractorimportActor, Context, Message, RuntimeclassCounter(Actor):
def__init__(self) ->None:
self.count=0@dataclassclassIncrement(Message[Counter, None]):
by: int=1@overrideasyncdefdispatch(self, actor: Counter, ctx: Context[Counter]) ->None:
actor.count+=self.by@dataclassclassGet(Message[Counter, int]):
@overrideasyncdefdispatch(self, actor: Counter, ctx: Context[Counter]) ->int:
returnactor.countasyncdefmain() ->None:
runtime=Runtime()
counter=runtime.spawn(Counter())
awaitruntime.tell(counter, Increment(by=3)) # fire-and-forgetawaitruntime.tell(counter, Increment())
total=awaitruntime.ask(counter, Get()) # request/reply -> intprint(total) # 4awaitcounter.stop()
if__name__=="__main__":
asyncio.run(main())

Concepts

Actor — your state lives here. Subclass it and add plain methods; lifecycle hooks (on_start/on_stop/on_panic) and step are all optional with sensible defaults.
Message[A, R] — a typed, dispatchable message. Implement dispatch to invoke the actor and produce the reply R.
Runtime — created once at startup; spawns actors and routes ask/tell. Inside a handler, use ctx.ask / ctx.tell so sender identity is carried through.
ActorRef[A] — an opaque handle to a spawned actor; the only way to address it.
CrashPolicy — observer invoked after every panic (defaults to logging).

Design notes

tractor borrows its shape from two places: kameo, a typed Rust actor library on tokio, which informs the Actor lifecycle (on_start / on_stop / on_panic) and the typed ask/tell surface; and an internal Rust actor runtime, which informs the explicit Runtime that every message passes through.

One deliberate inversion from kameo: Rust declares message handling on the actor (impl Message<M> for A, with an associated reply type); tractor declares it on the message (Message[A, R].dispatch). Python has no trait impls, so the message is the one place the actor/reply relationship can be stated once and checked everywhere. The trade-off is generic bounds: where Rust can constrain "any actor handling M1 and M2", tractor spells the single-message case with Sender[M, R] (kameo's Recipient<M>) or a signature generic over A shared by ActorRef[A] and Message[A, R], and multi-message capabilities with a common Actor base class.

This design is also why tractor requires Python 3.14+: typed messages lean on PEP 695 class-scoped generics, @override, Self, and strict variance checking — the pieces that make a statically-typed actor protocol expressible in Python at all.

Examples

See examples/ for a runnable pub/sub demo covering fanout, lifecycle hooks, and a custom step heartbeat:

python examples/pub_sub.py

Development

This repo uses uv and provides a Nix flake.

# with uv
uv sync
uv run pytest
# with Nix (provides Python 3.14 + uv, tractor installed editable)
nix develop
pytest

Build the PyPI artifacts (sdist + wheel) reproducibly with Nix:

nix build # -> ./result/{tractor-*.tar.gz, tractor-*.whl}

License

MIT © Shane Murphy

tractor

Warning

Pre-release. This is an early prototype: APIs are unstable and will change without notice, and there are no published releases yet.

A simple, modern, type-safe actor framework for asynchronous, fault-tolerant systems.

tractor gives you isolated, single-threaded actors that communicate only by message passing on top of asyncio. Messages are ordinary typed objects, so your editor and type checker understand exactly which actor a message targets and what it replies with — no Any, no string dispatch.

Features

Type-safe messaging — Message[A, R] ties a message to the actor type A it's sent to and the reply type R it produces. ask returns R; tell returns nothing. Mismatches are caught statically.
ask / tell semantics — request/reply or fire-and-forget, plus non-blocking try_ask / try_tell and reply forwarding for delegation.
Lifecycle hooks — on_start, on_stop, and on_panic with a per-actor ControlFlow decision (stop or keep running).
Fault tolerance — panics are isolated to the actor and reported to a pluggable CrashPolicy.
Custom work sources — override step to await timers, futures, or streams alongside the inbox using the biased select.
Fully typed — ships py.typed; built around PEP 695 generics.

Requirements

Python 3.14+ (the API uses recent typing features).

Installation

Not yet published to PyPI (note that the tractor name on PyPI currently belongs to an unrelated project — do not pip install tractor expecting this library). For now, install from source:

uv add git+https://github.com/ShaneEverittM/tractor
# or
pip install git+https://github.com/ShaneEverittM/tractor

Quick start

importasynciofromdataclassesimportdataclassfromtypingimportoverridefromtractorimportActor, Context, Message, RuntimeclassCounter(Actor):
def__init__(self) ->None:
self.count=0@dataclassclassIncrement(Message[Counter, None]):
by: int=1@overrideasyncdefdispatch(self, actor: Counter, ctx: Context[Counter]) ->None:
actor.count+=self.by@dataclassclassGet(Message[Counter, int]):
@overrideasyncdefdispatch(self, actor: Counter, ctx: Context[Counter]) ->int:
returnactor.countasyncdefmain() ->None:
runtime=Runtime()
counter=runtime.spawn(Counter())
awaitruntime.tell(counter, Increment(by=3)) # fire-and-forgetawaitruntime.tell(counter, Increment())
total=awaitruntime.ask(counter, Get()) # request/reply -> intprint(total) # 4awaitcounter.stop()
if__name__=="__main__":
asyncio.run(main())

Concepts

Actor — your state lives here. Subclass it and add plain methods; lifecycle hooks (on_start/on_stop/on_panic) and step are all optional with sensible defaults.
Message[A, R] — a typed, dispatchable message. Implement dispatch to invoke the actor and produce the reply R.
Runtime — created once at startup; spawns actors and routes ask/tell. Inside a handler, use ctx.ask / ctx.tell so sender identity is carried through.
ActorRef[A] — an opaque handle to a spawned actor; the only way to address it.
CrashPolicy — observer invoked after every panic (defaults to logging).

Design notes

tractor borrows its shape from two places: kameo, a typed Rust actor library on tokio, which informs the Actor lifecycle (on_start / on_stop / on_panic) and the typed ask/tell surface; and an internal Rust actor runtime, which informs the explicit Runtime that every message passes through.

One deliberate inversion from kameo: Rust declares message handling on the actor (impl Message<M> for A, with an associated reply type); tractor declares it on the message (Message[A, R].dispatch). Python has no trait impls, so the message is the one place the actor/reply relationship can be stated once and checked everywhere. The trade-off is generic bounds: where Rust can constrain "any actor handling M1 and M2", tractor spells the single-message case with Sender[M, R] (kameo's Recipient<M>) or a signature generic over A shared by ActorRef[A] and Message[A, R], and multi-message capabilities with a common Actor base class.

This design is also why tractor requires Python 3.14+: typed messages lean on PEP 695 class-scoped generics, @override, Self, and strict variance checking — the pieces that make a statically-typed actor protocol expressible in Python at all.

Examples

See examples/ for a runnable pub/sub demo covering fanout, lifecycle hooks, and a custom step heartbeat:

python examples/pub_sub.py

Development

This repo uses uv and provides a Nix flake.

# with uv
uv sync
uv run pytest
# with Nix (provides Python 3.14 + uv, tractor installed editable)
nix develop
pytest

Build the PyPI artifacts (sdist + wheel) reproducibly with Nix:

nix build # -> ./result/{tractor-*.tar.gz, tractor-*.whl}

License

MIT © Shane Murphy

tractor

Warning

Pre-release. This is an early prototype: APIs are unstable and will change without notice, and there are no published releases yet.

A simple, modern, type-safe actor framework for asynchronous, fault-tolerant systems.

tractor gives you isolated, single-threaded actors that communicate only by message passing on top of asyncio. Messages are ordinary typed objects, so your editor and type checker understand exactly which actor a message targets and what it replies with — no Any, no string dispatch.

Features

Type-safe messaging — Message[A, R] ties a message to the actor type A it's sent to and the reply type R it produces. ask returns R; tell returns nothing. Mismatches are caught statically.
ask / tell semantics — request/reply or fire-and-forget, plus non-blocking try_ask / try_tell and reply forwarding for delegation.
Lifecycle hooks — on_start, on_stop, and on_panic with a per-actor ControlFlow decision (stop or keep running).
Fault tolerance — panics are isolated to the actor and reported to a pluggable CrashPolicy.
Custom work sources — override step to await timers, futures, or streams alongside the inbox using the biased select.
Fully typed — ships py.typed; built around PEP 695 generics.

Requirements

Python 3.14+ (the API uses recent typing features).

Installation

Not yet published to PyPI (note that the tractor name on PyPI currently belongs to an unrelated project — do not pip install tractor expecting this library). For now, install from source:

uv add git+https://github.com/ShaneEverittM/tractor
# or
pip install git+https://github.com/ShaneEverittM/tractor

Quick start

importasynciofromdataclassesimportdataclassfromtypingimportoverridefromtractorimportActor, Context, Message, RuntimeclassCounter(Actor):
def__init__(self) ->None:
self.count=0@dataclassclassIncrement(Message[Counter, None]):
by: int=1@overrideasyncdefdispatch(self, actor: Counter, ctx: Context[Counter]) ->None:
actor.count+=self.by@dataclassclassGet(Message[Counter, int]):
@overrideasyncdefdispatch(self, actor: Counter, ctx: Context[Counter]) ->int:
returnactor.countasyncdefmain() ->None:
runtime=Runtime()
counter=runtime.spawn(Counter())
awaitruntime.tell(counter, Increment(by=3)) # fire-and-forgetawaitruntime.tell(counter, Increment())
total=awaitruntime.ask(counter, Get()) # request/reply -> intprint(total) # 4awaitcounter.stop()
if__name__=="__main__":
asyncio.run(main())

Concepts

Actor — your state lives here. Subclass it and add plain methods; lifecycle hooks (on_start/on_stop/on_panic) and step are all optional with sensible defaults.
Message[A, R] — a typed, dispatchable message. Implement dispatch to invoke the actor and produce the reply R.
Runtime — created once at startup; spawns actors and routes ask/tell. Inside a handler, use ctx.ask / ctx.tell so sender identity is carried through.
ActorRef[A] — an opaque handle to a spawned actor; the only way to address it.
CrashPolicy — observer invoked after every panic (defaults to logging).

Design notes

tractor borrows its shape from two places: kameo, a typed Rust actor library on tokio, which informs the Actor lifecycle (on_start / on_stop / on_panic) and the typed ask/tell surface; and an internal Rust actor runtime, which informs the explicit Runtime that every message passes through.

One deliberate inversion from kameo: Rust declares message handling on the actor (impl Message<M> for A, with an associated reply type); tractor declares it on the message (Message[A, R].dispatch). Python has no trait impls, so the message is the one place the actor/reply relationship can be stated once and checked everywhere. The trade-off is generic bounds: where Rust can constrain "any actor handling M1 and M2", tractor spells the single-message case with Sender[M, R] (kameo's Recipient<M>) or a signature generic over A shared by ActorRef[A] and Message[A, R], and multi-message capabilities with a common Actor base class.

This design is also why tractor requires Python 3.14+: typed messages lean on PEP 695 class-scoped generics, @override, Self, and strict variance checking — the pieces that make a statically-typed actor protocol expressible in Python at all.

Examples

See examples/ for a runnable pub/sub demo covering fanout, lifecycle hooks, and a custom step heartbeat:

python examples/pub_sub.py

Development

This repo uses uv and provides a Nix flake.

# with uv
uv sync
uv run pytest
# with Nix (provides Python 3.14 + uv, tractor installed editable)
nix develop
pytest

Build the PyPI artifacts (sdist + wheel) reproducibly with Nix:

nix build # -> ./result/{tractor-*.tar.gz, tractor-*.whl}

License

MIT © Shane Murphy

tractor

Warning

Pre-release. This is an early prototype: APIs are unstable and will change without notice, and there are no published releases yet.

A simple, modern, type-safe actor framework for asynchronous, fault-tolerant systems.

tractor gives you isolated, single-threaded actors that communicate only by message passing on top of asyncio. Messages are ordinary typed objects, so your editor and type checker understand exactly which actor a message targets and what it replies with — no Any, no string dispatch.

Features

Type-safe messaging — Message[A, R] ties a message to the actor type A it's sent to and the reply type R it produces. ask returns R; tell returns nothing. Mismatches are caught statically.
ask / tell semantics — request/reply or fire-and-forget, plus non-blocking try_ask / try_tell and reply forwarding for delegation.
Lifecycle hooks — on_start, on_stop, and on_panic with a per-actor ControlFlow decision (stop or keep running).
Fault tolerance — panics are isolated to the actor and reported to a pluggable CrashPolicy.
Custom work sources — override step to await timers, futures, or streams alongside the inbox using the biased select.
Fully typed — ships py.typed; built around PEP 695 generics.

Requirements

Python 3.14+ (the API uses recent typing features).

Installation

Not yet published to PyPI (note that the tractor name on PyPI currently belongs to an unrelated project — do not pip install tractor expecting this library). For now, install from source:

uv add git+https://github.com/ShaneEverittM/tractor
# or
pip install git+https://github.com/ShaneEverittM/tractor

Quick start

importasynciofromdataclassesimportdataclassfromtypingimportoverridefromtractorimportActor, Context, Message, RuntimeclassCounter(Actor):
def__init__(self) ->None:
self.count=0@dataclassclassIncrement(Message[Counter, None]):
by: int=1@overrideasyncdefdispatch(self, actor: Counter, ctx: Context[Counter]) ->None:
actor.count+=self.by@dataclassclassGet(Message[Counter, int]):
@overrideasyncdefdispatch(self, actor: Counter, ctx: Context[Counter]) ->int:
returnactor.countasyncdefmain() ->None:
runtime=Runtime()
counter=runtime.spawn(Counter())
awaitruntime.tell(counter, Increment(by=3)) # fire-and-forgetawaitruntime.tell(counter, Increment())
total=awaitruntime.ask(counter, Get()) # request/reply -> intprint(total) # 4awaitcounter.stop()
if__name__=="__main__":
asyncio.run(main())

Concepts

Actor — your state lives here. Subclass it and add plain methods; lifecycle hooks (on_start/on_stop/on_panic) and step are all optional with sensible defaults.
Message[A, R] — a typed, dispatchable message. Implement dispatch to invoke the actor and produce the reply R.
Runtime — created once at startup; spawns actors and routes ask/tell. Inside a handler, use ctx.ask / ctx.tell so sender identity is carried through.
ActorRef[A] — an opaque handle to a spawned actor; the only way to address it.
CrashPolicy — observer invoked after every panic (defaults to logging).

Design notes

tractor borrows its shape from two places: kameo, a typed Rust actor library on tokio, which informs the Actor lifecycle (on_start / on_stop / on_panic) and the typed ask/tell surface; and an internal Rust actor runtime, which informs the explicit Runtime that every message passes through.

One deliberate inversion from kameo: Rust declares message handling on the actor (impl Message<M> for A, with an associated reply type); tractor declares it on the message (Message[A, R].dispatch). Python has no trait impls, so the message is the one place the actor/reply relationship can be stated once and checked everywhere. The trade-off is generic bounds: where Rust can constrain "any actor handling M1 and M2", tractor spells the single-message case with Sender[M, R] (kameo's Recipient<M>) or a signature generic over A shared by ActorRef[A] and Message[A, R], and multi-message capabilities with a common Actor base class.

This design is also why tractor requires Python 3.14+: typed messages lean on PEP 695 class-scoped generics, @override, Self, and strict variance checking — the pieces that make a statically-typed actor protocol expressible in Python at all.

Examples

See examples/ for a runnable pub/sub demo covering fanout, lifecycle hooks, and a custom step heartbeat:

python examples/pub_sub.py

Development

This repo uses uv and provides a Nix flake.

# with uv
uv sync
uv run pytest
# with Nix (provides Python 3.14 + uv, tractor installed editable)
nix develop
pytest

Build the PyPI artifacts (sdist + wheel) reproducibly with Nix:

nix build # -> ./result/{tractor-*.tar.gz, tractor-*.whl}

License

tractor

Warning

Pre-release. This is an early prototype: APIs are unstable and will change without notice, and there are no published releases yet.

A simple, modern, type-safe actor framework for asynchronous, fault-tolerant systems.

tractor gives you isolated, single-threaded actors that communicate only by message passing on top of asyncio. Messages are ordinary typed objects, so your editor and type checker understand exactly which actor a message targets and what it replies with — no Any, no string dispatch.

Features

Type-safe messaging — Message[A, R] ties a message to the actor type A it's sent to and the reply type R it produces. ask returns R; tell returns nothing. Mismatches are caught statically.
ask / tell semantics — request/reply or fire-and-forget, plus non-blocking try_ask / try_tell and reply forwarding for delegation.
Lifecycle hooks — on_start, on_stop, and on_panic with a per-actor ControlFlow decision (stop or keep running).
Fault tolerance — panics are isolated to the actor and reported to a pluggable CrashPolicy.
Custom work sources — override step to await timers, futures, or streams alongside the inbox using the biased select.
Fully typed — ships py.typed; built around PEP 695 generics.

Requirements

Python 3.14+ (the API uses recent typing features).

Installation

Not yet published to PyPI (note that the tractor name on PyPI currently belongs to an unrelated project — do not pip install tractor expecting this library). For now, install from source:

uv add git+https://github.com/ShaneEverittM/tractor
# or
pip install git+https://github.com/ShaneEverittM/tractor

Quick start

importasynciofromdataclassesimportdataclassfromtypingimportoverridefromtractorimportActor, Context, Message, RuntimeclassCounter(Actor):
def__init__(self) ->None:
self.count=0@dataclassclassIncrement(Message[Counter, None]):
by: int=1@overrideasyncdefdispatch(self, actor: Counter, ctx: Context[Counter]) ->None:
actor.count+=self.by@dataclassclassGet(Message[Counter, int]):
@overrideasyncdefdispatch(self, actor: Counter, ctx: Context[Counter]) ->int:
returnactor.countasyncdefmain() ->None:
runtime=Runtime()
counter=runtime.spawn(Counter())
awaitruntime.tell(counter, Increment(by=3)) # fire-and-forgetawaitruntime.tell(counter, Increment())
total=awaitruntime.ask(counter, Get()) # request/reply -> intprint(total) # 4awaitcounter.stop()
if__name__=="__main__":
asyncio.run(main())

Concepts

Actor — your state lives here. Subclass it and add plain methods; lifecycle hooks (on_start/on_stop/on_panic) and step are all optional with sensible defaults.
Message[A, R] — a typed, dispatchable message. Implement dispatch to invoke the actor and produce the reply R.
Runtime — created once at startup; spawns actors and routes ask/tell. Inside a handler, use ctx.ask / ctx.tell so sender identity is carried through.
ActorRef[A] — an opaque handle to a spawned actor; the only way to address it.
CrashPolicy — observer invoked after every panic (defaults to logging).

Design notes

tractor borrows its shape from two places: kameo, a typed Rust actor library on tokio, which informs the Actor lifecycle (on_start / on_stop / on_panic) and the typed ask/tell surface; and an internal Rust actor runtime, which informs the explicit Runtime that every message passes through.

One deliberate inversion from kameo: Rust declares message handling on the actor (impl Message<M> for A, with an associated reply type); tractor declares it on the message (Message[A, R].dispatch). Python has no trait impls, so the message is the one place the actor/reply relationship can be stated once and checked everywhere. The trade-off is generic bounds: where Rust can constrain "any actor handling M1 and M2", tractor spells the single-message case with Sender[M, R] (kameo's Recipient<M>) or a signature generic over A shared by ActorRef[A] and Message[A, R], and multi-message capabilities with a common Actor base class.

This design is also why tractor requires Python 3.14+: typed messages lean on PEP 695 class-scoped generics, @override, Self, and strict variance checking — the pieces that make a statically-typed actor protocol expressible in Python at all.

Examples

See examples/ for a runnable pub/sub demo covering fanout, lifecycle hooks, and a custom step heartbeat:

python examples/pub_sub.py

Development

This repo uses uv and provides a Nix flake.

# with uv
uv sync
uv run pytest
# with Nix (provides Python 3.14 + uv, tractor installed editable)
nix develop
pytest

Build the PyPI artifacts (sdist + wheel) reproducibly with Nix:

nix build # -> ./result/{tractor-*.tar.gz, tractor-*.whl}

License

tractor

Warning

Pre-release. This is an early prototype: APIs are unstable and will change without notice, and there are no published releases yet.

A simple, modern, type-safe actor framework for asynchronous, fault-tolerant systems.

tractor gives you isolated, single-threaded actors that communicate only by message passing on top of asyncio. Messages are ordinary typed objects, so your editor and type checker understand exactly which actor a message targets and what it replies with — no Any, no string dispatch.

Features

Type-safe messaging — Message[A, R] ties a message to the actor type A it's sent to and the reply type R it produces. ask returns R; tell returns nothing. Mismatches are caught statically.
ask / tell semantics — request/reply or fire-and-forget, plus non-blocking try_ask / try_tell and reply forwarding for delegation.
Lifecycle hooks — on_start, on_stop, and on_panic with a per-actor ControlFlow decision (stop or keep running).
Fault tolerance — panics are isolated to the actor and reported to a pluggable CrashPolicy.
Custom work sources — override step to await timers, futures, or streams alongside the inbox using the biased select.
Fully typed — ships py.typed; built around PEP 695 generics.

Requirements

Python 3.14+ (the API uses recent typing features).

Installation

Not yet published to PyPI (note that the tractor name on PyPI currently belongs to an unrelated project — do not pip install tractor expecting this library). For now, install from source:

uv add git+https://github.com/ShaneEverittM/tractor
# or
pip install git+https://github.com/ShaneEverittM/tractor

Quick start

importasynciofromdataclassesimportdataclassfromtypingimportoverridefromtractorimportActor, Context, Message, RuntimeclassCounter(Actor):
def__init__(self) ->None:
self.count=0@dataclassclassIncrement(Message[Counter, None]):
by: int=1@overrideasyncdefdispatch(self, actor: Counter, ctx: Context[Counter]) ->None:
actor.count+=self.by@dataclassclassGet(Message[Counter, int]):
@overrideasyncdefdispatch(self, actor: Counter, ctx: Context[Counter]) ->int:
returnactor.countasyncdefmain() ->None:
runtime=Runtime()
counter=runtime.spawn(Counter())
awaitruntime.tell(counter, Increment(by=3)) # fire-and-forgetawaitruntime.tell(counter, Increment())
total=awaitruntime.ask(counter, Get()) # request/reply -> intprint(total) # 4awaitcounter.stop()
if__name__=="__main__":
asyncio.run(main())

Concepts

Actor — your state lives here. Subclass it and add plain methods; lifecycle hooks (on_start/on_stop/on_panic) and step are all optional with sensible defaults.
Message[A, R] — a typed, dispatchable message. Implement dispatch to invoke the actor and produce the reply R.
Runtime — created once at startup; spawns actors and routes ask/tell. Inside a handler, use ctx.ask / ctx.tell so sender identity is carried through.
ActorRef[A] — an opaque handle to a spawned actor; the only way to address it.
CrashPolicy — observer invoked after every panic (defaults to logging).

Design notes

tractor borrows its shape from two places: kameo, a typed Rust actor library on tokio, which informs the Actor lifecycle (on_start / on_stop / on_panic) and the typed ask/tell surface; and an internal Rust actor runtime, which informs the explicit Runtime that every message passes through.

One deliberate inversion from kameo: Rust declares message handling on the actor (impl Message<M> for A, with an associated reply type); tractor declares it on the message (Message[A, R].dispatch). Python has no trait impls, so the message is the one place the actor/reply relationship can be stated once and checked everywhere. The trade-off is generic bounds: where Rust can constrain "any actor handling M1 and M2", tractor spells the single-message case with Sender[M, R] (kameo's Recipient<M>) or a signature generic over A shared by ActorRef[A] and Message[A, R], and multi-message capabilities with a common Actor base class.

This design is also why tractor requires Python 3.14+: typed messages lean on PEP 695 class-scoped generics, @override, Self, and strict variance checking — the pieces that make a statically-typed actor protocol expressible in Python at all.

Examples

See examples/ for a runnable pub/sub demo covering fanout, lifecycle hooks, and a custom step heartbeat:

python examples/pub_sub.py

Development

This repo uses uv and provides a Nix flake.

# with uv
uv sync
uv run pytest
# with Nix (provides Python 3.14 + uv, tractor installed editable)
nix develop
pytest

Build the PyPI artifacts (sdist + wheel) reproducibly with Nix:

nix build # -> ./result/{tractor-*.tar.gz, tractor-*.whl}

Name		Name	Last commit message	Last commit date
.claude		.claude
.vscode		.vscode
examples		examples
src/tractor		src/tractor
tests		tests
.gitignore		.gitignore
CLAUDE.md		CLAUDE.md
LICENSE		LICENSE
README.md		README.md
flake.lock		flake.lock
flake.nix		flake.nix
pyproject.toml		pyproject.toml
uv.lock		uv.lock

Name		Name	Last commit message	Last commit date
.claude		.claude
.vscode		.vscode
examples		examples
src/tractor		src/tractor
tests		tests
.gitignore		.gitignore
CLAUDE.md		CLAUDE.md
LICENSE		LICENSE
README.md		README.md
flake.lock		flake.lock
flake.nix		flake.nix
pyproject.toml		pyproject.toml
uv.lock		uv.lock

Name		Name	Last commit message	Last commit date
.claude		.claude
.vscode		.vscode
examples		examples
src/tractor		src/tractor
tests		tests
.gitignore		.gitignore
CLAUDE.md		CLAUDE.md
LICENSE		LICENSE
README.md		README.md
flake.lock		flake.lock
flake.nix		flake.nix
pyproject.toml		pyproject.toml
uv.lock		uv.lock

Name		Name	Last commit message	Last commit date
.claude		.claude
.vscode		.vscode
examples		examples
src/tractor		src/tractor
tests		tests
.gitignore		.gitignore
CLAUDE.md		CLAUDE.md
LICENSE		LICENSE
README.md		README.md
flake.lock		flake.lock
flake.nix		flake.nix
pyproject.toml		pyproject.toml
uv.lock		uv.lock

Name		Name	Last commit message	Last commit date
.claude		.claude
.vscode		.vscode
examples		examples
src/tractor		src/tractor
tests		tests
.gitignore		.gitignore
CLAUDE.md		CLAUDE.md
LICENSE		LICENSE
README.md		README.md
flake.lock		flake.lock
flake.nix		flake.nix
pyproject.toml		pyproject.toml
uv.lock		uv.lock

Latest commit

History

Folders and files

Repository files navigation

tractor

Features

Requirements

Installation

Quick start

Concepts

Design notes

Examples

Development

License

About

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages

Latest commit

History

Folders and files

Repository files navigation

tractor

Features

Requirements

Installation

Quick start

Concepts

Design notes

Examples

Development

License

About

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages

Latest commit

History

Folders and files

Repository files navigation

tractor

Features

Requirements

Installation

Quick start

Concepts

Design notes

Examples

Development

License

About

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages

Latest commit

History

Folders and files

Repository files navigation

tractor

Features

Requirements

Installation

Quick start

Concepts

Design notes