Python Development Patterns Skill

A Claude Code skill for writing production-quality Python — covering idiomatic patterns, type hints, async programming, testing strategies, project structure, and performance optimization.

When to Use This Skill

Choose this skill when:

• Writing Python code following modern best practices (3.10+)
• Implementing async patterns with asyncio
• Structuring Python projects for maintainability
• Adding type hints and runtime validation
• Optimizing Python performance
• Writing tests with pytest

Consider alternatives when:

• You need Django or Flask-specific guidance (use framework skills)
• You need data science patterns (use a data science skill)
• You need machine learning (use a ML/AI skill)

Quick Start

Copy
# Set up a Python project
python -m venv .venv
source .venv/bin/activate
pip install ruff mypy pytest

Copy
# Modern Python patterns (3.10+)
from dataclasses import dataclass, field
from typing import TypeAlias

# Type aliases for clarity
UserId: TypeAlias = str
Email: TypeAlias = str

@dataclass
class User:
    id: UserId
    name: str
    email: Email
    tags: list[str] = field(default_factory=list)

    def is_admin(self) -> bool:
        return "admin" in self.tags

# Pattern matching (3.10+)
def handle_response(status: int) -> str:
    match status:
        case 200: return "OK"
        case 404: return "Not Found"
        case 500: return "Server Error"
        case _:   return f"Unknown: {status}"

Core Concepts

Python Idioms

Pattern	Pythonic	Not Pythonic
List comprehension	[x*2 for x in items]	map(lambda x: x*2, items)
Dictionary building	{k: v for k, v in pairs}	Manual loop with d[k] = v
Context manager	with open(f) as fp:	fp = open(f); fp.close()
Unpacking	a, b, *rest = items	a = items[0]; b = items[1]
Truthiness	if items:	if len(items) > 0:
EAFP	try: x[key]	if key in x: x[key]

Async Patterns

Copy
import asyncio
from aiohttp import ClientSession

async def fetch_all(urls: list[str]) -> list[dict]:
    async with ClientSession() as session:
        tasks = [fetch_one(session, url) for url in urls]
        return await asyncio.gather(*tasks)

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

# Run async code
results = asyncio.run(fetch_all(["https://api.example.com/1", "https://api.example.com/2"]))

Project Structure

myproject/
├── src/myproject/
│   ├── __init__.py
│   ├── models.py        # Data models
│   ├── services.py      # Business logic
│   ├── api.py           # API endpoints
│   └── utils.py         # Utilities
├── tests/
│   ├── conftest.py      # Shared fixtures
│   ├── test_models.py
│   └── test_services.py
├── pyproject.toml        # Project config
├── .python-version       # Python version
└── ruff.toml             # Linter config

Configuration

Parameter	Type	Default	Description
python_version	string	"3.12"	Minimum Python version
type_checker	string	"mypy"	Type checker: mypy, pyright
linter	string	"ruff"	Linter: ruff, flake8, pylint
formatter	string	"ruff"	Formatter: ruff, black
test_framework	string	"pytest"	Test framework: pytest, unittest
async_framework	string	"asyncio"	Async: asyncio, trio
package_manager	string	"pip"	Package manager: pip, uv, poetry

Best Practices

1. Use type hints on all public functions — type hints serve as documentation and enable static analysis; use mypy --strict or pyright to catch type errors before runtime.

2. Prefer dataclass or pydantic.BaseModel over plain dicts — structured data types provide validation, IDE autocompletion, and self-documenting code; dicts are error-prone and hard to refactor.

3. Use ruff for both linting and formatting — ruff is 10-100x faster than flake8 + black combined and covers both linting and formatting in a single tool.

4. Write fixtures in conftest.py for shared test setup — pytest fixtures provide dependency injection for tests; shared fixtures in conftest.py are auto-discovered by all tests in the directory.

5. Use asyncio.gather for concurrent I/O operations — when making multiple HTTP requests or database queries, gather them for concurrent execution instead of awaiting sequentially.

Common Issues

Circular imports between modules — Two modules importing each other causes ImportError. Break the cycle by moving shared types to a separate types.py module or using TYPE_CHECKING guard for type-only imports.

asyncio.run() fails with "event loop already running" — This happens inside Jupyter notebooks or frameworks that already have an event loop. Use await directly or nest_asyncio.apply() as a workaround.

Type checker reports false positives on library code — Some libraries lack type stubs. Install types-* packages from PyPI (e.g., types-requests) or add # type: ignore[import] for untyped libraries.