Beautiful Python async.
What is Wove For?
Wove is for running high latency async tasks like web requests and database queries concurrently in the same way as asyncio, but with a drastically improved user experience.
Improvements compared to asyncio include:
- Reads Top-to-Bottom: The workflow is declared in the order it runs, inline with the code that needs the result.
- Implicit Parallelism: Parallelism and execution order are implicit based on function and parameter naming.
- Sync or Async: Mix
async defanddeffreely without restructuring the call site around one concurrency style. - Normal Python Data: Task outputs behave like normal Python values without making you manage shared mutable state.
- Automatic Scheduling: Wove builds a dependency graph from your task signatures and runs independent tasks concurrently as soon as possible.
- Automatic Detachment: Run inline workflows outside the current request, command, or worker when waiting would be the wrong user experience.
- Remote Task Environments: Keep quick work local while sending selected long-running or infrastructure-heavy tasks to your worker service, queue, workflow engine, cluster, or scheduler.
- Extensibility: Define parallelized workflow templates that can be overridden inline.
- High Visibility: Wove includes debugging tools that allow you to identify where exceptions and deadlocks occur across parallel tasks, and inspect inputs and outputs at each stage of execution.
- Minimal Boilerplate: Get started with just the
with weave() as w:context manager and the@w.dodecorator. - Fast: Wove has low overhead and internally uses
asyncio, so performance is comparable to usingthreadingorasynciodirectly. - Free Threading Compatible: Running a modern GIL-less Python? Build true multithreading without changing the workflow shape.
- Zero Required Dependencies: Core Wove installs without third-party packages. Serialization, networking, and backend libraries are only needed when a workflow opts into features that use them.
Install
Install Wove with uv:
uv add wove
Or with pip:
pip install wove
Streamline Your Async
The core of Wove's functionality is the weave context manager. A weave block collects task functions and runs them when Python exits the block. Wove builds a dependency graph from task function signatures: when a task parameter has the same name as another task, Wove passes that upstream task's result into the parameter. Independent tasks run concurrently, dependent tasks wait for their named inputs, and the final task result is available at w.result.final.
import time from wove import weave with weave() as w: # These first two tasks run concurrently. @w.do def magic_number(): time.sleep(1.0) return 42 @w.do def important_text(): time.sleep(1.0) return "The meaning of life" # This task depends on the first two. It runs only after both are complete. @w.do def combined(important_text, magic_number): return f"{important_text} is {magic_number}!" # When the `with` block closes, all tasks are executed. print(w.result.final) # >> The meaning of life is 42! print(f"The magic number was {w.result.magic_number}") # >> The magic number was 42 print(f'The important text was "{w.result["important_text"]}"') # >> The important text was "The meaning of life"
There's Much More Inside
The full documentation includes topic guides, API reference pages, and more.
Topics
Start with the smallest useful weave, then add the things real workflows need as they grow: fanout, task policy, reuse, helper glue, failure handling, observability, background work, remote execution, and production patterns.
- The Basics: the core
weave()and@w.doworkflow. - Task Mapping: running one task or helper callable across many inputs and collecting the results.
- Task Quality of Life: task options that replace retry, timeout, fanout, and routing boilerplate.
- Inheritable Weaves: reusable workflow templates with inline overrides.
- Helper Functions: small data-shaping tools that keep task glue readable.
- Error Handling: how task, background, and remote delivery failures surface.
- Debugging & Introspection: graph, timing, mapping, and failure inspection.
- Background Processing: running a whole weave after the caller continues.
- Remote Task Environments: sending selected tasks to other processes, services, queues, clusters, or schedulers.
- Patterns For Production: common production workflow shapes built from Wove's core task, mapping, policy, background, and remote-execution building blocks.
Reference
Definitions of the public surface of Wove: imports, configuration shape, environment resolution, executor contracts, network executors, and backend adapter setup. Reference pages answer what each feature accepts, returns, guarantees, and raises.
Core Behavior
Core behavior covers the names and runtime rules that everything else builds on: imports, environment resolution, and the guarantees Wove keeps before any executor-specific or adapter-specific behavior is involved.
- Public API: stable imports most users should rely on.
- Environments: persistent execution profiles, defaults, and precedence rules.
- Executors: delivery interfaces for local, subprocess, and direct network execution.
- Backend Adapters: bridges from Wove tasks into existing task systems, queues, clusters, and schedulers.
Runtime Modules
Runtime module references connect public concepts back to the objects that implement and enforce them.
wove.runtime: process-widewove.config(...)behavior.wove.environment: executor interfaces, runtime delivery errors, and executor runtime classes.wove.backend: backend callback transport and dispatch payload helpers.wove.integrations: adapter registry, adapter base interface, and worker entrypoints.
Executors
Executors are the delivery layer for Wove environments. They carry task frames to local execution, subprocess workers, or direct worker services over HTTP, gRPC, and WebSocket while keeping result collection attached to the weave.
Backend Adapters
Backend adapters are separate from direct executors because an existing task system owns delivery behavior: queueing, scheduling, retries, worker placement, or batch execution. They let a Wove task enter infrastructure the project already runs while Wove keeps the task result attached to the local weave.
Version History
Wove's version history records the major and minor release series. Patch releases are not listed separately unless they change the shape of a series.
- 2.0.0: remote task environments and the new execution-environment layer.
- 1.0.0: stable local inline concurrency and background processing.
- 0.3.0: reusable weave classes, richer task controls, and helpers.
- 0.2.0: dynamic task mapping and executor management.
- 0.1.0: initial public release.
Benchmarks
Wove has low overhead and internally uses asyncio, so its performance is comparable to using threading or asyncio directly. The benchmark script below is available in the /examples directory.
$ python examples/benchmark.py Starting performance benchmarks... Number of tasks: 200 CPU load iterations per task: 100000 I/O sleep duration per task: 0.1s =================================== --- Running Threading Benchmark --- Threading total time: 0.6978 seconds ----------------------------------- --- Running Asyncio Benchmark --- Asyncio total time: 0.6831 seconds ----------------------------------- --- Running Wove Benchmark --- Wove timing details: - data: 0.5908s - planning: 0.0001s - tier_1_execution: 0.6902s - tier_1_post_execution: 0.0000s - tier_1_pre_execution: 0.0004s - wove_task: 0.6882s Wove total time: 0.6937 seconds ----------------------------------- --- Running Wove Async Benchmark --- Wove Async timing details: - data: 0.5515s - planning: 0.0000s - tier_1_execution: 0.6550s - tier_1_post_execution: 0.0000s - tier_1_pre_execution: 0.0004s - wove_async_task: 0.6534s Wove Async total time: 0.6571 seconds ----------------------------------- Benchmarks finished.