Add rule: configure Python client with kwargs, not ConnectionPolicy#225
Open
yumnahussain wants to merge 1 commit into
Open
Add rule: configure Python client with kwargs, not ConnectionPolicy#225yumnahussain wants to merge 1 commit into
yumnahussain wants to merge 1 commit into
Conversation
New skill rule sdk-python-client-kwargs. In the azure-cosmos v4 SDK all CosmosClient configuration is passed as keyword arguments to the constructor; the client maps them onto a ConnectionPolicy internally via _build_connection_policy(). Hand-building a documents.ConnectionPolicy and mutating its attributes (e.g. policy.RequestTimeout = 10000) is a legacy v3/pydocumentdb carry-over and steers toward deprecated config knobs (retry_options, connection_retry_policy). The rule documents the kwargs surface with Incorrect/Correct examples and notes SSLConfiguration/ProxyConfiguration remain the required objects for those specific settings. Regenerated AGENTS.md (npm run build). Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
yumnahussain
requested review from
TheovanKraay,
jaydestro and
sajeetharan
as code owners
July 14, 2026 19:45
yumnahussain
added a commit
to yumnahussain/cosmosdb-agent-kit
that referenced
this pull request
Jul 14, 2026
The new skill rule and its AGENTS.md regeneration now live in a separate PR (AzureCosmosDB#225). This PR keeps only the verifier test TestClientConfigViaKwargs in check_source.py, which cites the rule id. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
yumnahussain
added a commit
to yumnahussain/cosmosdb-agent-kit
that referenced
this pull request
Jul 14, 2026
The new skill rule and its AGENTS.md regeneration now live in a separate PR (AzureCosmosDB#225). This PR keeps only the verifier test TestClientConfigViaKwargs in check_source.py, which cites the rule id. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Contributor
There was a problem hiding this comment.
Pull request overview
Adds a new Cosmos DB best-practices skill rule intended to steer Python azure-cosmos v4 users toward configuring CosmosClient via constructor keyword arguments rather than constructing/mutating a documents.ConnectionPolicy, and regenerates the compiled AGENTS.md accordingly.
Changes:
- Added new rule
sdk-python-client-kwargsunderskills/cosmosdb-best-practices/rules/. - Regenerated
skills/cosmosdb-best-practices/AGENTS.mdto include the new rule and updated section numbering/TOC.
Reviewed changes
Copilot reviewed 2 out of 2 changed files in this pull request and generated 3 comments.
| File | Description |
|---|---|
| skills/cosmosdb-best-practices/rules/sdk-python-client-kwargs.md | New rule describing the preferred Python SDK v4 client configuration surface (kwargs vs ConnectionPolicy). |
| skills/cosmosdb-best-practices/AGENTS.md | Recompiled skill output to include the new rule content and updated TOC/section numbering. |
Comment on lines
+56
to
+60
| connection_timeout=10, # seconds (NOT the ms-based legacy request_timeout) | ||
| preferred_locations=["West US 2", "East US 2"], | ||
| retry_total=9, # azure-core throttle/retry, replaces RetryOptions | ||
| connection_verify=False, # emulator self-signed cert; True in production | ||
| enable_diagnostics_logging=True, |
Comment on lines
+51
to
+52
| # The documented v4 surface. The SDK maps these kwargs onto its internal | ||
| # ConnectionPolicy for you via _build_connection_policy(). |
Comment on lines
+12
to
+14
| regions, TLS verification, diagnostics, and more. Internally the client maps those | ||
| kwargs onto a `ConnectionPolicy` via its own `_build_connection_policy()` helper, so | ||
| you never construct that object yourself. |
TheovanKraay
requested changes
Jul 18, 2026
TheovanKraay
left a comment
TheovanKraay
left a comment
Contributor
There was a problem hiding this comment.
Thanks @yumnahussain, this is great, not covered by any existing rule, so no redundancy concerns. Two things before we merge, both from the Copilot pass: please flip connection_verify to True in the "Correct" example (with False only noted for the local emulator/self-signed case, ideally cross-referencing sdk-emulator-ssl), since it is an easy unsafe copy-paste as-is, and drop the references to the private _build_connection_policy() helper (just say the SDK maps the kwargs internally). Once those are in, this is good to go!
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
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.
Summary
Adds a new Cosmos DB best-practices skill rule:
sdk-python-client-kwargs— configure the PythonCosmosClientwith keyword arguments, not a hand-builtConnectionPolicy.In the
azure-cosmosv4 SDK, all client configuration is passed as keyword arguments to the constructor (connection_timeout,preferred_locations,retry_total,connection_verify, ...). The client maps them onto aConnectionPolicyinternally via_build_connection_policy(). Constructingazure.cosmos.documents.ConnectionPolicyand mutating its attributes (the classicpolicy.RequestTimeout = 10000anti-pattern) is a legacy v3/pydocumentdbcarry-over that also steers toward deprecated knobs (retry_options,connection_retry_policy).Provenance
Verified against the installed
azure-cosmosv4.7.0 source (cosmos_client.py_build_connection_policy) and cross-checked with SDK CHANGELOG history (connection_timeoutbecame canonical in 4.4.0b2).SSLConfiguration/ProxyConfigurationobjects are intentionally not discouraged — they remain the required surface for those settings.Changes
skills/cosmosdb-best-practices/rules/sdk-python-client-kwargs.mdAGENTS.md(npm run build)Note
A companion verifier test (
TestClientConfigViaKwargsincheck_source.py) that enforces this rule lives in the pipeline PR #222.