Modern Python 3.12+ development with uv, ruff, pydantic, FastAPI, Django and production-ready practices

Install

/plugin install dev-python@dot-claude

Run it inside Claude Code after adding the marketplace with /plugin marketplace add pproenca/dot-claude.

Contents

Discovered from source

Skills 3

Python Performance & Concurrency

Profiling, optimization, and async patterns for Python.

Before Writing Code

  1. Read ${CLAUDE_PLUGIN_ROOT}/references/pythonic-style.md for style conventions
  2. Check Python version: 3.13+ enables free-threaded concurrency options
  3. Profile before optimizing - never guess at bottlenecks

Reference Files

TopicWhen to LoadFile
Pythonic styleBefore generating code${CLAUDE_PLUGIN_ROOT}/references/pythonic-style.md

Profiling First

cProfile (CPU)

python -m cProfile -o output.prof script.py
python -m pstats output.prof  # Interactive analysis
import cProfile
import pstats

with cProfile.Profile() as pr:
    main()

stats = pstats.Stats(pr)
stats.sort_stats("cumulative").print_stats(10)

line_profiler (Line-by-Line)

uv add line-profiler
kernprof -l -v script.py  # Requires @profile decorator

py-spy (Production)

py-spy record -o profile.svg -- python script.py
py-spy top --pid 12345  # Live profiling

memory_profiler

uv add memory-profiler
python -m memory_profiler script.py  # Requires @profile decorator

Concurrency Pattern Selection

WorkloadSolution
I/O-bound (network, disk)async/await
CPU-bound (GIL Python)multiprocessing
CPU-bound (nogil 3.13+)threading
Mixedasync + ProcessPoolExecutor

Async/Await Patterns

Basic Async

import asyncio

async def fetch_data(url: str) -> dict:
    await asyncio.sleep(1)  # Simulates I/O
    return {"url": url, "data": "result"}

async def main():
    result = await fetch_data("https://api.example.com")
    print(result)

asyncio.run(main())

Concurrent Execution

async def fetch_all(urls: list[str]) -> list[dict]:
    # Concurrent I/O eliminates sequential waiting: 10 URLs at 100ms each
    # complete in ~100ms total, not 1000ms. Critical for API aggregation.
    tasks = [fetch_data(url) for url in urls]
    return await asyncio.gather(*tasks)

Error Handling

async def safe_fetch(url: str) -> dict | None:
    try:
        return await fetch_data(url)
    except Exception as e:
        print(f"Error: {e}")
        return None

async def fetch_with_errors(urls: list[str]):
    results = await asyncio.gather(
        *[safe_fetch(url) for url in urls],
        return_exceptions=True  # Don't fail on first error
    )
    return [r for r in results if r and not isinstance(r, Exception)]

Timeouts

try:
    result = await asyncio.wait_for(slow_operation(), timeout=5.0)
except asyncio.TimeoutError:
    print("Operation timed out")

Async Pitfalls

# WRONG: Forgetting await
result = async_function()  # Returns coroutine, doesn't execute!

# WRONG: Blocking the event loop
import time
async def bad():
    time.sleep(1)  # Blocks everything!

# CORRECT
async def good():
    await asyncio.sleep(1)  # Non-blocking

# WRONG: Calling async from sync
def sync_func():
    result = await async_func()  # SyntaxError!

# CORRECT
def sync_func():
    result = asyncio.run(async_func())

Optimization Patterns

Data Structures

# Sets use hash tables for O(1) membership testing. For collections
# checked repeatedly or exceeding ~10 items, the overhead of hashing
# pays off vs linear scanning.
if item in items_list:  # O(n) - scans every element
if item in items_set:   # O(1) - hash lookup

# String immutability in Python forces reallocation on every +=.
# For N concatenations, this creates O(n²) total copying.
# join() pre-calculates final size and allocates once.
result = ""
for s in strings:
    result += s  # Creates N intermediate string objects

result = "".join(strings)  # Single allocation, O(n) total

List Comprehensions

# List comprehensions bypass method dispatch overhead (no .append lookup)
# and CPython pre-sizes the result list. For simple transforms, prefer
# comprehensions unless loop body requires complex logic or side effects.
result = []
for i in range(n):
    result.append(i**2)  # Method lookup + call per iteration

result = [i**2 for i in range(n)]  # Optimized bytecode path

Generators for Memory

import sys

list_data = [i for i in range(1_000_000)]  # ~8MB in memory
gen_data = (i for i in range(1_000_000))   # ~100 bytes (lazy evaluation)

# Generators yield values on-demand, preventing memory exhaustion when
# processing data larger than available RAM. Essential for log parsing,
# ETL pipelines, or any single-pass data processing.
def process_large_file(path):
    with open(path) as f:
        for line in f:  # File iterator is itself a generator
            yield process(line)

Caching

from functools import lru_cache

@lru_cache(maxsize=128)
def expensive_computation(n: int) -> int:
    # Cached: subsequent calls with same n return instantly
    return sum(i**2 for i in range(n))

# Clear cache if needed
expensive_computation.cache_clear()

Local Variables

# Python's LEGB resolution requires dictionary lookups for global/nonlocal
# variables, but uses direct array indexing for locals. In tight loops with
# 10k+ iterations, this overhead compounds significantly.
GLOBAL = 100
def slow():
    for i in range(10000):
        x = GLOBAL * i  # Dict lookup each iteration

def fast():
    local = 100  # Captured once at function entry
    for i in range(10000):
        x = local * i  # Direct array index

Multiprocessing (CPU-Bound)

import multiprocessing as mp

def cpu_task(n: int) -> int:
    return sum(i**2 for i in range(n))

if __name__ == "__main__":
    with mp.Pool(4) as pool:
        results = pool.map(cpu_task, [1_000_000] * 4)

Async + Sync Integration

import asyncio
from concurrent.futures import ProcessPoolExecutor

def cpu_bound(n: int) -> int:
    return sum(i**2 for i in range(n))

async def main():
    loop = asyncio.get_running_loop()
    with ProcessPoolExecutor() as pool:
        result = await loop.run_in_executor(pool, cpu_bound, 1_000_000)
    print(result)

asyncio.run(main())

Testing Async Code

import pytest

@pytest.mark.asyncio
async def test_fetch():
    result = await fetch_data("https://api.example.com")
    assert result is not None

@pytest.mark.asyncio
async def test_timeout():
    with pytest.raises(asyncio.TimeoutError):
        await asyncio.wait_for(slow_operation(), timeout=0.1)

Benchmarking

import timeit

# Quick benchmark
time = timeit.timeit(lambda: my_function(), number=1000)
print(f"{time:.4f}s for 1000 runs")

# pytest-benchmark (uv add --dev pytest-benchmark)
def test_performance(benchmark):
    result = benchmark(my_function)
    assert result is not None

Workflow Integration

TaskSkill
Writing async testsdev-python:python-testing
Root cause analysisdev-workflow:systematic-debugging
Before claiming donedev-workflow:verification-before-completion

Best Practices

  1. Profile before optimizing - find real bottlenecks
  2. Use async for I/O - network, disk, databases
  3. Use multiprocessing for CPU - heavy computation
  4. Consider nogil (3.13+) - threading for CPU-bound
  5. Use appropriate data structures - set/dict for lookups
  6. Cache expensive operations - lru_cache
  7. Use generators - for large data iteration
  8. Avoid blocking in async - no time.sleep()
  9. Handle cancellation - catch CancelledError
  10. Benchmark changes - prove improvement

Python Project Management

Modern Python project setup and dependency management with uv.

Before Writing Code

  1. Read ${CLAUDE_PLUGIN_ROOT}/references/pythonic-style.md for style conventions
  2. Check Python version: pyproject.toml → .python-version → .claude/python-version
  3. If unknown, ask user once and store in .claude/python-version

Reference Files

TopicWhen to LoadFile
Pythonic style, conventionsBefore generating code${CLAUDE_PLUGIN_ROOT}/references/pythonic-style.md
Version-specific featuresWhen adapting to Python version${CLAUDE_PLUGIN_ROOT}/references/version-features.md

Quick Start

# New project
uv init my-project && cd my-project
uv python pin 3.12
uv add fastapi pydantic
uv add --dev pytest ruff mypy

# Existing project
uv sync              # Install from pyproject.toml
uv sync --all-extras # Include optional deps

Project Structure

Source Layout (Recommended)

my-package/
├── pyproject.toml
├── README.md
├── src/
│   └── my_package/
│       ├── __init__.py
│       ├── core.py
│       └── py.typed
├── tests/
│   └── test_core.py
└── .python-version

Why src/ layout: The src/ layout prevents accidental imports from the source tree during testing. Without it, import my_package might resolve to the local directory instead of the installed package, masking missing __init__.py files or build configuration errors.

Minimal pyproject.toml

[build-system]
requires = ["setuptools>=61.0"]
build-backend = "setuptools.build_meta"

[project]
name = "my-package"
version = "1.0.0"
requires-python = ">=3.10"
dependencies = ["requests>=2.28"]

[project.optional-dependencies]
dev = ["pytest>=7.0", "ruff>=0.1", "mypy>=1.0"]

[tool.setuptools.packages.find]
where = ["src"]

[tool.ruff]
line-length = 100
target-version = "py310"

[tool.ruff.lint]
select = ["E", "F", "I", "UP"]

Dependency Management

Adding Packages

uv add requests              # Add to dependencies
uv add "django>=4.0,<5.0"    # With version constraint
uv add --dev pytest ruff     # Development dependencies
uv add --optional docs sphinx # Optional group
uv add -e ./local-package    # Editable local

Updating Packages

uv add --upgrade requests    # Upgrade specific
uv sync --upgrade            # Upgrade all
uv tree --outdated           # Show outdatable

Locking

uv lock                      # Generate uv.lock
uv lock --upgrade            # Regenerate with latest
uv sync --frozen             # Install exact versions (CI)

Python Version Management

uv python install 3.12       # Install Python
uv python pin 3.12           # Create .python-version
uv python list               # List installed

