Skip to content

Add grounded Python typing docs for serialization and async iteration - #19

Open
citadelgrad wants to merge 2 commits into
jpablo:mainfrom
citadelgrad:python-typing-docs-research
Open

Add grounded Python typing docs for serialization and async iteration#19
citadelgrad wants to merge 2 commits into
jpablo:mainfrom
citadelgrad:python-typing-docs-research

Conversation

@citadelgrad

@citadelgrad citadelgrad commented Jul 10, 2026

Copy link
Copy Markdown

Summary

Adds grounded Python typing coverage for two missing areas:

  • T64-async-iteration: async iteration/generator technique doc with pyright-checked snippets and source anchors.
  • UC19-serialization: serialization safety use case for parsing JSON/wire data into typed payloads, with TypedDict/dataclass/Literal patterns.
  • Updates Python navigation, cross-language taxonomy counts, and Python source references.
  • Fixes an existing strict-Pyright docs-snippet failure in UC11-effect-tracking.md by annotating @contextmanager examples with Generator instead of Iterator.

Grounding / sources checked

Fetched and used official/source docs for Python typing, collections.abc, json, PEP 492, PEP 525, PEP 589, PEP 655, PEP 705, PEP 681, Pydantic serialization, and mypy TypedDict behavior. These are listed in taxonomy/sources.md and in the new docs' Source anchors.

Review passes

  • Research grounding review: source-backed claims only; Python UC19 is marked ~ in the taxonomy because full serialization safety is achievable via patterns/libraries, not native compiler derivation.
  • Python typing/code review: snippets are pyright-verified; async generator annotations and contextmanager annotations match current checker behavior.
  • Documentation integration review: navigation, SKILL.md, README counts, and taxonomy coverage were updated together.

Annotation reasoning: @contextmanager uses Generator, not Iterator

The UC11-effect-tracking.md change from Iterator[T] to Generator[T] is intentional and checker-driven:

  • A function decorated with @contextmanager is implemented as a generator function: it yields the value exposed by with ... as value.
  • Iterator[T] is broad enough for some checkers, but current Pyright strict mode reports that annotation as deprecated for @contextmanager and asks for Generator[T]. This is not limited to Python 3.14; it appears under the repo's strict Pyright config across Python targets 3.10-3.14.
  • ty 0.0.56 accepts both Iterator[int] and Generator[int] and reveals the with binding as int in both cases.
  • Therefore Generator[T] is the more portable documentation choice for this repo: it passes strict Pyright while remaining accepted by ty, and it more precisely describes the generator function before contextmanager wraps it.

Review follow-up

Follow-up commit 5bf502f addresses reviewer findings: Python navigation now exposes all 33 catalog entries and UC21, UC19/T64 snippets in the touched docs have zero skipped snippets, the shared T64 taxonomy wording is language-neutral, and the TypeScript technique count is corrected to the filesystem-backed 35.

Verification

  • make check
    • tenets sync: all skills ok
    • snippet extractor tests: 39 passed
  • make verify FILE=plugin/skills/python/catalog/T64-async-iteration.md
    • 2 ok, 0 fail, 3 expected-fail, 0 missing-expected-error, 0 skipped, 0 tool errors
  • make verify FILE=plugin/skills/python/usecases/UC19-serialization.md
    • 1 ok, 0 fail, 4 expected-fail, 0 missing-expected-error, 0 skipped, 0 tool errors
  • make verify-python
    • checked 54 files: 0 with failures, 0 tool-errors

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant