python

name	python
description	This skill should be used when the user works with Python files (.py), asks about "type hints", "protocols", "dataclasses", "async/await", "decorators", or discusses Pythonic patterns and data modeling. Provides patterns for type safety, error handling, data modeling, and async programming.
user-invocable	false
allowed-tools	Read, Grep, Glob
activation	{"file-patterns":["**/*.py"],"exclude":["venv/**",".venv/**","**/__pycache__/**"]}

Python Patterns

Iron Law

EXPLICIT IS BETTER THAN IMPLICIT [3]

Type-hint every function signature. Name every exception. Use dataclasses over raw dicts. Python's flexibility is a strength only when boundaries are explicit.

When This Skill Activates

Working with Python codebases, designing typed APIs, modeling data with dataclasses or Pydantic, implementing async code, structuring Python packages.

---

Type Safety

Type Hint Everything [4][17][18]

# BAD: def process(data, config): ...
def process(data: list[dict[str, Any]], config: AppConfig) -> ProcessResult: ...

Dropbox's 4M-line mypy migration eliminated entire bug classes [18]. Use from __future__ import annotations for forward references [22].

Protocols for Structural Typing [5][1]

from typing import Protocol

class Repository(Protocol):
    def find_by_id(self, id: str) -> User | None: ...
    def save(self, entity: User) -> User: ...

PEP 544 formalizes duck typing as "static duck typing" — no implements required [5]. Any class with matching methods satisfies the Protocol [1].

Strict Optional Handling [4][23]

PEP 604 X | Y syntax replaces verbose Optional[X] [23]:

def get_name(user: User | None) -> str:
    return "Anonymous" if user is None else user.name

---

Error Handling [2][8][9]

class AppError(Exception): ...

class NotFoundError(AppError):
    def __init__(self, entity: str, id: str) -> None:
        super().__init__(f"{entity} {id} not found")
        self.entity, self.id = entity, id

@contextmanager
def database_transaction(conn: Connection):
    try:
        yield conn; conn.commit()
    except Exception:
        conn.rollback(); raise

Google Style Guide prohibits bare except: — catches SystemExit [8]. Cosmic Python wraps the unit-of-work in a context manager [9].

---

Data Modeling [6][12][14]

# Internal value objects — frozen enforces immutability [6][14]
@dataclass(frozen=True)
class User:
    name: str
    email: str
    created_at: datetime = field(default_factory=lambda: datetime.now(timezone.utc))

# API boundary models — Pydantic validates on instantiation [12]
class CreateUserRequest(BaseModel):
    name: str
    email: EmailStr
    age: int = Field(ge=0, le=150)

PEP 557 gives __init__, __repr__, __eq__ for free [6]. Use @dataclass for domain objects and Pydantic for API models — not interchangeably [9][12].

---

Pythonic Patterns [2][3]

names = [u.name for u in users if u.active]  # comprehension over loop [2]
for i, item in enumerate(items): ...          # enumerate, not range(len) [2]
try:                                          # EAFP over LBYL [3]
    value = mapping[key]
except KeyError:
    value = default

---

Anti-Patterns [2][8][14][4]

Pattern	Violation	Fix
Bare except	except:	except (ValueError, KeyError): [8]
Mutable default	def fn(items=[])	def fn(items: list | None = None) [2]
No type hints	def process(data)	Annotate params + return [4]
Forward ref string	x: "MyClass"	from __future__ import annotations [22]
God class	50-method class	Compose smaller focused classes [9]

---

Extended References

• references/sources.md — Full bibliography (25 sources)
• references/patterns.md — Extended patterns: DI, decorators, fixtures [2][9][10][13]
• references/violations.md — Violation examples with citations
• references/detection.md — Grep patterns for Python issues
• references/async.md — Async patterns: gather, TaskGroup, generators [1][16]

---

Checklist

• All functions annotated (params + return) [4]
• Custom exception types, no bare except: [8]
• Dataclasses or Pydantic for structured data [6][12]
• No mutable default arguments [2]
• Context managers for resource cleanup [10]
• from __future__ import annotations for forward refs [22]
• Protocols over ABC for structural typing [5]
• Tests use pytest fixtures, no repeated setup [13]