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

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`

```diff
  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`

```diff
- 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`

```diff
  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

---------

Co-authored-by: iscai-msft <43154838+iscai-msft@users.noreply.github.com>
Copilot-Session: 1a8cce88-1663-4cc6-a634-2e83e35d04b7

Author: l0lawrence

.chronus/changes/fix-python-emitter-invalid-type-annotations-2026-4-18-0-0-0.md

@@ -0,0 +1,7 @@
+---
+changeKind: fix
+packages:
+  - "@typespec/http-client-python"
+---
+
+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.

cspell.yaml

@@ -62,6 +62,7 @@ words:
   - Declipse
   - dedented
   - dedup
+  - dedupe
   - Dedupes
   - deps
   - deser
@@ -240,6 +241,7 @@ words:
   - reactivex
   - recase
   - recorda
+  - redef
   - regen
   - rehype
   - reinjected

packages/http-client-python/generator/pygen/codegen/models/enum_type.py

@@ -203,6 +203,10 @@ def type_annotation(self, **kwargs: Any) -> str:
                 model_alias = self.code_model.get_unique_models_alias(serialize_namespace, self.client_namespace)
                 module_name = f"{model_alias}."
             file_name = f"{self.code_model.enums_filename}." if self.internal else ""
+            if serialize_namespace_type == NamespaceType.TYPES_FILE:
+                # In types.py the enum symbol is imported directly (bare name), so no ``_enums.``
+                # module prefix even for internal enums — the prefix would be an undefined name.
+                file_name = ""
             model_name = module_name + file_name + self.name
             # we don't need quoted annotation in operation files, and need it in model folder files.
             if not kwargs.get("is_operation_file", False):
@@ -305,9 +309,17 @@ def imports(self, **kwargs: Any) -> FileImport:
                         typing_section=TypingSection.REGULAR,
                     )
                 elif serialize_namespace_type == NamespaceType.TYPES_FILE:
