fix(python): escape quotes in enum documentation

[RKS (rksharma-owg)]

Enum and enum member documentation containing triple quotes can terminate its generated Python docstring. For syntactically valid input, the formatter accepts the following documentation as class-body statements; trailing single quotes can also make member docstrings invalid Python.

Add a reusable docstring-wrapping macro that escapes quotes after the existing prose wrapping and backslash escaping, and use it for enum classes, members, and Literal[...] enum descriptions in TypedDict output. This preserves ordinary documentation.

Fixes #11881. Related to #10784; this change specifically covers quotes at the enum rendering boundary.

Validation:

• 18 template regression cases pass. Nine original cases failed against the base templates; five added Literal-enum cases fail against the previous PR head. Cases cover ordinary prose, embedded delimiters, statement-shaped documentation, trailing quotes, backslashes, and multiple paragraphs. The tests inspect the formatted Python AST and documentation contents, rather than relying only on formatting success.
• Package build and wheel creation pass.
• All 23 emitter tests pass.
• Python generator Pylint, TypeScript Oxlint, test formatting, changeset formatting, and git diff --check pass. Linters were invoked directly to work around local optional-dependency and path-with-spaces problems in the wrapper.
• Full SDK regeneration passes for both flavors: 124 Azure specs / 133 generation tasks and 65 unbranded specs / 73 generation tasks. Regeneration leaves the working tree clean.
• Earlier broader unit run (not repeated for this review update): 528 passed, 3 failed. Running the same suite against the base generator gives 516 passed and the same 3 failures (the difference is the 12 added tests). Existing failures are test_polymorphic_deserialization, test_enumeration_results_blobs_unwrapped, and test_models_mode_typeddict_does_not_write_empty_models_folder. The local test run uses --confcutdir=tests/unit to avoid starting the unrelated mock API server.
• The full generated-SDK CI matrix was not run locally; upstream CI status is tracked on the PR.

[azure-pipelines]

Azure Pipelines:
Successfully started running 1 pipeline(s).
1 pipeline(s) were filtered out due to trigger conditions.
There may be pipelines that require an authorized user to comment /azp run to run.

[Copilot]

🟡 Changes recommended

Enum descriptions rendered as Literal[...] in types.py.jinja2 still use unescaped wrap_string inside """...""", leaving the same triple-quote breakout risk in typeddict mode.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Pull request overview

Fixes a Python emitter correctness issue where enum/enum-member documentation containing """ can prematurely terminate generated docstrings, causing subsequent text to be treated as executable Python at import time.

Changes:

• Add a reusable wrap_docstring Jinja macro that escapes double quotes after existing wrapping/backslash escaping.
• Use wrap_docstring for enum class and enum member docstrings in enum.py.jinja2.
• Add regression tests that parse the formatted Python AST to ensure documentation stays within a string literal, plus a .chronus fix entry.

File summaries

File	Description
packages/http-client-python/tests/unit/test_enum_docstrings.py	Adds AST-based regressions ensuring enum docs remain string literals even with embedded """, backslashes, and trailing quotes.
packages/http-client-python/generator/pygen/codegen/templates/operation_tools.jinja2	Introduces wrap_docstring macro to escape quotes after wrapping.
packages/http-client-python/generator/pygen/codegen/templates/enum.py.jinja2	Switches enum and enum member docstring emission to the new wrap_docstring helper.
.chronus/changes/escape-python-enum-docstrings.md	Records a fix changeset for @typespec/http-client-python.

Review details

• Files reviewed: 4/4 changed files
• Comments generated: 1
• Review effort level: Lite

---

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

[RKS (rksharma-owg)]

Posted on behalf of RKS (@rksharma-owg) by OpenAI Codex.

Addressed the TypedDict/Literal enum path in b89dbca: types.py.jinja2 now uses wrap_docstring for literal enum descriptions. The AST regression suite covers all three enum documentation sites; 18 cases pass, and five of the added Literal cases failed on the previous PR head.

Package build/wheel creation, all 23 emitter tests, targeted Pylint/Black checks, and full Azure/unbranded SDK regeneration passed. Regeneration produced no generated-file changes. The focused Python tests use --confcutdir=tests/unit to avoid the unrelated mock-server startup fixture. The full generated-SDK CI matrix was not run locally.

[Copilot]

🟢 Approval recommended

The change is narrowly scoped to enum docstring rendering, includes a reusable helper, adds targeted regression tests that would fail on reversion, and includes an appropriate .chronus fix entry.

Review details

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