Skip to content
Draft
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
14 changes: 14 additions & 0 deletions .chronus/changes/python-lro-status-metadata-operation-id.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,14 @@
---
changeKind: feature
packages:
- "@typespec/http-client-python"
---

Generate `MetadataLROPoller` and `AsyncMetadataLROPoller` for Azure operations using `@lroStatusMetadata` or `@lroOperationId`. Their `details` and `operation_id` properties expose selected monitor metadata and server-issued identifiers, refresh on polling, and repopulate after resuming from a continuation token. Operations without these annotations retain their existing pollers.

```python
poller = client.begin_analyze(document)
result = poller.result()
print(poller.operation_id)
print(poller.details)
```
1 change: 1 addition & 0 deletions cspell.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -214,6 +214,7 @@ words:
- onwarn
- openapi
- opfields
- operationid
- oxlint
- openapiv
- Packument
Expand Down
15 changes: 15 additions & 0 deletions packages/http-client-python/ARCHITECTURE.md
Original file line number Diff line number Diff line change
Expand Up @@ -308,6 +308,21 @@ The emitter supports different operation patterns:
- **Paging**: Operations that return paginated results
- **LRO + Paging**: Combined pattern

### Selected LRO Metadata

For Azure LROs annotated with `@lroStatusMetadata` or `@lroOperationId`, the emitter preserves the selected properties and status-monitor model in the intermediate code model. The generator exports `MetadataLROPoller` from the SDK package and `AsyncMetadataLROPoller` from its `aio` package. Unannotated operations retain their existing poller types.

The poller's `details` mapping exposes selected values by their Python client names, using the generated status-monitor deserializer. It reflects the latest successfully decoded monitor response: changed values replace earlier values, absent selected properties are `None`, and failed or canceled responses remain inspectable. Non-success HTTP responses, decoding failures, and a subsequent final-resource request do not replace the monitor snapshot. The `operation_id` property exposes a selected monitor-body ID, falling back to the selected parameter of the initial polling URI. When no selected property is named `operation_id`, `details["operation_id"]` also provides the identifier when available. Polling still uses the complete URL, including its query parameters.

Continuation tokens retain Azure Core's existing format. After resuming through the generated begin method, the URI identifier is immediately available, but selected monitor metadata is repopulated only after another monitor response. The default generated polling strategy refreshes metadata; an explicitly supplied custom polling strategy remains responsible for its own behavior.

```python
poller = client.begin_analyze(document, polling_interval=1)
result = poller.result()
print(poller.operation_id)
print(poller.details.get("percent_complete"))
```

### Model Modes

Two model generation modes:
Expand Down
66 changes: 66 additions & 0 deletions packages/http-client-python/emitter/src/http.ts
Original file line number Diff line number Diff line change
Expand Up @@ -23,6 +23,7 @@ import type {
} from "@azure-tools/typespec-client-generator-core";
import { getHttpOperationParameter, UsageFlags } from "@azure-tools/typespec-client-generator-core";
import type { HttpStatusCodeRange } from "@typespec/http";
import { getHeaderFieldName } from "@typespec/http";
import type { PythonSdkContext } from "./lib.js";
import { reportDiagnostic } from "./lib.js";
import { getType, KnownTypes } from "./types.js";
Expand Down Expand Up @@ -285,6 +286,70 @@ function emitInitialLroHttpMethod(
};
}

