Skip to main content

aionode

Lightweight asyncio task tracking as call tree and DAG.

Installation

pip install aionode

Quick Start

import asyncio
import aionode

async def fetch_data() -> list[int]:
    await asyncio.sleep(1)
    return list(range(100))

async def process(data: list[int]) -> int:
    await asyncio.sleep(0.5)
    return sum(data)

async def pipeline() -> None:
    async with asyncio.TaskGroup() as tg:
        fetch = tg.create_task(aionode.node(fetch_data)(), name="fetch")
        tg.create_task(aionode.node(process)(aionode.resolve(fetch)), name="process")

async def main() -> None:
    root = asyncio.create_task(aionode.node(pipeline)(), name="pipeline")
    await root
    for info in aionode.walk_dag():
        print(f"{info.name}: {info.status} ({info.duration():.2f}s)")

asyncio.run(main())

Core Concepts

node(func, wait_for=[], track=True, auto_progress=True)

Wraps an async function as a DAG node. Use resolve() to pass awaitables as arguments — they are gathered concurrently before the function is called. Sync functions must be wrapped with make_async first.

# Async function — pass upstream tasks with resolve()
fetch = tg.create_task(aionode.node(fetch_data)(), name="fetch")
process_task = tg.create_task(aionode.node(process)(aionode.resolve(fetch)), name="process")

# Sync function — wrap with make_async first
summarize = tg.create_task(
    aionode.node(aionode.make_async(my_sync_fn))(aionode.resolve(process_task)),
    name="summarize",
)

# Side-only dependency (no value passed): use wait_for
task_b = tg.create_task(aionode.node(cleanup, wait_for=[fetch])(), name="cleanup")

While waiting on its dependencies a node is WAITING. If a dependency fails, the node is marked FAILED and raises RuntimeError("Failed while waiting to start.") chained to the upstream error. If a dependency is cancelled, or the node itself is cancelled while waiting, the node is marked CANCELLED.

Cancelling a waiting node does not cancel dependencies that are tasks/futures, since they may be shared with other dependents. Bare coroutines passed to resolve() are owned by the node and are cancelled with it.

resolve(awaitable)

Marks an awaitable to be resolved before being passed as an argument to node(). This preserves type information — the type checker sees resolve(task: Task[T]) as returning T.

result = await aionode.node(process)(aionode.resolve(upstream_task))

walk_tree / walk_dag

Iterate over tracked tasks after they have been created.

# DFS pre-order through the call tree (parent → children)
for info in aionode.walk_tree():
    print(info.name, info.status)

# Topological order over the DAG (deps → dependents)
for info in aionode.walk_dag():
    print(info.name, info.status)

Both accept an optional root argument (an asyncio.Task or task id). Passing None (the default) includes all tasks in the current event loop.

sync_node(name, auto_progress=True)

Track sync code blocks as child nodes in the task tree — without spawning extra threads. Use inside functions running in a make_async thread.

@aionode.make_async
def compute_pipeline(state):
    with aionode.sync_node("extract"):
        extract(state)
    with aionode.sync_node("transform"):
        transform(state)
    with aionode.sync_node("load"):
        load(state)

# Each block appears as a named child in walk_tree() with its own timing.

sync_node can also be used directly inside async node-wrapped code for lightweight sync blocks. Be aware that the wrapped code runs on the event loop thread and blocks other coroutines — keep it short, or use make_async to offload to a thread.

Also works as a decorator:

@aionode.sync_node
def extract(state):
    ...

# Or with a custom/parameterized name:
@aionode.sync_node(name="compute_{table}")
def process(table: str, state):
    ...

Task Inspection

task_id = await aionode.get_task_id(asyncio_task)
info = aionode.get_task_info(task_id)

info.status        # TaskStatus: WAITING, RUNNING, DONE, FAILED, CANCELLED
info.duration()    # Elapsed seconds
info.name          # Task name
info.deps          # Upstream dependency IDs
info.dependents    # Downstream dependent IDs
info.logs          # Accumulated log output

await aionode.log("processing record 42")  # Append to current task's logs

# Get TaskInfo for the currently running tracked task
info = aionode.current_task_info()

API Reference

Function Description
node(func, wait_for, track, auto_progress) Wrap an async function as a DAG node
resolve(awaitable) Mark an awaitable to be resolved as a node argument
get_task_id(task, timeout) Get the task ID for an asyncio.Task
get_task_info(task_id) Get TaskInfo by ID
current_task_info() Get TaskInfo for the currently running tracked task
remove_task(task_id) Remove a task and its descendants
log(value, end) Append to the current task's logs
sync_node(name, auto_progress) Track a sync block or function as a child node
make_async(func) Run a sync function in a thread
make_async_generator(gen) Async iterate a sync iterator via threads
walk_tree(root) DFS pre-order through the call tree
walk_dag(root) Topological order over the DAG

Metadata

Release files for aionode 0.3.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for aionode 0.3.1
File Size Uploaded Provenance Actions
aionode-0.3.1.tar.gz 9.5 kB With provenance Details for aionode-0.3.1.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for aionode 0.3.1
File Interpreter ABI Platform Actions
aionode-0.3.1-py3-none-any.whl Python 3 none any Details for aionode-0.3.1-py3-none-any.whl

Total release size: 19.6 kB

Release files / aionode-0.3.1.tar.gz

Download URL aionode-0.3.1.tar.gz
Size 9.5 kB
Tags Source
SHA-256 checksum
How to use checksums
b8b8cf0ff713567d181c5486de5ac55bb1fe47f5c2e866534ad0599e280cb6ec
BLAKE2b-256 checksum
How to use checksums
86438ac4c641a6b125247f92213b8018562d27d6a37e2b8ac8cb51028b1dc234
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Sep 24, 2026.

Transparency log

Release files / aionode-0.3.1-py3-none-any.whl

Download URL aionode-0.3.1-py3-none-any.whl
Size 10.1 kB
Tags Python 3
SHA-256 checksum
How to use checksums
3a97f0cc8d5b4d6a736cf875adf29b63bea2f22c8e7cf7b382850854c02fbc55
BLAKE2b-256 checksum
How to use checksums
68df4cbe861922ba222cabd7566ed57e41d5e1f0970532b3518131ffe2b431b1
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Sep 24, 2026.

Transparency log

Security for aionode 0.3.1

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for aionode-0.3.1.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Sep 24, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page