[python] support custom wire names for etags defined with Azure.Core.eTag (#10494)

## Problem

Custom etag-typed headers (e.g. `x-ms-if-blob-match`,
`x-ms-if-blob-none-match`) were being assigned to the wrong
if-match/if-none-match slot during preprocessing. The slot assignment
and the per-parameter conversion used different logic to classify
headers, and synthetic partners inherited incorrect wire names.

## Changes

- **Added `_etag_kind()` helper** — centralizes etag classification
using `none-match` substring (stricter than the previous `none` check
which could false-positive on unrelated headers)
- **Fixed slot assignment** — uses `_etag_kind()` to correctly classify
custom etag headers before pairing
- **Fixed synthetic partner creation** — strips `isEtag` from synthetic
clones to prevent re-conversion with wrong `originalWireName`, falls
back to standard `If-Match`/`If-None-Match` wire names
- **Unified classification** — both slot assignment and per-parameter
conversion now use the same `_etag_kind()` logic

---------

Co-authored-by: iscai-msft <isabellavcai@gmail.com>
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: 3 people

.chronus/changes/python-etagMatchCondition-2026-04-27-13-33-08.md

@@ -0,0 +1,7 @@
+---
+changeKind: fix
+packages:
+  - "@typespec/http-client-python"
+---
+
+Support custom wire names for etags defined with `Azure.Core.eTag` (e.g. `x-ms-blob-if-match`)

packages/http-client-python/emitter/src/http.ts

@@ -1,4 +1,4 @@
-import { NoTarget } from "@typespec/compiler";
+import { getNamespaceFullName, NoTarget } from "@typespec/compiler";
 
 import {
   getHttpOperationParameter,
@@ -19,6 +19,7 @@ import {
   SdkQueryParameter,
   SdkServiceMethod,
   SdkServiceResponseHeader,
+  SdkType,
   UsageFlags,
 } from "@azure-tools/typespec-client-generator-core";
 import { HttpStatusCodeRange } from "@typespec/http";
@@ -41,6 +42,32 @@ export enum ReferredByOperationTypes {
   NonPagingOnly = 2,
 }
 
+function isEtagType(type: SdkType): boolean {
+  if (type.kind === "nullable") return isEtagType(type.type);
+  const raw = type.__raw;
+  if (!raw || raw.kind !== "Scalar") return false;
+  return (
+    raw.name === "eTag" &&
+    raw.namespace !== undefined &&
+    getNamespaceFullName(raw.namespace) === "Azure.Core"
+  );
+}
+
+function getEtagRole(parameter: SdkHeaderParameter): string | undefined {
+  const name = parameter.name.toLowerCase();
+  const wire = parameter.serializedName.toLowerCase();
+  // Standard If-Match / If-None-Match headers work with any type
+  if (wire === "if-match") return "ifMatch";
+  if (wire === "if-none-match") return "ifNoneMatch";
+  // Non-standard headers require Azure.Core.eTag type
+  if (!isEtagType(parameter.type)) return undefined;
+  if (name.includes("nonematch") || name.includes("none_match")) return "ifNoneMatch";
+  if (name.includes("match")) return "ifMatch";
+  if (wire.endsWith("-if-none-match")) return "ifNoneMatch";
+  if (wire.endsWith("-if-match")) return "ifMatch";
+  return undefined;
+}
+
 function isContentTypeParameter(parameter: SdkHeaderParameter) {
   return parameter.serializedName.toLowerCase() === "content-type";
 }
@@ -496,6 +523,7 @@ function emitHttpHeaderParameter(
     delimiter,
     explode,
     clientDefaultValue,
+    etagRole: getEtagRole(parameter),
   };
 }
 

packages/http-client-python/generator/pygen/codegen/models/parameter.py

@@ -61,6 +61,7 @@ def __init__(
     ) -> None:
         super().__init__(yaml_data, code_model)
         self.wire_name: str = yaml_data.get("wireName", "")
+        self.etag_role: Optional[str] = yaml_data.get("etagRole", None)
         self.client_name: str = self.yaml_data["clientName"]
         self.optional: bool = self.yaml_data["optional"]
         self.implementation: Optional[str] = yaml_data.get("implementation", None)

packages/http-client-python/generator/pygen/codegen/serializers/parameter_serializer.py

@@ -39,16 +39,6 @@ class PopKwargType(Enum):
     "client-request-id": [],
     "x-ms-client-request-id": [],
     "return-client-request-id": [],
-    "etag": [
-        """if_match = prep_if_match(etag, match_condition)""",
-        """if if_match is not None:""",
-        """    _headers["If-Match"] = _SERIALIZER.header("if_match", if_match, "str")""",
-    ],
-    "match-condition": [
-        """if_none_match = prep_if_none_match(etag, match_condition)""",
-        """if if_none_match is not None:""",
-        """    _headers["If-None-Match"] = _SERIALIZER.header("if_none_match", if_none_match, "str")""",
-    ],
 }
 
 
@@ -157,6 +147,20 @@ def serialize_query_header(
         ):
             return SPECIAL_HEADER_SERIALIZATION[param.wire_name.lower()]
 
+        if not is_legacy and param.location == ParameterLocation.HEADER and param.etag_role is not None:
+            header_name = param.wire_name
+            if param.etag_role == "ifMatch":
+                return [
+                    """if_match = prep_if_match(etag, match_condition)""",
+                    """if if_match is not None:""",
+                    f"""    _headers["{header_name}"] = _SERIALIZER.header("if_match", if_match, "str")""",
+                ]
+            return [
+                """if_none_match = prep_if_none_match(etag, match_condition)""",
+                """if if_none_match is not None:""",
+                f"""    _headers["{header_name}"] = _SERIALIZER.header("if_none_match", if_none_match, "str")""",
+            ]
+
         set_parameter = "_{}['{}'] = {}".format(
             kwarg_name,
             param.wire_name,

packages/http-client-python/generator/pygen/preprocess/__init__.py

@@ -132,20 +132,18 @@ def update_paging_response(yaml_data: dict[str, Any]) -> None:
     "client-request-id",
     "return-client-request-id",
 )
