[Bug]: Python emitter generates invalid type annotations for Azure AI Search

[efrainretana]

Describe the bug

Environment

• Package: azure-search-documents
• API version: 2026-08-01-preview
• Python emitter: @azure-tools/typespec-python 0.63.3
• TypeSpec project: specification/search/data-plane/Search
• TypeSpec commit: 84400eeb46c48ffe88d81e126449725508c17547
• Validation: MyPy with Python 3.10 compatibility

Summary

The Python emitter generates four MyPy errors across three types.py surfaces. Direct edits to
these files are not viable because SDK regeneration overwrites them.

Reproduction

Generate azure-search-documents from the TypeSpec project above, then run:

azpysdk --isolate mypy .

Actual diagnostics

azure/search/documents/types.py:16: error: Module "azure.search.documents.models" has no attribute "SemanticQueryRewritesResultType" [attr-defined]
azure/search/documents/types.py:382: error: Name "_enums" is not defined [name-defined]
azure/search/documents/knowledgebases/types.py:28: error: Name "KnowledgeSourceKind" already defined (possibly by an import) [no-redef]
azure/search/documents/indexes/types.py:5443: error: Overwriting TypedDict field "generatedKeyName" while extending [misc]

Bug 1: inconsistent enum export and reference

SemanticQueryRewritesResultType is generated in azure.search.documents.models._enums, but it is
not exported from azure.search.documents.models. The generated TYPE_CHECKING import expects the
public export, while SearchDocumentsResult refers to the undefined name
_enums.SemanticQueryRewritesResultType.

Expected generation:

1. Export SemanticQueryRewritesResultType from azure.search.documents.models.
2. Use a valid direct or public reference in SearchDocumentsResult, consistent with the other
   generated enum annotations.

Bug 2: duplicate enum import

azure.search.documents.knowledgebases.types imports KnowledgeSourceKind at runtime from
indexes.models._enums, then imports the same name again under TYPE_CHECKING from
indexesmodels.

Expected generation: emit only one import for KnowledgeSourceKind. The existing runtime import is
sufficient for the generated Literal annotations.

Bug 3: TypedDict requiredness override

SearchIndexerKnowledgeStoreProjectionSelector declares generatedKeyName as optional because the
base TypedDict uses total=False. SearchIndexerKnowledgeStoreTableProjectionSelector inherits
from it and redeclares the same key as Required[str]. MyPy does not permit changing a TypedDict
key's requiredness through inheritance.

Expected generation: preserve generatedKeyName as required for table projections without
overwriting an inherited TypedDict field. One valid representation is a standalone table-projection
TypedDict containing the shared selector fields plus required generatedKeyName and tableName.

Expected result

The generated package passes MyPy without SDK-side edits to generated files, while preserving the
public enum exports and required fields represented by the TypeSpec model.

Reproduction

See summary above.

Checklist

• Follow our Code of Conduct
• Check that there isn't already an issue that request the same bug to avoid creating a duplicate.
• Check that this is a concrete bug. For Q&A open a GitHub Discussion.
• The provided reproduction is a minimal reproducible example of the bug.

[github-actions]

🎯 Issue Triage

The Python emitter (@azure-tools/typespec-python 0.63.3) generates invalid Python type annotations for the azure-search-documents package, causing four MyPy errors across three types.py files. The bugs involve a missing enum export, a duplicate enum import, and an illegal TypedDict field requiredness override via inheritance.

Category: Bug
Area: emitter:client:python

⚠️ No TypeSpec reproduction provided. The reproduction requires generating the azure-search-documents SDK from the specification/search/data-plane/Search TypeSpec project at commit 84400eeb46c48ffe88d81e126449725508c17547, then running azpysdk --isolate mypy ..

🔍 Analysis

Three distinct code generation bugs are reported:

1. Bug 1 — Inconsistent enum export/reference (types.py:16, types.py:382): SemanticQueryRewritesResultType is generated in _enums but not re-exported from the public models module. A TYPE_CHECKING import references the missing public symbol, while the runtime code uses the undefined bare name _enums.SemanticQueryRewritesResultType. Root cause: enum export table generation is incomplete for this enum, and the reference strategy is inconsistent.

2. Bug 2 — Duplicate enum import (knowledgebases/types.py:28): KnowledgeSourceKind is imported twice — once at runtime from indexes.models._enums and once under TYPE_CHECKING from indexesmodels. MyPy sees this as a redefinition ([no-redef]). Root cause: the import deduplication logic doesn't unify runtime and TYPE_CHECKING imports for the same symbol.

3. Bug 3 — TypedDict requiredness override (indexes/types.py:5443): SearchIndexerKnowledgeStoreTableProjectionSelector inherits from SearchIndexerKnowledgeStoreProjectionSelector (total=False) and tries to redeclare generatedKeyName as Required[str]. Python's MyPy disallows overwriting inherited TypedDict fields. Root cause: the emitter emits a subclass TypedDict that re-declares an inherited field to change its requiredness, which is not valid in Python's type system.

All three bugs are confined to the Python emitter's code generation logic and do not require TypeSpec spec changes.

📝 Suggested next steps

• Fix enum export: ensure all generated enums are added to the public __all__ / re-export list of their parent models module.
• Fix enum import deduplication: unify runtime and TYPE_CHECKING import lists so the same symbol isn't imported twice.
• Fix TypedDict inheritance: when a subtype needs to change a field's requiredness, generate a flat (non-inheriting) TypedDict that includes all fields explicitly rather than subclassing.
• Add regression tests covering cross-namespace enum imports and TypedDict required-field inheritance patterns.

Generated by Agentic Triage