Add azure-mgmt-unified-design.md: TypedDict-driven Azure management SDK design document

[Copilot]

Description

Adds a design document showcasing a lightweight unified Azure management SDK approach using Python's TypedDict for declarative resource specifications with automated CRUD/paging/LRO operation mapping.

Document contents:

• TypedDict meta-definitions: ResourceSpec, OperationSpec, PagingSpec, LROSpec, CRUDSpec, ParameterSpec
• Example resource specs for VirtualMachine and StorageAccount
• AutoResourceManager base class implementation with automatic operation generation
• ResourceManagerFactory for resource registration and access
• Practical usage examples

Key pattern:

VIRTUAL_MACHINE_SPEC: ResourceSpec = {
    "name": "VirtualMachine",
    "provider_namespace": "Microsoft.Compute",
    "resource_type": "virtualMachines",
    "api_version": "2024-07-01",
    "crud": {"get": True, "create_or_update": True, "delete": True, "list": True},
    "paging": {"item_name": "value", "next_link_name": "nextLink"},
    "lro": {"polling_method": "azure-async-operation", "polling_interval": 30},
}

Location: doc/dev/mgmt/azure-mgmt-unified-design.md

All SDK Contribution checklist:

• The pull request does not introduce [breaking changes]
• CHANGELOG is updated for new features, bug fixes or other significant changes.
• I have read the contribution guidelines.

General Guidelines and Best Practices

• Title of the pull request is clear and informative.
• There are a small number of commits, each of which have an informative message. This means that previously merged commits do not appear in the history of the PR. For more information on cleaning up the commits in your PR, see this page.

Testing Guidelines

• Pull request includes test coverage for the included changes.

N/A - documentation only, no executable code changes.

Original prompt

Create a Gist for the lightweight unified Azure management SDK design, featuring TypedDict meta-definitions for automated CRUD/paging/LRO operation mapping. See the provided markdown content for architectural explanation, TypedDict definitions, example resource specifications, automated resource manager code, benefits, and a practical usage example. The file should be named azure-mgmt-unified-design.md and showcase the TypedDict-driven approach for easy maintenance and extensibility of Azure resource managers in Python.

This pull request was created as a result of the following prompt from Copilot chat.

Create a Gist for the lightweight unified Azure management SDK design, featuring TypedDict meta-definitions for automated CRUD/paging/LRO operation mapping. See the provided markdown content for architectural explanation, TypedDict definitions, example resource specifications, automated resource manager code, benefits, and a practical usage example. The file should be named azure-mgmt-unified-design.md and showcase the TypedDict-driven approach for easy maintenance and extensibility of Azure resource managers in Python.

---

💬 We'd love your input! Share your thoughts on Copilot coding agent in our 2 minute survey.

[github-actions]

Hi @copilot. Thank you for your interest in helping to improve the Azure SDK experience and for your contribution. We've noticed that there hasn't been recent engagement on this pull request. If this is still an active work stream, please let us know by pushing some changes or leaving a comment. Otherwise, we'll close this out in 7 days.

[github-actions]

Hi @copilot. Thank you for your interest in helping to improve the Azure SDK experience and for your contribution. We've noticed that there hasn't been recent engagement on this pull request. If this is still an active work stream, please let us know by pushing some changes or leaving a comment. Otherwise, we'll close this out in 7 days.

[Copilot]

🟡 Changes recommended

Critical implementation issues and an unrelated file remain unresolved.

Get a fresh assessment by requesting another Copilot review.

Pull request overview

Adds a TypedDict-driven design for unified Azure management resource managers, including CRUD, paging, LRO, factory, and usage examples.

Changes:

• Adds metadata schemas and VM/Storage Account specifications.
• Adds illustrative manager, factory, and usage implementations.
• Adds the unrelated root-level agents.md guide.

File summaries

File	Findings
doc/dev/mgmt/azure-mgmt-unified-design.md	Critical: update is advertised but not implemented (3 votes); LRO polling passes an unsent request (3 votes); PipelineClient uses the wrong import path (1 vote). Moderate: required spec metadata is not enforced (2 votes); synchronous PUT does not wait for LRO completion (1 vote).
agents.md	Moderate: Unrelated root-level guide conflicts with the stated PR scope (3 votes).

Review details

Suppressed comments (11)

doc/dev/mgmt/azure-mgmt-unified-design.md:450

• Although create_or_update accepts an OperationSpec, this implementation only tests its truthiness and then hard-codes the generic URL, PUT method, and model_type. The StorageAccount override's URL, parameters, and response_model are therefore ignored; resolve and apply the selected operation specification instead.

        url = self._get_base_url(resource_group_name, resource_name)
        body = self._serialize.body(parameters, self._spec.get("model_type", ""))
        request = self._build_request("PUT", url, json=body, **kwargs)

