From d7256f960d9ff8f38f531d66574507eba646c957 Mon Sep 17 00:00:00 2001 From: Larry Osterman Date: Wed, 15 Jul 2026 10:27:24 -0700 Subject: [PATCH 01/26] Add capability and non-hero references for Python skills Split from #375: adds references/capabilities.md and references/non-hero-scenarios.md across ~30 azure-sdk-python skills, updates their SKILL.md files, and refreshes .github/skills symlinks. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: 9429ad33-6f31-4ec5-ba00-0f11b5afb82e --- .../agent-framework-azure-ai-py/SKILL.md | 2 +- .../skills/azure-ai-contentsafety-py/SKILL.md | 7 + .../references/capabilities.md | 34 +++ .../references/non-hero-scenarios.md | 29 +++ .../azure-ai-contentunderstanding-py/SKILL.md | 7 + .../references/capabilities.md | 46 ++++ .../references/non-hero-scenarios.md | 175 +++++++++++++++ .../SKILL.md | 9 +- .../references/capabilities.md | 27 +++ .../references/non-hero-scenarios.md | 8 + .../skills/azure-ai-ml-py/SKILL.md | 7 + .../azure-ai-ml-py/references/capabilities.md | 38 ++++ .../references/non-hero-scenarios.md | 104 +++++++++ .../skills/azure-ai-textanalytics-py/SKILL.md | 7 + .../references/capabilities.md | 40 ++++ .../references/non-hero-scenarios.md | 104 +++++++++ .../skills/azure-ai-transcription-py/SKILL.md | 22 +- .../references/capabilities.md | 28 +++ .../references/non-hero-scenarios.md | 8 + .../azure-ai-translation-document-py/SKILL.md | 7 + .../references/capabilities.md | 44 ++++ .../references/non-hero-scenarios.md | 105 +++++++++ .../azure-ai-translation-text-py/SKILL.md | 7 + .../references/capabilities.md | 44 ++++ .../references/non-hero-scenarios.md | 150 +++++++++++++ .../azure-ai-vision-imageanalysis-py/SKILL.md | 7 + .../references/capabilities.md | 46 ++++ .../references/non-hero-scenarios.md | 137 ++++++++++++ .../skills/azure-ai-voicelive-py/SKILL.md | 2 +- .../skills/azure-appconfiguration-py/SKILL.md | 7 + .../references/capabilities.md | 34 +++ .../references/non-hero-scenarios.md | 60 +++++ .../azure-containerregistry-py/SKILL.md | 7 + .../references/capabilities.md | 38 ++++ .../references/non-hero-scenarios.md | 80 +++++++ .../skills/azure-cosmos-db-py/SKILL.md | 2 +- .../scripts/setup_cosmos_container.py | 138 ++++++------ .../skills/azure-data-tables-py/SKILL.md | 7 + .../references/capabilities.md | 34 +++ .../references/non-hero-scenarios.md | 62 ++++++ .../skills/azure-eventgrid-py/SKILL.md | 7 + .../references/capabilities.md | 32 +++ .../references/non-hero-scenarios.md | 47 ++++ .../skills/azure-identity-py/SKILL.md | 22 +- .../references/capabilities.md | 42 ++++ .../references/non-hero-scenarios.md | 129 +++++++++++ .../skills/azure-keyvault-py/SKILL.md | 7 + .../references/capabilities.md | 32 +++ .../references/non-hero-scenarios.md | 35 +++ .../SKILL.md | 7 + .../references/capabilities.md | 30 +++ .../references/non-hero-scenarios.md | 8 + .../skills/azure-mgmt-apicenter-py/SKILL.md | 94 ++++---- .../references/capabilities.md | 44 ++++ .../references/non-hero-scenarios.md | 139 ++++++++++++ .../azure-mgmt-apimanagement-py/SKILL.md | 7 + .../references/capabilities.md | 44 ++++ .../references/non-hero-scenarios.md | 156 +++++++++++++ .../skills/azure-mgmt-botservice-py/SKILL.md | 7 + .../references/capabilities.md | 46 ++++ .../references/non-hero-scenarios.md | 208 ++++++++++++++++++ .../skills/azure-mgmt-fabric-py/SKILL.md | 7 + .../references/capabilities.md | 48 ++++ .../references/non-hero-scenarios.md | 142 ++++++++++++ .../azure-monitor-ingestion-py/SKILL.md | 7 + .../references/capabilities.md | 40 ++++ .../references/non-hero-scenarios.md | 73 ++++++ .../SKILL.md | 20 +- .../references/capabilities.md | 42 ++++ .../references/non-hero-scenarios.md | 91 ++++++++ .../azure-monitor-opentelemetry-py/SKILL.md | 20 +- .../references/capabilities.md | 48 ++++ .../references/non-hero-scenarios.md | 136 ++++++++++++ .../skills/azure-monitor-query-py/SKILL.md | 7 + .../references/capabilities.md | 30 +++ .../references/non-hero-scenarios.md | 11 + .../azure-speech-to-text-rest-py/SKILL.md | 13 +- .../skills/azure-storage-blob-py/SKILL.md | 7 + .../references/capabilities.md | 32 +++ .../references/non-hero-scenarios.md | 46 ++++ .../azure-storage-file-datalake-py/SKILL.md | 7 + .../references/capabilities.md | 36 +++ .../references/non-hero-scenarios.md | 77 +++++++ .../azure-storage-file-share-py/SKILL.md | 7 + .../references/capabilities.md | 34 +++ .../references/non-hero-scenarios.md | 46 ++++ .../skills/azure-storage-queue-py/SKILL.md | 7 + .../references/capabilities.md | 40 ++++ .../references/non-hero-scenarios.md | 101 +++++++++ .../skills/fastapi-router-py/SKILL.md | 8 +- .../references/capabilities.md | 25 +++ .../skills/m365-agents-py/SKILL.md | 17 +- .../m365-agents-py/references/capabilities.md | 42 ++++ .../skills/pydantic-models-py/SKILL.md | 6 + .../references/capabilities.md | 25 +++ .github/skills/agent-framework-azure-ai-py | 1 + .github/skills/azure-ai-contentsafety-py | 1 + .../skills/azure-ai-contentunderstanding-py | 1 + .../skills/azure-ai-language-conversations-py | 1 + .github/skills/azure-ai-ml-py | 1 + .github/skills/azure-ai-projects-py | 1 + .github/skills/azure-ai-textanalytics-py | 1 + .github/skills/azure-ai-transcription-py | 1 + .../skills/azure-ai-translation-document-py | 1 + .github/skills/azure-ai-translation-text-py | 1 + .../skills/azure-ai-vision-imageanalysis-py | 1 + .github/skills/azure-ai-voicelive-py | 1 + .github/skills/azure-appconfiguration-py | 1 + .github/skills/azure-containerregistry-py | 1 + .github/skills/azure-cosmos-db-py | 1 + .github/skills/azure-cosmos-py | 1 + .github/skills/azure-data-tables-py | 1 + .github/skills/azure-eventgrid-py | 1 + .github/skills/azure-eventhub-py | 1 + .github/skills/azure-identity-py | 1 + .github/skills/azure-keyvault-py | 1 + .../azure-messaging-webpubsubservice-py | 1 + .github/skills/azure-mgmt-apicenter-py | 1 + .github/skills/azure-mgmt-apimanagement-py | 1 + .github/skills/azure-mgmt-botservice-py | 1 + .github/skills/azure-mgmt-fabric-py | 1 + .github/skills/azure-monitor-ingestion-py | 1 + .../azure-monitor-opentelemetry-exporter-py | 1 + .github/skills/azure-monitor-opentelemetry-py | 1 + .github/skills/azure-monitor-query-py | 1 + .github/skills/azure-search-documents-py | 1 + .github/skills/azure-servicebus-py | 1 + .github/skills/azure-speech-to-text-rest-py | 1 + .github/skills/azure-storage-blob-py | 1 + .github/skills/azure-storage-file-datalake-py | 1 + .github/skills/azure-storage-file-share-py | 1 + .github/skills/azure-storage-queue-py | 1 + .github/skills/fastapi-router-py | 1 + .github/skills/m365-agents-py | 1 + .github/skills/pydantic-models-py | 1 + 135 files changed, 4075 insertions(+), 126 deletions(-) create mode 100644 .github/plugins/azure-sdk-python/skills/azure-ai-contentsafety-py/references/capabilities.md create mode 100644 .github/plugins/azure-sdk-python/skills/azure-ai-contentsafety-py/references/non-hero-scenarios.md create mode 100644 .github/plugins/azure-sdk-python/skills/azure-ai-contentunderstanding-py/references/capabilities.md create mode 100644 .github/plugins/azure-sdk-python/skills/azure-ai-contentunderstanding-py/references/non-hero-scenarios.md create mode 100644 .github/plugins/azure-sdk-python/skills/azure-ai-language-conversations-py/references/capabilities.md create mode 100644 .github/plugins/azure-sdk-python/skills/azure-ai-language-conversations-py/references/non-hero-scenarios.md create mode 100644 .github/plugins/azure-sdk-python/skills/azure-ai-ml-py/references/capabilities.md create mode 100644 .github/plugins/azure-sdk-python/skills/azure-ai-ml-py/references/non-hero-scenarios.md create mode 100644 .github/plugins/azure-sdk-python/skills/azure-ai-textanalytics-py/references/capabilities.md create mode 100644 .github/plugins/azure-sdk-python/skills/azure-ai-textanalytics-py/references/non-hero-scenarios.md create mode 100644 .github/plugins/azure-sdk-python/skills/azure-ai-transcription-py/references/capabilities.md create mode 100644 .github/plugins/azure-sdk-python/skills/azure-ai-transcription-py/references/non-hero-scenarios.md create mode 100644 .github/plugins/azure-sdk-python/skills/azure-ai-translation-document-py/references/capabilities.md create mode 100644 .github/plugins/azure-sdk-python/skills/azure-ai-translation-document-py/references/non-hero-scenarios.md create mode 100644 .github/plugins/azure-sdk-python/skills/azure-ai-translation-text-py/references/capabilities.md create mode 100644 .github/plugins/azure-sdk-python/skills/azure-ai-translation-text-py/references/non-hero-scenarios.md create mode 100644 .github/plugins/azure-sdk-python/skills/azure-ai-vision-imageanalysis-py/references/capabilities.md create mode 100644 .github/plugins/azure-sdk-python/skills/azure-ai-vision-imageanalysis-py/references/non-hero-scenarios.md create mode 100644 .github/plugins/azure-sdk-python/skills/azure-appconfiguration-py/references/capabilities.md create mode 100644 .github/plugins/azure-sdk-python/skills/azure-appconfiguration-py/references/non-hero-scenarios.md create mode 100644 .github/plugins/azure-sdk-python/skills/azure-containerregistry-py/references/capabilities.md create mode 100644 .github/plugins/azure-sdk-python/skills/azure-containerregistry-py/references/non-hero-scenarios.md create mode 100644 .github/plugins/azure-sdk-python/skills/azure-data-tables-py/references/capabilities.md create mode 100644 .github/plugins/azure-sdk-python/skills/azure-data-tables-py/references/non-hero-scenarios.md create mode 100644 .github/plugins/azure-sdk-python/skills/azure-eventgrid-py/references/capabilities.md create mode 100644 .github/plugins/azure-sdk-python/skills/azure-eventgrid-py/references/non-hero-scenarios.md create mode 100644 .github/plugins/azure-sdk-python/skills/azure-identity-py/references/capabilities.md create mode 100644 .github/plugins/azure-sdk-python/skills/azure-identity-py/references/non-hero-scenarios.md create mode 100644 .github/plugins/azure-sdk-python/skills/azure-keyvault-py/references/capabilities.md create mode 100644 .github/plugins/azure-sdk-python/skills/azure-keyvault-py/references/non-hero-scenarios.md create mode 100644 .github/plugins/azure-sdk-python/skills/azure-messaging-webpubsubservice-py/references/capabilities.md create mode 100644 .github/plugins/azure-sdk-python/skills/azure-messaging-webpubsubservice-py/references/non-hero-scenarios.md create mode 100644 .github/plugins/azure-sdk-python/skills/azure-mgmt-apicenter-py/references/capabilities.md create mode 100644 .github/plugins/azure-sdk-python/skills/azure-mgmt-apicenter-py/references/non-hero-scenarios.md create mode 100644 .github/plugins/azure-sdk-python/skills/azure-mgmt-apimanagement-py/references/capabilities.md create mode 100644 .github/plugins/azure-sdk-python/skills/azure-mgmt-apimanagement-py/references/non-hero-scenarios.md create mode 100644 .github/plugins/azure-sdk-python/skills/azure-mgmt-botservice-py/references/capabilities.md create mode 100644 .github/plugins/azure-sdk-python/skills/azure-mgmt-botservice-py/references/non-hero-scenarios.md create mode 100644 .github/plugins/azure-sdk-python/skills/azure-mgmt-fabric-py/references/capabilities.md create mode 100644 .github/plugins/azure-sdk-python/skills/azure-mgmt-fabric-py/references/non-hero-scenarios.md create mode 100644 .github/plugins/azure-sdk-python/skills/azure-monitor-ingestion-py/references/capabilities.md create mode 100644 .github/plugins/azure-sdk-python/skills/azure-monitor-ingestion-py/references/non-hero-scenarios.md create mode 100644 .github/plugins/azure-sdk-python/skills/azure-monitor-opentelemetry-exporter-py/references/capabilities.md create mode 100644 .github/plugins/azure-sdk-python/skills/azure-monitor-opentelemetry-exporter-py/references/non-hero-scenarios.md create mode 100644 .github/plugins/azure-sdk-python/skills/azure-monitor-opentelemetry-py/references/capabilities.md create mode 100644 .github/plugins/azure-sdk-python/skills/azure-monitor-opentelemetry-py/references/non-hero-scenarios.md create mode 100644 .github/plugins/azure-sdk-python/skills/azure-monitor-query-py/references/capabilities.md create mode 100644 .github/plugins/azure-sdk-python/skills/azure-monitor-query-py/references/non-hero-scenarios.md create mode 100644 .github/plugins/azure-sdk-python/skills/azure-storage-blob-py/references/capabilities.md create mode 100644 .github/plugins/azure-sdk-python/skills/azure-storage-blob-py/references/non-hero-scenarios.md create mode 100644 .github/plugins/azure-sdk-python/skills/azure-storage-file-datalake-py/references/capabilities.md create mode 100644 .github/plugins/azure-sdk-python/skills/azure-storage-file-datalake-py/references/non-hero-scenarios.md create mode 100644 .github/plugins/azure-sdk-python/skills/azure-storage-file-share-py/references/capabilities.md create mode 100644 .github/plugins/azure-sdk-python/skills/azure-storage-file-share-py/references/non-hero-scenarios.md create mode 100644 .github/plugins/azure-sdk-python/skills/azure-storage-queue-py/references/capabilities.md create mode 100644 .github/plugins/azure-sdk-python/skills/azure-storage-queue-py/references/non-hero-scenarios.md create mode 100644 .github/plugins/azure-sdk-python/skills/fastapi-router-py/references/capabilities.md create mode 100644 .github/plugins/azure-sdk-python/skills/m365-agents-py/references/capabilities.md create mode 100644 .github/plugins/azure-sdk-python/skills/pydantic-models-py/references/capabilities.md create mode 120000 .github/skills/agent-framework-azure-ai-py create mode 120000 .github/skills/azure-ai-contentsafety-py create mode 120000 .github/skills/azure-ai-contentunderstanding-py create mode 120000 .github/skills/azure-ai-language-conversations-py create mode 120000 .github/skills/azure-ai-ml-py create mode 120000 .github/skills/azure-ai-projects-py create mode 120000 .github/skills/azure-ai-textanalytics-py create mode 120000 .github/skills/azure-ai-transcription-py create mode 120000 .github/skills/azure-ai-translation-document-py create mode 120000 .github/skills/azure-ai-translation-text-py create mode 120000 .github/skills/azure-ai-vision-imageanalysis-py create mode 120000 .github/skills/azure-ai-voicelive-py create mode 120000 .github/skills/azure-appconfiguration-py create mode 120000 .github/skills/azure-containerregistry-py create mode 120000 .github/skills/azure-cosmos-db-py create mode 120000 .github/skills/azure-cosmos-py create mode 120000 .github/skills/azure-data-tables-py create mode 120000 .github/skills/azure-eventgrid-py create mode 120000 .github/skills/azure-eventhub-py create mode 120000 .github/skills/azure-identity-py create mode 120000 .github/skills/azure-keyvault-py create mode 120000 .github/skills/azure-messaging-webpubsubservice-py create mode 120000 .github/skills/azure-mgmt-apicenter-py create mode 120000 .github/skills/azure-mgmt-apimanagement-py create mode 120000 .github/skills/azure-mgmt-botservice-py create mode 120000 .github/skills/azure-mgmt-fabric-py create mode 120000 .github/skills/azure-monitor-ingestion-py create mode 120000 .github/skills/azure-monitor-opentelemetry-exporter-py create mode 120000 .github/skills/azure-monitor-opentelemetry-py create mode 120000 .github/skills/azure-monitor-query-py create mode 120000 .github/skills/azure-search-documents-py create mode 120000 .github/skills/azure-servicebus-py create mode 120000 .github/skills/azure-speech-to-text-rest-py create mode 120000 .github/skills/azure-storage-blob-py create mode 120000 .github/skills/azure-storage-file-datalake-py create mode 120000 .github/skills/azure-storage-file-share-py create mode 120000 .github/skills/azure-storage-queue-py create mode 120000 .github/skills/fastapi-router-py create mode 120000 .github/skills/m365-agents-py create mode 120000 .github/skills/pydantic-models-py diff --git a/.github/plugins/azure-sdk-python/skills/agent-framework-azure-ai-py/SKILL.md b/.github/plugins/azure-sdk-python/skills/agent-framework-azure-ai-py/SKILL.md index 04a975fe..98b28f5c 100644 --- a/.github/plugins/azure-sdk-python/skills/agent-framework-azure-ai-py/SKILL.md +++ b/.github/plugins/azure-sdk-python/skills/agent-framework-azure-ai-py/SKILL.md @@ -347,7 +347,7 @@ if __name__ == "__main__": ## Best Practices -1. **This SDK is async-first** — use `async def` handlers and `async with` throughout. +1. **This SDK is async-first — use `async def` handlers and `async with` throughout.** 2. **Always use context managers for clients and async credentials.** Wrap every client in `with Client(...) as client:` (sync) or `async with Client(...) as client:` (async). For async `DefaultAzureCredential` from `azure.identity.aio`, also use `async with credential:` so tokens and transports are cleaned up. ## Reference Files diff --git a/.github/plugins/azure-sdk-python/skills/azure-ai-contentsafety-py/SKILL.md b/.github/plugins/azure-sdk-python/skills/azure-ai-contentsafety-py/SKILL.md index f48d8a11..9caadcc9 100644 --- a/.github/plugins/azure-sdk-python/skills/azure-ai-contentsafety-py/SKILL.md +++ b/.github/plugins/azure-sdk-python/skills/azure-ai-contentsafety-py/SKILL.md @@ -240,3 +240,10 @@ request = AnalyzeTextOptions( 7. **Log analysis results** for audit and improvement 8. **Consider 8-severity mode** for finer-grained control 9. **Pre-moderate AI outputs** before showing to users + +## Reference Files + +| File | Contents | +|------|----------| +| [references/capabilities.md](references/capabilities.md) | Additional non-hero capabilities, operation-group coverage, and production checklists. | +| [references/non-hero-scenarios.md](references/non-hero-scenarios.md) | Dedicated non-hero examples for secondary/advanced scenarios. | diff --git a/.github/plugins/azure-sdk-python/skills/azure-ai-contentsafety-py/references/capabilities.md b/.github/plugins/azure-sdk-python/skills/azure-ai-contentsafety-py/references/capabilities.md new file mode 100644 index 00000000..529c1776 --- /dev/null +++ b/.github/plugins/azure-sdk-python/skills/azure-ai-contentsafety-py/references/capabilities.md @@ -0,0 +1,34 @@ +# azure-ai-contentsafety-py capability coverage + +**SDK/package**: `azure-ai-contentsafety` + +This index maps hero scenarios in `SKILL.md` and links non-hero scenarios documented in dedicated reference files. + +## Hero scenarios covered in SKILL.md + +- `Analyze Text` +- `Analyze Image` +- `Text Blocklist Management` +- `Severity Levels` + +## Non-hero scenarios + +- `Harm Categories`: | Category | Description | + See: [`non-hero-scenarios.md#harm-categories`](non-hero-scenarios.md#harm-categories) +- `Severity Scale`: | Level | Text Range | Image Range | Meaning | + See: [`non-hero-scenarios.md#severity-scale`](non-hero-scenarios.md#severity-scale) +- `Client Types`: | Client | Purpose | + See: [`non-hero-scenarios.md#client-types`](non-hero-scenarios.md#client-types) + +## Related deep-dive references + +- [`non-hero-scenarios.md`](non-hero-scenarios.md): Dedicated non-hero examples and implementation notes. + +## API breadth checklist + +- Verify client/auth mode for the environment before coding. +- Confirm operation-group/method names against current Microsoft Learn API reference. +- For Python SDKs with both sync and async clients, document both forms without a blanket preference. +- Include cleanup/delete paths for created resources in examples. +- Prefer idempotent create/update operations where available. +- Validate paging/LRO/error-handling patterns for production paths. diff --git a/.github/plugins/azure-sdk-python/skills/azure-ai-contentsafety-py/references/non-hero-scenarios.md b/.github/plugins/azure-sdk-python/skills/azure-ai-contentsafety-py/references/non-hero-scenarios.md new file mode 100644 index 00000000..3d08cd45 --- /dev/null +++ b/.github/plugins/azure-sdk-python/skills/azure-ai-contentsafety-py/references/non-hero-scenarios.md @@ -0,0 +1,29 @@ +# azure-ai-contentsafety-py non-hero scenarios + +These scenarios are intentionally separate from hero flows in `SKILL.md`. +They cover secondary/advanced patterns typically used after the primary end-to-end path is working. + +## Harm Categories + +| Category | Description | +|----------|-------------| +| `Hate` | Attacks based on identity (race, religion, gender, etc.) | +| `Sexual` | Sexual content, relationships, anatomy | +| `Violence` | Physical harm, weapons, injury | +| `SelfHarm` | Self-injury, suicide, eating disorders | + +## Severity Scale + +| Level | Text Range | Image Range | Meaning | +|-------|------------|-------------|---------| +| 0 | Safe | Safe | No harmful content | +| 2 | Low | Low | Mild references | +| 4 | Medium | Medium | Moderate content | +| 6 | High | High | Severe content | + +## Client Types + +| Client | Purpose | +|--------|---------| +| `ContentSafetyClient` | Analyze text and images | +| `BlocklistClient` | Manage custom blocklists | diff --git a/.github/plugins/azure-sdk-python/skills/azure-ai-contentunderstanding-py/SKILL.md b/.github/plugins/azure-sdk-python/skills/azure-ai-contentunderstanding-py/SKILL.md index 1998fba3..5b59e23e 100644 --- a/.github/plugins/azure-sdk-python/skills/azure-ai-contentunderstanding-py/SKILL.md +++ b/.github/plugins/azure-sdk-python/skills/azure-ai-contentunderstanding-py/SKILL.md @@ -292,3 +292,10 @@ from azure.ai.contentunderstanding.models import ( 7. **Use async client** for high-throughput scenarios with `azure.identity.aio` credentials 8. **Handle long-running operations** — video/audio analysis can take minutes 9. **Use URL sources** when possible to avoid upload overhead + +## Reference Files + +| File | Contents | +|------|----------| +| [references/capabilities.md](references/capabilities.md) | Additional non-hero capabilities, operation-group coverage, and production checklists. | +| [references/non-hero-scenarios.md](references/non-hero-scenarios.md) | Dedicated non-hero examples for secondary/advanced scenarios. | diff --git a/.github/plugins/azure-sdk-python/skills/azure-ai-contentunderstanding-py/references/capabilities.md b/.github/plugins/azure-sdk-python/skills/azure-ai-contentunderstanding-py/references/capabilities.md new file mode 100644 index 00000000..d03bbc13 --- /dev/null +++ b/.github/plugins/azure-sdk-python/skills/azure-ai-contentunderstanding-py/references/capabilities.md @@ -0,0 +1,46 @@ +# azure-ai-contentunderstanding-py capability coverage + +**SDK/package**: `azure-ai-contentunderstanding` + +This index maps hero scenarios in `SKILL.md` and links non-hero scenarios documented in dedicated reference files. + +## Hero scenarios covered in SKILL.md + +- `Core Workflow` +- `Prebuilt Analyzers` +- `Analyze Document` +- `Access Document Content Details` + +## Non-hero scenarios + +- `Analyze Image`: Dedicated example and implementation notes. + See: [`non-hero-scenarios.md#analyze-image`](non-hero-scenarios.md#analyze-image) +- `Analyze Video`: Dedicated example and implementation notes. + See: [`non-hero-scenarios.md#analyze-video`](non-hero-scenarios.md#analyze-video) +- `Analyze Audio`: Dedicated example and implementation notes. + See: [`non-hero-scenarios.md#analyze-audio`](non-hero-scenarios.md#analyze-audio) +- `Custom Analyzers`: Create custom analyzers with field schemas for specialized extraction: + See: [`non-hero-scenarios.md#custom-analyzers`](non-hero-scenarios.md#custom-analyzers) +- `Analyzer Management`: Dedicated example and implementation notes. + See: [`non-hero-scenarios.md#analyzer-management`](non-hero-scenarios.md#analyzer-management) +- `Async Client`: Dedicated example and implementation notes. + See: [`non-hero-scenarios.md#async-client`](non-hero-scenarios.md#async-client) +- `Content Types`: | Class | For | Provides | + See: [`non-hero-scenarios.md#content-types`](non-hero-scenarios.md#content-types) +- `Model Imports`: Dedicated example and implementation notes. + See: [`non-hero-scenarios.md#model-imports`](non-hero-scenarios.md#model-imports) +- `Client Types`: | Client | Purpose | + See: [`non-hero-scenarios.md#client-types`](non-hero-scenarios.md#client-types) + +## Related deep-dive references + +- [`non-hero-scenarios.md`](non-hero-scenarios.md): Dedicated non-hero examples and implementation notes. + +## API breadth checklist + +- Verify client/auth mode for the environment before coding. +- Confirm operation-group/method names against current Microsoft Learn API reference. +- For Python SDKs with both sync and async clients, document both forms without a blanket preference. +- Include cleanup/delete paths for created resources in examples. +- Prefer idempotent create/update operations where available. +- Validate paging/LRO/error-handling patterns for production paths. diff --git a/.github/plugins/azure-sdk-python/skills/azure-ai-contentunderstanding-py/references/non-hero-scenarios.md b/.github/plugins/azure-sdk-python/skills/azure-ai-contentunderstanding-py/references/non-hero-scenarios.md new file mode 100644 index 00000000..f5a6a4fb --- /dev/null +++ b/.github/plugins/azure-sdk-python/skills/azure-ai-contentunderstanding-py/references/non-hero-scenarios.md @@ -0,0 +1,175 @@ +# azure-ai-contentunderstanding-py non-hero scenarios + +These scenarios are intentionally separate from hero flows in `SKILL.md`. +They cover secondary/advanced patterns typically used after the primary end-to-end path is working. + +## Analyze Image + +```python +from azure.ai.contentunderstanding.models import AnalyzeInput + +poller = client.begin_analyze( + analyzer_id="prebuilt-imageSearch", + inputs=[AnalyzeInput(url="https://example.com/image.jpg")] +) +result = poller.result() +content = result.contents[0] +print(content.markdown) +``` + +## Analyze Video + +```python +from azure.ai.contentunderstanding.models import AnalyzeInput + +poller = client.begin_analyze( + analyzer_id="prebuilt-videoSearch", + inputs=[AnalyzeInput(url="https://example.com/video.mp4")] +) + +result = poller.result() + +# Access video content (AudioVisualContent) +content = result.contents[0] + +# Get transcript phrases with timing +for phrase in content.transcript_phrases: + print(f"[{phrase.start_time} - {phrase.end_time}]: {phrase.text}") + +# Get key frames (for video) +for frame in content.key_frames: + print(f"Frame at {frame.time}: {frame.description}") +``` + +## Analyze Audio + +```python +from azure.ai.contentunderstanding.models import AnalyzeInput + +poller = client.begin_analyze( + analyzer_id="prebuilt-audioSearch", + inputs=[AnalyzeInput(url="https://example.com/audio.mp3")] +) + +result = poller.result() + +# Access audio transcript +content = result.contents[0] +for phrase in content.transcript_phrases: + print(f"[{phrase.start_time}] {phrase.text}") +``` + +## Custom Analyzers + +Create custom analyzers with field schemas for specialized extraction: + +```python +# Create custom analyzer +analyzer = client.create_analyzer( + analyzer_id="my-invoice-analyzer", + analyzer={ + "description": "Custom invoice analyzer", + "base_analyzer_id": "prebuilt-documentSearch", + "field_schema": { + "fields": { + "vendor_name": {"type": "string"}, + "invoice_total": {"type": "number"}, + "line_items": { + "type": "array", + "items": { + "type": "object", + "properties": { + "description": {"type": "string"}, + "amount": {"type": "number"} + } + } + } + } + } + } +) + +# Use custom analyzer +from azure.ai.contentunderstanding.models import AnalyzeInput + +poller = client.begin_analyze( + analyzer_id="my-invoice-analyzer", + inputs=[AnalyzeInput(url="https://example.com/invoice.pdf")] +) + +result = poller.result() + +# Access extracted fields +print(result.fields["vendor_name"]) +print(result.fields["invoice_total"]) +``` + +## Analyzer Management + +```python +# List all analyzers +analyzers = client.list_analyzers() +for analyzer in analyzers: + print(f"{analyzer.analyzer_id}: {analyzer.description}") + +# Get specific analyzer +analyzer = client.get_analyzer("prebuilt-documentSearch") + +# Delete custom analyzer +client.delete_analyzer("my-custom-analyzer") +``` + +## Async Client + +```python +import asyncio +import os +from azure.ai.contentunderstanding.aio import ContentUnderstandingClient +from azure.ai.contentunderstanding.models import AnalyzeInput +from azure.identity.aio import DefaultAzureCredential + +async def analyze_document(): + endpoint = os.environ["CONTENTUNDERSTANDING_ENDPOINT"] + async with DefaultAzureCredential() as credential: + async with ContentUnderstandingClient( + endpoint=endpoint, + credential=credential + ) as client: + poller = await client.begin_analyze( + analyzer_id="prebuilt-documentSearch", + inputs=[AnalyzeInput(url="https://example.com/doc.pdf")] + ) + result = await poller.result() + content = result.contents[0] + return content.markdown + +asyncio.run(analyze_document()) +``` + +## Content Types + +| Class | For | Provides | +|-------|-----|----------| +| `DocumentContent` | PDF, images, Office docs | Pages, tables, figures, paragraphs | +| `AudioVisualContent` | Audio, video files | Transcript phrases, timing, key frames | + +Both derive from `MediaContent` which provides basic info and markdown representation. + +## Model Imports + +```python +from azure.ai.contentunderstanding.models import ( + AnalyzeInput, + AnalyzeResult, + MediaContentKind, + DocumentContent, + AudioVisualContent, +) +``` + +## Client Types + +| Client | Purpose | +|--------|---------| +| `ContentUnderstandingClient` | Sync client for all operations | +| `ContentUnderstandingClient` (aio) | Async client for all operations | diff --git a/.github/plugins/azure-sdk-python/skills/azure-ai-language-conversations-py/SKILL.md b/.github/plugins/azure-sdk-python/skills/azure-ai-language-conversations-py/SKILL.md index 74a373cb..d875833e 100644 --- a/.github/plugins/azure-sdk-python/skills/azure-ai-language-conversations-py/SKILL.md +++ b/.github/plugins/azure-sdk-python/skills/azure-ai-language-conversations-py/SKILL.md @@ -96,4 +96,11 @@ with ConversationAnalysisClient(endpoint, credential) as client: } ) - print(f"Top intent: {result['result']['prediction']['topIntent']}") \ No newline at end of file + print(f"Top intent: {result['result']['prediction']['topIntent']}") + +## Reference Files + +| File | Contents | +|------|----------| +| [references/capabilities.md](references/capabilities.md) | Additional non-hero capabilities, operation-group coverage, and production checklists. | +| [references/non-hero-scenarios.md](references/non-hero-scenarios.md) | Dedicated non-hero examples for secondary/advanced scenarios. | diff --git a/.github/plugins/azure-sdk-python/skills/azure-ai-language-conversations-py/references/capabilities.md b/.github/plugins/azure-sdk-python/skills/azure-ai-language-conversations-py/references/capabilities.md new file mode 100644 index 00000000..abaae4b5 --- /dev/null +++ b/.github/plugins/azure-sdk-python/skills/azure-ai-language-conversations-py/references/capabilities.md @@ -0,0 +1,27 @@ +# azure-ai-language-conversations-py capability coverage + +**SDK/package**: `azure-ai-language-conversations` + +This index maps hero scenarios in `SKILL.md` and links non-hero scenarios documented in dedicated reference files. + +## Hero scenarios covered in SKILL.md + +- `Core workflow` + +## Non-hero scenarios + +- `Operational hardening`: Use this section for retries, timeouts, pagination, and cleanup patterns specific to this SDK. + See: [`non-hero-scenarios.md#operational-hardening`](non-hero-scenarios.md#operational-hardening) + +## Related deep-dive references + +- [`non-hero-scenarios.md`](non-hero-scenarios.md): Dedicated non-hero examples and implementation notes. + +## API breadth checklist + +- Verify client/auth mode for the environment before coding. +- Confirm operation-group/method names against current Microsoft Learn API reference. +- For Python SDKs with both sync and async clients, document both forms without a blanket preference. +- Include cleanup/delete paths for created resources in examples. +- Prefer idempotent create/update operations where available. +- Validate paging/LRO/error-handling patterns for production paths. diff --git a/.github/plugins/azure-sdk-python/skills/azure-ai-language-conversations-py/references/non-hero-scenarios.md b/.github/plugins/azure-sdk-python/skills/azure-ai-language-conversations-py/references/non-hero-scenarios.md new file mode 100644 index 00000000..d7383045 --- /dev/null +++ b/.github/plugins/azure-sdk-python/skills/azure-ai-language-conversations-py/references/non-hero-scenarios.md @@ -0,0 +1,8 @@ +# azure-ai-language-conversations-py non-hero scenarios + +These scenarios are intentionally separate from hero flows in `SKILL.md`. +They cover secondary/advanced patterns typically used after the primary end-to-end path is working. + +## Operational hardening + +Use this section for retries, timeouts, pagination, and cleanup patterns specific to this SDK. diff --git a/.github/plugins/azure-sdk-python/skills/azure-ai-ml-py/SKILL.md b/.github/plugins/azure-sdk-python/skills/azure-ai-ml-py/SKILL.md index 64ae2381..c3b6d0e1 100644 --- a/.github/plugins/azure-sdk-python/skills/azure-ai-ml-py/SKILL.md +++ b/.github/plugins/azure-sdk-python/skills/azure-ai-ml-py/SKILL.md @@ -299,3 +299,10 @@ print(f"Default: {default_ds.name}") 7. **Register models** after successful training jobs 8. **Use pipelines** for multi-step workflows 9. **Tag resources** for organization and cost tracking + +## Reference Files + +| File | Contents | +|------|----------| +| [references/capabilities.md](references/capabilities.md) | Additional non-hero capabilities, operation-group coverage, and production checklists. | +| [references/non-hero-scenarios.md](references/non-hero-scenarios.md) | Dedicated non-hero examples for secondary/advanced scenarios. | diff --git a/.github/plugins/azure-sdk-python/skills/azure-ai-ml-py/references/capabilities.md b/.github/plugins/azure-sdk-python/skills/azure-ai-ml-py/references/capabilities.md new file mode 100644 index 00000000..35896a80 --- /dev/null +++ b/.github/plugins/azure-sdk-python/skills/azure-ai-ml-py/references/capabilities.md @@ -0,0 +1,38 @@ +# azure-ai-ml-py capability coverage + +**SDK/package**: `azure-ai-ml` + +This index maps hero scenarios in `SKILL.md` and links non-hero scenarios documented in dedicated reference files. + +## Hero scenarios covered in SKILL.md + +- `Workspace Management` +- `Data Assets` +- `Model Registry` +- `Compute` + +## Non-hero scenarios + +- `Jobs`: Dedicated example and implementation notes. + See: [`non-hero-scenarios.md#jobs`](non-hero-scenarios.md#jobs) +- `Pipelines`: Dedicated example and implementation notes. + See: [`non-hero-scenarios.md#pipelines`](non-hero-scenarios.md#pipelines) +- `Environments`: Dedicated example and implementation notes. + See: [`non-hero-scenarios.md#environments`](non-hero-scenarios.md#environments) +- `Datastores`: Dedicated example and implementation notes. + See: [`non-hero-scenarios.md#datastores`](non-hero-scenarios.md#datastores) +- `MLClient Operations`: | Property | Operations | + See: [`non-hero-scenarios.md#mlclient-operations`](non-hero-scenarios.md#mlclient-operations) + +## Related deep-dive references + +- [`non-hero-scenarios.md`](non-hero-scenarios.md): Dedicated non-hero examples and implementation notes. + +## API breadth checklist + +- Verify client/auth mode for the environment before coding. +- Confirm operation-group/method names against current Microsoft Learn API reference. +- For Python SDKs with both sync and async clients, document both forms without a blanket preference. +- Include cleanup/delete paths for created resources in examples. +- Prefer idempotent create/update operations where available. +- Validate paging/LRO/error-handling patterns for production paths. diff --git a/.github/plugins/azure-sdk-python/skills/azure-ai-ml-py/references/non-hero-scenarios.md b/.github/plugins/azure-sdk-python/skills/azure-ai-ml-py/references/non-hero-scenarios.md new file mode 100644 index 00000000..f363f7b1 --- /dev/null +++ b/.github/plugins/azure-sdk-python/skills/azure-ai-ml-py/references/non-hero-scenarios.md @@ -0,0 +1,104 @@ +# azure-ai-ml-py non-hero scenarios + +These scenarios are intentionally separate from hero flows in `SKILL.md`. +They cover secondary/advanced patterns typically used after the primary end-to-end path is working. + +## Jobs + +### Command Job + +```python +from azure.ai.ml import command, Input + +job = command( + code="./src", + command="python train.py --data ${{inputs.data}} --lr ${{inputs.learning_rate}}", + inputs={ + "data": Input(type="uri_folder", path="azureml:my-dataset:1"), + "learning_rate": 0.01 + }, + environment="AzureML-sklearn-1.0-ubuntu20.04-py38-cpu@latest", + compute="cpu-cluster", + display_name="training-job" +) + +returned_job = ml_client.jobs.create_or_update(job) +print(f"Job URL: {returned_job.studio_url}") +``` + +### Monitor Job + +```python +ml_client.jobs.stream(returned_job.name) +``` + +## Pipelines + +```python +from azure.ai.ml import dsl, Input, Output +from azure.ai.ml.entities import Pipeline + +@dsl.pipeline( + compute="cpu-cluster", + description="Training pipeline" +) +def training_pipeline(data_input): + prep_step = prep_component(data=data_input) + train_step = train_component( + data=prep_step.outputs.output_data, + learning_rate=0.01 + ) + return {"model": train_step.outputs.model} + +pipeline = training_pipeline( + data_input=Input(type="uri_folder", path="azureml:my-dataset:1") +) + +pipeline_job = ml_client.jobs.create_or_update(pipeline) +``` + +## Environments + +### Create Custom Environment + +```python +from azure.ai.ml.entities import Environment + +env = Environment( + name="my-env", + version="1", + image="mcr.microsoft.com/azureml/openmpi4.1.0-ubuntu20.04", + conda_file="./environment.yml" +) + +ml_client.environments.create_or_update(env) +``` + +## Datastores + +### List Datastores + +```python +for ds in ml_client.datastores.list(): + print(f"{ds.name}: {ds.type}") +``` + +### Get Default Datastore + +```python +default_ds = ml_client.datastores.get_default() +print(f"Default: {default_ds.name}") +``` + +## MLClient Operations + +| Property | Operations | +|----------|------------| +| `workspaces` | create, get, list, delete | +| `jobs` | create_or_update, get, list, stream, cancel | +| `models` | create_or_update, get, list, archive | +| `data` | create_or_update, get, list | +| `compute` | begin_create_or_update, get, list, delete | +| `environments` | create_or_update, get, list | +| `datastores` | create_or_update, get, list, get_default | +| `components` | create_or_update, get, list | diff --git a/.github/plugins/azure-sdk-python/skills/azure-ai-textanalytics-py/SKILL.md b/.github/plugins/azure-sdk-python/skills/azure-ai-textanalytics-py/SKILL.md index dc9d0d92..3f7ec0d3 100644 --- a/.github/plugins/azure-sdk-python/skills/azure-ai-textanalytics-py/SKILL.md +++ b/.github/plugins/azure-sdk-python/skills/azure-ai-textanalytics-py/SKILL.md @@ -252,3 +252,10 @@ async def analyze(): 5. **Use async client** for high-throughput scenarios 6. **Handle document errors** — results list may contain errors for some docs 7. **Specify language** when known to improve accuracy + +## Reference Files + +| File | Contents | +|------|----------| +| [references/capabilities.md](references/capabilities.md) | Additional non-hero capabilities, operation-group coverage, and production checklists. | +| [references/non-hero-scenarios.md](references/non-hero-scenarios.md) | Dedicated non-hero examples for secondary/advanced scenarios. | diff --git a/.github/plugins/azure-sdk-python/skills/azure-ai-textanalytics-py/references/capabilities.md b/.github/plugins/azure-sdk-python/skills/azure-ai-textanalytics-py/references/capabilities.md new file mode 100644 index 00000000..19ce159a --- /dev/null +++ b/.github/plugins/azure-sdk-python/skills/azure-ai-textanalytics-py/references/capabilities.md @@ -0,0 +1,40 @@ +# azure-ai-textanalytics-py capability coverage + +**SDK/package**: `azure-ai-textanalytics` + +This index maps hero scenarios in `SKILL.md` and links non-hero scenarios documented in dedicated reference files. + +## Hero scenarios covered in SKILL.md + +- `Sentiment Analysis` +- `Entity Recognition` +- `PII Detection` +- `Key Phrase Extraction` + +## Non-hero scenarios + +- `Language Detection`: Dedicated example and implementation notes. + See: [`non-hero-scenarios.md#language-detection`](non-hero-scenarios.md#language-detection) +- `Healthcare Text Analytics`: Dedicated example and implementation notes. + See: [`non-hero-scenarios.md#healthcare-text-analytics`](non-hero-scenarios.md#healthcare-text-analytics) +- `Multiple Analysis (Batch)`: Dedicated example and implementation notes. + See: [`non-hero-scenarios.md#multiple-analysis-batch`](non-hero-scenarios.md#multiple-analysis-batch) +- `Async Client`: Dedicated example and implementation notes. + See: [`non-hero-scenarios.md#async-client`](non-hero-scenarios.md#async-client) +- `Client Types`: | Client | Purpose | + See: [`non-hero-scenarios.md#client-types`](non-hero-scenarios.md#client-types) +- `Available Operations`: | Method | Description | + See: [`non-hero-scenarios.md#available-operations`](non-hero-scenarios.md#available-operations) + +## Related deep-dive references + +- [`non-hero-scenarios.md`](non-hero-scenarios.md): Dedicated non-hero examples and implementation notes. + +## API breadth checklist + +- Verify client/auth mode for the environment before coding. +- Confirm operation-group/method names against current Microsoft Learn API reference. +- For Python SDKs with both sync and async clients, document both forms without a blanket preference. +- Include cleanup/delete paths for created resources in examples. +- Prefer idempotent create/update operations where available. +- Validate paging/LRO/error-handling patterns for production paths. diff --git a/.github/plugins/azure-sdk-python/skills/azure-ai-textanalytics-py/references/non-hero-scenarios.md b/.github/plugins/azure-sdk-python/skills/azure-ai-textanalytics-py/references/non-hero-scenarios.md new file mode 100644 index 00000000..461cb890 --- /dev/null +++ b/.github/plugins/azure-sdk-python/skills/azure-ai-textanalytics-py/references/non-hero-scenarios.md @@ -0,0 +1,104 @@ +# azure-ai-textanalytics-py non-hero scenarios + +These scenarios are intentionally separate from hero flows in `SKILL.md`. +They cover secondary/advanced patterns typically used after the primary end-to-end path is working. + +## Language Detection + +```python +documents = ["Ce document est en francais.", "This is written in English."] + +result = client.detect_language(documents) + +for doc in result: + if not doc.is_error: + print(f"Language: {doc.primary_language.name} ({doc.primary_language.iso6391_name})") + print(f"Confidence: {doc.primary_language.confidence_score:.2f}") +``` + +## Healthcare Text Analytics + +```python +documents = ["Patient has diabetes and was prescribed metformin 500mg twice daily."] + +poller = client.begin_analyze_healthcare_entities(documents) +result = poller.result() + +for doc in result: + if not doc.is_error: + for entity in doc.entities: + print(f"Entity: {entity.text}") + print(f" Category: {entity.category}") + print(f" Normalized: {entity.normalized_text}") + + # Entity links (UMLS, etc.) + for link in entity.data_sources: + print(f" Link: {link.name} - {link.entity_id}") +``` + +## Multiple Analysis (Batch) + +```python +from azure.ai.textanalytics import ( + RecognizeEntitiesAction, + ExtractKeyPhrasesAction, + AnalyzeSentimentAction +) + +documents = ["Microsoft announced new Azure AI features at Build conference."] + +poller = client.begin_analyze_actions( + documents, + actions=[ + RecognizeEntitiesAction(), + ExtractKeyPhrasesAction(), + AnalyzeSentimentAction() + ] +) + +results = poller.result() +for doc_results in results: + for result in doc_results: + if result.kind == "EntityRecognition": + print(f"Entities: {[e.text for e in result.entities]}") + elif result.kind == "KeyPhraseExtraction": + print(f"Key phrases: {result.key_phrases}") + elif result.kind == "SentimentAnalysis": + print(f"Sentiment: {result.sentiment}") +``` + +## Async Client + +```python +from azure.ai.textanalytics.aio import TextAnalyticsClient +from azure.identity.aio import DefaultAzureCredential + +async def analyze(): + async with DefaultAzureCredential() as credential: + async with TextAnalyticsClient( + endpoint=endpoint, + credential=credential + ) as client: + result = await client.analyze_sentiment(documents) + # Process results... +``` + +## Client Types + +| Client | Purpose | +|--------|---------| +| `TextAnalyticsClient` | All text analytics operations | +| `TextAnalyticsClient` (aio) | Async version | + +## Available Operations + +| Method | Description | +|--------|-------------| +| `analyze_sentiment` | Sentiment analysis with opinion mining | +| `recognize_entities` | Named entity recognition | +| `recognize_pii_entities` | PII detection and redaction | +| `recognize_linked_entities` | Entity linking to Wikipedia | +| `extract_key_phrases` | Key phrase extraction | +| `detect_language` | Language detection | +| `begin_analyze_healthcare_entities` | Healthcare NLP (long-running) | +| `begin_analyze_actions` | Multiple analyses in batch | diff --git a/.github/plugins/azure-sdk-python/skills/azure-ai-transcription-py/SKILL.md b/.github/plugins/azure-sdk-python/skills/azure-ai-transcription-py/SKILL.md index a6fd15e7..6f43ff43 100644 --- a/.github/plugins/azure-sdk-python/skills/azure-ai-transcription-py/SKILL.md +++ b/.github/plugins/azure-sdk-python/skills/azure-ai-transcription-py/SKILL.md @@ -24,12 +24,21 @@ pip install azure-ai-transcription ```bash TRANSCRIPTION_ENDPOINT=https://.cognitiveservices.azure.com -TRANSCRIPTION_KEY= +TRANSCRIPTION_KEY= # Required for all auth paths (this SDK currently uses key auth) ``` -## Authentication +## Authentication & Lifecycle -Use subscription key authentication (DefaultAzureCredential is not supported for this client): +> **🔑 Two rules apply to every code sample below:** +> +> 1. **This SDK currently requires API-key authentication.** `DefaultAzureCredential`/Entra ID isn't available for this client yet, so use `TRANSCRIPTION_KEY` from environment variables (never hardcoded in code). +> 2. **Wrap every client in a context manager** so HTTP transports and sockets are released deterministically: +> - Sync: `with (...) as client:` +> - Async: `async with (...) as client:` +> +> Snippets may abbreviate this setup, but production code should always follow both rules. + +Use subscription key authentication: ```python import os @@ -88,3 +97,10 @@ with TranscriptionClient( 6. **Specify language** to improve recognition accuracy 7. **Handle streaming backpressure** for real-time transcription 8. **Close transcription sessions** when complete + +## Reference Files + +| File | Contents | +|------|----------| +| [references/capabilities.md](references/capabilities.md) | Additional non-hero capabilities, operation-group coverage, and production checklists. | +| [references/non-hero-scenarios.md](references/non-hero-scenarios.md) | Dedicated non-hero examples for secondary/advanced scenarios. | diff --git a/.github/plugins/azure-sdk-python/skills/azure-ai-transcription-py/references/capabilities.md b/.github/plugins/azure-sdk-python/skills/azure-ai-transcription-py/references/capabilities.md new file mode 100644 index 00000000..9f35147f --- /dev/null +++ b/.github/plugins/azure-sdk-python/skills/azure-ai-transcription-py/references/capabilities.md @@ -0,0 +1,28 @@ +# azure-ai-transcription-py capability coverage + +**SDK/package**: `azure-ai-transcription` + +This index maps hero scenarios in `SKILL.md` and links non-hero scenarios documented in dedicated reference files. + +## Hero scenarios covered in SKILL.md + +- `Transcription (Batch)` +- `Transcription (Real-time)` + +## Non-hero scenarios + +- `Operational hardening`: Use this section for retries, timeouts, pagination, and cleanup patterns specific to this SDK. + See: [`non-hero-scenarios.md#operational-hardening`](non-hero-scenarios.md#operational-hardening) + +## Related deep-dive references + +- [`non-hero-scenarios.md`](non-hero-scenarios.md): Dedicated non-hero examples and implementation notes. + +## API breadth checklist + +- Verify client/auth mode for the environment before coding. +- Confirm operation-group/method names against current Microsoft Learn API reference. +- For Python SDKs with both sync and async clients, document both forms without a blanket preference. +- Include cleanup/delete paths for created resources in examples. +- Prefer idempotent create/update operations where available. +- Validate paging/LRO/error-handling patterns for production paths. diff --git a/.github/plugins/azure-sdk-python/skills/azure-ai-transcription-py/references/non-hero-scenarios.md b/.github/plugins/azure-sdk-python/skills/azure-ai-transcription-py/references/non-hero-scenarios.md new file mode 100644 index 00000000..a1532705 --- /dev/null +++ b/.github/plugins/azure-sdk-python/skills/azure-ai-transcription-py/references/non-hero-scenarios.md @@ -0,0 +1,8 @@ +# azure-ai-transcription-py non-hero scenarios + +These scenarios are intentionally separate from hero flows in `SKILL.md`. +They cover secondary/advanced patterns typically used after the primary end-to-end path is working. + +## Operational hardening + +Use this section for retries, timeouts, pagination, and cleanup patterns specific to this SDK. diff --git a/.github/plugins/azure-sdk-python/skills/azure-ai-translation-document-py/SKILL.md b/.github/plugins/azure-sdk-python/skills/azure-ai-translation-document-py/SKILL.md index 07379f43..4cf2eca9 100644 --- a/.github/plugins/azure-sdk-python/skills/azure-ai-translation-document-py/SKILL.md +++ b/.github/plugins/azure-sdk-python/skills/azure-ai-translation-document-py/SKILL.md @@ -276,3 +276,10 @@ async def translate_documents(): 7. **Separate target containers** for each language 8. **Use async client** for multiple concurrent jobs 9. **Check supported formats** before submitting documents + +## Reference Files + +| File | Contents | +|------|----------| +| [references/capabilities.md](references/capabilities.md) | Additional non-hero capabilities, operation-group coverage, and production checklists. | +| [references/non-hero-scenarios.md](references/non-hero-scenarios.md) | Dedicated non-hero examples for secondary/advanced scenarios. | diff --git a/.github/plugins/azure-sdk-python/skills/azure-ai-translation-document-py/references/capabilities.md b/.github/plugins/azure-sdk-python/skills/azure-ai-translation-document-py/references/capabilities.md new file mode 100644 index 00000000..d0ead4f4 --- /dev/null +++ b/.github/plugins/azure-sdk-python/skills/azure-ai-translation-document-py/references/capabilities.md @@ -0,0 +1,44 @@ +# azure-ai-translation-document-py capability coverage + +**SDK/package**: `azure-ai-translation-document` + +This index maps hero scenarios in `SKILL.md` and links non-hero scenarios documented in dedicated reference files. + +## Hero scenarios covered in SKILL.md + +- `Basic Document Translation` +- `Multiple Target Languages` +- `Translate Single Document` +- `Check Translation Status` + +## Non-hero scenarios + +- `List Document Statuses`: Dedicated example and implementation notes. + See: [`non-hero-scenarios.md#list-document-statuses`](non-hero-scenarios.md#list-document-statuses) +- `Cancel Translation`: Dedicated example and implementation notes. + See: [`non-hero-scenarios.md#cancel-translation`](non-hero-scenarios.md#cancel-translation) +- `Using Glossary`: Dedicated example and implementation notes. + See: [`non-hero-scenarios.md#using-glossary`](non-hero-scenarios.md#using-glossary) +- `Supported Document Formats`: Dedicated example and implementation notes. + See: [`non-hero-scenarios.md#supported-document-formats`](non-hero-scenarios.md#supported-document-formats) +- `Supported Languages`: Dedicated example and implementation notes. + See: [`non-hero-scenarios.md#supported-languages`](non-hero-scenarios.md#supported-languages) +- `Async Client`: Dedicated example and implementation notes. + See: [`non-hero-scenarios.md#async-client`](non-hero-scenarios.md#async-client) +- `Supported Formats`: | Category | Formats | + See: [`non-hero-scenarios.md#supported-formats`](non-hero-scenarios.md#supported-formats) +- `Storage Requirements`: - Source and target containers must be Azure Blob Storage + See: [`non-hero-scenarios.md#storage-requirements`](non-hero-scenarios.md#storage-requirements) + +## Related deep-dive references + +- [`non-hero-scenarios.md`](non-hero-scenarios.md): Dedicated non-hero examples and implementation notes. + +## API breadth checklist + +- Verify client/auth mode for the environment before coding. +- Confirm operation-group/method names against current Microsoft Learn API reference. +- For Python SDKs with both sync and async clients, document both forms without a blanket preference. +- Include cleanup/delete paths for created resources in examples. +- Prefer idempotent create/update operations where available. +- Validate paging/LRO/error-handling patterns for production paths. diff --git a/.github/plugins/azure-sdk-python/skills/azure-ai-translation-document-py/references/non-hero-scenarios.md b/.github/plugins/azure-sdk-python/skills/azure-ai-translation-document-py/references/non-hero-scenarios.md new file mode 100644 index 00000000..cf9cb490 --- /dev/null +++ b/.github/plugins/azure-sdk-python/skills/azure-ai-translation-document-py/references/non-hero-scenarios.md @@ -0,0 +1,105 @@ +# azure-ai-translation-document-py non-hero scenarios + +These scenarios are intentionally separate from hero flows in `SKILL.md`. +They cover secondary/advanced patterns typically used after the primary end-to-end path is working. + +## List Document Statuses + +```python +# Get status of individual documents in a job +operation_id = poller.id +document_statuses = client.list_document_statuses(operation_id) + +for doc in document_statuses: + print(f"Document: {doc.source_document_url}") + print(f" Status: {doc.status}") + print(f" Translated to: {doc.translated_to}") + if doc.error: + print(f" Error: {doc.error.message}") +``` + +## Cancel Translation + +```python +# Cancel a running translation +client.cancel_translation(operation_id) +``` + +## Using Glossary + +```python +from azure.ai.translation.document import TranslationGlossary + +poller = client.begin_translation( + inputs=[ + DocumentTranslationInput( + source_url=source_url, + targets=[ + TranslationTarget( + target_url=target_url, + language="es", + glossaries=[ + TranslationGlossary( + glossary_url="https://.blob.core.windows.net/glossary/terms.csv?", + file_format="csv" + ) + ] + ) + ] + ) + ] +) +``` + +## Supported Document Formats + +```python +# Get supported formats +formats = client.get_supported_document_formats() + +for fmt in formats: + print(f"Format: {fmt.format}") + print(f" Extensions: {fmt.file_extensions}") + print(f" Content types: {fmt.content_types}") +``` + +## Supported Languages + +```python +# Get supported languages +languages = client.get_supported_languages() + +for lang in languages: + print(f"Language: {lang.name} ({lang.code})") +``` + +## Async Client + +```python +from azure.ai.translation.document.aio import DocumentTranslationClient +from azure.identity.aio import DefaultAzureCredential + +async def translate_documents(): + async with DefaultAzureCredential() as credential: + async with DocumentTranslationClient( + endpoint=endpoint, + credential=credential, + ) as client: + poller = await client.begin_translation(inputs=[...]) + result = await poller.result() +``` + +## Supported Formats + +| Category | Formats | +|----------|---------| +| Documents | DOCX, PDF, PPTX, XLSX, HTML, TXT, RTF | +| Structured | CSV, TSV, JSON, XML | +| Localization | XLIFF, XLF, MHTML | + +## Storage Requirements + +- Source and target containers must be Azure Blob Storage +- Use SAS tokens with appropriate permissions: + - Source: Read, List + - Target: Write, List diff --git a/.github/plugins/azure-sdk-python/skills/azure-ai-translation-text-py/SKILL.md b/.github/plugins/azure-sdk-python/skills/azure-ai-translation-text-py/SKILL.md index 11d6f6fc..e8ed670c 100644 --- a/.github/plugins/azure-sdk-python/skills/azure-ai-translation-text-py/SKILL.md +++ b/.github/plugins/azure-sdk-python/skills/azure-ai-translation-text-py/SKILL.md @@ -298,3 +298,10 @@ async def translate_text(): 7. **Handle profanity** appropriately for your application 8. **Use html text_type** when translating HTML content 9. **Include alignment** for applications needing word mapping + +## Reference Files + +| File | Contents | +|------|----------| +| [references/capabilities.md](references/capabilities.md) | Additional non-hero capabilities, operation-group coverage, and production checklists. | +| [references/non-hero-scenarios.md](references/non-hero-scenarios.md) | Dedicated non-hero examples for secondary/advanced scenarios. | diff --git a/.github/plugins/azure-sdk-python/skills/azure-ai-translation-text-py/references/capabilities.md b/.github/plugins/azure-sdk-python/skills/azure-ai-translation-text-py/references/capabilities.md new file mode 100644 index 00000000..379de29c --- /dev/null +++ b/.github/plugins/azure-sdk-python/skills/azure-ai-translation-text-py/references/capabilities.md @@ -0,0 +1,44 @@ +# azure-ai-translation-text-py capability coverage + +**SDK/package**: `azure-ai-translation-text` + +This index maps hero scenarios in `SKILL.md` and links non-hero scenarios documented in dedicated reference files. + +## Hero scenarios covered in SKILL.md + +- `Basic Translation` +- `Translate to Multiple Languages` +- `Specify Source Language` +- `Language Detection` + +## Non-hero scenarios + +- `Transliteration`: Convert text from one script to another: + See: [`non-hero-scenarios.md#transliteration`](non-hero-scenarios.md#transliteration) +- `Dictionary Lookup`: Find alternate translations and definitions: + See: [`non-hero-scenarios.md#dictionary-lookup`](non-hero-scenarios.md#dictionary-lookup) +- `Dictionary Examples`: Get usage examples for translations: + See: [`non-hero-scenarios.md#dictionary-examples`](non-hero-scenarios.md#dictionary-examples) +- `Get Supported Languages`: Dedicated example and implementation notes. + See: [`non-hero-scenarios.md#get-supported-languages`](non-hero-scenarios.md#get-supported-languages) +- `Break Sentence`: Identify sentence boundaries: + See: [`non-hero-scenarios.md#break-sentence`](non-hero-scenarios.md#break-sentence) +- `Translation Options`: Dedicated example and implementation notes. + See: [`non-hero-scenarios.md#translation-options`](non-hero-scenarios.md#translation-options) +- `Async Client`: Dedicated example and implementation notes. + See: [`non-hero-scenarios.md#async-client`](non-hero-scenarios.md#async-client) +- `Client Methods`: | Method | Description | + See: [`non-hero-scenarios.md#client-methods`](non-hero-scenarios.md#client-methods) + +## Related deep-dive references + +- [`non-hero-scenarios.md`](non-hero-scenarios.md): Dedicated non-hero examples and implementation notes. + +## API breadth checklist + +- Verify client/auth mode for the environment before coding. +- Confirm operation-group/method names against current Microsoft Learn API reference. +- For Python SDKs with both sync and async clients, document both forms without a blanket preference. +- Include cleanup/delete paths for created resources in examples. +- Prefer idempotent create/update operations where available. +- Validate paging/LRO/error-handling patterns for production paths. diff --git a/.github/plugins/azure-sdk-python/skills/azure-ai-translation-text-py/references/non-hero-scenarios.md b/.github/plugins/azure-sdk-python/skills/azure-ai-translation-text-py/references/non-hero-scenarios.md new file mode 100644 index 00000000..c2b870e2 --- /dev/null +++ b/.github/plugins/azure-sdk-python/skills/azure-ai-translation-text-py/references/non-hero-scenarios.md @@ -0,0 +1,150 @@ +# azure-ai-translation-text-py non-hero scenarios + +These scenarios are intentionally separate from hero flows in `SKILL.md`. +They cover secondary/advanced patterns typically used after the primary end-to-end path is working. + +## Transliteration + +Convert text from one script to another: + +```python +result = client.transliterate( + body=["konnichiwa"], + language="ja", + from_script="Latn", # From Latin script + to_script="Jpan" # To Japanese script +) + +for item in result: + print(f"Transliterated: {item.text}") + print(f"Script: {item.script}") +``` + +## Dictionary Lookup + +Find alternate translations and definitions: + +```python +result = client.lookup_dictionary_entries( + body=["fly"], + from_parameter="en", + to="es" +) + +for item in result: + print(f"Source: {item.normalized_source} ({item.display_source})") + for translation in item.translations: + print(f" Translation: {translation.normalized_target}") + print(f" Part of speech: {translation.pos_tag}") + print(f" Confidence: {translation.confidence:.2f}") +``` + +## Dictionary Examples + +Get usage examples for translations: + +```python +from azure.ai.translation.text.models import DictionaryExampleTextItem + +result = client.lookup_dictionary_examples( + body=[DictionaryExampleTextItem(text="fly", translation="volar")], + from_parameter="en", + to="es" +) + +for item in result: + for example in item.examples: + print(f"Source: {example.source_prefix}{example.source_term}{example.source_suffix}") + print(f"Target: {example.target_prefix}{example.target_term}{example.target_suffix}") +``` + +## Get Supported Languages + +```python +# Get all supported languages +languages = client.get_supported_languages() + +# Translation languages +print("Translation languages:") +for code, lang in languages.translation.items(): + print(f" {code}: {lang.name} ({lang.native_name})") + +# Transliteration languages +print("\nTransliteration languages:") +for code, lang in languages.transliteration.items(): + print(f" {code}: {lang.name}") + for script in lang.scripts: + print(f" {script.code} -> {[t.code for t in script.to_scripts]}") + +# Dictionary languages +print("\nDictionary languages:") +for code, lang in languages.dictionary.items(): + print(f" {code}: {lang.name}") +``` + +## Break Sentence + +Identify sentence boundaries: + +```python +result = client.find_sentence_boundaries( + body=["Hello! How are you? I hope you are well."], + language="en" +) + +for item in result: + print(f"Sentence lengths: {item.sent_len}") +``` + +## Translation Options + +```python +result = client.translate( + body=["Hello, world!"], + to=["de"], + text_type="html", # "plain" or "html" + profanity_action="Marked", # "NoAction", "Deleted", "Marked" + profanity_marker="Asterisk", # "Asterisk", "Tag" + include_alignment=True, # Include word alignment + include_sentence_length=True # Include sentence boundaries +) + +for item in result: + translation = item.translations[0] + print(f"Translated: {translation.text}") + if translation.alignment: + print(f"Alignment: {translation.alignment.proj}") + if translation.sent_len: + print(f"Sentence lengths: {translation.sent_len.src_sent_len}") +``` + +## Async Client + +```python +from azure.ai.translation.text.aio import TextTranslationClient +from azure.identity.aio import DefaultAzureCredential + +async def translate_text(): + async with DefaultAzureCredential() as credential: + async with TextTranslationClient( + credential=credential, + endpoint=endpoint, + ) as client: + result = await client.translate( + body=["Hello, world!"], + to=["es"] + ) + print(result[0].translations[0].text) +``` + +## Client Methods + +| Method | Description | +|--------|-------------| +| `translate` | Translate text to one or more languages | +| `transliterate` | Convert text between scripts | +| `detect` | Detect language of text | +| `find_sentence_boundaries` | Identify sentence boundaries | +| `lookup_dictionary_entries` | Dictionary lookup for translations | +| `lookup_dictionary_examples` | Get usage examples | +| `get_supported_languages` | List supported languages | diff --git a/.github/plugins/azure-sdk-python/skills/azure-ai-vision-imageanalysis-py/SKILL.md b/.github/plugins/azure-sdk-python/skills/azure-ai-vision-imageanalysis-py/SKILL.md index ba1393b7..adaaf3c0 100644 --- a/.github/plugins/azure-sdk-python/skills/azure-ai-vision-imageanalysis-py/SKILL.md +++ b/.github/plugins/azure-sdk-python/skills/azure-ai-vision-imageanalysis-py/SKILL.md @@ -291,3 +291,10 @@ except HttpResponseError as e: 7. **Specify language** for localized captions 8. **Use smart_crops_aspect_ratios** matching your thumbnail requirements 9. **Cache results** when analyzing the same image multiple times + +## Reference Files + +| File | Contents | +|------|----------| +| [references/capabilities.md](references/capabilities.md) | Additional non-hero capabilities, operation-group coverage, and production checklists. | +| [references/non-hero-scenarios.md](references/non-hero-scenarios.md) | Dedicated non-hero examples for secondary/advanced scenarios. | diff --git a/.github/plugins/azure-sdk-python/skills/azure-ai-vision-imageanalysis-py/references/capabilities.md b/.github/plugins/azure-sdk-python/skills/azure-ai-vision-imageanalysis-py/references/capabilities.md new file mode 100644 index 00000000..b24da438 --- /dev/null +++ b/.github/plugins/azure-sdk-python/skills/azure-ai-vision-imageanalysis-py/references/capabilities.md @@ -0,0 +1,46 @@ +# azure-ai-vision-imageanalysis-py capability coverage + +**SDK/package**: `azure-ai-vision-imageanalysis` + +This index maps hero scenarios in `SKILL.md` and links non-hero scenarios documented in dedicated reference files. + +## Hero scenarios covered in SKILL.md + +- `Analyze Image from URL` +- `Analyze Image from File` +- `Image Caption` +- `Dense Captions (Multiple Regions)` + +## Non-hero scenarios + +- `Tags`: Dedicated example and implementation notes. + See: [`non-hero-scenarios.md#tags`](non-hero-scenarios.md#tags) +- `Object Detection`: Dedicated example and implementation notes. + See: [`non-hero-scenarios.md#object-detection`](non-hero-scenarios.md#object-detection) +- `OCR (Text Extraction)`: Dedicated example and implementation notes. + See: [`non-hero-scenarios.md#ocr-text-extraction`](non-hero-scenarios.md#ocr-text-extraction) +- `People Detection`: Dedicated example and implementation notes. + See: [`non-hero-scenarios.md#people-detection`](non-hero-scenarios.md#people-detection) +- `Smart Cropping`: Dedicated example and implementation notes. + See: [`non-hero-scenarios.md#smart-cropping`](non-hero-scenarios.md#smart-cropping) +- `Async Client`: Dedicated example and implementation notes. + See: [`non-hero-scenarios.md#async-client`](non-hero-scenarios.md#async-client) +- `Visual Features`: | Feature | Description | + See: [`non-hero-scenarios.md#visual-features`](non-hero-scenarios.md#visual-features) +- `Error Handling`: Dedicated example and implementation notes. + See: [`non-hero-scenarios.md#error-handling`](non-hero-scenarios.md#error-handling) +- `Image Requirements`: - Formats: JPEG, PNG, GIF, BMP, WEBP, ICO, TIFF, MPO + See: [`non-hero-scenarios.md#image-requirements`](non-hero-scenarios.md#image-requirements) + +## Related deep-dive references + +- [`non-hero-scenarios.md`](non-hero-scenarios.md): Dedicated non-hero examples and implementation notes. + +## API breadth checklist + +- Verify client/auth mode for the environment before coding. +- Confirm operation-group/method names against current Microsoft Learn API reference. +- For Python SDKs with both sync and async clients, document both forms without a blanket preference. +- Include cleanup/delete paths for created resources in examples. +- Prefer idempotent create/update operations where available. +- Validate paging/LRO/error-handling patterns for production paths. diff --git a/.github/plugins/azure-sdk-python/skills/azure-ai-vision-imageanalysis-py/references/non-hero-scenarios.md b/.github/plugins/azure-sdk-python/skills/azure-ai-vision-imageanalysis-py/references/non-hero-scenarios.md new file mode 100644 index 00000000..fe519431 --- /dev/null +++ b/.github/plugins/azure-sdk-python/skills/azure-ai-vision-imageanalysis-py/references/non-hero-scenarios.md @@ -0,0 +1,137 @@ +# azure-ai-vision-imageanalysis-py non-hero scenarios + +These scenarios are intentionally separate from hero flows in `SKILL.md`. +They cover secondary/advanced patterns typically used after the primary end-to-end path is working. + +## Tags + +```python +result = client.analyze_from_url( + image_url=image_url, + visual_features=[VisualFeatures.TAGS] +) + +if result.tags: + for tag in result.tags.list: + print(f"Tag: {tag.name} (confidence: {tag.confidence:.2f})") +``` + +## Object Detection + +```python +result = client.analyze_from_url( + image_url=image_url, + visual_features=[VisualFeatures.OBJECTS] +) + +if result.objects: + for obj in result.objects.list: + print(f"Object: {obj.tags[0].name}") + print(f" Confidence: {obj.tags[0].confidence:.2f}") + box = obj.bounding_box + print(f" Bounding box: x={box.x}, y={box.y}, w={box.width}, h={box.height}") +``` + +## OCR (Text Extraction) + +```python +result = client.analyze_from_url( + image_url=image_url, + visual_features=[VisualFeatures.READ] +) + +if result.read: + for block in result.read.blocks: + for line in block.lines: + print(f"Line: {line.text}") + print(f" Bounding polygon: {line.bounding_polygon}") + + # Word-level details + for word in line.words: + print(f" Word: {word.text} (confidence: {word.confidence:.2f})") +``` + +## People Detection + +```python +result = client.analyze_from_url( + image_url=image_url, + visual_features=[VisualFeatures.PEOPLE] +) + +if result.people: + for person in result.people.list: + print(f"Person detected:") + print(f" Confidence: {person.confidence:.2f}") + box = person.bounding_box + print(f" Bounding box: x={box.x}, y={box.y}, w={box.width}, h={box.height}") +``` + +## Smart Cropping + +```python +result = client.analyze_from_url( + image_url=image_url, + visual_features=[VisualFeatures.SMART_CROPS], + smart_crops_aspect_ratios=[0.9, 1.33, 1.78] # Portrait, 4:3, 16:9 +) + +if result.smart_crops: + for crop in result.smart_crops.list: + print(f"Aspect ratio: {crop.aspect_ratio}") + box = crop.bounding_box + print(f" Crop region: x={box.x}, y={box.y}, w={box.width}, h={box.height}") +``` + +## Async Client + +```python +from azure.ai.vision.imageanalysis.aio import ImageAnalysisClient +from azure.identity.aio import DefaultAzureCredential + +async def analyze_image(): + async with DefaultAzureCredential() as credential: + async with ImageAnalysisClient( + endpoint=endpoint, + credential=credential + ) as client: + result = await client.analyze_from_url( + image_url=image_url, + visual_features=[VisualFeatures.CAPTION] + ) + print(result.caption.text) +``` + +## Visual Features + +| Feature | Description | +|---------|-------------| +| `CAPTION` | Single sentence describing the image | +| `DENSE_CAPTIONS` | Captions for multiple regions | +| `TAGS` | Content tags (objects, scenes, actions) | +| `OBJECTS` | Object detection with bounding boxes | +| `READ` | OCR text extraction | +| `PEOPLE` | People detection with bounding boxes | +| `SMART_CROPS` | Suggested crop regions for thumbnails | + +## Error Handling + +```python +from azure.core.exceptions import HttpResponseError + +try: + result = client.analyze_from_url( + image_url=image_url, + visual_features=[VisualFeatures.CAPTION] + ) +except HttpResponseError as e: + print(f"Status code: {e.status_code}") + print(f"Reason: {e.reason}") + print(f"Message: {e.error.message}") +``` + +## Image Requirements + +- Formats: JPEG, PNG, GIF, BMP, WEBP, ICO, TIFF, MPO +- Max size: 20 MB +- Dimensions: 50x50 to 16000x16000 pixels diff --git a/.github/plugins/azure-sdk-python/skills/azure-ai-voicelive-py/SKILL.md b/.github/plugins/azure-sdk-python/skills/azure-ai-voicelive-py/SKILL.md index 1a3f3aa1..512d0686 100644 --- a/.github/plugins/azure-sdk-python/skills/azure-ai-voicelive-py/SKILL.md +++ b/.github/plugins/azure-sdk-python/skills/azure-ai-voicelive-py/SKILL.md @@ -329,7 +329,7 @@ except ConnectionError as e: ## Best Practices -1. **This SDK is async-only; use `azure.ai.voicelive.aio` throughout.** Do not try to pair it with sync clients from other Azure SDKs in the same call path — keep the whole request path async. +1. **This SDK is async-only; use the `.aio` namespace throughout.** Do not try to pair it with sync clients from other Azure SDKs in the same call path — keep the whole request path async. 2. **Always use context managers for clients and async credentials.** Wrap every connection in `async with connect(...) as conn:`. For async `DefaultAzureCredential` from `azure.identity.aio`, also use `async with credential:` so tokens and transports are cleaned up. ## References diff --git a/.github/plugins/azure-sdk-python/skills/azure-appconfiguration-py/SKILL.md b/.github/plugins/azure-sdk-python/skills/azure-appconfiguration-py/SKILL.md index 9fe7feb9..bd07f043 100644 --- a/.github/plugins/azure-sdk-python/skills/azure-appconfiguration-py/SKILL.md +++ b/.github/plugins/azure-sdk-python/skills/azure-appconfiguration-py/SKILL.md @@ -256,3 +256,10 @@ async def main(): 7. **Use Entra ID** instead of connection strings in production 8. **Refresh settings periodically** in long-running applications 9. **Use feature flags** for gradual rollouts and A/B testing + +## Reference Files + +| File | Contents | +|------|----------| +| [references/capabilities.md](references/capabilities.md) | Additional non-hero capabilities, operation-group coverage, and production checklists. | +| [references/non-hero-scenarios.md](references/non-hero-scenarios.md) | Dedicated non-hero examples for secondary/advanced scenarios. | diff --git a/.github/plugins/azure-sdk-python/skills/azure-appconfiguration-py/references/capabilities.md b/.github/plugins/azure-sdk-python/skills/azure-appconfiguration-py/references/capabilities.md new file mode 100644 index 00000000..9b454b1c --- /dev/null +++ b/.github/plugins/azure-sdk-python/skills/azure-appconfiguration-py/references/capabilities.md @@ -0,0 +1,34 @@ +# azure-appconfiguration-py capability coverage + +**SDK/package**: `azure-appconfiguration` + +This index maps hero scenarios in `SKILL.md` and links non-hero scenarios documented in dedicated reference files. + +## Hero scenarios covered in SKILL.md + +- `Configuration Settings` +- `List Settings` +- `Feature Flags` +- `Read-Only Settings` + +## Non-hero scenarios + +- `Snapshots`: Dedicated example and implementation notes. + See: [`non-hero-scenarios.md#snapshots`](non-hero-scenarios.md#snapshots) +- `Async Client`: Dedicated example and implementation notes. + See: [`non-hero-scenarios.md#async-client`](non-hero-scenarios.md#async-client) +- `Client Operations`: | Operation | Description | + See: [`non-hero-scenarios.md#client-operations`](non-hero-scenarios.md#client-operations) + +## Related deep-dive references + +- [`non-hero-scenarios.md`](non-hero-scenarios.md): Dedicated non-hero examples and implementation notes. + +## API breadth checklist + +- Verify client/auth mode for the environment before coding. +- Confirm operation-group/method names against current Microsoft Learn API reference. +- For Python SDKs with both sync and async clients, document both forms without a blanket preference. +- Include cleanup/delete paths for created resources in examples. +- Prefer idempotent create/update operations where available. +- Validate paging/LRO/error-handling patterns for production paths. diff --git a/.github/plugins/azure-sdk-python/skills/azure-appconfiguration-py/references/non-hero-scenarios.md b/.github/plugins/azure-sdk-python/skills/azure-appconfiguration-py/references/non-hero-scenarios.md new file mode 100644 index 00000000..fe023531 --- /dev/null +++ b/.github/plugins/azure-sdk-python/skills/azure-appconfiguration-py/references/non-hero-scenarios.md @@ -0,0 +1,60 @@ +# azure-appconfiguration-py non-hero scenarios + +These scenarios are intentionally separate from hero flows in `SKILL.md`. +They cover secondary/advanced patterns typically used after the primary end-to-end path is working. + +## Snapshots + +### Create Snapshot + +```python +from azure.appconfiguration import ConfigurationSnapshot, ConfigurationSettingFilter + +snapshot = ConfigurationSnapshot( + name="v1-snapshot", + filters=[ + ConfigurationSettingFilter(key="app:*", label="production") + ] +) + +created = client.begin_create_snapshot( + name="v1-snapshot", + snapshot=snapshot +).result() +``` + +### List Snapshot Settings + +```python +settings = client.list_configuration_settings( + snapshot_name="v1-snapshot" +) +``` + +## Async Client + +```python +from azure.appconfiguration.aio import AzureAppConfigurationClient +from azure.identity.aio import DefaultAzureCredential + +async def main(): + async with DefaultAzureCredential() as credential: + async with AzureAppConfigurationClient( + base_url=endpoint, + credential=credential + ) as client: + setting = await client.get_configuration_setting(key="app:message") + print(setting.value) +``` + +## Client Operations + +| Operation | Description | +|-----------|-------------| +| `get_configuration_setting` | Get single setting | +| `set_configuration_setting` | Create or update setting | +| `delete_configuration_setting` | Delete setting | +| `list_configuration_settings` | List with filters | +| `set_read_only` | Lock/unlock setting | +| `begin_create_snapshot` | Create point-in-time snapshot | +| `list_snapshots` | List all snapshots | diff --git a/.github/plugins/azure-sdk-python/skills/azure-containerregistry-py/SKILL.md b/.github/plugins/azure-sdk-python/skills/azure-containerregistry-py/SKILL.md index e1a8305c..fb6ab982 100644 --- a/.github/plugins/azure-sdk-python/skills/azure-containerregistry-py/SKILL.md +++ b/.github/plugins/azure-sdk-python/skills/azure-containerregistry-py/SKILL.md @@ -273,3 +273,10 @@ for manifest in client.list_manifest_properties("my-image"): 7. **Use async client** for high-throughput operations 8. **Order by last_updated** to find recent/old images 9. **Check manifest.tags** before deleting to avoid removing tagged images + +## Reference Files + +| File | Contents | +|------|----------| +| [references/capabilities.md](references/capabilities.md) | Additional non-hero capabilities, operation-group coverage, and production checklists. | +| [references/non-hero-scenarios.md](references/non-hero-scenarios.md) | Dedicated non-hero examples for secondary/advanced scenarios. | diff --git a/.github/plugins/azure-sdk-python/skills/azure-containerregistry-py/references/capabilities.md b/.github/plugins/azure-sdk-python/skills/azure-containerregistry-py/references/capabilities.md new file mode 100644 index 00000000..bea1d77b --- /dev/null +++ b/.github/plugins/azure-sdk-python/skills/azure-containerregistry-py/references/capabilities.md @@ -0,0 +1,38 @@ +# azure-containerregistry-py capability coverage + +**SDK/package**: `azure-containerregistry` + +This index maps hero scenarios in `SKILL.md` and links non-hero scenarios documented in dedicated reference files. + +## Hero scenarios covered in SKILL.md + +- `List Repositories` +- `Repository Operations` +- `List Tags` +- `Manifest Operations` + +## Non-hero scenarios + +- `Tag Operations`: Dedicated example and implementation notes. + See: [`non-hero-scenarios.md#tag-operations`](non-hero-scenarios.md#tag-operations) +- `Upload and Download Artifacts`: Dedicated example and implementation notes. + See: [`non-hero-scenarios.md#upload-and-download-artifacts`](non-hero-scenarios.md#upload-and-download-artifacts) +- `Async Client`: Dedicated example and implementation notes. + See: [`non-hero-scenarios.md#async-client`](non-hero-scenarios.md#async-client) +- `Clean Up Old Images`: Dedicated example and implementation notes. + See: [`non-hero-scenarios.md#clean-up-old-images`](non-hero-scenarios.md#clean-up-old-images) +- `Client Operations`: | Operation | Description | + See: [`non-hero-scenarios.md#client-operations`](non-hero-scenarios.md#client-operations) + +## Related deep-dive references + +- [`non-hero-scenarios.md`](non-hero-scenarios.md): Dedicated non-hero examples and implementation notes. + +## API breadth checklist + +- Verify client/auth mode for the environment before coding. +- Confirm operation-group/method names against current Microsoft Learn API reference. +- For Python SDKs with both sync and async clients, document both forms without a blanket preference. +- Include cleanup/delete paths for created resources in examples. +- Prefer idempotent create/update operations where available. +- Validate paging/LRO/error-handling patterns for production paths. diff --git a/.github/plugins/azure-sdk-python/skills/azure-containerregistry-py/references/non-hero-scenarios.md b/.github/plugins/azure-sdk-python/skills/azure-containerregistry-py/references/non-hero-scenarios.md new file mode 100644 index 00000000..daa07c57 --- /dev/null +++ b/.github/plugins/azure-sdk-python/skills/azure-containerregistry-py/references/non-hero-scenarios.md @@ -0,0 +1,80 @@ +# azure-containerregistry-py non-hero scenarios + +These scenarios are intentionally separate from hero flows in `SKILL.md`. +They cover secondary/advanced patterns typically used after the primary end-to-end path is working. + +## Tag Operations + +### Get Tag Properties + +```python +tag = client.get_tag_properties("my-image", "latest") +print(f"Digest: {tag.digest}") +print(f"Created: {tag.created_on}") +``` + +### Delete Tag + +```python +client.delete_tag("my-image", "old-tag") +``` + +## Upload and Download Artifacts + +```python +from azure.containerregistry import ContainerRegistryClient + +with ContainerRegistryClient(endpoint, DefaultAzureCredential()) as client: + # Download manifest + manifest = client.download_manifest("my-image", "latest") + print(f"Media type: {manifest.media_type}") + print(f"Digest: {manifest.digest}") + + # Download blob + blob = client.download_blob("my-image", "sha256:abc123...") + with open("layer.tar.gz", "wb") as f: + for chunk in blob: + f.write(chunk) +``` + +## Async Client + +```python +from azure.containerregistry.aio import ContainerRegistryClient +from azure.identity.aio import DefaultAzureCredential + +async def list_repos(): + async with DefaultAzureCredential() as credential: + async with ContainerRegistryClient(endpoint, credential) as client: + async for repo in client.list_repository_names(): + print(repo) +``` + +## Clean Up Old Images + +```python +from datetime import datetime, timedelta, timezone + +cutoff = datetime.now(timezone.utc) - timedelta(days=30) + +for manifest in client.list_manifest_properties("my-image"): + if manifest.last_updated_on < cutoff and not manifest.tags: + print(f"Deleting {manifest.digest}") + client.delete_manifest("my-image", manifest.digest) +``` + +## Client Operations + +| Operation | Description | +|-----------|-------------| +| `list_repository_names` | List all repositories | +| `get_repository_properties` | Get repository metadata | +| `delete_repository` | Delete repository and all images | +| `list_tag_properties` | List tags in repository | +| `get_tag_properties` | Get tag metadata | +| `delete_tag` | Delete specific tag | +| `list_manifest_properties` | List manifests in repository | +| `get_manifest_properties` | Get manifest metadata | +| `delete_manifest` | Delete manifest by digest | +| `download_manifest` | Download manifest content | +| `download_blob` | Download layer blob | diff --git a/.github/plugins/azure-sdk-python/skills/azure-cosmos-db-py/SKILL.md b/.github/plugins/azure-sdk-python/skills/azure-cosmos-db-py/SKILL.md index 9fcb9385..66973512 100644 --- a/.github/plugins/azure-sdk-python/skills/azure-cosmos-db-py/SKILL.md +++ b/.github/plugins/azure-sdk-python/skills/azure-cosmos-db-py/SKILL.md @@ -223,7 +223,7 @@ async def test_get_project_by_id_returns_project(mock_cosmos_container): ## Best Practices -1. **This skill uses async throughout (`azure.cosmos.aio`); do not mix with the sync `azure.cosmos` client.** Keep the whole FastAPI request path async — don't pair sync Cosmos calls with async handlers. +1. **Pick sync OR async and stay consistent.** Do not mix `azure.xxx` sync clients with `azure.xxx.aio` async clients in the same call path. Choose one mode per module. 2. **Always use context managers for clients and async credentials.** Wrap the client in `async with CosmosClient(...) as client:` (or manage its lifetime via FastAPI lifespan and close it explicitly). For async `DefaultAzureCredential` from `azure.identity.aio`, also use `async with credential:` so tokens and transports are cleaned up. ## Reference Files diff --git a/.github/plugins/azure-sdk-python/skills/azure-cosmos-py/scripts/setup_cosmos_container.py b/.github/plugins/azure-sdk-python/skills/azure-cosmos-py/scripts/setup_cosmos_container.py index 88cb5d06..d9baedf1 100644 --- a/.github/plugins/azure-sdk-python/skills/azure-cosmos-py/scripts/setup_cosmos_container.py +++ b/.github/plugins/azure-sdk-python/skills/azure-cosmos-py/scripts/setup_cosmos_container.py @@ -31,7 +31,7 @@ def get_cosmos_client() -> CosmosClient: endpoint = os.environ.get("COSMOS_ENDPOINT") if not endpoint: raise ValueError("COSMOS_ENDPOINT environment variable required") - + # Try key auth first, fall back to DefaultAzureCredential key = os.environ.get("COSMOS_KEY") if key: @@ -44,33 +44,33 @@ def get_cosmos_client() -> CosmosClient: def create_indexing_policy( include_paths: list[str] | None = None, exclude_paths: list[str] | None = None, - composite_indexes: list[list[dict]] | None = None + composite_indexes: list[list[dict]] | None = None, ) -> dict[str, Any]: """Build an indexing policy.""" policy = { "indexingMode": "consistent", "automatic": True, "includedPaths": [], - "excludedPaths": [] + "excludedPaths": [], } - + # Include paths (default: all) if include_paths: policy["includedPaths"] = [{"path": p} for p in include_paths] else: policy["includedPaths"] = [{"path": "/*"}] - + # Exclude paths if exclude_paths: policy["excludedPaths"] = [{"path": p} for p in exclude_paths] - + # Always exclude _etag - policy["excludedPaths"].append({"path": "/_etag/?")}) - + policy["excludedPaths"].append({"path": "/_etag/?"}) + # Composite indexes for ORDER BY on multiple fields if composite_indexes: policy["compositeIndexes"] = composite_indexes - + return policy @@ -81,10 +81,10 @@ def create_container( partition_key_paths: list[str], throughput: int | None = None, ttl: int | None = None, - indexing_policy: dict | None = None + indexing_policy: dict | None = None, ) -> dict[str, Any]: """Create or update a Cosmos DB container.""" - + # Get or create database try: database = client.create_database_if_not_exists(id=database_id) @@ -92,41 +92,37 @@ def create_container( except CosmosHttpResponseError as e: print(f"Error creating database: {e.message}") raise - + # Build partition key if len(partition_key_paths) == 1: partition_key = PartitionKey(path=partition_key_paths[0]) else: # Hierarchical partition key partition_key = PartitionKey(path=partition_key_paths) - + # Container properties - container_props = { - "id": container_id, - "partition_key": partition_key - } - + container_props = {"id": container_id, "partition_key": partition_key} + # Add TTL if specified if ttl is not None: container_props["default_time_to_live"] = ttl - + # Add indexing policy if specified if indexing_policy: container_props["indexing_policy"] = indexing_policy - + # Create container try: if throughput: container = database.create_container_if_not_exists( - **container_props, - offer_throughput=throughput + **container_props, offer_throughput=throughput ) else: container = database.create_container_if_not_exists(**container_props) - + print(f"Container: {container_id}") print(f"Partition key: {partition_key_paths}") - + except CosmosHttpResponseError as e: if e.status_code == 409: print(f"Container {container_id} already exists") @@ -134,16 +130,16 @@ def create_container( else: print(f"Error creating container: {e.message}") raise - + # Get container properties properties = container.read() - + return { "database": database_id, "container": container_id, "partition_key": partition_key_paths, "self_link": properties.get("_self"), - "resource_id": properties.get("_rid") + "resource_id": properties.get("_rid"), } @@ -151,14 +147,14 @@ def show_container_info(client: CosmosClient, database_id: str, container_id: st """Display detailed container information.""" database = client.get_database_client(database_id) container = database.get_container_client(container_id) - + properties = container.read() - + print("\n=== Container Information ===") print(f"Database: {database_id}") print(f"Container: {container_id}") print(f"Partition Key: {properties.get('partitionKey', {}).get('paths', [])}") - + # TTL ttl = properties.get("defaultTtl") if ttl == -1: @@ -167,25 +163,29 @@ def show_container_info(client: CosmosClient, database_id: str, container_id: st print(f"TTL: {ttl} seconds") else: print("TTL: Disabled") - + # Indexing policy index_policy = properties.get("indexingPolicy", {}) print(f"Indexing Mode: {index_policy.get('indexingMode', 'consistent')}") - + # Throughput try: offer = container.read_offer() print(f"Throughput: {offer.offer_throughput} RU/s") if offer.properties.get("content", {}).get("offerAutopilotSettings"): - max_throughput = offer.properties["content"]["offerAutopilotSettings"]["maxThroughput"] + max_throughput = offer.properties["content"]["offerAutopilotSettings"][ + "maxThroughput" + ] print(f"Autoscale Max: {max_throughput} RU/s") except Exception: print("Throughput: Serverless or database-level") - + # Item count (approximate) try: query = "SELECT VALUE COUNT(1) FROM c" - count = list(container.query_items(query=query, enable_cross_partition_query=True))[0] + count = list( + container.query_items(query=query, enable_cross_partition_query=True) + )[0] print(f"Item Count: ~{count}") except Exception: print("Item Count: Unable to retrieve") @@ -195,84 +195,77 @@ def main(): parser = argparse.ArgumentParser( description="Create and configure Cosmos DB containers", formatter_class=argparse.RawDescriptionHelpFormatter, - epilog=__doc__ - ) - - parser.add_argument( - "--database", "-d", - required=True, - help="Database ID" - ) - parser.add_argument( - "--container", "-c", - required=True, - help="Container ID" + epilog=__doc__, ) + + parser.add_argument("--database", "-d", required=True, help="Database ID") + parser.add_argument("--container", "-c", required=True, help="Container ID") parser.add_argument( - "--partition-key", "-pk", + "--partition-key", + "-pk", nargs="+", required=True, - help="Partition key path(s). Use multiple for hierarchical keys." + help="Partition key path(s). Use multiple for hierarchical keys.", ) parser.add_argument( - "--throughput", "-t", + "--throughput", + "-t", type=int, - help="Provisioned throughput in RU/s (omit for serverless)" + help="Provisioned throughput in RU/s (omit for serverless)", ) parser.add_argument( "--serverless", action="store_true", - help="Use serverless mode (no throughput provisioning)" + help="Use serverless mode (no throughput provisioning)", ) parser.add_argument( - "--ttl", - type=int, - help="Default TTL in seconds (-1 for per-item TTL)" + "--ttl", type=int, help="Default TTL in seconds (-1 for per-item TTL)" ) parser.add_argument( "--exclude-paths", nargs="+", - help="Paths to exclude from indexing (e.g., /large_field/*)" + help="Paths to exclude from indexing (e.g., /large_field/*)", ) parser.add_argument( "--composite-index", action="append", nargs="+", metavar="PATH", - help="Composite index paths (can specify multiple times). Format: --composite-index /field1 /field2" + help="Composite index paths (can specify multiple times). Format: --composite-index /field1 /field2", ) parser.add_argument( "--info", action="store_true", - help="Show container information instead of creating" + help="Show container information instead of creating", ) parser.add_argument( - "--output", "-o", + "--output", + "-o", choices=["json", "text"], default="text", - help="Output format (default: text)" + help="Output format (default: text)", ) - + args = parser.parse_args() - + # Validate arguments if args.throughput and args.serverless: print("Error: Cannot specify both --throughput and --serverless") sys.exit(1) - + # Ensure partition key paths start with / partition_keys = [] for pk in args.partition_key: if not pk.startswith("/"): pk = f"/{pk}" partition_keys.append(pk) - + try: client = get_cosmos_client() except ValueError as e: print(f"Error: {e}") sys.exit(1) - + # Show info mode if args.info: try: @@ -281,7 +274,7 @@ def main(): print(f"Error: {e.message}") sys.exit(1) return - + # Build indexing policy indexing_policy = None if args.exclude_paths or args.composite_index: @@ -291,12 +284,11 @@ def main(): [{"path": p, "order": "ascending"} for p in index_paths] for index_paths in args.composite_index ] - + indexing_policy = create_indexing_policy( - exclude_paths=args.exclude_paths, - composite_indexes=composite_indexes + exclude_paths=args.exclude_paths, composite_indexes=composite_indexes ) - + # Create container try: result = create_container( @@ -306,12 +298,12 @@ def main(): partition_key_paths=partition_keys, throughput=args.throughput if not args.serverless else None, ttl=args.ttl, - indexing_policy=indexing_policy + indexing_policy=indexing_policy, ) except CosmosHttpResponseError as e: print(f"Error: {e.message}") sys.exit(1) - + # Output result if args.output == "json": print(json.dumps(result, indent=2)) @@ -326,7 +318,7 @@ def main(): print("Throughput: Serverless") if args.ttl: print(f"TTL: {args.ttl} seconds") - + print("\nContainer ready for use!") diff --git a/.github/plugins/azure-sdk-python/skills/azure-data-tables-py/SKILL.md b/.github/plugins/azure-sdk-python/skills/azure-data-tables-py/SKILL.md index ef513ce5..6376581b 100644 --- a/.github/plugins/azure-sdk-python/skills/azure-data-tables-py/SKILL.md +++ b/.github/plugins/azure-sdk-python/skills/azure-data-tables-py/SKILL.md @@ -269,3 +269,10 @@ asyncio.run(table_operations()) 8. **Use parameterized queries** to prevent injection 9. **Keep entities small** — max 1MB per entity 10. **Use async client** for high-throughput scenarios + +## Reference Files + +| File | Contents | +|------|----------| +| [references/capabilities.md](references/capabilities.md) | Additional non-hero capabilities, operation-group coverage, and production checklists. | +| [references/non-hero-scenarios.md](references/non-hero-scenarios.md) | Dedicated non-hero examples for secondary/advanced scenarios. | diff --git a/.github/plugins/azure-sdk-python/skills/azure-data-tables-py/references/capabilities.md b/.github/plugins/azure-sdk-python/skills/azure-data-tables-py/references/capabilities.md new file mode 100644 index 00000000..efb547ee --- /dev/null +++ b/.github/plugins/azure-sdk-python/skills/azure-data-tables-py/references/capabilities.md @@ -0,0 +1,34 @@ +# azure-data-tables-py capability coverage + +**SDK/package**: `azure-data-tables` + +This index maps hero scenarios in `SKILL.md` and links non-hero scenarios documented in dedicated reference files. + +## Hero scenarios covered in SKILL.md + +- `Client Types` +- `Table Operations` +- `Entity Operations` +- `Query Entities` + +## Non-hero scenarios + +- `Batch Operations`: Dedicated example and implementation notes. + See: [`non-hero-scenarios.md#batch-operations`](non-hero-scenarios.md#batch-operations) +- `Async Client`: Dedicated example and implementation notes. + See: [`non-hero-scenarios.md#async-client`](non-hero-scenarios.md#async-client) +- `Data Types`: | Python Type | Table Storage Type | + See: [`non-hero-scenarios.md#data-types`](non-hero-scenarios.md#data-types) + +## Related deep-dive references + +- [`non-hero-scenarios.md`](non-hero-scenarios.md): Dedicated non-hero examples and implementation notes. + +## API breadth checklist + +- Verify client/auth mode for the environment before coding. +- Confirm operation-group/method names against current Microsoft Learn API reference. +- For Python SDKs with both sync and async clients, document both forms without a blanket preference. +- Include cleanup/delete paths for created resources in examples. +- Prefer idempotent create/update operations where available. +- Validate paging/LRO/error-handling patterns for production paths. diff --git a/.github/plugins/azure-sdk-python/skills/azure-data-tables-py/references/non-hero-scenarios.md b/.github/plugins/azure-sdk-python/skills/azure-data-tables-py/references/non-hero-scenarios.md new file mode 100644 index 00000000..00a4e48b --- /dev/null +++ b/.github/plugins/azure-sdk-python/skills/azure-data-tables-py/references/non-hero-scenarios.md @@ -0,0 +1,62 @@ +# azure-data-tables-py non-hero scenarios + +These scenarios are intentionally separate from hero flows in `SKILL.md`. +They cover secondary/advanced patterns typically used after the primary end-to-end path is working. + +## Batch Operations + +```python +from azure.data.tables import TableTransactionError + +# Batch operations (same partition only!) +operations = [ + ("create", {"PartitionKey": "batch", "RowKey": "1", "data": "first"}), + ("create", {"PartitionKey": "batch", "RowKey": "2", "data": "second"}), + ("upsert", {"PartitionKey": "batch", "RowKey": "3", "data": "third"}), +] + +try: + table_client.submit_transaction(operations) +except TableTransactionError as e: + print(f"Transaction failed: {e}") +``` + +## Async Client + +```python +from azure.data.tables.aio import TableServiceClient, TableClient +from azure.identity.aio import DefaultAzureCredential + +async def table_operations(): + async with DefaultAzureCredential() as credential: + async with TableClient( + endpoint="https://.table.core.windows.net", + table_name="mytable", + credential=credential + ) as client: + # Create + await client.create_entity(entity={ + "PartitionKey": "async", + "RowKey": "1", + "data": "test" + }) + + # Query + async for entity in client.query_entities("PartitionKey eq 'async'"): + print(entity) + +import asyncio +asyncio.run(table_operations()) +``` + +## Data Types + +| Python Type | Table Storage Type | +|-------------|-------------------| +| `str` | String | +| `int` | Int64 | +| `float` | Double | +| `bool` | Boolean | +| `datetime` | DateTime | +| `bytes` | Binary | +| `UUID` | Guid | diff --git a/.github/plugins/azure-sdk-python/skills/azure-eventgrid-py/SKILL.md b/.github/plugins/azure-sdk-python/skills/azure-eventgrid-py/SKILL.md index 907ee84b..bf34e1da 100644 --- a/.github/plugins/azure-sdk-python/skills/azure-eventgrid-py/SKILL.md +++ b/.github/plugins/azure-sdk-python/skills/azure-eventgrid-py/SKILL.md @@ -193,3 +193,10 @@ with EventGridPublisherClient( 7. **Use async client** for high-throughput scenarios 8. **Handle retries** — Event Grid has built-in retry 9. **Set appropriate event types** for routing and filtering + +## Reference Files + +| File | Contents | +|------|----------| +| [references/capabilities.md](references/capabilities.md) | Additional non-hero capabilities, operation-group coverage, and production checklists. | +| [references/non-hero-scenarios.md](references/non-hero-scenarios.md) | Dedicated non-hero examples for secondary/advanced scenarios. | diff --git a/.github/plugins/azure-sdk-python/skills/azure-eventgrid-py/references/capabilities.md b/.github/plugins/azure-sdk-python/skills/azure-eventgrid-py/references/capabilities.md new file mode 100644 index 00000000..5c18e7d9 --- /dev/null +++ b/.github/plugins/azure-sdk-python/skills/azure-eventgrid-py/references/capabilities.md @@ -0,0 +1,32 @@ +# azure-eventgrid-py capability coverage + +**SDK/package**: `azure-eventgrid` + +This index maps hero scenarios in `SKILL.md` and links non-hero scenarios documented in dedicated reference files. + +## Hero scenarios covered in SKILL.md + +- `Event Types` +- `Publish CloudEvents` +- `Publish EventGridEvents` +- `Event Properties` + +## Non-hero scenarios + +- `Async Client`: Dedicated example and implementation notes. + See: [`non-hero-scenarios.md#async-client`](non-hero-scenarios.md#async-client) +- `Namespace Topics (Event Grid Namespaces)`: For Event Grid Namespaces (pull delivery): + See: [`non-hero-scenarios.md#namespace-topics-event-grid-namespaces`](non-hero-scenarios.md#namespace-topics-event-grid-namespaces) + +## Related deep-dive references + +- [`non-hero-scenarios.md`](non-hero-scenarios.md): Dedicated non-hero examples and implementation notes. + +## API breadth checklist + +- Verify client/auth mode for the environment before coding. +- Confirm operation-group/method names against current Microsoft Learn API reference. +- For Python SDKs with both sync and async clients, document both forms without a blanket preference. +- Include cleanup/delete paths for created resources in examples. +- Prefer idempotent create/update operations where available. +- Validate paging/LRO/error-handling patterns for production paths. diff --git a/.github/plugins/azure-sdk-python/skills/azure-eventgrid-py/references/non-hero-scenarios.md b/.github/plugins/azure-sdk-python/skills/azure-eventgrid-py/references/non-hero-scenarios.md new file mode 100644 index 00000000..a74c845f --- /dev/null +++ b/.github/plugins/azure-sdk-python/skills/azure-eventgrid-py/references/non-hero-scenarios.md @@ -0,0 +1,47 @@ +# azure-eventgrid-py non-hero scenarios + +These scenarios are intentionally separate from hero flows in `SKILL.md`. +They cover secondary/advanced patterns typically used after the primary end-to-end path is working. + +## Async Client + +```python +from azure.eventgrid.aio import EventGridPublisherClient +from azure.identity.aio import DefaultAzureCredential + +async def publish_events(): + credential = DefaultAzureCredential() + + async with EventGridPublisherClient(endpoint, credential) as client: + event = CloudEvent( + type="MyApp.Events.Test", + source="/myapp", + data={"message": "hello"} + ) + await client.send(event) + +import asyncio +asyncio.run(publish_events()) +``` + +## Namespace Topics (Event Grid Namespaces) + +For Event Grid Namespaces (pull delivery): + +```python +from azure.eventgrid import EventGridPublisherClient +from azure.identity import DefaultAzureCredential + +# Namespace endpoint (different from custom topic) +namespace_endpoint = "https://..eventgrid.azure.net" +topic_name = "my-topic" + +with EventGridPublisherClient( + endpoint=namespace_endpoint, + credential=DefaultAzureCredential() +) as client: + client.send( + event, + namespace_topic=topic_name + ) +``` diff --git a/.github/plugins/azure-sdk-python/skills/azure-identity-py/SKILL.md b/.github/plugins/azure-sdk-python/skills/azure-identity-py/SKILL.md index 37e6a034..f187f844 100644 --- a/.github/plugins/azure-sdk-python/skills/azure-identity-py/SKILL.md +++ b/.github/plugins/azure-sdk-python/skills/azure-identity-py/SKILL.md @@ -62,7 +62,20 @@ AZURE_CLIENT_ID= AZURE_TOKEN_CREDENTIALS=dev|prod| # Optional, restricts DAC chain ``` -## DefaultAzureCredential +## Authentication & Lifecycle + +> **🔑 Two rules apply to every code sample below:** +> +> 1. **Prefer `DefaultAzureCredential`.** It works locally (Azure CLI / VS Code / Developer CLI) and in Azure (managed identity, workload identity) with no code change. Avoid connection strings, account/API keys — they bypass Entra audit and rotation. +> - Local dev: `DefaultAzureCredential` works as-is. +> - Production: set `AZURE_TOKEN_CREDENTIALS=prod` (or `AZURE_TOKEN_CREDENTIALS=`) to constrain the credential chain to production-safe credentials. +> 2. **Wrap credentials and clients in context managers** when they own token caches / transports: +> - Sync: `with DefaultAzureCredential() as credential:` +> - Async: `async with DefaultAzureCredential() as credential:` (from `azure.identity.aio`) +> +> Snippets may abbreviate this setup, but production code should always follow both rules. + +### DefaultAzureCredential The recommended credential for most scenarios. Tries multiple authentication methods in order: @@ -522,3 +535,10 @@ AZURE_LOG_LEVEL=debug | API Reference | https://learn.microsoft.com/python/api/azure-identity | | GitHub Source | https://github.com/Azure/azure-sdk-for-python/tree/main/sdk/identity/azure-identity | | Credential Chains | https://aka.ms/azsdk/python/identity/credential-chains | + +## Reference Files + +| File | Contents | +|------|----------| +| [references/capabilities.md](references/capabilities.md) | Additional non-hero capabilities, operation-group coverage, and production checklists. | +| [references/non-hero-scenarios.md](references/non-hero-scenarios.md) | Dedicated non-hero examples for secondary/advanced scenarios. | diff --git a/.github/plugins/azure-sdk-python/skills/azure-identity-py/references/capabilities.md b/.github/plugins/azure-sdk-python/skills/azure-identity-py/references/capabilities.md new file mode 100644 index 00000000..bfc31d6e --- /dev/null +++ b/.github/plugins/azure-sdk-python/skills/azure-identity-py/references/capabilities.md @@ -0,0 +1,42 @@ +# azure-identity-py capability coverage + +**SDK/package**: `azure-identity` + +This index maps hero scenarios in `SKILL.md` and links non-hero scenarios documented in dedicated reference files. + +## Hero scenarios covered in SKILL.md + +- `get_bearer_token_provider` +- `Credential Types` +- `Specific Credential Examples` +- `Getting Tokens Directly` + +## Non-hero scenarios + +- `Async Credentials`: Async credentials are in `azure.identity.aio`. Always close them or use `async with`: + See: [`non-hero-scenarios.md#async-credentials`](non-hero-scenarios.md#async-credentials) +- `Sovereign Clouds`: Use `AzureAuthorityHosts` or the `AZURE_AUTHORITY_HOST` env var: + See: [`non-hero-scenarios.md#sovereign-clouds`](non-hero-scenarios.md#sovereign-clouds) +- `Persistent Token Caching`: Opt-in disk-based caching with `TokenCachePersistenceOptions`: + See: [`non-hero-scenarios.md#persistent-token-caching`](non-hero-scenarios.md#persistent-token-caching) +- `Multi-Tenant Support`: Allow token acquisition for additional tenants beyond the configured one: + See: [`non-hero-scenarios.md#multi-tenant-support`](non-hero-scenarios.md#multi-tenant-support) +- `Error Handling`: Dedicated example and implementation notes. + See: [`non-hero-scenarios.md#error-handling`](non-hero-scenarios.md#error-handling) +- `Logging`: Enable authentication logging for debugging: + See: [`non-hero-scenarios.md#logging`](non-hero-scenarios.md#logging) +- `Credential Selection Matrix`: | Environment | Recommended Credential | + See: [`non-hero-scenarios.md#credential-selection-matrix`](non-hero-scenarios.md#credential-selection-matrix) + +## Related deep-dive references + +- [`non-hero-scenarios.md`](non-hero-scenarios.md): Dedicated non-hero examples and implementation notes. + +## API breadth checklist + +- Verify client/auth mode for the environment before coding. +- Confirm operation-group/method names against current Microsoft Learn API reference. +- For Python SDKs with both sync and async clients, document both forms without a blanket preference. +- Include cleanup/delete paths for created resources in examples. +- Prefer idempotent create/update operations where available. +- Validate paging/LRO/error-handling patterns for production paths. diff --git a/.github/plugins/azure-sdk-python/skills/azure-identity-py/references/non-hero-scenarios.md b/.github/plugins/azure-sdk-python/skills/azure-identity-py/references/non-hero-scenarios.md new file mode 100644 index 00000000..e1c9ec06 --- /dev/null +++ b/.github/plugins/azure-sdk-python/skills/azure-identity-py/references/non-hero-scenarios.md @@ -0,0 +1,129 @@ +# azure-identity-py non-hero scenarios + +These scenarios are intentionally separate from hero flows in `SKILL.md`. +They cover secondary/advanced patterns typically used after the primary end-to-end path is working. + +## Async Credentials + +Async credentials are in `azure.identity.aio`. Always close them or use `async with`: + +```python +from azure.identity.aio import DefaultAzureCredential +from azure.storage.blob.aio import BlobServiceClient + +async def main(): + # Preferred: use async context manager for both credential and client + async with DefaultAzureCredential() as credential: + async with BlobServiceClient( + account_url="https://.blob.core.windows.net", + credential=credential, + ) as client: + # ... async operations + pass +``` + +> The async `get_bearer_token_provider` is at `azure.identity.aio.get_bearer_token_provider`. + +## Sovereign Clouds + +Use `AzureAuthorityHosts` or the `AZURE_AUTHORITY_HOST` env var: + +```python +from azure.identity import DefaultAzureCredential, AzureAuthorityHosts + +# Azure Government +credential = DefaultAzureCredential(authority=AzureAuthorityHosts.AZURE_GOVERNMENT) + +# Azure China +credential = DefaultAzureCredential(authority=AzureAuthorityHosts.AZURE_CHINA) +``` + +| Constant | Authority | +|----------|-----------| +| `AzureAuthorityHosts.AZURE_PUBLIC_CLOUD` | `login.microsoftonline.com` (default) | +| `AzureAuthorityHosts.AZURE_GOVERNMENT` | `login.microsoftonline.us` | +| `AzureAuthorityHosts.AZURE_CHINA` | `login.chinacloudapi.cn` | + +## Persistent Token Caching + +Opt-in disk-based caching with `TokenCachePersistenceOptions`: + +```python +from azure.identity import DefaultAzureCredential, TokenCachePersistenceOptions + +credential = DefaultAzureCredential( + cache_persistence_options=TokenCachePersistenceOptions() +) + +# Allow unencrypted fallback (NOT recommended for production) +credential = DefaultAzureCredential( + cache_persistence_options=TokenCachePersistenceOptions(allow_unencrypted_storage=True) +) +``` + +Storage: Windows (DPAPI), macOS (Keychain), Linux (Keyring). + +## Multi-Tenant Support + +Allow token acquisition for additional tenants beyond the configured one: + +```python +from azure.identity import ClientSecretCredential + +credential = ClientSecretCredential( + tenant_id="", + client_id="", + client_secret="", + additionally_allowed_tenants=["", "*"], # "*" allows any tenant +) +``` + +## Error Handling + +```python +from azure.identity import DefaultAzureCredential, CredentialUnavailableError +from azure.core.exceptions import ClientAuthenticationError + +with DefaultAzureCredential() as credential: + try: + token = credential.get_token("https://management.azure.com/.default") + except CredentialUnavailableError: + # No credential in the chain could attempt authentication + pass + except ClientAuthenticationError as e: + # Authentication was attempted but failed + # e.message contains details from each credential in the chain + pass +``` + +## Logging + +Enable authentication logging for debugging: + +```python +import logging + +# Enable verbose Azure Identity logging +logging.basicConfig(level=logging.DEBUG) +logger = logging.getLogger("azure.identity") +logger.setLevel(logging.DEBUG) +``` + +```bash +# Or via environment variable +AZURE_LOG_LEVEL=debug +``` + +## Credential Selection Matrix + +| Environment | Recommended Credential | +|-------------|------------------------| +| Local Development | `DefaultAzureCredential` (uses Azure CLI) | +| Azure App Service | `DefaultAzureCredential` (uses Managed Identity) | +| Azure Functions | `DefaultAzureCredential` (uses Managed Identity) | +| Azure Kubernetes Service | `WorkloadIdentityCredential` | +| Azure VMs | `DefaultAzureCredential` (uses Managed Identity) | +| CI/CD Pipeline | `EnvironmentCredential` or `AzurePipelinesCredential` | +| Desktop App | `InteractiveBrowserCredential` | +| CLI / Headless Tool | `DeviceCodeCredential` | +| Middle-tier Service | `OnBehalfOfCredential` | diff --git a/.github/plugins/azure-sdk-python/skills/azure-keyvault-py/SKILL.md b/.github/plugins/azure-sdk-python/skills/azure-keyvault-py/SKILL.md index 20c836c7..ef10d433 100644 --- a/.github/plugins/azure-sdk-python/skills/azure-keyvault-py/SKILL.md +++ b/.github/plugins/azure-sdk-python/skills/azure-keyvault-py/SKILL.md @@ -272,3 +272,10 @@ except HttpResponseError as e: 8. **Use Key Vault references** in App Service/Functions config 9. **Cache secrets** appropriately to reduce API calls 10. **Use async clients** for high-throughput scenarios + +## Reference Files + +| File | Contents | +|------|----------| +| [references/capabilities.md](references/capabilities.md) | Additional non-hero capabilities, operation-group coverage, and production checklists. | +| [references/non-hero-scenarios.md](references/non-hero-scenarios.md) | Dedicated non-hero examples for secondary/advanced scenarios. | diff --git a/.github/plugins/azure-sdk-python/skills/azure-keyvault-py/references/capabilities.md b/.github/plugins/azure-sdk-python/skills/azure-keyvault-py/references/capabilities.md new file mode 100644 index 00000000..5a008b97 --- /dev/null +++ b/.github/plugins/azure-sdk-python/skills/azure-keyvault-py/references/capabilities.md @@ -0,0 +1,32 @@ +# azure-keyvault-py capability coverage + +**SDK/package**: `azure-keyvault-secrets, azure-keyvault-keys, azure-keyvault-certificates` + +This index maps hero scenarios in `SKILL.md` and links non-hero scenarios documented in dedicated reference files. + +## Hero scenarios covered in SKILL.md + +- `Secrets` +- `Keys` +- `Certificates` +- `Client Types Table` + +## Non-hero scenarios + +- `Async Clients`: Dedicated example and implementation notes. + See: [`non-hero-scenarios.md#async-clients`](non-hero-scenarios.md#async-clients) +- `Error Handling`: Dedicated example and implementation notes. + See: [`non-hero-scenarios.md#error-handling`](non-hero-scenarios.md#error-handling) + +## Related deep-dive references + +- [`non-hero-scenarios.md`](non-hero-scenarios.md): Dedicated non-hero examples and implementation notes. + +## API breadth checklist + +- Verify client/auth mode for the environment before coding. +- Confirm operation-group/method names against current Microsoft Learn API reference. +- For Python SDKs with both sync and async clients, document both forms without a blanket preference. +- Include cleanup/delete paths for created resources in examples. +- Prefer idempotent create/update operations where available. +- Validate paging/LRO/error-handling patterns for production paths. diff --git a/.github/plugins/azure-sdk-python/skills/azure-keyvault-py/references/non-hero-scenarios.md b/.github/plugins/azure-sdk-python/skills/azure-keyvault-py/references/non-hero-scenarios.md new file mode 100644 index 00000000..2f1bd32f --- /dev/null +++ b/.github/plugins/azure-sdk-python/skills/azure-keyvault-py/references/non-hero-scenarios.md @@ -0,0 +1,35 @@ +# azure-keyvault-py non-hero scenarios + +These scenarios are intentionally separate from hero flows in `SKILL.md`. +They cover secondary/advanced patterns typically used after the primary end-to-end path is working. + +## Async Clients + +```python +from azure.identity.aio import DefaultAzureCredential +from azure.keyvault.secrets.aio import SecretClient + +async def get_secret(): + async with DefaultAzureCredential() as credential: + async with SecretClient(vault_url=vault_url, credential=credential) as client: + secret = await client.get_secret("my-secret") + print(secret.value) + +import asyncio +asyncio.run(get_secret()) +``` + +## Error Handling + +```python +from azure.core.exceptions import ResourceNotFoundError, HttpResponseError + +try: + secret = client.get_secret("nonexistent") +except ResourceNotFoundError: + print("Secret not found") +except HttpResponseError as e: + if e.status_code == 403: + print("Access denied - check RBAC permissions") + raise +``` diff --git a/.github/plugins/azure-sdk-python/skills/azure-messaging-webpubsubservice-py/SKILL.md b/.github/plugins/azure-sdk-python/skills/azure-messaging-webpubsubservice-py/SKILL.md index 8cdd7c32..20cf2ada 100644 --- a/.github/plugins/azure-sdk-python/skills/azure-messaging-webpubsubservice-py/SKILL.md +++ b/.github/plugins/azure-sdk-python/skills/azure-messaging-webpubsubservice-py/SKILL.md @@ -255,3 +255,10 @@ async def broadcast(): 7. **Handle reconnection** in client applications 8. **Use JSON** content type for structured data 9. **Close connections** gracefully with reasons + +## Reference Files + +| File | Contents | +|------|----------| +| [references/capabilities.md](references/capabilities.md) | Additional non-hero capabilities, operation-group coverage, and production checklists. | +| [references/non-hero-scenarios.md](references/non-hero-scenarios.md) | Dedicated non-hero examples for secondary/advanced scenarios. | diff --git a/.github/plugins/azure-sdk-python/skills/azure-messaging-webpubsubservice-py/references/capabilities.md b/.github/plugins/azure-sdk-python/skills/azure-messaging-webpubsubservice-py/references/capabilities.md new file mode 100644 index 00000000..6964e572 --- /dev/null +++ b/.github/plugins/azure-sdk-python/skills/azure-messaging-webpubsubservice-py/references/capabilities.md @@ -0,0 +1,30 @@ +# azure-messaging-webpubsubservice-py capability coverage + +**SDK/package**: `azure-messaging-webpubsubservice` + +This index maps hero scenarios in `SKILL.md` and links non-hero scenarios documented in dedicated reference files. + +## Hero scenarios covered in SKILL.md + +- `Service Client (Server-Side)` +- `Client SDK (Python WebSocket Client)` +- `Async Service Client` +- `Client Operations` + +## Non-hero scenarios + +- `Operational hardening`: Use this section for retries, timeouts, pagination, and cleanup patterns specific to this SDK. + See: [`non-hero-scenarios.md#operational-hardening`](non-hero-scenarios.md#operational-hardening) + +## Related deep-dive references + +- [`non-hero-scenarios.md`](non-hero-scenarios.md): Dedicated non-hero examples and implementation notes. + +## API breadth checklist + +- Verify client/auth mode for the environment before coding. +- Confirm operation-group/method names against current Microsoft Learn API reference. +- For Python SDKs with both sync and async clients, document both forms without a blanket preference. +- Include cleanup/delete paths for created resources in examples. +- Prefer idempotent create/update operations where available. +- Validate paging/LRO/error-handling patterns for production paths. diff --git a/.github/plugins/azure-sdk-python/skills/azure-messaging-webpubsubservice-py/references/non-hero-scenarios.md b/.github/plugins/azure-sdk-python/skills/azure-messaging-webpubsubservice-py/references/non-hero-scenarios.md new file mode 100644 index 00000000..56754214 --- /dev/null +++ b/.github/plugins/azure-sdk-python/skills/azure-messaging-webpubsubservice-py/references/non-hero-scenarios.md @@ -0,0 +1,8 @@ +# azure-messaging-webpubsubservice-py non-hero scenarios + +These scenarios are intentionally separate from hero flows in `SKILL.md`. +They cover secondary/advanced patterns typically used after the primary end-to-end path is working. + +## Operational hardening + +Use this section for retries, timeouts, pagination, and cleanup patterns specific to this SDK. diff --git a/.github/plugins/azure-sdk-python/skills/azure-mgmt-apicenter-py/SKILL.md b/.github/plugins/azure-sdk-python/skills/azure-mgmt-apicenter-py/SKILL.md index 99f050f5..97f22bbd 100644 --- a/.github/plugins/azure-sdk-python/skills/azure-mgmt-apicenter-py/SKILL.md +++ b/.github/plugins/azure-sdk-python/skills/azure-mgmt-apicenter-py/SKILL.md @@ -89,7 +89,7 @@ for api_center in api_centers: ## Register an API ```python -from azure.mgmt.apicenter.models import Api, ApiKind, LifecycleStage +from azure.mgmt.apicenter.models import Api, ApiKind, ApiProperties api = client.apis.create_or_update( resource_group_name="my-resource-group", @@ -97,22 +97,23 @@ api = client.apis.create_or_update( workspace_name="default", api_name="my-api", resource=Api( - title="My API", - description="A sample API for demonstration", - kind=ApiKind.REST, - lifecycle_stage=LifecycleStage.PRODUCTION, - terms_of_service={"url": "https://example.com/terms"}, - contacts=[{"name": "API Team", "email": "api-team@example.com"}] - ) + properties=ApiProperties( + title="My API", + description="A sample API for demonstration", + kind=ApiKind.REST, + terms_of_service={"url": "https://example.com/terms"}, + contacts=[{"name": "API Team", "email": "api-team@example.com"}], + ) + ), ) -print(f"Registered API: {api.title}") +print(f"Registered API: {api.properties.title}") ``` ## Create API Version ```python -from azure.mgmt.apicenter.models import ApiVersion, LifecycleStage +from azure.mgmt.apicenter.models import ApiVersion, ApiVersionProperties, LifecycleStage version = client.api_versions.create_or_update( resource_group_name="my-resource-group", @@ -121,18 +122,20 @@ version = client.api_versions.create_or_update( api_name="my-api", version_name="v1", resource=ApiVersion( - title="Version 1.0", - lifecycle_stage=LifecycleStage.PRODUCTION - ) + properties=ApiVersionProperties( + title="Version 1.0", + lifecycle_stage=LifecycleStage.PRODUCTION, + ) + ), ) -print(f"Created version: {version.title}") +print(f"Created version: {version.properties.title}") ``` ## Add API Definition ```python -from azure.mgmt.apicenter.models import ApiDefinition +from azure.mgmt.apicenter.models import ApiDefinition, ApiDefinitionProperties definition = client.api_definitions.create_or_update( resource_group_name="my-resource-group", @@ -142,9 +145,11 @@ definition = client.api_definitions.create_or_update( version_name="v1", definition_name="openapi", resource=ApiDefinition( - title="OpenAPI Definition", - description="OpenAPI 3.0 specification" - ) + properties=ApiDefinitionProperties( + title="OpenAPI Definition", + description="OpenAPI 3.0 specification", + ) + ), ) ``` @@ -154,7 +159,7 @@ definition = client.api_definitions.create_or_update( from azure.mgmt.apicenter.models import ApiSpecImportRequest, ApiSpecImportSourceFormat # Import from inline content -client.api_definitions.import_specification( +client.api_definitions.begin_import_specification( resource_group_name="my-resource-group", service_name="my-api-center", workspace_name="default", @@ -163,9 +168,9 @@ client.api_definitions.import_specification( definition_name="openapi", body=ApiSpecImportRequest( format=ApiSpecImportSourceFormat.INLINE, - value='{"openapi": "3.0.0", "info": {"title": "My API", "version": "1.0"}, "paths": {}}' + value='{"openapi": "3.0.0", "info": {"title": "My API", "version": "1.0"}, "paths": {}}', ) -) +).result() ``` ## List APIs @@ -184,7 +189,7 @@ for api in apis: ## Create Environment ```python -from azure.mgmt.apicenter.models import Environment, EnvironmentKind +from azure.mgmt.apicenter.models import Environment, EnvironmentKind, EnvironmentProperties environment = client.environments.create_or_update( resource_group_name="my-resource-group", @@ -192,18 +197,20 @@ environment = client.environments.create_or_update( workspace_name="default", environment_name="production", resource=Environment( - title="Production", - description="Production environment", - kind=EnvironmentKind.PRODUCTION, - server={"type": "Azure API Management", "management_portal_uri": ["https://portal.azure.com"]} - ) + properties=EnvironmentProperties( + title="Production", + description="Production environment", + kind=EnvironmentKind.PRODUCTION, + server={"type": "Azure API Management", "management_portal_uri": ["https://portal.azure.com"]}, + ) + ), ) ``` ## Create Deployment ```python -from azure.mgmt.apicenter.models import Deployment, DeploymentState +from azure.mgmt.apicenter.models import Deployment, DeploymentProperties, DeploymentState deployment = client.deployments.create_or_update( resource_group_name="my-resource-group", @@ -212,28 +219,32 @@ deployment = client.deployments.create_or_update( api_name="my-api", deployment_name="prod-deployment", resource=Deployment( - title="Production Deployment", - description="Deployed to production APIM", - environment_id="/workspaces/default/environments/production", - definition_id="/workspaces/default/apis/my-api/versions/v1/definitions/openapi", - state=DeploymentState.ACTIVE, - server={"runtime_uri": ["https://api.example.com"]} - ) + properties=DeploymentProperties( + title="Production Deployment", + description="Deployed to production APIM", + environment_id="/workspaces/default/environments/production", + definition_id="/workspaces/default/apis/my-api/versions/v1/definitions/openapi", + state=DeploymentState.ACTIVE, + server={"runtime_uri": ["https://api.example.com"]}, + ) + ), ) ``` ## Define Custom Metadata ```python -from azure.mgmt.apicenter.models import MetadataSchema +from azure.mgmt.apicenter.models import MetadataSchema, MetadataSchemaProperties metadata = client.metadata_schemas.create_or_update( resource_group_name="my-resource-group", service_name="my-api-center", metadata_schema_name="data-classification", resource=MetadataSchema( - schema='{"type": "string", "title": "Data Classification", "enum": ["public", "internal", "confidential"]}' - ) + properties=MetadataSchemaProperties( + schema='{"type": "string", "title": "Data Classification", "enum": ["public", "internal", "confidential"]}' + ) + ), ) ``` @@ -266,3 +277,10 @@ metadata = client.metadata_schemas.create_or_update( 6. **Import specifications** to enable API analysis and linting 7. **Use lifecycle stages** to track API maturity 8. **Add contacts** for API ownership and support + +## Reference Files + +| File | Contents | +|------|----------| +| [references/capabilities.md](references/capabilities.md) | Additional non-hero capabilities, operation-group coverage, and production checklists. | +| [references/non-hero-scenarios.md](references/non-hero-scenarios.md) | Dedicated non-hero examples for secondary/advanced scenarios. | diff --git a/.github/plugins/azure-sdk-python/skills/azure-mgmt-apicenter-py/references/capabilities.md b/.github/plugins/azure-sdk-python/skills/azure-mgmt-apicenter-py/references/capabilities.md new file mode 100644 index 00000000..cca21654 --- /dev/null +++ b/.github/plugins/azure-sdk-python/skills/azure-mgmt-apicenter-py/references/capabilities.md @@ -0,0 +1,44 @@ +# azure-mgmt-apicenter-py capability coverage + +**SDK/package**: `azure-mgmt-apicenter` + +This index maps hero scenarios in `SKILL.md` and links non-hero scenarios documented in dedicated reference files. + +## Hero scenarios covered in SKILL.md + +- `Create API Center` +- `List API Centers` +- `Register an API` +- `Create API Version` + +## Non-hero scenarios + +- `Add API Definition`: Dedicated example and implementation notes. + See: [`non-hero-scenarios.md#add-api-definition`](non-hero-scenarios.md#add-api-definition) +- `Import API Specification`: Dedicated example and implementation notes. + See: [`non-hero-scenarios.md#import-api-specification`](non-hero-scenarios.md#import-api-specification) +- `List APIs`: Dedicated example and implementation notes. + See: [`non-hero-scenarios.md#list-apis`](non-hero-scenarios.md#list-apis) +- `Create Environment`: Dedicated example and implementation notes. + See: [`non-hero-scenarios.md#create-environment`](non-hero-scenarios.md#create-environment) +- `Create Deployment`: Dedicated example and implementation notes. + See: [`non-hero-scenarios.md#create-deployment`](non-hero-scenarios.md#create-deployment) +- `Define Custom Metadata`: Dedicated example and implementation notes. + See: [`non-hero-scenarios.md#define-custom-metadata`](non-hero-scenarios.md#define-custom-metadata) +- `Client Types`: | Client | Purpose | + See: [`non-hero-scenarios.md#client-types`](non-hero-scenarios.md#client-types) +- `Operations`: | Operation Group | Purpose | + See: [`non-hero-scenarios.md#operations`](non-hero-scenarios.md#operations) + +## Related deep-dive references + +- [`non-hero-scenarios.md`](non-hero-scenarios.md): Dedicated non-hero examples and implementation notes. + +## API breadth checklist + +- Verify client/auth mode for the environment before coding. +- Confirm operation-group/method names against current Microsoft Learn API reference. +- For Python SDKs with both sync and async clients, document both forms without a blanket preference. +- Include cleanup/delete paths for created resources in examples. +- Prefer idempotent create/update operations where available. +- Validate paging/LRO/error-handling patterns for production paths. diff --git a/.github/plugins/azure-sdk-python/skills/azure-mgmt-apicenter-py/references/non-hero-scenarios.md b/.github/plugins/azure-sdk-python/skills/azure-mgmt-apicenter-py/references/non-hero-scenarios.md new file mode 100644 index 00000000..1fb05fd8 --- /dev/null +++ b/.github/plugins/azure-sdk-python/skills/azure-mgmt-apicenter-py/references/non-hero-scenarios.md @@ -0,0 +1,139 @@ +# azure-mgmt-apicenter-py non-hero scenarios + +These scenarios are intentionally separate from hero flows in `SKILL.md`. +They cover secondary/advanced patterns typically used after the primary end-to-end path is working. + +## Add API Definition + +```python +from azure.mgmt.apicenter.models import ApiDefinition, ApiDefinitionProperties + +definition = client.api_definitions.create_or_update( + resource_group_name="my-resource-group", + service_name="my-api-center", + workspace_name="default", + api_name="my-api", + version_name="v1", + definition_name="openapi", + resource=ApiDefinition( + properties=ApiDefinitionProperties( + title="OpenAPI Definition", + description="OpenAPI 3.0 specification", + ) + ), +) +``` + +## Import API Specification + +```python +from azure.mgmt.apicenter.models import ApiSpecImportRequest, ApiSpecImportSourceFormat + +# Import from inline content +client.api_definitions.begin_import_specification( + resource_group_name="my-resource-group", + service_name="my-api-center", + workspace_name="default", + api_name="my-api", + version_name="v1", + definition_name="openapi", + body=ApiSpecImportRequest( + format=ApiSpecImportSourceFormat.INLINE, + value='{"openapi": "3.0.0", "info": {"title": "My API", "version": "1.0"}, "paths": {}}', + ) +).result() +``` + +## List APIs + +```python +apis = client.apis.list( + resource_group_name="my-resource-group", + service_name="my-api-center", + workspace_name="default" +) + +for api in apis: + print(f"{api.name}: {api.title} ({api.kind})") +``` + +## Create Environment + +```python +from azure.mgmt.apicenter.models import Environment, EnvironmentKind, EnvironmentProperties + +environment = client.environments.create_or_update( + resource_group_name="my-resource-group", + service_name="my-api-center", + workspace_name="default", + environment_name="production", + resource=Environment( + properties=EnvironmentProperties( + title="Production", + description="Production environment", + kind=EnvironmentKind.PRODUCTION, + server={"type": "Azure API Management", "management_portal_uri": ["https://portal.azure.com"]}, + ) + ), +) +``` + +## Create Deployment + +```python +from azure.mgmt.apicenter.models import Deployment, DeploymentProperties, DeploymentState + +deployment = client.deployments.create_or_update( + resource_group_name="my-resource-group", + service_name="my-api-center", + workspace_name="default", + api_name="my-api", + deployment_name="prod-deployment", + resource=Deployment( + properties=DeploymentProperties( + title="Production Deployment", + description="Deployed to production APIM", + environment_id="/workspaces/default/environments/production", + definition_id="/workspaces/default/apis/my-api/versions/v1/definitions/openapi", + state=DeploymentState.ACTIVE, + server={"runtime_uri": ["https://api.example.com"]}, + ) + ), +) +``` + +## Define Custom Metadata + +```python +from azure.mgmt.apicenter.models import MetadataSchema, MetadataSchemaProperties + +metadata = client.metadata_schemas.create_or_update( + resource_group_name="my-resource-group", + service_name="my-api-center", + metadata_schema_name="data-classification", + resource=MetadataSchema( + properties=MetadataSchemaProperties( + schema='{"type": "string", "title": "Data Classification", "enum": ["public", "internal", "confidential"]}' + ) + ), +) +``` + +## Client Types + +| Client | Purpose | +|--------|---------| +| `ApiCenterMgmtClient` | Main client for all operations | + +## Operations + +| Operation Group | Purpose | +|----------------|---------| +| `services` | API Center service management | +| `workspaces` | Workspace management | +| `apis` | API registration and management | +| `api_versions` | API version management | +| `api_definitions` | API definition management | +| `deployments` | Deployment tracking | +| `environments` | Environment management | +| `metadata_schemas` | Custom metadata definitions | diff --git a/.github/plugins/azure-sdk-python/skills/azure-mgmt-apimanagement-py/SKILL.md b/.github/plugins/azure-sdk-python/skills/azure-mgmt-apimanagement-py/SKILL.md index 23cccf5a..ddec4896 100644 --- a/.github/plugins/azure-sdk-python/skills/azure-mgmt-apimanagement-py/SKILL.md +++ b/.github/plugins/azure-sdk-python/skills/azure-mgmt-apimanagement-py/SKILL.md @@ -302,3 +302,10 @@ user = client.user.create_or_update( 6. **Enable Application Insights** for monitoring 7. **Use backends** to abstract backend services 8. **Version your APIs** using APIM's versioning features + +## Reference Files + +| File | Contents | +|------|----------| +| [references/capabilities.md](references/capabilities.md) | Additional non-hero capabilities, operation-group coverage, and production checklists. | +| [references/non-hero-scenarios.md](references/non-hero-scenarios.md) | Dedicated non-hero examples for secondary/advanced scenarios. | diff --git a/.github/plugins/azure-sdk-python/skills/azure-mgmt-apimanagement-py/references/capabilities.md b/.github/plugins/azure-sdk-python/skills/azure-mgmt-apimanagement-py/references/capabilities.md new file mode 100644 index 00000000..a74cb701 --- /dev/null +++ b/.github/plugins/azure-sdk-python/skills/azure-mgmt-apimanagement-py/references/capabilities.md @@ -0,0 +1,44 @@ +# azure-mgmt-apimanagement-py capability coverage + +**SDK/package**: `azure-mgmt-apimanagement` + +This index maps hero scenarios in `SKILL.md` and links non-hero scenarios documented in dedicated reference files. + +## Hero scenarios covered in SKILL.md + +- `Create APIM Service` +- `Import API from OpenAPI` +- `Import API from URL` +- `List APIs` + +## Non-hero scenarios + +- `Create Product`: Dedicated example and implementation notes. + See: [`non-hero-scenarios.md#create-product`](non-hero-scenarios.md#create-product) +- `Add API to Product`: Dedicated example and implementation notes. + See: [`non-hero-scenarios.md#add-api-to-product`](non-hero-scenarios.md#add-api-to-product) +- `Create Subscription`: Dedicated example and implementation notes. + See: [`non-hero-scenarios.md#create-subscription`](non-hero-scenarios.md#create-subscription) +- `Set API Policy`: Dedicated example and implementation notes. + See: [`non-hero-scenarios.md#set-api-policy`](non-hero-scenarios.md#set-api-policy) +- `Create Named Value (Secret)`: Dedicated example and implementation notes. + See: [`non-hero-scenarios.md#create-named-value-secret`](non-hero-scenarios.md#create-named-value-secret) +- `Create Backend`: Dedicated example and implementation notes. + See: [`non-hero-scenarios.md#create-backend`](non-hero-scenarios.md#create-backend) +- `Create User`: Dedicated example and implementation notes. + See: [`non-hero-scenarios.md#create-user`](non-hero-scenarios.md#create-user) +- `Operation Groups`: | Group | Purpose | + See: [`non-hero-scenarios.md#operation-groups`](non-hero-scenarios.md#operation-groups) + +## Related deep-dive references + +- [`non-hero-scenarios.md`](non-hero-scenarios.md): Dedicated non-hero examples and implementation notes. + +## API breadth checklist + +- Verify client/auth mode for the environment before coding. +- Confirm operation-group/method names against current Microsoft Learn API reference. +- For Python SDKs with both sync and async clients, document both forms without a blanket preference. +- Include cleanup/delete paths for created resources in examples. +- Prefer idempotent create/update operations where available. +- Validate paging/LRO/error-handling patterns for production paths. diff --git a/.github/plugins/azure-sdk-python/skills/azure-mgmt-apimanagement-py/references/non-hero-scenarios.md b/.github/plugins/azure-sdk-python/skills/azure-mgmt-apimanagement-py/references/non-hero-scenarios.md new file mode 100644 index 00000000..fa31a077 --- /dev/null +++ b/.github/plugins/azure-sdk-python/skills/azure-mgmt-apimanagement-py/references/non-hero-scenarios.md @@ -0,0 +1,156 @@ +# azure-mgmt-apimanagement-py non-hero scenarios + +These scenarios are intentionally separate from hero flows in `SKILL.md`. +They cover secondary/advanced patterns typically used after the primary end-to-end path is working. + +## Create Product + +```python +from azure.mgmt.apimanagement.models import ProductContract + +product = client.product.create_or_update( + resource_group_name="my-resource-group", + service_name="my-apim", + product_id="premium", + parameters=ProductContract( + display_name="Premium", + description="Premium tier with unlimited access", + subscription_required=True, + approval_required=False, + state="published" + ) +) + +print(f"Created product: {product.display_name}") +``` + +## Add API to Product + +```python +client.product_api.create_or_update( + resource_group_name="my-resource-group", + service_name="my-apim", + product_id="premium", + api_id="my-api" +) +``` + +## Create Subscription + +```python +from azure.mgmt.apimanagement.models import SubscriptionCreateParameters + +subscription = client.subscription.create_or_update( + resource_group_name="my-resource-group", + service_name="my-apim", + sid="my-subscription", + parameters=SubscriptionCreateParameters( + display_name="My Subscription", + scope=f"/products/premium", + state="active" + ) +) + +print(f"Subscription key: {subscription.primary_key}") +``` + +## Set API Policy + +```python +from azure.mgmt.apimanagement.models import PolicyContract + +policy_xml = """ + + + + + CustomValue + + + + + + + + +""" + +client.api_policy.create_or_update( + resource_group_name="my-resource-group", + service_name="my-apim", + api_id="my-api", + policy_id="policy", + parameters=PolicyContract( + value=policy_xml, + format="xml" + ) +) +``` + +## Create Named Value (Secret) + +```python +from azure.mgmt.apimanagement.models import NamedValueCreateContract + +named_value = client.named_value.begin_create_or_update( + resource_group_name="my-resource-group", + service_name="my-apim", + named_value_id="backend-api-key", + parameters=NamedValueCreateContract( + display_name="Backend API Key", + value="secret-key-value", + secret=True + ) +).result() +``` + +## Create Backend + +```python +from azure.mgmt.apimanagement.models import BackendContract + +backend = client.backend.create_or_update( + resource_group_name="my-resource-group", + service_name="my-apim", + backend_id="my-backend", + parameters=BackendContract( + url="https://api.backend.example.com", + protocol="http", + description="My backend service" + ) +) +``` + +## Create User + +```python +from azure.mgmt.apimanagement.models import UserCreateParameters + +user = client.user.create_or_update( + resource_group_name="my-resource-group", + service_name="my-apim", + user_id="newuser", + parameters=UserCreateParameters( + email="user@example.com", + first_name="John", + last_name="Doe" + ) +) +``` + +## Operation Groups + +| Group | Purpose | +|-------|---------| +| `api_management_service` | APIM instance management | +| `api` | API operations | +| `api_operation` | API operation details | +| `api_policy` | API-level policies | +| `product` | Product management | +| `product_api` | Product-API associations | +| `subscription` | Subscription management | +| `user` | User management | +| `named_value` | Named values/secrets | +| `backend` | Backend services | +| `certificate` | Certificates | +| `gateway` | Self-hosted gateways | diff --git a/.github/plugins/azure-sdk-python/skills/azure-mgmt-botservice-py/SKILL.md b/.github/plugins/azure-sdk-python/skills/azure-mgmt-botservice-py/SKILL.md index ec8513af..4ad0b650 100644 --- a/.github/plugins/azure-sdk-python/skills/azure-mgmt-botservice-py/SKILL.md +++ b/.github/plugins/azure-sdk-python/skills/azure-mgmt-botservice-py/SKILL.md @@ -342,3 +342,10 @@ for conn in connections: 7. **Rotate Direct Line keys** periodically 8. **Use managed identity** when possible for bot connections 9. **Configure proper CORS** for Web Chat channel + +## Reference Files + +| File | Contents | +|------|----------| +| [references/capabilities.md](references/capabilities.md) | Additional non-hero capabilities, operation-group coverage, and production checklists. | +| [references/non-hero-scenarios.md](references/non-hero-scenarios.md) | Dedicated non-hero examples for secondary/advanced scenarios. | diff --git a/.github/plugins/azure-sdk-python/skills/azure-mgmt-botservice-py/references/capabilities.md b/.github/plugins/azure-sdk-python/skills/azure-mgmt-botservice-py/references/capabilities.md new file mode 100644 index 00000000..9cdefab7 --- /dev/null +++ b/.github/plugins/azure-sdk-python/skills/azure-mgmt-botservice-py/references/capabilities.md @@ -0,0 +1,46 @@ +# azure-mgmt-botservice-py capability coverage + +**SDK/package**: `azure-mgmt-botservice` + +This index maps hero scenarios in `SKILL.md` and links non-hero scenarios documented in dedicated reference files. + +## Hero scenarios covered in SKILL.md + +- `Create a Bot` +- `Get Bot Details` +- `List Bots in Resource Group` +- `List All Bots in Subscription` + +## Non-hero scenarios + +- `Update Bot`: Dedicated example and implementation notes. + See: [`non-hero-scenarios.md#update-bot`](non-hero-scenarios.md#update-bot) +- `Delete Bot`: Dedicated example and implementation notes. + See: [`non-hero-scenarios.md#delete-bot`](non-hero-scenarios.md#delete-bot) +- `Configure Channels`: Dedicated example and implementation notes. + See: [`non-hero-scenarios.md#configure-channels`](non-hero-scenarios.md#configure-channels) +- `Get Channel Details`: Dedicated example and implementation notes. + See: [`non-hero-scenarios.md#get-channel-details`](non-hero-scenarios.md#get-channel-details) +- `List Channel Keys`: Dedicated example and implementation notes. + See: [`non-hero-scenarios.md#list-channel-keys`](non-hero-scenarios.md#list-channel-keys) +- `Bot Connections (OAuth)`: Dedicated example and implementation notes. + See: [`non-hero-scenarios.md#bot-connections-oauth`](non-hero-scenarios.md#bot-connections-oauth) +- `Client Operations`: | Operation | Method | + See: [`non-hero-scenarios.md#client-operations`](non-hero-scenarios.md#client-operations) +- `SKU Options`: | SKU | Description | + See: [`non-hero-scenarios.md#sku-options`](non-hero-scenarios.md#sku-options) +- `Channel Types`: | Channel | Class | Purpose | + See: [`non-hero-scenarios.md#channel-types`](non-hero-scenarios.md#channel-types) + +## Related deep-dive references + +- [`non-hero-scenarios.md`](non-hero-scenarios.md): Dedicated non-hero examples and implementation notes. + +## API breadth checklist + +- Verify client/auth mode for the environment before coding. +- Confirm operation-group/method names against current Microsoft Learn API reference. +- For Python SDKs with both sync and async clients, document both forms without a blanket preference. +- Include cleanup/delete paths for created resources in examples. +- Prefer idempotent create/update operations where available. +- Validate paging/LRO/error-handling patterns for production paths. diff --git a/.github/plugins/azure-sdk-python/skills/azure-mgmt-botservice-py/references/non-hero-scenarios.md b/.github/plugins/azure-sdk-python/skills/azure-mgmt-botservice-py/references/non-hero-scenarios.md new file mode 100644 index 00000000..024f6a72 --- /dev/null +++ b/.github/plugins/azure-sdk-python/skills/azure-mgmt-botservice-py/references/non-hero-scenarios.md @@ -0,0 +1,208 @@ +# azure-mgmt-botservice-py non-hero scenarios + +These scenarios are intentionally separate from hero flows in `SKILL.md`. +They cover secondary/advanced patterns typically used after the primary end-to-end path is working. + +## Update Bot + +```python +bot = client.bots.update( + resource_group_name=resource_group, + resource_name=bot_name, + properties=BotProperties( + display_name="Updated Bot Name", + description="Updated description" + ) +) +``` + +## Delete Bot + +```python +client.bots.delete( + resource_group_name=resource_group, + resource_name=bot_name +) +``` + +## Configure Channels + +### Add Teams Channel + +```python +from azure.mgmt.botservice.models import ( + BotChannel, + MsTeamsChannel, + MsTeamsChannelProperties +) + +channel = client.channels.create( + resource_group_name=resource_group, + resource_name=bot_name, + channel_name="MsTeamsChannel", + parameters=BotChannel( + location="global", + properties=MsTeamsChannel( + properties=MsTeamsChannelProperties( + is_enabled=True + ) + ) + ) +) +``` + +### Add Direct Line Channel + +```python +from azure.mgmt.botservice.models import ( + BotChannel, + DirectLineChannel, + DirectLineChannelProperties, + DirectLineSite +) + +channel = client.channels.create( + resource_group_name=resource_group, + resource_name=bot_name, + channel_name="DirectLineChannel", + parameters=BotChannel( + location="global", + properties=DirectLineChannel( + properties=DirectLineChannelProperties( + sites=[ + DirectLineSite( + site_name="Default Site", + is_enabled=True, + is_v1_enabled=False, + is_v3_enabled=True + ) + ] + ) + ) + ) +) +``` + +### Add Web Chat Channel + +```python +from azure.mgmt.botservice.models import ( + BotChannel, + WebChatChannel, + WebChatChannelProperties, + WebChatSite +) + +channel = client.channels.create( + resource_group_name=resource_group, + resource_name=bot_name, + channel_name="WebChatChannel", + parameters=BotChannel( + location="global", + properties=WebChatChannel( + properties=WebChatChannelProperties( + sites=[ + WebChatSite( + site_name="Default Site", + is_enabled=True + ) + ] + ) + ) + ) +) +``` + +## Get Channel Details + +```python +channel = client.channels.get( + resource_group_name=resource_group, + resource_name=bot_name, + channel_name="DirectLineChannel" +) +``` + +## List Channel Keys + +```python +keys = client.channels.list_with_keys( + resource_group_name=resource_group, + resource_name=bot_name, + channel_name="DirectLineChannel" +) + +# Access Direct Line keys +if hasattr(keys.properties, 'properties'): + for site in keys.properties.properties.sites: + print(f"Site: {site.site_name}") + print(f"Key: {site.key}") +``` + +## Bot Connections (OAuth) + +### Create Connection Setting + +```python +from azure.mgmt.botservice.models import ( + ConnectionSetting, + ConnectionSettingProperties +) + +connection = client.bot_connection.create( + resource_group_name=resource_group, + resource_name=bot_name, + connection_name="graph-connection", + parameters=ConnectionSetting( + location="global", + properties=ConnectionSettingProperties( + client_id="", + client_secret="", + scopes="User.Read", + service_provider_id="" + ) + ) +) +``` + +### List Connections + +```python +connections = client.bot_connection.list_by_bot_service( + resource_group_name=resource_group, + resource_name=bot_name +) + +for conn in connections: + print(f"Connection: {conn.name}") +``` + +## Client Operations + +| Operation | Method | +|-----------|--------| +| `client.bots` | Bot CRUD operations | +| `client.channels` | Channel configuration | +| `client.bot_connection` | OAuth connection settings | +| `client.direct_line` | Direct Line channel operations | +| `client.email` | Email channel operations | +| `client.operations` | Available operations | +| `client.host_settings` | Host settings operations | + +## SKU Options + +| SKU | Description | +|-----|-------------| +| `F0` | Free tier (limited messages) | +| `S1` | Standard tier (unlimited messages) | + +## Channel Types + +| Channel | Class | Purpose | +|---------|-------|---------| +| `MsTeamsChannel` | Microsoft Teams | Teams integration | +| `DirectLineChannel` | Direct Line | Custom client integration | +| `WebChatChannel` | Web Chat | Embeddable web widget | +| `SlackChannel` | Slack | Slack workspace integration | +| `FacebookChannel` | Facebook | Messenger integration | +| `EmailChannel` | Email | Email communication | diff --git a/.github/plugins/azure-sdk-python/skills/azure-mgmt-fabric-py/SKILL.md b/.github/plugins/azure-sdk-python/skills/azure-mgmt-fabric-py/SKILL.md index fbb6c37b..31cb7e05 100644 --- a/.github/plugins/azure-sdk-python/skills/azure-mgmt-fabric-py/SKILL.md +++ b/.github/plugins/azure-sdk-python/skills/azure-mgmt-fabric-py/SKILL.md @@ -280,3 +280,10 @@ capacity = poller.result() 8. **Handle LRO properly** — don't assume immediate completion 9. **Set up capacity admins** — specify users who can manage workspaces 10. **Monitor capacity usage** via Azure Monitor metrics + +## Reference Files + +| File | Contents | +|------|----------| +| [references/capabilities.md](references/capabilities.md) | Additional non-hero capabilities, operation-group coverage, and production checklists. | +| [references/non-hero-scenarios.md](references/non-hero-scenarios.md) | Dedicated non-hero examples for secondary/advanced scenarios. | diff --git a/.github/plugins/azure-sdk-python/skills/azure-mgmt-fabric-py/references/capabilities.md b/.github/plugins/azure-sdk-python/skills/azure-mgmt-fabric-py/references/capabilities.md new file mode 100644 index 00000000..2671e9f6 --- /dev/null +++ b/.github/plugins/azure-sdk-python/skills/azure-mgmt-fabric-py/references/capabilities.md @@ -0,0 +1,48 @@ +# azure-mgmt-fabric-py capability coverage + +**SDK/package**: `azure-mgmt-fabric` + +This index maps hero scenarios in `SKILL.md` and links non-hero scenarios documented in dedicated reference files. + +## Hero scenarios covered in SKILL.md + +- `Create Fabric Capacity` +- `Get Capacity Details` +- `List Capacities in Resource Group` +- `List All Capacities in Subscription` + +## Non-hero scenarios + +- `Update Capacity`: Dedicated example and implementation notes. + See: [`non-hero-scenarios.md#update-capacity`](non-hero-scenarios.md#update-capacity) +- `Suspend Capacity`: Pause capacity to stop billing: + See: [`non-hero-scenarios.md#suspend-capacity`](non-hero-scenarios.md#suspend-capacity) +- `Resume Capacity`: Resume a paused capacity: + See: [`non-hero-scenarios.md#resume-capacity`](non-hero-scenarios.md#resume-capacity) +- `Delete Capacity`: Dedicated example and implementation notes. + See: [`non-hero-scenarios.md#delete-capacity`](non-hero-scenarios.md#delete-capacity) +- `Check Name Availability`: Dedicated example and implementation notes. + See: [`non-hero-scenarios.md#check-name-availability`](non-hero-scenarios.md#check-name-availability) +- `List Available SKUs`: Dedicated example and implementation notes. + See: [`non-hero-scenarios.md#list-available-skus`](non-hero-scenarios.md#list-available-skus) +- `Client Operations`: | Operation | Method | + See: [`non-hero-scenarios.md#client-operations`](non-hero-scenarios.md#client-operations) +- `Fabric SKUs`: | SKU | Description | CUs | + See: [`non-hero-scenarios.md#fabric-skus`](non-hero-scenarios.md#fabric-skus) +- `Capacity States`: | State | Description | + See: [`non-hero-scenarios.md#capacity-states`](non-hero-scenarios.md#capacity-states) +- `Long-Running Operations`: All mutating operations are long-running (LRO). Use `.result()` to wait: + See: [`non-hero-scenarios.md#long-running-operations`](non-hero-scenarios.md#long-running-operations) + +## Related deep-dive references + +- [`non-hero-scenarios.md`](non-hero-scenarios.md): Dedicated non-hero examples and implementation notes. + +## API breadth checklist + +- Verify client/auth mode for the environment before coding. +- Confirm operation-group/method names against current Microsoft Learn API reference. +- For Python SDKs with both sync and async clients, document both forms without a blanket preference. +- Include cleanup/delete paths for created resources in examples. +- Prefer idempotent create/update operations where available. +- Validate paging/LRO/error-handling patterns for production paths. diff --git a/.github/plugins/azure-sdk-python/skills/azure-mgmt-fabric-py/references/non-hero-scenarios.md b/.github/plugins/azure-sdk-python/skills/azure-mgmt-fabric-py/references/non-hero-scenarios.md new file mode 100644 index 00000000..cffbf63d --- /dev/null +++ b/.github/plugins/azure-sdk-python/skills/azure-mgmt-fabric-py/references/non-hero-scenarios.md @@ -0,0 +1,142 @@ +# azure-mgmt-fabric-py non-hero scenarios + +These scenarios are intentionally separate from hero flows in `SKILL.md`. +They cover secondary/advanced patterns typically used after the primary end-to-end path is working. + +## Update Capacity + +```python +from azure.mgmt.fabric.models import FabricCapacityUpdate, CapacitySku + +updated = client.fabric_capacities.begin_update( + resource_group_name=resource_group, + capacity_name=capacity_name, + properties=FabricCapacityUpdate( + sku=CapacitySku( + name="F4", # Scale up + tier="Fabric" + ), + tags={"environment": "production"} + ) +).result() + +print(f"Updated SKU: {updated.sku.name}") +``` + +## Suspend Capacity + +Pause capacity to stop billing: + +```python +client.fabric_capacities.begin_suspend( + resource_group_name=resource_group, + capacity_name=capacity_name +).result() + +print("Capacity suspended") +``` + +## Resume Capacity + +Resume a paused capacity: + +```python +client.fabric_capacities.begin_resume( + resource_group_name=resource_group, + capacity_name=capacity_name +).result() + +print("Capacity resumed") +``` + +## Delete Capacity + +```python +client.fabric_capacities.begin_delete( + resource_group_name=resource_group, + capacity_name=capacity_name +).result() + +print("Capacity deleted") +``` + +## Check Name Availability + +```python +from azure.mgmt.fabric.models import CheckNameAvailabilityRequest + +result = client.fabric_capacities.check_name_availability( + location="eastus", + body=CheckNameAvailabilityRequest( + name="my-new-capacity", + type="Microsoft.Fabric/capacities" + ) +) + +if result.name_available: + print("Name is available") +else: + print(f"Name not available: {result.reason}") +``` + +## List Available SKUs + +```python +skus = client.fabric_capacities.list_skus( + resource_group_name=resource_group, + capacity_name=capacity_name +) + +for sku in skus: + print(f"SKU: {sku.name} - Tier: {sku.tier}") +``` + +## Client Operations + +| Operation | Method | +|-----------|--------| +| `client.fabric_capacities` | Capacity CRUD operations | +| `client.operations` | List available operations | + +## Fabric SKUs + +| SKU | Description | CUs | +|-----|-------------|-----| +| `F2` | Entry level | 2 Capacity Units | +| `F4` | Small | 4 Capacity Units | +| `F8` | Medium | 8 Capacity Units | +| `F16` | Large | 16 Capacity Units | +| `F32` | X-Large | 32 Capacity Units | +| `F64` | 2X-Large | 64 Capacity Units | +| `F128` | 4X-Large | 128 Capacity Units | +| `F256` | 8X-Large | 256 Capacity Units | +| `F512` | 16X-Large | 512 Capacity Units | +| `F1024` | 32X-Large | 1024 Capacity Units | +| `F2048` | 64X-Large | 2048 Capacity Units | + +## Capacity States + +| State | Description | +|-------|-------------| +| `Active` | Capacity is running | +| `Paused` | Capacity is suspended (no billing) | +| `Provisioning` | Being created | +| `Updating` | Being modified | +| `Deleting` | Being removed | +| `Failed` | Operation failed | + +## Long-Running Operations + +All mutating operations are long-running (LRO). Use `.result()` to wait: + +```python +# Synchronous wait +capacity = client.fabric_capacities.begin_create_or_update(...).result() + +# Or poll manually +poller = client.fabric_capacities.begin_create_or_update(...) +while not poller.done(): + print(f"Status: {poller.status()}") + time.sleep(5) +capacity = poller.result() +``` diff --git a/.github/plugins/azure-sdk-python/skills/azure-monitor-ingestion-py/SKILL.md b/.github/plugins/azure-sdk-python/skills/azure-monitor-ingestion-py/SKILL.md index b6146061..56f0f86d 100644 --- a/.github/plugins/azure-sdk-python/skills/azure-monitor-ingestion-py/SKILL.md +++ b/.github/plugins/azure-sdk-python/skills/azure-monitor-ingestion-py/SKILL.md @@ -228,3 +228,10 @@ Stream names follow patterns: 7. **Use async client** for high-throughput scenarios 8. **Batch uploads** — SDK handles batching, but send reasonable chunks 9. **Monitor ingestion** — Check Log Analytics for ingestion status + +## Reference Files + +| File | Contents | +|------|----------| +| [references/capabilities.md](references/capabilities.md) | Additional non-hero capabilities, operation-group coverage, and production checklists. | +| [references/non-hero-scenarios.md](references/non-hero-scenarios.md) | Dedicated non-hero examples for secondary/advanced scenarios. | diff --git a/.github/plugins/azure-sdk-python/skills/azure-monitor-ingestion-py/references/capabilities.md b/.github/plugins/azure-sdk-python/skills/azure-monitor-ingestion-py/references/capabilities.md new file mode 100644 index 00000000..be938859 --- /dev/null +++ b/.github/plugins/azure-sdk-python/skills/azure-monitor-ingestion-py/references/capabilities.md @@ -0,0 +1,40 @@ +# azure-monitor-ingestion-py capability coverage + +**SDK/package**: `azure-monitor-ingestion` + +This index maps hero scenarios in `SKILL.md` and links non-hero scenarios documented in dedicated reference files. + +## Hero scenarios covered in SKILL.md + +- `Upload Custom Logs` +- `Upload from JSON File` +- `Custom Error Handling` +- `Ignore Errors` + +## Non-hero scenarios + +- `Async Client`: Dedicated example and implementation notes. + See: [`non-hero-scenarios.md#async-client`](non-hero-scenarios.md#async-client) +- `Sovereign Clouds`: Dedicated example and implementation notes. + See: [`non-hero-scenarios.md#sovereign-clouds`](non-hero-scenarios.md#sovereign-clouds) +- `Batching Behavior`: The SDK automatically: + See: [`non-hero-scenarios.md#batching-behavior`](non-hero-scenarios.md#batching-behavior) +- `Client Types`: | Client | Purpose | + See: [`non-hero-scenarios.md#client-types`](non-hero-scenarios.md#client-types) +- `Key Concepts`: | Concept | Description | + See: [`non-hero-scenarios.md#key-concepts`](non-hero-scenarios.md#key-concepts) +- `DCR Stream Name Format`: Stream names follow patterns: + See: [`non-hero-scenarios.md#dcr-stream-name-format`](non-hero-scenarios.md#dcr-stream-name-format) + +## Related deep-dive references + +- [`non-hero-scenarios.md`](non-hero-scenarios.md): Dedicated non-hero examples and implementation notes. + +## API breadth checklist + +- Verify client/auth mode for the environment before coding. +- Confirm operation-group/method names against current Microsoft Learn API reference. +- For Python SDKs with both sync and async clients, document both forms without a blanket preference. +- Include cleanup/delete paths for created resources in examples. +- Prefer idempotent create/update operations where available. +- Validate paging/LRO/error-handling patterns for production paths. diff --git a/.github/plugins/azure-sdk-python/skills/azure-monitor-ingestion-py/references/non-hero-scenarios.md b/.github/plugins/azure-sdk-python/skills/azure-monitor-ingestion-py/references/non-hero-scenarios.md new file mode 100644 index 00000000..620e311e --- /dev/null +++ b/.github/plugins/azure-sdk-python/skills/azure-monitor-ingestion-py/references/non-hero-scenarios.md @@ -0,0 +1,73 @@ +# azure-monitor-ingestion-py non-hero scenarios + +These scenarios are intentionally separate from hero flows in `SKILL.md`. +They cover secondary/advanced patterns typically used after the primary end-to-end path is working. + +## Async Client + +```python +import asyncio +from azure.monitor.ingestion.aio import LogsIngestionClient +from azure.identity.aio import DefaultAzureCredential + +async def upload_logs(): + async with LogsIngestionClient( + endpoint=endpoint, + credential=DefaultAzureCredential() + ) as client: + await client.upload( + rule_id=rule_id, + stream_name=stream_name, + logs=logs + ) + +asyncio.run(upload_logs()) +``` + +## Sovereign Clouds + +```python +from azure.identity import AzureAuthorityHosts, DefaultAzureCredential +from azure.monitor.ingestion import LogsIngestionClient + +# Azure Government +credential = DefaultAzureCredential(authority=AzureAuthorityHosts.AZURE_GOVERNMENT) +with LogsIngestionClient( + endpoint="https://example.ingest.monitor.azure.us", + credential=credential, + credential_scopes=["https://monitor.azure.us/.default"] +) as client: + # client.upload(...) + ... +``` + +## Batching Behavior + +The SDK automatically: +- Splits logs into chunks of 1MB or less +- Compresses each chunk with gzip +- Uploads chunks in parallel + +No manual batching needed for large log sets. + +## Client Types + +| Client | Purpose | +|--------|---------| +| `LogsIngestionClient` | Sync client for uploading logs | +| `LogsIngestionClient` (aio) | Async client for uploading logs | + +## Key Concepts + +| Concept | Description | +|---------|-------------| +| **DCE** | Data Collection Endpoint — ingestion URL | +| **DCR** | Data Collection Rule — defines schema, transformations, destination | +| **Stream** | Named data flow within a DCR | +| **Custom Table** | Target table in Log Analytics (ends with `_CL`) | + +## DCR Stream Name Format + +Stream names follow patterns: +- `Custom-_CL` — For custom tables +- `Microsoft-` — For built-in tables diff --git a/.github/plugins/azure-sdk-python/skills/azure-monitor-opentelemetry-exporter-py/SKILL.md b/.github/plugins/azure-sdk-python/skills/azure-monitor-opentelemetry-exporter-py/SKILL.md index bd9553c4..86f904ba 100644 --- a/.github/plugins/azure-sdk-python/skills/azure-monitor-opentelemetry-exporter-py/SKILL.md +++ b/.github/plugins/azure-sdk-python/skills/azure-monitor-opentelemetry-exporter-py/SKILL.md @@ -27,7 +27,16 @@ APPLICATIONINSIGHTS_CONNECTION_STRING=InstrumentationKey=xxx;IngestionEndpoint=h AZURE_TOKEN_CREDENTIALS=prod # Required only if DefaultAzureCredential is used in production ``` -> **🔑 Auth & lifecycle:** These exporters take a connection string by design, but for *AAD-authenticated ingestion* (where supported) prefer `DefaultAzureCredential` via the `credential=` parameter — see the [Azure AD Authentication](#azure-ad-authentication) section. Any Azure SDK clients you create alongside the exporter should be wrapped in `with`/`async with` blocks (and async credentials from `azure.identity.aio` likewise). +## Authentication & Lifecycle + +> **🔑 Two rules apply to every code sample below:** +> +> 1. **Prefer `DefaultAzureCredential` for ingestion auth when supported.** `APPLICATIONINSIGHTS_CONNECTION_STRING` identifies the target Application Insights resource, and `credential=DefaultAzureCredential(...)` provides Microsoft Entra authentication. +> - Local dev: `DefaultAzureCredential` works as-is. +> - Production: set `AZURE_TOKEN_CREDENTIALS=prod` (or `AZURE_TOKEN_CREDENTIALS=`) to constrain the credential chain to production-safe credentials. +> 2. **Providers are not context managers.** Flush and shut down telemetry providers explicitly at process exit so buffers are exported deterministically. +> +> Snippets may abbreviate this setup, but production code should always follow both rules. ## When to Use @@ -221,10 +230,17 @@ exporter = AzureMonitorTraceExporter( ## Best Practices 1. **Pick sync OR async and stay consistent.** Do not mix `azure.xxx` sync clients with `azure.xxx.aio` async clients in the same call path. Choose one mode per module. -2. **Flush and shut down providers at process exit.** Call the shutdown/flush APIs (e.g. `tracer_provider.shutdown()`, `meter_provider.shutdown()`, `logger_provider.shutdown()`) at process exit to flush telemetry before the process terminates. +2. **Call `provider.shutdown()` / `flush()` at process exit to flush telemetry — providers are not context managers.** 3. **Use BatchSpanProcessor** for production (not SimpleSpanProcessor) 4. **Use ApplicationInsightsSampler** for consistent sampling across services 5. **Enable offline storage** for reliability in production 6. **Use Microsoft Entra authentication** instead of instrumentation keys 7. **Set export intervals** appropriate for your workload 8. **Use the distro** (`azure-monitor-opentelemetry`) unless you need custom pipelines + +## Reference Files + +| File | Contents | +|------|----------| +| [references/capabilities.md](references/capabilities.md) | Additional non-hero capabilities, operation-group coverage, and production checklists. | +| [references/non-hero-scenarios.md](references/non-hero-scenarios.md) | Dedicated non-hero examples for secondary/advanced scenarios. | diff --git a/.github/plugins/azure-sdk-python/skills/azure-monitor-opentelemetry-exporter-py/references/capabilities.md b/.github/plugins/azure-sdk-python/skills/azure-monitor-opentelemetry-exporter-py/references/capabilities.md new file mode 100644 index 00000000..6cddf922 --- /dev/null +++ b/.github/plugins/azure-sdk-python/skills/azure-monitor-opentelemetry-exporter-py/references/capabilities.md @@ -0,0 +1,42 @@ +# azure-monitor-opentelemetry-exporter-py capability coverage + +**SDK/package**: `azure-monitor-opentelemetry-exporter` + +This index maps hero scenarios in `SKILL.md` and links non-hero scenarios documented in dedicated reference files. + +## Hero scenarios covered in SKILL.md + +- `Trace Exporter` +- `Metric Exporter` +- `Log Exporter` +- `From Environment Variable` + +## Non-hero scenarios + +- `Azure AD Authentication`: Dedicated example and implementation notes. + See: [`non-hero-scenarios.md#azure-ad-authentication`](non-hero-scenarios.md#azure-ad-authentication) +- `Sampling`: Use `ApplicationInsightsSampler` for consistent sampling: + See: [`non-hero-scenarios.md#sampling`](non-hero-scenarios.md#sampling) +- `Offline Storage`: Configure offline storage for retry: + See: [`non-hero-scenarios.md#offline-storage`](non-hero-scenarios.md#offline-storage) +- `Disable Offline Storage`: Dedicated example and implementation notes. + See: [`non-hero-scenarios.md#disable-offline-storage`](non-hero-scenarios.md#disable-offline-storage) +- `Sovereign Clouds`: Dedicated example and implementation notes. + See: [`non-hero-scenarios.md#sovereign-clouds`](non-hero-scenarios.md#sovereign-clouds) +- `Exporter Types`: | Exporter | Telemetry Type | Application Insights Table | + See: [`non-hero-scenarios.md#exporter-types`](non-hero-scenarios.md#exporter-types) +- `Configuration Options`: | Parameter | Description | Default | + See: [`non-hero-scenarios.md#configuration-options`](non-hero-scenarios.md#configuration-options) + +## Related deep-dive references + +- [`non-hero-scenarios.md`](non-hero-scenarios.md): Dedicated non-hero examples and implementation notes. + +## API breadth checklist + +- Verify client/auth mode for the environment before coding. +- Confirm operation-group/method names against current Microsoft Learn API reference. +- For Python SDKs with both sync and async clients, document both forms without a blanket preference. +- Include cleanup/delete paths for created resources in examples. +- Prefer idempotent create/update operations where available. +- Validate paging/LRO/error-handling patterns for production paths. diff --git a/.github/plugins/azure-sdk-python/skills/azure-monitor-opentelemetry-exporter-py/references/non-hero-scenarios.md b/.github/plugins/azure-sdk-python/skills/azure-monitor-opentelemetry-exporter-py/references/non-hero-scenarios.md new file mode 100644 index 00000000..566af556 --- /dev/null +++ b/.github/plugins/azure-sdk-python/skills/azure-monitor-opentelemetry-exporter-py/references/non-hero-scenarios.md @@ -0,0 +1,91 @@ +# azure-monitor-opentelemetry-exporter-py non-hero scenarios + +These scenarios are intentionally separate from hero flows in `SKILL.md`. +They cover secondary/advanced patterns typically used after the primary end-to-end path is working. + +## Azure AD Authentication + +```python +from azure.identity import DefaultAzureCredential, ManagedIdentityCredential +from azure.monitor.opentelemetry.exporter import AzureMonitorTraceExporter + +# Local dev: DefaultAzureCredential. Production: set AZURE_TOKEN_CREDENTIALS=prod or AZURE_TOKEN_CREDENTIALS= +credential = DefaultAzureCredential(require_envvar=True) +# Or use a specific credential directly in production: +# See https://learn.microsoft.com/python/api/overview/azure/identity-readme?view=azure-python#credential-classes +# credential = ManagedIdentityCredential() + +exporter = AzureMonitorTraceExporter( + credential=credential +) +``` + +## Sampling + +Use `ApplicationInsightsSampler` for consistent sampling: + +```python +from opentelemetry.sdk.trace import TracerProvider +from opentelemetry.sdk.trace.sampling import ParentBasedTraceIdRatio +from azure.monitor.opentelemetry.exporter import ApplicationInsightsSampler + +# Sample 10% of traces +sampler = ApplicationInsightsSampler(sampling_ratio=0.1) + +trace.set_tracer_provider(TracerProvider(sampler=sampler)) +``` + +## Offline Storage + +Configure offline storage for retry: + +```python +from azure.identity import DefaultAzureCredential +from azure.monitor.opentelemetry.exporter import AzureMonitorTraceExporter + +exporter = AzureMonitorTraceExporter( + credential=DefaultAzureCredential(), + storage_directory="/path/to/storage", # Custom storage path + disable_offline_storage=False # Enable retry (default) +) +``` + +## Disable Offline Storage + +```python +exporter = AzureMonitorTraceExporter( + credential=DefaultAzureCredential(), + disable_offline_storage=True # No retry on failure +) +``` + +## Sovereign Clouds + +```python +from azure.identity import AzureAuthorityHosts, DefaultAzureCredential +from azure.monitor.opentelemetry.exporter import AzureMonitorTraceExporter + +# Azure Government +credential = DefaultAzureCredential(authority=AzureAuthorityHosts.AZURE_GOVERNMENT) +exporter = AzureMonitorTraceExporter( + connection_string="InstrumentationKey=xxx;IngestionEndpoint=https://xxx.in.applicationinsights.azure.us/", + credential=credential +) +``` + +## Exporter Types + +| Exporter | Telemetry Type | Application Insights Table | +|----------|---------------|---------------------------| +| `AzureMonitorTraceExporter` | Traces/Spans | requests, dependencies, exceptions | +| `AzureMonitorMetricExporter` | Metrics | customMetrics, performanceCounters | +| `AzureMonitorLogExporter` | Logs | traces, customEvents | + +## Configuration Options + +| Parameter | Description | Default | +|-----------|-------------|---------| +| `connection_string` | Application Insights connection string | From env var | +| `credential` | Azure credential for AAD auth | None | +| `disable_offline_storage` | Disable retry storage | False | +| `storage_directory` | Custom storage path | Temp directory | diff --git a/.github/plugins/azure-sdk-python/skills/azure-monitor-opentelemetry-py/SKILL.md b/.github/plugins/azure-sdk-python/skills/azure-monitor-opentelemetry-py/SKILL.md index 00f1d753..ef0b2e0f 100644 --- a/.github/plugins/azure-sdk-python/skills/azure-monitor-opentelemetry-py/SKILL.md +++ b/.github/plugins/azure-sdk-python/skills/azure-monitor-opentelemetry-py/SKILL.md @@ -27,7 +27,16 @@ APPLICATIONINSIGHTS_CONNECTION_STRING=InstrumentationKey=xxx;IngestionEndpoint=h AZURE_TOKEN_CREDENTIALS=prod # Required only if DefaultAzureCredential is used in production ``` -> **🔑 Auth & lifecycle:** This distro is configured with a connection string by design, but for *AAD-authenticated ingestion* (where supported) prefer `DefaultAzureCredential` via the `credential=` parameter — see the [Azure AD Authentication](#azure-ad-authentication) section. Any Azure SDK clients you create alongside the exporter should be wrapped in `with`/`async with` blocks (and async credentials from `azure.identity.aio` likewise). +## Authentication & Lifecycle + +> **🔑 Two rules apply to every code sample below:** +> +> 1. **Prefer `DefaultAzureCredential` for ingestion auth when supported.** `APPLICATIONINSIGHTS_CONNECTION_STRING` identifies the target Application Insights resource, and `credential=DefaultAzureCredential(...)` provides Microsoft Entra authentication. +> - Local dev: `DefaultAzureCredential` works as-is. +> - Production: set `AZURE_TOKEN_CREDENTIALS=prod` (or `AZURE_TOKEN_CREDENTIALS=`) to constrain the credential chain to production-safe credentials. +> 2. **Providers are not context managers.** Flush and shut down telemetry providers explicitly at process exit so buffers are exported deterministically. +> +> Snippets may abbreviate this setup, but production code should always follow both rules. ## Quick Start @@ -236,7 +245,7 @@ configure_azure_monitor( ## Best Practices 1. **Pick sync OR async and stay consistent.** Do not mix `azure.xxx` sync clients with `azure.xxx.aio` async clients in the same call path. Choose one mode per module. -2. **Flush and shut down providers at process exit.** Call the shutdown/flush APIs (e.g. `tracer_provider.shutdown()`, `meter_provider.shutdown()`, `logger_provider.shutdown()`) at process exit to flush telemetry before the process terminates. +2. **Call `provider.shutdown()` / `flush()` at process exit to flush telemetry — providers are not context managers.** 3. **Call configure_azure_monitor() early** — Before importing instrumented libraries 4. **Use environment variables** for connection string in production 5. **Set cloud role name** for multi-service applications @@ -244,3 +253,10 @@ configure_azure_monitor( 7. **Use structured logging** for better log analytics queries 8. **Add custom attributes** to spans for better debugging 9. **Use Microsoft Entra authentication** for production workloads + +## Reference Files + +| File | Contents | +|------|----------| +| [references/capabilities.md](references/capabilities.md) | Additional non-hero capabilities, operation-group coverage, and production checklists. | +| [references/non-hero-scenarios.md](references/non-hero-scenarios.md) | Dedicated non-hero examples for secondary/advanced scenarios. | diff --git a/.github/plugins/azure-sdk-python/skills/azure-monitor-opentelemetry-py/references/capabilities.md b/.github/plugins/azure-sdk-python/skills/azure-monitor-opentelemetry-py/references/capabilities.md new file mode 100644 index 00000000..8876f7ae --- /dev/null +++ b/.github/plugins/azure-sdk-python/skills/azure-monitor-opentelemetry-py/references/capabilities.md @@ -0,0 +1,48 @@ +# azure-monitor-opentelemetry-py capability coverage + +**SDK/package**: `azure-monitor-opentelemetry` + +This index maps hero scenarios in `SKILL.md` and links non-hero scenarios documented in dedicated reference files. + +## Hero scenarios covered in SKILL.md + +- `Explicit Configuration` +- `With Flask` +- `With Django` +- `With FastAPI` + +## Non-hero scenarios + +- `Custom Traces`: Dedicated example and implementation notes. + See: [`non-hero-scenarios.md#custom-traces`](non-hero-scenarios.md#custom-traces) +- `Custom Metrics`: Dedicated example and implementation notes. + See: [`non-hero-scenarios.md#custom-metrics`](non-hero-scenarios.md#custom-metrics) +- `Custom Logs`: Dedicated example and implementation notes. + See: [`non-hero-scenarios.md#custom-logs`](non-hero-scenarios.md#custom-logs) +- `Sampling`: Dedicated example and implementation notes. + See: [`non-hero-scenarios.md#sampling`](non-hero-scenarios.md#sampling) +- `Cloud Role Name`: Set cloud role name for Application Map: + See: [`non-hero-scenarios.md#cloud-role-name`](non-hero-scenarios.md#cloud-role-name) +- `Disable Specific Instrumentations`: Dedicated example and implementation notes. + See: [`non-hero-scenarios.md#disable-specific-instrumentations`](non-hero-scenarios.md#disable-specific-instrumentations) +- `Enable Live Metrics`: Dedicated example and implementation notes. + See: [`non-hero-scenarios.md#enable-live-metrics`](non-hero-scenarios.md#enable-live-metrics) +- `Azure AD Authentication`: Dedicated example and implementation notes. + See: [`non-hero-scenarios.md#azure-ad-authentication`](non-hero-scenarios.md#azure-ad-authentication) +- `Auto-Instrumentations Included`: | Library | Telemetry Type | + See: [`non-hero-scenarios.md#auto-instrumentations-included`](non-hero-scenarios.md#auto-instrumentations-included) +- `Configuration Options`: | Parameter | Description | Default | + See: [`non-hero-scenarios.md#configuration-options`](non-hero-scenarios.md#configuration-options) + +## Related deep-dive references + +- [`non-hero-scenarios.md`](non-hero-scenarios.md): Dedicated non-hero examples and implementation notes. + +## API breadth checklist + +- Verify client/auth mode for the environment before coding. +- Confirm operation-group/method names against current Microsoft Learn API reference. +- For Python SDKs with both sync and async clients, document both forms without a blanket preference. +- Include cleanup/delete paths for created resources in examples. +- Prefer idempotent create/update operations where available. +- Validate paging/LRO/error-handling patterns for production paths. diff --git a/.github/plugins/azure-sdk-python/skills/azure-monitor-opentelemetry-py/references/non-hero-scenarios.md b/.github/plugins/azure-sdk-python/skills/azure-monitor-opentelemetry-py/references/non-hero-scenarios.md new file mode 100644 index 00000000..384bb1c2 --- /dev/null +++ b/.github/plugins/azure-sdk-python/skills/azure-monitor-opentelemetry-py/references/non-hero-scenarios.md @@ -0,0 +1,136 @@ +# azure-monitor-opentelemetry-py non-hero scenarios + +These scenarios are intentionally separate from hero flows in `SKILL.md`. +They cover secondary/advanced patterns typically used after the primary end-to-end path is working. + +## Custom Traces + +```python +from opentelemetry import trace +from azure.monitor.opentelemetry import configure_azure_monitor + +configure_azure_monitor() + +tracer = trace.get_tracer(__name__) + +with tracer.start_as_current_span("my-operation") as span: + span.set_attribute("custom.attribute", "value") + # Do work... +``` + +## Custom Metrics + +```python +from opentelemetry import metrics +from azure.monitor.opentelemetry import configure_azure_monitor + +configure_azure_monitor() + +meter = metrics.get_meter(__name__) +counter = meter.create_counter("my_counter") + +counter.add(1, {"dimension": "value"}) +``` + +## Custom Logs + +```python +import logging +from azure.monitor.opentelemetry import configure_azure_monitor + +configure_azure_monitor() + +logger = logging.getLogger(__name__) +logger.setLevel(logging.INFO) + +logger.info("This will appear in Application Insights") +logger.error("Errors are captured too", exc_info=True) +``` + +## Sampling + +```python +from azure.monitor.opentelemetry import configure_azure_monitor + +# Sample 10% of requests +configure_azure_monitor( + sampling_ratio=0.1 +) +``` + +## Cloud Role Name + +Set cloud role name for Application Map: + +```python +from azure.monitor.opentelemetry import configure_azure_monitor +from opentelemetry.sdk.resources import Resource, SERVICE_NAME + +configure_azure_monitor( + resource=Resource.create({SERVICE_NAME: "my-service-name"}) +) +``` + +## Disable Specific Instrumentations + +```python +from azure.monitor.opentelemetry import configure_azure_monitor + +configure_azure_monitor( + instrumentations=["flask", "requests"] # Only enable these +) +``` + +## Enable Live Metrics + +```python +from azure.monitor.opentelemetry import configure_azure_monitor + +configure_azure_monitor( + enable_live_metrics=True +) +``` + +## Azure AD Authentication + +```python +from azure.monitor.opentelemetry import configure_azure_monitor +from azure.identity import DefaultAzureCredential, ManagedIdentityCredential + +# Local dev: DefaultAzureCredential. Production: set AZURE_TOKEN_CREDENTIALS=prod or AZURE_TOKEN_CREDENTIALS= +credential = DefaultAzureCredential(require_envvar=True) +# Or use a specific credential directly in production: +# See https://learn.microsoft.com/python/api/overview/azure/identity-readme?view=azure-python#credential-classes +# credential = ManagedIdentityCredential() + +configure_azure_monitor( + credential=credential +) +``` + +## Auto-Instrumentations Included + +| Library | Telemetry Type | +|---------|---------------| +| Flask | Traces | +| Django | Traces | +| FastAPI | Traces | +| Requests | Traces | +| urllib3 | Traces | +| httpx | Traces | +| aiohttp | Traces | +| psycopg2 | Traces | +| pymysql | Traces | +| pymongo | Traces | +| redis | Traces | + +## Configuration Options + +| Parameter | Description | Default | +|-----------|-------------|---------| +| `connection_string` | Application Insights connection string | From env var | +| `credential` | Azure credential for AAD auth | None | +| `sampling_ratio` | Sampling rate (0.0 to 1.0) | 1.0 | +| `resource` | OpenTelemetry Resource | Auto-detected | +| `instrumentations` | List of instrumentations to enable | All | +| `enable_live_metrics` | Enable Live Metrics stream | False | diff --git a/.github/plugins/azure-sdk-python/skills/azure-monitor-query-py/SKILL.md b/.github/plugins/azure-sdk-python/skills/azure-monitor-query-py/SKILL.md index 95defd74..c0ce6826 100644 --- a/.github/plugins/azure-sdk-python/skills/azure-monitor-query-py/SKILL.md +++ b/.github/plugins/azure-sdk-python/skills/azure-monitor-query-py/SKILL.md @@ -267,3 +267,10 @@ AppExceptions 7. **Convert to DataFrame** for easier data analysis 8. **Use aggregations** to summarize metric data 9. **Filter by dimensions** to narrow metric results + +## Reference Files + +| File | Contents | +|------|----------| +| [references/capabilities.md](references/capabilities.md) | Additional non-hero capabilities, operation-group coverage, and production checklists. | +| [references/non-hero-scenarios.md](references/non-hero-scenarios.md) | Dedicated non-hero examples for secondary/advanced scenarios. | diff --git a/.github/plugins/azure-sdk-python/skills/azure-monitor-query-py/references/capabilities.md b/.github/plugins/azure-sdk-python/skills/azure-monitor-query-py/references/capabilities.md new file mode 100644 index 00000000..8cf8156e --- /dev/null +++ b/.github/plugins/azure-sdk-python/skills/azure-monitor-query-py/references/capabilities.md @@ -0,0 +1,30 @@ +# azure-monitor-query-py capability coverage + +**SDK/package**: `azure-monitor-query` + +This index maps hero scenarios in `SKILL.md` and links non-hero scenarios documented in dedicated reference files. + +## Hero scenarios covered in SKILL.md + +- `Logs Query Client` +- `Metrics Query Client` +- `Async Clients` +- `Common Kusto Queries` + +## Non-hero scenarios + +- `Client Types`: | Client | Purpose | + See: [`non-hero-scenarios.md#client-types`](non-hero-scenarios.md#client-types) + +## Related deep-dive references + +- [`non-hero-scenarios.md`](non-hero-scenarios.md): Dedicated non-hero examples and implementation notes. + +## API breadth checklist + +- Verify client/auth mode for the environment before coding. +- Confirm operation-group/method names against current Microsoft Learn API reference. +- For Python SDKs with both sync and async clients, document both forms without a blanket preference. +- Include cleanup/delete paths for created resources in examples. +- Prefer idempotent create/update operations where available. +- Validate paging/LRO/error-handling patterns for production paths. diff --git a/.github/plugins/azure-sdk-python/skills/azure-monitor-query-py/references/non-hero-scenarios.md b/.github/plugins/azure-sdk-python/skills/azure-monitor-query-py/references/non-hero-scenarios.md new file mode 100644 index 00000000..82a76632 --- /dev/null +++ b/.github/plugins/azure-sdk-python/skills/azure-monitor-query-py/references/non-hero-scenarios.md @@ -0,0 +1,11 @@ +# azure-monitor-query-py non-hero scenarios + +These scenarios are intentionally separate from hero flows in `SKILL.md`. +They cover secondary/advanced patterns typically used after the primary end-to-end path is working. + +## Client Types + +| Client | Purpose | +|--------|---------| +| `LogsQueryClient` | Query Log Analytics workspaces | +| `MetricsQueryClient` | Query Azure Monitor metrics | diff --git a/.github/plugins/azure-sdk-python/skills/azure-speech-to-text-rest-py/SKILL.md b/.github/plugins/azure-sdk-python/skills/azure-speech-to-text-rest-py/SKILL.md index b0f96a3e..9fa73c65 100644 --- a/.github/plugins/azure-sdk-python/skills/azure-speech-to-text-rest-py/SKILL.md +++ b/.github/plugins/azure-sdk-python/skills/azure-speech-to-text-rest-py/SKILL.md @@ -37,6 +37,17 @@ AZURE_SPEECH_ENDPOINT=https://.stt.speech.microsoft.com pip install requests ``` +## Authentication & Lifecycle + +> **🔑 Two rules apply to every code sample below:** +> +> 1. **This API currently requires key-based authentication.** `DefaultAzureCredential` / Entra ID auth isn't available for this REST path yet, so use `AZURE_SPEECH_KEY` and `AZURE_SPEECH_REGION` from environment variables (never hardcoded in source). +> 2. **Use context managers for files and HTTP resources** so file handles and network connections are released deterministically: +> - Sync: `with open(...) as f:` and (when reusing connections) `with requests.Session() as session:` +> - Async: `async with aiohttp.ClientSession() as session:` +> +> Snippets may abbreviate this setup, but production code should always follow both rules. + ## Quick Start ```python @@ -352,7 +363,7 @@ Common language codes (see [full list](https://learn.microsoft.com/azure/ai-serv ## Best Practices 1. **Pick sync OR async and stay consistent.** Do not mix `azure.xxx` sync clients with `azure.xxx.aio` async clients in the same call path. Choose one mode per module. -2. **Always use context managers for clients.** Use `with httpx.Client(...) as client:` (sync) or `async with httpx.AsyncClient(...) as client:` (async) so connections are pooled and closed deterministically. +2. **Use context managers for files and HTTP resources.** Use `with open(...) as f:` and (when reusing connections) `with requests.Session() as session:` for sync code, or `async with aiohttp.ClientSession() as session:` for async code. 3. **Use WAV PCM 16kHz mono** for best compatibility 4. **Enable chunked transfer** for lower latency 5. **Cache access tokens** for 9 minutes (valid for 10) diff --git a/.github/plugins/azure-sdk-python/skills/azure-storage-blob-py/SKILL.md b/.github/plugins/azure-sdk-python/skills/azure-storage-blob-py/SKILL.md index 45cb8391..31cd68bb 100644 --- a/.github/plugins/azure-sdk-python/skills/azure-storage-blob-py/SKILL.md +++ b/.github/plugins/azure-sdk-python/skills/azure-storage-blob-py/SKILL.md @@ -255,3 +255,10 @@ async def download_async(): 6. **Prefer `readinto()`** over `readall()` for memory efficiency 7. **Use `walk_blobs()`** for hierarchical listing 8. **Set appropriate content types** for web-served blobs + +## Reference Files + +| File | Contents | +|------|----------| +| [references/capabilities.md](references/capabilities.md) | Capability index mapping hero flows and non-hero references. | +| [references/non-hero-scenarios.md](references/non-hero-scenarios.md) | Dedicated non-hero examples (metadata/properties and async patterns). | diff --git a/.github/plugins/azure-sdk-python/skills/azure-storage-blob-py/references/capabilities.md b/.github/plugins/azure-sdk-python/skills/azure-storage-blob-py/references/capabilities.md new file mode 100644 index 00000000..3a153a14 --- /dev/null +++ b/.github/plugins/azure-sdk-python/skills/azure-storage-blob-py/references/capabilities.md @@ -0,0 +1,32 @@ +# azure-storage-blob-py capability coverage + +**SDK/package**: `azure-storage-blob` + +This index maps hero scenarios in `SKILL.md` and links non-hero scenarios documented in dedicated reference files. + +## Hero scenarios covered in SKILL.md + +- `Client Hierarchy` +- `Core Workflow` +- `Performance Tuning` +- `SAS Tokens (User Delegation)` + +## Non-hero scenarios + +- `Blob Properties and Metadata`: Dedicated example and implementation notes. + See: [`non-hero-scenarios.md#blob-properties-and-metadata`](non-hero-scenarios.md#blob-properties-and-metadata) +- `Async Client`: Dedicated example and implementation notes. + See: [`non-hero-scenarios.md#async-client`](non-hero-scenarios.md#async-client) + +## Related deep-dive references + +- [`non-hero-scenarios.md`](non-hero-scenarios.md): Dedicated non-hero examples and implementation notes. + +## API breadth checklist + +- Verify client/auth mode for the environment before coding. +- Confirm operation-group/method names against current Microsoft Learn API reference. +- For Python SDKs with both sync and async clients, document both forms without a blanket preference. +- Include cleanup/delete paths for created resources in examples. +- Prefer idempotent create/update operations where available. +- Validate paging/LRO/error-handling patterns for production paths. diff --git a/.github/plugins/azure-sdk-python/skills/azure-storage-blob-py/references/non-hero-scenarios.md b/.github/plugins/azure-sdk-python/skills/azure-storage-blob-py/references/non-hero-scenarios.md new file mode 100644 index 00000000..8952d21a --- /dev/null +++ b/.github/plugins/azure-sdk-python/skills/azure-storage-blob-py/references/non-hero-scenarios.md @@ -0,0 +1,46 @@ +# azure-storage-blob-py non-hero scenarios + +These scenarios are intentionally separate from hero flows in `SKILL.md`. +They cover secondary/advanced patterns typically used after the primary end-to-end path is working. + +## Blob Properties and Metadata + +```python +# Get properties +properties = blob_client.get_blob_properties() +print(f"Size: {properties.size}") +print(f"Content-Type: {properties.content_settings.content_type}") +print(f"Last modified: {properties.last_modified}") + +# Set metadata +blob_client.set_blob_metadata(metadata={"category": "logs", "year": "2024"}) + +# Set content type +from azure.storage.blob import ContentSettings +blob_client.set_http_headers( + content_settings=ContentSettings(content_type="application/json") +) +``` + +## Async Client + +```python +from azure.identity.aio import DefaultAzureCredential +from azure.storage.blob.aio import BlobServiceClient + +async def upload_async(): + async with DefaultAzureCredential() as credential: + async with BlobServiceClient(account_url, credential=credential) as client: + blob_client = client.get_blob_client("mycontainer", "sample.txt") + + with open("./file.txt", "rb") as data: + await blob_client.upload_blob(data, overwrite=True) + +# Download async +async def download_async(): + async with BlobServiceClient(account_url, credential=credential) as client: + blob_client = client.get_blob_client("mycontainer", "sample.txt") + + stream = await blob_client.download_blob() + data = await stream.readall() +``` diff --git a/.github/plugins/azure-sdk-python/skills/azure-storage-file-datalake-py/SKILL.md b/.github/plugins/azure-sdk-python/skills/azure-storage-file-datalake-py/SKILL.md index cbf9de12..bd8a9e4a 100644 --- a/.github/plugins/azure-sdk-python/skills/azure-storage-file-datalake-py/SKILL.md +++ b/.github/plugins/azure-sdk-python/skills/azure-storage-file-datalake-py/SKILL.md @@ -233,3 +233,10 @@ asyncio.run(datalake_operations()) 8. **Use `get_paths` with `recursive=True`** for full directory listing 9. **Set metadata** for custom file attributes 10. **Consider Blob API** for simple object storage use cases + +## Reference Files + +| File | Contents | +|------|----------| +| [references/capabilities.md](references/capabilities.md) | Additional non-hero capabilities, operation-group coverage, and production checklists. | +| [references/non-hero-scenarios.md](references/non-hero-scenarios.md) | Dedicated non-hero examples for secondary/advanced scenarios. | diff --git a/.github/plugins/azure-sdk-python/skills/azure-storage-file-datalake-py/references/capabilities.md b/.github/plugins/azure-sdk-python/skills/azure-storage-file-datalake-py/references/capabilities.md new file mode 100644 index 00000000..b1d10159 --- /dev/null +++ b/.github/plugins/azure-sdk-python/skills/azure-storage-file-datalake-py/references/capabilities.md @@ -0,0 +1,36 @@ +# azure-storage-file-datalake-py capability coverage + +**SDK/package**: `azure-storage-file-datalake` + +This index maps hero scenarios in `SKILL.md` and links non-hero scenarios documented in dedicated reference files. + +## Hero scenarios covered in SKILL.md + +- `Client Hierarchy` +- `File System Operations` +- `Directory Operations` +- `File Operations` + +## Non-hero scenarios + +- `List Contents`: Dedicated example and implementation notes. + See: [`non-hero-scenarios.md#list-contents`](non-hero-scenarios.md#list-contents) +- `File/Directory Properties`: Dedicated example and implementation notes. + See: [`non-hero-scenarios.md#filedirectory-properties`](non-hero-scenarios.md#filedirectory-properties) +- `Access Control (ACL)`: Dedicated example and implementation notes. + See: [`non-hero-scenarios.md#access-control-acl`](non-hero-scenarios.md#access-control-acl) +- `Async Client`: Dedicated example and implementation notes. + See: [`non-hero-scenarios.md#async-client`](non-hero-scenarios.md#async-client) + +## Related deep-dive references + +- [`non-hero-scenarios.md`](non-hero-scenarios.md): Dedicated non-hero examples and implementation notes. + +## API breadth checklist + +- Verify client/auth mode for the environment before coding. +- Confirm operation-group/method names against current Microsoft Learn API reference. +- For Python SDKs with both sync and async clients, document both forms without a blanket preference. +- Include cleanup/delete paths for created resources in examples. +- Prefer idempotent create/update operations where available. +- Validate paging/LRO/error-handling patterns for production paths. diff --git a/.github/plugins/azure-sdk-python/skills/azure-storage-file-datalake-py/references/non-hero-scenarios.md b/.github/plugins/azure-sdk-python/skills/azure-storage-file-datalake-py/references/non-hero-scenarios.md new file mode 100644 index 00000000..f23a4960 --- /dev/null +++ b/.github/plugins/azure-sdk-python/skills/azure-storage-file-datalake-py/references/non-hero-scenarios.md @@ -0,0 +1,77 @@ +# azure-storage-file-datalake-py non-hero scenarios + +These scenarios are intentionally separate from hero flows in `SKILL.md`. +They cover secondary/advanced patterns typically used after the primary end-to-end path is working. + +## List Contents + +```python +# List paths (files and directories) +for path in file_system_client.get_paths(): + print(f"{'DIR' if path.is_directory else 'FILE'}: {path.name}") + +# List paths in directory +for path in file_system_client.get_paths(path="mydir"): + print(path.name) + +# Recursive listing +for path in file_system_client.get_paths(path="mydir", recursive=True): + print(path.name) +``` + +## File/Directory Properties + +```python +# Get properties +properties = file_client.get_file_properties() +print(f"Size: {properties.size}") +print(f"Last modified: {properties.last_modified}") + +# Set metadata +file_client.set_metadata(metadata={"processed": "true"}) +``` + +## Access Control (ACL) + +```python +# Get ACL +acl = directory_client.get_access_control() +print(f"Owner: {acl['owner']}") +print(f"Permissions: {acl['permissions']}") + +# Set ACL +directory_client.set_access_control( + owner="user-id", + permissions="rwxr-x---" +) + +# Update ACL entries +from azure.storage.filedatalake import AccessControlChangeResult +directory_client.update_access_control_recursive( + acl="user:user-id:rwx" +) +``` + +## Async Client + +```python +from azure.storage.filedatalake.aio import DataLakeServiceClient +from azure.identity.aio import DefaultAzureCredential + +async def datalake_operations(): + async with DefaultAzureCredential() as credential: + async with DataLakeServiceClient( + account_url="https://.dfs.core.windows.net", + credential=credential + ) as service_client: + file_system_client = service_client.get_file_system_client("myfilesystem") + file_client = file_system_client.get_file_client("test.txt") + + await file_client.upload_data(b"async content", overwrite=True) + + download = await file_client.download_file() + content = await download.readall() + +import asyncio +asyncio.run(datalake_operations()) +``` diff --git a/.github/plugins/azure-sdk-python/skills/azure-storage-file-share-py/SKILL.md b/.github/plugins/azure-sdk-python/skills/azure-storage-file-share-py/SKILL.md index 5200889a..5adf7ad6 100644 --- a/.github/plugins/azure-sdk-python/skills/azure-storage-file-share-py/SKILL.md +++ b/.github/plugins/azure-sdk-python/skills/azure-storage-file-share-py/SKILL.md @@ -243,3 +243,10 @@ async def upload_file(): 6. **Create snapshots** before major changes 7. **Set quotas** to prevent unexpected storage costs 8. **Use ranges** for partial file updates + +## Reference Files + +| File | Contents | +|------|----------| +| [references/capabilities.md](references/capabilities.md) | Additional non-hero capabilities, operation-group coverage, and production checklists. | +| [references/non-hero-scenarios.md](references/non-hero-scenarios.md) | Dedicated non-hero examples for secondary/advanced scenarios. | diff --git a/.github/plugins/azure-sdk-python/skills/azure-storage-file-share-py/references/capabilities.md b/.github/plugins/azure-sdk-python/skills/azure-storage-file-share-py/references/capabilities.md new file mode 100644 index 00000000..6044d9b1 --- /dev/null +++ b/.github/plugins/azure-sdk-python/skills/azure-storage-file-share-py/references/capabilities.md @@ -0,0 +1,34 @@ +# azure-storage-file-share-py capability coverage + +**SDK/package**: `azure-storage-file-share` + +This index maps hero scenarios in `SKILL.md` and links non-hero scenarios documented in dedicated reference files. + +## Hero scenarios covered in SKILL.md + +- `Share Operations` +- `Directory Operations` +- `File Operations` +- `Range Operations` + +## Non-hero scenarios + +- `Snapshot Operations`: Dedicated example and implementation notes. + See: [`non-hero-scenarios.md#snapshot-operations`](non-hero-scenarios.md#snapshot-operations) +- `Async Client`: Dedicated example and implementation notes. + See: [`non-hero-scenarios.md#async-client`](non-hero-scenarios.md#async-client) +- `Client Types`: | Client | Purpose | + See: [`non-hero-scenarios.md#client-types`](non-hero-scenarios.md#client-types) + +## Related deep-dive references + +- [`non-hero-scenarios.md`](non-hero-scenarios.md): Dedicated non-hero examples and implementation notes. + +## API breadth checklist + +- Verify client/auth mode for the environment before coding. +- Confirm operation-group/method names against current Microsoft Learn API reference. +- For Python SDKs with both sync and async clients, document both forms without a blanket preference. +- Include cleanup/delete paths for created resources in examples. +- Prefer idempotent create/update operations where available. +- Validate paging/LRO/error-handling patterns for production paths. diff --git a/.github/plugins/azure-sdk-python/skills/azure-storage-file-share-py/references/non-hero-scenarios.md b/.github/plugins/azure-sdk-python/skills/azure-storage-file-share-py/references/non-hero-scenarios.md new file mode 100644 index 00000000..e43eab1f --- /dev/null +++ b/.github/plugins/azure-sdk-python/skills/azure-storage-file-share-py/references/non-hero-scenarios.md @@ -0,0 +1,46 @@ +# azure-storage-file-share-py non-hero scenarios + +These scenarios are intentionally separate from hero flows in `SKILL.md`. +They cover secondary/advanced patterns typically used after the primary end-to-end path is working. + +## Snapshot Operations + +### Create Snapshot + +```python +snapshot = share_client.create_snapshot() +print(f"Snapshot: {snapshot['snapshot']}") +``` + +### Access Snapshot + +```python +snapshot_client = service.get_share_client( + "my-share", + snapshot=snapshot["snapshot"] +) +``` + +## Async Client + +```python +from azure.storage.fileshare.aio import ShareServiceClient +from azure.identity.aio import DefaultAzureCredential + +async def upload_file(): + async with DefaultAzureCredential() as credential: + async with ShareServiceClient(account_url, credential=credential) as service: + share = service.get_share_client("my-share") + file_client = share.get_file_client("test.txt") + + await file_client.upload_file("Hello!") +``` + +## Client Types + +| Client | Purpose | +|--------|---------| +| `ShareServiceClient` | Account-level operations | +| `ShareClient` | Share operations | +| `ShareDirectoryClient` | Directory operations | +| `ShareFileClient` | File operations | diff --git a/.github/plugins/azure-sdk-python/skills/azure-storage-queue-py/SKILL.md b/.github/plugins/azure-sdk-python/skills/azure-storage-queue-py/SKILL.md index 2e953c26..f8ed9816 100644 --- a/.github/plugins/azure-sdk-python/skills/azure-storage-queue-py/SKILL.md +++ b/.github/plugins/azure-sdk-python/skills/azure-storage-queue-py/SKILL.md @@ -237,3 +237,10 @@ with QueueClient( 8. **Use `peek_messages`** for monitoring without affecting queue 9. **Set `time_to_live`** to prevent stale messages 10. **Consider Service Bus** for advanced features (sessions, topics) + +## Reference Files + +| File | Contents | +|------|----------| +| [references/capabilities.md](references/capabilities.md) | Additional non-hero capabilities, operation-group coverage, and production checklists. | +| [references/non-hero-scenarios.md](references/non-hero-scenarios.md) | Dedicated non-hero examples for secondary/advanced scenarios. | diff --git a/.github/plugins/azure-sdk-python/skills/azure-storage-queue-py/references/capabilities.md b/.github/plugins/azure-sdk-python/skills/azure-storage-queue-py/references/capabilities.md new file mode 100644 index 00000000..af6e9c29 --- /dev/null +++ b/.github/plugins/azure-sdk-python/skills/azure-storage-queue-py/references/capabilities.md @@ -0,0 +1,40 @@ +# azure-storage-queue-py capability coverage + +**SDK/package**: `azure-storage-queue` + +This index maps hero scenarios in `SKILL.md` and links non-hero scenarios documented in dedicated reference files. + +## Hero scenarios covered in SKILL.md + +- `Queue Operations` +- `Send Messages` +- `Receive Messages` +- `Peek Messages` + +## Non-hero scenarios + +- `Update Message`: Dedicated example and implementation notes. + See: [`non-hero-scenarios.md#update-message`](non-hero-scenarios.md#update-message) +- `Delete Message`: Dedicated example and implementation notes. + See: [`non-hero-scenarios.md#delete-message`](non-hero-scenarios.md#delete-message) +- `Clear Queue`: Dedicated example and implementation notes. + See: [`non-hero-scenarios.md#clear-queue`](non-hero-scenarios.md#clear-queue) +- `Queue Properties`: Dedicated example and implementation notes. + See: [`non-hero-scenarios.md#queue-properties`](non-hero-scenarios.md#queue-properties) +- `Async Client`: Dedicated example and implementation notes. + See: [`non-hero-scenarios.md#async-client`](non-hero-scenarios.md#async-client) +- `Base64 Encoding`: Dedicated example and implementation notes. + See: [`non-hero-scenarios.md#base64-encoding`](non-hero-scenarios.md#base64-encoding) + +## Related deep-dive references + +- [`non-hero-scenarios.md`](non-hero-scenarios.md): Dedicated non-hero examples and implementation notes. + +## API breadth checklist + +- Verify client/auth mode for the environment before coding. +- Confirm operation-group/method names against current Microsoft Learn API reference. +- For Python SDKs with both sync and async clients, document both forms without a blanket preference. +- Include cleanup/delete paths for created resources in examples. +- Prefer idempotent create/update operations where available. +- Validate paging/LRO/error-handling patterns for production paths. diff --git a/.github/plugins/azure-sdk-python/skills/azure-storage-queue-py/references/non-hero-scenarios.md b/.github/plugins/azure-sdk-python/skills/azure-storage-queue-py/references/non-hero-scenarios.md new file mode 100644 index 00000000..2d595015 --- /dev/null +++ b/.github/plugins/azure-sdk-python/skills/azure-storage-queue-py/references/non-hero-scenarios.md @@ -0,0 +1,101 @@ +# azure-storage-queue-py non-hero scenarios + +These scenarios are intentionally separate from hero flows in `SKILL.md`. +They cover secondary/advanced patterns typically used after the primary end-to-end path is working. + +## Update Message + +```python +# Extend visibility or update content +messages = queue_client.receive_messages() +for message in messages: + # Extend timeout (need more time) + queue_client.update_message( + message, + visibility_timeout=60 + ) + + # Update content and timeout + queue_client.update_message( + message, + content="Updated content", + visibility_timeout=60 + ) +``` + +## Delete Message + +```python +# Delete after successful processing +messages = queue_client.receive_messages() +for message in messages: + try: + # Process... + queue_client.delete_message(message) + except Exception: + # Message becomes visible again after timeout + pass +``` + +## Clear Queue + +```python +# Delete all messages +queue_client.clear_messages() +``` + +## Queue Properties + +```python +# Get queue properties +properties = queue_client.get_queue_properties() +print(f"Approximate message count: {properties.approximate_message_count}") + +# Set/get metadata +queue_client.set_queue_metadata(metadata={"environment": "production"}) +properties = queue_client.get_queue_properties() +print(properties.metadata) +``` + +## Async Client + +```python +from azure.storage.queue.aio import QueueServiceClient, QueueClient +from azure.identity.aio import DefaultAzureCredential + +async def queue_operations(): + credential = DefaultAzureCredential() + + async with QueueClient( + account_url="https://.queue.core.windows.net", + queue_name="myqueue", + credential=credential + ) as client: + # Send + await client.send_message("Async message") + + # Receive + async for message in client.receive_messages(): + print(message.content) + await client.delete_message(message) + +import asyncio +asyncio.run(queue_operations()) +``` + +## Base64 Encoding + +```python +from azure.storage.queue import QueueClient, BinaryBase64EncodePolicy, BinaryBase64DecodePolicy + +# For binary data +with QueueClient( + account_url=account_url, + queue_name="myqueue", + credential=credential, + message_encode_policy=BinaryBase64EncodePolicy(), + message_decode_policy=BinaryBase64DecodePolicy() +) as queue_client: + # Send bytes + queue_client.send_message(b"Binary content") +``` diff --git a/.github/plugins/azure-sdk-python/skills/fastapi-router-py/SKILL.md b/.github/plugins/azure-sdk-python/skills/fastapi-router-py/SKILL.md index 0d6f32e6..1e966fef 100644 --- a/.github/plugins/azure-sdk-python/skills/fastapi-router-py/SKILL.md +++ b/.github/plugins/azure-sdk-python/skills/fastapi-router-py/SKILL.md @@ -57,5 +57,11 @@ async def list_items() -> list[Item]: ## Best Practices -1. **Pick `def` or `async def` per endpoint based on whether you call async I/O;** do not mix sync and async blocking calls in one handler. +1. **Pick `def` or `async def` per endpoint based on whether you call async I/O; do not mix sync and blocking calls in one handler.** 2. **Manage long-lived resources (DB pools, HTTP clients) in `lifespan` and inject via `Depends`;** use `with`/`async with` for per-request resources. + +## Reference Files + +| File | Contents | +|------|----------| +| [references/capabilities.md](references/capabilities.md) | Additional non-hero capabilities, operation-group coverage, and production checklists. | diff --git a/.github/plugins/azure-sdk-python/skills/fastapi-router-py/references/capabilities.md b/.github/plugins/azure-sdk-python/skills/fastapi-router-py/references/capabilities.md new file mode 100644 index 00000000..ba5506a4 --- /dev/null +++ b/.github/plugins/azure-sdk-python/skills/fastapi-router-py/references/capabilities.md @@ -0,0 +1,25 @@ +# fastapi-router-py capability coverage + +**SDK/package**: `fastapi-router-py` + +This reference captures additional non-hero capabilities and API breadth so the main `SKILL.md` can stay focused on copy/paste hero flows. + +## Hero scenarios covered in SKILL.md + +- `Quick Start` +- `Authentication Patterns` +- `Response Models` +- `HTTP Status Codes` + +## Important non-hero scenarios to include when needed + +- `Integration Steps` +- `Best Practices` + +## API breadth checklist + +- Verify client/auth mode for the environment before coding. +- Confirm operation-group/method names against current Microsoft Learn API reference. +- Include cleanup/delete paths for created resources in examples. +- Prefer idempotent create/update operations where available. +- Validate paging/LRO/error-handling patterns for production paths. diff --git a/.github/plugins/azure-sdk-python/skills/m365-agents-py/SKILL.md b/.github/plugins/azure-sdk-python/skills/m365-agents-py/SKILL.md index 743e9ac1..3d583a89 100644 --- a/.github/plugins/azure-sdk-python/skills/m365-agents-py/SKILL.md +++ b/.github/plugins/azure-sdk-python/skills/m365-agents-py/SKILL.md @@ -54,6 +54,15 @@ COPILOTSTUDIOAGENT__TENANTID= COPILOTSTUDIOAGENT__AGENTAPPID= ``` +## Authentication & Lifecycle + +> **🔑 Two rules apply to every code sample below:** +> +> 1. **This SDK is async-first — use `async def` handlers and `async with` throughout.** +> 2. **Use explicit auth managers and context-managed network resources.** Use `MsalConnectionManager` for agent auth, and wrap per-request HTTP resources in `async with` (for example, `aiohttp.ClientSession`). +> +> Snippets may abbreviate this setup, but production code should always follow both rules. + ## Core Workflow: aiohttp-hosted AgentApplication ```python @@ -333,7 +342,7 @@ asyncio.run(main()) ## Best Practices -1. **This skill is async-first (aiohttp-based).** Use async handlers and `async with` for aiohttp sessions. +1. **This SDK is async-first — use `async def` handlers and `async with` throughout.** 2. **Always use context managers for clients and async credentials.** Wrap every client in `with Client(...) as client:` (sync) or `async with Client(...) as client:` (async). For async `DefaultAzureCredential` from `azure.identity.aio`, also use `async with credential:` so tokens and transports are cleaned up. 3. Use `microsoft_agents` import prefix (underscores, not dots). 4. Use `MemoryStorage` only for development; use BlobStorage or CosmosDB in production. @@ -352,3 +361,9 @@ asyncio.run(main()) | GitHub samples (Python) | https://github.com/microsoft/Agents-for-python | | PyPI packages | https://pypi.org/search/?q=microsoft-agents | | Integrate with Copilot Studio | https://learn.microsoft.com/en-us/microsoft-365/agents-sdk/integrate-with-mcs | + +## Reference Files + +| File | Contents | +|------|----------| +| [references/capabilities.md](references/capabilities.md) | Additional non-hero capabilities, operation-group coverage, and production checklists. | diff --git a/.github/plugins/azure-sdk-python/skills/m365-agents-py/references/capabilities.md b/.github/plugins/azure-sdk-python/skills/m365-agents-py/references/capabilities.md new file mode 100644 index 00000000..aedf8e7c --- /dev/null +++ b/.github/plugins/azure-sdk-python/skills/m365-agents-py/references/capabilities.md @@ -0,0 +1,42 @@ +# m365-agents-py capability coverage + +**SDK/package**: `microsoft-agents-hosting-core, microsoft-agents-hosting-aiohttp, microsoft-agents-activity, microsoft-agents-authentication-msal, microsoft-agents-copilotstudio-client` + +This reference mirrors the actual capability sections in `SKILL.md` and provides concrete non-hero examples for implementation guidance. + +## Hero scenarios covered in SKILL.md + +- `Core Workflow: aiohttp-hosted AgentApplication` +- `AgentApplication Routing` +- `Streaming Responses with Azure OpenAI` +- `OAuth / Auto Sign-In` + +## Important non-hero scenarios with examples + +### `Copilot Studio Client (Direct to Engine)` + +```python +import asyncio +from msal import PublicClientApplication +from microsoft_agents.activity import ActivityTypes, load_configuration_from_env +from microsoft_agents.copilotstudio.client import ( + ConnectionSettings, + CopilotClient, +) + +# Token cache (local file for interactive flows) +class LocalTokenCache: + # See samples for full implementation + pass + +def acquire_token(settings, app_client_id, tenant_id): +# ... see SKILL.md for the full example +``` + +## API breadth checklist + +- Verify client/auth mode for the environment before coding. +- Confirm operation-group/method names against current Microsoft Learn API reference. +- Include cleanup/delete paths for created resources in examples. +- Prefer idempotent create/update operations where available. +- Validate paging/LRO/error-handling patterns for production paths. diff --git a/.github/plugins/azure-sdk-python/skills/pydantic-models-py/SKILL.md b/.github/plugins/azure-sdk-python/skills/pydantic-models-py/SKILL.md index 56de5e40..2605b360 100644 --- a/.github/plugins/azure-sdk-python/skills/pydantic-models-py/SKILL.md +++ b/.github/plugins/azure-sdk-python/skills/pydantic-models-py/SKILL.md @@ -60,3 +60,9 @@ class MyInDB(MyResponse): 1. Create models in `src/backend/app/models/` 2. Export from `src/backend/app/models/__init__.py` 3. Add corresponding TypeScript types + +## Reference Files + +| File | Contents | +|------|----------| +| [references/capabilities.md](references/capabilities.md) | Additional non-hero capabilities, operation-group coverage, and production checklists. | diff --git a/.github/plugins/azure-sdk-python/skills/pydantic-models-py/references/capabilities.md b/.github/plugins/azure-sdk-python/skills/pydantic-models-py/references/capabilities.md new file mode 100644 index 00000000..5ed18ff5 --- /dev/null +++ b/.github/plugins/azure-sdk-python/skills/pydantic-models-py/references/capabilities.md @@ -0,0 +1,25 @@ +# pydantic-models-py capability coverage + +**SDK/package**: `pydantic-models-py` + +This reference captures additional non-hero capabilities and API breadth so the main `SKILL.md` can stay focused on copy/paste hero flows. + +## Hero scenarios covered in SKILL.md + +- `Quick Start` +- `Multi-Model Pattern` +- `camelCase Aliases` +- `Optional Update Fields` + +## Important non-hero scenarios to include when needed + +- `Database Document` +- `Integration Steps` + +## API breadth checklist + +- Verify client/auth mode for the environment before coding. +- Confirm operation-group/method names against current Microsoft Learn API reference. +- Include cleanup/delete paths for created resources in examples. +- Prefer idempotent create/update operations where available. +- Validate paging/LRO/error-handling patterns for production paths. diff --git a/.github/skills/agent-framework-azure-ai-py b/.github/skills/agent-framework-azure-ai-py new file mode 120000 index 00000000..0f574683 --- /dev/null +++ b/.github/skills/agent-framework-azure-ai-py @@ -0,0 +1 @@ +../plugins/azure-sdk-python/skills/agent-framework-azure-ai-py \ No newline at end of file diff --git a/.github/skills/azure-ai-contentsafety-py b/.github/skills/azure-ai-contentsafety-py new file mode 120000 index 00000000..08ab0c46 --- /dev/null +++ b/.github/skills/azure-ai-contentsafety-py @@ -0,0 +1 @@ +../plugins/azure-sdk-python/skills/azure-ai-contentsafety-py \ No newline at end of file diff --git a/.github/skills/azure-ai-contentunderstanding-py b/.github/skills/azure-ai-contentunderstanding-py new file mode 120000 index 00000000..8d4a2e04 --- /dev/null +++ b/.github/skills/azure-ai-contentunderstanding-py @@ -0,0 +1 @@ +../plugins/azure-sdk-python/skills/azure-ai-contentunderstanding-py \ No newline at end of file diff --git a/.github/skills/azure-ai-language-conversations-py b/.github/skills/azure-ai-language-conversations-py new file mode 120000 index 00000000..257a9470 --- /dev/null +++ b/.github/skills/azure-ai-language-conversations-py @@ -0,0 +1 @@ +../plugins/azure-sdk-python/skills/azure-ai-language-conversations-py \ No newline at end of file diff --git a/.github/skills/azure-ai-ml-py b/.github/skills/azure-ai-ml-py new file mode 120000 index 00000000..eaac1e82 --- /dev/null +++ b/.github/skills/azure-ai-ml-py @@ -0,0 +1 @@ +../plugins/azure-sdk-python/skills/azure-ai-ml-py \ No newline at end of file diff --git a/.github/skills/azure-ai-projects-py b/.github/skills/azure-ai-projects-py new file mode 120000 index 00000000..eaaf98bc --- /dev/null +++ b/.github/skills/azure-ai-projects-py @@ -0,0 +1 @@ +../plugins/azure-sdk-python/skills/azure-ai-projects-py \ No newline at end of file diff --git a/.github/skills/azure-ai-textanalytics-py b/.github/skills/azure-ai-textanalytics-py new file mode 120000 index 00000000..650baacf --- /dev/null +++ b/.github/skills/azure-ai-textanalytics-py @@ -0,0 +1 @@ +../plugins/azure-sdk-python/skills/azure-ai-textanalytics-py \ No newline at end of file diff --git a/.github/skills/azure-ai-transcription-py b/.github/skills/azure-ai-transcription-py new file mode 120000 index 00000000..f5b70e97 --- /dev/null +++ b/.github/skills/azure-ai-transcription-py @@ -0,0 +1 @@ +../plugins/azure-sdk-python/skills/azure-ai-transcription-py \ No newline at end of file diff --git a/.github/skills/azure-ai-translation-document-py b/.github/skills/azure-ai-translation-document-py new file mode 120000 index 00000000..d81c331a --- /dev/null +++ b/.github/skills/azure-ai-translation-document-py @@ -0,0 +1 @@ +../plugins/azure-sdk-python/skills/azure-ai-translation-document-py \ No newline at end of file diff --git a/.github/skills/azure-ai-translation-text-py b/.github/skills/azure-ai-translation-text-py new file mode 120000 index 00000000..a0d31c26 --- /dev/null +++ b/.github/skills/azure-ai-translation-text-py @@ -0,0 +1 @@ +../plugins/azure-sdk-python/skills/azure-ai-translation-text-py \ No newline at end of file diff --git a/.github/skills/azure-ai-vision-imageanalysis-py b/.github/skills/azure-ai-vision-imageanalysis-py new file mode 120000 index 00000000..0cf02c59 --- /dev/null +++ b/.github/skills/azure-ai-vision-imageanalysis-py @@ -0,0 +1 @@ +../plugins/azure-sdk-python/skills/azure-ai-vision-imageanalysis-py \ No newline at end of file diff --git a/.github/skills/azure-ai-voicelive-py b/.github/skills/azure-ai-voicelive-py new file mode 120000 index 00000000..ee0d9929 --- /dev/null +++ b/.github/skills/azure-ai-voicelive-py @@ -0,0 +1 @@ +../plugins/azure-sdk-python/skills/azure-ai-voicelive-py \ No newline at end of file diff --git a/.github/skills/azure-appconfiguration-py b/.github/skills/azure-appconfiguration-py new file mode 120000 index 00000000..0c8182d0 --- /dev/null +++ b/.github/skills/azure-appconfiguration-py @@ -0,0 +1 @@ +../plugins/azure-sdk-python/skills/azure-appconfiguration-py \ No newline at end of file diff --git a/.github/skills/azure-containerregistry-py b/.github/skills/azure-containerregistry-py new file mode 120000 index 00000000..ee9c2e53 --- /dev/null +++ b/.github/skills/azure-containerregistry-py @@ -0,0 +1 @@ +../plugins/azure-sdk-python/skills/azure-containerregistry-py \ No newline at end of file diff --git a/.github/skills/azure-cosmos-db-py b/.github/skills/azure-cosmos-db-py new file mode 120000 index 00000000..4b58584f --- /dev/null +++ b/.github/skills/azure-cosmos-db-py @@ -0,0 +1 @@ +../plugins/azure-sdk-python/skills/azure-cosmos-db-py \ No newline at end of file diff --git a/.github/skills/azure-cosmos-py b/.github/skills/azure-cosmos-py new file mode 120000 index 00000000..ab82f04f --- /dev/null +++ b/.github/skills/azure-cosmos-py @@ -0,0 +1 @@ +../plugins/azure-sdk-python/skills/azure-cosmos-py \ No newline at end of file diff --git a/.github/skills/azure-data-tables-py b/.github/skills/azure-data-tables-py new file mode 120000 index 00000000..a2dbba4d --- /dev/null +++ b/.github/skills/azure-data-tables-py @@ -0,0 +1 @@ +../plugins/azure-sdk-python/skills/azure-data-tables-py \ No newline at end of file diff --git a/.github/skills/azure-eventgrid-py b/.github/skills/azure-eventgrid-py new file mode 120000 index 00000000..d3caa828 --- /dev/null +++ b/.github/skills/azure-eventgrid-py @@ -0,0 +1 @@ +../plugins/azure-sdk-python/skills/azure-eventgrid-py \ No newline at end of file diff --git a/.github/skills/azure-eventhub-py b/.github/skills/azure-eventhub-py new file mode 120000 index 00000000..d2fc8221 --- /dev/null +++ b/.github/skills/azure-eventhub-py @@ -0,0 +1 @@ +../plugins/azure-sdk-python/skills/azure-eventhub-py \ No newline at end of file diff --git a/.github/skills/azure-identity-py b/.github/skills/azure-identity-py new file mode 120000 index 00000000..dfe20c2b --- /dev/null +++ b/.github/skills/azure-identity-py @@ -0,0 +1 @@ +../plugins/azure-sdk-python/skills/azure-identity-py \ No newline at end of file diff --git a/.github/skills/azure-keyvault-py b/.github/skills/azure-keyvault-py new file mode 120000 index 00000000..2335eac7 --- /dev/null +++ b/.github/skills/azure-keyvault-py @@ -0,0 +1 @@ +../plugins/azure-sdk-python/skills/azure-keyvault-py \ No newline at end of file diff --git a/.github/skills/azure-messaging-webpubsubservice-py b/.github/skills/azure-messaging-webpubsubservice-py new file mode 120000 index 00000000..41368c4a --- /dev/null +++ b/.github/skills/azure-messaging-webpubsubservice-py @@ -0,0 +1 @@ +../plugins/azure-sdk-python/skills/azure-messaging-webpubsubservice-py \ No newline at end of file diff --git a/.github/skills/azure-mgmt-apicenter-py b/.github/skills/azure-mgmt-apicenter-py new file mode 120000 index 00000000..446781ba --- /dev/null +++ b/.github/skills/azure-mgmt-apicenter-py @@ -0,0 +1 @@ +../plugins/azure-sdk-python/skills/azure-mgmt-apicenter-py \ No newline at end of file diff --git a/.github/skills/azure-mgmt-apimanagement-py b/.github/skills/azure-mgmt-apimanagement-py new file mode 120000 index 00000000..adf8958c --- /dev/null +++ b/.github/skills/azure-mgmt-apimanagement-py @@ -0,0 +1 @@ +../plugins/azure-sdk-python/skills/azure-mgmt-apimanagement-py \ No newline at end of file diff --git a/.github/skills/azure-mgmt-botservice-py b/.github/skills/azure-mgmt-botservice-py new file mode 120000 index 00000000..84a3ac19 --- /dev/null +++ b/.github/skills/azure-mgmt-botservice-py @@ -0,0 +1 @@ +../plugins/azure-sdk-python/skills/azure-mgmt-botservice-py \ No newline at end of file diff --git a/.github/skills/azure-mgmt-fabric-py b/.github/skills/azure-mgmt-fabric-py new file mode 120000 index 00000000..67651cbb --- /dev/null +++ b/.github/skills/azure-mgmt-fabric-py @@ -0,0 +1 @@ +../plugins/azure-sdk-python/skills/azure-mgmt-fabric-py \ No newline at end of file diff --git a/.github/skills/azure-monitor-ingestion-py b/.github/skills/azure-monitor-ingestion-py new file mode 120000 index 00000000..a31461c2 --- /dev/null +++ b/.github/skills/azure-monitor-ingestion-py @@ -0,0 +1 @@ +../plugins/azure-sdk-python/skills/azure-monitor-ingestion-py \ No newline at end of file diff --git a/.github/skills/azure-monitor-opentelemetry-exporter-py b/.github/skills/azure-monitor-opentelemetry-exporter-py new file mode 120000 index 00000000..23b34751 --- /dev/null +++ b/.github/skills/azure-monitor-opentelemetry-exporter-py @@ -0,0 +1 @@ +../plugins/azure-sdk-python/skills/azure-monitor-opentelemetry-exporter-py \ No newline at end of file diff --git a/.github/skills/azure-monitor-opentelemetry-py b/.github/skills/azure-monitor-opentelemetry-py new file mode 120000 index 00000000..bcee5c56 --- /dev/null +++ b/.github/skills/azure-monitor-opentelemetry-py @@ -0,0 +1 @@ +../plugins/azure-sdk-python/skills/azure-monitor-opentelemetry-py \ No newline at end of file diff --git a/.github/skills/azure-monitor-query-py b/.github/skills/azure-monitor-query-py new file mode 120000 index 00000000..0f8f3bd6 --- /dev/null +++ b/.github/skills/azure-monitor-query-py @@ -0,0 +1 @@ +../plugins/azure-sdk-python/skills/azure-monitor-query-py \ No newline at end of file diff --git a/.github/skills/azure-search-documents-py b/.github/skills/azure-search-documents-py new file mode 120000 index 00000000..13a4ec86 --- /dev/null +++ b/.github/skills/azure-search-documents-py @@ -0,0 +1 @@ +../plugins/azure-sdk-python/skills/azure-search-documents-py \ No newline at end of file diff --git a/.github/skills/azure-servicebus-py b/.github/skills/azure-servicebus-py new file mode 120000 index 00000000..5275c159 --- /dev/null +++ b/.github/skills/azure-servicebus-py @@ -0,0 +1 @@ +../plugins/azure-sdk-python/skills/azure-servicebus-py \ No newline at end of file diff --git a/.github/skills/azure-speech-to-text-rest-py b/.github/skills/azure-speech-to-text-rest-py new file mode 120000 index 00000000..c9bc2f35 --- /dev/null +++ b/.github/skills/azure-speech-to-text-rest-py @@ -0,0 +1 @@ +../plugins/azure-sdk-python/skills/azure-speech-to-text-rest-py \ No newline at end of file diff --git a/.github/skills/azure-storage-blob-py b/.github/skills/azure-storage-blob-py new file mode 120000 index 00000000..6941148a --- /dev/null +++ b/.github/skills/azure-storage-blob-py @@ -0,0 +1 @@ +../plugins/azure-sdk-python/skills/azure-storage-blob-py \ No newline at end of file diff --git a/.github/skills/azure-storage-file-datalake-py b/.github/skills/azure-storage-file-datalake-py new file mode 120000 index 00000000..a4f13f7b --- /dev/null +++ b/.github/skills/azure-storage-file-datalake-py @@ -0,0 +1 @@ +../plugins/azure-sdk-python/skills/azure-storage-file-datalake-py \ No newline at end of file diff --git a/.github/skills/azure-storage-file-share-py b/.github/skills/azure-storage-file-share-py new file mode 120000 index 00000000..5e1e9b27 --- /dev/null +++ b/.github/skills/azure-storage-file-share-py @@ -0,0 +1 @@ +../plugins/azure-sdk-python/skills/azure-storage-file-share-py \ No newline at end of file diff --git a/.github/skills/azure-storage-queue-py b/.github/skills/azure-storage-queue-py new file mode 120000 index 00000000..3260a7ed --- /dev/null +++ b/.github/skills/azure-storage-queue-py @@ -0,0 +1 @@ +../plugins/azure-sdk-python/skills/azure-storage-queue-py \ No newline at end of file diff --git a/.github/skills/fastapi-router-py b/.github/skills/fastapi-router-py new file mode 120000 index 00000000..d190edc7 --- /dev/null +++ b/.github/skills/fastapi-router-py @@ -0,0 +1 @@ +../plugins/azure-sdk-python/skills/fastapi-router-py \ No newline at end of file diff --git a/.github/skills/m365-agents-py b/.github/skills/m365-agents-py new file mode 120000 index 00000000..a4dddc0e --- /dev/null +++ b/.github/skills/m365-agents-py @@ -0,0 +1 @@ +../plugins/azure-sdk-python/skills/m365-agents-py \ No newline at end of file diff --git a/.github/skills/pydantic-models-py b/.github/skills/pydantic-models-py new file mode 120000 index 00000000..5f5f6459 --- /dev/null +++ b/.github/skills/pydantic-models-py @@ -0,0 +1 @@ +../plugins/azure-sdk-python/skills/pydantic-models-py \ No newline at end of file From f5038695ad7d54a4cb84fdb8ebeb69647a597707 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Wed, 15 Jul 2026 18:02:34 +0000 Subject: [PATCH 02/26] Fix create_analyzer to begin_create_analyzer LRO in contentunderstanding non-hero-scenarios --- .../references/non-hero-scenarios.md | 65 ++++++++++--------- 1 file changed, 36 insertions(+), 29 deletions(-) diff --git a/.github/plugins/azure-sdk-python/skills/azure-ai-contentunderstanding-py/references/non-hero-scenarios.md b/.github/plugins/azure-sdk-python/skills/azure-ai-contentunderstanding-py/references/non-hero-scenarios.md index f5a6a4fb..90100e6d 100644 --- a/.github/plugins/azure-sdk-python/skills/azure-ai-contentunderstanding-py/references/non-hero-scenarios.md +++ b/.github/plugins/azure-sdk-python/skills/azure-ai-contentunderstanding-py/references/non-hero-scenarios.md @@ -64,44 +64,51 @@ for phrase in content.transcript_phrases: Create custom analyzers with field schemas for specialized extraction: ```python -# Create custom analyzer -analyzer = client.create_analyzer( +from azure.ai.contentunderstanding.models import ( + AnalysisInput, + ContentAnalyzer, + ContentFieldDefinition, + ContentFieldSchema, +) + +# Create custom analyzer - returns an LRO poller; wait for provisioning to complete +poller = client.begin_create_analyzer( analyzer_id="my-invoice-analyzer", - analyzer={ - "description": "Custom invoice analyzer", - "base_analyzer_id": "prebuilt-documentSearch", - "field_schema": { - "fields": { - "vendor_name": {"type": "string"}, - "invoice_total": {"type": "number"}, - "line_items": { - "type": "array", - "items": { - "type": "object", - "properties": { - "description": {"type": "string"}, - "amount": {"type": "number"} - } - } - } + resource=ContentAnalyzer( + description="Custom invoice analyzer", + base_analyzer_id="prebuilt-documentSearch", + field_schema=ContentFieldSchema( + fields={ + "vendor_name": ContentFieldDefinition(type="string"), + "invoice_total": ContentFieldDefinition(type="number"), + "line_items": ContentFieldDefinition( + type="array", + item_definition=ContentFieldDefinition( + type="object", + properties={ + "description": ContentFieldDefinition(type="string"), + "amount": ContentFieldDefinition(type="number"), + }, + ), + ), } - } - } + ), + ), ) +poller.result() # wait until analyzer is ready # Use custom analyzer -from azure.ai.contentunderstanding.models import AnalyzeInput - -poller = client.begin_analyze( +analyze_poller = client.begin_analyze( analyzer_id="my-invoice-analyzer", - inputs=[AnalyzeInput(url="https://example.com/invoice.pdf")] + inputs=[AnalysisInput(url="https://example.com/invoice.pdf")] ) -result = poller.result() +result = analyze_poller.result() -# Access extracted fields -print(result.fields["vendor_name"]) -print(result.fields["invoice_total"]) +# Access extracted fields from analyzed content +content = result.contents[0] +print(content.fields["vendor_name"].value_string) +print(content.fields["invoice_total"].value_number) ``` ## Analyzer Management From c70b46202b9a2c3235bdac3dfe563eabd261edb0 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Wed, 15 Jul 2026 18:05:08 +0000 Subject: [PATCH 03/26] Fix get_supported_languages to use TextTranslationClient in translation-document non-hero-scenarios --- .../references/non-hero-scenarios.md | 16 ++++++++++++---- 1 file changed, 12 insertions(+), 4 deletions(-) diff --git a/.github/plugins/azure-sdk-python/skills/azure-ai-translation-document-py/references/non-hero-scenarios.md b/.github/plugins/azure-sdk-python/skills/azure-ai-translation-document-py/references/non-hero-scenarios.md index cf9cb490..2472c88c 100644 --- a/.github/plugins/azure-sdk-python/skills/azure-ai-translation-document-py/references/non-hero-scenarios.md +++ b/.github/plugins/azure-sdk-python/skills/azure-ai-translation-document-py/references/non-hero-scenarios.md @@ -65,12 +65,20 @@ for fmt in formats: ## Supported Languages +`DocumentTranslationClient` does not expose a language discovery method. Use `TextTranslationClient` +from `azure-ai-translation-text` instead — its `get_supported_languages()` call requires no +authentication: + ```python -# Get supported languages -languages = client.get_supported_languages() +from azure.ai.translation.text import TextTranslationClient + +# Languages endpoint requires no credential; omit auth for this lookup +text_client = TextTranslationClient() +result = text_client.get_supported_languages() -for lang in languages: - print(f"Language: {lang.name} ({lang.code})") +# result.translation is a dict: BCP 47 code -> TranslationLanguage +for code, lang in result.translation.items(): + print(f"Language: {lang.name} ({code})") ``` ## Async Client From 6b02b9e0375d5cd6e16e427a0c1cad9f6a85c824 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Wed, 15 Jul 2026 18:05:37 +0000 Subject: [PATCH 04/26] Clarify TextTranslationClient default endpoint in supported languages example --- .../references/non-hero-scenarios.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/.github/plugins/azure-sdk-python/skills/azure-ai-translation-document-py/references/non-hero-scenarios.md b/.github/plugins/azure-sdk-python/skills/azure-ai-translation-document-py/references/non-hero-scenarios.md index 2472c88c..15eb6947 100644 --- a/.github/plugins/azure-sdk-python/skills/azure-ai-translation-document-py/references/non-hero-scenarios.md +++ b/.github/plugins/azure-sdk-python/skills/azure-ai-translation-document-py/references/non-hero-scenarios.md @@ -72,8 +72,8 @@ authentication: ```python from azure.ai.translation.text import TextTranslationClient -# Languages endpoint requires no credential; omit auth for this lookup -text_client = TextTranslationClient() +# Languages endpoint requires no credential; default endpoint is https://api.cognitive.microsofttranslator.com +text_client = TextTranslationClient() # no credential needed for this call result = text_client.get_supported_languages() # result.translation is a dict: BCP 47 code -> TranslationLanguage From be5ac848987499499c1edd43a43ede9e0d75aec1 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Wed, 15 Jul 2026 18:07:53 +0000 Subject: [PATCH 05/26] Fix instrumentation_options API and supported libraries in azure-monitor-opentelemetry-py non-hero-scenarios --- .../references/non-hero-scenarios.md | 18 +++++++++++------- 1 file changed, 11 insertions(+), 7 deletions(-) diff --git a/.github/plugins/azure-sdk-python/skills/azure-monitor-opentelemetry-py/references/non-hero-scenarios.md b/.github/plugins/azure-sdk-python/skills/azure-monitor-opentelemetry-py/references/non-hero-scenarios.md index 384bb1c2..2742f456 100644 --- a/.github/plugins/azure-sdk-python/skills/azure-monitor-opentelemetry-py/references/non-hero-scenarios.md +++ b/.github/plugins/azure-sdk-python/skills/azure-monitor-opentelemetry-py/references/non-hero-scenarios.md @@ -73,11 +73,18 @@ configure_azure_monitor( ## Disable Specific Instrumentations +Use `instrumentation_options` to selectively enable or disable individual libraries. Libraries not +listed remain enabled by default: + ```python from azure.monitor.opentelemetry import configure_azure_monitor +# Disable Django and psycopg2; leave flask, requests, urllib, urllib3 etc. enabled configure_azure_monitor( - instrumentations=["flask", "requests"] # Only enable these + instrumentation_options={ + "django": {"enabled": False}, + "psycopg2": {"enabled": False}, + } ) ``` @@ -116,13 +123,10 @@ configure_azure_monitor( | Django | Traces | | FastAPI | Traces | | Requests | Traces | +| urllib | Traces | | urllib3 | Traces | -| httpx | Traces | -| aiohttp | Traces | | psycopg2 | Traces | -| pymysql | Traces | -| pymongo | Traces | -| redis | Traces | +| Azure SDK | Traces | ## Configuration Options @@ -132,5 +136,5 @@ configure_azure_monitor( | `credential` | Azure credential for AAD auth | None | | `sampling_ratio` | Sampling rate (0.0 to 1.0) | 1.0 | | `resource` | OpenTelemetry Resource | Auto-detected | -| `instrumentations` | List of instrumentations to enable | All | +| `instrumentation_options` | Dict controlling per-library `enabled` flags | All enabled | | `enable_live_metrics` | Enable Live Metrics stream | False | From bccd23e2fda5b9cc827b66d62a1e0dd10f2c8894 Mon Sep 17 00:00:00 2001 From: Larry Osterman Date: Wed, 15 Jul 2026 12:02:11 -0700 Subject: [PATCH 06/26] Apply suggestions from code review Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> --- .../references/non-hero-scenarios.md | 4 +-- .../references/non-hero-scenarios.md | 11 ++++---- .../references/non-hero-scenarios.md | 27 +++++++++---------- .../skills/fastapi-router-py/SKILL.md | 2 +- .../references/capabilities.md | 2 +- 5 files changed, 23 insertions(+), 23 deletions(-) diff --git a/.github/plugins/azure-sdk-python/skills/azure-monitor-opentelemetry-py/references/non-hero-scenarios.md b/.github/plugins/azure-sdk-python/skills/azure-monitor-opentelemetry-py/references/non-hero-scenarios.md index 2742f456..bffdd918 100644 --- a/.github/plugins/azure-sdk-python/skills/azure-monitor-opentelemetry-py/references/non-hero-scenarios.md +++ b/.github/plugins/azure-sdk-python/skills/azure-monitor-opentelemetry-py/references/non-hero-scenarios.md @@ -104,8 +104,8 @@ configure_azure_monitor( from azure.monitor.opentelemetry import configure_azure_monitor from azure.identity import DefaultAzureCredential, ManagedIdentityCredential -# Local dev: DefaultAzureCredential. Production: set AZURE_TOKEN_CREDENTIALS=prod or AZURE_TOKEN_CREDENTIALS= -credential = DefaultAzureCredential(require_envvar=True) +# Local dev: DefaultAzureCredential. In production, set AZURE_TOKEN_CREDENTIALS=prod or use a specific credential. +credential = DefaultAzureCredential() # Or use a specific credential directly in production: # See https://learn.microsoft.com/python/api/overview/azure/identity-readme?view=azure-python#credential-classes # credential = ManagedIdentityCredential() diff --git a/.github/plugins/azure-sdk-python/skills/azure-storage-blob-py/references/non-hero-scenarios.md b/.github/plugins/azure-sdk-python/skills/azure-storage-blob-py/references/non-hero-scenarios.md index 8952d21a..95d21b1b 100644 --- a/.github/plugins/azure-sdk-python/skills/azure-storage-blob-py/references/non-hero-scenarios.md +++ b/.github/plugins/azure-sdk-python/skills/azure-storage-blob-py/references/non-hero-scenarios.md @@ -38,9 +38,10 @@ async def upload_async(): # Download async async def download_async(): - async with BlobServiceClient(account_url, credential=credential) as client: - blob_client = client.get_blob_client("mycontainer", "sample.txt") - - stream = await blob_client.download_blob() - data = await stream.readall() + async with DefaultAzureCredential() as credential: + async with BlobServiceClient(account_url, credential=credential) as client: + blob_client = client.get_blob_client("mycontainer", "sample.txt") + + stream = await blob_client.download_blob() + data = await stream.readall() ``` diff --git a/.github/plugins/azure-sdk-python/skills/azure-storage-queue-py/references/non-hero-scenarios.md b/.github/plugins/azure-sdk-python/skills/azure-storage-queue-py/references/non-hero-scenarios.md index 2d595015..aafaf0a7 100644 --- a/.github/plugins/azure-sdk-python/skills/azure-storage-queue-py/references/non-hero-scenarios.md +++ b/.github/plugins/azure-sdk-python/skills/azure-storage-queue-py/references/non-hero-scenarios.md @@ -64,20 +64,19 @@ from azure.storage.queue.aio import QueueServiceClient, QueueClient from azure.identity.aio import DefaultAzureCredential async def queue_operations(): - credential = DefaultAzureCredential() - - async with QueueClient( - account_url="https://.queue.core.windows.net", - queue_name="myqueue", - credential=credential - ) as client: - # Send - await client.send_message("Async message") - - # Receive - async for message in client.receive_messages(): - print(message.content) - await client.delete_message(message) + async with DefaultAzureCredential() as credential: + async with QueueClient( + account_url="https://.queue.core.windows.net", + queue_name="myqueue", + credential=credential + ) as client: + # Send + await client.send_message("Async message") + + # Receive + async for message in client.receive_messages(): + print(message.content) + await client.delete_message(message) import asyncio asyncio.run(queue_operations()) diff --git a/.github/plugins/azure-sdk-python/skills/fastapi-router-py/SKILL.md b/.github/plugins/azure-sdk-python/skills/fastapi-router-py/SKILL.md index 1e966fef..426c9f53 100644 --- a/.github/plugins/azure-sdk-python/skills/fastapi-router-py/SKILL.md +++ b/.github/plugins/azure-sdk-python/skills/fastapi-router-py/SKILL.md @@ -57,7 +57,7 @@ async def list_items() -> list[Item]: ## Best Practices -1. **Pick `def` or `async def` per endpoint based on whether you call async I/O; do not mix sync and blocking calls in one handler.** +1. **Pick `def` or `async def` per endpoint based on whether you call async I/O; do not call blocking I/O from an `async def` handler.** 2. **Manage long-lived resources (DB pools, HTTP clients) in `lifespan` and inject via `Depends`;** use `with`/`async with` for per-request resources. ## Reference Files diff --git a/.github/plugins/azure-sdk-python/skills/fastapi-router-py/references/capabilities.md b/.github/plugins/azure-sdk-python/skills/fastapi-router-py/references/capabilities.md index ba5506a4..6a8a2f60 100644 --- a/.github/plugins/azure-sdk-python/skills/fastapi-router-py/references/capabilities.md +++ b/.github/plugins/azure-sdk-python/skills/fastapi-router-py/references/capabilities.md @@ -1,6 +1,6 @@ # fastapi-router-py capability coverage -**SDK/package**: `fastapi-router-py` +**SDK/package**: `fastapi` This reference captures additional non-hero capabilities and API breadth so the main `SKILL.md` can stay focused on copy/paste hero flows. From bc0ee8218d2b8a976d1088449a75f26f04d3985a Mon Sep 17 00:00:00 2001 From: Larry Osterman Date: Wed, 15 Jul 2026 12:03:32 -0700 Subject: [PATCH 07/26] Apply suggestions from code review Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> --- .../references/non-hero-scenarios.md | 12 ++++++------ .../references/non-hero-scenarios.md | 12 ++++++------ 2 files changed, 12 insertions(+), 12 deletions(-) diff --git a/.github/plugins/azure-sdk-python/skills/azure-ai-contentunderstanding-py/references/non-hero-scenarios.md b/.github/plugins/azure-sdk-python/skills/azure-ai-contentunderstanding-py/references/non-hero-scenarios.md index 90100e6d..1a713870 100644 --- a/.github/plugins/azure-sdk-python/skills/azure-ai-contentunderstanding-py/references/non-hero-scenarios.md +++ b/.github/plugins/azure-sdk-python/skills/azure-ai-contentunderstanding-py/references/non-hero-scenarios.md @@ -6,11 +6,11 @@ They cover secondary/advanced patterns typically used after the primary end-to-e ## Analyze Image ```python -from azure.ai.contentunderstanding.models import AnalyzeInput +from azure.ai.contentunderstanding.models import AnalysisInput poller = client.begin_analyze( analyzer_id="prebuilt-imageSearch", - inputs=[AnalyzeInput(url="https://example.com/image.jpg")] + inputs=[AnalysisInput(url="https://example.com/image.jpg")] ) result = poller.result() content = result.contents[0] @@ -160,15 +160,15 @@ asyncio.run(analyze_document()) | `DocumentContent` | PDF, images, Office docs | Pages, tables, figures, paragraphs | | `AudioVisualContent` | Audio, video files | Transcript phrases, timing, key frames | -Both derive from `MediaContent` which provides basic info and markdown representation. +Both derive from `AnalysisContent`, which provides basic information and a markdown representation. ## Model Imports ```python from azure.ai.contentunderstanding.models import ( - AnalyzeInput, - AnalyzeResult, - MediaContentKind, + AnalysisInput, + AnalysisResult, + AnalysisContent, DocumentContent, AudioVisualContent, ) diff --git a/.github/plugins/azure-sdk-python/skills/azure-ai-translation-text-py/references/non-hero-scenarios.md b/.github/plugins/azure-sdk-python/skills/azure-ai-translation-text-py/references/non-hero-scenarios.md index c2b870e2..d58575ca 100644 --- a/.github/plugins/azure-sdk-python/skills/azure-ai-translation-text-py/references/non-hero-scenarios.md +++ b/.github/plugins/azure-sdk-python/skills/azure-ai-translation-text-py/references/non-hero-scenarios.md @@ -27,8 +27,8 @@ Find alternate translations and definitions: ```python result = client.lookup_dictionary_entries( body=["fly"], - from_parameter="en", - to="es" + from_language="en", + to_language="es" ) for item in result: @@ -48,8 +48,8 @@ from azure.ai.translation.text.models import DictionaryExampleTextItem result = client.lookup_dictionary_examples( body=[DictionaryExampleTextItem(text="fly", translation="volar")], - from_parameter="en", - to="es" + from_language="en", + to_language="es" ) for item in result: @@ -101,7 +101,7 @@ for item in result: ```python result = client.translate( body=["Hello, world!"], - to=["de"], + to_language=["de"], text_type="html", # "plain" or "html" profanity_action="Marked", # "NoAction", "Deleted", "Marked" profanity_marker="Asterisk", # "Asterisk", "Tag" @@ -132,7 +132,7 @@ async def translate_text(): ) as client: result = await client.translate( body=["Hello, world!"], - to=["es"] + to_language=["es"] ) print(result[0].translations[0].text) ``` From 506437c000bb5a5db348ef7a5cef60e5e99fea9a Mon Sep 17 00:00:00 2001 From: Larry Osterman Date: Wed, 15 Jul 2026 12:05:00 -0700 Subject: [PATCH 08/26] Apply suggestions from code review Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> --- .../references/non-hero-scenarios.md | 26 ++++++++------- .../references/non-hero-scenarios.md | 33 +++++++++---------- .../references/non-hero-scenarios.md | 2 +- .../references/non-hero-scenarios.md | 2 +- .../references/non-hero-scenarios.md | 2 +- .../references/non-hero-scenarios.md | 19 ++++++----- .../references/non-hero-scenarios.md | 4 +-- .../references/capabilities.md | 2 +- 8 files changed, 46 insertions(+), 44 deletions(-) diff --git a/.github/plugins/azure-sdk-python/skills/azure-containerregistry-py/references/non-hero-scenarios.md b/.github/plugins/azure-sdk-python/skills/azure-containerregistry-py/references/non-hero-scenarios.md index daa07c57..033e8b9f 100644 --- a/.github/plugins/azure-sdk-python/skills/azure-containerregistry-py/references/non-hero-scenarios.md +++ b/.github/plugins/azure-sdk-python/skills/azure-containerregistry-py/references/non-hero-scenarios.md @@ -23,18 +23,20 @@ client.delete_tag("my-image", "old-tag") ```python from azure.containerregistry import ContainerRegistryClient - -with ContainerRegistryClient(endpoint, DefaultAzureCredential()) as client: - # Download manifest - manifest = client.download_manifest("my-image", "latest") - print(f"Media type: {manifest.media_type}") - print(f"Digest: {manifest.digest}") - - # Download blob - blob = client.download_blob("my-image", "sha256:abc123...") - with open("layer.tar.gz", "wb") as f: - for chunk in blob: - f.write(chunk) +from azure.identity import DefaultAzureCredential + +with DefaultAzureCredential() as credential: + with ContainerRegistryClient(endpoint, credential) as client: + # Download manifest + manifest = client.download_manifest("my-image", "latest") + print(f"Media type: {manifest.media_type}") + print(f"Digest: {manifest.digest}") + + # Download blob + blob = client.download_blob("my-image", "sha256:abc123...") + with open("layer.tar.gz", "wb") as f: + for chunk in blob: + f.write(chunk) ``` ## Async Client diff --git a/.github/plugins/azure-sdk-python/skills/azure-eventgrid-py/references/non-hero-scenarios.md b/.github/plugins/azure-sdk-python/skills/azure-eventgrid-py/references/non-hero-scenarios.md index a74c845f..cfa51c6c 100644 --- a/.github/plugins/azure-sdk-python/skills/azure-eventgrid-py/references/non-hero-scenarios.md +++ b/.github/plugins/azure-sdk-python/skills/azure-eventgrid-py/references/non-hero-scenarios.md @@ -6,19 +6,19 @@ They cover secondary/advanced patterns typically used after the primary end-to-e ## Async Client ```python +from azure.core.messaging import CloudEvent from azure.eventgrid.aio import EventGridPublisherClient from azure.identity.aio import DefaultAzureCredential async def publish_events(): - credential = DefaultAzureCredential() - - async with EventGridPublisherClient(endpoint, credential) as client: - event = CloudEvent( - type="MyApp.Events.Test", - source="/myapp", - data={"message": "hello"} - ) - await client.send(event) + async with DefaultAzureCredential() as credential: + async with EventGridPublisherClient(endpoint, credential) as client: + event = CloudEvent( + type="MyApp.Events.Test", + source="/myapp", + data={"message": "hello"} + ) + await client.send(event) import asyncio asyncio.run(publish_events()) @@ -36,12 +36,11 @@ from azure.identity import DefaultAzureCredential namespace_endpoint = "https://..eventgrid.azure.net" topic_name = "my-topic" -with EventGridPublisherClient( - endpoint=namespace_endpoint, - credential=DefaultAzureCredential() -) as client: - client.send( - event, - namespace_topic=topic_name - ) +with DefaultAzureCredential() as credential: + with EventGridPublisherClient( + endpoint=namespace_endpoint, + credential=credential, + namespace_topic=topic_name, + ) as client: + client.send(event) ``` diff --git a/.github/plugins/azure-sdk-python/skills/azure-mgmt-apicenter-py/references/non-hero-scenarios.md b/.github/plugins/azure-sdk-python/skills/azure-mgmt-apicenter-py/references/non-hero-scenarios.md index 1fb05fd8..b78ca5be 100644 --- a/.github/plugins/azure-sdk-python/skills/azure-mgmt-apicenter-py/references/non-hero-scenarios.md +++ b/.github/plugins/azure-sdk-python/skills/azure-mgmt-apicenter-py/references/non-hero-scenarios.md @@ -54,7 +54,7 @@ apis = client.apis.list( ) for api in apis: - print(f"{api.name}: {api.title} ({api.kind})") + print(f"{api.name}: {api.properties.title} ({api.properties.kind})" ``` ## Create Environment diff --git a/.github/plugins/azure-sdk-python/skills/azure-mgmt-apimanagement-py/references/non-hero-scenarios.md b/.github/plugins/azure-sdk-python/skills/azure-mgmt-apimanagement-py/references/non-hero-scenarios.md index fa31a077..8af06bc3 100644 --- a/.github/plugins/azure-sdk-python/skills/azure-mgmt-apimanagement-py/references/non-hero-scenarios.md +++ b/.github/plugins/azure-sdk-python/skills/azure-mgmt-apimanagement-py/references/non-hero-scenarios.md @@ -51,7 +51,7 @@ subscription = client.subscription.create_or_update( ) ) -print(f"Subscription key: {subscription.primary_key}") +print("Subscription created") ``` ## Set API Policy diff --git a/.github/plugins/azure-sdk-python/skills/azure-mgmt-botservice-py/references/non-hero-scenarios.md b/.github/plugins/azure-sdk-python/skills/azure-mgmt-botservice-py/references/non-hero-scenarios.md index 024f6a72..7cbeb404 100644 --- a/.github/plugins/azure-sdk-python/skills/azure-mgmt-botservice-py/references/non-hero-scenarios.md +++ b/.github/plugins/azure-sdk-python/skills/azure-mgmt-botservice-py/references/non-hero-scenarios.md @@ -136,7 +136,7 @@ keys = client.channels.list_with_keys( if hasattr(keys.properties, 'properties'): for site in keys.properties.properties.sites: print(f"Site: {site.site_name}") - print(f"Key: {site.key}") + # Use site.key without logging or persisting it. ``` ## Bot Connections (OAuth) diff --git a/.github/plugins/azure-sdk-python/skills/azure-monitor-ingestion-py/references/non-hero-scenarios.md b/.github/plugins/azure-sdk-python/skills/azure-monitor-ingestion-py/references/non-hero-scenarios.md index 620e311e..a0e11ba3 100644 --- a/.github/plugins/azure-sdk-python/skills/azure-monitor-ingestion-py/references/non-hero-scenarios.md +++ b/.github/plugins/azure-sdk-python/skills/azure-monitor-ingestion-py/references/non-hero-scenarios.md @@ -11,15 +11,16 @@ from azure.monitor.ingestion.aio import LogsIngestionClient from azure.identity.aio import DefaultAzureCredential async def upload_logs(): - async with LogsIngestionClient( - endpoint=endpoint, - credential=DefaultAzureCredential() - ) as client: - await client.upload( - rule_id=rule_id, - stream_name=stream_name, - logs=logs - ) + async with DefaultAzureCredential() as credential: + async with LogsIngestionClient( + endpoint=endpoint, + credential=credential + ) as client: + await client.upload( + rule_id=rule_id, + stream_name=stream_name, + logs=logs + ) asyncio.run(upload_logs()) ``` diff --git a/.github/plugins/azure-sdk-python/skills/azure-monitor-opentelemetry-exporter-py/references/non-hero-scenarios.md b/.github/plugins/azure-sdk-python/skills/azure-monitor-opentelemetry-exporter-py/references/non-hero-scenarios.md index 566af556..2e29697a 100644 --- a/.github/plugins/azure-sdk-python/skills/azure-monitor-opentelemetry-exporter-py/references/non-hero-scenarios.md +++ b/.github/plugins/azure-sdk-python/skills/azure-monitor-opentelemetry-exporter-py/references/non-hero-scenarios.md @@ -9,8 +9,8 @@ They cover secondary/advanced patterns typically used after the primary end-to-e from azure.identity import DefaultAzureCredential, ManagedIdentityCredential from azure.monitor.opentelemetry.exporter import AzureMonitorTraceExporter -# Local dev: DefaultAzureCredential. Production: set AZURE_TOKEN_CREDENTIALS=prod or AZURE_TOKEN_CREDENTIALS= -credential = DefaultAzureCredential(require_envvar=True) +# Local dev: DefaultAzureCredential. In production, set AZURE_TOKEN_CREDENTIALS=prod or use a specific credential. +credential = DefaultAzureCredential() # Or use a specific credential directly in production: # See https://learn.microsoft.com/python/api/overview/azure/identity-readme?view=azure-python#credential-classes # credential = ManagedIdentityCredential() diff --git a/.github/plugins/azure-sdk-python/skills/pydantic-models-py/references/capabilities.md b/.github/plugins/azure-sdk-python/skills/pydantic-models-py/references/capabilities.md index 5ed18ff5..0fb5e410 100644 --- a/.github/plugins/azure-sdk-python/skills/pydantic-models-py/references/capabilities.md +++ b/.github/plugins/azure-sdk-python/skills/pydantic-models-py/references/capabilities.md @@ -1,6 +1,6 @@ # pydantic-models-py capability coverage -**SDK/package**: `pydantic-models-py` +**SDK/package**: `pydantic` This reference captures additional non-hero capabilities and API breadth so the main `SKILL.md` can stay focused on copy/paste hero flows. From 480222d109051fe79e33df778da6b25b7981a4f2 Mon Sep 17 00:00:00 2001 From: Larry Osterman Date: Wed, 15 Jul 2026 12:11:43 -0700 Subject: [PATCH 09/26] Potential fix for pull request finding Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> --- .../references/non-hero-scenarios.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/.github/plugins/azure-sdk-python/skills/azure-mgmt-apimanagement-py/references/non-hero-scenarios.md b/.github/plugins/azure-sdk-python/skills/azure-mgmt-apimanagement-py/references/non-hero-scenarios.md index 8af06bc3..cc26dd53 100644 --- a/.github/plugins/azure-sdk-python/skills/azure-mgmt-apimanagement-py/references/non-hero-scenarios.md +++ b/.github/plugins/azure-sdk-python/skills/azure-mgmt-apimanagement-py/references/non-hero-scenarios.md @@ -90,6 +90,7 @@ client.api_policy.create_or_update( ## Create Named Value (Secret) ```python +import os from azure.mgmt.apimanagement.models import NamedValueCreateContract named_value = client.named_value.begin_create_or_update( @@ -98,7 +99,7 @@ named_value = client.named_value.begin_create_or_update( named_value_id="backend-api-key", parameters=NamedValueCreateContract( display_name="Backend API Key", - value="secret-key-value", + value=os.environ["BACKEND_API_KEY"], secret=True ) ).result() From dab5d2b209a7f0d58e9b20ecdd483e5b2dc86575 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Wed, 15 Jul 2026 19:12:34 +0000 Subject: [PATCH 10/26] Apply remaining changes --- tests/pnpm-workspace.yaml | 2 ++ 1 file changed, 2 insertions(+) create mode 100644 tests/pnpm-workspace.yaml diff --git a/tests/pnpm-workspace.yaml b/tests/pnpm-workspace.yaml new file mode 100644 index 00000000..00f6fc47 --- /dev/null +++ b/tests/pnpm-workspace.yaml @@ -0,0 +1,2 @@ +allowBuilds: + esbuild: set this to true or false From c3a1e630b4a5debd2cc9dbd2e4cd91776a7ac469 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Wed, 15 Jul 2026 19:13:11 +0000 Subject: [PATCH 11/26] Fix invalid token acquisition example in m365 capabilities reference --- .../m365-agents-py/references/capabilities.md | 15 ++++++++++++++- 1 file changed, 14 insertions(+), 1 deletion(-) diff --git a/.github/plugins/azure-sdk-python/skills/m365-agents-py/references/capabilities.md b/.github/plugins/azure-sdk-python/skills/m365-agents-py/references/capabilities.md index aedf8e7c..508bccf8 100644 --- a/.github/plugins/azure-sdk-python/skills/m365-agents-py/references/capabilities.md +++ b/.github/plugins/azure-sdk-python/skills/m365-agents-py/references/capabilities.md @@ -30,7 +30,20 @@ class LocalTokenCache: pass def acquire_token(settings, app_client_id, tenant_id): -# ... see SKILL.md for the full example + pca = PublicClientApplication( + client_id=app_client_id, + authority=f"https://login.microsoftonline.com/{tenant_id}", + ) + + token_request = {"scopes": ["https://api.powerplatform.com/.default"]} + accounts = pca.get_accounts() + + if accounts: + response = pca.acquire_token_silent(token_request["scopes"], account=accounts[0]) + return response.get("access_token") + else: + response = pca.acquire_token_interactive(**token_request) + return response.get("access_token") ``` ## API breadth checklist From 0e12867e7e13fa330efea6a1564b928c77dd7e01 Mon Sep 17 00:00:00 2001 From: Larry Osterman Date: Wed, 15 Jul 2026 12:19:25 -0700 Subject: [PATCH 12/26] Potential fix for pull request finding Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> --- .../references/non-hero-scenarios.md | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/.github/plugins/azure-sdk-python/skills/azure-appconfiguration-py/references/non-hero-scenarios.md b/.github/plugins/azure-sdk-python/skills/azure-appconfiguration-py/references/non-hero-scenarios.md index fe023531..fe197704 100644 --- a/.github/plugins/azure-sdk-python/skills/azure-appconfiguration-py/references/non-hero-scenarios.md +++ b/.github/plugins/azure-sdk-python/skills/azure-appconfiguration-py/references/non-hero-scenarios.md @@ -8,12 +8,11 @@ They cover secondary/advanced patterns typically used after the primary end-to-e ### Create Snapshot ```python -from azure.appconfiguration import ConfigurationSnapshot, ConfigurationSettingFilter +from azure.appconfiguration import ConfigurationSnapshot, ConfigurationSettingsFilter snapshot = ConfigurationSnapshot( - name="v1-snapshot", filters=[ - ConfigurationSettingFilter(key="app:*", label="production") + ConfigurationSettingsFilter(key="app:*", label="production") ] ) From 187771d885f44d60b9330f9bdfc6bf00521e199b Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Wed, 15 Jul 2026 19:19:57 +0000 Subject: [PATCH 13/26] Replace placeholder non-hero scenario files with actionable content Add retry, timeout, pagination, cleanup, and async examples for: - azure-ai-transcription-py - azure-messaging-webpubsubservice-py - azure-ai-language-conversations-py --- .../references/non-hero-scenarios.md | 162 +++++++++++++++++- .../references/non-hero-scenarios.md | 104 ++++++++++- .../references/non-hero-scenarios.md | 112 +++++++++++- 3 files changed, 375 insertions(+), 3 deletions(-) diff --git a/.github/plugins/azure-sdk-python/skills/azure-ai-language-conversations-py/references/non-hero-scenarios.md b/.github/plugins/azure-sdk-python/skills/azure-ai-language-conversations-py/references/non-hero-scenarios.md index d7383045..a7adef26 100644 --- a/.github/plugins/azure-sdk-python/skills/azure-ai-language-conversations-py/references/non-hero-scenarios.md +++ b/.github/plugins/azure-sdk-python/skills/azure-ai-language-conversations-py/references/non-hero-scenarios.md @@ -5,4 +5,164 @@ They cover secondary/advanced patterns typically used after the primary end-to-e ## Operational hardening -Use this section for retries, timeouts, pagination, and cleanup patterns specific to this SDK. +### Retry Policy + +Configure retries for transient service errors: + +```python +import os +from azure.identity import DefaultAzureCredential +from azure.ai.language.conversations import ConversationAnalysisClient +from azure.core.pipeline.policies import RetryPolicy + +retry_policy = RetryPolicy(retry_total=3, retry_backoff_factor=2) +credential = DefaultAzureCredential() + +with ConversationAnalysisClient( + os.environ["AZURE_CONVERSATIONS_ENDPOINT"], + credential, + retry_policy=retry_policy, +) as client: + result = client.analyze_conversation( + task={ + "kind": "Conversation", + "analysisInput": { + "conversationItem": { + "participantId": "1", + "id": "1", + "modality": "text", + "language": "en", + "text": "Set an alarm for 7am tomorrow", + }, + "isLoggingEnabled": False, + }, + "parameters": { + "projectName": os.environ["AZURE_CONVERSATIONS_PROJECT"], + "deploymentName": os.environ["AZURE_CONVERSATIONS_DEPLOYMENT"], + }, + } + ) +``` + +### Entity Extraction and Confidence Filtering + +Access predicted entities and skip low-confidence results: + +```python +import os +from azure.identity import DefaultAzureCredential +from azure.ai.language.conversations import ConversationAnalysisClient + +MIN_CONFIDENCE = 0.7 + +credential = DefaultAzureCredential() + +with ConversationAnalysisClient( + os.environ["AZURE_CONVERSATIONS_ENDPOINT"], credential +) as client: + result = client.analyze_conversation( + task={ + "kind": "Conversation", + "analysisInput": { + "conversationItem": { + "participantId": "1", + "id": "1", + "modality": "text", + "language": "en", + "text": "Book a flight to London next Monday", + }, + "isLoggingEnabled": False, + }, + "parameters": { + "projectName": os.environ["AZURE_CONVERSATIONS_PROJECT"], + "deploymentName": os.environ["AZURE_CONVERSATIONS_DEPLOYMENT"], + "verbose": True, + }, + } + ) + + prediction = result["result"]["prediction"] + top_intent = prediction["topIntent"] + confidence = next( + i["confidenceScore"] + for i in prediction["intents"] + if i["category"] == top_intent + ) + + if confidence < MIN_CONFIDENCE: + print(f"Low confidence ({confidence:.2f}) — ask for clarification") + else: + print(f"Intent: {top_intent} ({confidence:.2f})") + for entity in prediction.get("entities", []): + print(f" Entity: {entity['category']} = {entity['text']}") +``` + +### Orchestration Workflow Routing + +When the CLU project is an orchestration project, route to the target skill: + +```python +result = client.analyze_conversation( + task={ + "kind": "Conversation", + "analysisInput": { + "conversationItem": { + "participantId": "1", + "id": "1", + "modality": "text", + "language": "en", + "text": "What's the weather like today?", + }, + "isLoggingEnabled": False, + }, + "parameters": { + "projectName": os.environ["AZURE_ORCHESTRATION_PROJECT"], + "deploymentName": os.environ["AZURE_ORCHESTRATION_DEPLOYMENT"], + }, + } +) + +prediction = result["result"]["prediction"] +top_intent = prediction["topIntent"] + +# Orchestration projects expose the target intent result under the intent name +intent_result = prediction["intents"].get(top_intent, {}) +target_kind = intent_result.get("targetProjectKind") # e.g. "Luis" or "Conversation" +print(f"Routed to: {top_intent} ({target_kind})") +``` + +### Async Client + +Use the async client for concurrent request handling: + +```python +import os +from azure.identity.aio import DefaultAzureCredential +from azure.ai.language.conversations.aio import ConversationAnalysisClient + +async def analyze_async(text: str) -> dict: + async with DefaultAzureCredential() as credential: + async with ConversationAnalysisClient( + os.environ["AZURE_CONVERSATIONS_ENDPOINT"], credential + ) as client: + result = await client.analyze_conversation( + task={ + "kind": "Conversation", + "analysisInput": { + "conversationItem": { + "participantId": "1", + "id": "1", + "modality": "text", + "language": "en", + "text": text, + }, + "isLoggingEnabled": False, + }, + "parameters": { + "projectName": os.environ["AZURE_CONVERSATIONS_PROJECT"], + "deploymentName": os.environ["AZURE_CONVERSATIONS_DEPLOYMENT"], + }, + } + ) + return result["result"]["prediction"] +``` diff --git a/.github/plugins/azure-sdk-python/skills/azure-ai-transcription-py/references/non-hero-scenarios.md b/.github/plugins/azure-sdk-python/skills/azure-ai-transcription-py/references/non-hero-scenarios.md index a1532705..c59ac4c9 100644 --- a/.github/plugins/azure-sdk-python/skills/azure-ai-transcription-py/references/non-hero-scenarios.md +++ b/.github/plugins/azure-sdk-python/skills/azure-ai-transcription-py/references/non-hero-scenarios.md @@ -5,4 +5,106 @@ They cover secondary/advanced patterns typically used after the primary end-to-e ## Operational hardening -Use this section for retries, timeouts, pagination, and cleanup patterns specific to this SDK. +### Retry Policy + +Configure retries for transient failures via `azure-core` retry policy: + +```python +import os +from azure.ai.transcription import TranscriptionClient +from azure.core.pipeline.policies import RetryPolicy + +retry_policy = RetryPolicy(retry_total=3, retry_backoff_factor=2) + +with TranscriptionClient( + endpoint=os.environ["TRANSCRIPTION_ENDPOINT"], + credential=os.environ["TRANSCRIPTION_KEY"], + retry_policy=retry_policy, +) as client: + job = client.begin_transcription( + name="meeting-transcription", + locale="en-US", + content_urls=["https:///audio.wav"], + ) + result = job.result() +``` + +### LRO Poll with Timeout + +Avoid blocking indefinitely on long-running batch jobs: + +```python +import os +from azure.ai.transcription import TranscriptionClient + +with TranscriptionClient( + endpoint=os.environ["TRANSCRIPTION_ENDPOINT"], + credential=os.environ["TRANSCRIPTION_KEY"], +) as client: + job = client.begin_transcription( + name="long-audio", + locale="en-US", + content_urls=["https:///long-audio.wav"], + ) + # Raise azure.core.exceptions.OperationTimeoutError if not done within 300 s + result = job.result(timeout=300) + print(result.status) +``` + +### List and Paginate Transcriptions + +`list_transcriptions()` returns a lazy iterator; paginate explicitly to avoid loading everything at once: + +```python +import os +from azure.ai.transcription import TranscriptionClient + +with TranscriptionClient( + endpoint=os.environ["TRANSCRIPTION_ENDPOINT"], + credential=os.environ["TRANSCRIPTION_KEY"], +) as client: + page = 0 + for transcription in client.list_transcriptions(): + print(f"[{page}] {transcription.name}: {transcription.status}") + page += 1 +``` + +### Delete Completed Transcriptions + +Remove completed jobs to keep the account tidy: + +```python +import os +from azure.ai.transcription import TranscriptionClient + +with TranscriptionClient( + endpoint=os.environ["TRANSCRIPTION_ENDPOINT"], + credential=os.environ["TRANSCRIPTION_KEY"], +) as client: + for transcription in client.list_transcriptions(): + if transcription.status == "Succeeded": + client.delete_transcription(transcription.transcription_id) +``` + +### Async Batch Transcription + +Use the async client for non-blocking workflows: + +```python +import os +from azure.ai.transcription.aio import TranscriptionClient + +async def run_async_transcription(): + async with TranscriptionClient( + endpoint=os.environ["TRANSCRIPTION_ENDPOINT"], + credential=os.environ["TRANSCRIPTION_KEY"], + ) as client: + job = await client.begin_transcription( + name="async-meeting", + locale="en-US", + content_urls=["https:///audio.wav"], + diarization_enabled=True, + ) + result = await job.result() + print(result.status) +``` diff --git a/.github/plugins/azure-sdk-python/skills/azure-messaging-webpubsubservice-py/references/non-hero-scenarios.md b/.github/plugins/azure-sdk-python/skills/azure-messaging-webpubsubservice-py/references/non-hero-scenarios.md index 56754214..dd20ffaa 100644 --- a/.github/plugins/azure-sdk-python/skills/azure-messaging-webpubsubservice-py/references/non-hero-scenarios.md +++ b/.github/plugins/azure-sdk-python/skills/azure-messaging-webpubsubservice-py/references/non-hero-scenarios.md @@ -5,4 +5,114 @@ They cover secondary/advanced patterns typically used after the primary end-to-e ## Operational hardening -Use this section for retries, timeouts, pagination, and cleanup patterns specific to this SDK. +### Retry Policy + +Configure retries for transient failures via `azure-core` retry policy: + +```python +import os +from azure.messaging.webpubsubservice import WebPubSubServiceClient +from azure.identity import DefaultAzureCredential +from azure.core.pipeline.policies import RetryPolicy + +retry_policy = RetryPolicy(retry_total=3, retry_backoff_factor=2) +credential = DefaultAzureCredential() + +with WebPubSubServiceClient( + endpoint=os.environ["WEBPUBSUB_ENDPOINT"], + hub=os.environ["AZURE_WEBPUBSUB_HUB"], + credential=credential, + retry_policy=retry_policy, +) as client: + client.send_to_all("Hello!", content_type="text/plain") +``` + +### Broadcast with Connection Exclusion + +Send to all connections except the sender: + +```python +# Exclude the sender's connection ID from the broadcast +client.send_to_all( + message={"type": "chat", "text": "Hello everyone!"}, + content_type="application/json", + excluded_connections=["sender-connection-id"], +) +``` + +### Connection Lifecycle Check + +Verify connection and user state before sending: + +```python +connection_id = "abc123" +user_id = "user123" + +if client.connection_exists(connection_id=connection_id): + client.send_to_connection( + connection_id=connection_id, + message="You have a message!", + content_type="text/plain", + ) + +if client.user_exists(user_id=user_id): + client.send_to_user( + user_id=user_id, + message="Personal message", + content_type="text/plain", + ) +else: + print(f"User {user_id} has no active connections") +``` + +### Group Cleanup + +Remove all connections from a group before deleting it: + +```python +# Remove a user from all groups, then close their connections +client.remove_user_from_all_groups(user_id="user123") +client.close_all_connections(user_id="user123", reason="Session ended") +``` + +### Short-lived Access Tokens + +Issue tokens with a limited TTL to reduce credential exposure: + +```python +from datetime import timedelta + +# 30-minute token with limited roles +token = client.get_client_access_token( + user_id="user123", + roles=["webpubsub.sendToGroup.my-group"], + minutes_to_expire=30, + groups=["my-group"], +) +print(f"Connect URL: {token['url']}") +``` + +### Async Client + +Use the async client for high-concurrency workloads: + +```python +import os +from azure.messaging.webpubsubservice.aio import WebPubSubServiceClient +from azure.identity.aio import DefaultAzureCredential + +async def broadcast_notifications(user_ids: list[str], message: str): + async with DefaultAzureCredential() as credential: + async with WebPubSubServiceClient( + endpoint=os.environ["WEBPUBSUB_ENDPOINT"], + hub=os.environ["AZURE_WEBPUBSUB_HUB"], + credential=credential, + ) as client: + for user_id in user_ids: + if await client.user_exists(user_id=user_id): + await client.send_to_user( + user_id=user_id, + message=message, + content_type="text/plain", + ) +``` From c17bc5cef53d90f59c0c581bef73674029d0dbfe Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Wed, 15 Jul 2026 19:21:06 +0000 Subject: [PATCH 14/26] Fix variable naming and list iteration in new non-hero scenarios --- .../references/non-hero-scenarios.md | 4 +++- .../references/non-hero-scenarios.md | 6 ++---- 2 files changed, 5 insertions(+), 5 deletions(-) diff --git a/.github/plugins/azure-sdk-python/skills/azure-ai-language-conversations-py/references/non-hero-scenarios.md b/.github/plugins/azure-sdk-python/skills/azure-ai-language-conversations-py/references/non-hero-scenarios.md index a7adef26..27762cf9 100644 --- a/.github/plugins/azure-sdk-python/skills/azure-ai-language-conversations-py/references/non-hero-scenarios.md +++ b/.github/plugins/azure-sdk-python/skills/azure-ai-language-conversations-py/references/non-hero-scenarios.md @@ -126,7 +126,9 @@ prediction = result["result"]["prediction"] top_intent = prediction["topIntent"] # Orchestration projects expose the target intent result under the intent name -intent_result = prediction["intents"].get(top_intent, {}) +intent_result = next( + (i for i in prediction["intents"] if i["category"] == top_intent), {} +) target_kind = intent_result.get("targetProjectKind") # e.g. "Luis" or "Conversation" print(f"Routed to: {top_intent} ({target_kind})") ``` diff --git a/.github/plugins/azure-sdk-python/skills/azure-ai-transcription-py/references/non-hero-scenarios.md b/.github/plugins/azure-sdk-python/skills/azure-ai-transcription-py/references/non-hero-scenarios.md index c59ac4c9..a574699b 100644 --- a/.github/plugins/azure-sdk-python/skills/azure-ai-transcription-py/references/non-hero-scenarios.md +++ b/.github/plugins/azure-sdk-python/skills/azure-ai-transcription-py/references/non-hero-scenarios.md @@ -63,10 +63,8 @@ with TranscriptionClient( endpoint=os.environ["TRANSCRIPTION_ENDPOINT"], credential=os.environ["TRANSCRIPTION_KEY"], ) as client: - page = 0 - for transcription in client.list_transcriptions(): - print(f"[{page}] {transcription.name}: {transcription.status}") - page += 1 + for index, transcription in enumerate(client.list_transcriptions()): + print(f"[{index}] {transcription.name}: {transcription.status}") ``` ### Delete Completed Transcriptions From d49e62c004e7561482ee3dc1faf0172e52e6a18a Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Wed, 15 Jul 2026 19:21:40 +0000 Subject: [PATCH 15/26] Replace Azure SDK boilerplate checklist with Pydantic-specific checks in capabilities.md --- .../pydantic-models-py/references/capabilities.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/.github/plugins/azure-sdk-python/skills/pydantic-models-py/references/capabilities.md b/.github/plugins/azure-sdk-python/skills/pydantic-models-py/references/capabilities.md index 0fb5e410..e9707367 100644 --- a/.github/plugins/azure-sdk-python/skills/pydantic-models-py/references/capabilities.md +++ b/.github/plugins/azure-sdk-python/skills/pydantic-models-py/references/capabilities.md @@ -18,8 +18,8 @@ This reference captures additional non-hero capabilities and API breadth so the ## API breadth checklist -- Verify client/auth mode for the environment before coding. -- Confirm operation-group/method names against current Microsoft Learn API reference. -- Include cleanup/delete paths for created resources in examples. -- Prefer idempotent create/update operations where available. -- Validate paging/LRO/error-handling patterns for production paths. +- Verify field validators (`@field_validator`) and model validators (`@model_validator`) cover all required constraints. +- Confirm serialization behavior: use `model_dump(mode="json")` for JSON-safe output and `model_dump(exclude_unset=True)` for partial updates. +- Include schema generation examples (`model_json_schema()`) when the model drives API contracts or documentation. +- Prefer `model_validate` over direct construction to ensure validators and coercion run. +- Validate migration paths from Pydantic v1 (`@validator`, `orm_mode`) to v2 (`@field_validator`, `model_config`) for any code that may need to upgrade. From 90f544122517f4ca45b6333c0365fd7f46bb9ab2 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Wed, 15 Jul 2026 19:22:23 +0000 Subject: [PATCH 16/26] Refine Pydantic checklist: focus v2 patterns item on new code --- .../skills/pydantic-models-py/references/capabilities.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/plugins/azure-sdk-python/skills/pydantic-models-py/references/capabilities.md b/.github/plugins/azure-sdk-python/skills/pydantic-models-py/references/capabilities.md index e9707367..b3228e34 100644 --- a/.github/plugins/azure-sdk-python/skills/pydantic-models-py/references/capabilities.md +++ b/.github/plugins/azure-sdk-python/skills/pydantic-models-py/references/capabilities.md @@ -22,4 +22,4 @@ This reference captures additional non-hero capabilities and API breadth so the - Confirm serialization behavior: use `model_dump(mode="json")` for JSON-safe output and `model_dump(exclude_unset=True)` for partial updates. - Include schema generation examples (`model_json_schema()`) when the model drives API contracts or documentation. - Prefer `model_validate` over direct construction to ensure validators and coercion run. -- Validate migration paths from Pydantic v1 (`@validator`, `orm_mode`) to v2 (`@field_validator`, `model_config`) for any code that may need to upgrade. +- Ensure new code uses Pydantic v2 patterns (`@field_validator`, `model_config`) rather than deprecated v1 patterns (`@validator`, `orm_mode`). From fada13f93489df986a9d5f7ff9021abae6d4eb98 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Wed, 15 Jul 2026 19:22:26 +0000 Subject: [PATCH 17/26] Fix fastapi-router-py capabilities checklist: replace Azure SDK boilerplate with FastAPI-specific checks --- .../fastapi-router-py/references/capabilities.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/.github/plugins/azure-sdk-python/skills/fastapi-router-py/references/capabilities.md b/.github/plugins/azure-sdk-python/skills/fastapi-router-py/references/capabilities.md index 6a8a2f60..d440f94f 100644 --- a/.github/plugins/azure-sdk-python/skills/fastapi-router-py/references/capabilities.md +++ b/.github/plugins/azure-sdk-python/skills/fastapi-router-py/references/capabilities.md @@ -18,8 +18,8 @@ This reference captures additional non-hero capabilities and API breadth so the ## API breadth checklist -- Verify client/auth mode for the environment before coding. -- Confirm operation-group/method names against current Microsoft Learn API reference. -- Include cleanup/delete paths for created resources in examples. -- Prefer idempotent create/update operations where available. -- Validate paging/LRO/error-handling patterns for production paths. +- Verify dependency lifetimes (`Depends` with `yield`) for resources like DB connections and HTTP clients. +- Confirm request/response validation uses Pydantic models with appropriate field constraints. +- Include proper error responses with `HTTPException` and correct status codes. +- Avoid blocking I/O in `async def` endpoints; use `run_in_executor` or a thread-pool for sync calls. +- Validate middleware, background tasks, and lifespan event patterns for production paths. From 512a0e991ba3c36ba25fbfdf87fe6e563f39ce61 Mon Sep 17 00:00:00 2001 From: Larry Osterman Date: Wed, 15 Jul 2026 12:24:05 -0700 Subject: [PATCH 18/26] Potential fix for pull request finding Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> --- .../references/non-hero-scenarios.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/plugins/azure-sdk-python/skills/azure-monitor-opentelemetry-exporter-py/references/non-hero-scenarios.md b/.github/plugins/azure-sdk-python/skills/azure-monitor-opentelemetry-exporter-py/references/non-hero-scenarios.md index 2e29697a..af09ed2a 100644 --- a/.github/plugins/azure-sdk-python/skills/azure-monitor-opentelemetry-exporter-py/references/non-hero-scenarios.md +++ b/.github/plugins/azure-sdk-python/skills/azure-monitor-opentelemetry-exporter-py/references/non-hero-scenarios.md @@ -25,8 +25,8 @@ exporter = AzureMonitorTraceExporter( Use `ApplicationInsightsSampler` for consistent sampling: ```python +from opentelemetry import trace from opentelemetry.sdk.trace import TracerProvider -from opentelemetry.sdk.trace.sampling import ParentBasedTraceIdRatio from azure.monitor.opentelemetry.exporter import ApplicationInsightsSampler # Sample 10% of traces From 209e7773803b25da656fe4fff42de859bad2e3da Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Wed, 15 Jul 2026 19:30:02 +0000 Subject: [PATCH 19/26] Fix remaining open review comments: eventgrid event var, transcription/speech auth, fabric RpSku, keyvault/botservice credential exposure --- .../skills/azure-ai-transcription-py/SKILL.md | 4 ++-- .../references/non-hero-scenarios.md | 6 ++++++ .../references/non-hero-scenarios.md | 2 +- .../references/non-hero-scenarios.md | 3 ++- .../references/non-hero-scenarios.md | 12 +++++------- .../skills/azure-speech-to-text-rest-py/SKILL.md | 2 +- 6 files changed, 17 insertions(+), 12 deletions(-) diff --git a/.github/plugins/azure-sdk-python/skills/azure-ai-transcription-py/SKILL.md b/.github/plugins/azure-sdk-python/skills/azure-ai-transcription-py/SKILL.md index 6f43ff43..6ea94b7c 100644 --- a/.github/plugins/azure-sdk-python/skills/azure-ai-transcription-py/SKILL.md +++ b/.github/plugins/azure-sdk-python/skills/azure-ai-transcription-py/SKILL.md @@ -24,14 +24,14 @@ pip install azure-ai-transcription ```bash TRANSCRIPTION_ENDPOINT=https://.cognitiveservices.azure.com -TRANSCRIPTION_KEY= # Required for all auth paths (this SDK currently uses key auth) +TRANSCRIPTION_KEY= # For key auth; omit when using DefaultAzureCredential/TokenCredential ``` ## Authentication & Lifecycle > **🔑 Two rules apply to every code sample below:** > -> 1. **This SDK currently requires API-key authentication.** `DefaultAzureCredential`/Entra ID isn't available for this client yet, so use `TRANSCRIPTION_KEY` from environment variables (never hardcoded in code). +> 1. **Two auth modes are supported:** `AzureKeyCredential(os.environ["TRANSCRIPTION_KEY"])` for key-based auth, or `DefaultAzureCredential()` / any `TokenCredential` for Entra ID. Prefer `DefaultAzureCredential` in production; never hardcode credentials in code. > 2. **Wrap every client in a context manager** so HTTP transports and sockets are released deterministically: > - Sync: `with (...) as client:` > - Async: `async with (...) as client:` diff --git a/.github/plugins/azure-sdk-python/skills/azure-eventgrid-py/references/non-hero-scenarios.md b/.github/plugins/azure-sdk-python/skills/azure-eventgrid-py/references/non-hero-scenarios.md index cfa51c6c..72576325 100644 --- a/.github/plugins/azure-sdk-python/skills/azure-eventgrid-py/references/non-hero-scenarios.md +++ b/.github/plugins/azure-sdk-python/skills/azure-eventgrid-py/references/non-hero-scenarios.md @@ -29,6 +29,7 @@ asyncio.run(publish_events()) For Event Grid Namespaces (pull delivery): ```python +from azure.core.messaging import CloudEvent from azure.eventgrid import EventGridPublisherClient from azure.identity import DefaultAzureCredential @@ -42,5 +43,10 @@ with DefaultAzureCredential() as credential: credential=credential, namespace_topic=topic_name, ) as client: + event = CloudEvent( + type="MyApp.Events.Test", + source="/myapp", + data={"message": "hello from namespace"} + ) client.send(event) ``` diff --git a/.github/plugins/azure-sdk-python/skills/azure-keyvault-py/references/non-hero-scenarios.md b/.github/plugins/azure-sdk-python/skills/azure-keyvault-py/references/non-hero-scenarios.md index 2f1bd32f..ccc2649a 100644 --- a/.github/plugins/azure-sdk-python/skills/azure-keyvault-py/references/non-hero-scenarios.md +++ b/.github/plugins/azure-sdk-python/skills/azure-keyvault-py/references/non-hero-scenarios.md @@ -13,7 +13,7 @@ async def get_secret(): async with DefaultAzureCredential() as credential: async with SecretClient(vault_url=vault_url, credential=credential) as client: secret = await client.get_secret("my-secret") - print(secret.value) + print(f"Retrieved secret: {secret.name} (version: {secret.properties.version})") import asyncio asyncio.run(get_secret()) diff --git a/.github/plugins/azure-sdk-python/skills/azure-mgmt-botservice-py/references/non-hero-scenarios.md b/.github/plugins/azure-sdk-python/skills/azure-mgmt-botservice-py/references/non-hero-scenarios.md index 7cbeb404..279f4841 100644 --- a/.github/plugins/azure-sdk-python/skills/azure-mgmt-botservice-py/references/non-hero-scenarios.md +++ b/.github/plugins/azure-sdk-python/skills/azure-mgmt-botservice-py/references/non-hero-scenarios.md @@ -144,6 +144,7 @@ if hasattr(keys.properties, 'properties'): ### Create Connection Setting ```python +import os from azure.mgmt.botservice.models import ( ConnectionSetting, ConnectionSettingProperties @@ -157,7 +158,7 @@ connection = client.bot_connection.create( location="global", properties=ConnectionSettingProperties( client_id="", - client_secret="", + client_secret=os.environ["OAUTH_CLIENT_SECRET"], scopes="User.Read", service_provider_id="" ) diff --git a/.github/plugins/azure-sdk-python/skills/azure-mgmt-fabric-py/references/non-hero-scenarios.md b/.github/plugins/azure-sdk-python/skills/azure-mgmt-fabric-py/references/non-hero-scenarios.md index cffbf63d..7d95638b 100644 --- a/.github/plugins/azure-sdk-python/skills/azure-mgmt-fabric-py/references/non-hero-scenarios.md +++ b/.github/plugins/azure-sdk-python/skills/azure-mgmt-fabric-py/references/non-hero-scenarios.md @@ -6,13 +6,13 @@ They cover secondary/advanced patterns typically used after the primary end-to-e ## Update Capacity ```python -from azure.mgmt.fabric.models import FabricCapacityUpdate, CapacitySku +from azure.mgmt.fabric.models import FabricCapacityUpdate, RpSku updated = client.fabric_capacities.begin_update( resource_group_name=resource_group, capacity_name=capacity_name, properties=FabricCapacityUpdate( - sku=CapacitySku( + sku=RpSku( name="F4", # Scale up tier="Fabric" ), @@ -82,13 +82,11 @@ else: ## List Available SKUs ```python -skus = client.fabric_capacities.list_skus( - resource_group_name=resource_group, - capacity_name=capacity_name -) +skus = client.fabric_capacities.list_skus() for sku in skus: - print(f"SKU: {sku.name} - Tier: {sku.tier}") + locations = ", ".join(sku.locations) if sku.locations else "N/A" + print(f"SKU: {sku.name} - Locations: {locations}") ``` ## Client Operations diff --git a/.github/plugins/azure-sdk-python/skills/azure-speech-to-text-rest-py/SKILL.md b/.github/plugins/azure-sdk-python/skills/azure-speech-to-text-rest-py/SKILL.md index 9fa73c65..d53b3cab 100644 --- a/.github/plugins/azure-sdk-python/skills/azure-speech-to-text-rest-py/SKILL.md +++ b/.github/plugins/azure-sdk-python/skills/azure-speech-to-text-rest-py/SKILL.md @@ -41,7 +41,7 @@ pip install requests > **🔑 Two rules apply to every code sample below:** > -> 1. **This API currently requires key-based authentication.** `DefaultAzureCredential` / Entra ID auth isn't available for this REST path yet, so use `AZURE_SPEECH_KEY` and `AZURE_SPEECH_REGION` from environment variables (never hardcoded in source). +> 1. **Two auth modes are supported.** Use a subscription key (`Ocp-Apim-Subscription-Key` header) for quick access, or a Microsoft Entra bearer token (including one acquired with `DefaultAzureCredential`) in an `Authorization: ****** header. Never hardcode credentials in source. > 2. **Use context managers for files and HTTP resources** so file handles and network connections are released deterministically: > - Sync: `with open(...) as f:` and (when reusing connections) `with requests.Session() as session:` > - Async: `async with aiohttp.ClientSession() as session:` From bfdb6926072ec7c27a13f8eee3f84658d658bbb0 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Wed, 15 Jul 2026 19:31:19 +0000 Subject: [PATCH 20/26] Fix Authorization header wording in speech-to-text-rest SKILL.md --- .../skills/azure-speech-to-text-rest-py/SKILL.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/plugins/azure-sdk-python/skills/azure-speech-to-text-rest-py/SKILL.md b/.github/plugins/azure-sdk-python/skills/azure-speech-to-text-rest-py/SKILL.md index d53b3cab..da5ca03f 100644 --- a/.github/plugins/azure-sdk-python/skills/azure-speech-to-text-rest-py/SKILL.md +++ b/.github/plugins/azure-sdk-python/skills/azure-speech-to-text-rest-py/SKILL.md @@ -41,7 +41,7 @@ pip install requests > **🔑 Two rules apply to every code sample below:** > -> 1. **Two auth modes are supported.** Use a subscription key (`Ocp-Apim-Subscription-Key` header) for quick access, or a Microsoft Entra bearer token (including one acquired with `DefaultAzureCredential`) in an `Authorization: ****** header. Never hardcode credentials in source. +> 1. **Two auth modes are supported.** Use a subscription key (`Ocp-Apim-Subscription-Key` header) for quick access, or a Microsoft Entra bearer token (including one acquired with `DefaultAzureCredential`) via the `Authorization` request header. Never hardcode credentials in source. > 2. **Use context managers for files and HTTP resources** so file handles and network connections are released deterministically: > - Sync: `with open(...) as f:` and (when reusing connections) `with requests.Session() as session:` > - Async: `async with aiohttp.ClientSession() as session:` From de92acccb8558ed60dad7d7f103ac235c632f3f1 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Wed, 15 Jul 2026 19:32:33 +0000 Subject: [PATCH 21/26] Polish wording per code review: fabric None guard, transcription key comment, speech-to-text auth reference --- .../azure-sdk-python/skills/azure-ai-transcription-py/SKILL.md | 2 +- .../azure-mgmt-fabric-py/references/non-hero-scenarios.md | 2 +- .../skills/azure-speech-to-text-rest-py/SKILL.md | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/.github/plugins/azure-sdk-python/skills/azure-ai-transcription-py/SKILL.md b/.github/plugins/azure-sdk-python/skills/azure-ai-transcription-py/SKILL.md index 6ea94b7c..3f997727 100644 --- a/.github/plugins/azure-sdk-python/skills/azure-ai-transcription-py/SKILL.md +++ b/.github/plugins/azure-sdk-python/skills/azure-ai-transcription-py/SKILL.md @@ -24,7 +24,7 @@ pip install azure-ai-transcription ```bash TRANSCRIPTION_ENDPOINT=https://.cognitiveservices.azure.com -TRANSCRIPTION_KEY= # For key auth; omit when using DefaultAzureCredential/TokenCredential +TRANSCRIPTION_KEY= # For key auth; not needed when using DefaultAzureCredential/TokenCredential ``` ## Authentication & Lifecycle diff --git a/.github/plugins/azure-sdk-python/skills/azure-mgmt-fabric-py/references/non-hero-scenarios.md b/.github/plugins/azure-sdk-python/skills/azure-mgmt-fabric-py/references/non-hero-scenarios.md index 7d95638b..7847e587 100644 --- a/.github/plugins/azure-sdk-python/skills/azure-mgmt-fabric-py/references/non-hero-scenarios.md +++ b/.github/plugins/azure-sdk-python/skills/azure-mgmt-fabric-py/references/non-hero-scenarios.md @@ -85,7 +85,7 @@ else: skus = client.fabric_capacities.list_skus() for sku in skus: - locations = ", ".join(sku.locations) if sku.locations else "N/A" + locations = ", ".join(sku.locations) if sku.locations is not None else "N/A" print(f"SKU: {sku.name} - Locations: {locations}") ``` diff --git a/.github/plugins/azure-sdk-python/skills/azure-speech-to-text-rest-py/SKILL.md b/.github/plugins/azure-sdk-python/skills/azure-speech-to-text-rest-py/SKILL.md index da5ca03f..48ec00fd 100644 --- a/.github/plugins/azure-sdk-python/skills/azure-speech-to-text-rest-py/SKILL.md +++ b/.github/plugins/azure-sdk-python/skills/azure-speech-to-text-rest-py/SKILL.md @@ -41,7 +41,7 @@ pip install requests > **🔑 Two rules apply to every code sample below:** > -> 1. **Two auth modes are supported.** Use a subscription key (`Ocp-Apim-Subscription-Key` header) for quick access, or a Microsoft Entra bearer token (including one acquired with `DefaultAzureCredential`) via the `Authorization` request header. Never hardcode credentials in source. +> 1. **Two auth modes are supported.** Use a subscription key (`Ocp-Apim-Subscription-Key` header) for quick access, or a Microsoft Entra token (including one acquired with `DefaultAzureCredential`) via the `Authorization` request header (see "Option 2" below). Never hardcode credentials in source. > 2. **Use context managers for files and HTTP resources** so file handles and network connections are released deterministically: > - Sync: `with open(...) as f:` and (when reusing connections) `with requests.Session() as session:` > - Async: `async with aiohttp.ClientSession() as session:` From d7fb53a6cc240ef53e0dbf3b2886eafc5c73d9da Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Wed, 15 Jul 2026 19:43:04 +0000 Subject: [PATCH 22/26] Address all open PR review comments MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Fix pnpm-workspace.yaml: resolve esbuild allowBuilds placeholder - Fix azure-mgmt-apicenter non-hero: add missing closing parenthesis - Fix azure-monitor-opentelemetry SKILL.md: flush() → force_flush() - Fix azure-monitor-opentelemetry-exporter SKILL.md: flush() → force_flush() - Fix azure-storage-queue non-hero: re-raise instead of silently passing exception - Fix azure-identity non-hero: log and re-raise auth errors instead of silently passing - Fix azure-ai-contentunderstanding non-hero: AnalysisInput → AnalyzeInput, fix model imports - Fix azure-ai-transcription SKILL.md + non-hero: use AzureKeyCredential wrapper - Fix m365-agents capabilities.md: complete CopilotClient example end-to-end --- .../references/non-hero-scenarios.md | 13 +++-- .../skills/azure-ai-transcription-py/SKILL.md | 9 ++-- .../references/non-hero-scenarios.md | 15 ++++-- .../references/non-hero-scenarios.md | 16 ++++-- .../references/non-hero-scenarios.md | 2 +- .../SKILL.md | 2 +- .../azure-monitor-opentelemetry-py/SKILL.md | 2 +- .../references/non-hero-scenarios.md | 5 +- .../m365-agents-py/references/capabilities.md | 49 ++++++++++++++----- tests/pnpm-workspace.yaml | 2 +- 10 files changed, 78 insertions(+), 37 deletions(-) diff --git a/.github/plugins/azure-sdk-python/skills/azure-ai-contentunderstanding-py/references/non-hero-scenarios.md b/.github/plugins/azure-sdk-python/skills/azure-ai-contentunderstanding-py/references/non-hero-scenarios.md index 1a713870..754b45ef 100644 --- a/.github/plugins/azure-sdk-python/skills/azure-ai-contentunderstanding-py/references/non-hero-scenarios.md +++ b/.github/plugins/azure-sdk-python/skills/azure-ai-contentunderstanding-py/references/non-hero-scenarios.md @@ -6,11 +6,11 @@ They cover secondary/advanced patterns typically used after the primary end-to-e ## Analyze Image ```python -from azure.ai.contentunderstanding.models import AnalysisInput +from azure.ai.contentunderstanding.models import AnalyzeInput poller = client.begin_analyze( analyzer_id="prebuilt-imageSearch", - inputs=[AnalysisInput(url="https://example.com/image.jpg")] + inputs=[AnalyzeInput(url="https://example.com/image.jpg")] ) result = poller.result() content = result.contents[0] @@ -65,7 +65,7 @@ Create custom analyzers with field schemas for specialized extraction: ```python from azure.ai.contentunderstanding.models import ( - AnalysisInput, + AnalyzeInput, ContentAnalyzer, ContentFieldDefinition, ContentFieldSchema, @@ -100,7 +100,7 @@ poller.result() # wait until analyzer is ready # Use custom analyzer analyze_poller = client.begin_analyze( analyzer_id="my-invoice-analyzer", - inputs=[AnalysisInput(url="https://example.com/invoice.pdf")] + inputs=[AnalyzeInput(url="https://example.com/invoice.pdf")] ) result = analyze_poller.result() @@ -166,9 +166,8 @@ Both derive from `AnalysisContent`, which provides basic information and a markd ```python from azure.ai.contentunderstanding.models import ( - AnalysisInput, - AnalysisResult, - AnalysisContent, + AnalyzeInput, + AnalyzeResult, DocumentContent, AudioVisualContent, ) diff --git a/.github/plugins/azure-sdk-python/skills/azure-ai-transcription-py/SKILL.md b/.github/plugins/azure-sdk-python/skills/azure-ai-transcription-py/SKILL.md index 3f997727..e27cf180 100644 --- a/.github/plugins/azure-sdk-python/skills/azure-ai-transcription-py/SKILL.md +++ b/.github/plugins/azure-sdk-python/skills/azure-ai-transcription-py/SKILL.md @@ -42,11 +42,12 @@ Use subscription key authentication: ```python import os +from azure.core.credentials import AzureKeyCredential from azure.ai.transcription import TranscriptionClient with TranscriptionClient( endpoint=os.environ["TRANSCRIPTION_ENDPOINT"], - credential=os.environ["TRANSCRIPTION_KEY"], + credential=AzureKeyCredential(os.environ["TRANSCRIPTION_KEY"]), ) as client: transcriptions = list(client.list_transcriptions()) ``` @@ -55,11 +56,12 @@ with TranscriptionClient( ```python import os +from azure.core.credentials import AzureKeyCredential from azure.ai.transcription import TranscriptionClient with TranscriptionClient( endpoint=os.environ["TRANSCRIPTION_ENDPOINT"], - credential=os.environ["TRANSCRIPTION_KEY"], + credential=AzureKeyCredential(os.environ["TRANSCRIPTION_KEY"]), ) as client: job = client.begin_transcription( name="meeting-transcription", @@ -75,11 +77,12 @@ with TranscriptionClient( ```python import os +from azure.core.credentials import AzureKeyCredential from azure.ai.transcription import TranscriptionClient with TranscriptionClient( endpoint=os.environ["TRANSCRIPTION_ENDPOINT"], - credential=os.environ["TRANSCRIPTION_KEY"], + credential=AzureKeyCredential(os.environ["TRANSCRIPTION_KEY"]), ) as client: stream = client.begin_stream_transcription(locale="en-US") stream.send_audio_file("audio.wav") diff --git a/.github/plugins/azure-sdk-python/skills/azure-ai-transcription-py/references/non-hero-scenarios.md b/.github/plugins/azure-sdk-python/skills/azure-ai-transcription-py/references/non-hero-scenarios.md index a574699b..ab708539 100644 --- a/.github/plugins/azure-sdk-python/skills/azure-ai-transcription-py/references/non-hero-scenarios.md +++ b/.github/plugins/azure-sdk-python/skills/azure-ai-transcription-py/references/non-hero-scenarios.md @@ -11,6 +11,7 @@ Configure retries for transient failures via `azure-core` retry policy: ```python import os +from azure.core.credentials import AzureKeyCredential from azure.ai.transcription import TranscriptionClient from azure.core.pipeline.policies import RetryPolicy @@ -18,7 +19,7 @@ retry_policy = RetryPolicy(retry_total=3, retry_backoff_factor=2) with TranscriptionClient( endpoint=os.environ["TRANSCRIPTION_ENDPOINT"], - credential=os.environ["TRANSCRIPTION_KEY"], + credential=AzureKeyCredential(os.environ["TRANSCRIPTION_KEY"]), retry_policy=retry_policy, ) as client: job = client.begin_transcription( @@ -35,11 +36,12 @@ Avoid blocking indefinitely on long-running batch jobs: ```python import os +from azure.core.credentials import AzureKeyCredential from azure.ai.transcription import TranscriptionClient with TranscriptionClient( endpoint=os.environ["TRANSCRIPTION_ENDPOINT"], - credential=os.environ["TRANSCRIPTION_KEY"], + credential=AzureKeyCredential(os.environ["TRANSCRIPTION_KEY"]), ) as client: job = client.begin_transcription( name="long-audio", @@ -57,11 +59,12 @@ with TranscriptionClient( ```python import os +from azure.core.credentials import AzureKeyCredential from azure.ai.transcription import TranscriptionClient with TranscriptionClient( endpoint=os.environ["TRANSCRIPTION_ENDPOINT"], - credential=os.environ["TRANSCRIPTION_KEY"], + credential=AzureKeyCredential(os.environ["TRANSCRIPTION_KEY"]), ) as client: for index, transcription in enumerate(client.list_transcriptions()): print(f"[{index}] {transcription.name}: {transcription.status}") @@ -73,11 +76,12 @@ Remove completed jobs to keep the account tidy: ```python import os +from azure.core.credentials import AzureKeyCredential from azure.ai.transcription import TranscriptionClient with TranscriptionClient( endpoint=os.environ["TRANSCRIPTION_ENDPOINT"], - credential=os.environ["TRANSCRIPTION_KEY"], + credential=AzureKeyCredential(os.environ["TRANSCRIPTION_KEY"]), ) as client: for transcription in client.list_transcriptions(): if transcription.status == "Succeeded": @@ -90,12 +94,13 @@ Use the async client for non-blocking workflows: ```python import os +from azure.core.credentials import AzureKeyCredential from azure.ai.transcription.aio import TranscriptionClient async def run_async_transcription(): async with TranscriptionClient( endpoint=os.environ["TRANSCRIPTION_ENDPOINT"], - credential=os.environ["TRANSCRIPTION_KEY"], + credential=AzureKeyCredential(os.environ["TRANSCRIPTION_KEY"]), ) as client: job = await client.begin_transcription( name="async-meeting", diff --git a/.github/plugins/azure-sdk-python/skills/azure-identity-py/references/non-hero-scenarios.md b/.github/plugins/azure-sdk-python/skills/azure-identity-py/references/non-hero-scenarios.md index e1c9ec06..06509500 100644 --- a/.github/plugins/azure-sdk-python/skills/azure-identity-py/references/non-hero-scenarios.md +++ b/.github/plugins/azure-sdk-python/skills/azure-identity-py/references/non-hero-scenarios.md @@ -83,17 +83,23 @@ credential = ClientSecretCredential( ```python from azure.identity import DefaultAzureCredential, CredentialUnavailableError from azure.core.exceptions import ClientAuthenticationError +import logging + +logger = logging.getLogger(__name__) with DefaultAzureCredential() as credential: try: token = credential.get_token("https://management.azure.com/.default") except CredentialUnavailableError: - # No credential in the chain could attempt authentication - pass + # No credential in the chain could attempt authentication. + # Log and re-raise so the caller can surface the configuration issue. + logger.error("No credential available — check Azure CLI login or Managed Identity configuration") + raise except ClientAuthenticationError as e: - # Authentication was attempted but failed - # e.message contains details from each credential in the chain - pass + # Authentication was attempted but failed. + # e.message contains details from each credential in the chain. + logger.error("Authentication failed: %s", e.message) + raise ``` ## Logging diff --git a/.github/plugins/azure-sdk-python/skills/azure-mgmt-apicenter-py/references/non-hero-scenarios.md b/.github/plugins/azure-sdk-python/skills/azure-mgmt-apicenter-py/references/non-hero-scenarios.md index b78ca5be..a327f7a9 100644 --- a/.github/plugins/azure-sdk-python/skills/azure-mgmt-apicenter-py/references/non-hero-scenarios.md +++ b/.github/plugins/azure-sdk-python/skills/azure-mgmt-apicenter-py/references/non-hero-scenarios.md @@ -54,7 +54,7 @@ apis = client.apis.list( ) for api in apis: - print(f"{api.name}: {api.properties.title} ({api.properties.kind})" + print(f"{api.name}: {api.properties.title} ({api.properties.kind})") ``` ## Create Environment diff --git a/.github/plugins/azure-sdk-python/skills/azure-monitor-opentelemetry-exporter-py/SKILL.md b/.github/plugins/azure-sdk-python/skills/azure-monitor-opentelemetry-exporter-py/SKILL.md index 86f904ba..7feaa1cd 100644 --- a/.github/plugins/azure-sdk-python/skills/azure-monitor-opentelemetry-exporter-py/SKILL.md +++ b/.github/plugins/azure-sdk-python/skills/azure-monitor-opentelemetry-exporter-py/SKILL.md @@ -230,7 +230,7 @@ exporter = AzureMonitorTraceExporter( ## Best Practices 1. **Pick sync OR async and stay consistent.** Do not mix `azure.xxx` sync clients with `azure.xxx.aio` async clients in the same call path. Choose one mode per module. -2. **Call `provider.shutdown()` / `flush()` at process exit to flush telemetry — providers are not context managers.** +2. **Call `provider.shutdown()` / `force_flush()` at process exit to flush telemetry — providers are not context managers.** 3. **Use BatchSpanProcessor** for production (not SimpleSpanProcessor) 4. **Use ApplicationInsightsSampler** for consistent sampling across services 5. **Enable offline storage** for reliability in production diff --git a/.github/plugins/azure-sdk-python/skills/azure-monitor-opentelemetry-py/SKILL.md b/.github/plugins/azure-sdk-python/skills/azure-monitor-opentelemetry-py/SKILL.md index ef0b2e0f..b2d2779a 100644 --- a/.github/plugins/azure-sdk-python/skills/azure-monitor-opentelemetry-py/SKILL.md +++ b/.github/plugins/azure-sdk-python/skills/azure-monitor-opentelemetry-py/SKILL.md @@ -245,7 +245,7 @@ configure_azure_monitor( ## Best Practices 1. **Pick sync OR async and stay consistent.** Do not mix `azure.xxx` sync clients with `azure.xxx.aio` async clients in the same call path. Choose one mode per module. -2. **Call `provider.shutdown()` / `flush()` at process exit to flush telemetry — providers are not context managers.** +2. **Call `provider.shutdown()` / `force_flush()` at process exit to flush telemetry — providers are not context managers.** 3. **Call configure_azure_monitor() early** — Before importing instrumented libraries 4. **Use environment variables** for connection string in production 5. **Set cloud role name** for multi-service applications diff --git a/.github/plugins/azure-sdk-python/skills/azure-storage-queue-py/references/non-hero-scenarios.md b/.github/plugins/azure-sdk-python/skills/azure-storage-queue-py/references/non-hero-scenarios.md index aafaf0a7..c4a37422 100644 --- a/.github/plugins/azure-sdk-python/skills/azure-storage-queue-py/references/non-hero-scenarios.md +++ b/.github/plugins/azure-sdk-python/skills/azure-storage-queue-py/references/non-hero-scenarios.md @@ -33,8 +33,9 @@ for message in messages: # Process... queue_client.delete_message(message) except Exception: - # Message becomes visible again after timeout - pass + # Message becomes visible again after visibility timeout for retry. + # Log the failure and re-raise so the caller is aware. + raise ``` ## Clear Queue diff --git a/.github/plugins/azure-sdk-python/skills/m365-agents-py/references/capabilities.md b/.github/plugins/azure-sdk-python/skills/m365-agents-py/references/capabilities.md index 508bccf8..b1ebbc62 100644 --- a/.github/plugins/azure-sdk-python/skills/m365-agents-py/references/capabilities.md +++ b/.github/plugins/azure-sdk-python/skills/m365-agents-py/references/capabilities.md @@ -17,33 +17,60 @@ This reference mirrors the actual capability sections in `SKILL.md` and provides ```python import asyncio +from os import environ from msal import PublicClientApplication -from microsoft_agents.activity import ActivityTypes, load_configuration_from_env +from microsoft_agents.activity import ActivityTypes from microsoft_agents.copilotstudio.client import ( ConnectionSettings, CopilotClient, ) -# Token cache (local file for interactive flows) -class LocalTokenCache: - # See samples for full implementation - pass -def acquire_token(settings, app_client_id, tenant_id): +def acquire_token(app_client_id: str, tenant_id: str) -> str: pca = PublicClientApplication( client_id=app_client_id, authority=f"https://login.microsoftonline.com/{tenant_id}", ) - token_request = {"scopes": ["https://api.powerplatform.com/.default"]} + scopes = ["https://api.powerplatform.com/.default"] accounts = pca.get_accounts() if accounts: - response = pca.acquire_token_silent(token_request["scopes"], account=accounts[0]) - return response.get("access_token") + response = pca.acquire_token_silent(scopes, account=accounts[0]) else: - response = pca.acquire_token_interactive(**token_request) - return response.get("access_token") + response = pca.acquire_token_interactive(scopes=scopes) + + return response["access_token"] + + +async def main() -> None: + settings = ConnectionSettings( + environment_id=environ["COPILOTSTUDIOAGENT__ENVIRONMENTID"], + agent_identifier=environ["COPILOTSTUDIOAGENT__SCHEMANAME"], + ) + + token = acquire_token( + app_client_id=environ["COPILOTSTUDIOAGENT__AGENTAPPID"], + tenant_id=environ["COPILOTSTUDIOAGENT__TENANTID"], + ) + + # CopilotClient does not implement the context manager protocol. + copilot_client = CopilotClient(settings, token) + + # Start conversation and collect the opening activity + act = copilot_client.start_conversation(True) + async for action in act: + if action.text: + print(action.text) + + # Send a message and iterate replies + replies = copilot_client.ask_question("Hello!", action.conversation.id) + async for reply in replies: + if reply.type == ActivityTypes.message: + print(reply.text) + + +asyncio.run(main()) ``` ## API breadth checklist diff --git a/tests/pnpm-workspace.yaml b/tests/pnpm-workspace.yaml index 00f6fc47..5ed0b5af 100644 --- a/tests/pnpm-workspace.yaml +++ b/tests/pnpm-workspace.yaml @@ -1,2 +1,2 @@ allowBuilds: - esbuild: set this to true or false + esbuild: true From 9c67af11637fa4dc5002a57d3ce74ba0bdbe84f1 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Wed, 15 Jul 2026 19:47:22 +0000 Subject: [PATCH 23/26] Polish m365-agents capabilities: improve variable names and context manager comment --- .../m365-agents-py/references/capabilities.md | 15 ++++++++------- 1 file changed, 8 insertions(+), 7 deletions(-) diff --git a/.github/plugins/azure-sdk-python/skills/m365-agents-py/references/capabilities.md b/.github/plugins/azure-sdk-python/skills/m365-agents-py/references/capabilities.md index b1ebbc62..de88b702 100644 --- a/.github/plugins/azure-sdk-python/skills/m365-agents-py/references/capabilities.md +++ b/.github/plugins/azure-sdk-python/skills/m365-agents-py/references/capabilities.md @@ -54,17 +54,18 @@ async def main() -> None: tenant_id=environ["COPILOTSTUDIOAGENT__TENANTID"], ) - # CopilotClient does not implement the context manager protocol. + # CopilotClient does not implement the context manager protocol; close + # any underlying resources explicitly when your application shuts down. copilot_client = CopilotClient(settings, token) - # Start conversation and collect the opening activity - act = copilot_client.start_conversation(True) - async for action in act: - if action.text: - print(action.text) + # Start conversation and collect the opening activities + opening_activities = copilot_client.start_conversation(True) + async for activity in opening_activities: + if activity.text: + print(activity.text) # Send a message and iterate replies - replies = copilot_client.ask_question("Hello!", action.conversation.id) + replies = copilot_client.ask_question("Hello!", activity.conversation.id) async for reply in replies: if reply.type == ActivityTypes.message: print(reply.text) From 407be445af5a42e55fda757eae9f746e42b6f735 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Wed, 15 Jul 2026 21:30:27 +0000 Subject: [PATCH 24/26] Fix remaining review comments and CI pipeline failure - Delete tests/pnpm-workspace.yaml (caused CI 'packages field missing' error) - Delete azure-cosmos-py/scripts/setup_cosmos_container.py (outside PR scope) - Fix pydantic-models-py: clarify model_validate vs direct construction - Fix m365-agents-py: remove activity.conversation.id (UnboundLocalError on empty stream) - Fix azure-messaging-webpubsubservice-py: use close_user_connections, don't log bearer token URL - Fix azure-messaging-webpubsubservice-py acceptance-criteria: update connection close example - Fix azure-ai-transcription-py: correct LROPoller timeout pattern (done()+deadline loop) - Fix azure-ai-transcription-py acceptance-criteria: remove DefaultAzureCredential anti-pattern - Fix azure-ai-translation-text-py: use InputTextItem instead of raw strings in all bodies - Fix azure-ai-ml-py: remove unused Pipeline import - Fix azure-ai-language-conversations-py: fix orchestration intents (dict keyed by name) --- .../references/non-hero-scenarios.md | 8 +- .../references/non-hero-scenarios.md | 1 - .../references/non-hero-scenarios.md | 10 +- .../references/non-hero-scenarios.md | 19 +- .../scripts/setup_cosmos_container.py | 326 ------------------ .../references/non-hero-scenarios.md | 5 +- .../m365-agents-py/references/capabilities.md | 4 +- .../references/capabilities.md | 2 +- tests/pnpm-workspace.yaml | 2 - .../acceptance-criteria.md | 6 +- .../acceptance-criteria.md | 8 +- 11 files changed, 38 insertions(+), 353 deletions(-) delete mode 100644 .github/plugins/azure-sdk-python/skills/azure-cosmos-py/scripts/setup_cosmos_container.py delete mode 100644 tests/pnpm-workspace.yaml diff --git a/.github/plugins/azure-sdk-python/skills/azure-ai-language-conversations-py/references/non-hero-scenarios.md b/.github/plugins/azure-sdk-python/skills/azure-ai-language-conversations-py/references/non-hero-scenarios.md index 27762cf9..fded76ab 100644 --- a/.github/plugins/azure-sdk-python/skills/azure-ai-language-conversations-py/references/non-hero-scenarios.md +++ b/.github/plugins/azure-sdk-python/skills/azure-ai-language-conversations-py/references/non-hero-scenarios.md @@ -125,11 +125,9 @@ result = client.analyze_conversation( prediction = result["result"]["prediction"] top_intent = prediction["topIntent"] -# Orchestration projects expose the target intent result under the intent name -intent_result = next( - (i for i in prediction["intents"] if i["category"] == top_intent), {} -) -target_kind = intent_result.get("targetProjectKind") # e.g. "Luis" or "Conversation" +# Orchestration: prediction['intents'] is a dict keyed by intent name +intent_data = prediction["intents"].get(top_intent, {}) +target_kind = intent_data.get("targetProjectKind") # e.g. "Luis" or "Conversation" print(f"Routed to: {top_intent} ({target_kind})") ``` diff --git a/.github/plugins/azure-sdk-python/skills/azure-ai-ml-py/references/non-hero-scenarios.md b/.github/plugins/azure-sdk-python/skills/azure-ai-ml-py/references/non-hero-scenarios.md index f363f7b1..0556eff5 100644 --- a/.github/plugins/azure-sdk-python/skills/azure-ai-ml-py/references/non-hero-scenarios.md +++ b/.github/plugins/azure-sdk-python/skills/azure-ai-ml-py/references/non-hero-scenarios.md @@ -36,7 +36,6 @@ ml_client.jobs.stream(returned_job.name) ```python from azure.ai.ml import dsl, Input, Output -from azure.ai.ml.entities import Pipeline @dsl.pipeline( compute="cpu-cluster", diff --git a/.github/plugins/azure-sdk-python/skills/azure-ai-transcription-py/references/non-hero-scenarios.md b/.github/plugins/azure-sdk-python/skills/azure-ai-transcription-py/references/non-hero-scenarios.md index ab708539..a5d146bb 100644 --- a/.github/plugins/azure-sdk-python/skills/azure-ai-transcription-py/references/non-hero-scenarios.md +++ b/.github/plugins/azure-sdk-python/skills/azure-ai-transcription-py/references/non-hero-scenarios.md @@ -48,8 +48,14 @@ with TranscriptionClient( locale="en-US", content_urls=["https:///long-audio.wav"], ) - # Raise azure.core.exceptions.OperationTimeoutError if not done within 300 s - result = job.result(timeout=300) + # Poll with an explicit deadline; job.result() does not raise on timeout + import time + deadline = time.monotonic() + 300 + while not job.done(): + if time.monotonic() > deadline: + raise TimeoutError("Transcription did not complete within 300 s") + time.sleep(5) + result = job.result() print(result.status) ``` diff --git a/.github/plugins/azure-sdk-python/skills/azure-ai-translation-text-py/references/non-hero-scenarios.md b/.github/plugins/azure-sdk-python/skills/azure-ai-translation-text-py/references/non-hero-scenarios.md index d58575ca..8bc5844d 100644 --- a/.github/plugins/azure-sdk-python/skills/azure-ai-translation-text-py/references/non-hero-scenarios.md +++ b/.github/plugins/azure-sdk-python/skills/azure-ai-translation-text-py/references/non-hero-scenarios.md @@ -8,8 +8,10 @@ They cover secondary/advanced patterns typically used after the primary end-to-e Convert text from one script to another: ```python +from azure.ai.translation.text.models import InputTextItem + result = client.transliterate( - body=["konnichiwa"], + body=[InputTextItem(text="konnichiwa")], language="ja", from_script="Latn", # From Latin script to_script="Jpan" # To Japanese script @@ -25,8 +27,10 @@ for item in result: Find alternate translations and definitions: ```python +from azure.ai.translation.text.models import InputTextItem + result = client.lookup_dictionary_entries( - body=["fly"], + body=[InputTextItem(text="fly")], from_language="en", to_language="es" ) @@ -87,8 +91,10 @@ for code, lang in languages.dictionary.items(): Identify sentence boundaries: ```python +from azure.ai.translation.text.models import InputTextItem + result = client.find_sentence_boundaries( - body=["Hello! How are you? I hope you are well."], + body=[InputTextItem(text="Hello! How are you? I hope you are well.")], language="en" ) @@ -99,8 +105,10 @@ for item in result: ## Translation Options ```python +from azure.ai.translation.text.models import InputTextItem + result = client.translate( - body=["Hello, world!"], + body=[InputTextItem(text="Hello, world!")], to_language=["de"], text_type="html", # "plain" or "html" profanity_action="Marked", # "NoAction", "Deleted", "Marked" @@ -122,6 +130,7 @@ for item in result: ```python from azure.ai.translation.text.aio import TextTranslationClient +from azure.ai.translation.text.models import InputTextItem from azure.identity.aio import DefaultAzureCredential async def translate_text(): @@ -131,7 +140,7 @@ async def translate_text(): endpoint=endpoint, ) as client: result = await client.translate( - body=["Hello, world!"], + body=[InputTextItem(text="Hello, world!")], to_language=["es"] ) print(result[0].translations[0].text) diff --git a/.github/plugins/azure-sdk-python/skills/azure-cosmos-py/scripts/setup_cosmos_container.py b/.github/plugins/azure-sdk-python/skills/azure-cosmos-py/scripts/setup_cosmos_container.py deleted file mode 100644 index d9baedf1..00000000 --- a/.github/plugins/azure-sdk-python/skills/azure-cosmos-py/scripts/setup_cosmos_container.py +++ /dev/null @@ -1,326 +0,0 @@ -#!/usr/bin/env python3 -""" -Cosmos DB Container Setup CLI Tool - -Create and configure Azure Cosmos DB containers with proper partitioning, -throughput settings, and indexing policies. - -Usage: - python setup_cosmos_container.py --database mydb --container orders --partition-key /customer_id - python setup_cosmos_container.py --database mydb --container events --partition-key /device_id /day --throughput 1000 - python setup_cosmos_container.py --database mydb --container data --partition-key /pk --serverless - -Environment Variables: - COSMOS_ENDPOINT - Cosmos DB account endpoint URL - COSMOS_KEY - Cosmos DB account key (optional if using DefaultAzureCredential) -""" - -import argparse -import json -import os -import sys -from typing import Any - -from azure.identity import DefaultAzureCredential -from azure.cosmos import CosmosClient, PartitionKey -from azure.cosmos.exceptions import CosmosHttpResponseError - - -def get_cosmos_client() -> CosmosClient: - """Create Cosmos DB client from environment variables.""" - endpoint = os.environ.get("COSMOS_ENDPOINT") - if not endpoint: - raise ValueError("COSMOS_ENDPOINT environment variable required") - - # Try key auth first, fall back to DefaultAzureCredential - key = os.environ.get("COSMOS_KEY") - if key: - return CosmosClient(url=endpoint, credential=key) - else: - credential = DefaultAzureCredential() - return CosmosClient(url=endpoint, credential=credential) - - -def create_indexing_policy( - include_paths: list[str] | None = None, - exclude_paths: list[str] | None = None, - composite_indexes: list[list[dict]] | None = None, -) -> dict[str, Any]: - """Build an indexing policy.""" - policy = { - "indexingMode": "consistent", - "automatic": True, - "includedPaths": [], - "excludedPaths": [], - } - - # Include paths (default: all) - if include_paths: - policy["includedPaths"] = [{"path": p} for p in include_paths] - else: - policy["includedPaths"] = [{"path": "/*"}] - - # Exclude paths - if exclude_paths: - policy["excludedPaths"] = [{"path": p} for p in exclude_paths] - - # Always exclude _etag - policy["excludedPaths"].append({"path": "/_etag/?"}) - - # Composite indexes for ORDER BY on multiple fields - if composite_indexes: - policy["compositeIndexes"] = composite_indexes - - return policy - - -def create_container( - client: CosmosClient, - database_id: str, - container_id: str, - partition_key_paths: list[str], - throughput: int | None = None, - ttl: int | None = None, - indexing_policy: dict | None = None, -) -> dict[str, Any]: - """Create or update a Cosmos DB container.""" - - # Get or create database - try: - database = client.create_database_if_not_exists(id=database_id) - print(f"Database: {database_id}") - except CosmosHttpResponseError as e: - print(f"Error creating database: {e.message}") - raise - - # Build partition key - if len(partition_key_paths) == 1: - partition_key = PartitionKey(path=partition_key_paths[0]) - else: - # Hierarchical partition key - partition_key = PartitionKey(path=partition_key_paths) - - # Container properties - container_props = {"id": container_id, "partition_key": partition_key} - - # Add TTL if specified - if ttl is not None: - container_props["default_time_to_live"] = ttl - - # Add indexing policy if specified - if indexing_policy: - container_props["indexing_policy"] = indexing_policy - - # Create container - try: - if throughput: - container = database.create_container_if_not_exists( - **container_props, offer_throughput=throughput - ) - else: - container = database.create_container_if_not_exists(**container_props) - - print(f"Container: {container_id}") - print(f"Partition key: {partition_key_paths}") - - except CosmosHttpResponseError as e: - if e.status_code == 409: - print(f"Container {container_id} already exists") - container = database.get_container_client(container_id) - else: - print(f"Error creating container: {e.message}") - raise - - # Get container properties - properties = container.read() - - return { - "database": database_id, - "container": container_id, - "partition_key": partition_key_paths, - "self_link": properties.get("_self"), - "resource_id": properties.get("_rid"), - } - - -def show_container_info(client: CosmosClient, database_id: str, container_id: str): - """Display detailed container information.""" - database = client.get_database_client(database_id) - container = database.get_container_client(container_id) - - properties = container.read() - - print("\n=== Container Information ===") - print(f"Database: {database_id}") - print(f"Container: {container_id}") - print(f"Partition Key: {properties.get('partitionKey', {}).get('paths', [])}") - - # TTL - ttl = properties.get("defaultTtl") - if ttl == -1: - print("TTL: Enabled (per-item)") - elif ttl: - print(f"TTL: {ttl} seconds") - else: - print("TTL: Disabled") - - # Indexing policy - index_policy = properties.get("indexingPolicy", {}) - print(f"Indexing Mode: {index_policy.get('indexingMode', 'consistent')}") - - # Throughput - try: - offer = container.read_offer() - print(f"Throughput: {offer.offer_throughput} RU/s") - if offer.properties.get("content", {}).get("offerAutopilotSettings"): - max_throughput = offer.properties["content"]["offerAutopilotSettings"][ - "maxThroughput" - ] - print(f"Autoscale Max: {max_throughput} RU/s") - except Exception: - print("Throughput: Serverless or database-level") - - # Item count (approximate) - try: - query = "SELECT VALUE COUNT(1) FROM c" - count = list( - container.query_items(query=query, enable_cross_partition_query=True) - )[0] - print(f"Item Count: ~{count}") - except Exception: - print("Item Count: Unable to retrieve") - - -def main(): - parser = argparse.ArgumentParser( - description="Create and configure Cosmos DB containers", - formatter_class=argparse.RawDescriptionHelpFormatter, - epilog=__doc__, - ) - - parser.add_argument("--database", "-d", required=True, help="Database ID") - parser.add_argument("--container", "-c", required=True, help="Container ID") - parser.add_argument( - "--partition-key", - "-pk", - nargs="+", - required=True, - help="Partition key path(s). Use multiple for hierarchical keys.", - ) - parser.add_argument( - "--throughput", - "-t", - type=int, - help="Provisioned throughput in RU/s (omit for serverless)", - ) - parser.add_argument( - "--serverless", - action="store_true", - help="Use serverless mode (no throughput provisioning)", - ) - parser.add_argument( - "--ttl", type=int, help="Default TTL in seconds (-1 for per-item TTL)" - ) - parser.add_argument( - "--exclude-paths", - nargs="+", - help="Paths to exclude from indexing (e.g., /large_field/*)", - ) - parser.add_argument( - "--composite-index", - action="append", - nargs="+", - metavar="PATH", - help="Composite index paths (can specify multiple times). Format: --composite-index /field1 /field2", - ) - parser.add_argument( - "--info", - action="store_true", - help="Show container information instead of creating", - ) - parser.add_argument( - "--output", - "-o", - choices=["json", "text"], - default="text", - help="Output format (default: text)", - ) - - args = parser.parse_args() - - # Validate arguments - if args.throughput and args.serverless: - print("Error: Cannot specify both --throughput and --serverless") - sys.exit(1) - - # Ensure partition key paths start with / - partition_keys = [] - for pk in args.partition_key: - if not pk.startswith("/"): - pk = f"/{pk}" - partition_keys.append(pk) - - try: - client = get_cosmos_client() - except ValueError as e: - print(f"Error: {e}") - sys.exit(1) - - # Show info mode - if args.info: - try: - show_container_info(client, args.database, args.container) - except CosmosHttpResponseError as e: - print(f"Error: {e.message}") - sys.exit(1) - return - - # Build indexing policy - indexing_policy = None - if args.exclude_paths or args.composite_index: - composite_indexes = None - if args.composite_index: - composite_indexes = [ - [{"path": p, "order": "ascending"} for p in index_paths] - for index_paths in args.composite_index - ] - - indexing_policy = create_indexing_policy( - exclude_paths=args.exclude_paths, composite_indexes=composite_indexes - ) - - # Create container - try: - result = create_container( - client=client, - database_id=args.database, - container_id=args.container, - partition_key_paths=partition_keys, - throughput=args.throughput if not args.serverless else None, - ttl=args.ttl, - indexing_policy=indexing_policy, - ) - except CosmosHttpResponseError as e: - print(f"Error: {e.message}") - sys.exit(1) - - # Output result - if args.output == "json": - print(json.dumps(result, indent=2)) - else: - print("\n=== Container Created ===") - print(f"Database: {result['database']}") - print(f"Container: {result['container']}") - print(f"Partition Key: {result['partition_key']}") - if args.throughput: - print(f"Throughput: {args.throughput} RU/s") - else: - print("Throughput: Serverless") - if args.ttl: - print(f"TTL: {args.ttl} seconds") - - print("\nContainer ready for use!") - - -if __name__ == "__main__": - main() diff --git a/.github/plugins/azure-sdk-python/skills/azure-messaging-webpubsubservice-py/references/non-hero-scenarios.md b/.github/plugins/azure-sdk-python/skills/azure-messaging-webpubsubservice-py/references/non-hero-scenarios.md index dd20ffaa..de3313e6 100644 --- a/.github/plugins/azure-sdk-python/skills/azure-messaging-webpubsubservice-py/references/non-hero-scenarios.md +++ b/.github/plugins/azure-sdk-python/skills/azure-messaging-webpubsubservice-py/references/non-hero-scenarios.md @@ -72,7 +72,7 @@ Remove all connections from a group before deleting it: ```python # Remove a user from all groups, then close their connections client.remove_user_from_all_groups(user_id="user123") -client.close_all_connections(user_id="user123", reason="Session ended") +client.close_user_connections(user_id="user123", reason="Session ended") ``` ### Short-lived Access Tokens @@ -89,7 +89,8 @@ token = client.get_client_access_token( minutes_to_expire=30, groups=["my-group"], ) -print(f"Connect URL: {token['url']}") +# Pass the URL directly to the authorized client — do not log it (it embeds a bearer token) +connect_url = token["url"] ``` ### Async Client diff --git a/.github/plugins/azure-sdk-python/skills/m365-agents-py/references/capabilities.md b/.github/plugins/azure-sdk-python/skills/m365-agents-py/references/capabilities.md index de88b702..b27a60a3 100644 --- a/.github/plugins/azure-sdk-python/skills/m365-agents-py/references/capabilities.md +++ b/.github/plugins/azure-sdk-python/skills/m365-agents-py/references/capabilities.md @@ -64,8 +64,8 @@ async def main() -> None: if activity.text: print(activity.text) - # Send a message and iterate replies - replies = copilot_client.ask_question("Hello!", activity.conversation.id) + # Send a message and iterate replies; CopilotClient retains the conversation ID + replies = copilot_client.ask_question("Hello!") async for reply in replies: if reply.type == ActivityTypes.message: print(reply.text) diff --git a/.github/plugins/azure-sdk-python/skills/pydantic-models-py/references/capabilities.md b/.github/plugins/azure-sdk-python/skills/pydantic-models-py/references/capabilities.md index b3228e34..7c461490 100644 --- a/.github/plugins/azure-sdk-python/skills/pydantic-models-py/references/capabilities.md +++ b/.github/plugins/azure-sdk-python/skills/pydantic-models-py/references/capabilities.md @@ -21,5 +21,5 @@ This reference captures additional non-hero capabilities and API breadth so the - Verify field validators (`@field_validator`) and model validators (`@model_validator`) cover all required constraints. - Confirm serialization behavior: use `model_dump(mode="json")` for JSON-safe output and `model_dump(exclude_unset=True)` for partial updates. - Include schema generation examples (`model_json_schema()`) when the model drives API contracts or documentation. -- Prefer `model_validate` over direct construction to ensure validators and coercion run. +- Use `model_validate` when validating an existing dict or object; direct `BaseModel(...)` construction also runs validators and coercion. - Ensure new code uses Pydantic v2 patterns (`@field_validator`, `model_config`) rather than deprecated v1 patterns (`@validator`, `orm_mode`). diff --git a/tests/pnpm-workspace.yaml b/tests/pnpm-workspace.yaml deleted file mode 100644 index 5ed0b5af..00000000 --- a/tests/pnpm-workspace.yaml +++ /dev/null @@ -1,2 +0,0 @@ -allowBuilds: - esbuild: true diff --git a/tests/scenarios/azure-ai-transcription-py/acceptance-criteria.md b/tests/scenarios/azure-ai-transcription-py/acceptance-criteria.md index c92f3797..5a41e0a0 100644 --- a/tests/scenarios/azure-ai-transcription-py/acceptance-criteria.md +++ b/tests/scenarios/azure-ai-transcription-py/acceptance-criteria.md @@ -54,13 +54,13 @@ from azure.ai.transcription.models import ( ### 1.3 Anti-Patterns (ERRORS) -#### ❌ INCORRECT: Using DefaultAzureCredential +#### ❌ INCORRECT: Using DefaultAzureCredential when only key auth was supported ```python -# WRONG - TranscriptionClient only supports subscription key auth +# WRONG - older SDK versions only support subscription key auth from azure.identity import DefaultAzureCredential client = TranscriptionClient( endpoint=endpoint, - credential=DefaultAzureCredential() # This will fail + credential=DefaultAzureCredential() # Fails on older SDK versions ) ``` diff --git a/tests/scenarios/azure-messaging-webpubsubservice-py/acceptance-criteria.md b/tests/scenarios/azure-messaging-webpubsubservice-py/acceptance-criteria.md index 2b0085ed..070f056f 100644 --- a/tests/scenarios/azure-messaging-webpubsubservice-py/acceptance-criteria.md +++ b/tests/scenarios/azure-messaging-webpubsubservice-py/acceptance-criteria.md @@ -186,15 +186,15 @@ user_connected = client.user_exists(user_id="user123") group_has_connections = client.group_exists(group="my-group") client.close_connection(connection_id="abc123", reason="Session ended") -client.close_all_connections(user_id="user123") +client.close_user_connections(user_id="user123", reason="Session ended") ``` ### 6.2 Anti-Patterns (ERRORS) -#### ❌ INCORRECT: Wrong parameter name +#### ❌ INCORRECT: Wrong method for closing a user's connections ```python -# WRONG - close_all_connections requires user_id -client.close_all_connections(connection_id="abc123") +# WRONG - close_all_connections does not accept user_id; use close_user_connections instead +client.close_all_connections(user_id="user123") ``` --- From bbe36fb7a95111547794fda5703b7e7a79409037 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Wed, 15 Jul 2026 21:31:12 +0000 Subject: [PATCH 25/26] Move import time to top of transcription timeout example --- .../azure-ai-transcription-py/references/non-hero-scenarios.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/plugins/azure-sdk-python/skills/azure-ai-transcription-py/references/non-hero-scenarios.md b/.github/plugins/azure-sdk-python/skills/azure-ai-transcription-py/references/non-hero-scenarios.md index a5d146bb..5fec3267 100644 --- a/.github/plugins/azure-sdk-python/skills/azure-ai-transcription-py/references/non-hero-scenarios.md +++ b/.github/plugins/azure-sdk-python/skills/azure-ai-transcription-py/references/non-hero-scenarios.md @@ -36,6 +36,7 @@ Avoid blocking indefinitely on long-running batch jobs: ```python import os +import time from azure.core.credentials import AzureKeyCredential from azure.ai.transcription import TranscriptionClient @@ -49,7 +50,6 @@ with TranscriptionClient( content_urls=["https:///long-audio.wav"], ) # Poll with an explicit deadline; job.result() does not raise on timeout - import time deadline = time.monotonic() + 300 while not job.done(): if time.monotonic() > deadline: From 8b9dd9e1af318fe359db379a8afaea71b62c2f6d Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Wed, 15 Jul 2026 21:37:51 +0000 Subject: [PATCH 26/26] Fix transcription acceptance criteria: add DefaultAzureCredential as valid auth, remove incorrect anti-pattern --- .../acceptance-criteria.md | 24 ++++++++++--------- 1 file changed, 13 insertions(+), 11 deletions(-) diff --git a/tests/scenarios/azure-ai-transcription-py/acceptance-criteria.md b/tests/scenarios/azure-ai-transcription-py/acceptance-criteria.md index 5a41e0a0..19c394dc 100644 --- a/tests/scenarios/azure-ai-transcription-py/acceptance-criteria.md +++ b/tests/scenarios/azure-ai-transcription-py/acceptance-criteria.md @@ -22,6 +22,18 @@ client = TranscriptionClient( ) ``` +#### ✅ CORRECT: Entra ID / DefaultAzureCredential (preferred for production) +```python +import os +from azure.ai.transcription import TranscriptionClient +from azure.identity import DefaultAzureCredential + +client = TranscriptionClient( + endpoint=os.environ["TRANSCRIPTION_ENDPOINT"], + credential=DefaultAzureCredential() +) +``` + #### ✅ CORRECT: Using environment variables ```python from azure.ai.transcription import TranscriptionClient @@ -54,16 +66,6 @@ from azure.ai.transcription.models import ( ### 1.3 Anti-Patterns (ERRORS) -#### ❌ INCORRECT: Using DefaultAzureCredential when only key auth was supported -```python -# WRONG - older SDK versions only support subscription key auth -from azure.identity import DefaultAzureCredential -client = TranscriptionClient( - endpoint=endpoint, - credential=DefaultAzureCredential() # Fails on older SDK versions -) -``` - #### ❌ INCORRECT: Importing from wrong module ```python # WRONG - TranscriptionClient is at top level @@ -593,7 +595,7 @@ job = client.begin_transcription( | Error | Cause | Fix | |-------|-------|-----| -| `AuthenticationError` | Wrong credential type | Use `AzureKeyCredential`, not `DefaultAzureCredential` | +| `AuthenticationError` | Wrong or missing credential | Use `AzureKeyCredential` or `DefaultAzureCredential`; never hardcode keys | | `AttributeError: 'NoneType' object` | Result is None | Check `result.status == "succeeded"` first | | `IndexError: list index out of range` | No results in list | Check `if result.results:` before indexing | | `Stream stuck/hanging` | Not calling `stream.stop()` | Always call `stream.stop()` after sending audio |