python-notebooks-async · diff
git:20260207.e28ccf5 to git:20260207.f7d1140
50 added, 15 removed. Audit A to A.
---
name: python-notebooks-async
- description: Provides Python notebook async guidance. Use when writing or reviewing asyncio code in .ipynb or '#%%' notebook workflows with host-owned event loops.
+ description: "Use when writing or reviewing asyncio code in Jupyter notebooks or '#%%' cell workflows — structuring event-loop ownership, orchestrating async tasks, or choosing compatibility strategies. Also use when hitting RuntimeError: This event loop is already running, asyncio.run() failures in cells, or tasks silently never completing."
---
# Python Notebooks Async
+ ## Overview
+
+ Notebook kernels own the event loop; async code must cooperate with that ownership rather than fight it.
+ This skill covers orchestration patterns, top-level `await`, and compatibility constraints for `.ipynb` and `#%%` workflows.
+
+ Treat these recommendations as preferred defaults.
+ When project constraints require deviation, call out tradeoffs and compensating controls.
+
+ ## When to Use
+
+ - `asyncio.run()` raises `RuntimeError` inside a notebook cell.
+ - Event-loop conflicts when mixing async libraries in Jupyter.
+ - Porting async scripts into notebook workflows.
+ - Orchestrating concurrent tasks (`gather`, `TaskGroup`) in IPython kernels.
+ - Deciding where to place reusable async logic across notebook/module boundaries.
+
+ ### When NOT to Use
+
+ - Pure script or service code with no notebook involvement — see `python-concurrency-performance`.
+ - Synchronous notebook workflows with no async needs.
+ - General asyncio API design outside notebook contexts — see `python-runtime-operations`.
+
+ ## Quick Reference
+
+ - Treat notebook kernels as loop-owned environments; never create a competing loop.
+ - Use top-level `await` instead of `asyncio.run()` in notebook cells.
+ - Orchestrate concurrent work with `asyncio.gather()` or `asyncio.TaskGroup`.
+ - Keep reusable async logic in regular `.py` modules, imported into notebooks.
+ - Use `nest_asyncio` only as a constrained compatibility fallback, not a default.
+ - Avoid fire-and-forget tasks — always `await` or collect results explicitly.
+
+ ## Common Mistakes
+
+ - **Calling `asyncio.run()` in a notebook cell.**
+ The kernel already runs a loop; `asyncio.run()` tries to start a second one and raises `RuntimeError`.
+ Use `await` directly instead.
+ - **Applying `nest_asyncio` globally by default.**
+ It patches the loop to allow reentrant calls but masks design problems and can hide subtle concurrency bugs.
+ Reserve it for legacy compatibility.
+ - **Defining async helpers inline in cells instead of modules.**
+ Inline definitions are lost on kernel restart and cannot be tested outside the notebook.
+ Extract to `.py` files.
+ - **Ignoring returned tasks or coroutines.**
+ Calling an async function without `await` silently produces a never-executed coroutine object, with no error until results are missing downstream.
+ - **Mixing blocking I/O with async in the same cell.**
+ Synchronous calls like `requests.get()` block the event loop, starving concurrent tasks.
+ Use `aiohttp`, `httpx`, or `asyncio.to_thread()`.
+
## Scope Note
- Treat these recommendations as preferred defaults for common cases, not universal rules.
- If a default conflicts with project constraints or worsens the outcome, suggest a better-fit alternative and explain why it is better for this case.
- When deviating, call out tradeoffs and compensating controls (tests, observability, migration, rollback).
## Invocation Notice
- - Inform the user when this skill is being invoked by name: `python-notebooks-async`.
-
- ## Overview
-
- Use this skill when Python async code runs inside notebooks or mixed notebook/script workflows.
- It focuses on event-loop ownership, orchestration patterns, and compatibility constraints.
-
- ## Core Rules
-
- - Treat notebook kernels as loop-owned environments.
- - Prefer top-level `await` and explicit task orchestration.
- - Avoid `asyncio.run()` inside notebook cells.
- - Keep reusable async logic in regular modules.
- - Use `nest_asyncio` only as a constrained compatibility fallback.
+ - Inform the user when this skill is being invoked by name: `python-design-modularity`.
## References
- `references/notebooks-async.md`