reorganize python notes, audit examples against real code

- restructure into language/ and ecosystem/ subdirectories
- trim README commentary
- verify all code examples against pdsx, fastmcp, docket
- add source links to examples

🤖 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.
+assumes 3.12+.
 
-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.
+## language
 
-these notes assume python 3.12 or later. 3.12 introduced native generic syntax and the `type` statement - the typing story finally feels complete.
-
-## the language
-
-- [typing](./typing.md) - type hints, generics, Protocol
-- [async](./async.md) - async with, ContextVar, concurrency
-- [patterns](./patterns.md) - class design, decorators, error handling
+- [typing](./language/typing.md)
+- [async](./language/async.md)
+- [patterns](./language/patterns.md)
 
-## the ecosystem
+## ecosystem
 
-- [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
-- [pydantic](./pydantic.md) - validation at boundaries
-- [mcp](./mcp.md) - building tools for LLMs
+- [uv](./ecosystem/uv.md)
+- [project setup](./ecosystem/project-setup.md)
+- [tooling](./ecosystem/tooling.md)
+- [pydantic](./ecosystem/pydantic.md)
+- [mcp](./ecosystem/mcp.md)
 
 ## sources
 

languages/python/async.md

···
-# async
-
-python's `async`/`await` syntax is straightforward. the interesting part is how you structure code around it.
-
-## async with
-
-the core insight from async python codebases: `async with` is how you manage resources. not try/finally, not callbacks - the context manager protocol.
-
-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() -> AsyncIterator[Client]:
-    client = Client()
-    await client.connect()
-    try:
-        yield client
-    finally:
-        await client.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.
-
-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.
-
-## ContextVar
-
-python added `contextvars` to solve a specific problem: how do you have request-scoped state in async code without passing it 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_request: ContextVar[Request | None] = ContextVar("request", default=None)
-```
-
-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.
-
-the pattern: set at the boundary (request handler, task entry), read anywhere inside. reset when you're done.
-
-## concurrency control
-
-`asyncio.gather()` runs tasks concurrently, but sometimes you need to limit how many run at once - rate limits, connection pools, memory constraints.
-
-`asyncio.Semaphore` is the primitive for this. acquire before work, release after. the `async with` syntax makes it clean:
-
-```python
-semaphore = asyncio.Semaphore(10)
-
-async def limited_work(item):
-    async with semaphore:
-        return await do_work(item)
-```
-
-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)
-- [docket/src/docket/worker.py](https://github.com/chrisguidry/docket/blob/main/src/docket/worker.py)

languages/python/ecosystem/pydantic.md

···
+# pydantic
+
+pydantic is a library, not the language. but it's become foundational enough that it's worth understanding.
+
+## the core idea
+
+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.
+
+pydantic makes them real. define a model with type hints, and pydantic validates and coerces data to match:
+
+```python
+from pydantic import BaseModel
+
+class User(BaseModel):
+    name: str
+    age: int
+
+user = User(name="alice", age="25")  # age coerced to int
+user = User(name="alice", age="not a number")  # raises ValidationError
+```
+
+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
+
+the most common use: replacing `os.getenv()` calls with validated configuration.
+
+```python
+from pydantic import Field
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+class Settings(BaseSettings):
+    """settings for atproto cli."""
+
+    model_config = SettingsConfigDict(
+        env_file=str(Path.cwd() / ".env"),
+        env_file_encoding="utf-8",
+        extra="ignore",
+        case_sensitive=False,
+    )
+
+    atproto_pds_url: str = Field(
+        default="https://bsky.social",
+        description="PDS URL",
+    )
+    atproto_handle: str = Field(default="", description="Your atproto handle")
+    atproto_password: str = Field(default="", description="Your atproto app password")
+
+settings = Settings()
+```
+
+`model_config` controls where settings come from (environment, .env files) and how to handle unknowns. required fields without defaults fail at import time - not later when you try to use them.
+
+from [pdsx/_internal/config.py](https://github.com/zzstoatzz/pdsx/blob/main/src/pdsx/_internal/config.py)
+
+## when to use what
+
+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
+from dataclasses import dataclass
+
+@dataclass
+class BatchResult:
+    """result of a batch operation."""
+    successful: list[str]
+    failed: list[tuple[str, Exception]]
+
+    @property
+    def total(self) -> int:
+        return len(self.successful) + len(self.failed)
+```
+
+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.
+
+from [pdsx/_internal/batch.py](https://github.com/zzstoatzz/pdsx/blob/main/src/pdsx/_internal/batch.py)
+
+sources:
+- [how to use pydantic-settings](https://blog.zzstoatzz.io/how-to-use-pydantic-settings/)

languages/python/language/async.md

···
+# async
+
+python's `async`/`await` syntax is straightforward. the interesting part is how you structure code around it.
+
+## async with
+
+the core insight from async python codebases: `async with` is how you manage resources. not try/finally, not callbacks - the context manager protocol.
+
+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_atproto_client(
+    require_auth: bool = False,
+    operation: str = "this operation",
+    target_repo: str | None = None,
+) -> AsyncIterator[AsyncClient]:
+    """get an atproto client using credentials from context or environment."""
+    client = AsyncClient(pds_url)
+    if require_auth and handle and password:
+        await client.login(handle, password)
+    try:
+        yield client
+    finally:
+        pass  # AsyncClient doesn't need explicit cleanup
+```
+
+the caller writes `async with get_atproto_client() as client:` and cleanup happens automatically. this pattern appears constantly - database connections, HTTP sessions, file handles, locks.
+
+from [pdsx/mcp/client.py](https://github.com/zzstoatzz/pdsx/blob/main/src/pdsx/mcp/client.py)
+
+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.
+
+## ContextVar
+
+python added `contextvars` to solve a specific problem: how do you have request-scoped state in async code without passing it 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_docket: ContextVar[Docket | None] = ContextVar("docket", default=None)
+_current_worker: ContextVar[Worker | None] = ContextVar("worker", default=None)
+_current_server: ContextVar[weakref.ref[FastMCP] | None] = ContextVar("server", default=None)
+```
+
+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.
+
+the pattern: set at the boundary (request handler, task entry), read anywhere inside. reset when you're done.
+
+from [fastmcp/server/dependencies.py](https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/server/dependencies.py)
+
+## concurrency control
+
+`asyncio.gather()` runs tasks concurrently, but sometimes you need to limit how many run at once - rate limits, connection pools, memory constraints.
+
+`asyncio.Semaphore` is the primitive for this. acquire before work, release after. the `async with` syntax makes it clean:
+
+```python
+semaphore = asyncio.Semaphore(concurrency)
+
+async def delete_one(uri: str) -> None:
+    """delete a single record with concurrency control."""
+    async with semaphore:
+        try:
+            await delete_record(client, uri)
+            successful.append(uri)
+        except Exception as e:
+            failed.append((uri, e))
+            if fail_fast:
+                raise
+
+await asyncio.gather(*[delete_one(uri) for uri in uris])
+```
+
+at most `concurrency` delete operations run at once. the rest wait.
+
+from [pdsx/_internal/batch.py](https://github.com/zzstoatzz/pdsx/blob/main/src/pdsx/_internal/batch.py)

languages/python/language/typing.md

···
+# typing
+
+notes on type hints as actually used in projects like pdsx and fastmcp.
+
+## unions
+
+use `|` for unions, not `Optional`:
+
+```python
+RecordValue = str | int | float | bool | None | dict[str, Any] | list[Any]
+```
+
+from [pdsx/_internal/types.py](https://github.com/zzstoatzz/pdsx/blob/main/src/pdsx/_internal/types.py)
+
+## TypedDict
+
+for structured dictionaries where you know the shape:
+
+```python
+from typing import TypedDict
+
+class RecordResponse(TypedDict):
+    """a record returned from list or get operations."""
+    uri: str
+    cid: str | None
+    value: dict
+
+class CredentialsContext(TypedDict):
+    """credentials extracted from context or headers."""
+    handle: str | None
+    password: str | None
+    pds_url: str | None
+    repo: str | None
+```
+
+better than `dict[str, Any]` because the structure is documented and checked.
+
+from [pdsx/mcp/_types.py](https://github.com/zzstoatzz/pdsx/blob/main/src/pdsx/mcp/_types.py)
+
+## Annotated
+
+attach metadata to types. useful for documentation and schema generation:
+
+```python
+from typing import Annotated
+from pydantic import Field
+
+FilterParam = Annotated[
+    str | None,
+    Field(
+        description=(
+            "jmespath expression to filter/project the result. "
+            "examples: '[*].{uri: uri, text: value.text}' (select fields), "
+            "'[?value.text != null]' (filter items), "
+            "'[*].uri' (extract values)"
+        ),
+    ),
+]
+```
+
+the metadata travels with the type. MCP tools use this for parameter descriptions.
+
+from [pdsx/mcp/filterable.py](https://github.com/zzstoatzz/pdsx/blob/main/src/pdsx/mcp/filterable.py)
+
+## Protocol
+
+define what methods something needs, not what class it is:
+
+```python
+from typing import Protocol
+
+class ContextSamplingFallbackProtocol(Protocol):
+    async def __call__(
+        self,
+        messages: str | list[str | SamplingMessage],
+        system_prompt: str | None = None,
+        temperature: float | None = None,
+        max_tokens: int | None = None,
+    ) -> ContentBlock: ...
+```
+
+any callable matching this signature satisfies the protocol. no inheritance required.
+
+from [fastmcp/utilities/types.py](https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/utilities/types.py)
+
+## generics
+
+TypeVar for generic functions and classes:
+
+```python
+from typing import ParamSpec, TypeVar
+
+P = ParamSpec("P")
+R = TypeVar("R")
+
+def filterable(
+    fn: Callable[P, R] | Callable[P, Awaitable[R]],
+) -> Callable[P, Any] | Callable[P, Awaitable[Any]]:
+    ...
+```
+
+`ParamSpec` captures the full signature (args and kwargs) for decorator typing.
+
+from [pdsx/mcp/filterable.py](https://github.com/zzstoatzz/pdsx/blob/main/src/pdsx/mcp/filterable.py)
+
+## ParamSpec
+
+for decorators that preserve function signatures:
+
+```python
+@wraps(fn)
+async def async_wrapper(
+    *args: P.args, _filter: str | None = None, **kwargs: P.kwargs
+) -> Any:
+    result = await fn(*args, **kwargs)
+    return apply_filter(result, _filter)
+```
+
+`P.args` and `P.kwargs` carry the original function's parameter types into the wrapper. type checkers see the wrapper with the same signature as the wrapped function (plus any new parameters).
+
+from [pdsx/mcp/filterable.py](https://github.com/zzstoatzz/pdsx/blob/main/src/pdsx/mcp/filterable.py)
+
+## overload
+
+when return type depends on input type:
+
+```python
+from typing import overload
+
+@overload
+def filterable(
+    fn: Callable[P, Awaitable[R]],
+) -> Callable[P, Awaitable[Any]]: ...
+
+@overload
+def filterable(
+    fn: Callable[P, R],
+) -> Callable[P, Any]: ...
+
+def filterable(
+    fn: Callable[P, R] | Callable[P, Awaitable[R]],
+) -> Callable[P, Any] | Callable[P, Awaitable[Any]]:
+    ...
+```
+
+type checkers know async functions get async wrappers, sync functions get sync wrappers.
+
+from [pdsx/mcp/filterable.py](https://github.com/zzstoatzz/pdsx/blob/main/src/pdsx/mcp/filterable.py)
+
+## TYPE_CHECKING
+
+avoid runtime import costs for types only needed for hints:
+
+```python
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from docket import Docket
+    from docket.execution import Execution
+    from fastmcp.tools.tool_transform import ArgTransform, TransformedTool
+```
+
+the import doesn't happen at runtime, only when type checkers analyze the code. with `from __future__ import annotations`, you don't need string quotes.
+
+from [fastmcp/tools/tool.py](https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/tools/tool.py)
+
+## import organization
+
+```python
+"""module docstring."""
+
+from __future__ import annotations
+
+import stdlib_module
+from typing import TYPE_CHECKING
+
+from third_party import thing
+
+from local_package import helper
+
+if TYPE_CHECKING:
+    from expensive import Type
+```
+
+sources:
+- [pdsx/src/pdsx/_internal/types.py](https://github.com/zzstoatzz/pdsx/blob/main/src/pdsx/_internal/types.py)
+- [fastmcp/src/fastmcp/tools/tool.py](https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/tools/tool.py)

languages/python/patterns.md languages/python/language/patterns.md

···
 
 lighter than pydantic when you control the data source.
 
+from [pdsx/_internal/batch.py](https://github.com/zzstoatzz/pdsx/blob/main/src/pdsx/_internal/batch.py)
+
 ## base classes with parallel implementations
 
 when you need both sync and async:
···
 ```python
 @dataclass
 class URIParts:
+    """parsed components of an AT-URI."""
     repo: str
     collection: str
     rkey: str
 
     @classmethod
-    def from_uri(cls, uri: str) -> "URIParts":
-        # at://did:plc:xxx/app.bsky.feed.post/abc
-        parts = uri.replace("at://", "").split("/")
-        return cls(repo=parts[0], collection=parts[1], rkey=parts[2])
+    def from_uri(cls, uri: str, client_did: str | None = None) -> URIParts:
+        """parse an AT-URI into its components."""
+        uri_without_prefix = uri.replace("at://", "")
+        parts = uri_without_prefix.split("/")
+
+        # shorthand format: collection/rkey
+        if len(parts) == 2:
+            if not client_did:
+                raise ValueError("shorthand URI requires authentication")
+            return cls(repo=client_did, collection=parts[0], rkey=parts[1])
+
+        # full format: did/collection/rkey
+        if len(parts) == 3:
+            return cls(repo=parts[0], collection=parts[1], rkey=parts[2])
+
+        raise ValueError(f"invalid URI format: {uri}")
 ```
+
+from [pdsx/_internal/resolution.py](https://github.com/zzstoatzz/pdsx/blob/main/src/pdsx/_internal/resolution.py)
 
 ## keyword-only arguments
 
···
 ```
 
 the message tells you what to do, not just what went wrong.
+
+from [pdsx/mcp/client.py](https://github.com/zzstoatzz/pdsx/blob/main/src/pdsx/mcp/client.py)
 
 ## exception hierarchies
 
···
 ```
 
 the wrapper's signature now includes `_filter`. IDEs and schema generators see it.
+
+from [pdsx/mcp/filterable.py](https://github.com/zzstoatzz/pdsx/blob/main/src/pdsx/mcp/filterable.py)
 
 ## argparse for CLIs
 

languages/python/pydantic.md

···
-# pydantic
-
-pydantic is a library, not the language. but it's become foundational enough that it's worth understanding.
-
-## the core idea
-
-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.
-
-pydantic makes them real. define a model with type hints, and pydantic validates and coerces data to match:
-
-```python
-from pydantic import BaseModel
-
-class User(BaseModel):
-    name: str
-    age: int
-
-user = User(name="alice", age="25")  # age coerced to int
-user = User(name="alice", age="not a number")  # raises ValidationError
-```
-
-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
-
-the most common use: replacing `os.getenv()` calls with validated configuration.
-
-```python
-from pydantic_settings import BaseSettings
-
-class Settings(BaseSettings):
-    database_url: str
-    debug: bool = False
-
-settings = Settings()  # reads from environment
-```
-
-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.
-
-## when to use what
-
-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
-from dataclasses import dataclass
-
-@dataclass
-class InternalRecord:
-    id: str
-    value: float
-```
-
-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:
-- [how to use pydantic-settings](https://blog.zzstoatzz.io/how-to-use-pydantic-settings/)

languages/python/typing.md

···
-# typing
-
-python 3.12 made typing feel native. generics have real syntax, type aliases have a keyword, and you rarely need to import from `typing` anymore.
-
-## the basics
-
-use `|` for unions:
-
-```python
-def fetch(url: str, timeout: float | None = None) -> dict[str, Any]: ...
-```
-
-`from __future__ import annotations` at the top of files lets you reference types before they're defined and avoids some runtime costs.
-
-## type aliases
-
-the `type` statement creates type aliases:
-
-```python
-type UserId = int
-type Handler = Callable[[Request], Response]
-type Result[T] = T | Error
-```
-
-clearer than `TypeAlias` annotations and supports generics directly.
-
-## TypedDict
-
-for structured dictionaries where you know the shape:
-
-```python
-from typing import TypedDict
-
-class RecordResponse(TypedDict):
-    uri: str
-    cid: str | None
-    value: dict[str, Any]
-
-def get_record(uri: str) -> RecordResponse:
-    ...
-```
-
-better than `dict[str, Any]` because the structure is documented and checked.
-
-## Annotated
-
-add metadata to types, especially useful with pydantic:
-
-```python
-from typing import Annotated
-from pydantic import Field
-
-FilterParam = Annotated[
-    str | None,
-    Field(description="jmespath expression to filter results"),
-]
-
-def list_records(collection: str, _filter: FilterParam = None) -> list[dict]:
-    ...
-```
-
-the metadata travels with the type. frameworks like fastmcp use it for schema generation.
-
-## Protocol
-
-duck typing with type safety. define what methods something needs, not what class it is:
-
-```python
-from typing import Protocol, runtime_checkable
-
-@runtime_checkable
-class Closeable(Protocol):
-    def close(self) -> None: ...
-
-def cleanup(resource: Closeable) -> None:
-    resource.close()
-```
-
-`@runtime_checkable` lets you use `isinstance()` checks.
-
-## generics
-
-3.12 introduced native syntax for generics. no more `TypeVar`:
-
-```python
-def first[T](items: list[T]) -> T | None:
-    return items[0] if items else None
-```
-
-with bounds:
-
-```python
-from pydantic import BaseModel
-
-def parse[M: BaseModel](data: dict, model: type[M]) -> M:
-    return model.model_validate(data)
-```
-
-the `[T]` declares the type parameter inline. `[M: BaseModel]` constrains it. this is real syntax, not a workaround.
-
-## ParamSpec
-
-for decorators that preserve function signatures:
-
-```python
-from typing import ParamSpec, TypeVar, Callable, Awaitable
-from functools import wraps
-
-P = ParamSpec("P")
-R = TypeVar("R")
-
-def logged(fn: Callable[P, Awaitable[R]]) -> Callable[P, Awaitable[R]]:
-    @wraps(fn)
-    async def wrapper(*args: P.args, **kwargs: P.kwargs) -> R:
-        print(f"calling {fn.__name__}")
-        return await fn(*args, **kwargs)
-    return wrapper
-```
-
-this preserves the original function's parameter types in the wrapper.
-
-## overload
-
-when return type depends on input:
-
-```python
-from typing import overload, Literal
-
-@overload
-def fetch(url: str, raw: Literal[True]) -> bytes: ...
-@overload
-def fetch(url: str, raw: Literal[False] = False) -> dict: ...
-
-def fetch(url: str, raw: bool = False) -> bytes | dict:
-    response = httpx.get(url)
-    return response.content if raw else response.json()
-```
-
-IDEs and type checkers know that `fetch(url, raw=True)` returns `bytes`.
-
-## TYPE_CHECKING
-
-avoid runtime import costs for types only needed for hints:
-
-```python
-from typing import TYPE_CHECKING
-
-if TYPE_CHECKING:
-    from heavy_module import ExpensiveClass
-
-def process(item: "ExpensiveClass") -> None:
-    ...
-```
-
-the string quote is needed because the import doesn't happen at runtime.
-
-## import organization
-
-```python
-"""module docstring."""
-
-from __future__ import annotations
-
-import stdlib_module
-from typing import TYPE_CHECKING
-
-from third_party import thing
-
-from local_package import helper
-
-if TYPE_CHECKING:
-    from expensive import Type
-```
-
-sources:
-- [pdsx/src/pdsx/_internal/types.py](https://github.com/zzstoatzz/pdsx/blob/main/src/pdsx/_internal/types.py)
-- [fastmcp/src/fastmcp/tools/tool.py](https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/tools/tool.py)