wove

Most application code should import from wove. The package-level API names the stable entrypoints for declaring a weave, configuring execution environments, handling public exceptions, and using the helper functions that are meant to sit inside task code.

Primary Entrypoints

• weave: the context manager factory used as with weave() as w:.

• Weave: base class for reusable and inheritable workflow definitions.

• config: process-wide runtime configuration function.

• merge: runs external callables from inside a weave task, with the same execution options as @w.do(...).

Public Runtime Types

• WoveResult: result object returned by completed weaves.

• EnvironmentExecutor: executor interface for custom execution environments.

• BackendAdapterEnvironmentExecutor: executor wrapper used by built-in backend adapters.

• HttpEnvironmentExecutor: direct HTTP/HTTPS network executor.

• GrpcEnvironmentExecutor: generic unary gRPC network executor.

• WebSocketEnvironmentExecutor: bidirectional WebSocket network executor.

• NetworkExecutorSecurity: request signing and verification helper for network executors.

• BackendAdapter: base interface for backend-specific adapters.

Public Exceptions

• MissingDispatchFeatureError: dispatch-only feature was used without wove[dispatch].

• DeliveryTimeoutError: backend delivery or heartbeat timeout.

• DeliveryOrphanedError: pending backend work became orphaned during shutdown handling.

Helpers

Import common data-shaping helpers from the package root when glue code would otherwise distract from the task graph: sync_to_async, flatten, fold, batch, undict, redict, and denone.

API Details

Wove.

Inline task orchestration for Python code that needs concurrent work without restructuring the surrounding function around an event loop. Wove keeps the workflow in ordinary Python: define tasks where the result is needed, let dependencies come from function signatures, and route selected work through named environments when it belongs in another process or service.

class wove.BackendAdapterEnvironmentExecutor(name, adapter_class=None, required_modules=None)

Bases: EnvironmentExecutor

Executor that submits Wove task payloads to a backend adapter and receives worker frames over a callback server.

Parameters:

• name (str)

• adapter_class (Type[BackendAdapter] | None)

• required_modules (Tuple[str, ...] | None)

async recv()

Receive one event frame.

Return type:

Dict[str, Any]

async send(frame)

Send one command frame.

Parameters:

frame (Dict[str, Any])

Return type:

None

async start(*, environment_name, environment_config, run_config)

Initialize a run/session for this executor.

Parameters:

• environment_name (str)

• environment_config (Dict[str, Any])

• run_config (Dict[str, Any])

Return type:

None

async stop()

Stop the executor session and clean up resources.

Return type:

None

exception wove.DeliveryOrphanedError

Bases: RuntimeError

Raised when a backend run becomes orphaned during runtime shutdown/failure handling.

exception wove.DeliveryTimeoutError

Bases: RuntimeError

Raised when backend delivery does not complete within configured delivery_timeout.

class wove.EnvironmentExecutor

Bases: ABC

CGI-like stream transport contract for environment executors.

abstractmethod async recv()

Receive one event frame.

Return type:

Dict[str, Any]

abstractmethod async send(frame)

Send one command frame.

Parameters:

frame (Dict[str, Any])

Return type:

None

abstractmethod async start(*, environment_name, environment_config, run_config)

Initialize a run/session for this executor.

Parameters:

• environment_name (str)

• environment_config (Dict[str, Any])

• run_config (Dict[str, Any])

Return type:

None

abstractmethod async stop()

Stop the executor session and clean up resources.

Return type:

None

class wove.GrpcEnvironmentExecutor

Bases: EnvironmentExecutor

Network executor that sends Wove frames through a generic gRPC method.

async recv()

Receive one event frame.

Return type:

Dict[str, Any]

async send(frame)

Send one command frame.

Parameters:

frame (Dict[str, Any])

Return type:

None

async start(*, environment_name, environment_config, run_config)

Initialize a run/session for this executor.

Parameters:

• environment_name (str)

• environment_config (Dict[str, Any])

• run_config (Dict[str, Any])

Return type:

None

async stop()

Stop the executor session and clean up resources.

Return type:

None

class wove.HttpEnvironmentExecutor(*, require_https=False)

Bases: EnvironmentExecutor

Network executor that sends Wove frames to a worker service over HTTP or HTTPS.

Parameters:

require_https (bool)

async recv()

Receive one event frame.

Return type:

Dict[str, Any]

async send(frame)

Send one command frame.

Parameters:

frame (Dict[str, Any])

Return type:

None

async start(*, environment_name, environment_config, run_config)

Initialize a run/session for this executor.

Parameters:

• environment_name (str)

• environment_config (Dict[str, Any])

• run_config (Dict[str, Any])

Return type:

None

async stop()

Stop the executor session and clean up resources.

Return type:

None

exception wove.MissingDispatchFeatureError(reason)

Bases: RuntimeError

Raised when a dispatch feature is used without optional dispatch dependencies.

Parameters:

reason (str)

Return type:

None

class wove.NetworkExecutorSecurity(*, mode='none', secret=None, key='default', token=None, clock_skew_seconds=300.0, remember_nonces=True)

Bases: object

Authentication helper for Wove network executors.

Parameters:

• mode (str)

• secret (Any | None)

• key (str)

• token (str | None)

• clock_skew_seconds (float)

• remember_nonces (bool)

classmethod from_config(config)

Build network executor security from an executor security config value.

Parameters:

config (Any)

Return type:

NetworkExecutorSecurity

headers_for(*, transport, target, body)

Return HTTP/WebSocket headers for one outbound network executor request.

Parameters:

• transport (str)

• target (str)

• body (bytes)

Return type:

Dict[str, str]

metadata_for(*, transport, target, body)

Return lowercase gRPC metadata pairs for one outbound network executor request.

Parameters:

• transport (str)

• target (str)

• body (bytes)

Return type:

Tuple[Tuple[str, str], …]

verify_headers(*, headers, transport, target, body)

Verify HTTP/WebSocket network executor request headers.

Parameters:

• headers (Mapping[str, Any])

• transport (str)

• target (str)

• body (bytes)

Return type:

None

verify_metadata(*, metadata, transport, target, body)

Verify gRPC network executor request metadata.

Parameters:

• metadata (Iterable[Tuple[str, Any]])

• transport (str)

• target (str)

• body (bytes)

Return type:

None

class wove.Weave

Bases: object

A base class for creating inheritable, reusable workflows.

Tasks are defined as methods using the @Weave.do decorator. These workflows can then be passed to the weave context manager and customized inline.

static do(arg=None, *, retries=None, timeout=None, workers=None, limit_per_minute=None, environment=None, delivery_timeout=None, delivery_idempotency_key=None, delivery_cancel_mode=None, delivery_heartbeat_seconds=None, delivery_max_in_flight=None, delivery_orphan_policy=None)

A decorator for defining a task within a Weave class.

This is the class-based equivalent of the @w.do decorator used inside a weave block. It accepts the same parameters.

Parameters:

• arg (Callable | str | Iterable | None)

• retries (int | None)

• timeout (float | None)

• workers (int | None)

• limit_per_minute (int | None)

• environment (str | None)

• delivery_timeout (float | None)

• delivery_idempotency_key (object | None)

• delivery_cancel_mode (str | None)

• delivery_heartbeat_seconds (float | None)

• delivery_max_in_flight (int | None)

• delivery_orphan_policy (str | None)

Return type:

Callable

class wove.WebSocketEnvironmentExecutor

Bases: EnvironmentExecutor

Network executor that exchanges Wove frames with a worker service over WebSocket.

async recv()

Receive one event frame.

Return type:

Dict[str, Any]

async send(frame)

Send one command frame.

Parameters:

frame (Dict[str, Any])

Return type:

None

async start(*, environment_name, environment_config, run_config)

Initialize a run/session for this executor.

Parameters:

• environment_name (str)

• environment_config (Dict[str, Any])

• run_config (Dict[str, Any])

Return type:

None

