Claude Skill

python-async-ops

Python asyncio patterns for concurrent programming. Triggers on: asyncio, async, await, coroutine, gather, semaphore, TaskGroup, event loop, aiohttp, concurrent.

LLM Mart · 0 points · 2 views 0 listing impressions 0 install-command copies
Download 0xdarkmatter-claude-mods-skills_python-async-ops-3dfaf0b.zip · 22 KB

Install

skills CLI npx skills add https://github.com/0xDarkMatter/claude-mods/tree/main/skills/python-async-ops
Claude Code claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install 0xdarkmatter-claude-mods@llmmart
Git git clone https://github.com/0xDarkMatter/claude-mods.git

The skills CLI installs just this skill, for any of its supported agents. Claude Code installs the whole 0xdarkmatter/claude-mods collection as a plugin from our marketplace. Git is the plain clone.

Skill manifest

Python Async Patterns

Asyncio patterns for concurrent Python programming.

When to Use Async vs Sync

Use Async When Use Sync When
I/O-bound operations (HTTP, DB, files) CPU-bound computations
High concurrency (100s+ connections) Simple scripts, one-off tasks
WebSocket/streaming connections Small data processing
Microservices with network calls Single sequential operations

Decision tree:

  1. Is it CPU-bound? → Sync (or multiprocessing)
  2. Is it I/O-bound with high concurrency? → Async
  3. Is it simple I/O with few connections? → Sync is fine

Core Concepts

import asyncio

# Coroutine (must be awaited)
async def fetch(url: str) -> str:
    async with aiohttp.ClientSession() as session:
        async with session.get(url) as response:
            return await response.text()

# Entry point
async def main():
    result = await fetch("https://example.com")
    return result

asyncio.run(main())

Pattern 1: Concurrent with gather

async def fetch_all(urls: list[str]) -> list[str]:
    """Fetch multiple URLs concurrently."""
    async with aiohttp.ClientSession() as session:
        tasks = [fetch_one(session, url) for url in urls]
        return await asyncio.gather(*tasks, return_exceptions=True)

Pattern 2: Bounded Concurrency

async def fetch_with_limit(urls: list[str], limit: int = 10):
    """Limit concurrent requests."""
    semaphore = asyncio.Semaphore(limit)

    async def bounded_fetch(url):
        async with semaphore:
            return await fetch_one(url)

    return await asyncio.gather(*[bounded_fetch(url) for url in urls])

Pattern 3: TaskGroup (Python 3.11+)

async def process_items(items):
    """Structured concurrency with automatic cleanup."""
    async with asyncio.TaskGroup() as tg:
        for item in items:
            tg.create_task(process_one(item))
    # All tasks complete here, or exception raised

Pattern 4: Timeout

async def with_timeout():
    try:
        async with asyncio.timeout(5.0):  # Python 3.11+
            result = await slow_operation()
    except asyncio.TimeoutError:
        result = None
    return result

Critical Warnings

# WRONG - blocks event loop
async def bad():
    time.sleep(5)         # Never use time.sleep!
    requests.get(url)     # Blocking I/O!

# CORRECT
async def good():
    await asyncio.sleep(5)
    async with aiohttp.ClientSession() as s:
        await s.get(url)
# WRONG - orphaned task
async def bad():
    asyncio.create_task(work())  # May be garbage collected!

# CORRECT - keep reference
async def good():
    task = asyncio.create_task(work())
    await task

Quick Reference

Pattern Use Case
gather(*tasks) Multiple independent operations
Semaphore(n) Rate limiting, resource constraints
TaskGroup() Structured concurrency (3.11+)
Queue() Producer-consumer
timeout(s) Timeout wrapper (3.11+)
Lock() Shared mutable state

Async Context Manager

from contextlib import asynccontextmanager

@asynccontextmanager
async def managed_connection():
    conn = await create_connection()
    try:
        yield conn
    finally:
        await conn.close()

Additional Resources

For detailed patterns, load:

  • ./references/concurrency-patterns.md - Queue, Lock, producer-consumer
  • ./references/aiohttp-patterns.md - HTTP client/server patterns
  • ./references/mixing-sync-async.md - run_in_executor, thread pools
  • ./references/debugging-async.md - Debug mode, profiling, finding issues
  • ./references/production-patterns.md - Graceful shutdown, health checks, signal handling
  • ./references/error-handling.md - Retry with backoff, circuit breakers, partial failures
  • ./references/performance.md - uvloop, connection pooling, buffer sizing

Scripts

  • ./scripts/find-blocking-calls.sh - Scan code for blocking calls in async functions

Assets

  • ./assets/async-project-template.py - Production-ready async app skeleton

See Also

Prerequisites:

  • python-typing-ops - Type hints for async functions

Related Skills:

  • python-fastapi-ops - Async web APIs
  • python-observability-ops - Async logging and tracing
  • python-database-ops - Async database access
