Add grounded Python typing docs for serialization and async iteration - #19
Open
citadelgrad wants to merge 2 commits into
Open
Add grounded Python typing docs for serialization and async iteration#19citadelgrad wants to merge 2 commits into
citadelgrad wants to merge 2 commits into
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
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.UC11-effect-tracking.mdby annotating@contextmanagerexamples withGeneratorinstead ofIterator.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.mdand in the new docs' Source anchors.Review passes
~in the taxonomy because full serialization safety is achievable via patterns/libraries, not native compiler derivation.Annotation reasoning:
@contextmanagerusesGenerator, notIteratorThe
UC11-effect-tracking.mdchange fromIterator[T]toGenerator[T]is intentional and checker-driven:@contextmanageris implemented as a generator function: ityields the value exposed bywith ... as value.Iterator[T]is broad enough for some checkers, but current Pyright strict mode reports that annotation as deprecated for@contextmanagerand asks forGenerator[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.56accepts bothIterator[int]andGenerator[int]and reveals thewithbinding asintin both cases.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 beforecontextmanagerwraps it.Review follow-up
Follow-up commit
5bf502faddresses 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 check39 passedmake verify FILE=plugin/skills/python/catalog/T64-async-iteration.md2 ok, 0 fail, 3 expected-fail, 0 missing-expected-error, 0 skipped, 0 tool errorsmake verify FILE=plugin/skills/python/usecases/UC19-serialization.md1 ok, 0 fail, 4 expected-fail, 0 missing-expected-error, 0 skipped, 0 tool errorsmake verify-pythonchecked 54 files: 0 with failures, 0 tool-errors