Skip to content

[Bug]: Python emitter changes raw XML byte streams to str and loses publishing-profile content after upgrade #12325

Closed

Description

@msyyc

Describe the bug

Regenerating azure-mgmt-web with a newer Python emitter changes the publishing-profile XML APIs from raw byte iterators to str, despite using the same TypeSpec source commit. This is a backward-compatibility regression and also introduces XML content loss: the new generated code deserializes the XML document as an XML string scalar rather than preserving the document.

Downstream PR: Azure/azure-sdk-for-python#49637

Affected methods on WebAppsOperations, in both sync and async clients:

  • list_publishing_profile_xml_with_secrets
  • list_publishing_profile_xml_with_secrets_slot

Version and source context

The downstream _metadata.json changes:

Component Before After
Azure Python wrapper (emitterVersion) 0.63.2 0.63.10
Python emitter (httpClientPythonVersion) ^0.34.1 0.39.0
REST API version 2025-05-01 2025-05-01
REST API specs commit 965041b72edd6a89003243f98e36c74ffbfc33c9 Same commit

The baseline records a version range, not an exact resolved Python emitter version. The published Python emitter 0.34.1 declares TCGC ~0.69.1 as a development dependency; 0.39.0 declares ~0.73.0. Published TCGC 0.69.1 and 0.73.0 sources were compared to establish the encoding metadata change below; the precise baseline generation dependency lock was not available in this investigation.

Pinned source:

Both operations use this response shape:

{
  @header("Content-Type")
  contentType: "application/xml";

  #suppress "@azure-tools/typespec-azure-core/known-encoding" "Temporary fix."
  @doc("Receipt body in COSE format")
  @bodyRoot
  @encode("bytes")
  body: bytes;
}

This is an existing legacy/custom encoding annotation with an explicit known-encoding suppression. Whether that annotation should also be revised is a separate question; upgrading the generator currently changes the established SDK contract and loses the response document.

Actual behavior

The downstream generated sync signature changes from:

def list_publishing_profile_xml_with_secrets(...) -> Iterator[bytes]:
    ...

to:

def list_publishing_profile_xml_with_secrets(...) -> str:
    ...

Async signatures similarly change from AsyncIterator[bytes] to str.

The implementation changes as well:

-_stream = kwargs.pop("stream", True)
+_stream = kwargs.pop("stream", False)

-deserialized = response.iter_bytes() if _decompress else response.iter_raw()
+if _stream:
+    deserialized = response.iter_bytes() if _decompress else response.iter_raw()
+else:
+    deserialized = _deserialize_xml(str, response.text())

The same change occurs in the slot operation and async implementations.

This is not merely a type-annotation change. _deserialize_xml parses the document into an XML element, and string deserialization returns element.text or "". For a representative publishing-profile-shaped document:

<publishData><publishProfile profileName="example" publishMethod="MSDeploy" /></publishData>

the new non-streaming path returns "", not the XML document. With pretty-printed XML it can return only the root's leading whitespace. Nested elements and attributes are not preserved in either case.

Root-cause trace

  1. TypeSpec's @encode("bytes") uses string as the default encodedAs type when the second argument is omitted. See compiler encoding resolution.
  2. Azure/typespec-azure#5146, released in TCGC 0.71.0, started exposing wireType for encoded bytes, integers, and booleans. In the published old TCGC bytes path, this property was absent; in the newer path it is populated from encodeData.type.
  3. The Python emitter's supported encodings and fallback preserve bytes for base64 and base64url, but do not recognize "bytes" as a supported bytes encoding. Consequently, the newly available string wireType activates the generic unsupported/custom-encoding fallback.
  4. The emitted response type therefore becomes string rather than bytes. The Python generator no longer selects the binary-stream response path, defaults to non-streaming, and generates XML scalar deserialization.

Related fix #11637 intentionally preserved Python client-facing types for supported encodings after TCGC began providing wireType. It covered boolean/integer string encodings and bytes base64/base64url encodings, but did not cover this raw-bytes response case. This issue is not caused by the JSONL/SSE structured-streaming feature.

