docs(python): add deeper type system coverage to best practices

[agent-kurouto]

Summary

Addresses PLT-1013 — expands Section 2 (Type Hints & Static Analysis) with 9 new subsections that dive deeper into Python's type system:

• TypedDict — typed dict structures with optional keys; comparison table vs dataclasses/Pydantic/NamedTuple
• Literal — value-constrained types for function parameters; exhaustive narrowing with Pyright
• NewType — zero-runtime-cost domain primitives to prevent mixing semantically different IDs/values
• Final and ClassVar — immutability annotations for constants, frozen instance attributes, and class-level vs instance-level fields
• @overload — multiple call signatures when return type varies by argument type; rules and anti-patterns
• TypeGuard and type narrowing — custom predicates, built-in isinstance narrowing, and assert_never for exhaustive matching
• Self — subclass-safe returns for fluent/builder patterns and classmethods; replaces TypeVar(bound=...) boilerplate
• TYPE_CHECKING guard — avoiding circular imports by deferring type-only imports; paired with from __future__ import annotations
• Annotated — attaching validation/documentation metadata to types; Pydantic v2 and FastAPI integration examples

Also adds 8 new PEP references to the Further Reading section (PEP 544, 586, 589, 591, 647, 673, 593, and the mypy type narrowing docs).

Test plan

• Read through all new subsections for accuracy and consistency with existing document style
• Verify code examples are syntactically correct Python
• Check that "Good" / "Avoid" / tip patterns match the rest of the document
• Confirm no overlap or contradiction with existing sections

🤖 Generated with Claude Code