doc/dev/mgmt/azure-mgmt-unified-design.md:243

• The examples populate custom_operations with power_off, start, and list_keys, but neither register nor AutoResourceManager generates or exposes methods for these entries. As written, those advertised operations—and the later restart example—cannot be called through the factory.

    "custom_operations": [
        {
            "name": "power_off",
            "http_method": "POST",
            "url_template": (
                "/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}"
                "/providers/Microsoft.Compute/virtualMachines/{vmName}/powerOff"
            ),

doc/dev/mgmt/azure-mgmt-unified-design.md:400

• The scope metadata is never consulted: this URL builder always requires a resource-group path. A spec declaring subscription, tenant, or resource scope will still produce the resource-group URL and method signature, so the documented scope options do not work.

    def _get_base_url(self, resource_group_name: str, resource_name: str) -> str:
        """Generate the base URL for a specific resource."""
        provider = self._spec.get("provider_namespace", "")
        resource_type = self._spec.get("resource_type", "")
        return (
            f"/subscriptions/{{subscriptionId}}/resourceGroups/{resource_group_name}"
            f"/providers/{provider}/{resource_type}/{resource_name}"

doc/dev/mgmt/azure-mgmt-unified-design.md:606

• The request URL is still relative when it is passed directly to the pipeline. ARM operation implementations format requests with self._client.format_url(...) first; without that step this code sends paths such as /subscriptions/... to the transport instead of an absolute management endpoint.

        pipeline_response = self._client._pipeline.run(request, stream=False)

doc/dev/mgmt/azure-mgmt-unified-design.md:610

• Every non-success response is raised as the base HttpResponseError, so a 404 is never converted to ResourceNotFoundError; the error-handling example below therefore cannot catch a missing VM as shown. Apply an ARM error map (at least for 404/401/409/304) before raising.

        if response.status_code >= 400:
            from azure.core.exceptions import HttpResponseError
            raise HttpResponseError(response=response)

doc/dev/mgmt/azure-mgmt-unified-design.md:478

• Only polling_interval is read from LROSpec; polling_method, final_state_via, and timeout are never passed to ARMPolling. Consequently the Storage Account specification's location final-state behavior and timeout setting have no effect.

        lro_spec = self._spec.get("lro", {})
        polling_interval = lro_spec.get("polling_interval", 30)
        
        def get_long_running_output(response: HttpResponse) -> ModelType:
            return self._deserialize(self._spec.get("model_type", ""), response)

doc/dev/mgmt/azure-mgmt-unified-design.md:536

• The delete LRO has the same initialization bug: the request is never sent and an HttpRequest is passed where LROPoller expects a PipelineResponse, so begin_delete fails immediately instead of starting the operation.

        return LROPoller(
            self._client,
            request,
            lambda _: None,
            ARMPolling(polling_interval),

doc/dev/mgmt/azure-mgmt-unified-design.md:530

• This delete path also reads only polling_interval; the declared polling strategy, final-state mode, and timeout are ignored just as in begin_create_or_update. The metadata-driven LRO behavior is therefore not implemented for deletes.

        lro_spec = self._spec.get("lro", {})
        polling_interval = lro_spec.get("polling_interval", 30)
        
        url = self._get_base_url(resource_group_name, resource_name)
        request = self._build_request("DELETE", url, **kwargs)

doc/dev/mgmt/azure-mgmt-unified-design.md:772

• ARMPipelineClient requires an ARM configuration object or explicit policies; passing credential directly without either causes its constructor to raise before the factory is created. Build the service configuration with the credential and pass it as config to the client.

client = ARMPipelineClient(
    base_url="https://management.azure.com",
    credential=credential,
)

doc/dev/mgmt/azure-mgmt-unified-design.md:777

• The usage example passes a plain dictionary as config, but _build_url dereferences self._config.subscription_id. The first manager request therefore raises AttributeError; use the same typed ARM configuration object for both the client and factory, or consistently support mapping access.

    config={"subscription_id": subscription_id},

doc/dev/mgmt/azure-mgmt-unified-design.md:452

• Both example resources declare LRO settings, but this synchronous method sends the PUT once and immediately deserializes its initial response. For an ARM 202 response it returns before provisioning completes, so the documented ModelType result is not reliable; LRO resources should use the polling path or wait here.

        url = self._get_base_url(resource_group_name, resource_name)
        body = self._serialize.body(parameters, self._spec.get("model_type", ""))
        request = self._build_request("PUT", url, json=body, **kwargs)
        response = self._send_request(request)
        return self._deserialize(self._spec.get("model_type", ""), response)

• Files reviewed: 2/2 changed files
• Comments generated: 5
• Review effort level: Lite

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.