ABOUTME: Comprehensive skill for idiomatic Python best practices Skill

ABOUTME: Comprehensive skill for idiomatic Python best practices

ABOUTME: Covers loops, dicts, comprehensions, typing, Pydantic v2, error handling

Idiomatic Python Best Practices

Target: Python 3.11+ with modern tooling (uv, Pydantic v2, type hints).

Detailed patterns: See references/pydantic-patterns.md and references/advanced-patterns.md

Quick Reference

| Pattern | Pythonic Way | Avoid | |---------|--------------|-------| | Iteration | for item in items: | for i in range(len(items)): | | Index + Value | for i, v in enumerate(seq): | Manual counter | | Dict Access | d.get("key", default) | if "key" in d: d["key"] | | Dict Iteration | for k, v in d.items(): | for k in d: v = d[k] | | Swap Variables | a, b = b, a | temp = a; a = b; b = temp | | Build Strings | "".join(parts) | s += part in loop | | Membership | x in set_or_dict | x in list (for large) | | File I/O | with open(...) as f: | Manual f.close() | | Truthiness | if items: | if len(items) > 0: | | None Check | if x is None: | if x == None: |

🛑 FILE OPERATION CHECKPOINT (BLOCKING)

Before EVERY Write or Edit tool call on a .py file:

╔══════════════════════════════════════════════════════════════════╗
║  🛑 STOP - PYTHON SKILL CHECK                                    ║
║                                                                  ║
║  You are about to modify a .py file.                             ║
║                                                                  ║
║  QUESTION: Is /python skill currently active?                    ║
║                                                                  ║
║  If YES → Proceed with the edit                                  ║
║  If NO  → STOP! Invoke /python FIRST, then edit                  ║
║                                                                  ║
║  This check applies to:                                          ║
║  ✗ Write tool with file_path ending in .py                       ║
║  ✗ Edit tool with file_path ending in .py                        ║
║  ✗ ANY Python file, regardless of conversation topic             ║
║                                                                  ║
║  Examples that REQUIRE this skill:                               ║
║  - "update the schemas" (edits schemas.py)                       ║
║  - "fix the import" (edits any .py file)                         ║
║  - "add logging" (edits Python code)                             ║
╚══════════════════════════════════════════════════════════════════╝

Why this matters: In session 1ea73ffd, Claude edited 3+ Python files without invoking the Python skill, leading to potential style/pattern inconsistencies.

🔄 RESUMED SESSION CHECKPOINT

┌─────────────────────────────────────────────────────────────┐
│  SESSION RESUMED - PYTHON SKILL VERIFICATION                │
│                                                             │
│  Before continuing:                                         │
│  1. Type hints on all functions?                            │
│  2. Pydantic v2 for API validation?                         │
│  3. ABOUTME headers on new files?                           │
│  4. Run: ruff check <file>.py && mypy <file>.py             │
│  5. Re-invoke /python if skill context was lost             │
└─────────────────────────────────────────────────────────────┘

Core Patterns

Iteration

# Direct iteration
for item in items:
    process(item)

# With index
for i, item in enumerate(items):
    print(f"{i}: {item}")

# Parallel iteration
for name, score in zip(names, scores, strict=True):
    process(name, score)

# Reversed/sorted (no copy)
for item in reversed(items):
    process(item)

Dictionaries

# Safe access with default
port = config.get("port", 8080)

# Initialize-if-missing
groups: dict[str, list[str]] = {}
groups.setdefault(category, []).append(item)

# Merge dicts (Python 3.9+)
merged = defaults | overrides

# Dict comprehension
squares = {n: n**2 for n in range(10)}

Comprehensions

# List comprehension
squared = [x**2 for x in numbers]
evens = [x for x in numbers if x % 2 == 0]

# Generator expression (memory efficient)
total = sum(x**2 for x in range(1_000_000))
any_match = any(item.is_valid for item in items)

# Set comprehension
unique_domains = {email.split("@")[1] for email in emails}

Unpacking

# Basic
x, y, z = coordinates
first, *rest = items
a, b = b, a  # Swap

# Dict unpacking
combined = {**defaults, **overrides}
connect(**config)  # Pass as kwargs

Type Hints

Basic Types

def greet(name: str, times: int = 1) -> str:
    return f"Hello, {name}! " * times

def process(items: list[str]) -> dict[str, int]:
    return {item: len(item) for item in items}

Optional and Union

def find_user(user_id: int) -> User | None:
    return db.get(user_id)

def process(value: int | str | None) -> str:
    if value is None:
        return "none"
    return str(value)

Generic Collections

from collections.abc import Sequence, Mapping, Iterable, Callable

def process_items(items: Sequence[str]) -> list[str]:
    return [item.upper() for item in items]

def apply_func(data: Iterable[int], func: Callable[[int], int]) -> list[int]:
    return [func(x) for x in data]

Pydantic v2 (Quick Reference)

Use Pydantic for API validation and serialization. Full patterns: references/pydantic-patterns.md

from pydantic import BaseModel, Field, EmailStr

class User(BaseModel):
    id: int
    email: EmailStr
    name: str = Field(min_length=1, max_length=100)
    is_active: bool = True

# Parse and validate
user = User.model_validate({"id": 1, "email": "test@example.com", "name": "Alice"})

# Serialize
user.model_dump()       # To dict
user.model_dump_json()  # To JSON

When to Use What

| Data Type | Use | |-----------|-----| | API request/response | Pydantic BaseModel | | External JSON/dict shape | TypedDict (type hints only) | | Internal data container | dataclass | | Configuration | pydantic-settings |

Error Handling

Catch Specific Exceptions

try:
    value = int(user_input)
except ValueError:
    print("Invalid number")
except TypeError:
    print("Wrong type")

# DON'T: bare except
try:
    value = int(user_input)
except:  # Catches KeyboardInterrupt too!
    pass

EAFP (Pythonic)

# EAFP: Easier to Ask Forgiveness than Permission
try:
    value = mapping[key]
except KeyError:
    value = default

# vs LBYL: Look Before You Leap
if key in mapping:
    value = mapping[key]
else:
    value = default

Custom Exceptions

class ValidationError(Exception):
    def __init__(self, field: str, message: str):
        self.field = field
        self.message = message
        super().__init__(f"{field}: {message}")

def validate_email(email: str) -> str:
    if "@" not in email:
        raise ValidationError("email", "Must contain @")
    return email.lower()

Context Managers

# File handling (always use with)
with open("data.txt", "r", encoding="utf-8") as f:
    content = f.read()

# Multiple files
with open("in.txt") as infile, open("out.txt", "w") as outfile:
    outfile.write(infile.read().upper())

String Handling

# f-strings
name = "Alice"
score = 95.678
print(f"Score: {score:.2f}")  # 95.68
print(f"{1000000:,}")  # 1,000,000
print(f"{x=}")  # Debug: x=42

# String building (use join, not +=)
result = " ".join(parts)

Best Practices

DO

Use meaningful variable names
Prefer composition over inheritance
Keep functions small and focused
Use type hints consistently
Use pathlib.Path for file paths
Use logging instead of print

DON'T

Use mutable default arguments: def f(items=[]):
Modify lists while iterating
Use from module import *
Catch bare except:
Use eval() with untrusted input

Quality Tools

# Linting
ruff check .
ruff check --fix .

# Type checking
mypy src/

# Formatting
ruff format .

Advanced Patterns

See references/advanced-patterns.md for:

itertools (chain, islice, groupby, product)
functools (partial, lru_cache, cached_property)
collections (defaultdict, Counter, deque)
Custom context managers
Generator functions
Dataclasses
Enumerations
TypedDict for data contracts

Agent Skills: ABOUTME: Comprehensive skill for idiomatic Python best practices

Install this agent skill to your local

Skill Files