wove 2.0.2

Inline task orchestration for Python

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 def and def freely 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.do decorator.
• Fast: Wove has low overhead and internally uses asyncio, so performance is comparable to using threading or asyncio directly.
• 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

Documentation

The full documentation includes topic guides, API reference pages, executor setup, backend adapter setup, and version history.

View Documentation

Topics

The topic path starts with the smallest useful weave, then adds 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.do workflow.
• 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

Reference material pins down 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 once the workflow shape is already clear.

Core Behavior

Core behavior covers the names and runtime rules that everything else builds on: stable 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-wide wove.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.

• Executors
  • Local Executor
  • Stdio Executor
  • HTTP/HTTPS Executor
  • gRPC Executor
  • WebSocket Executor
  • Custom Executors

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.

• Backend Adapters
  • Celery
  • Temporal
  • Ray
  • RQ
  • Taskiq
  • ARQ
  • Dask
  • Kubernetes Jobs
  • AWS Batch
  • Slurm
  • Custom Backend Adapters

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.