Repository navigation
network-watcher packet-capture create: unescaped C:\Captures\... in docstring emits SyntaxWarning on first run and corrupts the help example #34136
Description
Activity
Thank you for opening this issue, we will look into it.
Reacted by beenet-bytesBug analysis
Hi beenet-bytes, the report contains enough evidence to proceed: an exact failing command, actual stderr/help output, expected behavior, and a reproducible version/context. No additional requirements are needed.
Command, reproduction, and impact
- Affected command:
az network network-watcher packet-capture create; the non-resource reproduction isaz network network-watcher packet-capture create --help. - Reported environment: Azure CLI/core 2.90.0, bundled Python 3.14.7, Homebrew on macOS 26.6.2 arm64. These version details are reporter-provided, not independently runtime-verified here.
- The report distinguishes a first-compilation invalid-escape
SyntaxWarningfrom help-example corruption on every run. A cached.pyccan hide the warning on retry, so cold/warm help alone is not a sufficient regression check. The supplied cache-independent reproduction makes this a well-specified report. - Expected result: no invalid-escape warning and a help example that preserves the Windows path separators and the full
testByCli.capfilename. This is a client-side help/compilation defect; the report does not demonstrate a packet-capture service failure. Stderr-combining callers can be affected on the first invocation.
Source-confirmed root cause and scope
Read-only inspection of current
devconfirms thatnetwork/.../packet_capture/_create.pyregisters this exact command and uses a normal triple-quotedCreatedocstring. Its line 21 contains"filePath": "C:\Captures\testByCli.cap"with single source backslashes. Python treats\Cas an invalid escape and interprets\trather than preserving those two literal characters. This is sufficient to explain both the warning and loss of the intended path in the example; it is not an SDK-owned azure-batch warning.The file is explicitly generated by aaz-dev-tools.
_aaz_infoidentifies API version2024-05-01and resource/subscriptions/{}/resourcegroups/{}/providers/microsoft.network/networkwatchers/{}/packetcaptures/{}. The inspected source blob iscd2a654258b47ee58c991353f413162c7245ba35._parse_cls_doctakes command help/examples fromcls.__doc__, after Python has already interpreted its escapes. Exact later whitespace rendering was not independently executed. No tests, issue-provided scripts, Azure resource operations, or implementation changes were run during this triage.The durable AAZ example and the reporter's upstream generator/history claims have not been independently verified. The confirmed defect is in the checked-in generated Python; this is not evidence by itself that the current generator or REST specification is defective.
Suggested fix for the implementation job
- Inspect the corresponding durable
Azure/aazcommand model/example and the current aaz-dev-tools rendering of that example using the command and_aaz_infoabove. Correct the durable example only if its encoding is wrong; do not double-escape an already-correct model or change the REST API specification without evidence. - Regenerate the existing
networkmodule with the supported generator so normal Python docstrings correctly escape literal backslashes. Preserve the intended Windows path and separately validate the JSON/shorthand serialization of--storage-location; Python-literal escaping and CLI argument encoding are different layers. If the current generator still emits invalid Python escapes, isolate and fix the responsible rendering path rather than hand-patching generated output. - Do not directly edit
aaz/latest/.../_create.py, suppress warnings, or broadly alter help parsing. Follow the mandatory source/codegen workflow below, review the full generated diff, and retain the command/API version, argument schema, and request behavior. Check for an existing equivalent fix before making implementation changes.
Focused regression and scenario coverage
- Use the existing network unittest structure in
test_network_unit_tests.py. Add a source-based, in-memory compilation check for this generated module with invalid-escape warnings treated as errors (SyntaxWarningon Python 3.12+; coverDeprecationWarningwhere applicable). Do not let an existing.pycbypass the check. - Check the command docstring and parsed example: both Windows path separators and the complete
testByCli.capfilename must survive, with no escape-induced control character or whitespace substitution. Validate the example's--storage-locationpath value without invoking the create operation. - Exercise the offline
--helpscenario, capture stdout and stderr separately, and verify warning-free cold/warm behavior and an intact example. Use the repository's existing test framework; no live Azure resources are required for this regression. - Verify regeneration is reproducible and introduces no unintended command/schema/operation changes. The implementation job, not this triage process, performs the focused validation required below.
Mandatory Codegen execution protocol
Before editing implementation files, determine whether the affected
networkcommand is AAZ-generated. Files underaaz/<profile>/are generated output and must never be patched directly, including by an AI agent. Check outAzure/aazbesideAzure/azure-rest-api-specs,Azure/aaz-dev-tools, and the downstream repository. API-schema defects start in the specification; command naming, grouping, arguments, API-version selection, help, and examples belong in the durableAzure/aazcommand model; non-modelable client behavior belongs in a handwritten subclass or wrapper incustom.py, registered fromcommands.py. X Engineering Agent creates and promotes the corresponding durableAzure/aazsource pull request before it promotes downstream generated output.Follow the Azure CLI repository's Codegen workflow and the aaz-dev setup documentation. Set up the checked-out repositories with
azdev setup. Usegenerateonly when importing or redesigning command models from Swagger/TypeSpec. For an existing module whose durableAzure/aazmodel has been updated, render that model withregenerate:aaz-dev cli regenerate --name network --cli-path <azure-cli> # New/imported command model only: aaz-dev cli generate --spec <specification-name> --module network
You MUST actually run the generator; do not merely describe it or imitate its output. If the AAZ/specification checkout, local source change, credentials, or generator is unavailable, stop and report the blocker instead of editing generated files. Inspect
_aaz_infoprovenance and the complete regenerated diff, then run focusedazdev style,azdev linter, andazdev testvalidation. For an extension, also update its version andHISTORY.rst, preserveazext_metadata.jsoncompatibility, and let release automation updatesrc/index.json.PR title & description format (required)
This repo enforces a PR format (guide). Please author the PR exactly as follows or CI's Check the Format of Pull Request Title and Content will fail.
Use this EXACT PR title (copy verbatim, do not reword):
[Network] Fix #34136: `az network network-watcher packet-capture create`: Escape Windows path backslashes in the help exampleKeep the backticks around the command and the
Fix #34136:prefix. You may only adjust the wording after the command (the final summary) if the fix changes; the[Network]prefix, issue link, and backticked command must stay.Description — follow the PR template and fill in:
- Link the issue — start the Description with a closing keyword so the PR auto-links and closes it:
Fixes #34136. - Related command — the
az ...command this affects. - Description (mandatory) — why the bug happens, what you changed, and the resulting behavior.
- Testing Guide — example command(s) showing the fix works.
- History Notes — leave the title to drive the history note, or add extra lines in the same format (component in brackets + the command in backticks), e.g.
[Network] `az <command>`: <note>. - Keep the template checklist and tick the items you've satisfied.
- Affected command:
Implementation Result
No pull request was opened because the implementation run completed without a validated code change.
The source analysis remains available above. A maintainer should confirm whether the issue is already resolved on the current target branch or provide the reproduction or root-cause evidence needed for another implementation request.
microsoft-github-policy-service commented
on Sep 28, 2026 Contributor🔔 Routing this issue to @Azure/act-quality-productivity-squad.
microsoft-github-policy-service commented
on Sep 28, 2026 ContributorThanks for the feedback! We are routing this to the appropriate team for follow-up. cc aznetsuppgithub, @Azure/act-quality-productivity-squad.
Describe the bug
src/azure-cli/azure/cli/command_modules/network/aaz/latest/network/network_watcher/packet_capture/_create.py, line 21, has a Windows path inside the class docstring, which is a normal (non-raw) string:That has two effects:
\Cis an invalid escape sequence. Python has warned on invalid escapes by default since 3.12; on the 3.14.7 build tested here, the first import of the module (before its.pycis cached) prints aSyntaxWarningto stderr.\tis a valid escape, so it's consumed too: the example in--helpends up with blank space where\twas written, not the literal characters:"C:\Captures estByCli.cap".The line is unchanged on
dev. The file's last commit is #31624 (2025-06-18), well after aaz-dev-tools started escaping backslashes in generated docstrings (Azure/aaz-dev-tools#360, merged 2024-05-20). I don't know whether #31624 regenerated this file or just touched something else in it, so I can't say whether the fix belongs here, in the example source in Azure/aaz, or both.This isn't the
azure-batchSDK warning tracked in #31789 / #32495. That one is in a different package; this file is owned by azure-cli.Related command
az network network-watcher packet-capture createErrors
First run after install (no
__pycache__yet for that package):The second run prints nothing, because the
.pycis cached by then.Help output (every run):
Issue script & Debug output
This reproduces without relying on cache state, by compiling the file in memory with az's own interpreter:
Output: the same
SyntaxWarningas above.And where the
\tescape ends up:Expected behavior
No warning on stderr, and the help example shows
C:\Captures\testByCli.cap. Escaping the backslashes (C:\\Captures\\testByCli.cap) fixes both.Environment Summary
Additional context
The warning only fires on the very first import, before the
.pycis cached (confirmed above). That's an easy trap for anything that merges stderr into parsed output (2>&1): it fails once, then passes silently on retry. ASyntaxWarningshouldn't be on stderr to begin with.