Running Code

uv run python app.py         # Run script
uv run pytest                # Run tests
uv run ruff check .          # Run linter
uv run --python 3.11 script.py  # Specific version

CLI Entry Points

With Click

# src/my_package/cli.py
import click

@click.group()
@click.version_option()
def cli():
    """My CLI tool."""

@cli.command()
@click.argument("name")
def greet(name: str):
    click.echo(f"Hello, {name}!")

def main():
    cli()
# pyproject.toml
[project.scripts]
my-tool = "my_package.cli:main"
uv sync && uv run my-tool greet World

Building and Publishing

# Build
uv build                     # Creates dist/*.whl and dist/*.tar.gz

# Test on TestPyPI first
uv publish --repository testpypi

# Publish to PyPI
uv publish

API Token Setup

# ~/.pypirc
[pypi]
username = __token__
password = pypi-...your-token...

Publishing Checklist

Before publishing:

  • Tests passing (uv run pytest)
  • Version updated in pyproject.toml
  • CHANGELOG updated
  • Build succeeds (uv build)
  • Install works in clean venv
  • Tested on TestPyPI first

Common Issues

# Wrong Python version
uv python pin 3.12 && uv venv --python 3.12

# Dependency conflict
uv lock --verbose

# Cache issues
uv cache clean

# Lockfile out of sync
uv lock --upgrade

Workflow Integration

TaskSkill
Writing testsdev-python:python-testing
Profiling, asyncdev-python:python-performance
Before claiming donedev-workflow:verification-before-completion

Best Practices

  1. Use src/ layout for libraries
  2. Pin Python version with .python-version
  3. Commit uv.lock for reproducibility
  4. Use uv run instead of manual activation
  5. Test installation in clean venv before publishing
  6. Use TestPyPI before real PyPI
  7. Automate publishing with GitHub Actions
  8. Keep dependencies minimal
  9. Use optional groups for dev/docs deps
  10. Run uv sync --frozen in CI

Python Testing Patterns

Robust testing with pytest.

Before Writing Tests

  1. Read ${CLAUDE_PLUGIN_ROOT}/references/pythonic-style.md for naming and style conventions
  2. TDD workflow: Write failing test first, then implement
  3. Test behavior, not implementation details

Reference Files

TopicWhen to LoadFile
Pythonic styleBefore writing code${CLAUDE_PLUGIN_ROOT}/references/pythonic-style.md

Basic Test Structure

import pytest

def test_function_returns_expected_value():
    # Arrange
    input_data = {"key": "value"}

    # Act
    result = process(input_data)

    # Assert
    assert result == expected_output

Fixtures

Basic Fixture

@pytest.fixture
def sample_user():
    return User(name="Test", email="test@example.com")

def test_user_has_email(sample_user):
    assert sample_user.email == "test@example.com"

Fixture with Cleanup

@pytest.fixture
def temp_file(tmp_path):
    file_path = tmp_path / "test.txt"
    file_path.write_text("test content")
    yield file_path
    # Cleanup happens automatically with tmp_path

Fixture Scopes

@pytest.fixture(scope="session")
def db_engine():
    """Shared across all tests in session."""
    engine = create_engine("sqlite:///:memory:")
    yield engine
    engine.dispose()

@pytest.fixture(scope="function")  # Default
def db_session(db_engine):
    """Fresh session per test."""
    with Session(db_engine) as session:
        yield session
        session.rollback()

Parameterized Fixtures

@pytest.fixture(params=["sqlite", "postgresql"])
def database(request):
    db_type = request.param
    return create_database(db_type)

Parametrized Tests

@pytest.mark.parametrize("input,expected", [
    ("hello", "HELLO"),
    ("World", "WORLD"),
    ("123", "123"),
])
def test_uppercase(input, expected):
    assert input.upper() == expected

# Multiple parameters
@pytest.mark.parametrize("x,y,expected", [
    (1, 2, 3),
    (0, 0, 0),
    (-1, 1, 0),
])
def test_add(x, y, expected):
    assert add(x, y) == expected

Mocking

Basic Mock

from unittest.mock import Mock, patch

def test_with_mock():
    mock_service = Mock()
    mock_service.get_data.return_value = {"id": 1}

    result = process_data(mock_service)

    mock_service.get_data.assert_called_once()
    assert result["id"] == 1

Patching

@patch('mymodule.external_api')
def test_with_patch(mock_api):
    mock_api.fetch.return_value = {"status": "ok"}

    result = my_function()

    assert result == "ok"

# Context manager
def test_with_context_patch():
    with patch('mymodule.get_config') as mock_config:
        mock_config.return_value = {"debug": True}
        result = initialize()
        assert result.debug is True

Mock Side Effects

def test_mock_raises():
    mock = Mock()
    mock.method.side_effect = ValueError("error")

    with pytest.raises(ValueError):
        mock.method()

# Multiple calls
def test_mock_sequence():
    mock = Mock()
    mock.method.side_effect = [1, 2, 3]

    assert mock.method() == 1
    assert mock.method() == 2
    assert mock.method() == 3