-HEADERS_CONVERT_IN_METHOD = {
-    "if-match": {
-        "clientName": "etag",
-        "wireName": "etag",
-        "description": "check if resource is changed. Set None to skip checking etag.",
-    },
-    "if-none-match": {
-        "clientName": "match_condition",
-        "wireName": "match-condition",
-        "description": "The match condition to use upon the etag.",
-        "type": {
-            "type": "sdkcore",
-            "name": "MatchConditions",
-        },
+ETAG_MATCH_DATA = {
+    "clientName": "etag",
+    "etagRole": "ifMatch",
+    "description": "check if resource is changed. Set None to skip checking etag.",
+}
+ETAG_NONE_MATCH_DATA = {
+    "clientName": "match_condition",
+    "etagRole": "ifNoneMatch",
+    "description": "The match condition to use upon the etag.",
+    "type": {
+        "type": "sdkcore",
+        "name": "MatchConditions",
     },
 }
 CLOUD_SETTING = {
@@ -166,6 +164,11 @@ def get_wire_name_lower(parameter: dict[str, Any]) -> str:
     return (parameter.get("wireName") or "").lower()
 
 
+def _get_etag_role(parameter: dict[str, Any]) -> Optional[str]:
+    """Return 'ifMatch', 'ifNoneMatch', or None for this header parameter."""
+    return parameter.get("etagRole")
+
+
 def headers_convert(yaml_data: dict[str, Any], replace_data: Any) -> None:
     if isinstance(replace_data, dict):
         for k, v in replace_data.items():
@@ -281,9 +284,8 @@ def update_types(self, yaml_data: list[dict[str, Any]]) -> None:
                         value["name"] = upper_name
 
         # add type for reference
-        for v in HEADERS_CONVERT_IN_METHOD.values():
-            if isinstance(v, dict) and "type" in v:
-                yaml_data.append(v["type"])
+        if "type" in ETAG_NONE_MATCH_DATA:
+            yaml_data.append(ETAG_NONE_MATCH_DATA["type"])
         yaml_data.append(CLOUD_SETTING["type"])  # type: ignore
 
     def update_client(self, yaml_data: dict[str, Any]) -> None:
@@ -317,27 +319,30 @@ def update_client(self, yaml_data: dict[str, Any]) -> None:
                     if p["location"] == "header" and wire_name_lower == "client-request-id":
                         yaml_data["requestIdHeaderName"] = wire_name_lower
                     if self.version_tolerant and p["location"] == "header":
-                        if wire_name_lower == "if-match":
+                        role = _get_etag_role(p)
+                        if role == "ifMatch" and not property_if_match:
                             property_if_match = p
-                        elif wire_name_lower == "if-none-match":
+                        elif role == "ifNoneMatch" and not property_if_none_match:
                             property_if_none_match = p
                 # pylint: disable=line-too-long
                 # some service(e.g. https://github.com/Azure/azure-rest-api-specs/blob/main/specification/cosmos-db/data-plane/Microsoft.Tables/preview/2019-02-02/table.json)
                 # only has one, so we need to add "if-none-match" or "if-match" if it's missing
                 if not property_if_match and property_if_none_match:
                     property_if_match = property_if_none_match.copy()
                     property_if_match["wireName"] = "if-match"
+                    property_if_match["etagRole"] = "ifMatch"
                 if not property_if_none_match and property_if_match:
                     property_if_none_match = property_if_match.copy()
                     property_if_none_match["wireName"] = "if-none-match"
+                    property_if_none_match["etagRole"] = "ifNoneMatch"
 
                 if property_if_match and property_if_none_match:
                     # arrange if-match and if-none-match to the end of parameters
-                    o["parameters"] = [
-                        item
-                        for item in o["parameters"]
-                        if get_wire_name_lower(item) not in ("if-match", "if-none-match")
-                    ] + [property_if_match, property_if_none_match]
+                    etag_params = {id(property_if_match), id(property_if_none_match)}
+                    o["parameters"] = [item for item in o["parameters"] if id(item) not in etag_params] + [
+                        property_if_match,
+                        property_if_none_match,
+                    ]
 
                     o["hasEtag"] = True
                     yaml_data["hasEtag"] = True
@@ -372,8 +377,12 @@ def update_parameter(self, yaml_data: dict[str, Any]) -> None:
             wire_name_lower in HEADERS_HIDE_IN_METHOD or yaml_data.get("clientDefaultValue") == "multipart/form-data"
         ):
             yaml_data["hideInMethod"] = True
-        if self.version_tolerant and yaml_data["location"] == "header" and wire_name_lower in HEADERS_CONVERT_IN_METHOD:
-            headers_convert(yaml_data, HEADERS_CONVERT_IN_METHOD[wire_name_lower])
+        if self.version_tolerant and yaml_data["location"] == "header":
+            role = _get_etag_role(yaml_data)
+            if role == "ifMatch":
+                headers_convert(yaml_data, ETAG_MATCH_DATA)
+            elif role == "ifNoneMatch":
+                headers_convert(yaml_data, ETAG_NONE_MATCH_DATA)
         if wire_name_lower in ["$host", "content-type", "accept"] and yaml_data["type"]["type"] == "constant":
             yaml_data["clientDefaultValue"] = yaml_data["type"]["value"]