Async Python Patterns

作者 wshobson46891e7e60da無授權條款收錄於 2026年10月8日更新於 2026年10月8日

Master Python asyncio, concurrent programming, and async/await patterns for high-performance applications. Use when building async APIs, concurrent systems, or I/O-bound applications requiring non-blocking operations.

僅含說明Software Development
AI 產生的概覽

提供 Python asyncio、並行程式設計與 async/await 模式的指引，用於非阻塞應用程式。

功能
此技能提供 Python 非同步程式設計的教學指引，涵蓋 asyncio 的事件迴圈、協程、任務、future、非同步情境管理器與非同步迭代器。它說明多種範例模式，包括以 gather() 進行並行執行、建立任務、錯誤處理、逾時與取消，以及常見陷阱和以 pytest-asyncio 進行的測試。它也包含同步與非同步的選擇指南，並指向參考檔案以取得進階模式。
適用情境
適用於建置非同步 Web API、並行 I/O 操作、網路爬蟲、即時服務或其他 I/O 密集的 Python 工作負載。也適合用來判斷是否該採用非同步做法，以及避免常見的 asyncio 錯誤。
執行需求
除代理程式外不需要指令碼或套件；範例涉及 Python 的 asyncio 以及用於測試的 pytest-asyncio，技能另指向 references/details.md 取得進階模式。

Async Python Patterns

Comprehensive guidance for implementing asynchronous Python applications using asyncio, concurrent programming patterns, and async/await for building high-performance, non-blocking systems.

When to Use This Skill

  • Building async web APIs (FastAPI, aiohttp, Sanic)
  • Implementing concurrent I/O operations (database, file, network)
  • Creating web scrapers with concurrent requests
  • Developing real-time applications (WebSocket servers, chat systems)
  • Processing multiple independent tasks simultaneously
  • Building microservices with async communication
  • Optimizing I/O-bound workloads
  • Implementing async background tasks and queues

Sync vs Async Decision Guide

Before adopting async, consider whether it's the right choice for your use case.

Use CaseRecommended Approach
Many concurrent network/DB callsasyncio
CPU-bound computationmultiprocessing or thread pool
Mixed I/O + CPUOffload CPU work with asyncio.to_thread()
Simple scripts, few connectionsSync (simpler, easier to debug)
Web APIs with high concurrencyAsync frameworks (FastAPI, aiohttp)

Key Rule: Stay fully sync or fully async within a call path. Mixing creates hidden blocking and complexity.

Core Concepts

1. Event Loop

The event loop is the heart of asyncio, managing and scheduling asynchronous tasks.

Key characteristics:

  • Single-threaded cooperative multitasking
  • Schedules coroutines for execution
  • Handles I/O operations without blocking
  • Manages callbacks and futures

2. Coroutines

Functions defined with async def that can be paused and resumed.

Syntax:

python
async def my_coroutine():    result = await some_async_operation()    return result

3. Tasks

Scheduled coroutines that run concurrently on the event loop.

4. Futures

Low-level objects representing eventual results of async operations.

5. Async Context Managers

Resources that support async with for proper cleanup.

6. Async Iterators

Objects that support async for for iterating over async data sources.

Quick Start

python
import asyncio
async def main():    print("Hello")    await asyncio.sleep(1)    print("World")
# Python 3.7+asyncio.run(main())

Fundamental Patterns

Pattern 1: Basic Async/Await

python
import asyncio
async def fetch_data(url: str) -> dict:    """Fetch data from URL asynchronously."""    await asyncio.sleep(1)  # Simulate I/O    return {"url": url, "data": "result"}
async def main():    result = await fetch_data("https://api.example.com")    print(result)
asyncio.run(main())

Pattern 2: Concurrent Execution with gather()

python
import asynciofrom typing import List
async def fetch_user(user_id: int) -> dict:    """Fetch user data."""    await asyncio.sleep(0.5)    return {"id": user_id, "name": f"User {user_id}"}
async def fetch_all_users(user_ids: List[int]) -> List[dict]:    """Fetch multiple users concurrently."""    tasks = [fetch_user(uid) for uid in user_ids]    results = await asyncio.gather(*tasks)    return results
async def main():    user_ids = [1, 2, 3, 4, 5]    users = await fetch_all_users(user_ids)    print(f"Fetched {len(users)} users")
asyncio.run(main())

Pattern 3: Task Creation and Management

python
import asyncio
async def background_task(name: str, delay: int):    """Long-running background task."""    print(f"{name} started")    await asyncio.sleep(delay)    print(f"{name} completed")    return f"Result from {name}"
async def main():    # Create tasks    task1 = asyncio.create_task(background_task("Task 1", 2))    task2 = asyncio.create_task(background_task("Task 2", 1))
    # Do other work    print("Main: doing other work")    await asyncio.sleep(0.5)
    # Wait for tasks    result1 = await task1    result2 = await task2
    print(f"Results: {result1}, {result2}")
asyncio.run(main())

Pattern 4: Error Handling in Async Code

