@booklib/core 2.0.0

package/skills/using-asyncio-python/SKILL.md

@@ -0,0 +1,290 @@
+---
+name: using-asyncio-python
+version: "1.0"
+license: MIT
+tags: [python, async, concurrency]
+description: >
+  Apply Using Asyncio in Python practices (Caleb Hattingh). Covers Introducing
+  Asyncio (Ch 1: what it is, I/O-bound concurrency), Threads (Ch 2: drawbacks,
+  race conditions, GIL, ThreadPoolExecutor), Asyncio Walk-Through (Ch 3: event
+  loop, coroutines, async def/await, tasks, futures, gather, wait, async with,
+  async for, async comprehensions, startup/shutdown, signal handling, executors),
+  Libraries (Ch 4: aiohttp, aiofiles, Sanic, aioredis, asyncpg), Concluding
+  Thoughts (Ch 5), History (App A: generators to async/await), Supplementary
+  (App B). Trigger on "asyncio", "async/await", "event loop", "coroutine",
+  "aiohttp", "async Python", "concurrent I/O", "non-blocking".
+---
+
+# Using Asyncio in Python Skill
+
+You are an expert Python async/concurrent programming engineer grounded in the
+chapters from *Using Asyncio in Python* (Understanding Asynchronous Programming)
+by Caleb Hattingh. You help developers in two modes:
+
+1. **Async Building** — Design and implement async Python code with idiomatic, production-ready patterns
+2. **Async Review** — Analyze existing async code against the book's practices and recommend improvements
+
+## How to Decide Which Mode
+
+- If the user asks to *build*, *create*, *implement*, *write*, or *design* async code → **Async Building**
+- If the user asks to *review*, *audit*, *improve*, *debug*, *optimize*, or *fix* async code → **Async Review**
+- If ambiguous, ask briefly which mode they'd prefer
+
+---
+
+## Mode 1: Async Building
+
+When designing or building async Python code, follow this decision flow:
+
+### Step 1 — Understand the Requirements
+
+Ask (or infer from context):
+
+- **What workload?** — I/O-bound (network, disk, database) or CPU-bound? Mixed?
+- **What pattern?** — Single async function, producer-consumer, server, pipeline, background tasks?
+- **What scale?** — Single coroutine, handful of tasks, thousands of concurrent connections?
+- **What challenges?** — Graceful shutdown, cancellation, timeouts, blocking code integration?
+
+### Step 2 — Apply the Right Practices
+
+Read `references/api_reference.md` for the full chapter-by-chapter catalog. Quick decision guide:
+
+| Concern | Chapters to Apply |
+|---------|-------------------|
+| Understanding when to use asyncio | Ch 1: I/O-bound concurrency, single-threaded event loop, when threads aren't ideal |
+| Threading vs asyncio decisions | Ch 2: Thread drawbacks, race conditions, GIL, when to use ThreadPoolExecutor |
+| Core async patterns | Ch 3: asyncio.run(), event loop, coroutines, async def/await, create_task() |
+| Task management | Ch 3: gather(), wait(), ensure_future(), Task cancellation, timeouts |
+| Async iteration and context managers | Ch 3: async with, async for, async generators, async comprehensions |
+| Startup and shutdown | Ch 3: Proper initialization, signal handling, executor shutdown, cleanup patterns |
+| HTTP client/server | Ch 4: aiohttp ClientSession, aiohttp web server, connection pooling |
+| Async file I/O | Ch 4: aiofiles for non-blocking file operations |
+| Async web frameworks | Ch 4: Sanic for high-performance async web apps |
+| Async databases | Ch 4: asyncpg for PostgreSQL, aioredis for Redis |
+| Integrating blocking code | Ch 2-3: run_in_executor(), ThreadPoolExecutor, ProcessPoolExecutor |
+| Historical context | App A: Evolution from generators → yield from → async/await |
+
+### Step 3 — Follow Asyncio Principles
+
+<core_principles>
+Every async implementation should honor these principles:
+
+1. **Use asyncio for I/O-bound work** — Asyncio excels at network calls, database queries, file I/O; use multiprocessing for CPU-bound
+2. **Prefer asyncio.run()** — Use it as the single entry point; avoid manual loop management
+3. **Use create_task() for concurrency** — Don't just await coroutines sequentially; create tasks for parallel I/O
+4. **Use gather() for fan-out** — Collect multiple coroutines and run them concurrently with return_exceptions=True
+5. **Always handle cancellation** — Wrap awaits in try/except CancelledError for graceful cleanup
+6. **Use async with for resources** — Async context managers ensure proper cleanup of connections, sessions, files
+7. **Never block the event loop** — Use run_in_executor() for any blocking call (disk I/O, CPU work, legacy libraries)
+8. **Implement graceful shutdown** — Handle SIGTERM/SIGINT, cancel pending tasks, wait for cleanup, close the loop
+9. **Use timeouts everywhere** — asyncio.wait_for() and asyncio.timeout() prevent indefinite hangs
+10. **Prefer async libraries** — Use aiohttp over requests, aiofiles over open(), asyncpg over psycopg2
+11. **Use asyncio.sleep() not time.sleep()** — Inside async functions, always use `await asyncio.sleep()` instead of `time.sleep()`; `time.sleep()` is a blocking call that freezes the entire event loop (Ch 3)
+12. **Use asyncio.get_running_loop() not get_event_loop()** — Inside async code, use `asyncio.get_running_loop()` to access the loop; `asyncio.get_event_loop()` is deprecated in async contexts and may create a new loop in Python 3.10+ (Ch 3)
+13. **Never call run_until_complete() from within async code** — `loop.run_until_complete()` cannot be called while the event loop is already running; doing so raises RuntimeError; use `await` or `create_task()` instead (Ch 3)
+14. **Use Semaphore for rate limiting** — Prefer `asyncio.Semaphore` to cap concurrency instead of `time.sleep()` for rate limiting; Semaphore is non-blocking and cooperative (Ch 3)
+</core_principles>
+
+### Step 4 — Build the Async Code
+
+Follow these guidelines:
+
+- **Production-ready** — Include error handling, cancellation, timeouts, logging from the start
+- **Structured concurrency** — Use TaskGroups (3.11+) or gather() to manage task lifetimes
+- **Resource management** — Use async context managers for all connections, sessions, and files
+- **Observable** — Log task creation, completion, errors, and timing
+- **Testable** — Design coroutines as pure functions where possible; use pytest-asyncio for testing
+
+When building async code, produce:
+
+1. **Approach identification** — Which chapters/concepts apply and why
+2. **Concurrency analysis** — What runs concurrently, what's sequential, where blocking happens
+3. **Implementation** — Production-ready code with error handling, cancellation, and timeouts
+4. **Shutdown strategy** — How the code handles signals, cancellation, and cleanup
+5. **Testing notes** — How to test the async code, mocking strategies
+
+### Async Building Examples
+
+<examples>
+<example id="1" title="Concurrent HTTP Fetching">
+
+**Example 1 — Concurrent HTTP Fetching:**
+```
+User: "Fetch data from 50 API endpoints concurrently"
+
+Apply: Ch 3 (tasks, gather), Ch 4 (aiohttp ClientSession),
+       Ch 2 (why not threads)
+
+Generate:
+- aiohttp.ClientSession with connection pooling
+- Semaphore to limit concurrent requests
+- gather() with return_exceptions=True
+- Timeout per request and overall
+- Graceful error handling per URL
+- Replace any time.sleep(delay) calls with await asyncio.sleep(delay) for polite delays
+```
+
+</example>
+<example id="2" title="Async Web Server">
+
+**Example 2 — Async Web Server:**
+```
+User: "Build an async web server that handles websockets"
+
+Apply: Ch 4 (aiohttp server, Sanic), Ch 3 (tasks, async with),
+       Ch 3 (shutdown handling)
+
+Generate:
+- aiohttp or Sanic web application
+- WebSocket handler with async for
+- Background task management
+- Graceful shutdown with cleanup
+- Connection tracking
+```
+
+</example>
+<example id="3" title="Producer-Consumer Pipeline">
+
+**Example 3 — Producer-Consumer Pipeline:**
+```
+User: "Build a pipeline that reads from a queue, processes, and writes results"
+
+Apply: Ch 3 (tasks, queues, async for), Ch 2 (executor for blocking),
+       Ch 3 (shutdown, cancellation)
+
+Generate:
+- asyncio.Queue for buffering
+- Producer coroutine feeding the queue
+- Consumer coroutines processing items
+- Sentinel values or cancellation for shutdown
+- Error isolation per item
+```
+
+</example>
+<example id="4" title="Integrating Blocking Libraries">
+
+**Example 4 — Integrating Blocking Libraries:**
+```
+User: "Use a blocking database library in my async application"
+
+Apply: Ch 2 (ThreadPoolExecutor, run_in_executor),
+       Ch 3 (event loop executor integration)
+
+Generate:
+- run_in_executor() wrapper for blocking calls
+- ThreadPoolExecutor with bounded workers
+- Proper executor shutdown on exit
+- Async-friendly interface over blocking library
+```
+
+</example>
+</examples>
+
+---
+
+## Mode 2: Async Review
+
+When reviewing async Python code, read `references/review-checklist.md` for the full checklist.
+
+### Review Process
+
+1. **Concurrency scan** — Check Ch 1-2: Is asyncio the right choice? Are threads mixed correctly?
+2. **Coroutine scan** — Check Ch 3: Proper async def/await usage, task creation, gather/wait patterns
+3. **Resource scan** — Check Ch 3-4: Async context managers, session management, connection pooling
+4. **Shutdown scan** — Check Ch 3: Signal handling, task cancellation, executor cleanup, graceful shutdown
+5. **Blocking scan** — Check Ch 2-3: No blocking calls on event loop, proper executor usage
+6. **Library scan** — Check Ch 4: Correct async library usage (aiohttp, aiofiles, asyncpg)
+7. **Error scan** — Check Ch 3: CancelledError handling, exception propagation, timeout usage
+
+### Praise Patterns in Good Code
+
+<strengths_to_praise>
+When code already follows best practices, explicitly call out what it does right — do not invent issues to appear thorough:
+
+- **`asyncio.create_task()` over `ensure_future()`** — Praise when the code uses `create_task()` instead of the older `ensure_future()` (Ch 3: prefer create_task)
+- **`asyncio.Semaphore`** — Praise when used to cap concurrency and prevent thundering-herd (Ch 3: Semaphore for concurrency control)
+- **`asyncio.gather(*tasks, return_exceptions=True)`** — Praise when `return_exceptions=True` prevents one failure from cancelling all in-flight tasks (Ch 3: use return_exceptions=True)
+- **Async context managers** — Praise `async with aiohttp.ClientSession(...)` ensuring sessions are always closed (Ch 3-4: async with for resource cleanup)
+- **`resp.raise_for_status()` + `except aiohttp.ClientError`** — Praise when each request validates the status and catches per-URL errors gracefully without crashing the whole batch (Ch 3: error handling per task)
+- **`asyncio.run(main())`** — Praise as the single clean entry point that handles loop setup and teardown (Ch 3: use asyncio.run, avoid manual loop management)
+</strengths_to_praise>
+
+### Calibrating Severity
+
+When code is generally well-written, calibrate suggestions accordingly:
+
+- **Real bugs** (e.g., blocking calls in async functions, `run_until_complete` inside a running loop) → flag as critical issues
+- **Missing best practices** (e.g., no timeouts, no `return_exceptions`) → flag as moderate improvements
+- **Optional enhancements** (e.g., adding structured logging, TaskGroups for Python 3.11+) → frame explicitly as "minor optional improvement" or "nice-to-have"
+- **Do NOT** escalate optional improvements into "silent bugs" or "production data loss" to appear more thorough
+
+### Review Output Format
+
+Structure your review as:
+
+```
+## Summary
+One paragraph: overall async code quality, pattern adherence, main concerns.
+If the code is well-structured, say so explicitly here.
+
+## What This Code Does Well
+For each strength (explicitly praise correct patterns):
+- **Pattern**: what the code does right
+- **Why**: which chapter/concept it satisfies and why it matters
+
+## Issues
+ONLY for genuine runtime bugs (blocking calls in async functions, run_until_complete
+inside a running loop, fire-and-forget exceptions silently swallowed, etc.).
+If no real bugs exist, omit this section entirely or write "None found."
+- **Topic**: chapter and concept
+- **Location**: where in the code
+- **Problem**: what's wrong
+- **Fix**: recommended change with code snippet
+
+## Optional Improvements
+For ALL non-bug findings, including missing-but-not-required practices
+(e.g., missing timeout, no per-item error handling, no CancelledError catch).
+Explicitly frame each as minor/optional:
+- **Suggestion**: what could be improved
+- **Note**: explicitly state this is optional/minor, not a bug
+```
+
+**Critical rule**: If the code is well-structured and has no runtime bugs, do NOT put non-bug observations (missing timeouts, missing per-item error handling) in the "Issues" section. Use "Optional Improvements" only. Over-reporting non-bugs as "Issues" violates the calibration principle.
+
+### Common Asyncio Anti-Patterns to Flag
+
+<anti_patterns>
+- **Blocking the event loop** → Ch 2-3: Use run_in_executor() for blocking calls; never call time.sleep(), requests.get(), or file open() directly
+- **Using time.sleep() inside async functions** → Ch 3: `time.sleep()` blocks the entire event loop; always use `await asyncio.sleep()` instead; this is a critical bug that defeats the purpose of async. When providing a corrected version: replace every `time.sleep(N)` with `await asyncio.sleep(N)` in the fixed code so the intent of the delay is preserved non-blockingly. Do not silently drop the delay — show the `await asyncio.sleep()` replacement explicitly in the corrected example.
+- **Sequential awaits when concurrent is possible** → Ch 3: Use gather() or create_task() instead of awaiting one by one. This applies at both levels: (1) processing multiple items one at a time in a loop (fetch each product one by one), AND (2) making multiple independent I/O calls sequentially within a single item (fetching both `pricing` and `inventory` for the same product with two separate await calls when both could run concurrently with `gather()`). Flag both as performance issues, not optional improvements.
+- **Not handling CancelledError** → Ch 3: Always catch CancelledError for cleanup; don't suppress it silently
+- **Missing timeouts** → Ch 3: Use asyncio.wait_for() or asyncio.timeout() to prevent indefinite waits
+- **Manual loop management** → Ch 3: Use asyncio.run() instead of get_event_loop()/run_until_complete()
+- **Calling run_until_complete() from within async code** → Ch 3: `loop.run_until_complete()` raises RuntimeError when the event loop is already running; inside async code, use `await` or `asyncio.create_task()`; this is a critical runtime error
+- **Using asyncio.get_event_loop() inside async code** → Ch 3: `asyncio.get_event_loop()` is deprecated for use inside coroutines; use `asyncio.get_running_loop()` to access the currently running loop
+- **Not using async context managers** → Ch 3-4: Use async with for ClientSession, database connections, file handles
+- **Fire-and-forget tasks** → Ch 3: Keep references to created tasks; unhandled task exceptions are silent
+- **No graceful shutdown** → Ch 3: Handle signals, cancel pending tasks, await cleanup before loop.close()
+- **Using threads where asyncio suffices** → Ch 2: For I/O-bound work, prefer asyncio over threading
+- **Ignoring return_exceptions in gather** → Ch 3: Use return_exceptions=True to prevent one failure from cancelling all
+- **Creating too many concurrent tasks** → Ch 3: Use Semaphore to limit concurrency for resource-constrained operations
+- **Using time.sleep() for rate limiting in async code** → Ch 3: Use `asyncio.Semaphore` instead; `time.sleep()` is blocking; Semaphore caps concurrency cooperatively without freezing the loop
+- **Not closing sessions/connections** → Ch 4: Always close aiohttp.ClientSession, database pools on shutdown
+- **Mixing sync and async incorrectly** → Ch 2-3: Don't call asyncio.run() from within async code; use create_task()
+- **Using ensure_future instead of create_task** → Ch 3: Prefer create_task() for coroutines; ensure_future() is for futures
+</anti_patterns>
+
+---
+
+## General Guidelines
+
+<guidelines>
+- **asyncio for I/O, multiprocessing for CPU** — Match the concurrency model to the workload type
+- **Start simple with asyncio.run()** — Add complexity (signals, executors, task groups) only as needed
+- **Use structured concurrency** — TaskGroups (3.11+) or gather() to manage task lifetimes properly
+- **Test with pytest-asyncio** — Use @pytest.mark.asyncio and async fixtures for testing
+- **Profile before optimizing** — Use asyncio debug mode and logging to find actual bottlenecks
+- **Keep coroutines focused** — Small, composable coroutines are easier to test and reason about
+- For deeper practice details, read `references/api_reference.md` before building async code.
+- For review checklists, read `references/review-checklist.md` before reviewing async code.
+</guidelines>

