modern-python-guidance 0.1.0__py3-none-any.whl

modern_python_guidance/skills/modern-python-guidance/SKILL.md

@@ -0,0 +1,104 @@
+---
+name: modern-python-guidance
+description: Version-aware BAD/GOOD pattern guides for modern Python. Use when writing, reviewing, or refactoring Python code to avoid outdated patterns (e.g. typing.List → list, @validator → @field_validator, setup.py → pyproject.toml). Triggers on "Python", "modernize", "upgrade", "deprecated", "pydantic", "fastapi", "httpx", "typing", "dataclass", "asyncio".
+---
+
+# Modern Python Guidance
+
+Version-aware BAD → GOOD pattern guides for modern Python (3.9–3.13+).
+
+When writing or reviewing Python code, consult these guides to ensure modern idioms are used instead of deprecated or outdated patterns. Each guide shows a concrete BAD example, the modern GOOD replacement, and explains why the change matters.
+
+## When to use
+
+- Writing new Python code (use modern patterns from the start)
+- Reviewing Python code (flag outdated patterns)
+- Migrating from Pydantic V1 to V2
+- Upgrading Python version (check which new features are available)
+- Replacing legacy tooling (setup.py, flake8, pip)
+
+## Guide inventory (30 guides)
+
+### Layer 1 — Standard Library & Language Features
+
+| Category | Guide | Python | What it replaces |
+|----------|-------|--------|-----------------|
+| typing | `use-builtin-generics` | >=3.9 | `typing.List` → `list` |
+| typing | `union-syntax` | >=3.10 | `Optional[X]` → `X \| None` |
+| typing | `type-parameter-syntax` | >=3.12 | `TypeVar("T")` → `[T]` |
+| typing | `override-decorator` | >=3.12 | manual override → `@override` |
+| typing | `typeis-vs-typeguard` | >=3.13 | `TypeGuard` → `TypeIs` |
+| typing | `paramspec-decorators` | >=3.10 | untyped decorators → `ParamSpec` |
+| async | `taskgroup-over-gather` | >=3.11 | `gather()` → `TaskGroup` |
+| async | `exception-groups` | >=3.11 | multi-error handling → `except*` |
+| async | `async-timeout-context` | >=3.11 | `wait_for()` → `asyncio.timeout` |
+| stdlib | `datetime-utc` | >=3.11 | `utcnow()` → `now(UTC)` |
+| stdlib | `pathlib-over-os-path` | >=3.9 | `os.path` → `pathlib.Path` |
+| stdlib | `tomllib-builtin` | >=3.11 | `toml` package → `tomllib` |
+| stdlib | `removeprefix-removesuffix` | >=3.9 | `lstrip()`/slicing → `removeprefix()` |
+| data-structures | `dict-merge-operator` | >=3.9 | `{**d1, **d2}` → `d1 \| d2` |
+| data-structures | `match-case-patterns` | >=3.10 | nested if/isinstance → `match`/`case` |
+| data-structures | `dataclass-modern` | >=3.10 | basic dataclass → `slots=True, kw_only=True` |
+
+### Layer 2 — Popular Frameworks
+
+| Category | Guide | What it replaces |
+|----------|-------|-----------------|
+| pydantic | `pydantic-v2-model-api` | `parse_obj()` → `model_validate()` |
+| pydantic | `pydantic-v2-validators` | `@validator` → `@field_validator` |
+| pydantic | `pydantic-v2-config` | `class Config` → `model_config = ConfigDict(...)` |
+| pydantic | `pydantic-v2-serialization` | `json_encoders` → `@field_serializer` |
+| fastapi | `fastapi-lifespan` | `@on_event` → lifespan context manager |
+| fastapi | `fastapi-annotated-depends` | `Depends()` default → `Annotated[T, Depends()]` |
+| fastapi | `fastapi-typed-state` | untyped `app.state` → typed state via lifespan |
+| httpx | `httpx-async-client-reuse` | per-request client → shared `AsyncClient` |
+| httpx | `httpx-streaming` | `response.content` → `client.stream()` |
+
+### Layer 3 — Toolchain & Security
+
+| Category | Guide | What it replaces |
+|----------|-------|-----------------|
+| toolchain | `pyproject-toml-over-setup` | `setup.py` → `pyproject.toml` |
+| toolchain | `uv-over-pip` | `pip` → `uv` |
+| toolchain | `ruff-over-flake8` | flake8+isort+black → `ruff` |
+| toolchain | `no-pickle` | `pickle.load()` → safe alternatives |
+| toolchain | `safe-subprocess` | `shell=True` → list arguments |
+
+## How to look up a guide
+
+Each guide is a markdown file in `guides/<category>/<id>.md` with YAML frontmatter containing:
+- `id`: unique identifier
+- `python`: minimum Python version (e.g. `">=3.11"`)
+- `frequency`: how often LLMs generate the outdated pattern (`high`/`medium`/`low`)
+- `layer`: 1 (stdlib), 2 (frameworks), 3 (toolchain)
+
+### Reading a guide directly
+
+Open `guides/<category>/<guide-id>.md` for the full BAD/GOOD comparison.
+
+### Using the CLI
+
+```bash
+# Search by keyword
+mpg search "typing list"
+
+# Retrieve full guide content
+mpg retrieve use-builtin-generics
+
+# List all guides for a Python version
+mpg list --python-version 3.11
+
+# Detect project Python version
+mpg detect-version
+```
+
+## Integration pattern for agents
+
+When generating Python code:
+
+1. Check if the target Python version is known (from `pyproject.toml`, `.python-version`, or context)
+2. For each pattern you're about to write, check if a guide exists for a modern replacement
+3. Use the GOOD pattern instead of the BAD pattern
+4. If the target Python version is too old for the modern pattern, use the older pattern and note it
+
+Example: if writing `from typing import List` for a Python 3.9+ project, use `list` instead (see `use-builtin-generics`).

