rewrite async and pydantic with fewer examples, more explanation

- async.md: focus on async with as core insight, explain why
- pydantic.md: acknowledge it's a library, explain the core idea
- README: honest about language vs ecosystem, better intro

cut 250 lines of snippet gallery

🤖 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 writing python - the language itself, the ecosystem around it, and patterns that work.
+notes on writing python.
 
-python is easy to start but has depth. these notes focus on modern python (3.10+) with strong typing, async patterns, and the tooling that makes it feel like a proper systems language.
+python is dynamically typed but increasingly written with static type hints. it has first-class async support but doesn't force it on you. it has a global interpreter lock but that matters less than people think for I/O-bound work.
 
-## the language
+these notes focus on modern python (3.10+) - the patterns that emerge when you take typing seriously and use async where it makes sense.
 
-how to write python code:
+## the language
 
-- [typing](./typing.md) - modern type hints, Protocol, generics
-- [async](./async.md) - context managers, ContextVar, patterns
-- [pydantic](./pydantic.md) - models, validation, settings
+- [typing](./typing.md) - type hints, generics, Protocol
+- [async](./async.md) - async with, ContextVar, concurrency
 - [patterns](./patterns.md) - class design, decorators, error handling
 
 ## the ecosystem
 
-tooling and project structure:
-
-- [uv](./uv.md) - cargo for python
+- [uv](./uv.md) - package management that doesn't hurt
 - [project setup](./project-setup.md) - src/ layout, pyproject.toml, justfile
 - [tooling](./tooling.md) - ruff, ty, pre-commit
-- [mcp](./mcp.md) - building MCP servers with fastmcp
+- [pydantic](./pydantic.md) - validation at boundaries
+- [mcp](./mcp.md) - building tools for LLMs
 
 ## sources
 
