@contractkit/plugin-python 0.11.7 → 0.12.0

package/.turbo/turbo-build$colon$ci.log

@@ -5,9 +5,9 @@ $ tsup src/index.ts --format esm --sourcemap --dts && tsc --emitDeclarationOnly
 CLI tsup v8.5.1
 CLI Target: esnext
 ESM Build start
-ESM dist/index.js     43.30 KB
-ESM dist/index.js.map 92.85 KB
-ESM ⚡️ Build success in 274ms
+ESM dist/index.js     52.19 KB
+ESM dist/index.js.map 110.13 KB
+ESM ⚡️ Build success in 233ms
 DTS Build start
-DTS ⚡️ Build success in 4814ms
+DTS ⚡️ Build success in 5411ms
 DTS dist/index.d.ts 1.10 KB

package/.turbo/turbo-test$colon$ci.log

@@ -3,22 +3,22 @@ $ vitest run --coverage
  RUN  v4.1.5 /home/runner/work/ContractKit/ContractKit/packages/plugin-python
       Coverage enabled with v8
 
- ✓ tests/codegen-client.test.ts (30 tests) 70ms
- ✓ tests/codegen-models.test.ts (36 tests) 177ms
+ ✓ tests/codegen-models.test.ts (36 tests) 50ms
+ ✓ tests/codegen-client.test.ts (35 tests) 115ms
 
  Test Files  2 passed (2)
-      Tests  66 passed (66)
-   Start at  17:06:40
-   Duration  5.70s (transform 2.27s, setup 0ms, import 7.55s, tests 246ms, environment 0ms)
+      Tests  71 passed (71)
+   Start at  16:09:45
+   Duration  5.54s (transform 2.13s, setup 0ms, import 7.77s, tests 164ms, environment 0ms)
 
  % Coverage report from v8
 -------------------|---------|----------|---------|---------|-------------------
 File               | % Stmts | % Branch | % Funcs | % Lines | Uncovered Line #s 
 -------------------|---------|----------|---------|---------|-------------------
-All files          |   83.57 |    78.28 |   86.31 |   85.13 |                   
- src               |   83.33 |     78.6 |   84.28 |   84.61 |                   
-  ...gen-client.ts |   83.18 |    78.96 |   87.17 |   83.56 | ...02-522,555-556 
+All files          |   85.63 |    79.49 |   88.39 |   86.87 |                   
+ src               |   85.54 |    79.57 |   87.35 |   86.52 |                   
+  ...gen-client.ts |   86.69 |    80.31 |   91.07 |   86.84 | ...96-716,749-750 
   ...gen-models.ts |   83.53 |    78.06 |   80.64 |   85.97 | ...59,373-375,379 
- tests             |   86.66 |    74.19 |      92 |    92.1 |                   
-  helpers.ts       |   86.66 |    74.19 |      92 |    92.1 | 137-141,167       
+ tests             |   86.95 |    78.37 |      92 |    92.3 |                   
+  helpers.ts       |   86.95 |    78.37 |      92 |    92.3 | 137-141,170       
 -------------------|---------|----------|---------|---------|-------------------

package/CHANGELOG.md

@@ -1,5 +1,34 @@
 # @contractkit/contractkit-plugin-python
 
+## 0.12.0
+
+### Minor Changes
+
+- 85d7566: Let an operation emit more than one status, and a status serve more than one content type.
+
+    A status code could previously declare only one mime — the parser warned `Duplicate response body` and dropped the rest — and the generated router pinned both `ctx.status` and `ctx.type` to whichever response happened to be listed first with a body. An endpoint serving several formats had to declare one lying mime and let browsers sniff, and a service had no way to say which status it produced.
+
+    A status now holds every declared `mime: Type` line (`OpResponseNode.bodies`). When there is more than one, the service picks at runtime and the router sets `ctx.type` from the returned `contentType`. When an operation produces more than one status, the service returns a union discriminated on `status` and the handler switches on it, so each status writes only its own headers, mime and body. Both SDKs mirror the router: the TypeScript and Python clients return a matching union, report which mime came back, and pass the non-2xx statuses they expect to the shared fetch so a declared `304` no longer surfaces as an error. `SdkError` now takes a body type parameter, and each operation exports a `…ErrorBody` alias for the statuses that stay on the throw path.
+
+    Which statuses the service produces is derived from the declaration: **a status is emitted if it has a block, or is 2xx.** An empty block (`304: {}`) says the service returns that status carrying nothing; a bare `304:` says it is documented and something else produces it. `404(documented): { … }` is the one modifier, forcing a block-carrying status back out.
+
+    Two long-standing bugs in the same area go with it. The formatter deleted any comment written inside a `response` block — above a status code, above a mime line, above a `headers:` block, or before a closing brace — so `pnpm format` silently threw away the notes explaining why a contract looks the way it does; all four positions now round-trip. And the generated router declared a `_ZodBinary` helper for a binary _response_ body, which is a plain `Buffer` annotation with no schema behind it, leaving an unused const that tripped `noUnusedLocals` downstream; helpers are now chosen from the code that was actually generated, the same way imports already were.
+
+    **If you are already on a pre-release version, two things change under you.** A contract that declares a body on an error status — `404: { application/json: Problem }` alongside a `200` — now returns it from the service instead of throwing, and the SDK return type becomes a union; add `(documented)` to that status to keep the previous behaviour. Contracts whose error statuses are bodyless (`400:`, `404:`) are unaffected. Anything reading the AST directly should move from `OpResponseNode.contentType`/`bodyType` to `bodies`, which replaces them.
+
+### Patch Changes
+
+- Updated dependencies [85d7566]
+- Updated dependencies [90d19ee]
+    - @contractkit/core@0.25.0
+
+## 0.11.8
+
+### Patch Changes
+
+- Updated dependencies [23e4beb]
+    - @contractkit/core@0.24.0
+
 ## 0.11.7
 
 ### Patch Changes

package/README.md

@@ -50,6 +50,8 @@ Each `contract` declaration becomes a Pydantic v2 `BaseModel`. Contracts that ha
 
 Each operation file with at least one public operation generates a client class. Methods correspond to HTTP verbs and are named from the `sdk:` field in the `.ck` source. Request and response bodies are typed with the generated Pydantic models.
 
+A method returns its body directly when the operation has one response a caller can receive. When it has several, the return type is a union of per-status `TypedDict`s keyed on a `Literal` status, and when one status declares several content types the result carries the `content_type` that actually came back.
+
 ### Aggregator (`__init__.py`)
 
 The aggregator class (named from `packageName`) instantiates all client classes and exposes them as attributes. Pass the base URL and optional headers at construction time:
@@ -63,7 +65,9 @@ payment = sdk.payments.get_payment(id="pay_123")
 
 ### Base client (`_base_client.py`)
 
-Provides `BaseClient` (wraps `httpx.Client`) and `SdkError` (raised on non-2xx responses). All generated client classes inherit from `BaseClient`.
+Provides `BaseClient` (wraps `httpx.Client`) and `SdkError`. All generated client classes inherit from `BaseClient`.
+
+`SdkError` is raised for any response at or above 400 **except** the statuses an operation declares as values, which each method passes as `expect_statuses`. A `304` produced by conditional-GET middleware, or an error status the service returns deliberately, therefore comes back as a normal return value rather than an exception.
 
 ## Runtime dependencies
 

package/dist/codegen-client.d.ts

@@ -26,5 +26,5 @@ export declare function generatePythonClient(root: OpRootNode, opts?: ClientCode
 export declare function deriveClientClassName(file: string): string;
 export declare function deriveClientModuleName(file: string): string;
 export declare function deriveClientPropertyName(file: string): string;
-export declare const BASE_CLIENT_PY = "# Auto-generated by contractkit-plugin-python-sdk. Do not edit manually.\nfrom __future__ import annotations\n\nimport httpx\nfrom typing import Any\n\n\nclass SdkError(Exception):\n    def __init__(self, status: int, status_text: str, body: Any):\n        super().__init__(f\"{status} {status_text}\")\n        self.status = status\n        self.status_text = status_text\n        self.body = body\n\n\nclass BaseClient:\n    def __init__(self, base_url: str, headers: dict[str, str] | None = None):\n        self._base_url = base_url.rstrip(\"/\")\n        self._headers = headers or {}\n        self._http = httpx.AsyncClient()\n\n    async def _fetch(\n        self,\n        path: str,\n        *,\n        method: str,\n        body: Any = None,\n        params: dict | None = None,\n        extra_headers: dict | None = None,\n        content_type: str | None = None,\n        body_kind: str = \"json\",\n        response_kind: str = \"json\",\n    ) -> Any:\n        result, _ = await self._fetch_with_headers(\n            path,\n            method=method,\n            body=body,\n            params=params,\n            extra_headers=extra_headers,\n            content_type=content_type,\n            body_kind=body_kind,\n            response_kind=response_kind,\n        )\n        return result\n\n    async def _fetch_with_headers(\n        self,\n        path: str,\n        *,\n        method: str,\n        body: Any = None,\n        params: dict | None = None,\n        extra_headers: dict | None = None,\n        content_type: str | None = None,\n        body_kind: str = \"json\",\n        response_kind: str = \"json\",\n    ) -> tuple[Any, dict[str, str]]:\n        headers = {**self._headers, **(extra_headers or {})}\n        if body is not None:\n            headers[\"Content-Type\"] = content_type or \"application/json\"\n        # body_kind controls how httpx serializes the request body:\n        #   \"json\"   \u2014 body is a JSON-serializable object, sent via httpx's json= kwarg\n        #   \"text\"/\"binary\" \u2014 body is a raw str/bytes payload, sent via content= unchanged\n        request_kwargs: dict[str, Any] = {\"method\": method, \"url\": f\"{self._base_url}{path}\", \"params\": params, \"headers\": headers}\n        if body is not None:\n            if body_kind == \"json\":\n                request_kwargs[\"json\"] = body\n            else:\n                request_kwargs[\"content\"] = body\n        response = await self._http.request(**request_kwargs)\n        if not response.is_success:\n            try:\n                error_body = response.json()\n            except Exception:\n                error_body = response.text\n            raise SdkError(response.status_code, response.reason_phrase, error_body)\n        # HTTP headers are case-insensitive \u2014 normalize to lowercase keys for stable lookup.\n        response_headers = {k.lower(): v for k, v in response.headers.items()}\n        if response.status_code == 204 or not response.content:\n            return None, response_headers\n        if response_kind == \"text\":\n            return response.text, response_headers\n        if response_kind == \"binary\":\n            return response.content, response_headers\n        return response.json(), response_headers\n";
+export declare const BASE_CLIENT_PY = "# Auto-generated by contractkit-plugin-python-sdk. Do not edit manually.\nfrom __future__ import annotations\n\nimport httpx\nfrom typing import Any\n\n\nclass SdkError(Exception):\n    def __init__(self, status: int, status_text: str, body: Any):\n        super().__init__(f\"{status} {status_text}\")\n        self.status = status\n        self.status_text = status_text\n        self.body = body\n\n\nclass BaseClient:\n    def __init__(self, base_url: str, headers: dict[str, str] | None = None):\n        self._base_url = base_url.rstrip(\"/\")\n        self._headers = headers or {}\n        self._http = httpx.AsyncClient()\n        self._last_status = 0\n        self._last_content_type = \"\"\n\n    async def _fetch(\n        self,\n        path: str,\n        *,\n        method: str,\n        body: Any = None,\n        params: dict | None = None,\n        extra_headers: dict | None = None,\n        content_type: str | None = None,\n        body_kind: str = \"json\",\n        response_kind: str = \"json\",\n        expect_statuses: tuple[int, ...] = (),\n    ) -> Any:\n        result, _ = await self._fetch_with_headers(\n            path,\n            method=method,\n            body=body,\n            params=params,\n            extra_headers=extra_headers,\n            content_type=content_type,\n            body_kind=body_kind,\n            response_kind=response_kind,\n            expect_statuses=expect_statuses,\n        )\n        return result\n\n    async def _fetch_full(\n        self,\n        path: str,\n        *,\n        method: str,\n        body: Any = None,\n        params: dict | None = None,\n        extra_headers: dict | None = None,\n        content_type: str | None = None,\n        body_kind: str = \"json\",\n        response_kind: str = \"json\",\n        expect_statuses: tuple[int, ...] = (),\n    ) -> tuple[int, str, Any, dict[str, str]]:\n        \"\"\"Like _fetch_with_headers, but also reports the status and content type.\n\n        Used by operations that declare more than one status, or more than one mime for a\n        status, where the caller cannot know which it got without being told.\n        \"\"\"\n        result, headers = await self._fetch_with_headers(\n            path,\n            method=method,\n            body=body,\n            params=params,\n            extra_headers=extra_headers,\n            content_type=content_type,\n            body_kind=body_kind,\n            response_kind=response_kind,\n            expect_statuses=expect_statuses,\n        )\n        return self._last_status, self._last_content_type, result, headers\n\n    async def _fetch_with_headers(\n        self,\n        path: str,\n        *,\n        method: str,\n        body: Any = None,\n        params: dict | None = None,\n        extra_headers: dict | None = None,\n        content_type: str | None = None,\n        body_kind: str = \"json\",\n        response_kind: str = \"json\",\n        expect_statuses: tuple[int, ...] = (),\n    ) -> tuple[Any, dict[str, str]]:\n        headers = {**self._headers, **(extra_headers or {})}\n        if body is not None:\n            headers[\"Content-Type\"] = content_type or \"application/json\"\n        # body_kind controls how httpx serializes the request body:\n        #   \"json\"   \u2014 body is a JSON-serializable object, sent via httpx's json= kwarg\n        #   \"text\"/\"binary\" \u2014 body is a raw str/bytes payload, sent via content= unchanged\n        request_kwargs: dict[str, Any] = {\"method\": method, \"url\": f\"{self._base_url}{path}\", \"params\": params, \"headers\": headers}\n        if body is not None:\n            if body_kind == \"json\":\n                request_kwargs[\"json\"] = body\n            else:\n                request_kwargs[\"content\"] = body\n        response = await self._http.request(**request_kwargs)\n        # expect_statuses carries the codes this operation declares as values rather than\n        # errors \u2014 a 304 from conditional-GET middleware, or an error status the service\n        # returns deliberately. Anything else outside 2xx still raises.\n        if not response.is_success and response.status_code not in expect_statuses:\n            try:\n                error_body = response.json()\n            except Exception:\n                error_body = response.text\n            raise SdkError(response.status_code, response.reason_phrase, error_body)\n        # HTTP headers are case-insensitive \u2014 normalize to lowercase keys for stable lookup.\n        response_headers = {k.lower(): v for k, v in response.headers.items()}\n        self._last_status = response.status_code\n        self._last_content_type = response.headers.get(\"content-type\", \"\").split(\";\")[0].strip()\n        if response.status_code == 204 or not response.content:\n            return None, response_headers\n        # \"auto\" is for a status declaring several mimes that do not read the same way: the\n        # response itself is the only thing that knows which one came back.\n        kind = response_kind\n        if kind == \"auto\":\n            ct = self._last_content_type\n            if ct.startswith(\"text/\"):\n                kind = \"text\"\n            elif ct == \"application/json\" or ct.endswith(\"+json\"):\n                kind = \"json\"\n            else:\n                kind = \"binary\"\n        if kind == \"text\":\n            return response.text, response_headers\n        if kind == \"binary\":\n            return response.content, response_headers\n        return response.json(), response_headers\n";
 //# sourceMappingURL=codegen-client.d.ts.map

package/dist/codegen-client.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"codegen-client.d.ts","sourceRoot":"","sources":["../src/codegen-client.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAqF,MAAM,mBAAmB,CAAC;AAMvI,MAAM,WAAW,oBAAoB;IACjC,0EAA0E;IAC1E,gBAAgB,CAAC,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACvC,0FAA0F;IAC1F,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,kDAAkD;IAClD,eAAe,CAAC,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IAC9B;;;;OAIG;IACH,eAAe,CAAC,EAAE,OAAO,CAAC;CAC7B;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,UAAU,EAAE,eAAe,UAAQ,GAAG,OAAO,CAOtF;AAED;;GAEG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,UAAU,EAAE,IAAI,GAAE,oBAAyB,GAAG,MAAM,CA0G9F;AA2YD,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAE1D;AAED,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAQ3D;AAED,wBAAgB,wBAAwB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAG7D;AAmCD,eAAO,MAAM,cAAc,wuGAqF1B,CAAC"}
+{"version":3,"file":"codegen-client.d.ts","sourceRoot":"","sources":["../src/codegen-client.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACR,UAAU,EAQb,MAAM,mBAAmB,CAAC;AAqD3B,MAAM,WAAW,oBAAoB;IACjC,0EAA0E;IAC1E,gBAAgB,CAAC,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACvC,0FAA0F;IAC1F,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,kDAAkD;IAClD,eAAe,CAAC,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IAC9B;;;;OAIG;IACH,eAAe,CAAC,EAAE,OAAO,CAAC;CAC7B;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,UAAU,EAAE,eAAe,UAAQ,GAAG,OAAO,CAOtF;AAED;;GAEG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,UAAU,EAAE,IAAI,GAAE,oBAAyB,GAAG,MAAM,CA+I9F;AAgfD,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAE1D;AAED,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAQ3D;AAED,wBAAgB,wBAAwB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAG7D;AAmCD,eAAO,MAAM,cAAc,6+KAyI1B,CAAC"}

package/dist/index.js

@@ -386,7 +386,50 @@ function deriveModelsModuleName(file) {
 __name(deriveModelsModuleName, "deriveModelsModuleName");
 
 // src/codegen-client.ts
-import { resolveModifiers, classifyContentType } from "@contractkit/core";
+import { resolveModifiers, classifyContentType, observableResponses } from "@contractkit/core";
+function headersClassName(methodBase, statusCode) {
+  return statusCode === void 0 ? `${methodBase}Headers` : `${methodBase}${statusCode}Headers`;
+}
+__name(headersClassName, "headersClassName");
+function responseClassName(methodBase, statusCode) {
+  return statusCode === void 0 ? `${methodBase}Response` : `${methodBase}${statusCode}Response`;
+}
+__name(responseClassName, "responseClassName");
+function pyBodyType(body, modelsWithInput) {
+  const category = classifyContentType(body.contentType);
+  if (category === "text") return "str";
+  if (category === "binary") return "bytes";
+  return renderPyType(body.bodyType, modelsWithInput);
+}
+__name(pyBodyType, "pyBodyType");
+function pyDataAnnotation(bodies, modelsWithInput) {
+  const types = [
+    ...new Set(bodies.map((b) => pyBodyType(b, modelsWithInput)))
+  ];
+  return types.join(" | ");
+}
+__name(pyDataAnnotation, "pyDataAnnotation");
+function pyContentTypeAnnotation(bodies) {
+  return `Literal[${bodies.map((b) => JSON.stringify(b.contentType)).join(", ")}]`;
+}
+__name(pyContentTypeAnnotation, "pyContentTypeAnnotation");
+function responseShape(op) {
+  const observable = observableResponses(op);
+  if (observable.length > 1) return {
+    kind: "multiStatus",
+    responses: observable
+  };
+  const resp = observable[0];
+  if (resp && resp.bodies.length > 1) return {
+    kind: "multiMime",
+    resp
+  };
+  return {
+    kind: "simple",
+    resp
+  };
+}
+__name(responseShape, "responseShape");
 function hasPublicOperations(root, includeInternal = false) {
   for (const route of root.routes) {
     for (const op of route.operations) {
@@ -428,14 +471,23 @@ function generatePythonClient(root, opts = {}) {
       });
     }
   }
+  const opShapes = new Map(publicOps.map(({ op }) => [
+    op,
+    responseShape(op)
+  ]));
   const opsWithRespHeaders = publicOps.filter(({ op }) => {
-    const primary = op.responses.find((r) => r.bodyType) ?? op.responses[0];
-    return (primary?.headers?.length ?? 0) > 0;
+    const shape = opShapes.get(op);
+    if (shape.kind === "multiStatus") return shape.responses.some((r) => (r.headers?.length ?? 0) > 0);
+    return (shape.resp?.headers?.length ?? 0) > 0;
   });
-  if (needsAny || opsWithRespHeaders.length > 0) {
+  const opsWithResponseDict = publicOps.filter(({ op }) => opShapes.get(op).kind !== "simple");
+  const needsTypedDict = opsWithRespHeaders.length > 0 || opsWithResponseDict.length > 0;
+  const needsLiteral = opsWithResponseDict.length > 0;
+  if (needsAny || needsTypedDict) {
     const typingImports = [];
     if (needsAny) typingImports.push("Any");
-    if (opsWithRespHeaders.length > 0) typingImports.push("TypedDict");
+    if (needsLiteral) typingImports.push("Literal");
+    if (needsTypedDict) typingImports.push("TypedDict");
     lines.push(`from typing import ${typingImports.join(", ")}`);
   }
   lines.push("from ._base_client import BaseClient, SdkError  # noqa: F401");
@@ -461,15 +513,50 @@ function generatePythonClient(root, opts = {}) {
     lines.push(`from ${mod} import ${sorted}`);
   }
   for (const { route, op } of opsWithRespHeaders) {
-    const primary = op.responses.find((r) => r.bodyType) ?? op.responses[0];
-    const className = `${snakeToPascal(deriveMethodName(op, route))}Headers`;
-    lines.push("");
-    lines.push("");
-    lines.push(`class ${className}(TypedDict, total=False):`);
-    for (const h of primary.headers) {
-      const pyName = toPythonFieldName(h.name);
-      const tag = h.optional ? "optional" : "required";
-      lines.push(`    ${pyName}: str  # ${h.name} (${tag})`);
+    const shape = opShapes.get(op);
+    const base = snakeToPascal(deriveMethodName(op, route));
+    const targets = shape.kind === "multiStatus" ? shape.responses.filter((r) => (r.headers?.length ?? 0) > 0).map((r) => ({
+      name: headersClassName(base, r.statusCode),
+      resp: r
+    })) : [
+      {
+        name: headersClassName(base),
+        resp: shape.resp
+      }
+    ];
+    for (const { name, resp } of targets) {
+      lines.push("");
+      lines.push("");
+      lines.push(`class ${name}(TypedDict, total=False):`);
+      for (const h of resp.headers) {
+        const pyName = toPythonFieldName(h.name);
+        const tag = h.optional ? "optional" : "required";
+        lines.push(`    ${pyName}: str  # ${h.name} (${tag})`);
+      }
+    }
+  }
+  for (const { route, op } of opsWithResponseDict) {
+    const shape = opShapes.get(op);
+    const base = snakeToPascal(deriveMethodName(op, route));
+    const targets = shape.kind === "multiStatus" ? shape.responses : shape.kind === "multiMime" ? [
+      shape.resp
+    ] : [];
+    for (const resp of targets) {
+      lines.push("");
+      lines.push("");
+      lines.push(`class ${responseClassName(base, shape.kind === "multiStatus" ? resp.statusCode : void 0)}(TypedDict):`);
+      if (shape.kind === "multiStatus") lines.push(`    status: Literal[${resp.statusCode}]`);
+      const bodies = resp.bodies;
+      if (bodies.length > 0) {
+        lines.push(`    content_type: ${pyContentTypeAnnotation(bodies)}`);
+        lines.push(`    data: ${pyDataAnnotation(bodies, opts.modelsWithInput)}`);
+      }
+      if ((resp.headers?.length ?? 0) > 0) {
+        lines.push(`    headers: ${headersClassName(base, shape.kind === "multiStatus" ? resp.statusCode : void 0)}`);
+      }
+      if (shape.kind !== "multiStatus" && bodies.length === 0 && (resp.headers?.length ?? 0) === 0) {
+        lines.push("    pass");
+      }
     }
   }
   lines.push("");
@@ -505,16 +592,19 @@ function generateMethod(route, op, opts) {
     return `${p.name}: ${p.type}`;
   });
   const paramStr = allParams.length > 0 ? `, ${allParams.join(", ")}` : "";
-  const primaryResponse = op.responses.find((r) => r.bodyType) ?? op.responses[0];
-  const isVoid = !primaryResponse?.bodyType;
-  const respCategory = primaryResponse?.contentType ? classifyContentType(primaryResponse.contentType) : "json";
-  const dataType = isVoid ? "None" : respCategory === "text" ? "str" : respCategory === "binary" ? "bytes" : renderPyType(primaryResponse.bodyType, modelsWithInput);
-  const isModelReturn = !isVoid && respCategory === "json" && isModelRef(primaryResponse.bodyType, modelsWithInput);
-  const isListModelReturn = !isVoid && respCategory === "json" && isListModelRef(primaryResponse.bodyType, modelsWithInput);
+  const shape = responseShape(op);
+  const methodBase = snakeToPascal(methodName);
+  const primaryResponse = shape.kind === "multiStatus" ? void 0 : shape.resp;
+  const primaryBodies = primaryResponse ? primaryResponse.bodies : [];
+  const isVoid = primaryBodies.length === 0;
+  const respCategory = primaryBodies[0] ? classifyContentType(primaryBodies[0].contentType) : "json";
+  const dataType = isVoid ? "None" : pyBodyType(primaryBodies[0], modelsWithInput);
+  const isModelReturn = !isVoid && respCategory === "json" && isModelRef(primaryBodies[0].bodyType, modelsWithInput);
+  const isListModelReturn = !isVoid && respCategory === "json" && isListModelRef(primaryBodies[0].bodyType, modelsWithInput);
   const respHeaders = primaryResponse?.headers ?? [];
   const hasRespHeaders = respHeaders.length > 0;
-  const headersTypeName = hasRespHeaders ? `${snakeToPascal(methodName)}Headers` : "";
-  const returnType = hasRespHeaders ? isVoid ? headersTypeName : `tuple[${dataType}, ${headersTypeName}]` : dataType;
+  const headersTypeName = hasRespHeaders ? headersClassName(methodBase) : "";
+  const returnType = shape.kind === "multiStatus" ? shape.responses.map((r) => responseClassName(methodBase, r.statusCode)).join(" | ") : shape.kind === "multiMime" ? responseClassName(methodBase) : hasRespHeaders ? isVoid ? headersTypeName : `tuple[${dataType}, ${headersTypeName}]` : dataType;
   const desc = op.description ?? route.description;
   if (op.name || desc) {
     lines.push(`    async def ${methodName}(${selfParam}${paramStr}) -> ${returnType}:`);
@@ -552,9 +642,19 @@ function generateMethod(route, op, opts) {
       fetchKwargs.push(`body_kind="${reqCategory}"`);
     }
   }
-  if (respCategory === "text" || respCategory === "binary") {
+  if (shape.kind !== "simple") {
+    fetchKwargs.push(`response_kind="auto"`);
+  } else if (respCategory === "text" || respCategory === "binary") {
     fetchKwargs.push(`response_kind="${respCategory}"`);
   }
+  const observable = shape.kind === "multiStatus" ? shape.responses : shape.resp ? [
+    shape.resp
+  ] : [];
+  const expectStatuses = observable.filter((r) => r.statusCode < 200 || r.statusCode >= 300).map((r) => r.statusCode);
+  if (expectStatuses.length > 0) {
+    const tuple = expectStatuses.length === 1 ? `(${expectStatuses[0]},)` : `(${expectStatuses.join(", ")})`;
+    fetchKwargs.push(`expect_statuses=${tuple}`);
+  }
   if (hasQuery) {
     fetchKwargs.push("params=query");
   }
@@ -562,6 +662,11 @@ function generateMethod(route, op, opts) {
     fetchKwargs.push("extra_headers=custom_headers");
   }
   const kwargsStr = fetchKwargs.length > 1 ? fetchKwargs.join(", ") : fetchKwargs[0] ?? "";
+  if (shape.kind !== "simple") {
+    lines.push(`        _status, _content_type, result, _response_headers = await self._fetch_full(${urlExpr}, ${kwargsStr})`);
+    lines.push(...buildMultiReturnLines(shape, methodBase, modelsWithInput));
+    return lines;
+  }
   if (hasRespHeaders) {
     lines.push(`        result, _response_headers = await self._fetch_with_headers(${urlExpr}, ${kwargsStr})`);
     lines.push(...buildHeadersDictLines(respHeaders, headersTypeName));
@@ -577,7 +682,7 @@ function generateMethod(route, op, opts) {
   } else {
     let dataExpr;
     if (isListModelReturn) {
-      const innerType = getListItemType(primaryResponse.bodyType, modelsWithInput);
+      const innerType = getListItemType(primaryBodies[0].bodyType, modelsWithInput);
       dataExpr = `[${innerType}.model_validate(item) for item in result]`;
     } else if (isModelReturn) {
       dataExpr = `${dataType}.model_validate(result)`;
@@ -593,13 +698,71 @@ function generateMethod(route, op, opts) {
   return lines;
 }
 __name(generateMethod, "generateMethod");
-function buildHeadersDictLines(headers, typeName) {
+function pyDataExpr(body, modelsWithInput) {
+  if (classifyContentType(body.contentType) !== "json") return "result";
+  if (isListModelRef(body.bodyType, modelsWithInput)) {
+    return `[${getListItemType(body.bodyType, modelsWithInput)}.model_validate(item) for item in result]`;
+  }
+  if (isModelRef(body.bodyType, modelsWithInput)) {
+    return `${renderPyType(body.bodyType, modelsWithInput)}.model_validate(result)`;
+  }
+  return "result";
+}
+__name(pyDataExpr, "pyDataExpr");
+function buildMultiReturnLines(shape, methodBase, modelsWithInput) {
+  const lines = [];
+  const returnFor = /* @__PURE__ */ __name((resp, body, indent, includeStatus, headersVar) => {
+    const entries = [];
+    if (includeStatus) entries.push(`"status": ${resp.statusCode}`);
+    if (body) {
+      entries.push(`"content_type": ${JSON.stringify(body.contentType)}`);
+      entries.push(`"data": ${pyDataExpr(body, modelsWithInput)}`);
+    }
+    if (headersVar) entries.push(`"headers": ${headersVar}`);
+    return [
+      `${indent}return {${entries.length > 0 ? ` ${entries.join(", ")} ` : ""}}`
+    ];
+  }, "returnFor");
+  const emitStatus = /* @__PURE__ */ __name((resp, indent, includeStatus) => {
+    const out = [];
+    let headersVar;
+    if ((resp.headers?.length ?? 0) > 0) {
+      headersVar = includeStatus ? `headers_${resp.statusCode}` : "headers";
+      const typeName = headersClassName(methodBase, includeStatus ? resp.statusCode : void 0);
+      out.push(...buildHeadersDictLines(resp.headers, typeName, indent, headersVar));
+    }
+    const bodies = resp.bodies;
+    if (bodies.length <= 1) {
+      out.push(...returnFor(resp, bodies[0], indent, includeStatus, headersVar));
+      return out;
+    }
+    for (const body of bodies.slice(1)) {
+      out.push(`${indent}if _content_type == ${JSON.stringify(body.contentType)}:`);
+      out.push(...returnFor(resp, body, `${indent}    `, includeStatus, headersVar));
+    }
+    out.push(...returnFor(resp, bodies[0], indent, includeStatus, headersVar));
+    return out;
+  }, "emitStatus");
+  if (shape.kind === "multiMime") {
+    lines.push(...emitStatus(shape.resp, "        ", false));
+    return lines;
+  }
+  const [fallback, ...rest] = shape.responses;
+  for (const resp of rest) {
+    lines.push(`        if _status == ${resp.statusCode}:`);
+    lines.push(...emitStatus(resp, "            ", true));
+  }
+  lines.push(...emitStatus(fallback, "        ", true));
+  return lines;
+}
+__name(buildMultiReturnLines, "buildMultiReturnLines");
+function buildHeadersDictLines(headers, typeName, indent = "        ", varName = "headers") {
   const lines = [];
-  lines.push(`        headers: ${typeName} = {}`);
+  lines.push(`${indent}${varName}: ${typeName} = {}`);
   for (const h of headers) {
     const pyName = toPythonFieldName(h.name);
-    lines.push(`        if ${JSON.stringify(h.name.toLowerCase())} in _response_headers:`);
-    lines.push(`            headers[${JSON.stringify(pyName)}] = _response_headers[${JSON.stringify(h.name.toLowerCase())}]`);
+    lines.push(`${indent}if ${JSON.stringify(h.name.toLowerCase())} in _response_headers:`);
+    lines.push(`${indent}    ${varName}[${JSON.stringify(pyName)}] = _response_headers[${JSON.stringify(h.name.toLowerCase())}]`);
   }
   return lines;
 }
@@ -743,7 +906,7 @@ function collectReferencedModels(root, modelsWithInput, includeInternal = false)
         for (const body of op.request.bodies) collectTypeRefs(body.bodyType, refs, modelsWithInput, true);
       }
       for (const resp of op.responses) {
-        if (resp.bodyType) collectTypeRefs(resp.bodyType, refs, modelsWithInput, false);
+        for (const body of resp.bodies) collectTypeRefs(body.bodyType, refs, modelsWithInput, false);
       }
       if (op.query) collectParamSourceRefs(op.query, refs, modelsWithInput);
       if (op.headers) collectParamSourceRefs(op.headers, refs, modelsWithInput);
@@ -893,6 +1056,8 @@ class BaseClient:
         self._base_url = base_url.rstrip("/")
         self._headers = headers or {}
         self._http = httpx.AsyncClient()
+        self._last_status = 0
+        self._last_content_type = ""
 
     async def _fetch(
         self,
@@ -905,6 +1070,7 @@ class BaseClient:
         content_type: str | None = None,
         body_kind: str = "json",
         response_kind: str = "json",
+        expect_statuses: tuple[int, ...] = (),
     ) -> Any:
         result, _ = await self._fetch_with_headers(
             path,
@@ -915,9 +1081,41 @@ class BaseClient:
             content_type=content_type,
             body_kind=body_kind,
             response_kind=response_kind,
+            expect_statuses=expect_statuses,
         )
         return result
 
+    async def _fetch_full(
+        self,
+        path: str,
+        *,
+        method: str,
+        body: Any = None,
+        params: dict | None = None,
+        extra_headers: dict | None = None,
+        content_type: str | None = None,
+        body_kind: str = "json",
+        response_kind: str = "json",
+        expect_statuses: tuple[int, ...] = (),
+    ) -> tuple[int, str, Any, dict[str, str]]:
+        """Like _fetch_with_headers, but also reports the status and content type.
+
+        Used by operations that declare more than one status, or more than one mime for a
+        status, where the caller cannot know which it got without being told.
+        """
+        result, headers = await self._fetch_with_headers(
+            path,
+            method=method,
+            body=body,
+            params=params,
+            extra_headers=extra_headers,
+            content_type=content_type,
+            body_kind=body_kind,
+            response_kind=response_kind,
+            expect_statuses=expect_statuses,
+        )
+        return self._last_status, self._last_content_type, result, headers
+
     async def _fetch_with_headers(
         self,
         path: str,
@@ -929,6 +1127,7 @@ class BaseClient:
         content_type: str | None = None,
         body_kind: str = "json",
         response_kind: str = "json",
+        expect_statuses: tuple[int, ...] = (),
     ) -> tuple[Any, dict[str, str]]:
         headers = {**self._headers, **(extra_headers or {})}
         if body is not None:
@@ -943,7 +1142,10 @@ class BaseClient:
             else:
                 request_kwargs["content"] = body
         response = await self._http.request(**request_kwargs)
-        if not response.is_success:
+        # expect_statuses carries the codes this operation declares as values rather than
+        # errors \u2014 a 304 from conditional-GET middleware, or an error status the service
+        # returns deliberately. Anything else outside 2xx still raises.
+        if not response.is_success and response.status_code not in expect_statuses:
             try:
                 error_body = response.json()
             except Exception:
@@ -951,11 +1153,24 @@ class BaseClient:
             raise SdkError(response.status_code, response.reason_phrase, error_body)
         # HTTP headers are case-insensitive \u2014 normalize to lowercase keys for stable lookup.
         response_headers = {k.lower(): v for k, v in response.headers.items()}
+        self._last_status = response.status_code
+        self._last_content_type = response.headers.get("content-type", "").split(";")[0].strip()
         if response.status_code == 204 or not response.content:
             return None, response_headers
-        if response_kind == "text":
+        # "auto" is for a status declaring several mimes that do not read the same way: the
+        # response itself is the only thing that knows which one came back.
+        kind = response_kind
+        if kind == "auto":
+            ct = self._last_content_type
+            if ct.startswith("text/"):
+                kind = "text"
+            elif ct == "application/json" or ct.endswith("+json"):
+                kind = "json"
+            else:
+                kind = "binary"
+        if kind == "text":
             return response.text, response_headers
-        if response_kind == "binary":
+        if kind == "binary":
             return response.content, response_headers
         return response.json(), response_headers
 `;
@@ -1176,7 +1391,7 @@ function collectOpRootModelRefs(root, modelMap) {
         for (const body of op.request.bodies) seeds.push(body.bodyType);
       }
       for (const resp of op.responses) {
-        if (resp.bodyType) seeds.push(resp.bodyType);
+        for (const body of resp.bodies) seeds.push(body.bodyType);
         if (resp.headers) {
           for (const h of resp.headers) seeds.push(h.type);
         }