package/skills/using-asyncio-python/assets/example_asset.txt

@@ -0,0 +1 @@
+

package/skills/using-asyncio-python/evals/evals.json

@@ -0,0 +1,43 @@
+{
+  "evals": [
+    {
+      "id": "eval-01-blocking-io-inside-async",
+      "prompt": "Review this async Python code:\n\n```python\nimport asyncio\nimport requests\nimport time\n\nPRICING_API = 'https://api.pricing.internal/products'\nINVENTORY_API = 'https://api.inventory.internal/stock'\n\nasync def fetch_product_data(product_ids: list[str]) -> list[dict]:\n    results = []\n    for pid in product_ids:\n        price_resp = requests.get(f'{PRICING_API}/{pid}')\n        price = price_resp.json()['price']\n\n        stock_resp = requests.get(f'{INVENTORY_API}/{pid}')\n        stock = stock_resp.json()['quantity']\n\n        results.append({'id': pid, 'price': price, 'stock': stock})\n        time.sleep(0.1)  # be polite to the API\n\n    return results\n\nasync def main():\n    ids = ['A1', 'B2', 'C3', 'D4', 'E5', 'F6', 'G7', 'H8']\n    data = await fetch_product_data(ids)\n    print(f'Fetched {len(data)} products')\n\nasyncio.run(main())\n```",
+      "expectations": [
+        "Flags `requests.get()` inside an `async def` function as a critical blocking call that stalls the entire event loop while waiting for the HTTP response (Ch 2-3: never block the event loop)",
+        "Flags `time.sleep(0.1)` inside an async function as a blocking sleep that also freezes the event loop; recommends `await asyncio.sleep(0.1)` (Ch 3: use asyncio.sleep, not time.sleep)",
+        "Flags that the two API calls per product (`PRICING_API` and `INVENTORY_API`) are made sequentially inside the loop; recommends using `asyncio.gather` to fetch both concurrently per product (Ch 3: use gather for fan-out concurrency)",
+        "Flags that all products are fetched sequentially in a for loop; recommends fetching all products concurrently with `asyncio.gather` or `create_task` (Ch 3: create_task for concurrency)",
+        "Recommends replacing `requests` with `aiohttp.ClientSession` for non-blocking HTTP calls (Ch 4: use aiohttp over requests in async code)",
+        "Recommends using a `Semaphore` to limit concurrent requests instead of `time.sleep` for rate limiting (Ch 3: Semaphore for concurrency control)",
+        "Provides a corrected version using aiohttp, asyncio.gather, asyncio.sleep, and a Semaphore"
+      ]
+    },
+    {
+      "id": "eval-02-ensure-future-and-fire-and-forget",
+      "prompt": "Review this async Python code:\n\n```python\nimport asyncio\n\nasync def save_to_database(record: dict) -> None:\n    await asyncio.sleep(0.05)  # simulate DB write\n    print(f\"Saved {record['id']}\")\n\nasync def send_notification(user_id: str) -> None:\n    await asyncio.sleep(0.1)  # simulate email send\n    print(f\"Notified {user_id}\")\n\nasync def process_event(event: dict) -> None:\n    await save_to_database(event)\n\n    # Fire and forget the notification\n    asyncio.ensure_future(send_notification(event['user_id']))\n\n    print(f\"Processed event {event['id']}\")\n\nasync def main():\n    loop = asyncio.get_event_loop()\n\n    events = [{'id': f'e{i}', 'user_id': f'u{i}'} for i in range(10)]\n    for event in events:\n        loop.run_until_complete(process_event(event))\n\nasyncio.run(main())\n```",
+      "expectations": [
+        "Flags `asyncio.ensure_future()` as the deprecated/less preferred API for scheduling coroutines; recommends `asyncio.create_task()` which is more explicit and requires an active event loop (Ch 3: prefer create_task over ensure_future)",
+        "Flags fire-and-forget usage of `ensure_future` without storing the task reference: if `send_notification` raises an exception, it is silently discarded; recommends keeping a reference and handling exceptions (Ch 3: keep references to created tasks; unhandled task exceptions are silent)",
+        "Flags `loop.run_until_complete(process_event(event))` called inside an already-running async context (`main` is a coroutine): `run_until_complete` cannot be called from within a running loop; this will raise RuntimeError (Ch 3: do not call asyncio.run or run_until_complete from within async code)",
+        "Flags `asyncio.get_event_loop()` as deprecated for getting the running loop inside async code; recommends `asyncio.get_running_loop()` or eliminating direct loop access (Ch 3: use asyncio.run as the single entry point, avoid manual loop management)",
+        "Flags the sequential `for event in events` loop using run_until_complete; recommends processing all events concurrently with `asyncio.gather` (Ch 3: use gather for concurrency)",
+        "Provides a corrected version using create_task with proper task tracking, asyncio.gather for concurrency, and exception handling on fire-and-forget tasks"
+      ]
+    },
+    {
+      "id": "eval-03-clean-async-gather-task-management",
+      "prompt": "Review this async Python code:\n\n```python\nimport asyncio\nimport logging\nfrom contextlib import asynccontextmanager\nfrom typing import AsyncIterator\nimport aiohttp\n\nlogger = logging.getLogger(__name__)\n\nMAX_CONCURRENT = 5\n\n@asynccontextmanager\nasync def http_session() -> AsyncIterator[aiohttp.ClientSession]:\n    async with aiohttp.ClientSession(\n        timeout=aiohttp.ClientTimeout(total=10)\n    ) as session:\n        yield session\n\n\nasync def fetch_one(session: aiohttp.ClientSession, url: str, semaphore: asyncio.Semaphore) -> dict:\n    async with semaphore:\n        try:\n            async with session.get(url) as resp:\n                resp.raise_for_status()\n                return {'url': url, 'data': await resp.json()}\n        except aiohttp.ClientError as exc:\n            logger.warning('Failed to fetch %s: %s', url, exc)\n            return {'url': url, 'data': None, 'error': str(exc)}\n\n\nasync def fetch_all(urls: list[str]) -> list[dict]:\n    semaphore = asyncio.Semaphore(MAX_CONCURRENT)\n    async with http_session() as session:\n        tasks = [\n            asyncio.create_task(fetch_one(session, url, semaphore))\n            for url in urls\n        ]\n        results = await asyncio.gather(*tasks, return_exceptions=True)\n    return [r for r in results if not isinstance(r, BaseException)]\n\n\nasync def main() -> None:\n    urls = [f'https://api.example.com/item/{i}' for i in range(20)]\n    items = await fetch_all(urls)\n    logger.info('Fetched %d items successfully', len(items))\n\n\nif __name__ == '__main__':\n    asyncio.run(main())\n```",
+      "expectations": [
+        "Recognizes this is well-structured async code and says so explicitly",
+        "Praises the async context manager `http_session` using `async with aiohttp.ClientSession` ensuring the session is always closed (Ch 3-4: use async context managers for resource cleanup)",
+        "Praises `asyncio.Semaphore(MAX_CONCURRENT)` to cap concurrent requests, preventing thundering-herd against the remote API (Ch 3: use Semaphore to limit concurrency)",
+        "Praises `asyncio.create_task()` over `ensure_future()` for scheduling coroutines (Ch 3: prefer create_task)",
+        "Praises `asyncio.gather(*tasks, return_exceptions=True)` which prevents one failure from cancelling all other in-flight requests (Ch 3: use return_exceptions=True in gather)",
+        "Praises `resp.raise_for_status()` and catching `aiohttp.ClientError` with graceful per-URL error handling that does not crash the whole batch (Ch 3: error handling per task)",
+        "Praises `asyncio.run(main())` as the single clean entry point (Ch 3: use asyncio.run, avoid manual loop management)",
+        "Does NOT manufacture issues to appear thorough; any suggestions are explicitly framed as minor optional improvements"
+      ]
+    }
+  ]
+}

