
dev-python
Modern Python 3.12+ development with uv, ruff, pydantic, FastAPI, Django and production-ready practices
Install
/plugin install dev-python@dot-claudeRun it inside Claude Code after adding the marketplace with /plugin marketplace add pproenca/dot-claude.
Contents
Discovered from sourceSkills 3
Python Performance & Concurrency
Profiling, optimization, and async patterns for Python.
Before Writing Code
- Read
${CLAUDE_PLUGIN_ROOT}/references/pythonic-style.mdfor style conventions - Check Python version: 3.13+ enables free-threaded concurrency options
- Profile before optimizing - never guess at bottlenecks
Reference Files
| Topic | When to Load | File |
|---|---|---|
| Pythonic style | Before 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
| Workload | Solution |
|---|---|
| I/O-bound (network, disk) | async/await |
| CPU-bound (GIL Python) | multiprocessing |
| CPU-bound (nogil 3.13+) | threading |
| Mixed | async + 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
| Task | Skill |
|---|---|
| Writing async tests | dev-python:python-testing |
| Root cause analysis | dev-workflow:systematic-debugging |
| Before claiming done | dev-workflow:verification-before-completion |
Best Practices
- Profile before optimizing - find real bottlenecks
- Use async for I/O - network, disk, databases
- Use multiprocessing for CPU - heavy computation
- Consider nogil (3.13+) - threading for CPU-bound
- Use appropriate data structures - set/dict for lookups
- Cache expensive operations - lru_cache
- Use generators - for large data iteration
- Avoid blocking in async - no time.sleep()
- Handle cancellation - catch CancelledError
- Benchmark changes - prove improvement
Python Project Management
Modern Python project setup and dependency management with uv.
Before Writing Code
- Read
${CLAUDE_PLUGIN_ROOT}/references/pythonic-style.mdfor style conventions - Check Python version:
pyproject.toml→.python-version→.claude/python-version - If unknown, ask user once and store in
.claude/python-version
Reference Files
| Topic | When to Load | File |
|---|---|---|
| Pythonic style, conventions | Before generating code | ${CLAUDE_PLUGIN_ROOT}/references/pythonic-style.md |
| Version-specific features | When 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
| Task | Skill |
|---|---|
| Writing tests | dev-python:python-testing |
| Profiling, async | dev-python:python-performance |
| Before claiming done | dev-workflow:verification-before-completion |
Best Practices
- Use
src/layout for libraries - Pin Python version with
.python-version - Commit
uv.lockfor reproducibility - Use
uv runinstead of manual activation - Test installation in clean venv before publishing
- Use TestPyPI before real PyPI
- Automate publishing with GitHub Actions
- Keep dependencies minimal
- Use optional groups for dev/docs deps
- Run
uv sync --frozenin CI
Python Testing Patterns
Robust testing with pytest.
Before Writing Tests
- Read
${CLAUDE_PLUGIN_ROOT}/references/pythonic-style.mdfor naming and style conventions - TDD workflow: Write failing test first, then implement
- Test behavior, not implementation details
Reference Files
| Topic | When to Load | File |
|---|---|---|
| Pythonic style | Before 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
-
Write failing test first
def test_calculate_discount(): assert calculate_discount(100, 0.2) == 80 -
Run test, see it fail
uv run pytest tests/test_pricing.py -v -
Write minimal code to pass
def calculate_discount(price, rate): return price * (1 - rate) -
Run test, see it pass
-
Refactor if needed, tests still pass
Workflow Integration
If the dev-workflow plugin is installed, use these skills:
| Task | Skill |
|---|---|
| Full TDD methodology | dev-workflow:test-driven-development |
| Debug test failures | dev-workflow:systematic-debugging |
| Before claiming done | dev-workflow:verification-before-completion |
Best Practices
- One assertion per test when possible
- Descriptive names explaining behavior
- Independent tests without shared mutable state
- Fixtures for setup/teardown
- Mock external dependencies appropriately
- Parametrize to reduce duplication
- Test edge cases and error conditions
- Run tests in CI on every commit
- Measure coverage focusing on quality
- 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:
- Use Glob to find Python files in the current directory
- Ask the user which file to refactor using AskUserQuestion
Step 2: Run Analysis (Parallel)
Run these checks concurrently:
-
Ruff Analysis
uv run ruff check <file> --output-format=json uv run ruff format <file> --check --diff -
Mypy Type Check
uv run mypy <file> --show-error-codes -
Python Expert Task Use the Task tool with
dev-python:python-expertagent to analyze:- Modern Python 3.12+ patterns that could be applied
- Pythonic idioms that could improve readability
- Type hint improvements
-
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:
- Apply ruff fixes:
uv run ruff check <file> --fix - Apply ruff format:
uv run ruff format <file> - Apply comment improvements via Edit tool
- Apply modernization patterns via Edit tool
Critical only:
- Apply only ruff error fixes (not style suggestions)
- Apply type fixes
Step 5: Verify
After applying changes:
- Run syntax check:
python -m py_compile <file> - Run ruff again to confirm no new issues
- 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:
| Topic | When to Load | File |
|---|---|---|
| Style guide | Code 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
| Task | Skill to Use |
|---|---|
| Project setup | dev-python:python-project |
| Writing tests | dev-python:python-testing |
| Profiling | dev-python:python-performance |
| Debugging | dev-workflow:systematic-debugging |
Best Practices
- Never block the event loop - Use async libraries or run_in_executor
- Use TaskGroup (3.11+) for structured concurrency
- Limit concurrency with Semaphore to avoid overwhelming resources
- Handle CancelledError - Clean up and re-raise
- Reuse ClientSession - Don't create new sessions per request
- Set timeouts - Prevent hanging operations
- Use context variables - Not thread-local for async code
- 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()andprefetch_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
| Relationship | Method | When |
|---|---|---|
| ForeignKey | select_related | Single object (JOIN) |
| OneToOneField | select_related | Single object (JOIN) |
| ManyToManyField | prefetch_related | Multiple objects (2 queries) |
| Reverse ForeignKey | prefetch_related | Multiple 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
- Business logic in views - Use services instead
- Django signals for side effects - Use explicit service calls
- N+1 queries - Always check query count with
django-debug-toolbar - Fat models - Keep models focused on data, services for logic
- Generic ViewSets - Use explicit APIViews for clarity
Reference Files
| Topic | File |
|---|---|
| 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
| Task | Skill |
|---|---|
| Project setup | dev-python:python-project |
| Writing tests | dev-python:python-testing |
| Query profiling | dev-python:python-performance |
You are a Python architectural advisor specializing in framework selection, project structure, and multi-skill coordination.
Core Responsibilities
- Framework Selection - Recommend appropriate frameworks based on project requirements
- Architecture Guidance - Address structural questions beyond individual skill scope
- 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
| Scenario | Agent |
|---|---|
| Django architecture/ORM | dev-python:django-specialist |
| Async/await patterns | dev-python:async-python-specialist |
Skill Dispatch Protocol
Rather than duplicating content, invoke specialized skills:
dev-python:python-projectfor setup and package structuredev-python:python-testingfor pytest and test fixturesdev-python:python-performancefor 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:
- Comments explain WHY, not WHAT - See
${CLAUDE_PLUGIN_ROOT}/references/decision-based-comments.md - Workarounds reference tickets - External bugs must have issue links
- Magic values have derivation - Numbers need context comments
- 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)
| Task | Tool |
|---|---|
| Package management | uv |
| Linting/formatting | ruff |
| Type checking | mypy or pyright |
| Testing | pytest |
| Project config | pyproject.toml |
Hooks 2
Sponsors
Details
- Marketplace
- pproenca/dot-claude
- Source
- domain_plugins/dev-python
- Category
- Community