function emitLroMetadata(
context: PythonSdkContext,
method: SdkLroServiceMethod<SdkHttpOperation> | SdkLroPagingServiceMethod<SdkHttpOperation>,
) {
const metadata = method.lroMetadata;
if (!metadata?.statusMetadata?.length && !metadata?.operationId?.length) return undefined;
const wirePath = (segments: SdkModelPropertyType[]) =>
segments.map((property) => property.serializationOptions.json?.name ?? property.name);
const pathId = metadata.operationId?.find((id) => id.kind === "path");
const bodyId = metadata.operationId?.find((id) => id.kind === "property");
const step = metadata.statusMonitorStep;
const pollingOperation =
step?.kind === "nextOperationLink" ? step.operation : step?.target.operation;
let operationIdUri: { location: string; property: string; pattern: string } | undefined;
if (pathId) {
const template = pollingOperation?.uriTemplate;
const path = template?.split(/\{[?&]/, 1)[0].split("?", 1)[0];
const segments = path?.split(/(\{[^{}]*\})/);
const parameter = `{${pathId.pathParameter.serializedName}}`;
const valid =
segments &&
segments.filter((segment) => segment === parameter).length === 1 &&
segments.every((segment) => /^\{[a-zA-Z0-9._%~-]+\}$/.test(segment) || !/[{}]/.test(segment));
if (valid) {
const pattern =
segments
.map((segment) =>
segment === parameter
? "(?P<operation_id>[^/]+)"
: segment.startsWith("{")
? "[^/]+"
: segment.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"),
)
.join("") + "/?$";
operationIdUri = {
location: pathId.source.location,
property:
pathId.source.location === "ResponseHeader" && pathId.source.property.__raw

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

why are we having to access __raw here? is that something we could get from tcgc

? getHeaderFieldName(context.program, pathId.source.property.__raw)
: (pathId.source.property.serializationOptions.json?.name ??
pathId.source.property.name),
pattern,
};
} else {
reportDiagnostic(context.program, {
code: "unsupported-lro-operation-id-template",
target: NoTarget,
format: { operationId: method.name, template: template ?? "(missing)" },
});
}
}
return {
responseModel: getType(context, metadata.pollingInfo.responseModel),
statusMetadata: metadata.statusMetadata?.map((selection) => ({
propertySegments: wirePath(selection.propertySegments),
})),
operationIdPath: bodyId ? wirePath(bodyId.propertySegments) : undefined,
operationIdUri,
initialResponseIsMonitor: method.operation.responses.some(
(response) => response.type === metadata.pollingInfo.responseModel,
),
};
}

function addLroInformation(
context: PythonSdkContext,
rootClient: SdkClientType<SdkHttpOperation>,
Expand Down Expand Up @@ -313,6 +378,7 @@ function addLroInformation(
exposeStreamKeyword: false,
description: method.doc ?? "",
summary: method.summary,
lroMetadata: emitLroMetadata(context, method),
};
}

Expand Down
6 changes: 6 additions & 0 deletions packages/http-client-python/emitter/src/lib.ts
Original file line number Diff line number Diff line change
Expand Up @@ -218,6 +218,12 @@ const libDef = {
default: paramMessage`No valid LRO result for operation '${"operationId"}'.`,
},
},
"unsupported-lro-operation-id-template": {
severity: "warning",
messages: {
default: paramMessage`Cannot extract the LRO operation ID for operation '${"operationId"}' from URI template '${"template"}'.`,
},
},
"invalid-continuation-token": {
severity: "warning",
messages: {
Expand Down
126 changes: 126 additions & 0 deletions packages/http-client-python/emitter/test/lro-metadata.test.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,126 @@
import { expectDiagnostics } from "@typespec/compiler/testing";
import { expect, it } from "vitest";
import { emitCodeModel } from "./test-host.js";

it.each([true, false])(
"emits selected LRO paths without changing unannotated operations (%s)",
async (annotated) => {
const { codeModel, diagnostics } = await emitCodeModel(`
import "@azure-tools/typespec-azure-core";
import "@azure-tools/typespec-client-generator-core";
using TypeSpec.Http;
using Azure.Core;
using Azure.ClientGenerator.Core;

@service namespace Test;
model Usage { tokens: int32; }
model BaseStatus {
${annotated ? "@lroStatusMetadata" : ""}
@clientName("progress")
@encodedName("application/json", "wire.progress")
usage?: Usage;
}
model Monitor extends BaseStatus {
${annotated ? "@lroOperationId" : ""}
@encodedName("application/json", "server-id")
id: string;
status: Foundations.OperationState;
result?: string;
}
@get @route("/operations/{id}/status")
op poll(${annotated ? "@lroOperationId" : ""} @path id: string): Monitor;
@post @route("/jobs")
@pollingOperation(poll)
op start(): Foundations.AcceptedResponse<Monitor> &
Foundations.LongRunningStatusLocation<Monitor>;
`);
expectDiagnostics(diagnostics, []);
const client = codeModel.clients[0] as {
operationGroups: { operations: { name: string; lroMetadata?: unknown }[] }[];
};
const start = client.operationGroups
.flatMap((group) => group.operations)
.find((op) => op.name === "start");
expect(start).toBeDefined();
if (!annotated) {
expect(start).not.toHaveProperty("lroMetadata");
return;
}
expect(start).toEqual(
expect.objectContaining({
name: "start",
discriminator: "lro",
lroMetadata: expect.objectContaining({
responseModel: expect.objectContaining({ name: "Monitor" }),
statusMetadata: [{ propertySegments: ["wire.progress"] }],
operationIdPath: ["server-id"],
operationIdUri: {
location: "ResponseHeader",
property: "Operation-Location",
pattern: "/operations/(?P<operation_id>[^/]+)/status/?$",
},
initialResponseIsMonitor: true,
}),
}),
);
},
);

it.each(["{+id}", "{id*}"])(
"diagnoses unsupported operation-ID URI templates (%s)",
async (segment) => {
const { diagnostics } = await emitCodeModel(`
import "@azure-tools/typespec-azure-core";
import "@azure-tools/typespec-client-generator-core";
using TypeSpec.Http;
using Azure.Core;
using Azure.ClientGenerator.Core;

@service namespace Test;
model Monitor { status: Foundations.OperationState; result?: string; }
@get @route("/operations/${segment}/status")
op poll(@lroOperationId @path id: string): Monitor;
@post @route("/jobs")
@pollingOperation(poll)
op start(): Foundations.AcceptedResponse<Monitor> &
Foundations.LongRunningStatusLocation<Monitor>;
`);
expectDiagnostics(diagnostics, {
code: "@typespec/http-client-python/unsupported-lro-operation-id-template",
severity: "warning",
});
},
);

it("emits a path pattern for URI templates with other parameters and query expansions", async () => {
const { codeModel, diagnostics } = await emitCodeModel(`
import "@azure-tools/typespec-azure-core";
import "@azure-tools/typespec-client-generator-core";
using TypeSpec.Http;
using Azure.Core;
using Azure.ClientGenerator.Core;

@service namespace Test;
model Monitor { status: Foundations.OperationState; result?: string; }
@get @route("/v1.0/{account}/operations/{id}/status")
op poll(@path account: string, @lroOperationId @path id: string, @query apiVersion?: string): Monitor;
@post @route("/v1.0/{account}/jobs")
@pollingOperation(poll)
op start(@path account: string): Foundations.AcceptedResponse<Monitor> &
Foundations.LongRunningStatusLocation<Monitor>;
`);
expectDiagnostics(diagnostics, []);
const client = codeModel.clients[0] as {
operationGroups: {
operations: { name: string; lroMetadata?: { operationIdUri?: unknown } }[];
}[];
};
const start = client.operationGroups
.flatMap((group) => group.operations)
.find((op) => op.name === "start");
expect(start?.lroMetadata?.operationIdUri).toEqual({
location: "ResponseHeader",
property: "Operation-Location",
pattern: "/v1\\.0/[^/]+/operations/(?P<operation_id>[^/]+)/status/?$",
});
});
6 changes: 5 additions & 1 deletion packages/http-client-python/emitter/test/test-host.ts
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,11 @@ import { $onEmit } from "../src/emitter.js";
import { $lib, type PythonEmitterOptions } from "../src/lib.js";

const PythonTester = createTester(resolvePath(import.meta.dirname, "../.."), {
libraries: ["@azure-tools/typespec-client-generator-core", "@typespec/http"],
libraries: [
"@azure-tools/typespec-client-generator-core",
"@azure-tools/typespec-azure-core",
"@typespec/http",
],
});

export const Tester = PythonTester;
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -129,6 +129,12 @@ export const AZURE_EMITTER_OPTIONS: Record<string, EmitterOptions | EmitterOptio
"azure/client-generator-core/hierarchy-building": {
namespace: "specs.azure.clientgenerator.core.hierarchybuilding",
},
"azure/client-generator-core/lro/metadata": {
namespace: "specs.azure.clientgenerator.core.lro.metadata",
},
"azure/client-generator-core/lro/operation-id": {
namespace: "specs.azure.clientgenerator.core.lro.operationid",
},
"azure/core/basic": {
namespace: "specs.azure.core.basic",
},
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -173,7 +173,7 @@ def build_type(yaml_data: dict[str, Any], code_model: CodeModel) -> BaseType:
not code_model.options["models-mode"] and not code_model.generate_typeddict_only
):
model_type = JSONModelType
elif yaml_data["base"] == "dpg":
elif yaml_data["base"] == "dpg" and code_model.options["models-mode"] != "msrest":
model_type = DPGModelType # type: ignore
else:
model_type = MsrestModelType # type: ignore
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -14,6 +14,7 @@
from .client import Client
from .request_builder import RequestBuilder, OverloadedRequestBuilder
from .operation_group import OperationGroup
from .lro_operation import LROOperationBase
from .utils import NamespaceType
from .._utils import DEFAULT_HEADER_TEXT, DEFAULT_LICENSE_DESCRIPTION
from ... import OptionsDict
Expand Down Expand Up @@ -295,6 +296,14 @@ def has_structured_stream(self) -> bool:
for op in og.operations
)

@property
def has_lro_metadata(self) -> bool:
return any(
isinstance(operation, LROOperationBase) and operation.lro_metadata
for client in self.clients
for operation in client.lro_operations
)

def need_utils_utils(self, async_mode: bool, client_namespace: str) -> bool:
return (
self.need_utils_form_data(async_mode, client_namespace)
Expand Down
Loading
Loading