async stop()

Stop the executor session and clean up resources.

Return type:

None

class wove.WoveResult(error_mode='raise')

Bases: object

A container for the results of a weave block. Supports dictionary-style access by task name, unpacking in definition order, and a .final shortcut to the last-defined task’s result.

Parameters:

error_mode (str)

property cancelled: Set[str]

Returns a set of the names of all cancelled tasks.

property final: Any

Returns the result of the last task defined in the weave block. If the task failed, its exception is raised. :returns: The result of the final task, or None if no tasks were defined.

wove.batch(a_list, count)

Converts a 1D list into count smaller lists of N length.

wove.config(*, config_file=None, default_environment=None, environments=None, max_workers=None, background=None, fork=None, retries=None, timeout=None, workers=None, limit_per_minute=None, max_pending=None, error_mode=None, delivery_timeout=None, delivery_idempotency_key=None, delivery_cancel_mode=None, delivery_heartbeat_seconds=None, delivery_max_in_flight=None, delivery_orphan_policy=None)

Configure process-wide Wove runtime behavior.

Calling wove.config() with no args attempts to autoload wove_config.py from the current working directory or one of its parents.

Parameters:

• config_file (str | None)

• default_environment (str | None)

• environments (Dict[str, Dict[str, Any]] | None)

• max_workers (int | None)

• background (bool | None)

• fork (bool | None)

• retries (int | None)

• timeout (float | None)

• workers (int | None)

• limit_per_minute (int | None)

• max_pending (int | None)

• error_mode (str | None)

• delivery_timeout (float | None)

• delivery_idempotency_key (Any | None)

• delivery_cancel_mode (str | None)

• delivery_heartbeat_seconds (float | None)

• delivery_max_in_flight (int | None)

• delivery_orphan_policy (str | None)

Return type:

RuntimeConfig

wove.denone(an_iterable)

Removes all None values from an iterable.

wove.flatten(list_of_lists)

Converts a 2D iterable into a 1D list.

wove.fold(a_list, size)

Converts a 1D list into N smaller lists of size length.

wove.merge(callable, iterable=None, *, retries=None, timeout=None, workers=None, limit_per_minute=None, environment=None, delivery_timeout=None, delivery_idempotency_key=None, delivery_cancel_mode=None, delivery_heartbeat_seconds=None, delivery_max_in_flight=None, delivery_orphan_policy=None)

Execute a callable from within a running Wove task.

Parameters

callable

The async or sync callable to execute.

iterable

Optional iterable. When provided, callable is executed for each item (similar to @w.do(iterable) behavior).

retries, timeout, workers, limit_per_minute, environment, delivery_*

The same execution options accepted by @w.do.

Returns

Any

The callable result, or a list of results when iterable is provided.

Raises

RuntimeError

If called outside of an active weave context.

Parameters:

• callable (Callable[[...], Any])

• iterable (Iterable[Any] | None)

• retries (int | None)

• timeout (float | None)

• workers (int | None)

• limit_per_minute (int | None)

• environment (str | None)

• delivery_timeout (float | None)

• delivery_idempotency_key (Any | None)

• delivery_cancel_mode (str | None)

• delivery_heartbeat_seconds (float | None)

• delivery_max_in_flight (int | None)

• delivery_orphan_policy (str | None)

Return type:

Any

wove.redict(list_of_pairs)

Converts a list of key-value pairs back into a dictionary.

wove.sync_to_async(func)

Wraps a synchronous function to run in an executor.

By default, it uses asyncio’s default thread pool, but if called from within a weave context, it will use the dedicated executor for that context. This prevents deadlocks when a weave block is used inside another system that also manages the default executor (like Quart).

Parameters:

func (Callable[[...], R]) – The synchronous function to wrap.

Returns:

An awaitable coroutine function that executes the original function in a separate thread.

Return type:

Callable[[…], Coroutine[Any, Any, R]]

wove.undict(a_dict)

Converts a dictionary into a list of [key, value] pairs.

wove.weave

alias of WoveContextManager