Python emitter: generated docstrings can contain invalid Python escape sequences (e.g. \W) causing SyntaxWarning on 3.12+

[msyyc]

Bug

The TypeSpec Python emitter (@azure-tools/typespec-python / @typespec/http-client-python) writes model/property doc strings verbatim into the generated Python source as the body of a docstring. When the original @doc(...) contains a backslash followed by a character that is not a recognized Python string escape (e.g. \W, \d, \s, etc.), the resulting Python source triggers:

SyntaxWarning: invalid escape sequence ''\W''

on Python 3.12+ (this will become a SyntaxError in a future Python version).

Repro

TypeSpec source (excerpt) — specification/compute/resource-manager/Microsoft.Compute/Compute/Compute/models.tsp in Azure/azure-rest-api-specs:

model OSProfile {
  @doc("Specifies the password ... Has a special character (Regex match [\\W_]) ...")
  @secret
  adminPassword?: string;
}

The TypeSpec string value here is the literal ... (Regex match [\W_]) ... (one backslash + W), which is correct for the swagger/REST description.

The generated Python (azure-mgmt-compute==38.0.0, azure/mgmt/compute/models/_models.py) contains:

class OSProfile(_Model):
    """...
    :ivar admin_password: ... Has a special character (Regex match [\W_]) ...
    ...
    """

Importing the module on Python 3.12 produces (issue Azure/azure-sdk-for-python#47011):

SyntaxWarning: invalid escape sequence ''\W''
  <br>Has upper characters <br> Has a digit <br> Has a special character (Regex match [\W_])

Expected

When emitting a Python docstring, the Python emitter should ensure the resulting Python string literal is valid — either by:

1. Writing the docstring as a raw string (r"""..."""), or
2. Escaping every backslash in the doc text (\ → \\) before writing it into the Python source.

This should be done unconditionally for all generated docstrings (class docstrings, attribute :ivar/:vartype/:keyword lines, operation parameter docs, etc.), because users cannot reasonably be expected to pre-escape every @doc in TypeSpec just for the Python emitter — and doing so would corrupt the REST API description / other-language SDKs.

Current workaround

Use @@clientDoc(..., DocumentationMode.replace, "python") in client.tsp to override the Python doc text with manually double-escaped backslashes. Example PR: Azure/azure-rest-api-specs#43481

This is fragile — it requires every service team to discover the warning, then duplicate and hand-escape long doc strings just for Python.

Environment

• Affected package: azure-mgmt-compute==38.0.0 (generated)
• Python: 3.12+
• Original issue: Syntax warnings when using azure-mgmt-compute in Python 3.12 Azure/azure-sdk-for-python#47011

[github-actions]

🎯 Issue Triage

The Python emitter writes @doc(...) strings verbatim into generated docstrings, causing SyntaxWarning: invalid escape sequence on Python 3.12+ when the doc text contains backslashes (e.g., regex patterns like [\W_]). This will become a SyntaxError in a future Python version.

Category: Bug
Area: emitter:client:python

📋 Reproduction code

model OSProfile {
  `@doc`("Specifies the password ... Has a special character (Regex match [\\W_]) ...")
  `@secret`
  adminPassword?: string;
}

🔍 Analysis

• Root cause: The emitter copies doc text directly into Python triple-quoted string literals without escaping backslashes. Python interprets \W, \d, \s, etc. as escape sequences; unrecognized ones produce SyntaxWarning in 3.12 and will become SyntaxError in a future release.
• Fix options: (1) escape all backslashes (\ → \\) in doc text before emitting, or (2) emit docstrings as raw strings (r"""..."""). Option 1 is simpler and more compatible since raw strings have their own edge cases (can't end with odd number of backslashes).
• Scope: Affects class docstrings, :ivar/:vartype/:keyword lines, and operation parameter docs — anywhere doc text is inserted verbatim.
• Upstream reference: Azure/azure-sdk-for-python#47011
• Current workaround (@@clientDoc`` with DocumentationMode.replace) is fragile and requires every service team to manually double-escape backslashes.

📝 Suggested next steps

• In the Python emitter's docstring-generation code, escape all backslash characters in doc text before inserting into the generated Python source.
• Add a test case with a @doc containing a regex-style backslash sequence to prevent regression.

Generated by Agentic Triage