Skip to content

[python] Upgrade the imports in examples #220

Closed

Description

@pamelafox

Pyupgrade recommends:

import asyncio
from typing import Annotated, Literal, TypedDict

import dotenv
from typing_extensions import Doc

As everything but Doc has been in typing since 3.8 or 3.9:

https://docs.python.org/3/library/typing.html#typing.Literal

Apparently Doc is non-standard, interesting discussion on the PEP here:
https://discuss.python.org/t/pep-727-documentation-metadata-in-typing/32566/172

It seems unlikely to get accepted, but I assume its the only way to document when using TypedDict? That's what I saw in the examples.

Activity

  1. pamelafox commented on Mar 17, 2024

    @pamelafox
    MemberAuthor

    Ah but then there's a Pydantic error in 3.11:

    Please use typing_extensions.TypedDict instead of typing.TypedDict on Python < 3.12

    Dang! I'll just ignore my linter then / add a noqa. That might be worth mentioning in documentation about using TypeChat with TypedDict.

  2. DanielRosenwasser commented on Mar 18, 2024

    @DanielRosenwasser
    Member

    I assume its the only way to document when using TypedDict

    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).

  3. pamelafox commented on Mar 18, 2024

    @pamelafox
    MemberAuthor

    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.

  4. robgruen commented on Nov 2, 2026

    @robgruen
    Contributor

    /typechat draft

  5. github-actions commented on Nov 2, 2026

    @github-actions
    Contributor

    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.

  6. robgruen commented on Nov 2, 2026

    @robgruen
    Contributor

    /typechat accept 13116089597:2abb67a9b2a120ab6d3f576d667c4eb3528e5224f290ebe9d1bda7746715c5f7

  7. github-actions commented on Nov 2, 2026

    @github-actions
    Contributor

    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

    • 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.

    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.

  8. robgruen commented on Nov 2, 2026

    @robgruen
    Contributor

    /typechat build 6570261735:2abb67a9b2a120ab6d3f576d667c4eb3528e5224f290ebe9d1bda7746715c5f7

  9. robgruen commented on Nov 2, 2026

    @robgruen
    Contributor

    /typechat build 6570261735:2abb67a9b2a120ab6d3f576d667c4eb3528e5224f290ebe9d1bda7746715c5f7

  10. robgruen commented on Nov 4, 2026

    @robgruen
    Contributor

    /typechat reply

  11. github-actions commented on Nov 4, 2026

    @github-actions
    Contributor

    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.

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

Metadata

Metadata

Assignees

No one assigned

    Labels

    Language: PythonPertains to the Python implementation of TypeChat.

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions