You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Python users can choose supported field-description syntax and copy imports that work with TypeChat's Python 3.11 validation support.
Scope
Add the Python 3.11 TypedDict import caveat and a compatible import example to the existing Python basic usage guide.
Show Doc-based and plain-string field descriptions together in the existing Python schema documentation, building on the merged usage and inline-comment documentation.
Non-goals
No runtime schema-conversion or validation changes, dependency changes, or increase to the minimum Python version.
No new field-comment mechanism, source rewriting, blanket example-import migration, or duplication of the runtime-type work in open PR 466.
Acceptance criteria
The existing Python schema guide includes a complete TypedDict example importing Annotated and Literal from typing and TypedDict and Doc from typing_extensions, and explicitly explains the Python 3.11 Pydantic restriction on typing.TypedDict.
Adjacent examples show an otherwise identical TypedDict field described once with Doc and once with a plain string, and explicitly state that either form supplies documentation to the generated schema.
Existing inline-comment guidance remains intact, including the need for available source and the precedence of explicit Annotated metadata. Runtime conversion, validation, dependencies, and the minimum Python version remain unchanged.
This accepts the scope above. It does not start or authorize an automated implementation run, increase any budget, or approve merging. Material scope changes require a new proposal and owner decision.
For Python 3.11, keeping TypedDict in typing_extensions is the right choice. TypeChat's runtime validator uses Pydantic, which requires that version of TypedDict below Python 3.12 even though typing.TypedDict exists. Annotated and Literal can come from typing; Doc, if used, comes from typing_extensions. Replacing the TypedDict import just to satisfy the linter would break validation on Python 3.11.
Doc is not the only option. Annotated is Python's mechanism for attaching metadata to a type, and TypeChat recognizes both Annotated[str, Doc("Description")] and Annotated[str, "Description"] as field descriptions in the generated TypeScript schema. Interpreting that metadata as documentation is TypeChat behavior. The repository also supports trailing inline comments when the class's source is available; explicit Annotated descriptions take precedence, even when empty.
Thanks for flagging the import caveat and asking for both description forms to be documented. PR 511 has since merged those additions into the repository's Python basic usage guide, building on DanielRosenwasser's usage documentation and hemanth1999k's inline-comment support. That addresses the documentation request without changing validation or replacing imports throughout the examples.
Activity
pamelafox commentedon Mar 17, 2024
Ah but then there's a Pydantic error in 3.11:
Please use
typing_extensions.TypedDictinstead oftyping.TypedDicton Python < 3.12Dang! I'll just ignore my linter then / add a noqa. That might be worth mentioning in documentation about using TypeChat with TypedDict.
DanielRosenwasser commentedon Mar 18, 2024
So if you use
Annotated[SomeType, Doc(...)]we recognize that. Some folks working on Python recommended we future-proof on that.But we also just recognize
Annotated[SomeType, "Some comment string."]because that's so common anyway (and it just feels better to use).pamelafox commentedon Mar 18, 2024
Ah okay, I saw that mentioned in the Discourse thread but wasnt sure if that was also a standard. I recommend documenting both of those.
robgruen commentedon Nov 2, 2026
/typechat draft
github-actions commentedon Nov 2, 2026
TypeChat: Draft and work-acceptance preview prepared for owner review.
Owner request | Run and preview
Operational receipt only. This comment does not publish draft text, accept work, authorize implementation, or approve merging.
robgruen commentedon Nov 2, 2026
/typechat accept 13116089597:2abb67a9b2a120ab6d3f576d667c4eb3528e5224f290ebe9d1bda7746715c5f7
github-actions commentedon Nov 2, 2026
Accepted work
Approved by the project owner, robgruen, for issue #220.
Goal
Python users can choose supported field-description syntax and copy imports that work with TypeChat's Python 3.11 validation support.
Scope
Non-goals
Acceptance criteria
Existing contributions
Proposal run | Approved scope policy
This accepts the scope above. It does not start or authorize an automated implementation run, increase any budget, or approve merging. Material scope changes require a new proposal and owner decision.
robgruen commentedon Nov 2, 2026
/typechat build 6570261735:2abb67a9b2a120ab6d3f576d667c4eb3528e5224f290ebe9d1bda7746715c5f7
robgruen commentedon Nov 2, 2026
/typechat build 6570261735:2abb67a9b2a120ab6d3f576d667c4eb3528e5224f290ebe9d1bda7746715c5f7
Document Python schema metadata and compatible TypedDict imports (#511)
robgruen commentedon Nov 4, 2026
/typechat reply
github-actions commentedon Nov 4, 2026
For Python 3.11, keeping TypedDict in typing_extensions is the right choice. TypeChat's runtime validator uses Pydantic, which requires that version of TypedDict below Python 3.12 even though typing.TypedDict exists. Annotated and Literal can come from typing; Doc, if used, comes from typing_extensions. Replacing the TypedDict import just to satisfy the linter would break validation on Python 3.11.
Doc is not the only option. Annotated is Python's mechanism for attaching metadata to a type, and TypeChat recognizes both Annotated[str, Doc("Description")] and Annotated[str, "Description"] as field descriptions in the generated TypeScript schema. Interpreting that metadata as documentation is TypeChat behavior. The repository also supports trailing inline comments when the class's source is available; explicit Annotated descriptions take precedence, even when empty.
Thanks for flagging the import caveat and asking for both description forms to be documented. PR 511 has since merged those additions into the repository's Python basic usage guide, building on DanielRosenwasser's usage documentation and hemanth1999k's inline-comment support. That addresses the documentation request without changing validation or replacing imports throughout the examples.
Related contributions: #237, #245, #364, #466, #511.
Automated response requested by the project owner. This does not accept work or authorize implementation.