fix(http-client-python): generate valid Python type annotations in types.py

[Libba Lawrence (l0lawrence)]

The Python client emitter generated types.py files with invalid type annotations for azure-search-documents, producing 4 MyPy errors across three generated files. This fixes the three distinct codegen bugs behind them. Each bug below shows the generated-code output before and after the fix.

Bug 1: inconsistent internal-enum export and reference

azure/search/documents/types.py

  from typing import TYPE_CHECKING, Union
  from typing_extensions import TypedDict

  if TYPE_CHECKING:
-     from .models import SemanticQueryRewritesResultType
+     from .models._enums import SemanticQueryRewritesResultType


  class SearchDocumentsResult(TypedDict, total=False):
-     semanticQueryRewritesResultType: Union[str, "_enums.SemanticQueryRewritesResultType"]
+     semanticQueryRewritesResultType: Union[str, "SemanticQueryRewritesResultType"]

Before, the import pulled the bare name from the public .models package, where the internal enum is not re-exported (Module "...models" has no attribute "SemanticQueryRewritesResultType" [attr-defined]), and the annotation referenced an undefined _enums. prefix (Name "_enums" is not defined [name-defined]). After, the enum symbol is imported directly from the private ._enums submodule and the annotation uses the matching bare forward reference. Enums stay private (no change to the public __all__).

Bug 2: duplicate enum import

azure/search/documents/knowledgebases/types.py

- from typing import TYPE_CHECKING, Union
+ from typing import Union
  from typing_extensions import TypedDict

  from ..indexes.models._enums import KnowledgeSourceKind

- if TYPE_CHECKING:
-     from ..indexes.models import KnowledgeSourceKind
-

  class KnowledgeSource(TypedDict, total=False):
      kind: Union[str, "KnowledgeSourceKind"]

Before, the same symbol was imported at runtime from its _enums submodule and again under if TYPE_CHECKING: from the public package (Name "KnowledgeSourceKind" already defined [no-redef]). After, a dedup pass drops the TYPE_CHECKING duplicate whose bound name is already imported at runtime; the runtime import is sufficient for the annotations.

Bug 3: TypedDict requiredness override via inheritance

azure/search/documents/indexes/types.py

  class SearchIndexerKnowledgeStoreProjectionSelector(TypedDict, total=False):
      referenceKeyName: str
      generatedKeyName: str


- class SearchIndexerKnowledgeStoreTableProjectionSelector(
-     SearchIndexerKnowledgeStoreProjectionSelector
- ):
+ class SearchIndexerKnowledgeStoreTableProjectionSelector(TypedDict, total=False):
+     referenceKeyName: str
      generatedKeyName: Required[str]
      tableName: Required[str]

Before, the child subclassed the parent and redeclared generatedKeyName as Required[str], which PEP 589 forbids (Overwriting TypedDict field "generatedKeyName" while extending [misc]). After, the child renders as a flat, non-inheriting TypedDict that lists every field (inherited plus own) directly, so requiredness is expressed without illegal inheritance.

Notes for reviewers

• The internal-enum import intentionally imports the bare symbol from _enums rather than the _enums module, which also avoids name collisions when internal enums come from several sibling namespaces.
• Regression tests were added to tests/unit/test_typeddict.py covering all three cases.

Validation

• test_typeddict.py + test_enums.py: 50 passed (42 existing + 8 new).
• pylint 10.00/10 on the changed files; black clean under the project config; mypy introduces no new errors (the pre-existing errors are unchanged on the baseline).
• Reproduced the fix end to end against the issue's errors: a minimal azure/search/documents package built from the buggy forms reproduces the attr-defined, name-defined, and misc (TypedDict) errors under mypy --python-version 3.10, and the fixed forms type-check with exit 0. Bug 2's duplicate import is confirmed removed at the serializer level (baseline emits two imports of KnowledgeSourceKind, the fix emits one).

Fixes: #11626

[pkg-pr-new]

Open in StackBlitz

npm i https://pkg.pr.new/@typespec/http-client-python@11638

commit: e3e2039

[github-actions]

All changed packages have been documented.

• ✅ @typespec/http-client-python

Show changes

@typespec/http-client-python - fix ✏️

Fix invalid Python type annotations generated in types.py files. Internal enums used as TypedDict fields are now imported (as a bare symbol) from their private _enums submodule so the annotation resolves; duplicate runtime + TYPE_CHECKING imports of the same symbol are deduplicated to avoid no-redef; and TypedDicts that change an inherited field's requiredness are emitted as a flat (non-inheriting) TypedDict to satisfy PEP 589.

[github-actions]

Python emitter diff

Baseline gh:a849fcfc965b6dc0cb8dffcb32132e71655a6b4a vs this PR.

No changes to generated output.

Rendered diff: inline on the run summary, or the emitter-diff-html artifact.

Informational check (eng/emitter-diff); does not block the PR.

[azure-sdk-automation]

You can try these changes here

🛝 Playground	🌐 Website	🛝 VSCode Extension

[iscai-msft]

which things do we keep in typing imports only? is it just the token credential from azure.core?

[Libba Lawrence (l0lawrence)]

Things we keep typing-only today are the imports that are only referenced inside quoted/forward-ref annotations and must not be imported at runtime, e.g.:

• TokenCredential / AsyncTokenCredential + SdkCoreType with isTypingOnly (primitive_types.py)
• forward-referenced model/enum annotations (model_type.py, enum_type.py) and a few response/parameter/combined-type cases

The only case this should touch and remove from type-checking is the same symbol imported both at runtime (from its _enums submodule) and again under TYPE_CHECKING (from the public models package)

[Copilot]

Pull request overview

Fixes multiple Python emitter codegen issues that produced invalid type annotations in generated types.py files (reported for azure-search-documents), primarily impacting MyPy correctness for internal enums, duplicate imports, and TypedDict inheritance requiredness.

Changes:

• Emit consistent internal-enum annotations and imports for types.py (use bare forward refs and import from private _enums when needed).
• Deduplicate TYPE_CHECKING imports when the same bound name is already imported at runtime to avoid MyPy no-redef.
• Emit “flat” (non-inheriting) TypedDicts when a child changes an inherited field’s requiredness (PEP 589 compliance), with unit test coverage for all three regressions.

Reviewed changes

Copilot reviewed 6 out of 6 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
packages/http-client-python/tests/unit/test_typeddict.py	Adds regression tests covering internal enum import/reference, import dedupe, and flat TypedDict requiredness override.
packages/http-client-python/generator/pygen/codegen/serializers/types_serializer.py	Introduces needs_flat_typeddict and uses it to avoid illegal TypedDict inheritance and unnecessary parent imports.
packages/http-client-python/generator/pygen/codegen/serializers/import_serializer.py	Adds dedupe pass to remove redundant TYPE_CHECKING imports that would cause MyPy no-redef.
packages/http-client-python/generator/pygen/codegen/models/enum_type.py	Adjusts enum annotation/import behavior for types.py, including internal enums importing from private _enums.
cspell.yaml	Adds “dedupe” and “redef” to dictionary for new terminology used in comments/strings.
.chronus/changes/fix-python-emitter-invalid-type-annotations-2026-4-18-0-0-0.md	Adds changelog entry describing the three bug fixes.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[Copilot]

Pull request overview

Copilot reviewed 6 out of 6 changed files in this pull request and generated no new comments.