[python] Fix named single-member union aliases

[Libba Lawrence (l0lawrence)]

Summary

• emit named unions as explicit TypeAlias declarations, including single-member unions
• preserve the named union annotation on concrete operation methods
• skip invalid lone overloads for one-member combined request bodies while retaining per-variant overloads for multi-member unions
• add focused regression coverage for single- and multi-member behavior

Validation

• npm run build
• npm run format
• npm run lint -- --generator
• npm run lint -- --emitter
• pnpm format
• focused unit tests: 21 passed

[pkg-pr-new]

Open in StackBlitz

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

commit: 2dde9ff

[github-actions]

All changed packages have been documented.

• ✅ @typespec/http-client-python

Show changes

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

Fix named single-member unions to emit valid Python type aliases without generating lone overloads.

[Copilot]

🔵 Needs a closer look

Regression coverage should exercise the full preprocessing path and assert distinct overload body types.

Pull request overview

Fixes Python generation for named single-member unions and avoids invalid lone overloads.

Changes:

• Emits named unions as explicit TypeAlias declarations.
• Preserves concrete method annotations and multi-member overloads.
• Adds regression tests and a changelog entry.

File summaries

File	Summary
packages/http-client-python/tests/unit/test_typeddict.py	Tests single- and multi-member union aliases.
packages/http-client-python/tests/unit/test_typeddict_overloads.py	Tests overload generation behavior.
packages/http-client-python/generator/pygen/preprocess/__init__.py	Skips lone overload generation.
packages/http-client-python/generator/pygen/codegen/templates/unions.py.jinja2	Emits explicit type aliases.
packages/http-client-python/generator/pygen/codegen/serializers/unions_serializer.py	Imports TypeAlias.
.chronus/changes/l0lawrence-single-union-aliases-2026-09-10-15-30-27.md	Records the bug fix.

Review details

Suppressed comments (3)

packages/http-client-python/generator/pygen/preprocess/init.py:102

• The new regression cases call add_overloads_for_body_param directly with hand-built YAML, so they never exercise the shipped PreProcessPlugin.update_operation path that invokes this branch or serialize the resulting concrete method. A failure in that integration could still leave the named body replaced or the method signature without "_unions.GenerateAgentRequest"; add a test through the real preprocessing/operation serialization entrypoint.

        and len(body_types) > 1
        and len(body_types) > len(yaml_data["overloads"])

packages/http-client-python/tests/unit/test_typeddict_overloads.py:109

• This regression test calls add_overloads_for_body_param directly, while the shipped path invokes it from PreProcessPlugin.update_operation after update_parameter and add_body_param_type (generator/pygen/preprocess/__init__.py:694-708). It therefore never verifies that the full preprocessing flow still renders the concrete operation with the named alias; add a test through that entry point (or the generator) and assert the emitted signature.

    add_overloads_for_body_param(yaml_data)

    assert yaml_data["overloads"] == []
    assert yaml_data["bodyParameter"]["type"] is named_union
    assert yaml_data["bodyParameter"]["type"]["name"] == "GenerateAgentRequest"

packages/http-client-python/tests/unit/test_typeddict_overloads.py:118

• Checking only the overload count does not enforce the stated per-variant behavior: a regression that appends two overloads for the same body member would still pass. Assert that the overload body types match the two distinct entries in the combined type.

    add_overloads_for_body_param(yaml_data)

    assert len(yaml_data["overloads"]) == 2

• Files reviewed: 6/6 changed files
• Comments generated: 0
• Review effort level: Lite

---

💡 Configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[azure-sdk-automation]

You can try these changes here

🛝 Playground	🌐 Website	🛝 VSCode Extension