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..754b45ef --- /dev/null +++ b/.github/plugins/azure-sdk-python/skills/azure-ai-contentunderstanding-py/references/non-hero-scenarios.md @@ -0,0 +1,181 @@ +# 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 +from azure.ai.contentunderstanding.models import ( + AnalyzeInput, + 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", + 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 +analyze_poller = client.begin_analyze( + analyzer_id="my-invoice-analyzer", + inputs=[AnalyzeInput(url="https://example.com/invoice.pdf")] +) + +result = analyze_poller.result() + +# 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 + +```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 `AnalysisContent`, which provides basic information and a markdown representation. + +## Model Imports + +```python +from azure.ai.contentunderstanding.models import ( + AnalyzeInput, + AnalyzeResult, + 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..fded76ab --- /dev/null +++ b/.github/plugins/azure-sdk-python/skills/azure-ai-language-conversations-py/references/non-hero-scenarios.md @@ -0,0 +1,168 @@ +# 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 + +### 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: 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})") +``` + +### 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-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..0556eff5 --- /dev/null +++ b/.github/plugins/azure-sdk-python/skills/azure-ai-ml-py/references/non-hero-scenarios.md @@ -0,0 +1,103 @@ +# 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 + +@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..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 @@ -24,20 +24,30 @@ pip install azure-ai-transcription ```bash TRANSCRIPTION_ENDPOINT=https://.cognitiveservices.azure.com -TRANSCRIPTION_KEY= +TRANSCRIPTION_KEY= # For key auth; not needed when using DefaultAzureCredential/TokenCredential ``` -## Authentication +## Authentication & Lifecycle -Use subscription key authentication (DefaultAzureCredential is not supported for this client): +> **🔑 Two rules apply to every code sample below:** +> +> 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:` +> +> Snippets may abbreviate this setup, but production code should always follow both rules. + +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()) ``` @@ -46,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", @@ -66,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") @@ -88,3 +100,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..5fec3267 --- /dev/null +++ b/.github/plugins/azure-sdk-python/skills/azure-ai-transcription-py/references/non-hero-scenarios.md @@ -0,0 +1,119 @@ +# 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 + +### Retry Policy + +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 + +retry_policy = RetryPolicy(retry_total=3, retry_backoff_factor=2) + +with TranscriptionClient( + endpoint=os.environ["TRANSCRIPTION_ENDPOINT"], + credential=AzureKeyCredential(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 +import time +from azure.core.credentials import AzureKeyCredential +from azure.ai.transcription import TranscriptionClient + +with TranscriptionClient( + endpoint=os.environ["TRANSCRIPTION_ENDPOINT"], + credential=AzureKeyCredential(os.environ["TRANSCRIPTION_KEY"]), +) as client: + job = client.begin_transcription( + name="long-audio", + locale="en-US", + content_urls=["https:///long-audio.wav"], + ) + # Poll with an explicit deadline; job.result() does not raise on timeout + 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) +``` + +### List and Paginate Transcriptions + +`list_transcriptions()` returns a lazy iterator; paginate explicitly to avoid loading everything at once: + +```python +import os +from azure.core.credentials import AzureKeyCredential +from azure.ai.transcription import TranscriptionClient + +with TranscriptionClient( + endpoint=os.environ["TRANSCRIPTION_ENDPOINT"], + credential=AzureKeyCredential(os.environ["TRANSCRIPTION_KEY"]), +) as client: + for index, transcription in enumerate(client.list_transcriptions()): + print(f"[{index}] {transcription.name}: {transcription.status}") +``` + +### Delete Completed Transcriptions + +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=AzureKeyCredential(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.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=AzureKeyCredential(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-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..15eb6947 --- /dev/null +++ b/.github/plugins/azure-sdk-python/skills/azure-ai-translation-document-py/references/non-hero-scenarios.md @@ -0,0 +1,113 @@ +# 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 + +`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 +from azure.ai.translation.text import 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 +for code, lang in result.translation.items(): + print(f"Language: {lang.name} ({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..8bc5844d --- /dev/null +++ b/.github/plugins/azure-sdk-python/skills/azure-ai-translation-text-py/references/non-hero-scenarios.md @@ -0,0 +1,159 @@ +# 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 +from azure.ai.translation.text.models import InputTextItem + +result = client.transliterate( + body=[InputTextItem(text="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 +from azure.ai.translation.text.models import InputTextItem + +result = client.lookup_dictionary_entries( + body=[InputTextItem(text="fly")], + from_language="en", + to_language="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_language="en", + to_language="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 +from azure.ai.translation.text.models import InputTextItem + +result = client.find_sentence_boundaries( + body=[InputTextItem(text="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 +from azure.ai.translation.text.models import InputTextItem + +result = client.translate( + body=[InputTextItem(text="Hello, world!")], + to_language=["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.ai.translation.text.models import InputTextItem +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=[InputTextItem(text="Hello, world!")], + to_language=["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..fe197704 --- /dev/null +++ b/.github/plugins/azure-sdk-python/skills/azure-appconfiguration-py/references/non-hero-scenarios.md @@ -0,0 +1,59 @@ +# 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, ConfigurationSettingsFilter + +snapshot = ConfigurationSnapshot( + filters=[ + ConfigurationSettingsFilter(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..033e8b9f --- /dev/null +++ b/.github/plugins/azure-sdk-python/skills/azure-containerregistry-py/references/non-hero-scenarios.md @@ -0,0 +1,82 @@ +# 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 +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 + +```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 deleted file mode 100644 index 88cb5d06..00000000 --- a/.github/plugins/azure-sdk-python/skills/azure-cosmos-py/scripts/setup_cosmos_container.py +++ /dev/null @@ -1,334 +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-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..72576325 --- /dev/null +++ b/.github/plugins/azure-sdk-python/skills/azure-eventgrid-py/references/non-hero-scenarios.md @@ -0,0 +1,52 @@ +# 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.core.messaging import CloudEvent +from azure.eventgrid.aio import EventGridPublisherClient +from azure.identity.aio import DefaultAzureCredential + +async def publish_events(): + 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()) +``` + +## Namespace Topics (Event Grid Namespaces) + +For Event Grid Namespaces (pull delivery): + +```python +from azure.core.messaging import CloudEvent +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 DefaultAzureCredential() as credential: + with EventGridPublisherClient( + endpoint=namespace_endpoint, + 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-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..06509500 --- /dev/null +++ b/.github/plugins/azure-sdk-python/skills/azure-identity-py/references/non-hero-scenarios.md @@ -0,0 +1,135 @@ +# 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 +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. + # 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. + logger.error("Authentication failed: %s", e.message) + raise +``` + +## 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..ccc2649a --- /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(f"Retrieved secret: {secret.name} (version: {secret.properties.version})") + +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..de3313e6 --- /dev/null +++ b/.github/plugins/azure-sdk-python/skills/azure-messaging-webpubsubservice-py/references/non-hero-scenarios.md @@ -0,0 +1,119 @@ +# 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 + +### 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_user_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"], +) +# Pass the URL directly to the authorized client — do not log it (it embeds a bearer token) +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", + ) +``` 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..a327f7a9 --- /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.properties.title} ({api.properties.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..cc26dd53 --- /dev/null +++ b/.github/plugins/azure-sdk-python/skills/azure-mgmt-apimanagement-py/references/non-hero-scenarios.md @@ -0,0 +1,157 @@ +# 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("Subscription created") +``` + +## 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 +import os +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=os.environ["BACKEND_API_KEY"], + 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..279f4841 --- /dev/null +++ b/.github/plugins/azure-sdk-python/skills/azure-mgmt-botservice-py/references/non-hero-scenarios.md @@ -0,0 +1,209 @@ +# 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}") + # Use site.key without logging or persisting it. +``` + +## Bot Connections (OAuth) + +### Create Connection Setting + +```python +import os +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=os.environ["OAUTH_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..7847e587 --- /dev/null +++ b/.github/plugins/azure-sdk-python/skills/azure-mgmt-fabric-py/references/non-hero-scenarios.md @@ -0,0 +1,140 @@ +# 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, RpSku + +updated = client.fabric_capacities.begin_update( + resource_group_name=resource_group, + capacity_name=capacity_name, + properties=FabricCapacityUpdate( + sku=RpSku( + 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() + +for sku in skus: + locations = ", ".join(sku.locations) if sku.locations is not None else "N/A" + print(f"SKU: {sku.name} - Locations: {locations}") +``` + +## 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..a0e11ba3 --- /dev/null +++ b/.github/plugins/azure-sdk-python/skills/azure-monitor-ingestion-py/references/non-hero-scenarios.md @@ -0,0 +1,74 @@ +# 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 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()) +``` + +## 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..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 @@ -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()` / `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 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..af09ed2a --- /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. 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() + +exporter = AzureMonitorTraceExporter( + credential=credential +) +``` + +## Sampling + +Use `ApplicationInsightsSampler` for consistent sampling: + +```python +from opentelemetry import trace +from opentelemetry.sdk.trace import TracerProvider +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..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 @@ -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()` / `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 @@ -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..bffdd918 --- /dev/null +++ b/.github/plugins/azure-sdk-python/skills/azure-monitor-opentelemetry-py/references/non-hero-scenarios.md @@ -0,0 +1,140 @@ +# 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 + +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( + instrumentation_options={ + "django": {"enabled": False}, + "psycopg2": {"enabled": False}, + } +) +``` + +## 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. 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() + +configure_azure_monitor( + credential=credential +) +``` + +## Auto-Instrumentations Included + +| Library | Telemetry Type | +|---------|---------------| +| Flask | Traces | +| Django | Traces | +| FastAPI | Traces | +| Requests | Traces | +| urllib | Traces | +| urllib3 | Traces | +| psycopg2 | Traces | +| Azure SDK | 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 | +| `instrumentation_options` | Dict controlling per-library `enabled` flags | All enabled | +| `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..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 @@ -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. **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:` +> +> 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..95d21b1b --- /dev/null +++ b/.github/plugins/azure-sdk-python/skills/azure-storage-blob-py/references/non-hero-scenarios.md @@ -0,0 +1,47 @@ +# 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 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-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..c4a37422 --- /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 visibility timeout for retry. + # Log the failure and re-raise so the caller is aware. + raise +``` + +## 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(): + 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()) +``` + +## 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..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,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 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 + +| 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..d440f94f --- /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` + +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 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. 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..b27a60a3 --- /dev/null +++ b/.github/plugins/azure-sdk-python/skills/m365-agents-py/references/capabilities.md @@ -0,0 +1,83 @@ +# 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 os import environ +from msal import PublicClientApplication +from microsoft_agents.activity import ActivityTypes +from microsoft_agents.copilotstudio.client import ( + ConnectionSettings, + CopilotClient, +) + + +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}", + ) + + scopes = ["https://api.powerplatform.com/.default"] + accounts = pca.get_accounts() + + if accounts: + response = pca.acquire_token_silent(scopes, account=accounts[0]) + else: + 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; close + # any underlying resources explicitly when your application shuts down. + copilot_client = CopilotClient(settings, token) + + # 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; CopilotClient retains the conversation ID + replies = copilot_client.ask_question("Hello!") + async for reply in replies: + if reply.type == ActivityTypes.message: + print(reply.text) + + +asyncio.run(main()) +``` + +## 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..7c461490 --- /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` + +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 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. +- 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/.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 diff --git a/tests/scenarios/azure-ai-transcription-py/acceptance-criteria.md b/tests/scenarios/azure-ai-transcription-py/acceptance-criteria.md index c92f3797..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 -```python -# WRONG - TranscriptionClient only supports subscription key auth -from azure.identity import DefaultAzureCredential -client = TranscriptionClient( - endpoint=endpoint, - credential=DefaultAzureCredential() # This will fail -) -``` - #### ❌ 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 | 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") ``` ---