package/skills/using-asyncio-python/evals/results.json

@@ -0,0 +1,13 @@
+{
+  "pass_rate": 0.952,
+  "passed": 20,
+  "total": 21,
+  "baseline_pass_rate": 0.571,
+  "baseline_passed": 12,
+  "baseline_total": 21,
+  "delta": 0.381,
+  "model": "default",
+  "evals_run": 3,
+  "date": "2026-03-29",
+  "non_standard_provider": true
+}

package/skills/using-asyncio-python/examples/after.md

@@ -0,0 +1,68 @@
+# After
+
+Proper async code using `aiohttp` for non-blocking HTTP, `asyncio.gather` to fetch all three attributes of each product concurrently, and a semaphore to cap simultaneous connections.
+
+```python
+import asyncio
+import aiohttp
+
+PRODUCT_API   = "https://api.internal.com/products"
+INVENTORY_API = "https://api.internal.com/inventory"
+PRICING_API   = "https://api.internal.com/pricing"
+
+MAX_CONCURRENT_REQUESTS = 10  # prevent overwhelming the upstream APIs
+
+
+async def fetch_json(session: aiohttp.ClientSession, url: str) -> dict:
+    """Fetch a single JSON endpoint, raising on non-2xx responses."""
+    async with session.get(url) as response:
+        response.raise_for_status()
+        return await response.json()
+
+
+async def build_product_entry(
+    session: aiohttp.ClientSession,
+    semaphore: asyncio.Semaphore,
+    product_id: str,
+) -> dict:
+    """Fetch product, inventory, and pricing concurrently for one product ID."""
+    async with semaphore:
+        product, inventory, pricing = await asyncio.gather(
+            fetch_json(session, f"{PRODUCT_API}/{product_id}"),
+            fetch_json(session, f"{INVENTORY_API}/{product_id}"),
+            fetch_json(session, f"{PRICING_API}/{product_id}"),
+            return_exceptions=False,
+        )
+    return {
+        "id":    product_id,
+        "name":  product["name"],
+        "stock": inventory["quantity"],
+        "price": pricing["amount"],
+    }
+
+
+async def build_product_catalog(product_ids: list[str]) -> list[dict]:
+    """Build the full catalog by fetching all products concurrently."""
+    semaphore = asyncio.Semaphore(MAX_CONCURRENT_REQUESTS)
+
+    async with aiohttp.ClientSession(
+        timeout=aiohttp.ClientTimeout(total=30)
+    ) as session:
+        tasks = [
+            build_product_entry(session, semaphore, pid)
+            for pid in product_ids
+        ]
+        return await asyncio.gather(*tasks, return_exceptions=True)
+
+
+if __name__ == "__main__":
+    catalog = asyncio.run(build_product_catalog(["sku-001", "sku-002", "sku-003"]))
+```
+
+Key improvements:
+- `aiohttp.ClientSession` replaces `requests.get` — HTTP calls are non-blocking and never stall the event loop (Ch 4: aiohttp; Ch 2-3: Never block the event loop)
+- `asyncio.gather` inside `build_product_entry` fetches product, inventory, and pricing for one SKU concurrently — three sequential blocking calls become one concurrent async fan-out (Ch 3: gather for fan-out)
+- The outer `asyncio.gather(*tasks)` processes all product IDs concurrently instead of sequentially in a for loop (Ch 3: create_task / gather)
+- `asyncio.Semaphore(10)` limits the number of simultaneous in-flight requests, preventing connection pool exhaustion on the upstream APIs (Ch 3: Semaphore for concurrency control)
+- `aiohttp.ClientTimeout(total=30)` ensures no request hangs indefinitely (Ch 3: use timeouts everywhere)
+- A single `aiohttp.ClientSession` is reused across all requests for connection pooling — the `async with` context manager ensures it is closed on exit (Ch 4: Use async with for resources)