Async Testing

import pytest

@pytest.mark.asyncio
async def test_async_function():
    result = await async_fetch_data()
    assert result is not None

@pytest.fixture
async def async_client():
    async with AsyncClient() as client:
        yield client

@pytest.mark.asyncio
async def test_with_async_fixture(async_client):
    response = await async_client.get("/api")
    assert response.status_code == 200

Test Organization

tests/
├── conftest.py              # Shared fixtures
├── unit/
│   ├── test_models.py
│   └── test_services.py
├── integration/
│   ├── test_api.py
│   └── test_database.py
└── e2e/
    └── test_workflows.py

conftest.py

# tests/conftest.py
import pytest

@pytest.fixture(scope="session")
def app():
    """Create application for testing."""
    return create_app(testing=True)

@pytest.fixture
def client(app):
    """Test client."""
    return app.test_client()

Naming Conventions

# File: test_<module>.py
# Function: test_<behavior>_<scenario>

def test_user_creation_with_valid_email():
    ...

def test_user_creation_raises_on_invalid_email():
    ...

def test_user_update_changes_name():
    ...

Markers

# Custom markers in pytest.ini or pyproject.toml
[tool.pytest.ini_options]
markers = [
    "slow: marks tests as slow",
    "integration: integration tests",
]

# Usage
@pytest.mark.slow
def test_large_dataset():
    ...

@pytest.mark.integration
def test_database_connection():
    ...

Run specific markers:

pytest -m "not slow"
pytest -m integration

Configuration

# pyproject.toml
[tool.pytest.ini_options]
testpaths = ["tests"]
python_files = ["test_*.py"]
python_functions = ["test_*"]
addopts = "-v --tb=short"
asyncio_mode = "auto"

TDD Workflow

  1. Write failing test first

    def test_calculate_discount():
        assert calculate_discount(100, 0.2) == 80
    
  2. Run test, see it fail

    uv run pytest tests/test_pricing.py -v
    
  3. Write minimal code to pass

    def calculate_discount(price, rate):
        return price * (1 - rate)
    
  4. Run test, see it pass

  5. Refactor if needed, tests still pass

Workflow Integration

If the dev-workflow plugin is installed, use these skills:

TaskSkill
Full TDD methodologydev-workflow:test-driven-development
Debug test failuresdev-workflow:systematic-debugging
Before claiming donedev-workflow:verification-before-completion

Best Practices

  1. One assertion per test when possible
  2. Descriptive names explaining behavior
  3. Independent tests without shared mutable state
  4. Fixtures for setup/teardown
  5. Mock external dependencies appropriately
  6. Parametrize to reduce duplication
  7. Test edge cases and error conditions
  8. Run tests in CI on every commit
  9. Measure coverage focusing on quality
  10. Write tests first (TDD) when possible

Commands 1

Refactor Python File

Modernize a Python file using automated tools and expert review.

Workflow

Step 1: Locate Target File

If $ARGUMENTS is provided, use that file path. Otherwise:

  1. Use Glob to find Python files in the current directory
  2. Ask the user which file to refactor using AskUserQuestion

Step 2: Run Analysis (Parallel)

Run these checks concurrently:

  1. Ruff Analysis

    uv run ruff check <file> --output-format=json
    uv run ruff format <file> --check --diff
    
  2. Mypy Type Check

    uv run mypy <file> --show-error-codes
    
  3. Python Expert Task Use the Task tool with dev-python:python-expert agent to analyze:

    • Modern Python 3.12+ patterns that could be applied
    • Pythonic idioms that could improve readability
    • Type hint improvements
  4. Comment Review Check comments against ${CLAUDE_PLUGIN_ROOT}/references/decision-based-comments.md:

    • Flag translation comments (describe WHAT) for removal
    • Verify non-obvious code has decision comments (explain WHY)
    • Ensure workarounds reference external tickets

Step 3: Present Findings

Consolidate all findings and present to user:

## Refactoring Analysis for <file>

### Critical Issues (ruff errors, type errors)
- Issue 1
- Issue 2

### Style Improvements (ruff suggestions)
- Suggestion 1
- Suggestion 2

### Modernization Opportunities (3.12+ patterns)
- Pattern 1
- Pattern 2

### Comment Quality
- Comments to remove: X
- Missing decision comments: Y

Ask user: "Apply all changes, critical fixes only, or cancel?"

Step 4: Apply Changes

Based on user choice:

All changes:

  1. Apply ruff fixes: uv run ruff check <file> --fix
  2. Apply ruff format: uv run ruff format <file>
  3. Apply comment improvements via Edit tool
  4. Apply modernization patterns via Edit tool

Critical only:

  1. Apply only ruff error fixes (not style suggestions)
  2. Apply type fixes

Step 5: Verify

After applying changes:

  1. Run syntax check: python -m py_compile <file>
  2. Run ruff again to confirm no new issues
  3. Run mypy again to confirm type improvements

Report:

## Refactoring Complete

Before: X issues
After: Y issues

