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

modern_python_guidance/skills/modern-python-guidance/guides/fastapi/fastapi-typed-state.md

@@ -0,0 +1,76 @@
+---
+id: fastapi-typed-state
+title: Use TypedDict or dataclass for App State
+category: fastapi
+layer: 2
+tags:
+  - fastapi
+  - state
+  - typed
+aliases:
+  - app.state
+  - request.state
+  - typed state
+python: ">=3.9"
+frequency: medium
+---
+
+# Use TypedDict or dataclass for App State
+
+Instead of untyped `app.state.foo` attribute access, use a typed state dict via the lifespan pattern.
+
+## BAD
+
+```python
+from fastapi import FastAPI, Request
+
+app = FastAPI()
+app.state.db_pool = create_pool()
+app.state.cache = create_cache()
+
+@app.get("/")
+async def root(request: Request):
+    pool = request.state.db_pool  # Any — no type checking
+    cache = request.state.cche   # typo silently passes
+```
+
+## GOOD
+
+```python
+from collections.abc import AsyncIterator
+from contextlib import asynccontextmanager
+from dataclasses import dataclass
+
+from fastapi import FastAPI, Request
+
+@dataclass(slots=True)
+class AppState:
+    db_pool: Pool
+    cache: Cache
+
+@asynccontextmanager
+async def lifespan(app: FastAPI) -> AsyncIterator[dict]:
+    pool = await create_pool()
+    cache = await create_cache()
+    yield {"db_pool": pool, "cache": cache}
+    await cache.close()
+    await pool.close()
+
+app = FastAPI(lifespan=lifespan)
+
+@app.get("/")
+async def root(request: Request):
+    pool = request.state.db_pool  # accessible via lifespan state
+```
+
+## Why
+
+- `app.state` is untyped — typos and missing attributes are invisible to type checkers
+- Lifespan state dict makes initialization and cleanup explicit
+- `dataclass` or `TypedDict` documents the expected shape
+- Resource cleanup is guaranteed by the context manager
+
+## References
+
+- [FastAPI Lifespan State](https://fastapi.tiangolo.com/advanced/events/#lifespan-state)
+- [Starlette State](https://www.starlette.io/lifespan/)

modern_python_guidance/skills/modern-python-guidance/guides/httpx/httpx-async-client-reuse.md

@@ -0,0 +1,70 @@
+---
+id: httpx-async-client-reuse
+title: Reuse httpx.AsyncClient Instead of Creating Per-Request
+category: httpx
+layer: 2
+tags:
+  - httpx
+  - async
+  - connection-pooling
+aliases:
+  - httpx
+  - AsyncClient
+  - aiohttp
+  - requests
+python: ">=3.9"
+frequency: high
+---
+
+# Reuse httpx.AsyncClient
+
+Create one `httpx.AsyncClient` and reuse it across requests instead of creating a new client per call.
+
+## BAD
+
+```python
+import httpx
+
+async def fetch_user(user_id: int) -> dict:
+    async with httpx.AsyncClient() as client:
+        resp = await client.get(f"https://api.example.com/users/{user_id}")
+        return resp.json()
+
+async def fetch_many(ids: list[int]) -> list[dict]:
+    return [await fetch_user(i) for i in ids]  # new client per call
+```
+
+## GOOD
+
+```python
+import httpx
+
+async def fetch_many(ids: list[int]) -> list[dict]:
+    async with httpx.AsyncClient(base_url="https://api.example.com") as client:
+        results = []
+        for user_id in ids:
+            resp = await client.get(f"/users/{user_id}")
+            resp.raise_for_status()
+            results.append(resp.json())
+        return results
+```
+
+## Why
+
+- Per-request clients skip connection pooling — each call opens a new TCP+TLS handshake
+- `AsyncClient` maintains a connection pool, reusing connections across requests
+- `httpx` is the modern replacement for `requests` (sync) and `aiohttp` (async)
+- Context manager ensures connections are properly closed
+- `base_url` eliminates URL duplication
+
+## Version Notes
+
+- `httpx` is a third-party package, not stdlib
+- Works on Python 3.9+ with `httpx >= 0.23`
+- Preferred over `requests` for new async code
+- Preferred over `aiohttp` for simpler API and `requests`-like interface
+
+## References
+
+- [httpx Async Client](https://www.python-httpx.org/async/)
+- [httpx Connection Pooling](https://www.python-httpx.org/advanced/clients/)

modern_python_guidance/skills/modern-python-guidance/guides/httpx/httpx-streaming.md

@@ -0,0 +1,66 @@
+---
+id: httpx-streaming
+title: Use httpx Streaming for Large Responses
+category: httpx
+layer: 2
+tags:
+  - httpx
+  - streaming
+  - memory
+aliases:
+  - streaming
+  - stream
+  - large response
+python: ">=3.9"
+frequency: medium
+---
+
+# Use httpx Streaming for Large Responses
+
+Use `client.stream()` instead of `client.get()` for large responses to avoid loading the entire body into memory.
+
+## BAD
+
+```python
+import httpx
+
+async def download_file(url: str, path: str) -> None:
+    async with httpx.AsyncClient() as client:
+        response = await client.get(url)
+        with open(path, "wb") as f:
+            f.write(response.content)  # entire file in memory
+```
+
+## GOOD
+
+```python
+import httpx
+
+async def download_file(url: str, path: str) -> None:
+    async with httpx.AsyncClient() as client:
+        async with client.stream("GET", url) as response:
+            response.raise_for_status()
+            with open(path, "wb") as f:
+                async for chunk in response.aiter_bytes(chunk_size=8192):
+                    f.write(chunk)
+```
+
+## Why
+
+- `response.content` loads the entire response body into memory at once
+- `client.stream()` reads the response incrementally — constant memory usage
+- Essential for large file downloads, SSE streams, and NDJSON feeds
+- `aiter_bytes()`, `aiter_lines()`, `aiter_text()` provide different iteration modes
+
+## Streaming Iteration Methods
+
+| Method | Use case |
+|--------|---------|
+| `aiter_bytes(chunk_size)` | Binary downloads, file writes |
+| `aiter_lines()` | Line-delimited text (NDJSON, logs) |
+| `aiter_text()` | Streamed text with encoding handling |
+| `aiter_raw()` | Raw bytes without decompression |
+
+## References
+
+- [httpx Streaming Responses](https://www.python-httpx.org/async/#streaming-responses)

modern_python_guidance/skills/modern-python-guidance/guides/pydantic/pydantic-v2-config.md

@@ -0,0 +1,73 @@
+---
+id: pydantic-v2-config
+title: Use model_config Instead of class Config
+category: pydantic
+layer: 2
+tags:
+  - pydantic
+  - config
+  - migration
+aliases:
+  - class Config
+  - model_config
+  - ConfigDict
+python: ">=3.9"
+frequency: high
+---
+
+# Use model_config Instead of class Config
+
+Pydantic V2 replaces the inner `class Config` with a module-level `model_config` dict.
+
+## BAD
+
+```python
+from pydantic import BaseModel
+
+class User(BaseModel):
+    name: str
+    email: str
+
+    class Config:
+        str_strip_whitespace = True
+        from_attributes = True
+        json_schema_extra = {"examples": [{"name": "Alice"}]}
+```
+
+## GOOD
+
+```python
+from pydantic import BaseModel, ConfigDict
+
+class User(BaseModel):
+    model_config = ConfigDict(
+        str_strip_whitespace=True,
+        from_attributes=True,
+        json_schema_extra={"examples": [{"name": "Alice"}]},
+    )
+
+    name: str
+    email: str
+```
+
+## Why
+
+- `class Config` is deprecated in Pydantic V2 (removed in V3)
+- `ConfigDict` is typed — IDE autocompletion and type checking work
+- Some V1 config keys were renamed (`orm_mode` → `from_attributes`, `allow_population_by_field_name` → `populate_by_name`)
+- `model_config` is a class variable, not a nested class — simpler inheritance
+
+## Migration Quick Reference
+
+| V1 (class Config) | V2 (ConfigDict) |
+|----|-----|
+| `orm_mode = True` | `from_attributes=True` |
+| `allow_population_by_field_name = True` | `populate_by_name=True` |
+| `anystr_strip_whitespace = True` | `str_strip_whitespace=True` |
+| `validate_assignment = True` | `validate_assignment=True` |
+| `use_enum_values = True` | `use_enum_values=True` |
+
+## References
+
+- [Pydantic V2 Configuration](https://docs.pydantic.dev/latest/concepts/config/)
+- [Pydantic V2 Migration Guide](https://docs.pydantic.dev/latest/migration/)

modern_python_guidance/skills/modern-python-guidance/guides/pydantic/pydantic-v2-model-api.md

@@ -0,0 +1,79 @@
+---
+id: pydantic-v2-model-api
+title: Use Pydantic V2 model_validate Instead of parse_obj
+category: pydantic
+layer: 2
+tags:
+  - pydantic
+  - validation
+  - migration
+aliases:
+  - parse_obj
+  - parse_raw
+  - from_orm
+  - model_validate
+python: ">=3.9"
+frequency: high
+---
+
+# Use Pydantic V2 Model API
+
+Pydantic V2 renamed core model methods. The V1 names are removed.
+
+## BAD
+
+```python
+from pydantic import BaseModel
+
+class User(BaseModel):
+    name: str
+    age: int
+
+# V1 API (removed in V2)
+user = User.parse_obj({"name": "Alice", "age": 30})
+user = User.parse_raw('{"name": "Alice", "age": 30}')
+user = User.from_orm(db_user)
+data = user.dict()
+json_str = user.json()
+schema = User.schema()
+```
+
+## GOOD
+
+```python
+from pydantic import BaseModel
+
+class User(BaseModel):
+    name: str
+    age: int
+
+# V2 API
+user = User.model_validate({"name": "Alice", "age": 30})
+user = User.model_validate_json('{"name": "Alice", "age": 30}')
+data = user.model_dump()
+json_str = user.model_dump_json()
+json_schema = User.model_json_schema()
+```
+
+## Why
+
+- V1 method names are removed in Pydantic V2
+- `model_validate` is ~5-50x faster than V1's `parse_obj` (Rust core)
+- `model_validate_json` parses JSON without intermediate dict
+- Consistent `model_` prefix makes API discoverable
+
+## Migration Quick Reference
+
+| V1 | V2 |
+|----|-----|
+| `parse_obj(data)` | `model_validate(data)` |
+| `parse_raw(json)` | `model_validate_json(json)` |
+| `from_orm(obj)` | `model_validate(obj)` with `from_attributes=True` |
+| `.dict()` | `.model_dump()` |
+| `.json()` | `.model_dump_json()` |
+| `.schema()` | `.model_json_schema()` |
+| `.copy()` | `.model_copy()` |
+
+## References
+
+- [Pydantic V2 Migration Guide](https://docs.pydantic.dev/latest/migration/)

modern_python_guidance/skills/modern-python-guidance/guides/pydantic/pydantic-v2-serialization.md

@@ -0,0 +1,71 @@
+---
+id: pydantic-v2-serialization
+title: Use field_serializer for Custom Serialization
+category: pydantic
+layer: 2
+tags:
+  - pydantic
+  - serialization
+  - migration
+aliases:
+  - field_serializer
+  - model_serializer
+  - json_encoders
+python: ">=3.9"
+frequency: medium
+---
+
+# Use field_serializer for Custom Serialization
+
+Pydantic V2 replaces `json_encoders` in Config with `@field_serializer` and `@model_serializer` decorators.
+
+## BAD
+
+```python
+from datetime import datetime
+from pydantic import BaseModel
+
+class Event(BaseModel):
+    name: str
+    timestamp: datetime
+
+    class Config:
+        json_encoders = {
+            datetime: lambda v: v.isoformat(),
+        }
+```
+
+## GOOD
+
+```python
+from datetime import datetime
+from pydantic import BaseModel, field_serializer
+
+class Event(BaseModel):
+    name: str
+    timestamp: datetime
+
+    @field_serializer("timestamp")
+    @classmethod
+    def serialize_timestamp(cls, v: datetime) -> str:
+        return v.isoformat()
+```
+
+## Why
+
+- `json_encoders` is removed in Pydantic V2
+- `@field_serializer` is explicit about which fields it handles
+- Type-safe — serializer input/output types are checked
+- `@model_serializer` replaces whole-model custom serialization
+- `mode="plain"` or `mode="wrap"` controls whether the default serializer runs first
+
+## Serializer Modes
+
+| Mode | Behavior |
+|------|---------|
+| `mode="plain"` (default) | Replaces the default serializer entirely |
+| `mode="wrap"` | Receives the default serializer as a callable, can modify its output |
+
+## References
+
+- [Pydantic V2 Serialization](https://docs.pydantic.dev/latest/concepts/serialization/)

modern_python_guidance/skills/modern-python-guidance/guides/pydantic/pydantic-v2-validators.md

@@ -0,0 +1,83 @@
+---
+id: pydantic-v2-validators
+title: Use Pydantic V2 field_validator Instead of validator
+category: pydantic
+layer: 2
+tags:
+  - pydantic
+  - validation
+  - migration
+aliases:
+  - validator
+  - field_validator
+  - model_validator
+python: ">=3.9"
+frequency: high
+---
+
+# Use Pydantic V2 Validators
+
+Pydantic V2 replaced `@validator` and `@root_validator` with `@field_validator` and `@model_validator`.
+
+## BAD
+
+```python
+from pydantic import BaseModel, validator, root_validator
+
+class User(BaseModel):
+    name: str
+    email: str
+
+    @validator("name")
+    @classmethod
+    def name_not_empty(cls, v):
+        if not v.strip():
+            raise ValueError("name cannot be empty")
+        return v.strip()
+
+    @root_validator
+    @classmethod
+    def check_consistency(cls, values):
+        return values
+```
+
+## GOOD
+
+```python
+from pydantic import BaseModel, field_validator, model_validator
+
+class User(BaseModel):
+    name: str
+    email: str
+
+    @field_validator("name")
+    @classmethod
+    def name_not_empty(cls, v: str) -> str:
+        if not v.strip():
+            raise ValueError("name cannot be empty")
+        return v.strip()
+
+    @model_validator(mode="after")
+    def check_consistency(self) -> "User":
+        return self
+```
+
+## Why
+
+- `@validator` and `@root_validator` are deprecated in Pydantic V2 (removed in V3)
+- `@field_validator` is explicit about which fields it validates
+- `@model_validator(mode="before"|"after")` replaces `@root_validator(pre=True|False)`
+- `mode="after"` receives the model instance, not a raw dict
+
+## Migration Quick Reference
+
+| V1 | V2 |
+|----|-----|
+| `@validator("field")` | `@field_validator("field")` |
+| `@validator("field", pre=True)` | `@field_validator("field", mode="before")` |
+| `@root_validator` | `@model_validator(mode="after")` |
+| `@root_validator(pre=True)` | `@model_validator(mode="before")` |
+
+## References
+
+- [Pydantic V2 Validators](https://docs.pydantic.dev/latest/concepts/validators/)

modern_python_guidance/skills/modern-python-guidance/guides/stdlib/datetime-utc.md

@@ -0,0 +1,56 @@
+---
+id: datetime-utc
+title: Use datetime.now(UTC) Instead of utcnow()
+category: stdlib
+layer: 1
+tags:
+  - datetime
+  - timezone
+  - utc
+aliases:
+  - utcnow
+  - datetime.utcnow
+  - datetime.utcfromtimestamp
+python: ">=3.11"
+frequency: high
+---
+
+# Use datetime.now(UTC) Instead of utcnow()
+
+`datetime.utcnow()` returns a naive datetime (no timezone info). This is a common source of bugs. Use `datetime.now(UTC)` for timezone-aware UTC datetimes.
+
+## BAD
+
+```python
+from datetime import datetime
+
+now = datetime.utcnow()
+ts = datetime.utcfromtimestamp(1234567890)
+```
+
+## GOOD
+
+```python
+from datetime import UTC, datetime
+
+now = datetime.now(UTC)
+ts = datetime.fromtimestamp(1234567890, tz=UTC)
+```
+
+## Why
+
+- `utcnow()` and `utcfromtimestamp()` are deprecated since Python 3.12
+- Naive datetimes cause subtle bugs in timezone arithmetic
+- `datetime.now(UTC)` returns a proper timezone-aware datetime
+- The `UTC` singleton was added in Python 3.11
+
+## Version Notes
+
+- 3.11+: `datetime.UTC` constant available
+- 3.12+: `utcnow()` and `utcfromtimestamp()` emit `DeprecationWarning`
+- For 3.9-3.10: use `datetime.now(timezone.utc)` instead
+
+## References
+
+- [datetime.UTC docs](https://docs.python.org/3/library/datetime.html#datetime.UTC)
+- [What's New in Python 3.12 — Deprecations](https://docs.python.org/3/whatsnew/3.12.html)

modern_python_guidance/skills/modern-python-guidance/guides/stdlib/pathlib-over-os-path.md

@@ -0,0 +1,68 @@
+---
+id: pathlib-over-os-path
+title: Use pathlib.Path Instead of os.path
+category: stdlib
+layer: 1
+tags:
+  - pathlib
+  - filesystem
+  - os.path
+aliases:
+  - os.path
+  - os.path.join
+  - os.path.exists
+python: ">=3.9"
+frequency: high
+---
+
+# Use pathlib.Path Instead of os.path
+
+Use `pathlib.Path` for filesystem operations instead of string-based `os.path` functions.
+
+## BAD
+
+```python
+import os
+
+config_path = os.path.join(os.path.expanduser("~"), ".config", "app", "config.toml")
+if os.path.exists(config_path):
+    with open(config_path) as f:
+        data = f.read()
+
+parent = os.path.dirname(config_path)
+name = os.path.basename(config_path)
+ext = os.path.splitext(config_path)[1]
+```
+
+## GOOD
+
+```python
+from pathlib import Path
+
+config_path = Path.home() / ".config" / "app" / "config.toml"
+if config_path.exists():
+    data = config_path.read_text()
+
+parent = config_path.parent
+name = config_path.name
+ext = config_path.suffix
+```
+
+## Why
+
+- `/` operator for path joining is more readable than `os.path.join`
+- Methods on Path objects instead of free functions on strings
+- Built-in `read_text()`, `write_text()`, `read_bytes()`, `write_bytes()`
+- Type safety — `Path` vs raw `str` catches path/string confusion
+- `os.path` functions still work with `Path` objects (backwards compatible)
+
+## Version Notes
+
+- 3.4+: `pathlib.Path` available
+- 3.6+: `os` functions accept `Path` objects
+- 3.9+: `Path.with_stem()`, `Path.is_relative_to()`
+- 3.12+: `Path.walk()` replaces `os.walk()`
+
+## References
+
+- [pathlib documentation](https://docs.python.org/3/library/pathlib.html)

modern_python_guidance/skills/modern-python-guidance/guides/stdlib/removeprefix-removesuffix.md

@@ -0,0 +1,64 @@
+---
+id: removeprefix-removesuffix
+title: Use str.removeprefix/removesuffix Instead of Slicing
+category: stdlib
+layer: 1
+tags:
+  - string
+  - stdlib
+aliases:
+  - removeprefix
+  - removesuffix
+  - lstrip
+  - rstrip
+python: ">=3.9"
+frequency: medium
+pep: 616
+---
+
+# Use str.removeprefix/removesuffix
+
+Since Python 3.9, use `str.removeprefix()` and `str.removesuffix()` instead of manual slicing or `lstrip()`/`rstrip()`.
+
+## BAD
+
+```python
+filename = "test_utils.py"
+
+# Manual slicing — must know exact length
+if filename.startswith("test_"):
+    name = filename[5:]  # fragile: magic number 5
+
+# Common mistake: lstrip removes CHARACTERS, not prefix
+name = filename.lstrip("test_")  # removes t, e, s, _, not "test_"
+# "test_utils.py".lstrip("test_") == "utils.py" (lucky)
+# "test_test.py".lstrip("test_") == ".py" (wrong!)
+```
+
+## GOOD
+
+```python
+filename = "test_utils.py"
+
+name = filename.removeprefix("test_")  # "utils.py"
+base = filename.removesuffix(".py")     # "test_utils"
+
+# Safe: returns original string if prefix/suffix not found
+name = "production.py".removeprefix("test_")  # "production.py"
+```
+
+## Why
+
+- No magic numbers or `len()` calculations
+- Semantically clear — removes a specific string, not individual characters
+- Safe — returns the original string unchanged if prefix/suffix not present
+- Avoids the `lstrip`/`rstrip` character-set trap
+
+## Version Notes
+
+- 3.9+: `str.removeprefix()`, `str.removesuffix()`
+- Also available on `bytes` and `bytearray`
+
+## References
+
+- [PEP 616 — String methods to remove prefixes and suffixes](https://peps.python.org/pep-0616/)