Engineering PythonAsyncType Hints

Python Pro

Advanced Python patterns: async/await, metaclasses, decorators, type hints, packaging, virtual environments, and performance optimization.

An expert Python practitioner covering the full language depth: async concurrency with asyncio, descriptor and metaclass machinery, parametric decorators, PEP 695 type parameter syntax, and packaging with pyproject.toml. Diagnoses performance bottlenecks using cProfile and memory_profiler, and guides strict mypy adoption without breaking existing code.

Added Mar 20, 2026

$npx skills add johnefemer/skillfish --skill python-pro

Capabilities Real Examples Get Started Models & Context Works Great With

What This Skill Can Do

Concrete capabilities you get when you install this skill.

Design async pipelines with asyncio, aiohttp, and TaskGroup

Write parametric decorators, descriptors, and metaclasses

Annotate codebases with mypy-compatible type hints incrementally

Profile CPU and memory bottlenecks with cProfile and tracemalloc

Package and publish libraries to PyPI with pyproject.toml and Hatch

Migrate from requirements.txt to modern dependency management (uv, Poetry)

Real Conversations

See how the Python Pro skill responds to actual requests. These are representative examples of what your AI agent will produce.

You

I need a retry decorator for async functions that does exponential backoff with jitter, a max retry count, and only retries on specific exception types. How should I implement this?

Agent

Here's a production-grade async retry decorator:

import asyncio
import random
from functools import wraps
from typing import Type

def async_retry(
    max_attempts: int = 3,
    base_delay: float = 0.5,
    max_delay: float = 30.0,
    exceptions: tuple[Type[Exception], ...] = (Exception,),
):
    def decorator(func):
        @wraps(func)
        async def wrapper(*args, **kwargs):
            last_exc: Exception | None = None
            for attempt in range(max_attempts):
                try:
                    return await func(*args, **kwargs)
                except exceptions as exc:
                    last_exc = exc
                    if attempt == max_attempts - 1:
                        raise
                    delay = min(base_delay * (2 ** attempt), max_delay)
                    jitter = random.uniform(0, delay * 0.25)
                    await asyncio.sleep(delay + jitter)
            raise last_exc  # unreachable, satisfies type checker
        return wrapper
    return decorator

# Usage
@async_retry(max_attempts=4, base_delay=1.0, exceptions=(aiohttp.ClientError, TimeoutError))
async def fetch_data(url: str) -> dict:
    async with aiohttp.ClientSession() as session:
        async with session.get(url, timeout=aiohttp.ClientTimeout(total=10)) as resp:
            return await resp.json()

Key decisions: @wraps(func) preserves docstrings and __name__; exceptions as a tuple means you can pass multiple types; jitter is 0–25% of the delay to prevent thundering-herd on concurrent retries.

You

My FastAPI app handles ~200 concurrent requests. Under load, some requests hang for 30+ seconds even though my endpoint just does a single DB query. I'm using asyncpg. What's happening?

Agent

This is almost certainly a blocking call on the event loop thread, not a database issue. Here's how to diagnose and fix:

Diagnose with asyncio debug mode:

import asyncio
asyncio.get_event_loop().set_debug(True)
# Logs any coroutine that blocks >100ms — you'll see the culprit immediately

Common blocking culprits in FastAPI apps:

time.sleep() instead of await asyncio.sleep()
Synchronous file I/O (open(), json.load()) — use aiofiles
requests library instead of httpx async client
CPU-bound code (JSON parsing large payloads, image processing) — offload to a thread pool:

import asyncio
from concurrent.futures import ThreadPoolExecutor

_pool = ThreadPoolExecutor(max_workers=4)

async def cpu_bound_work(data: bytes) -> dict:
    loop = asyncio.get_running_loop()
    return await loop.run_in_executor(_pool, parse_heavy_payload, data)

asyncpg-specific: Verify you're not accidentally creating a new pool per request. One pool per app lifetime:

# lifespan context — create once
app.state.pool = await asyncpg.create_pool(dsn, min_size=5, max_size=20)

If pool max_size is 10 and you have 200 concurrent requests, 190 will queue waiting for a connection. Bump max_size or reduce request parallelism with a semaphore.

Get Started

How to install and use this skill in your preferred environment.

Skills are designed for AI coding agents (Claude Code, Cursor, Windsurf) and IDE-based workflows where the agent can read files, run scripts, and act on your codebase.

Models & Context

Which AI models and context windows work best with this skill.

Recommended Models

Claude Sonnet 4 or GPT-4o handles Python idioms and async edge cases well. Avoid smaller models for metaclass or descriptor explanations.

Context Window

SKILL.md is ~5KB. Comfortable in 32K context for most tasks; large codebase refactors benefit from 64K+.

Pro tips for best results

1

Be specific

Include numbers — users, budget, RPS — so the skill can size the architecture.

2

Share constraints

Compliance needs, team size, and existing stack all improve the output.

3

Iterate

Start with a high-level design, then ask follow-ups for IaC, cost analysis, or security review.

4

Combine skills

Pair with companion skills below for end-to-end coverage.

Works Great With

These skills complement Python Pro for end-to-end coverage. Install them together for better results.

Senior Backend

REST APIs, database optimization, authentication, and microservices.

BackendAPIs

FastAPI Developer

FastAPI development: Pydantic v2 models, dependency injection, async patterns, background tasks, WebSocket endpoints, OpenAPI customization, and deployment.

FastAPIPydantic

Django Developer

Django development: class-based views, ORM optimization, Django REST Framework, Celery async tasks, deployment patterns, and async Django.

DjangoPython

TDD Guide

Test-driven development workflow with test generation and multi-framework support.

TDDTesting

Performance Profiler

Node/Python/Go profiling, bundle analysis, and load testing.

PerformanceProfiling

$ skillfish add johnefemer/skillfish --all # install all skills at once

Ready to try Python Pro?

Install the skill and start getting expert-level guidance in your workflow — any agent, any IDE.