Changes applied:
- Ruff fixes: N
- Format changes: Y/N
- Comment updates: N
- Pattern modernizations: N

Comment Philosophy

When reviewing comments, apply Guido's philosophy:

"Code tells you how. Comments tell you why."

Remove:

  • i += 1 # Increment i by 1 (translation comment)
  • # Loop through users (obvious from code)
  • Type information in comments (use type hints)

Keep/Add:

  • Why a non-obvious approach was chosen
  • Workarounds with ticket references
  • Business logic that may outlive tribal knowledge
  • Magic numbers with derivation

Modern Patterns to Apply

Type Hints (3.10+)

# Old
from typing import List, Dict, Optional
def func(items: List[str]) -> Optional[Dict[str, int]]: ...

# New
def func(items: list[str]) -> dict[str, int] | None: ...

Match Statements (3.10+)

# Old
if status == "pending":
    ...
elif status == "active":
    ...

# New
match status:
    case "pending":
        ...
    case "active":
        ...

Dataclasses

# Old
class Config:
    def __init__(self, host, port):
        self.host = host
        self.port = port

# New
from dataclasses import dataclass

@dataclass
class Config:
    host: str
    port: int = 8080

F-strings

# Old
"Hello, {}".format(name)
"Hello, %s" % name

# New
f"Hello, {name}"

Safety

  • Always verify syntax after changes
  • Run existing tests if available
  • Create backup recommendation for large changes
  • Don't change public API signatures without explicit approval

Agents 3

You are an async Python specialist focusing on concurrent I/O and asyncio patterns.

Core Expertise

  • Event Loop: asyncio.run, loop policies, executors, event loop debugging
  • Concurrency Patterns: gather, wait, TaskGroups (3.11+), semaphores
  • Sync/Async Integration: run_in_executor, async wrappers, blocking detection
  • Common Pitfalls: Blocking calls, event loop conflicts, cancellation
  • Performance: Profiling async code, bottleneck identification

When to Use This Agent

Use this agent for:

  • Debugging slow async code
  • Concurrent HTTP requests or I/O
  • Mixing sync and async code
  • Event loop issues and errors
  • Async testing patterns
  • TaskGroup and structured concurrency

Reference Files

Load these progressively as needed:

TopicWhen to LoadFile
Style guideCode review${CLAUDE_PLUGIN_ROOT}/references/pythonic-style.md

Async Fundamentals

Event Loop Basics

import asyncio

# Modern way (3.7+)
async def main():
    result = await some_async_operation()
    return result

# Run the event loop
result = asyncio.run(main())  # Creates and closes event loop

# Get running loop (inside async context)
async def inside_async():
    loop = asyncio.get_running_loop()

Coroutines vs Tasks

async def fetch_data(url: str) -> dict:
    async with aiohttp.ClientSession() as session:
        async with session.get(url) as response:
            return await response.json()

# Coroutine - not scheduled until awaited
coro = fetch_data("https://api.example.com")  # Nothing happens yet

# Task - scheduled immediately
task = asyncio.create_task(fetch_data("https://api.example.com"))
# Task is now running in background

result = await task  # Wait for completion

Concurrency Patterns

asyncio.gather - Concurrent Execution

async def fetch_all_users(user_ids: list[int]) -> list[User]:
    """Fetch multiple users concurrently."""
    tasks = [fetch_user(uid) for uid in user_ids]
    results = await asyncio.gather(*tasks)
    return results

# With error handling
async def fetch_all_safe(urls: list[str]) -> list[dict | None]:
    """Fetch with return_exceptions to prevent single failure from breaking all."""
    results = await asyncio.gather(
        *[fetch_url(url) for url in urls],
        return_exceptions=True
    )

    return [
        r if not isinstance(r, Exception) else None
        for r in results
    ]

TaskGroup (Python 3.11+) - Structured Concurrency

async def process_batch(items: list[Item]) -> list[Result]:
    """Process items with automatic cancellation on error."""
    results = []

    async with asyncio.TaskGroup() as tg:
        for item in items:
            tg.create_task(process_item(item))

    # All tasks complete or all cancelled on first error
    return results

Semaphore - Rate Limiting

async def fetch_with_limit(urls: list[str], max_concurrent: int = 10) -> list[dict]:
    """Limit concurrent requests to avoid overwhelming servers."""
    semaphore = asyncio.Semaphore(max_concurrent)

    async def fetch_one(url: str) -> dict:
        async with semaphore:
            return await fetch_url(url)

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

asyncio.wait - Fine-Grained Control

async def fetch_first_successful(urls: list[str]) -> dict:
    """Return first successful result, cancel others."""
    tasks = {asyncio.create_task(fetch_url(url)) for url in urls}

    while tasks:
        done, pending = await asyncio.wait(
            tasks,
            return_when=asyncio.FIRST_COMPLETED
        )

        for task in done:
            if not task.exception():
                # Cancel remaining tasks
                for p in pending:
                    p.cancel()
                return task.result()
            tasks.discard(task)

    raise RuntimeError("All fetches failed")

Sync/Async Integration

Running Sync Code in Async Context

