add python notes: uv, project setup, pydantic-settings, tooling, mcp

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <[e-mail]>

languages/python/README.md

···
+# python
+
+notes on python patterns - tooling, project structure, and building things.
+
+## topics
+
+- [uv](./uv.md) - cargo for python
+- [project setup](./project-setup.md) - src/ layout, pyproject.toml, justfile
+- [pydantic-settings](./pydantic-settings.md) - centralized typed configuration
+- [tooling](./tooling.md) - ruff, ty, pre-commit
+- [mcp](./mcp.md) - building MCP servers with fastmcp
+
+## sources
+
+patterns derived from building:
+
+| project | what it is |
+|---------|------------|
+| [pdsx](https://github.com/zzstoatzz/pdsx) | ATProto MCP server and CLI |
+| [raggy](https://github.com/zzstoatzz/raggy) | document loaders for LLMs |
+| [prefect-pack](https://github.com/zzstoatzz/prefect-pack) | prefect utilities |
+| [plyr.fm](https://github.com/zzstoatzz/plyr.fm) | music on atproto |
+
+and studying:
+
+| project | what it is |
+|---------|------------|
+| [fastmcp](https://github.com/jlowin/fastmcp) | MCP server framework |
+| [docket](https://github.com/chrisguidry/docket) | distributed task system |

languages/python/mcp.md

···
+# mcp
+
+MCP (Model Context Protocol) lets you build tools that LLMs can use. fastmcp makes this straightforward.
+
+## what MCP is
+
+MCP servers expose:
+- **tools** - functions LLMs can call (actions, side effects)
+- **resources** - read-only data (like GET endpoints)
+- **prompts** - reusable message templates
+
+clients (like Claude) discover and call these over stdio or HTTP.
+
+## basic server
+
+```python
+from fastmcp import FastMCP
+
+mcp = FastMCP("my-server")
+
[e-mail]
+def add(a: int, b: int) -> int:
+    """Add two numbers."""
+    return a + b
+
[e-mail]("config://version")
+def get_version() -> str:
+    return "1.0.0"
+
+if __name__ == "__main__":
+    mcp.run()
+```
+
+fastmcp generates JSON schemas from type hints and docstrings automatically.
+
+## running
+
+```bash
+# stdio (default, for local tools)
+python server.py
+
+# http (for deployment)
+fastmcp run server.py --transport http --port 8000
+```
+
+## tools vs resources
+
+**tools** do things:
+```python
[e-mail]
+async def create_post(text: str) -> dict:
+    """Create a new post."""
+    return await api.create(text)
+```
+
+**resources** read things:
+```python
[e-mail]("posts://{post_id}")
+async def get_post(post_id: str) -> dict:
+    """Get a post by ID."""
+    return await api.get(post_id)
+```
+
+## context
+
+access MCP capabilities within tools:
+
+```python
+from fastmcp import FastMCP, Context
+
+mcp = FastMCP("server")
+
[e-mail]
+async def process(uri: str, ctx: Context) -> str:
+    await ctx.info(f"Processing {uri}...")
+    data = await ctx.read_resource(uri)
+    await ctx.report_progress(50, 100)
+    return data
+```
+
+## middleware
+
+add authentication or other cross-cutting concerns:
+
+```python
+from fastmcp import FastMCP
+from fastmcp.server.middleware import Middleware
+
+class AuthMiddleware(Middleware):
+    async def on_call_tool(self, context, call_next):
+        # extract auth from headers, set context state
+        return await call_next(context)
+
+mcp = FastMCP("server")
+mcp.add_middleware(AuthMiddleware())
+```
+
+## decorator patterns
+
+add parameters dynamically (from pdsx):
+
+```python
+import inspect
+from functools import wraps
+
+def filterable(fn):
+    """Add a _filter parameter for JMESPath filtering."""
+    @wraps(fn)
+    async def wrapper(*args, _filter: str | None = None, **kwargs):
+        result = await fn(*args, **kwargs)
+        if _filter:
+            import jmespath
+            return jmespath.search(_filter, result)
+        return result
+
+    # modify signature to include new param
+    sig = inspect.signature(fn)
+    params = list(sig.parameters.values())
+    params.append(inspect.Parameter(
+        "_filter",
+        inspect.Parameter.KEYWORD_ONLY,
+        default=None,
+        annotation=str | None,
+    ))
+    wrapper.__signature__ = sig.replace(parameters=params)
+    return wrapper
+
[e-mail]
+@filterable
+async def list_records(collection: str) -> list[dict]:
+    ...
+```
+
+## response size protection
+
+LLMs have context limits. protect against flooding:
+
+```python
+MAX_RESPONSE_CHARS = 30000
+
+def truncate_response(records: list) -> list:
+    import json
+    serialized = json.dumps(records)
+    if len(serialized) <= MAX_RESPONSE_CHARS:
+        return records
+    # truncate and add message about using _filter
+    ...
+```
+
+## claude code plugins
+
+structure for Claude Code integration:
+
+```
+.claude-plugin/
+├── plugin.json          # plugin definition
+└── marketplace.json     # marketplace metadata
+
+skills/
+└── domain/
+    └── SKILL.md         # contextual guidance
+```
+
+**plugin.json**:
+```json
+{
+  "name": "myserver",
+  "description": "what it does",
+  "mcpServers": "./.mcp.json"
+}
+```
+
+skills are markdown files loaded as context when relevant to the task.
+
+## entry points
+
+expose both CLI and MCP server:
+
+```toml
+[project.scripts]
+mytool = "mytool.cli:main"
+mytool-mcp = "mytool.mcp:main"
+```
+
+sources:
+- [fastmcp](https://github.com/jlowin/fastmcp)
+- [pdsx](https://github.com/zzstoatzz/pdsx)
+- [gofastmcp.com](https://gofastmcp.com)

languages/python/project-setup.md

···
+# project setup
+
+consistent structure across projects: src/ layout, pyproject.toml as single source of truth, justfile for commands.
+
+## directory structure
+
+```
+myproject/
+├── src/myproject/
+│   ├── __init__.py
+│   ├── cli.py
+│   ├── settings.py
+│   └── _internal/       # private implementation
+├── tests/
+├── pyproject.toml
+├── justfile
+└── .pre-commit-config.yaml
+```
+
+the `src/` layout prevents accidental imports from the working directory. your package is only importable when properly installed.
+
+## pyproject.toml
+
+```toml
+[project]
+name = "myproject"
+description = "what it does"
+readme = "README.md"
+requires-python = ">=3.10"
+dynamic = ["version"]
+dependencies = [
+    "httpx>=0.27",
+    "pydantic>=2.0",
+]
+
+[project.scripts]
+myproject = "myproject.cli:main"
+
+[build-system]
+requires = ["hatchling", "uv-dynamic-versioning"]
+build-backend = "hatchling.build"
+
+[tool.hatch.version]
+source = "uv-dynamic-versioning"
+
+[tool.uv-dynamic-versioning]
+vcs = "git"
+style = "pep440"
+bump = true
+fallback-version = "0.0.0"
+
+[dependency-groups]
+dev = [
+    "pytest>=8.0",
+    "ruff>=0.8",
+    "ty>=0.0.1a6",
+]
+```
+
+key patterns:
+- `dynamic = ["version"]` - version comes from git tags, not manual editing
+- `[dependency-groups]` - dev deps separate from runtime deps
+- `[project.scripts]` - CLI entry points
+
+## versioning from git tags
+
+with `uv-dynamic-versioning`, your version is derived from git:
+
+```bash
+git tag v0.1.0
+git push --tags
+```
+
+no more editing `__version__` or `pyproject.toml` for releases.
+
+## justfile
+
+```makefile
+check-uv:
+    #!/usr/bin/env sh
+    if ! command -v uv >/dev/null 2>&1; then
+        echo "uv is not installed. Install: curl -LsSf https://astral.sh/uv/install.sh | sh"
+        exit 1
+    fi
+
+install: check-uv
+    uv sync
+
+test:
+    uv run pytest tests/ -xvs
+
+lint:
+    uv run ruff format src/ tests/
+    uv run ruff check src/ tests/ --fix
+
+check:
+    uv run ty check
+```
+
+run with `just test`, `just lint`, etc.
+
+## multiple entry points
+
+for projects with both CLI and MCP server:
+
+```toml
+[project.scripts]
+myproject = "myproject.cli:main"
+myproject-mcp = "myproject.mcp:main"
+```
+
+## optional dependencies
+
+for features that not everyone needs:
+
+```toml
+[project.optional-dependencies]
+mcp = ["fastmcp>=2.0"]
+```
+
+install with `uv sync --extra mcp` or `uv add 'myproject[mcp]'`.
+
+sources:
+- [pdsx/pyproject.toml](https://github.com/zzstoatzz/pdsx/blob/main/pyproject.toml)
+- [raggy/pyproject.toml](https://github.com/zzstoatzz/raggy/blob/main/pyproject.toml)

languages/python/pydantic-settings.md

···
+# pydantic-settings
+
+replace scattered `os.getenv()` calls with a typed, validated settings class.
+
+## the problem
+
+```python
+import os
+
+REDIS_HOST = os.getenv("REDIS_HOST")
+REDIS_PORT = os.getenv("REDIS_PORT")
+
+if not REDIS_HOST or not REDIS_PORT:
+    raise ValueError("REDIS_HOST and REDIS_PORT must be set")
+
+# REDIS_PORT is still a string here
+```
+
+issues:
+- validation happens where you use the value, not at startup
+- no type coercion (port is a string)
+- configuration scattered across files
+- easy to forget validation
+
+## the solution
+
+```python
+from pydantic import Field, SecretStr
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+class Settings(BaseSettings):
+    model_config = SettingsConfigDict(
+        env_file=".env",
+        extra="ignore",
+    )
+
+    redis_host: str
+    redis_port: int = Field(ge=0)
+    openai_api_key: SecretStr
+
+settings = Settings()
+```
+
+now:
+- missing `REDIS_HOST` fails immediately at import
+- `redis_port` is coerced to int and validated >= 0
+- `openai_api_key` won't accidentally appear in logs
+- all configuration in one place
+
+## field aliases
+
+when env var names don't match your preferred attribute names:
+
+```python
+class Settings(BaseSettings):
+    current_user: str = Field(alias="USER")
+```
+
+reads from `$USER`, accessed as `settings.current_user`.
+
+## secrets
+
+`SecretStr` prevents accidental exposure:
+
+```python
+class Settings(BaseSettings):
+    api_key: SecretStr
+
+settings = Settings()
+print(settings.api_key)              # SecretStr('**********')
+print(settings.api_key.get_secret_value())  # actual value
+```
+
+## contextual serialization
+
+when you need to unmask secrets for subprocesses:
+
+```python
+from pydantic import Secret, SerializationInfo
+
+def maybe_unmask(v: Secret[str], info: SerializationInfo) -> str | Secret[str]:
+    if info.context and info.context.get("unmask"):
+        return v.get_secret_value()
+    return v
+
+# usage
+settings.model_dump(context={"unmask": True})
+```
+
+## nested settings
+
+for larger projects:
+
+```python
+class DatabaseSettings(BaseSettings):
+    host: str = "localhost"
+    port: int = 5432
+
+class Settings(BaseSettings):
+    database: DatabaseSettings = Field(default_factory=DatabaseSettings)
+```
+
+## why fail-fast matters
+
+with `os.getenv()`, you find out about missing config when the code path executes - maybe in production, at 2am.
+
+with pydantic-settings, invalid configuration fails at startup. deploy fails, not runtime.
+
+sources:
+- [how to use pydantic-settings](https://blog.zzstoatzz.io/how-to-use-pydantic-settings/)

languages/python/tooling.md

···
+# tooling
+
+ruff for linting and formatting. ty for type checking. pre-commit to enforce both.
+
+## ruff
+
+replaces black, isort, flake8, and dozens of plugins. one tool, fast.
+
+```bash
+uv run ruff format src/ tests/   # format
+uv run ruff check src/ tests/    # lint
+uv run ruff check --fix          # lint and auto-fix
+```
+
+### pyproject.toml config
+
+```toml
+[tool.ruff]
+line-length = 88
+
+[tool.ruff.lint]
+fixable = ["ALL"]
+extend-select = [
+    "I",    # isort
+    "B",    # flake8-bugbear
+    "C4",   # flake8-comprehensions
+    "UP",   # pyupgrade
+    "SIM",  # flake8-simplify
+    "RUF",  # ruff-specific
+]
+ignore = [
+    "COM812",   # conflicts with formatter
+]
+
+[tool.ruff.lint.per-file-ignores]
+"__init__.py" = ["F401", "I001"]  # unused imports ok in __init__
+"tests/**/*.py" = ["S101"]        # assert ok in tests
+```
+
+## ty
+
+astral's new type checker. still early but fast and improving.
+
+```bash
+uv run ty check
+```
+
+### pyproject.toml config
+
+```toml
+[tool.ty.src]
+include = ["src", "tests"]
+exclude = ["**/node_modules", "**/__pycache__", ".venv"]
+
+[tool.ty.environment]
+python-version = "3.10"
+
+[tool.ty.rules]
+# start permissive, tighten over time
+unknown-argument = "ignore"
+no-matching-overload = "ignore"
+```
+
+## pre-commit
+
+enforce standards before commits reach the repo.
+
+### .pre-commit-config.yaml
+
+```yaml
+repos:
+  - repo: https://github.com/abravalheri/validate-pyproject
+    rev: v0.24.1
+    hooks:
+      - id: validate-pyproject
+
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.8.0
+    hooks:
+      - id: ruff-check
+        args: [--fix, --exit-non-zero-on-fix]
+      - id: ruff-format
+
+  - repo: local
+    hooks:
+      - id: type-check
+        name: type check
+        entry: uv run ty check
+        language: system
+        types: [python]
+        pass_filenames: false
+
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v5.0.0
+    hooks:
+      - id: no-commit-to-branch
+        args: [--branch, main]
+```
+
+install with:
+
+```bash
+uv run pre-commit install
+```
+
+never use `--no-verify` to skip hooks. fix the issue instead.
+
+## pytest
+
+```toml
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+asyncio_default_fixture_loop_scope = "function"
+testpaths = ["tests"]
+```
+
+`asyncio_mode = "auto"` means async tests just work - no `@pytest.mark.asyncio` needed.
+
+sources:
+- [pdsx/.pre-commit-config.yaml](https://github.com/zzstoatzz/pdsx/blob/main/.pre-commit-config.yaml)
+- [raggy/pyproject.toml](https://github.com/zzstoatzz/raggy/blob/main/pyproject.toml)

languages/python/uv.md

···
+# uv
+
+uv isn't "faster pip." it's cargo for python - a unified toolchain that changes what's practical to do.
+
+## install
+
+```bash
+# macOS/Linux
+curl -LsSf https://astral.sh/uv/install.sh | sh
+
+# Windows
+powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
+```
+
+## the commands you actually use
+
+```bash
+uv sync          # install deps from pyproject.toml
+uv run pytest    # run in project environment
+uv add httpx     # add a dependency
+uvx ruff check   # run a tool without installing it
+```
+
+never use `uv pip`. that's the escape hatch, not the workflow.
+
+## zero-setup environments
+
+run tools without installing anything:
+
+```bash
+uvx flask --help
+uvx ruff check .
+uvx pytest
+```
+
+this creates an ephemeral environment, runs the tool, done. no virtualenv activation, no pip install.
+
+## the repro pattern
+
+testing specific versions without polluting your environment:
+
+```bash
+# test against a specific version
+uv run --with 'pydantic==2.11.4' repro.py
+
+# test a git branch before it's released
+uv run --with pydantic@git+https://github.com/pydantic/pydantic.git@fix-branch repro.py
+
+# combine: released package + unreleased fix
+uv run --with prefect==3.1.3 --with pydantic@git+https://github.com/pydantic/pydantic.git@fix repro.py
+```
+
+for monorepos with subdirectories:
+
+```bash
+uv run --with git+https://github.com/prefecthq/prefect.git@branch#subdirectory=src/integrations/prefect-redis repro.py
+```
+
+## shareable one-liners
+
+no file needed:
+
+```bash
+uv run --with 'httpx==0.27.0' python -c 'import httpx; print(httpx.get("https://httpbin.org/get").json())'
+```
+
+share in github issues, slack, anywhere. anyone with uv can run it.
+
+## stdin execution
+
+pipe code directly:
+
+```bash
+echo 'import sys; print(sys.version)' | uv run -
+pbpaste | uv run --with pandas -
+```
+
+## project workflow
+
+```bash
+uv init myproject        # create new project
+cd myproject
+uv add httpx pydantic    # add deps
+uv sync                  # install everything
+uv run python main.py    # run in environment
+```
+
+`uv sync` reads `pyproject.toml` and `uv.lock`, installs exactly what's specified.
+
+## why this matters
+
+the old way:
+1. install python (which version?)
+2. create virtualenv
+3. activate it (did you remember?)
+4. pip install (hope versions resolve)
+5. run your code
+
+the uv way:
+1. `uv run your_code.py`
+
+uv handles python versions, environments, and dependencies implicitly. you stop thinking about environment management.
+
+sources:
+- [but really, what's so good about uv???](https://blog.zzstoatzz.io/but-really-whats-so-good-about-uv/)
+- [running list of repros via uv](https://blog.zzstoatzz.io/running-list-of-repros-via-uv/)