-patterns derived from building:
-
-| project | what it is |
-|---------|------------|
-| [pdsx](https://github.com/zzstoatzz/pdsx) | ATProto MCP server and CLI |
-| [plyr-python-client](https://github.com/zzstoatzz/plyr-python-client) | uv workspace, multi-package repo |
-| [prefect-mcp-server-demo](https://github.com/zzstoatzz/prefect-mcp-server-demo) | MCP server patterns |
-
-and studying:
-
-| project | what it is |
-|---------|------------|
-| [fastmcp](https://github.com/jlowin/fastmcp) | MCP server framework |
-| [docket](https://github.com/chrisguidry/docket) | distributed task system |
+| project | notes |
+|---------|-------|
+| [pdsx](https://github.com/zzstoatzz/pdsx) | async patterns, MCP, CLI |
+| [plyr-python-client](https://github.com/zzstoatzz/plyr-python-client) | multi-package workspace |
+| [fastmcp](https://github.com/jlowin/fastmcp) | decorator patterns, generics |
+| [docket](https://github.com/chrisguidry/docket) | dependency injection, async lifecycle |

languages/python/async.md

···
 # async
 
-async python patterns - context managers, concurrency, and request-scoped state.
+python's `async`/`await` syntax is straightforward. the interesting part is how you structure code around it.
 
-## async context managers
+## async with
 
-the core pattern for resource lifecycle:
+the core insight from async python codebases: `async with` is how you manage resources. not try/finally, not callbacks - the context manager protocol.
 
-```python
-from contextlib import asynccontextmanager
-from typing import AsyncIterator
+when you open a connection, start a session, or acquire any resource that needs cleanup, you wrap it in an async context manager:
 
+```python
 @asynccontextmanager
-async def get_client(require_auth: bool = False) -> AsyncIterator[Client]:
-    """acquire a client, ensure cleanup."""
+async def get_client() -> AsyncIterator[Client]:
     client = Client()
-
-    if require_auth:
-        await client.login()
-
+    await client.connect()
     try:
         yield client
     finally:
         await client.close()
 ```
 
-usage:
-
-```python
-async with get_client(require_auth=True) as client:
-    await client.do_something()
-# client.close() called automatically
-```
-
-## class-based context managers
-
-when you need state:
-
-```python
-class AsyncClient:
-    async def __aenter__(self) -> "AsyncClient":
-        self._session = await self._create_session()
-        return self
-
-    async def __aexit__(
-        self,
-        exc_type: type[BaseException] | None,
-        exc_val: BaseException | None,
-        exc_tb: TracebackType | None,
-    ) -> None:
-        await self._session.close()
-```
+the caller writes `async with get_client() as c:` and cleanup happens automatically, even if exceptions occur. this pattern appears constantly - database connections, HTTP sessions, file handles, locks.
 
-## AsyncExitStack
+the alternative - manual try/finally blocks scattered through the code, or worse, forgetting cleanup entirely - is why this pattern dominates. you encode the lifecycle once in the context manager, and every use site gets it right by default.
 
-compose multiple context managers:
+## ContextVar
 
-```python
-from contextlib import AsyncExitStack
+python added `contextvars` to solve a specific problem: how do you have request-scoped state in async code without passing it through every function?
 
-async def with_dependencies() -> dict[str, Any]:
-    async with AsyncExitStack() as stack:
-        db = await stack.enter_async_context(get_database())
-        cache = await stack.enter_async_context(get_cache())
-
-        return {"db": db, "cache": cache}
-```
-
-useful when the number of context managers is dynamic.
-
-## ContextVar
-
-request-scoped state without passing through every function:
+in sync code, you might use thread-locals. but async tasks can interleave on the same thread, so thread-locals don't work. `ContextVar` gives each task its own copy:
 
 ```python
 from contextvars import ContextVar
 
-_current_user: ContextVar[User | None] = ContextVar("current_user", default=None)
-
-def get_current_user() -> User:
-    user = _current_user.get()
-    if user is None:
-        raise RuntimeError("no user in context")
-    return user
-
-async def with_user(user: User):
-    token = _current_user.set(user)
-    try:
-        yield
-    finally:
-        _current_user.reset(token)
+_current_request: ContextVar[Request | None] = ContextVar("request", default=None)
 ```
 
-each async task gets its own copy. no global state pollution.
+set it at the start of handling a request, and any code called from that task can access it. this is how frameworks like fastapi and fastmcp pass request context without threading it through every function signature.
 
-## semaphore for concurrency
-
-limit concurrent operations:
+the pattern: set at the boundary (request handler, task entry), read anywhere inside. reset when you're done.
 
-```python
-import asyncio
+## concurrency control
 
-async def batch_process(items: list[str], concurrency: int = 10) -> list[Result]:
-    semaphore = asyncio.Semaphore(concurrency)
+`asyncio.gather()` runs tasks concurrently, but sometimes you need to limit how many run at once - rate limits, connection pools, memory constraints.
 
-    async def process_one(item: str) -> Result:
-        async with semaphore:
-            return await do_work(item)
-
-    return await asyncio.gather(*[process_one(item) for item in items])
-```
-
-## gather with error handling
-
-don't let one failure kill everything:
+`asyncio.Semaphore` is the primitive for this. acquire before work, release after. the `async with` syntax makes it clean:
 
 ```python
-results = await asyncio.gather(
-    *tasks,
-    return_exceptions=True,
-)
+semaphore = asyncio.Semaphore(10)
 
-successes = [r for r in results if not isinstance(r, Exception)]
-failures = [r for r in results if isinstance(r, Exception)]
+async def limited_work(item):
+    async with semaphore:
+        return await do_work(item)
 ```
 
-## shield for critical cleanup
-
-prevent cancellation during important operations:
-
-```python
-async def __aexit__(self, *args) -> None:
-    # don't let cancellation interrupt disconnect
-    await asyncio.shield(self._connection.disconnect())
-```
-
-## streaming responses
-
-async iteration over chunks:
-
-```python
-async with client.stream("GET", url) as response:
-    async for line in response.aiter_lines():
-        if line.startswith("data: "):
-            yield json.loads(line[6:])
-```
-
-## background tasks
-
-fire and forget with cleanup:
-
-```python
-class Worker:
-    async def __aenter__(self) -> "Worker":
-        self._heartbeat_task = asyncio.create_task(
-            self._heartbeat(),
-            name="worker.heartbeat",
-        )
-        return self
-
-    async def __aexit__(self, *args) -> None:
-        self._heartbeat_task.cancel()
-        with suppress(asyncio.CancelledError):
-            await self._heartbeat_task
-```
+at most 10 `do_work` calls run concurrently. the rest wait.
 
 sources:
 - [pdsx/src/pdsx/mcp/client.py](https://github.com/zzstoatzz/pdsx/blob/main/src/pdsx/mcp/client.py)

languages/python/pydantic.md

···
 # pydantic
 
-data validation, serialization, and settings. the foundation for typed python.
-
-## BaseModel basics
-
-```python
-from pydantic import BaseModel, Field, ConfigDict
-
-class Track(BaseModel):
-    model_config = ConfigDict(extra="forbid")  # reject unknown fields
-
-    title: str
-    album: str | None = None
-    tags: list[str] = Field(default_factory=list)
-```
-
-`extra="forbid"` catches typos. if someone passes `titl` instead of `title`, it fails.
-
-## field aliases
-
-when external data uses different names:
-
-```python
-class Track(BaseModel):
-    model_config = ConfigDict(populate_by_name=True)
+pydantic is a library, not the language. but it's become foundational enough that it's worth understanding.
 
-    audio_url: str | None = Field(default=None, alias="r2_url")
-```
+## the core idea
 
-accepts both `audio_url` and `r2_url` as input.
+python's type hints don't do anything at runtime by default. `def foo(x: int)` accepts strings, floats, whatever - the annotation is just documentation.
 
-## validators
-
-transform or check data:
+pydantic makes them real. define a model with type hints, and pydantic validates and coerces data to match:
 
 ```python
-from pydantic import field_validator, model_validator
-from typing import Self
+from pydantic import BaseModel
 
-class Document(BaseModel):
-    text: str
-    tokens: int | None = None
-
-    @field_validator("text", mode="before")
-    @classmethod
-    def strip_whitespace(cls, v: str) -> str:
-        return v.strip()
-
-    @model_validator(mode="after")
-    def compute_tokens(self) -> Self:
-        if self.tokens is None:
-            self.tokens = len(self.text.split())
-        return self
-```
-
-`mode="before"` runs before pydantic's own validation. `mode="after"` runs after the model is constructed.
-
-## discriminated unions
-
-polymorphic types with a type field:
-
-```python
-from typing import Annotated, Literal
-from pydantic import Field
-
-class TrackResult(BaseModel):
-    type: Literal["track"] = "track"
-    title: str
-
-class ArtistResult(BaseModel):
-    type: Literal["artist"] = "artist"
+class User(BaseModel):
     name: str
-
-SearchResult = Annotated[
-    TrackResult | ArtistResult,
-    Field(discriminator="type"),
-]
-
-def parse_results(data: list[dict]) -> list[SearchResult]:
-    from pydantic import TypeAdapter
-    adapter = TypeAdapter(list[SearchResult])
-    return adapter.validate_python(data)
-```
-
-pydantic looks at `type` to decide which model to use.
-
-## TypedDict for loose structures
-
-when you don't need full model machinery:
-
-```python
-from typing import TypedDict
+    age: int
 
-class RecordResponse(TypedDict):
-    uri: str
-    cid: str | None
-    value: dict[str, Any]
+user = User(name="alice", age="25")  # age coerced to int
+user = User(name="alice", age="not a number")  # raises ValidationError
 ```
 
-lighter than BaseModel, still typed.
+this is why pydantic shows up everywhere in python - it bridges the gap between python's dynamic runtime and the desire for validated, typed data.
 
 ## settings from environment
 
-replace `os.getenv()` with validated configuration:
+the most common use: replacing `os.getenv()` calls with validated configuration.
 
 ```python
-from pydantic import Field, SecretStr
-from pydantic_settings import BaseSettings, SettingsConfigDict
+from pydantic_settings import BaseSettings
 
 class Settings(BaseSettings):
-    model_config = SettingsConfigDict(
-        env_prefix="APP_",
-        env_file=".env",
-        extra="ignore",
-    )
-
     database_url: str
-    api_key: SecretStr
     debug: bool = False
 
-settings = Settings()
+settings = Settings()  # reads from environment
 ```
 
-- `env_prefix` means `APP_DATABASE_URL` maps to `database_url`
-- `SecretStr` hides values in logs
-- missing required fields fail at import, not at runtime
-
-## cached singleton
-
-```python
-from functools import lru_cache
+if `DATABASE_URL` isn't set, this fails at import time - not later when you try to connect. that fail-fast behavior catches configuration errors before they become runtime surprises.
 
-@lru_cache
-def get_settings() -> Settings:
-    return Settings()
-```
+## when to use what
 
-one instance, created once, reused everywhere.
-
-## nested settings
-
-for complex configuration:
+pydantic models are heavier than they look - they do a lot of work on instantiation. for internal data you control, python's `dataclasses` are simpler:
 
 ```python
-class DatabaseSettings(BaseSettings):
-    host: str = "localhost"
-    port: int = 5432
+from dataclasses import dataclass
 
-class Settings(BaseSettings):
-    database: DatabaseSettings = Field(default_factory=DatabaseSettings)
-    cache: CacheSettings = Field(default_factory=CacheSettings)
+@dataclass
+class InternalRecord:
+    id: str
+    value: float
 ```
 
-## factory methods
-
-alternative constructors:
-
-```python
-class Config(BaseModel):
-    name: str
-    values: dict[str, Any]
-
-    @classmethod
-    def from_file(cls, path: Path) -> "Config":
-        data = json.loads(path.read_text())
-        return cls.model_validate(data)
-```
-
-## TypeAdapter for non-model validation
-
-validate without a full model:
-
-```python
-from pydantic import TypeAdapter
-
-adapter = TypeAdapter(list[int])
-result = adapter.validate_python(["1", "2", "3"])  # [1, 2, 3]
-```
-
-useful for validating function arguments or API responses.
+no validation, no coercion, just a class with fields. use pydantic at boundaries (API input, config files, external data) where you need validation. use dataclasses for internal data structures.
 
 sources:
-- [pdsx/src/pdsx/_internal/types.py](https://github.com/zzstoatzz/pdsx/blob/main/src/pdsx/_internal/types.py)
-- [plyr-python-client/packages/plyrfm/src/plyrfm/_internal/types.py](https://github.com/zzstoatzz/plyr-python-client)
 - [how to use pydantic-settings](https://blog.zzstoatzz.io/how-to-use-pydantic-settings/)