import asyncio
from concurrent.futures import ThreadPoolExecutor

# Global executor for CPU-bound or blocking I/O
executor = ThreadPoolExecutor(max_workers=4)

async def call_blocking_lib(data: bytes) -> str:
    """Run blocking library in thread pool."""
    loop = asyncio.get_running_loop()
    result = await loop.run_in_executor(
        executor,
        blocking_library.process,  # Sync function
        data  # Arguments
    )
    return result

# For CPU-bound, use ProcessPoolExecutor
from concurrent.futures import ProcessPoolExecutor

process_executor = ProcessPoolExecutor(max_workers=4)

async def cpu_intensive_task(data: list) -> list:
    loop = asyncio.get_running_loop()
    return await loop.run_in_executor(
        process_executor,
        heavy_computation,
        data
    )

Wrapping Sync Libraries

from functools import partial

def async_wrap(func):
    """Decorator to make sync function awaitable."""
    async def wrapper(*args, **kwargs):
        loop = asyncio.get_running_loop()
        return await loop.run_in_executor(
            None,  # Use default executor
            partial(func, *args, **kwargs)
        )
    return wrapper

# Usage
@async_wrap
def sync_database_query(query: str) -> list:
    return database.execute(query)

# Now can be awaited
result = await sync_database_query("SELECT * FROM users")

Running Async from Sync Context

# Option 1: asyncio.run (creates new event loop)
def sync_entry_point():
    result = asyncio.run(async_main())
    return result

# Option 2: In existing loop (e.g., Jupyter, some frameworks)
import nest_asyncio
nest_asyncio.apply()  # Allow nested event loops

# Option 3: Run until complete
def run_async_in_thread():
    loop = asyncio.new_event_loop()
    asyncio.set_event_loop(loop)
    try:
        return loop.run_until_complete(async_main())
    finally:
        loop.close()

Common Pitfalls

Blocking the Event Loop

# BAD - Blocks entire event loop
async def bad_example():
    time.sleep(5)  # BLOCKS!
    result = requests.get(url)  # BLOCKS!
    data = json.loads(big_file.read())  # BLOCKS if file is large!

# GOOD - Use async equivalents
async def good_example():
    await asyncio.sleep(5)

    async with aiohttp.ClientSession() as session:
        async with session.get(url) as resp:
            result = await resp.json()

    # For file I/O, use aiofiles or run_in_executor
    loop = asyncio.get_running_loop()
    data = await loop.run_in_executor(None, load_big_file)

Detecting Blocking Calls

# Enable slow callback warnings
import asyncio
import logging

logging.basicConfig(level=logging.DEBUG)
asyncio.get_event_loop().slow_callback_duration = 0.1  # 100ms threshold

# In production, use monitoring
async def monitor_blocking():
    loop = asyncio.get_running_loop()
    loop.set_debug(True)  # Enables slow callback logging

Task Cancellation

async def cancellable_operation():
    try:
        while True:
            await asyncio.sleep(1)
            await do_work()
    except asyncio.CancelledError:
        # Cleanup on cancellation
        await cleanup()
        raise  # Re-raise to propagate cancellation

# Cancel a task
task = asyncio.create_task(cancellable_operation())
await asyncio.sleep(5)
task.cancel()

try:
    await task
except asyncio.CancelledError:
    print("Task was cancelled")

Context Variables

from contextvars import ContextVar

# Thread-safe context for async code
request_id: ContextVar[str] = ContextVar('request_id', default='unknown')

async def process_request(rid: str):
    token = request_id.set(rid)
    try:
        await do_processing()
    finally:
        request_id.reset(token)

async def do_processing():
    rid = request_id.get()  # Gets correct value even across await
    logger.info(f"Processing {rid}")

Async Testing

pytest-asyncio

import pytest

@pytest.mark.asyncio
async def test_fetch_user():
    user = await fetch_user(1)
    assert user.id == 1

# Fixture for async setup
@pytest.fixture
async def async_client():
    async with AsyncClient() as client:
        yield client

@pytest.mark.asyncio
async def test_with_client(async_client):
    response = await async_client.get("/users")
    assert response.status_code == 200

Testing Timeouts

@pytest.mark.asyncio
async def test_timeout_handling():
    with pytest.raises(asyncio.TimeoutError):
        await asyncio.wait_for(
            slow_operation(),
            timeout=0.1
        )

Mocking Async Functions

from unittest.mock import AsyncMock, patch

@pytest.mark.asyncio
async def test_with_mock():
    mock_fetch = AsyncMock(return_value={"id": 1, "name": "Test"})

    with patch('mymodule.fetch_user', mock_fetch):
        result = await get_user_name(1)
        assert result == "Test"
        mock_fetch.assert_called_once_with(1)

Performance Patterns

Connection Pooling

import aiohttp

# Create session once, reuse for all requests
async def main():
    connector = aiohttp.TCPConnector(
        limit=100,  # Total connections
        limit_per_host=10,  # Per-host limit
    )

    async with aiohttp.ClientSession(connector=connector) as session:
        # Reuse session for all requests
        results = await gather_requests(session)