Focused reproduction and evidence

Executing the current emitBuiltInType implementation with the relevant SDK type metadata produces:

Input:
{ kind: "bytes", encode: "bytes" }
Output:
{ type: "bytes", encode: "bytes" }

Input:
{ kind: "bytes", encode: "bytes", wireType: { kind: "string" } }
Output:
{ type: "string", encode: "bytes" }

Control input:
{ kind: "bytes", encode: "base64", wireType: { kind: "string" } }
Output:
{ type: "bytes", encode: "base64" }

Separately, executing the actual _deserialize_with_callable implementation on str and the parsed example XML element returns "". The exact downstream PR head's model_base.py has the same string-element behavior.

These were focused source-level executions, supported by inspection of the exact downstream base/head generated code and published old/new TCGC sources. A complete SDK regeneration or live App Service request was not performed.

Expected behavior

Preserve the existing raw-byte response contract for these operations:

  • Sync methods return Iterator[bytes].
  • Async methods return AsyncIterator[bytes].
  • Default behavior streams the unmodified response body rather than interpreting the document as an XML scalar.
  • The complete publishing-profile XML, including child elements and attributes, remains available.

The generic fallback for genuinely unsupported/custom encodings is intentional and should not be removed indiscriminately. The raw-bytes compatibility case needs targeted handling, with a spec-side adjustment considered if necessary.

Suggested regression coverage:

  • Emitter coverage for raw bytes with the newly populated wireType.
  • Generated sync/async signatures and default streaming behavior for application/xml raw-byte responses.
  • A representative publishing-profile XML response demonstrating that the document is preserved.
  • Existing supported-encoding and genuinely custom-encoding fallback behavior remains unchanged.

Separate API diff noise

The downstream PR also changes many types.py docstrings from Python-style names to wire names. For example, the baseline AllowedAudiencesValidation already declares allowedAudiences, but its docstring incorrectly documented allowed_audiences. The apparent removal of that snake-case field in api.md is a documentation correction, not an actual field declaration removal. This should be distinguished from the real publishing-profile return-type/runtime regression above.

Activity

  1. github-actions commented on Oct 21, 2026

    @github-actions
    Contributor

    🎯 Issue Triage

    Upgrading the Python emitter changes @encode("bytes") XML responses from raw byte streams to str, causing both an SDK contract regression and loss of nested XML content. The report identifies the wireType-driven fallback in emitBuiltInType and includes focused source-level evidence.

    Category: Bug

    Area: emitter:client:python

    🔗 [Playground Reproduction]((typespec.io/redacted)

    📋 Reproduction code
    {
      @header("Content-Type")
      contentType: "application/xml";
    
      #suppress "@azure-tools/typespec-azure-core/known-encoding" "Temporary fix."
      @doc("Receipt body in COSE format")
      @bodyRoot
      @encode("bytes")
      body: bytes;
    }
    🔍 Analysis

    TCGC now supplies a string wireType for the raw-bytes encoding. The Python emitter does not recognize "bytes" alongside its supported base64/base64url cases, so its generic custom-encoding fallback changes the client type to str. That disables default streaming and routes the response through XML scalar deserialization, which returns only root text rather than preserving the document, attributes, and child elements. This affects synchronous and asynchronous WebAppsOperations publishing-profile methods. #9503 is related to XML/bytes representation but tracks different OpenAPI emitter behavior and is not a duplicate. #12326 is already open with a targeted fix.

    📝 Suggested next steps
    • Add raw-bytes coverage with a populated string wireType.
    • Verify generated sync and async signatures retain byte iterators and default streaming.
    • Add an XML response test proving attributes and nested content are preserved.
    • Keep genuinely unsupported custom-encoding fallback behavior unchanged.

    Generated by Agentic Triage

  2. added a commit that references this issue on Oct 22, 2026
    c114161
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Labels

bugSomething isn't workingemitter:client:pythonIssue for the Python client emitter: @typespec/http-client-python

Type

No type

Projects

No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions