[python] add typeddict `models-mode` for Python HTTP client emitter by iscai-msft · Pull Request #10439 · microsoft/typespec

iscai-msft · 2026-04-21T17:46:09Z

Add a new 'typeddict' value for the models-mode option that generates Python TypedDict classes instead of DPG model classes. Key features:

TypedDict classes with Required[T]/NotRequired[T] annotations
TypedDict inheritance for non-discriminated models
Discriminated models: Union of leaf TypedDicts, no abstract base class
Input-only: operations accept TypedDict input, return dict output
Wire names used as TypedDict keys
_model_base.py still generated for serialization utilities

Add a new 'typeddict' value for the models-mode option that generates Python TypedDict classes instead of DPG model classes. Key features: - TypedDict classes with Required[T]/NotRequired[T] annotations - TypedDict inheritance for non-discriminated models - Discriminated models: Union of leaf TypedDicts, no abstract base class - Input-only: operations accept TypedDict input, return dict output - Wire names used as TypedDict keys - _model_base.py still generated for serialization utilities Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

pkg-pr-new · 2026-04-21T17:48:01Z

Open in StackBlitz

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

commit: 7f2ffd5

github-actions · 2026-04-21T17:49:06Z

All changed packages have been documented.

✅ @typespec/http-client-python

Show changes

`@typespec/http-client-python` - feature ✏️

[python] Always generate TypedDict typing hints for input models in the types.py file, and named union aliases in the _unions.py file

azure-sdk · 2026-04-21T18:00:13Z

You can try these changes here

🛝 Playground	🌐 Website	🛝 VSCode Extension

…ypespec into python/addTypedDict

…hon/addTypedDict

- TypedDictModelType returns 'JSON' for response type annotations - Response.type_annotation/docstring passes is_response=True - Typeddict deserialization uses response.json() directly - Removed NotRequired from TypedDictModelSerializer (total=False handles it) - Updated mock API tests to verify JSON dict responses Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

- Add client/naming typeddict variant to regenerate-common.ts - Create test_client_naming_typeddict.py with 11 tests verifying TypedDict uses wire names (defaultName, wireName) not client names - Tests cover: ClientNameModel, LanguageClientNameModel, ClientNameAndJsonEncodedNameModel, ClientModel, PythonModel Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

TypedDict is already JSON, so the MutableMapping[str, Any] overload is unnecessary. Only keep TypedDict model + IO[bytes] overloads. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Typeddict mode uses response.json() directly, so _deserialize is never called. Skip importing it to avoid W0611 unused-import lint warning. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

- Remove unused MutableMapping/Any imports from TypedDictModelType.imports() - Skip _deserialize import in paging_operation.py for typeddict mode Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

…ypespec into python/addTypedDict

TypedDictModelType returns 'JSON' for response type annotations but never defined the JSON = MutableMapping[str, Any] type alias, causing NameError at runtime. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

…ypespec into python/addTypedDict

…hon/addTypedDict

…of literals instead of enums when td only

- Fix cross-namespace parent imports in types.py to import from types module - Add isidentifier() check for wire names (not just iskeyword) for functional TypedDict form - Use __doc__ assignment for functional-form TypedDict docstrings - Add missing op_tools import in model_typeddict.py.jinja2 - Fix test docstring to match actual behavior - Update changelog entry with correct file names (types.py, _unions.py) Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

- Fix cross-namespace parent imports in types_serializer.py and model_type.py to use get_relative_import_path with module_name parameter instead of naive string concatenation - Remove unused model_typeddict.py.jinja2 template (dead code) - Fix misleading test name: rename test_models_mode_dpg_no_typeddict_models to test_models_mode_dpg_typeddict_models_included Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

iscai-msft · 2026-06-01T16:53:47Z

        : property.serializationOptions?.json?.name) ?? property.name,
    type: getType(context, sourceType),
    optional: property.optional,
+    nullable: isNullable,


we are conflating nullable and optional. this is one step to help with the conflation, since it's extra important in typeddicts to not type things as optional when we mean nullable

Revert to the original no-sdk-clients check without tying the exemption to models-mode=typeddict. Models-only generation should not be gated on a specific models-mode. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

iscai-msft · 2026-06-01T17:06:30Z

    def type_annotation(self, **kwargs: Any) -> str:
        if self.name:
-            return f'"_types.{self.name}"'
+            return f'"_unions.{self.name}"'


moved the existing union types to a unions.py file, keeping types.py purely for typeddict generation. So now, really instead of using JSON, we will be able to use the typeddict representations instead for those overloads. If we want to as well, we can not generate models and only generate typeddicts as well

iscai-msft · 2026-06-01T17:07:10Z

        """
        if self.code_model.options["models-mode"]:
+            if self.is_typeddict_mode:
+                # In typeddict mode, enums are Literal aliases defined in types.py


chatted with @johanste and in TD only mode, we don't want to generate enums as enum types, but instead as unions of literals. @johanste is this something we want to do everywhere?

iscai-msft · 2026-06-01T17:07:45Z

        self.cross_language_definition_id: Optional[str] = self.yaml_data.get("crossLanguageDefinitionId")
        self.usage: int = self.yaml_data.get("usage", UsageFlags.Input.value | UsageFlags.Output.value)
        self.client_namespace: str = self.yaml_data.get("clientNamespace", code_model.namespace)
+        self.is_typed_dict_only: bool = (


we want to be able to flag individual models as typeddict only as well. we will need to add a decorator in tcgc in order to support this

@overload

Replace the JSON (MutableMapping) overload with a TypedDict reference from types.py for model input parameters. This gives users proper type-checking and IDE completion when passing dict literals. Changes: - preprocess: insert TypedDict model reference instead of any-object for both model and list/dict body params with DPG model elements - TypedDictModelType: add type_annotation, imports, docstring_type, and instance_check_template overrides - build_type: handle base='typeddict' to create TypedDictModelType - code_model: exclude typeddict refs from model_types (annotation-only) Generated operations now show: @overload def op(body: _models.X, ...) -> ... @overload def op(body: types.X, ...) -> ... @overload def op(body: IO[bytes], ...) -> ... JSON overloads are preserved for spread bodies (base=json) where no model class exists. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

This file is shared with typespec-python via pnpm sync and should not be deleted. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

msyyc · 2026-06-04T08:35:20Z

I invoked workflow to generate code diff for this PR: Azure/azure-sdk-for-python#47346 for better review.

When multiple namespaces import 'types', the second import shadows the first causing mypy errors ('Name types already defined') and runtime failures ('Name types.X is not defined'). Add get_unique_types_alias() (mirrors get_unique_models_alias) to generate unique aliases like _types, _types_models1, _types_models2. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

…ypespec into python/addTypedDict

In types.py (TypedDict definitions), use the JSON wire type instead of rich Python types for properties: - datetime.datetime → str - datetime.date → str - datetime.time → str - datetime.timedelta → str - datetime.datetime (unix) → int - decimal.Decimal → float - bytes → str This follows the principle that TypedDicts represent the wire/JSON shape of the data. Rich types like datetime are still used in model classes and operation signatures. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

iscai-msft requested review from ChenxiJiang333, catalinaperalta, laiapat, lmazuel, msyyc, swathipil, tadelesh and timotheeguerin as code owners April 21, 2026 17:46

microsoft-github-policy-service Bot added the emitter:client:python Issue for the Python client emitter: @typespec/http-client-python label Apr 21, 2026

Enhance Python HTTP client emitter with TypedDict support

27c8bfb

iscai-msft and others added 12 commits April 21, 2026 14:37

add discriminator

c1487f8

Merge branch 'python/addTypedDict' of https://github.com/iscai-msft/t…

02e6f35

…ypespec into python/addTypedDict

Merge branch 'main' of https://github.com/microsoft/typespec into pyt…

2647828

…hon/addTypedDict

fix: remove redundant JSON overload for typeddict mode

3e5c0ef

TypedDict is already JSON, so the MutableMapping[str, Any] overload is unnecessary. Only keep TypedDict model + IO[bytes] overloads. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

fix: remove unused _deserialize import in typeddict mode

f76c88d

Typeddict mode uses response.json() directly, so _deserialize is never called. Skip importing it to avoid W0611 unused-import lint warning. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

fix: remove all unused imports in typeddict generated code

2401b66

- Remove unused MutableMapping/Any imports from TypedDictModelType.imports() - Skip _deserialize import in paging_operation.py for typeddict mode Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Merge branch 'main' into python/addTypedDict

57bf76a

format and lint

47b5024

Merge branch 'python/addTypedDict' of https://github.com/iscai-msft/t…

87ea0a1

…ypespec into python/addTypedDict

fix: define JSON type alias in TypedDictModelType imports

95db199

TypedDictModelType returns 'JSON' for response type annotations but never defined the JSON = MutableMapping[str, Any] type alias, causing NameError at runtime. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

iscai-msft force-pushed the python/addTypedDict branch from 34e0cda to 95db199 Compare April 29, 2026 15:39

iscai-msft added 3 commits May 5, 2026 15:58

switch to always generating typeddicts as typing hints

37806df

switch to always generating typeddicts as typing hints

18786e3

Merge branch 'python/addTypedDict' of https://github.com/iscai-msft/t…

8d323ac

…ypespec into python/addTypedDict

iscai-msft and others added 7 commits May 26, 2026 13:51

Merge branch 'main' of https://github.com/microsoft/typespec into pyt…

bd83e9f

…hon/addTypedDict

switch to models-mode=typeddict to represent td only, generate union …

6c0ee44

…of literals instead of enums when td only

don't conflate optional and nullable

6d75f07

format and lint

27113ce

lint

a88d471

Merge branch 'main' into python/addTypedDict

d9341d0

iscai-msft requested a review from l0lawrence as a code owner June 1, 2026 16:26

iscai-msft commented Jun 1, 2026

View reviewed changes

msyyc reviewed Jun 2, 2026

View reviewed changes

Comment thread packages/http-client-python/eng/scripts/ci/regenerate-common.ts

msyyc requested changes Jun 2, 2026

View reviewed changes

msyyc reviewed Jun 2, 2026

View reviewed changes

Comment thread packages/http-client-python/emitter/src/types.ts

iscai-msft and others added 4 commits June 2, 2026 13:48

Merge remote-tracking branch 'upstream/main' into python/addTypedDict

a99065d

fix: restore regenerate-common.ts

3cea12c

This file is shared with typespec-python via pnpm sync and should not be deleted. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Merge branch 'main' into python/addTypedDict

94f613b

github-actions Bot mentioned this pull request Jun 4, 2026

[typespec-python] Regenerate tests from microsoft/typespec PR #10439 Azure/azure-sdk-for-python#47344

Open

msyyc mentioned this pull request Jun 4, 2026

[typespec-python] Regenerate tests from microsoft/typespec PR #10439 (DO NOT MERGE) Azure/azure-sdk-for-python#47346

Draft

iscai-msft and others added 2 commits June 4, 2026 15:19

Merge branch 'python/addTypedDict' of https://github.com/iscai-msft/t…

4c0a3ac

…ypespec into python/addTypedDict

iscai-msft force-pushed the python/addTypedDict branch from d6eb5ab to 4c0a3ac Compare June 4, 2026 20:09

iscai-msft requested review from johanste and msyyc June 5, 2026 20:26

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

[python] add typeddict `models-mode` for Python HTTP client emitter#10439

[python] add typeddict `models-mode` for Python HTTP client emitter#10439
iscai-msft wants to merge 58 commits into
microsoft:mainfrom
iscai-msft:python/addTypedDict

iscai-msft commented Apr 21, 2026 •

edited

Loading

Uh oh!

pkg-pr-new Bot commented Apr 21, 2026 •

edited

Loading

Uh oh!

github-actions Bot commented Apr 21, 2026 •

edited

Loading

`@typespec/http-client-python` - feature ✏️

Uh oh!

azure-sdk commented Apr 21, 2026 •

edited by azure-sdk-automation Bot

Loading

Uh oh!

iscai-msft Jun 1, 2026

Uh oh!

iscai-msft Jun 1, 2026

Uh oh!

iscai-msft Jun 1, 2026

Uh oh!

iscai-msft Jun 1, 2026

Uh oh!

Uh oh!

Uh oh!

msyyc commented Jun 4, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

Conversation

iscai-msft commented Apr 21, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

pkg-pr-new Bot commented Apr 21, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

github-actions Bot commented Apr 21, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

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

Uh oh!

azure-sdk commented Apr 21, 2026 • edited by azure-sdk-automation Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

iscai-msft Jun 1, 2026

Choose a reason for hiding this comment

Uh oh!

iscai-msft Jun 1, 2026

Choose a reason for hiding this comment

Uh oh!

iscai-msft Jun 1, 2026

Choose a reason for hiding this comment

Uh oh!

iscai-msft Jun 1, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

msyyc commented Jun 4, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

iscai-msft commented Apr 21, 2026 •

edited

Loading

pkg-pr-new Bot commented Apr 21, 2026 •

edited

Loading

github-actions Bot commented Apr 21, 2026 •

edited

Loading

`@typespec/http-client-python` - feature ✏️

azure-sdk commented Apr 21, 2026 •

edited by azure-sdk-automation Bot

Loading