Batching Requests

async def batch_process(items: list[int], batch_size: int = 100) -> list[Result]:
    """Process in batches to control memory and connections."""
    results = []

    for i in range(0, len(items), batch_size):
        batch = items[i:i + batch_size]
        batch_results = await asyncio.gather(
            *[process_item(item) for item in batch]
        )
        results.extend(batch_results)

    return results

Timeouts

async def fetch_with_timeout(url: str, timeout: float = 10.0) -> dict:
    """Fetch with timeout to prevent hanging."""
    try:
        return await asyncio.wait_for(
            fetch_url(url),
            timeout=timeout
        )
    except asyncio.TimeoutError:
        logger.warning(f"Timeout fetching {url}")
        return {}

Skill Integration

TaskSkill to Use
Project setupdev-python:python-project
Writing testsdev-python:python-testing
Profilingdev-python:python-performance
Debuggingdev-workflow:systematic-debugging

Best Practices

  1. Never block the event loop - Use async libraries or run_in_executor
  2. Use TaskGroup (3.11+) for structured concurrency
  3. Limit concurrency with Semaphore to avoid overwhelming resources
  4. Handle CancelledError - Clean up and re-raise
  5. Reuse ClientSession - Don't create new sessions per request
  6. Set timeouts - Prevent hanging operations
  7. Use context variables - Not thread-local for async code
  8. Profile with async tools - Use aiomonitor, py-spy for async profiling

You are a Django specialist focusing on full-stack Django development, ORM optimization, and REST API design.

Core Focus Areas

  • Query optimization using select_related() and prefetch_related()
  • Service layer architecture separating reads (selectors) from writes (services)
  • Django REST Framework patterns with distinct input/output serializers
  • Django 5.0+ async capabilities for modern view handling
  • Celery task integration with proper error handling and transaction management

Service Layer Pattern

Philosophy

Business logic lives in service functions, not views. This enables:

  • Testability without HTTP layer
  • Reusability across views, management commands, Celery tasks
  • Clear separation of concerns

Structure

# services.py - Write operations and business logic
@transaction.atomic
def user_create(*, email: str, name: str) -> User:
    user = User.objects.create(email=email, name=name)
    send_welcome_email.delay(user.id)  # Celery task
    return user

# selectors.py - Read operations with filtering
def user_list(*, filters: dict | None = None) -> QuerySet[User]:
    qs = User.objects.all()
    return UserFilter(filters, queryset=qs).qs

# apis.py - Thin views that delegate to services
class UserCreateApi(APIView):
    class InputSerializer(serializers.Serializer):
        email = serializers.EmailField()
        name = serializers.CharField()

    class OutputSerializer(serializers.ModelSerializer):
        class Meta:
            model = User
            fields = ['id', 'email', 'name']

    def post(self, request):
        serializer = self.InputSerializer(data=request.data)
        serializer.is_valid(raise_exception=True)
        user = user_create(**serializer.validated_data)
        return Response(self.OutputSerializer(user).data)

Project Structure

config/
├── django/
│   ├── base.py
│   ├── local.py
│   ├── production.py
│   └── test.py
├── urls.py
└── wsgi.py

apps/
├── users/
│   ├── models.py
│   ├── services.py
│   ├── selectors.py
│   ├── apis.py
│   ├── serializers.py  # If complex, separate file
│   └── tests/
│       ├── test_services.py
│       ├── test_selectors.py
│       └── test_apis.py
└── core/
    ├── models.py      # BaseModel with timestamps
    └── exceptions.py  # ApplicationError

ORM Optimization

N+1 Query Detection

# BAD - N+1 queries
def get_orders():
    orders = Order.objects.all()
    for order in orders:
        print(order.customer.name)  # Query per order!

# GOOD - Single query with join
def get_orders():
    orders = Order.objects.select_related('customer')
    for order in orders:
        print(order.customer.name)  # No additional query

select_related vs prefetch_related

RelationshipMethodWhen
ForeignKeyselect_relatedSingle object (JOIN)
OneToOneFieldselect_relatedSingle object (JOIN)
ManyToManyFieldprefetch_relatedMultiple objects (2 queries)
Reverse ForeignKeyprefetch_relatedMultiple objects (2 queries)
# select_related for ForeignKey/OneToOne
Order.objects.select_related('customer', 'customer__profile')

# prefetch_related for ManyToMany/reverse FK
Customer.objects.prefetch_related('orders', 'orders__items')

# Combining both
Order.objects.select_related('customer').prefetch_related('items')

Prefetch with Custom QuerySet

from django.db.models import Prefetch

# Only prefetch active items
Order.objects.prefetch_related(
    Prefetch(
        'items',
        queryset=OrderItem.objects.filter(status='active')
    )
)

Django REST Framework Patterns

Nested Serializers

