add python best practice and update python skills accordingly

[xiangyan99]

add python best practice and update python skills accordingly

[kvenkatrajan]

@xiangyan99 - for @scottaddie's changes were these reflected back into the skill creator?

[xiangyan99]

@xiangyan99 - for @scottaddie's changes were these reflected back into the skill creator?

Yes. I updated in the skill-creator to use

3. Use DefaultAzureCredential for code that runs locally. Use a specific token credential (e.g. ManagedIdentityCredential, WorkloadIdentityCredential) for code that runs in Azure.

[thegovind]

Review summary

Solid cross-cutting Python improvement — the new "Sync vs Async: Pick One, Don't Mix" and tightened "Context Managers (Strongly Preferred)" sections in skill-creator/references/azure-sdk-patterns.md are exactly the kind of high-leverage guidance that should govern every Python skill in the catalog. Propagating the dual-rule callout to 38 SKILL.md files is a real net win.

A few concerns about scope and a couple of small bugs.

Issues

🔴 Blocking

1. Wholesale removal of AzureKeyCredential examples across many services.

The diff doesn't just prefer Entra — it deletes the API-key auth path entirely from at least: azure-ai-contentsafety-py, azure-ai-language-conversations-py, azure-ai-textanalytics-py, azure-ai-translation-document-py, azure-ai-translation-text-py, and others (~30 deletions of AzureKeyCredential usage).

Two problems:

• API-key auth is still officially supported for these services. Many existing users (including customers in regulated environments who haven't yet completed Entra rollout) need a copy-pastable working sample.
• For azure-ai-translation-text-py, key+region is the most common path because token-credential auth requires a custom endpoint; deleting the key+region example removes the canonical translator setup.

Suggested fix: Don't delete — demote. Keep a clearly labelled ### Legacy: API Key (existing keyed deployments) subsection after the Entra primary path, so the skill leads with credential-free but still answers "how do I use my existing key?". Mirrors what we do for connection strings in storage skills.

🟡 Recommended

2. Tension with PR #199's production-auth guidance.

PR #295 standardizes on DefaultAzureCredential (with AZURE_TOKEN_CREDENTIALS=prod to scope it) as the canonical example. PR #199 is currently arguing the opposite — that DefaultAzureCredential shouldn't be used in production and ManagedIdentityCredential should be the production example.

These two PRs touch the same surface area with opposite recommendations. Whichever lands first will force the other to rebase substantively. Worth a sync between authors / scottaddie before either merges; otherwise the catalog will ship contradictory Python guidance to users.

3. The "Bad — sync client inside async function" snippet in azure-sdk-patterns.md won't run as written.

async def run():
    from azure.ai.projects import AIProjectClient  # sync!
    client = AIProjectClient(endpoint=endpoint, credential=cred)
    ...

endpoint and cred are undefined and there's no await to make the example obviously async. Worth tightening: define both, and make it a one-liner with a comment. Right now an LLM ingesting this might copy a non-runnable pattern as canonical.

4. Best-practices renumbering in azure-identity-py shifts items 1–11 to 3–13 by inserting two new rules at the top.

Functionally fine, but anything that links to "Best Practice #6" (e.g., other skills cross-referencing) will silently break. Quick grep across the repo for Best Practice # would catch any references.

5. # ... placeholder bodies inside the rewritten with blocks.

Several skills now show:

with BlobServiceClient(...) as client:
    # ...
    ...

This compiles but reads as "skip me" to copy-pasters. Replace with a one-line representative call, e.g. containers = list(client.list_containers()). Otherwise the skill loses the point of the example.

🟢 Nits

• The dual-rule callout is solid, but consider hoisting it into a single shared snippet in skill-creator/references/azure-sdk-patterns.md and having each Python skill link to it. Inlining the same 8-line block in 38 files means future edits are 38-place changes.
• AZURE_TOKEN_CREDENTIALS=prod is mentioned in env-var blocks but the meaning of prod (and the alternative explicit credential names like ManagedIdentityCredential, WorkloadIdentityCredential) is only spelled out in some skills. Centralize the explanation.
• For async credentials, the snippet async with DefaultAzureCredential() as credential, async with Client(...) as client: is correct Python but rarely seen in the wild — a brief one-liner explaining the chained context-manager syntax would help reviewers and consumers.

Once #1 (don't delete API-key paths, just demote) and #3 (fix the broken bad-example) are addressed, I'd merge this.