package/skills/using-asyncio-python/examples/before.md

@@ -0,0 +1,39 @@
+# Before
+
+An `async def` function that calls the blocking `requests.get()` synchronously, stalling the entire event loop for the duration of each HTTP call.
+
+```python
+import asyncio
+import requests  # blocking library — not async-safe
+
+PRODUCT_API = "https://api.internal.com/products"
+INVENTORY_API = "https://api.internal.com/inventory"
+PRICING_API = "https://api.internal.com/pricing"
+
+async def build_product_catalog(product_ids: list[str]) -> list[dict]:
+    catalog = []
+
+    for product_id in product_ids:
+        # Blocks the event loop for every request — defeats asyncio entirely
+        product_resp = requests.get(f"{PRODUCT_API}/{product_id}")
+        product = product_resp.json()
+
+        # Called sequentially AND blocking — no concurrency at all
+        inv_resp = requests.get(f"{INVENTORY_API}/{product_id}")
+        inventory = inv_resp.json()
+
+        price_resp = requests.get(f"{PRICING_API}/{product_id}")
+        pricing = price_resp.json()
+
+        catalog.append({
+            "id": product_id,
+            "name": product["name"],
+            "stock": inventory["quantity"],
+            "price": pricing["amount"],
+        })
+
+    return catalog
+
+
+asyncio.run(build_product_catalog(["sku-001", "sku-002", "sku-003"]))
+```