python
import asynciofrom typing import List, Optional
async def risky_operation(item_id: int) -> dict:    """Operation that might fail."""    await asyncio.sleep(0.1)    if item_id % 3 == 0:        raise ValueError(f"Item {item_id} failed")    return {"id": item_id, "status": "success"}
async def safe_operation(item_id: int) -> Optional[dict]:    """Wrapper with error handling."""    try:        return await risky_operation(item_id)    except ValueError as e:        print(f"Error: {e}")        return None
async def process_items(item_ids: List[int]):    """Process multiple items with error handling."""    tasks = [safe_operation(iid) for iid in item_ids]    results = await asyncio.gather(*tasks, return_exceptions=True)
    # Filter out failures    successful = [r for r in results if r is not None and not isinstance(r, Exception)]    failed = [r for r in results if isinstance(r, Exception)]
    print(f"Success: {len(successful)}, Failed: {len(failed)}")    return successful
asyncio.run(process_items([1, 2, 3, 4, 5, 6]))

Pattern 5: Timeout Handling

python
import asyncio
async def slow_operation(delay: int) -> str:    """Operation that takes time."""    await asyncio.sleep(delay)    return f"Completed after {delay}s"
async def with_timeout():    """Execute operation with timeout."""    try:        result = await asyncio.wait_for(slow_operation(5), timeout=2.0)        print(result)    except asyncio.TimeoutError:        print("Operation timed out")
asyncio.run(with_timeout())

Detailed worked examples and patterns

Detailed sections (starting with ## Advanced Patterns) live in references/details.md. Read that file when the navigation summary above is insufficient.

Common Pitfalls

1. Forgetting await

python
# Wrong - returns coroutine object, doesn't executeresult = async_function()
# Correctresult = await async_function()

2. Blocking the Event Loop

python
# Wrong - blocks event loopimport timeasync def bad():    time.sleep(1)  # Blocks!
# Correctasync def good():    await asyncio.sleep(1)  # Non-blocking

3. Not Handling Cancellation

python
async def cancelable_task():    """Task that handles cancellation."""    try:        while True:            await asyncio.sleep(1)            print("Working...")    except asyncio.CancelledError:        print("Task cancelled, cleaning up...")        # Perform cleanup        raise  # Re-raise to propagate cancellation

4. Mixing Sync and Async Code

python
# Wrong - can't call async from sync directlydef sync_function():    result = await async_function()  # SyntaxError!
# Correctdef sync_function():    result = asyncio.run(async_function())

Testing Async Code

python
import asyncioimport pytest
# Using pytest-asyncio@pytest.mark.asyncioasync def test_async_function():    """Test async function."""    result = await fetch_data("https://api.example.com")    assert result is not None
@pytest.mark.asyncioasync def test_with_timeout():    """Test with timeout."""    with pytest.raises(asyncio.TimeoutError):        await asyncio.wait_for(slow_operation(5), timeout=1.0)

來源與署名

來源：wshobson/agents位於plugins/python-development/skills/async-python-patterns提交46891e7

授權條款： 無授權條款

內容歸原作者所有。SourceWeft 從公開儲存庫中收錄這些內容。

檢舉或申請下架

更多來自 wshobson/agents 的技能

Uv Package Manager

wshobson

關於使用 uv Python 套件管理器管理相依性、虛擬環境與專案工作流程的參考指南。

Software Development2026年10月8日

Web Component Design

wshobson

指導在 React、Vue 和 Svelte 中建構可重複使用的 UI 元件，涵蓋組合模式、CSS-in-JS 選擇與元件 API 設計。

Software Development2026年10月8日

Python Type Safety

wshobson

指導 Python 型別註解、泛型、協定以及 mypy/pyright 嚴格型別檢查。

Software Development2026年10月8日

Visual Design Foundations

wshobson

指導排版、色彩、間距與圖示設計，協助建立一致且無障礙的視覺設計系統。

Design & Creative2026年10月8日

Responsive Design

wshobson

指導使用容器查詢、流體排版、CSS Grid 與斷點策略實作響應式網頁版面。

Software Development2026年10月8日

Python Resource Management

wshobson

指導 Python 開發者使用情境管理器、清理模式與串流處理來確定性地管理資源。

Software Development2026年10月8日

更多Software Development技能

Playground

anthropics

精選

建立自成一體的互動式 HTML 遊樂場，包含控制項、即時預覽與可複製的提示詞輸出。

Software Development37K今天更新

M5 Onboard

anthropics

精選

透過 USB 偵測 M5Stack ESP32 開發板，燒錄 UIFlow 2.0 韌體並安裝 MicroPython 應用程式套件。

Software Development37K今天更新

Cardputer Buddy

anthropics

精選

指導迭代 Cardputer-Adv 的 MicroPython 應用程式套件：新增應用程式、透過 USB 序列埠推送檔案、查看日誌並執行 REPL 指令。

Software Development37K今天更新

Testing Strategy

anthropics

精選

設計測試策略與測試計畫，涵蓋測試類型、覆蓋率目標與範例測試案例。

Software Development27K今天更新

Tech Debt

anthropics

精選

辨識、分類並排序技術債，產出評分後的待辦清單與分階段改善計畫。

Software Development27K今天更新

System Design

anthropics

精選

透過需求、高階設計、深入設計、擴充與取捨分析來指導系統與架構設計。

Software Development27K今天更新