Files (claude-mods)
  • assets
    • async-project-template.py 3.6 KB
      Loading…
  • references
    • aiohttp-patterns.md 6.1 KB
      Loading…
    • concurrency-patterns.md 6 KB
      Loading…
    • debugging-async.md 5.8 KB
      Loading…
    • error-handling.md 11.9 KB
      Loading…
    • mixing-sync-async.md 5.7 KB
      Loading…
    • performance.md 10.1 KB
      Loading…
    • production-patterns.md 10 KB
      Loading…
  • scripts
    • find-blocking-calls.sh 1.4 KB
      Loading…
  • SKILL.md 4.8 KB
    ---
    name: python-async-ops
    description: "Python asyncio patterns for concurrent programming. Triggers on: asyncio, async, await, coroutine, gather, semaphore, TaskGroup, event loop, aiohttp, concurrent."
    license: MIT
    compatibility: "Python 3.10+ recommended. Some patterns require 3.11+ (TaskGroup, timeout)."
    allowed-tools: "Read Write"
    metadata:
      author: claude-mods
      depends-on: python-typing-ops
      related-skills: python-fastapi-ops, python-observability-ops
    ---
    
    # Python Async Patterns
    
    Asyncio patterns for concurrent Python programming.
    
    ## When to Use Async vs Sync
    
    | Use Async When | Use Sync When |
    |----------------|---------------|
    | I/O-bound operations (HTTP, DB, files) | CPU-bound computations |
    | High concurrency (100s+ connections) | Simple scripts, one-off tasks |
    | WebSocket/streaming connections | Small data processing |
    | Microservices with network calls | Single sequential operations |
    
    **Decision tree:**
    1. Is it CPU-bound? → Sync (or multiprocessing)
    2. Is it I/O-bound with high concurrency? → Async
    3. Is it simple I/O with few connections? → Sync is fine
    
    ## Core Concepts
    
    ```python
    import asyncio
    
    # Coroutine (must be awaited)
    async def fetch(url: str) -> str:
        async with aiohttp.ClientSession() as session:
            async with session.get(url) as response:
                return await response.text()
    
    # Entry point
    async def main():
        result = await fetch("https://example.com")
        return result
    
    asyncio.run(main())
    ```
    
    ## Pattern 1: Concurrent with gather
    
    ```python
    async def fetch_all(urls: list[str]) -> list[str]:
        """Fetch multiple URLs concurrently."""
        async with aiohttp.ClientSession() as session:
            tasks = [fetch_one(session, url) for url in urls]
            return await asyncio.gather(*tasks, return_exceptions=True)
    ```
    
    ## Pattern 2: Bounded Concurrency
    
    ```python
    async def fetch_with_limit(urls: list[str], limit: int = 10):
        """Limit concurrent requests."""
        semaphore = asyncio.Semaphore(limit)
    
        async def bounded_fetch(url):
            async with semaphore:
                return await fetch_one(url)
    
        return await asyncio.gather(*[bounded_fetch(url) for url in urls])
    ```
    
    ## Pattern 3: TaskGroup (Python 3.11+)
    
    ```python
    async def process_items(items):
        """Structured concurrency with automatic cleanup."""
        async with asyncio.TaskGroup() as tg:
            for item in items:
                tg.create_task(process_one(item))
        # All tasks complete here, or exception raised
    ```
    
    ## Pattern 4: Timeout
    
    ```python
    async def with_timeout():
        try:
            async with asyncio.timeout(5.0):  # Python 3.11+
                result = await slow_operation()
        except asyncio.TimeoutError:
            result = None
        return result
    ```
    
    ## Critical Warnings
    
    ```python
    # WRONG - blocks event loop
    async def bad():
        time.sleep(5)         # Never use time.sleep!
        requests.get(url)     # Blocking I/O!
    
    # CORRECT
    async def good():
        await asyncio.sleep(5)
        async with aiohttp.ClientSession() as s:
            await s.get(url)
    ```
    
    ```python
    # WRONG - orphaned task
    async def bad():
        asyncio.create_task(work())  # May be garbage collected!
    
    # CORRECT - keep reference
    async def good():
        task = asyncio.create_task(work())
        await task
    ```
    
    ## Quick Reference
    
    | Pattern | Use Case |
    |---------|----------|
    | `gather(*tasks)` | Multiple independent operations |
    | `Semaphore(n)` | Rate limiting, resource constraints |
    | `TaskGroup()` | Structured concurrency (3.11+) |
    | `Queue()` | Producer-consumer |
    | `timeout(s)` | Timeout wrapper (3.11+) |
    | `Lock()` | Shared mutable state |
    
    ## Async Context Manager
    
    ```python
    from contextlib import asynccontextmanager
    
    @asynccontextmanager
    async def managed_connection():
        conn = await create_connection()
        try:
            yield conn
        finally:
            await conn.close()
    ```
    
    ## Additional Resources
    
    For detailed patterns, load:
    - `./references/concurrency-patterns.md` - Queue, Lock, producer-consumer
    - `./references/aiohttp-patterns.md` - HTTP client/server patterns
    - `./references/mixing-sync-async.md` - run_in_executor, thread pools
    - `./references/debugging-async.md` - Debug mode, profiling, finding issues
    - `./references/production-patterns.md` - Graceful shutdown, health checks, signal handling
    - `./references/error-handling.md` - Retry with backoff, circuit breakers, partial failures
    - `./references/performance.md` - uvloop, connection pooling, buffer sizing
    
    ## Scripts
    
    - `./scripts/find-blocking-calls.sh` - Scan code for blocking calls in async functions
    
    ## Assets
    
    - `./assets/async-project-template.py` - Production-ready async app skeleton
    
    ---
    
    ## See Also
    
    **Prerequisites:**
    - `python-typing-ops` - Type hints for async functions
    
    **Related Skills:**
    - `python-fastapi-ops` - Async web APIs
    - `python-observability-ops` - Async logging and tracing
    - `python-database-ops` - Async database access
    

Comments (0)

Sign in to join the conversation.

No comments yet.

Reviews (0)

No reviews yet.