fix(http-client-python): escape leading @ in docstring field targets - #11622
Open
Libba Lawrence (l0lawrence) wants to merge 2 commits into
Open
fix(http-client-python): escape leading @ in docstring field targets#11622Libba Lawrence (l0lawrence) wants to merge 2 commits into
@ in docstring field targets#11622Libba Lawrence (l0lawrence) wants to merge 2 commits into
Conversation
Wire names such as @search.facets are emitted as the target of Sphinx info fields (:ivar/:vartype/:keyword/:paramtype/:param/:type). A leading @ is interpreted by Sphinx and breaks the rendered docstring, so escape it via a shared escape_sphinx_field_name helper applied across model, TypedDict, operation, and client docstring generation. The raw @ is preserved everywhere else (e.g. TypedDict keys, wire names). Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: 4b38539c-8877-4fdc-8b9d-bc400a50d325
Libba Lawrence (l0lawrence)
requested review from
ChenxiJiang333,
catalinaperalta,
iscai-msft,
Kashif Khan (kashifkhan),
Laurent Mazuel (lmazuel),
Mark Cowlishaw (markcowl),
Yuchao Yan (msyyc),
Chenjie Shi (tadelesh),
Timothee Guerin (timotheeguerin) and
Jeff Fisher (xirzec)
as code owners
August 11, 2026 21:09
microsoft-github-policy-service
Bot
added
the
emitter:client:python
commit: |
Contributor
|
All changed packages have been documented.
Show changes
|
… fields A leading @ in a Sphinx info-field target is fine in stock autodoc, but escaping it as \@ (the previous approach) emits an invalid Python escape sequence into the generated SDK (SyntaxWarning / SyntaxError under -W error). Instead wrap names containing @ in double backticks (inline literal), which renders correctly across :ivar/:vartype/:keyword/:paramtype/:param/:type with no backslash and no invalid escape. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: 4b38539c-8877-4fdc-8b9d-bc400a50d325
|
You can try these changes here
|
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Problem
When a property/parameter wire name starts with
@(e.g.@search.facets), the generated Python docstrings emit it directly as the target of a Sphinx info field:Sphinx/docutils interprets the leading
@, which breaks the rendered docstring.Fix
Added a shared helper
escape_sphinx_field_name(inmodels/utils.py) that escapes@→\@, and applied it at every site that emits a name as a docstring info-field target:model_serializer._documentation_string(:ivar/:vartype,:keyword/:paramtype)builder_serializer.param_description(:param/:type,:keyword/:paramtype)client_serializer.property_descriptions(client:ivaroperation groups, client-level params, and config params)Scope note
The escaping is applied only where the name lands inside a docstring, because
\@is an RST/Sphinx escape — not a Python one. The raw@is preserved everywhere else (TypedDict keys,rest_field(name=...), wire serialization), where it's the correct on-the-wire value. In practice@only ever reaches a docstring via the TypedDict types file (the only path that renders the rawwire_name); the other call sites use the sanitizedclient_nameand are covered defensively / future-proofed.Tests
Added
test_models_mode_typeddict_docstring_escapes_at_sign, which asserts both that the docstring field target is escaped (:vartype \@search.facets:) and that the generated TypedDict key keeps the raw"@search.facets":.