Skip to content

Document Python schema metadata and compatible TypedDict imports - #511

Merged
robgruen merged 1 commit into
mainfrom
dev/robgruen/python-schema-docs-220
Nov 2, 2026
Merged

robgruen merged 1 commit into
mainfrom
dev/robgruen/python-schema-docs-220

Conversation

@robgruen

@robgruen robgruen commented Nov 2, 2026 •

Copy link
Copy Markdown
Contributor

Summary

Implement the documentation-only scope accepted for #220.

  • Explain Python 3.11's Pydantic restriction on typing.TypedDict, with a complete example importing TypedDict and Doc from typing_extensions and Annotated/Literal from typing.
  • Show otherwise identical Doc and plain-string field descriptions and explain that both document the generated schema.
  • Preserve inline-comment source requirements and explicit-metadata precedence.
  • Execute both guide examples in deterministic tests, checking the exact generated schema, valid values, invalid literals, and required fields.

No runtime conversion/validation, dependency, minimum-Python-version, or blanket import migration changes. This does not duplicate the runtime work in #466.

Provenance and manual recovery

The documentation and tests originated in owner-authorized build run 41493733655, based on 81a9b902686723908a8be5ec5216bec19f5ccc64.

That run completed generation and threat detection and passed 107 Python tests with 3 skipped, but strict Pyright rejected three propagated unknown types in the new test. Automated publication was correctly blocked. The owner then approved manual recovery and this separate review PR.

The sole manual code change is the explicit TypeChatValidator[dict[str, str]] result type. The actual runtime schema argument and all negative validation assertions remain unchanged. The guide is byte-for-byte the original generated candidate. This is a manually recovered PR, not a successful automated publication; the original scan is not presented as validation of the subsequent manual edit.

Validation

  • Both new regression cases pass on Python 3.11.18 with the project's unchanged declared development/example dependencies, using the existing pytest runner directly.
  • npm run check: 0 errors and 0 warnings.
  • Site npm run build passes on Node 24.22.1 after restoring its existing locked dependencies.
  • Verified that only the explicit generic annotation differs from the original candidate.
  • Whitespace checks pass. All 12 current-head CI checks pass, including strict Pyright on Python 3.11 through 3.14 and aggregate CodeQL. Copilot reports no open issues and recommends approval; human review and merge remain separate decisions.

Existing contributions

Builds on the existing documentation and schema support in #237 and #364, preserves the history of #245, and retains #466 as related but separate work. Accepted scope and contributor credit are unchanged. No automatic merge or issue closure is requested.

Recover the candidate from workflow run 41493733655 and repair the explicit result type for its dynamically loaded guide schemas. Preserve the actual runtime schema and strict negative validation checks. Addresses #220 without changing runtime conversion, dependencies, or the minimum Python version.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Copilot AI balanced review requested due to automatic review settings November 2, 2026 18:57

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟢 Approval recommended

No active review issues are reported for the TypedDict documentation and example-test changes.

No open issues 🎉

What changed in this PR

Documents compatible Python TypedDict imports and field metadata within the accepted scope of #220, without changing runtime behavior or dependencies.

Changes:

  • Explains Python 3.11’s Pydantic import restriction and provides complete Doc and plain-string examples.
  • Clarifies inline-comment source requirements and explicit-metadata precedence.
  • Adds deterministic tests that execute both guide examples and check exact schema output, valid values, invalid literals, and required fields.
File Description
site/​src/​docs/​python/​basic-usage.md Documents compatible imports and supported field-description styles.
python/​tests/​test_schema_documentation.py Verifies the documented examples’ schema generation and validation behavior.

Review effort: Balanced

@robgruen
robgruen merged commit f545a51 into main Nov 2, 2026
13 checks passed
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.

3 participants