-                    # Import enum name directly to avoid dotted forward refs in TypedDict annotations
+                    # Import the enum symbol directly to avoid dotted forward refs in TypedDict
+                    # annotations. Internal enums are not re-exported from the public ``models``
+                    # package, so import them from the private ``_enums`` submodule instead — the
+                    # bare-symbol import (rather than the ``_enums`` module) also avoids name
+                    # collisions when internal enums come from several sibling namespaces.
+                    module_name = f"models.{self.code_model.enums_filename}" if self.internal else "models"
+                    enums_module = self.code_model.get_relative_import_path(
+                        serialize_namespace, self.client_namespace, module_name=module_name
+                    )
                     file_import.add_submodule_import(
-                        f"{relative_path}models" if relative_path != "." else ".models",
+                        enums_module,
                         self.name,
                         ImportType.LOCAL,
                         typing_section=TypingSection.TYPING,

packages/http-client-python/generator/pygen/codegen/serializers/import_serializer.py

@@ -84,6 +84,32 @@ def _add_type_checking_import(self):
         if any(self.file_import.get_imports_from_section(TypingSection.TYPING)):
             self.file_import.add_submodule_import("typing", "TYPE_CHECKING", ImportType.STDLIB)
 
+    def _dedupe_typing_imports(self):
+        """Drop TYPE_CHECKING imports whose bound name is already imported at runtime.
+
+        A name imported in the regular (runtime) section is also available during type checking, so a
+        duplicate import under ``if TYPE_CHECKING:`` is redundant and triggers mypy's ``no-redef``
+        error. This can happen when the same symbol is imported from two different modules — e.g. a
+        cross-namespace enum imported at runtime from its ``_enums`` submodule and again for its
+        annotation from the public ``models`` package. The runtime import is sufficient.
+        """
+        regular_bound_names = {
+            (i.alias or i.submodule_name)
+            for i in self.file_import.get_imports_from_section(TypingSection.REGULAR)
+            if i.submodule_name
+        }
+        if not regular_bound_names:
+            return
+        self.file_import.imports = [
+            i
+            for i in self.file_import.imports
+            if not (
+                i.typing_section == TypingSection.TYPING
+                and i.submodule_name
+                and (i.alias or i.submodule_name) in regular_bound_names
+            )
+        ]
+
     def _add_sys_import_if_needed(self):
         all_imports = list(self.file_import.get_imports_from_section(TypingSection.REGULAR)) + list(
             self.file_import.get_imports_from_section(TypingSection.TYPING)
@@ -106,6 +132,7 @@ def declare_definition(type_name: str, type_definition: TypeDefinition) -> list[
         return "\n".join(declarations)
 
     def __str__(self) -> str:
+        self._dedupe_typing_imports()
         self._add_type_checking_import()
         self._add_sys_import_if_needed()
         regular_imports = ""

packages/http-client-python/generator/pygen/codegen/serializers/types_serializer.py

@@ -243,6 +243,39 @@ def has_keyword_wire_names(model: ModelType) -> bool:
         """Whether any property wire_name is a Python keyword or requires functional TypedDict form."""
         return any(keyword.iskeyword(p.wire_name) or not p.wire_name.isidentifier() for p in model.properties)
 
+    @staticmethod
+    def needs_flat_typeddict(model: ModelType) -> bool:
+        """Whether a TypedDict must be emitted in flat (non-inheriting) form.
+
+        PEP 589 forbids changing an inherited TypedDict field's requiredness in a subclass. When a
+        child redeclares an inherited field with a different requiredness (e.g. the parent renders it
+        as optional via ``total=False`` while the child needs ``Required[...]``), subclassing would
+        emit an illegal ``Overwriting TypedDict field ... while extending`` construct. Such models are
+        instead rendered as a flat TypedDict that lists every field (inherited + own) directly.
+
+        Models with keyword wire_names already flatten all fields via the functional form, so they
+        never hit this path.
+        """
+        if TypesSerializer.has_keyword_wire_names(model):
+            return False
+        non_discriminated_parents = [p for p in model.parents if not p.discriminated_subtypes]
+        if not non_discriminated_parents:
+            return False
+        for parent in non_discriminated_parents:
+            for parent_prop in parent.properties:
+                child_prop = next(
+                    (p for p in model.properties if p.client_name == parent_prop.client_name),
+                    None,
+                )
+                if child_prop is None or child_prop is parent_prop:
+                    # Not overridden by the child (same object is reused when inherited unchanged).
+                    continue
+                parent_required = not (parent_prop.optional or parent_prop.client_default_value is not None)
+                child_required = not (child_prop.optional or child_prop.client_default_value is not None)
+                if parent_required != child_required:
+                    return True
+        return False
+
     def get_shadowed_builtins(self, model: ModelType) -> frozenset[str]:
         """Return the set of builtin type names shadowed by property wire_names in this model.
 
@@ -303,7 +336,11 @@ def imports(self) -> FileImport:
                 if self.get_shadowed_builtins(model):
                     needs_builtins = True
                 for parent in model.parents:
-                    if parent.client_namespace != model.client_namespace and not parent.discriminated_subtypes:
+                    if (
+                        parent.client_namespace != model.client_namespace
+                        and not parent.discriminated_subtypes
+                        and not self.needs_flat_typeddict(model)
+                    ):
                         # Import parent class from sibling namespace's types module
                         file_import.add_submodule_import(
                             self.code_model.get_relative_import_path(
@@ -329,7 +366,7 @@ def declare_model(self, model: ModelType) -> str:
         if self.has_keyword_wire_names(model):
             return ""  # functional form is rendered separately
         non_discriminated_parents = [p for p in model.parents if not p.discriminated_subtypes]
-        if non_discriminated_parents:
+        if non_discriminated_parents and not self.needs_flat_typeddict(model):
             basename = ", ".join([m.name for m in non_discriminated_parents])
             return f"class {model.name}({basename}):{model.pylint_disable()}"
         return f"class {model.name}(TypedDict, total=False):{model.pylint_disable()}"
@@ -362,7 +399,7 @@ def get_properties_to_declare(model: ModelType) -> list[Property]:
         if TypesSerializer.has_keyword_wire_names(model):
             return []  # functional form handles all properties
         non_discriminated_parents = [p for p in model.parents if not p.discriminated_subtypes]
-        if non_discriminated_parents:
+        if non_discriminated_parents and not TypesSerializer.needs_flat_typeddict(model):
             parent_properties = [p for bm in non_discriminated_parents for p in bm.properties]
             return [
                 p