modern_python_guidance/skills/modern-python-guidance/guides/async/async-timeout-context.md

@@ -0,0 +1,65 @@
+---
+id: async-timeout-context
+title: Use asyncio.timeout Instead of wait_for
+category: async
+layer: 1
+tags:
+  - asyncio
+  - timeout
+aliases:
+  - asyncio.wait_for
+  - asyncio.timeout
+python: ">=3.11"
+frequency: medium
+---
+
+# Use asyncio.timeout Instead of wait_for
+
+Since Python 3.11, use the `asyncio.timeout` context manager instead of `asyncio.wait_for`. It provides structured cancellation and works with any block of async code.
+
+## BAD
+
+```python
+import asyncio
+
+async def fetch_data():
+    try:
+        result = await asyncio.wait_for(slow_operation(), timeout=5.0)
+    except asyncio.TimeoutError:
+        result = default_value
+
+    # wait_for only wraps a single awaitable
+    # Cannot timeout multiple operations together
+```
+
+## GOOD
+
+```python
+import asyncio
+
+async def fetch_data():
+    try:
+        async with asyncio.timeout(5.0):
+            data = await slow_operation()
+            parsed = await parse(data)
+            # Both operations share the 5s budget
+    except TimeoutError:
+        return default_value
+```
+
+## Why
+
+- Context manager scopes timeout to an entire block, not just one awaitable
+- Multiple operations share the same deadline
+- Raises `TimeoutError` (3.12+) or `asyncio.TimeoutError` (3.11) — catch `TimeoutError` to cover both
+- `asyncio.timeout(None)` disables timeout (useful for conditional timeouts)
+
+## Version Notes
+
+- 3.11+: `asyncio.timeout(delay)` and `asyncio.timeout_at(when)`
+- 3.12+: `asyncio.timeout` raises `TimeoutError` (not `asyncio.TimeoutError`)
+- Pre-3.11: Use `async-timeout` package
+
+## References
+
+- [asyncio.timeout documentation](https://docs.python.org/3/library/asyncio-task.html#asyncio.timeout)

modern_python_guidance/skills/modern-python-guidance/guides/async/exception-groups.md

@@ -0,0 +1,70 @@
+---
+id: exception-groups
+title: Use except* for Exception Groups
+category: async
+layer: 1
+tags:
+  - asyncio
+  - exceptions
+  - error-handling
+aliases:
+  - ExceptionGroup
+  - except*
+  - BaseExceptionGroup
+python: ">=3.11"
+frequency: medium
+pep: 654
+---
+
+# Use except* for Exception Groups
+
+Since Python 3.11, use `except*` to handle multiple concurrent exceptions from `TaskGroup` and other async contexts.
+
+## BAD
+
+```python
+import asyncio
+
+async def main():
+    try:
+        async with asyncio.TaskGroup() as tg:
+            tg.create_task(fetch_users())
+            tg.create_task(fetch_orders())
+    except Exception as e:
+        # Only sees the ExceptionGroup wrapper, not individual errors
+        print(f"Something failed: {e}")
+```
+
+## GOOD
+
+```python
+import asyncio
+
+async def main():
+    try:
+        async with asyncio.TaskGroup() as tg:
+            tg.create_task(fetch_users())
+            tg.create_task(fetch_orders())
+    except* ValueError as eg:
+        for e in eg.exceptions:
+            print(f"Validation error: {e}")
+    except* ConnectionError as eg:
+        for e in eg.exceptions:
+            print(f"Connection failed: {e}")
+```
+
+## Why
+
+- `TaskGroup` raises `ExceptionGroup` when multiple tasks fail simultaneously
+- `except*` matches and extracts specific exception types from the group
+- Multiple `except*` clauses can each handle different types from the same group
+- Traditional `except` sees only the `ExceptionGroup` wrapper
+
+## Version Notes
+
+- 3.11+: `except*`, `ExceptionGroup`, `BaseExceptionGroup`
+- Pre-3.11: Use `exceptiongroup` backport package
+
+## References
+
+- [PEP 654 — Exception Groups and except*](https://peps.python.org/pep-0654/)

modern_python_guidance/skills/modern-python-guidance/guides/async/taskgroup-over-gather.md

@@ -0,0 +1,63 @@
+---
+id: taskgroup-over-gather
+title: Use asyncio.TaskGroup Instead of asyncio.gather
+category: async
+layer: 1
+tags:
+  - asyncio
+  - concurrency
+  - taskgroup
+aliases:
+  - asyncio.gather
+  - gather
+python: ">=3.11"
+frequency: high
+---
+
+# Use asyncio.TaskGroup Instead of asyncio.gather
+
+`asyncio.TaskGroup` provides structured concurrency with proper error handling. `asyncio.gather` silently drops errors from other tasks when one fails.
+
+## BAD
+
+```python
+import asyncio
+
+async def main():
+    results = await asyncio.gather(
+        fetch_users(),
+        fetch_orders(),
+        fetch_products(),
+    )
+```
+
+## GOOD
+
+```python
+import asyncio
+
+async def main():
+    async with asyncio.TaskGroup() as tg:
+        users_task = tg.create_task(fetch_users())
+        orders_task = tg.create_task(fetch_orders())
+        products_task = tg.create_task(fetch_products())
+
+    results = (users_task.result(), orders_task.result(), products_task.result())
+```
+
+## Why
+
+- `gather` with `return_exceptions=False` cancels remaining tasks on first error but may swallow secondary exceptions
+- `TaskGroup` raises `ExceptionGroup` containing all failures
+- Structured concurrency: all tasks are guaranteed to finish before the block exits
+- Clearer intent — each task is named and individually accessible
+
+## Version Notes
+
+- 3.11+: `asyncio.TaskGroup` added
+- For 3.10 and below, consider `anyio.create_task_group()` as a backport
+
+## References
+
+- [PEP 654 — Exception Groups](https://peps.python.org/pep-0654/)
+- [asyncio.TaskGroup docs](https://docs.python.org/3/library/asyncio-task.html#asyncio.TaskGroup)

modern_python_guidance/skills/modern-python-guidance/guides/data-structures/dataclass-modern.md

@@ -0,0 +1,73 @@
+---
+id: dataclass-modern
+title: Use Modern Dataclass Features (slots, kw_only)
+category: data-structures
+layer: 1
+tags:
+  - dataclass
+  - slots
+  - kw_only
+aliases:
+  - dataclass
+  - dataclasses
+python: ">=3.10"
+frequency: medium
+---
+
+# Use Modern Dataclass Features
+
+Since Python 3.10, dataclasses support `slots=True` and `kw_only=True` for better performance and safer APIs.
+
+## BAD
+
+```python
+from dataclasses import dataclass
+
+@dataclass
+class Point:
+    x: float
+    y: float
+    z: float = 0.0
+
+# No slots: allows typos on attributes
+p = Point(1.0, 2.0)
+p.w = 3.0  # silently creates new attribute (typo for 'z')
+
+# Positional args: easy to mix up x and y
+p = Point(2.0, 1.0)  # is this (x=2, y=1) or (x=1, y=2)?
+```
+
+## GOOD
+
+```python
+from dataclasses import dataclass
+
+@dataclass(slots=True, kw_only=True)
+class Point:
+    x: float
+    y: float
+    z: float = 0.0
+
+p = Point(x=1.0, y=2.0)
+p.w = 3.0  # AttributeError: 'Point' has no attribute 'w'
+
+# kw_only forces explicit names — no positional confusion
+p = Point(x=2.0, y=1.0)  # intent is clear
+```
+
+## Why
+
+- `slots=True`: 20-35% less memory, faster attribute access, prevents typo attributes
+- `kw_only=True`: forces named arguments, eliminates positional ordering bugs
+- `frozen=True` + `slots=True`: fast immutable value objects
+- Combine for production data classes: `@dataclass(slots=True, frozen=True, kw_only=True)`
+
+## Version Notes
+
+- 3.10+: `slots=True`, `kw_only=True`
+- 3.10+: Per-field `kw_only` via `field(kw_only=True)`
+- 3.7-3.9: Basic `@dataclass` without slots/kw_only
+
+## References
+
+- [dataclasses documentation](https://docs.python.org/3/library/dataclasses.html)

modern_python_guidance/skills/modern-python-guidance/guides/data-structures/dict-merge-operator.md

@@ -0,0 +1,63 @@
+---
+id: dict-merge-operator
+title: Use | Operator for Dict Merging
+category: data-structures
+layer: 1
+tags:
+  - dict
+  - merge
+  - operator
+aliases:
+  - dict merge
+  - dict update
+  - "**kwargs"
+python: ">=3.9"
+frequency: medium
+pep: 584
+---
+
+# Use | Operator for Dict Merging
+
+Since Python 3.9, use the `|` operator to merge dictionaries instead of `{**d1, **d2}` or `dict.update()`.
+
+## BAD
+
+```python
+defaults = {"timeout": 30, "retries": 3}
+overrides = {"timeout": 60, "verbose": True}
+
+# Unpacking merge — unclear precedence
+config = {**defaults, **overrides}
+
+# Mutates defaults
+defaults.update(overrides)
+```
+
+## GOOD
+
+```python
+defaults = {"timeout": 30, "retries": 3}
+overrides = {"timeout": 60, "verbose": True}
+
+# Merge (right side wins on conflicts)
+config = defaults | overrides
+
+# In-place merge
+defaults |= overrides
+```
+
+## Why
+
+- Cleaner syntax: `d1 | d2` is immediately obvious
+- Non-mutating by default (like set `|`)
+- `|=` for in-place update (like `+=`)
+- Works with dict subclasses (unlike `{**d1, **d2}`)
+
+## Version Notes
+
+- 3.9+: `dict.__or__` and `dict.__ior__`
+- Pre-3.9: `{**d1, **d2}` or `d1.update(d2)` (mutating)
+
+## References
+
+- [PEP 584 — Add Union Operators To dict](https://peps.python.org/pep-0584/)

modern_python_guidance/skills/modern-python-guidance/guides/data-structures/match-case-patterns.md

@@ -0,0 +1,70 @@
+---
+id: match-case-patterns
+title: Use Structural Pattern Matching
+category: data-structures
+layer: 1
+tags:
+  - match
+  - pattern-matching
+  - control-flow
+aliases:
+  - match case
+  - switch case
+  - pattern matching
+python: ">=3.10"
+frequency: medium
+pep: 634
+---
+
+# Use Structural Pattern Matching
+
+Since Python 3.10, use `match`/`case` for complex conditional logic involving structure, type, and value checks.
+
+## BAD
+
+```python
+def handle_command(command):
+    if isinstance(command, dict):
+        if "action" in command and command["action"] == "move":
+            x = command.get("x", 0)
+            y = command.get("y", 0)
+            return move(x, y)
+        elif "action" in command and command["action"] == "resize":
+            return resize(command.get("width"), command.get("height"))
+    elif isinstance(command, list) and len(command) == 2:
+        return move(*command)
+    raise ValueError(f"Unknown command: {command}")
+```
+
+## GOOD
+
+```python
+def handle_command(command):
+    match command:
+        case {"action": "move", "x": x, "y": y}:
+            return move(x, y)
+        case {"action": "resize", "width": w, "height": h}:
+            return resize(w, h)
+        case [x, y]:
+            return move(x, y)
+        case _:
+            raise ValueError(f"Unknown command: {command}")
+```
+
+## Why
+
+- Destructures and binds in one step
+- Handles dicts, sequences, classes, and literals uniformly
+- Guard clauses with `case ... if condition:`
+- `_` wildcard is explicit "match anything"
+- More readable than nested `if/isinstance/in` chains
+
+## Version Notes
+
+- 3.10+: `match`/`case` statements
+- Not a switch statement — it's structural pattern matching with binding
+
+## References
+
+- [PEP 634 — Structural Pattern Matching: Specification](https://peps.python.org/pep-0634/)
+- [PEP 636 — Structural Pattern Matching: Tutorial](https://peps.python.org/pep-0636/)

modern_python_guidance/skills/modern-python-guidance/guides/fastapi/fastapi-annotated-depends.md

@@ -0,0 +1,80 @@
+---
+id: fastapi-annotated-depends
+title: Use Annotated for Dependency Injection
+category: fastapi
+layer: 2
+tags:
+  - fastapi
+  - dependency-injection
+  - annotated
+aliases:
+  - Depends
+  - Annotated
+  - dependency injection
+python: ">=3.9"
+frequency: high
+---
+
+# Use Annotated for Dependency Injection
+
+Since FastAPI 0.95.0, use `Annotated[T, Depends(...)]` instead of bare `Depends()` as default values.
+
+## BAD
+
+```python
+from fastapi import Depends, FastAPI
+
+app = FastAPI()
+
+async def get_db():
+    db = SessionLocal()
+    try:
+        yield db
+    finally:
+        db.close()
+
+@app.get("/users")
+async def list_users(db: Session = Depends(get_db)):
+    return db.query(User).all()
+```
+
+## GOOD
+
+```python
+from typing import Annotated
+
+from fastapi import Depends, FastAPI
+
+app = FastAPI()
+
+async def get_db():
+    db = SessionLocal()
+    try:
+        yield db
+    finally:
+        db.close()
+
+DbDep = Annotated[Session, Depends(get_db)]
+
+@app.get("/users")
+async def list_users(db: DbDep):
+    return db.query(User).all()
+```
+
+## Why
+
+- `Annotated` keeps the type and the dependency together — reusable as a type alias
+- Default values with `Depends()` don't work well with non-FastAPI callers (e.g., tests)
+- `Annotated` is the standard Python way to attach metadata to types (PEP 593)
+- Multiple dependencies can be composed into a single type alias
+
+## Version Notes
+
+- `Annotated` available from `typing` since 3.9
+- FastAPI `Annotated` support since 0.95.0 (2023-04)
+- Also works for `Query`, `Path`, `Body`, `Header`, `Cookie`, `Form`, `File`
+
+## References
+
+- [FastAPI Dependencies with Annotated](https://fastapi.tiangolo.com/tutorial/dependencies/)
+- [PEP 593 — Flexible function and variable annotations](https://peps.python.org/pep-0593/)

modern_python_guidance/skills/modern-python-guidance/guides/fastapi/fastapi-lifespan.md

@@ -0,0 +1,77 @@
+---
+id: fastapi-lifespan
+title: Use Lifespan Context Manager Instead of on_event
+category: fastapi
+layer: 2
+tags:
+  - fastapi
+  - lifespan
+  - startup
+  - shutdown
+aliases:
+  - on_event
+  - startup
+  - shutdown
+python: ">=3.9"
+frequency: high
+---
+
+# Use Lifespan Context Manager
+
+FastAPI's `@app.on_event("startup")` and `@app.on_event("shutdown")` decorators are deprecated. Use the lifespan context manager instead.
+
+## BAD
+
+```python
+from fastapi import FastAPI
+
+app = FastAPI()
+db_pool = None
+
+@app.on_event("startup")
+async def startup():
+    global db_pool
+    db_pool = await create_pool()
+
+@app.on_event("shutdown")
+async def shutdown():
+    await db_pool.close()
+```
+
+## GOOD
+
+```python
+from collections.abc import AsyncIterator
+from contextlib import asynccontextmanager
+
+from fastapi import FastAPI
+
+@asynccontextmanager
+async def lifespan(app: FastAPI) -> AsyncIterator[dict]:
+    pool = await create_pool()
+    yield {"db_pool": pool}
+    await pool.close()
+
+app = FastAPI(lifespan=lifespan)
+
+@app.get("/")
+async def root(request: Request):
+    pool = request.state.db_pool
+```
+
+## Why
+
+- `on_event` is deprecated since FastAPI 0.93.0 (2023-02)
+- Lifespan provides typed state access via `request.state`
+- Resource cleanup is guaranteed by the context manager protocol
+- Easier to test — lifespan is a plain async function
+
+## Version Notes
+
+- Works on Python 3.9+ with FastAPI >= 0.93.0
+- `AsyncIterator` moved from `typing` to `collections.abc` in 3.9
+
+## References
+
+- [FastAPI Lifespan Events](https://fastapi.tiangolo.com/advanced/events/)
+- [Starlette Lifespan](https://www.starlette.io/lifespan/)