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)
| 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)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| 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 logRelease 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 logSecurity 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.
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 logA 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.