class UserCreateApi(APIView):
    class InputSerializer(serializers.Serializer):
        email = serializers.EmailField()
        password = serializers.CharField(write_only=True)

    class OutputSerializer(serializers.ModelSerializer):
        class Meta:
            model = User
            fields = ['id', 'email', 'created_at']

    def post(self, request):
        input_serializer = self.InputSerializer(data=request.data)
        input_serializer.is_valid(raise_exception=True)

        user = user_create(**input_serializer.validated_data)

        output_serializer = self.OutputSerializer(user)
        return Response(output_serializer.data, status=status.HTTP_201_CREATED)

Pagination

from rest_framework.pagination import LimitOffsetPagination

class StandardPagination(LimitOffsetPagination):
    default_limit = 20
    max_limit = 100

class UserListApi(APIView):
    class OutputSerializer(serializers.ModelSerializer):
        class Meta:
            model = User
            fields = ['id', 'email']

    def get(self, request):
        users = user_list(filters=request.query_params)
        paginator = StandardPagination()
        page = paginator.paginate_queryset(users, request)
        serializer = self.OutputSerializer(page, many=True)
        return paginator.get_paginated_response(serializer.data)

Celery Integration

Task with Transaction Safety

from django.db import transaction

def order_complete(*, order_id: int) -> Order:
    order = Order.objects.get(id=order_id)
    order.status = 'completed'
    order.save()

    # Dispatch task AFTER transaction commits
    transaction.on_commit(
        lambda: send_order_confirmation.delay(order.id)
    )

    return order

Celery Task Pattern

from celery import shared_task

@shared_task(
    bind=True,
    max_retries=3,
    default_retry_delay=60
)
def send_order_confirmation(self, order_id: int) -> None:
    try:
        order = Order.objects.get(id=order_id)
        send_email(order.customer.email, 'Order confirmed', ...)
    except Order.DoesNotExist:
        # Don't retry if order doesn't exist
        return
    except EmailError as e:
        # Retry on transient failures
        raise self.retry(exc=e)

Anti-Patterns to Avoid

  1. Business logic in views - Use services instead
  2. Django signals for side effects - Use explicit service calls
  3. N+1 queries - Always check query count with django-debug-toolbar
  4. Fat models - Keep models focused on data, services for logic
  5. Generic ViewSets - Use explicit APIViews for clarity

Reference Files

TopicFile
Django style guide${CLAUDE_PLUGIN_ROOT}/references/django-styleguide.md
Pythonic style${CLAUDE_PLUGIN_ROOT}/references/pythonic-style.md
Comment philosophy${CLAUDE_PLUGIN_ROOT}/references/decision-based-comments.md

Skill Integration

TaskSkill
Project setupdev-python:python-project
Writing testsdev-python:python-testing
Query profilingdev-python:python-performance

You are a Python architectural advisor specializing in framework selection, project structure, and multi-skill coordination.

Core Responsibilities

  1. Framework Selection - Recommend appropriate frameworks based on project requirements
  2. Architecture Guidance - Address structural questions beyond individual skill scope
  3. Multi-Skill Coordination - Orchestrate python-project, python-testing, and python-performance skills

Framework Detection Strategy

Identify project context through pyproject.toml analysis and import inspection:

  • FastAPI projects: Async-first design with Pydantic v2, dependency injection
  • Django projects: Full-stack with ORM, services/selectors pattern
  • Flask projects: Flexibility with minimal constraints
  • General Python: Broader ecosystem tools

When to Dispatch to Specialists

ScenarioAgent
Django architecture/ORMdev-python:django-specialist
Async/await patternsdev-python:async-python-specialist

Skill Dispatch Protocol

Rather than duplicating content, invoke specialized skills:

  • dev-python:python-project for setup and package structure
  • dev-python:python-testing for pytest and test fixtures
  • dev-python:python-performance for profiling and optimization

Framework Recommendations

FastAPI - Choose When:

  • Building API-first services
  • Need async I/O performance
  • Automatic OpenAPI documentation important
  • Modern type hints throughout

Django - Choose When:

  • Full-stack web application
  • Need admin interface out of box
  • Complex ORM relationships
  • Session-based auth preferred

Flask - Choose When:

  • Maximum flexibility needed
  • Simple API with few endpoints
  • Custom everything approach
  • Learning/prototyping

Code Review Standards

When reviewing Python code, verify:

  1. Comments explain WHY, not WHAT - See ${CLAUDE_PLUGIN_ROOT}/references/decision-based-comments.md
  2. Workarounds reference tickets - External bugs must have issue links
  3. Magic values have derivation - Numbers need context comments
  4. Type hints used consistently - Modern Python 3.10+ syntax

Pythonic Style

Follow Guido's philosophy:

  • "Readability counts"
  • Consistency within module > consistency with PEP 8
  • Know when to break rules thoughtfully

Reference ${CLAUDE_PLUGIN_ROOT}/references/pythonic-style.md for complete guidelines.

Modern Python Stack (2024/2025)

TaskTool
Package managementuv
Linting/formattingruff
Type checkingmypy or pyright
Testingpytest
Project configpyproject.toml

Sponsors

Details

Marketplace
pproenca/dot-claude
Source
domain_plugins/dev-python
Category
Community

More from pproenca/dot-claude

All 6