@typespec/http-client-python 0.34.2 → 0.35.1

package/eng/scripts/ci/config/pylintrc

@@ -16,8 +16,12 @@ enable=useless-suppression
 # cyclic-import: because of https://github.com/PyCQA/pylint/issues/850
 # too-many-arguments: Due to the nature of the CLI many commands have large arguments set which reflect in large arguments set in corresponding methods.
 # too-many-lines: Due to code generation many files end up with too many lines.
+# no-cross-package-private-import: The guideline checker does not resolve relative
+#   imports (it ignores the import level), so legitimate same-package relative imports
+#   like `from ...operations._operations import ...` in generated async code are
+#   misreported as cross-package private imports.
 # Let's black deal with bad-continuation
-disable=missing-docstring,locally-disabled,fixme,cyclic-import,too-many-arguments,invalid-name,duplicate-code,too-few-public-methods,consider-using-f-string,super-with-arguments,redefined-builtin,import-outside-toplevel,client-suffix-needed,unnecessary-dunder-call,unnecessary-ellipsis,disallowed-name,consider-using-max-builtin,unknown-option-value,file-needs-copyright-header,too-many-positional-arguments
+disable=missing-docstring,locally-disabled,fixme,cyclic-import,too-many-arguments,invalid-name,duplicate-code,too-few-public-methods,consider-using-f-string,super-with-arguments,redefined-builtin,import-outside-toplevel,client-suffix-needed,unnecessary-dunder-call,unnecessary-ellipsis,disallowed-name,consider-using-max-builtin,unknown-option-value,file-needs-copyright-header,too-many-positional-arguments,no-cross-package-private-import
 
 [FORMAT]
 max-line-length=120

package/eng/scripts/ci/dev_requirements.txt

@@ -1,8 +1,8 @@
-pyright==1.1.407
-pylint==4.0.4
+pyright==1.1.411
+pylint==4.0.6
 tox==4.16.0
 tox-uv
-mypy==1.19.1
+mypy==2.1.0
 colorama==0.4.6
 debugpy==1.8.2
 pytest==9.0.3

package/eng/scripts/ci/regenerate-common.ts

@@ -16,8 +16,7 @@
 import { compile, NodeHost } from "@typespec/compiler";
 import { execSync } from "child_process";
 import { existsSync, rmSync } from "fs";
-import { access, cp, mkdir, mkdtemp, readdir, writeFile } from "fs/promises";
-import { tmpdir } from "os";
+import { access, mkdir, readdir, writeFile } from "fs/promises";
 import { dirname, join, relative, resolve } from "path";
 import pc from "picocolors";
 
@@ -184,6 +183,9 @@ export const AZURE_EMITTER_OPTIONS: Record<
   "client/overload": {
     namespace: "client.overload",
   },
+  "encode/boolean": {
+    namespace: "encode.boolean",
+  },
   "encode/duration": {
     namespace: "encode.duration",
   },
@@ -652,6 +654,28 @@ export async function runParallel(
   return results;
 }
 
+/**
+ * Removes every generated file under `tests/generated`, keeping only the
+ * hand-authored files that are tracked in git. `git clean -xdf` deletes ignored
+ * and untracked files but never tracked ones, so `.gitignore` stays the single
+ * source of truth for which fixtures survive regeneration (each exception there
+ * documents why it cannot be regenerated).
+ */
+export async function cleanGeneratedCode(generatedFolder: string): Promise<void> {
+  const repoDir = resolve(generatedFolder, "..");
+  const testsGeneratedDir = resolve(repoDir, "tests/generated");
+  if (!existsSync(testsGeneratedDir)) return;
+
+  console.log(pc.cyan(`\n${"=".repeat(60)}`));
+  console.log(pc.cyan(`Cleaning generated test packages`));
+  console.log(pc.cyan(`${"=".repeat(60)}\n`));
+
+  execSync(`git clean -x -d -f -q -- "${testsGeneratedDir}"`, {
+    cwd: repoDir,
+    stdio: ["ignore", "inherit", "inherit"],
+  });
+}
+
 /**
  * Pre-create the marker files that the test harness expects to find before
  * regeneration so it can verify they're cleared/preserved correctly.
@@ -695,99 +719,3 @@ export async function preprocess(flavor: string, generatedFolder: string): Promi
     }),
   );
 }
-
-/**
- * Resets the `tests/generated/{azure,unbranded}` baseline by sparse-checking-out
- * `eng/tools/azure-sdk-tools/emitter/generated` from the Azure/azure-sdk-for-python repo, then
- * deleting a couple of fully-generated package folders so regeneration has to
- * recreate them from scratch (smoke test of full-emit path).
- *
- * `generatedFolder` is the per-repo `generator/` directory; baseline lands at
- * `<generatedFolder>/../tests/generated`.
- */
-export async function prepareBaselineOfGeneratedCode(generatedFolder: string): Promise<void> {
-  const repoUrl = "https://github.com/Azure/azure-sdk-for-python.git";
-  const branch = "typespec-python-generated-tests";
-  const sourceSubdir = "eng/tools/azure-sdk-tools/emitter/generated";
-  const testsGeneratedDir = resolve(generatedFolder, "../tests/generated");
-
-  console.log(pc.cyan(`\n${"=".repeat(60)}`));
-  console.log(pc.cyan(`Resetting baseline from ${repoUrl} (${branch}/${sourceSubdir})`));
-  console.log(pc.cyan(`${"=".repeat(60)}\n`));
-
-  // Wipe tests/generated
-  if (existsSync(testsGeneratedDir)) {
-    console.log(pc.dim(`Removing ${testsGeneratedDir}`));
-    rmSync(testsGeneratedDir, { recursive: true, force: true });
-  }
-
-  // Sparse-checkout the baseline folder into a temp directory
-  const tempDir = await mkdtemp(join(tmpdir(), "azsdk-baseline-"));
-  try {
-    console.log(pc.dim(`Cloning into ${tempDir}`));
-    const run = (cmd: string) =>
-      execSync(cmd, { cwd: tempDir, stdio: ["ignore", "ignore", "inherit"] });
-
-    run(`git init`);
-    run(`git config core.longpaths true`);
-    run(`git remote add origin ${repoUrl}`);
-    run(`git config core.sparseCheckout true`);
-    run(`git sparse-checkout init --cone`);
-    run(`git sparse-checkout set ${sourceSubdir}`);
-    run(`git fetch --depth 1 origin ${branch}`);
-    run(`git checkout FETCH_HEAD`);
-
-    // we don't copy whole generated folder, just the specific subfolders needed for tests
-    // to verify correct preservation/deletion of files and folders during regeneration,
-    // to avoid accidentally including any manually edited code that might be in the repo
-    // and cause confusion when it doesn't get updated during regeneration
-    const legacyCodePathNeededForTests = [
-      "azure/authentication-api-key",
-      "unbranded/authentication-api-key",
-      "azure/authentication-union",
-      "azure/generation-subdir",
-      "azure/generation-subdir2",
-      "unbranded/generation-subdir",
-      "unbranded/generation-subdir2",
-      "azure/azure-client-generator-core-alternate-type",
-    ];
-
-    const sourceRoot = join(tempDir, ...sourceSubdir.split("/"));
-    for (const subPath of legacyCodePathNeededForTests) {
-      const segments = subPath.split("/");
-      const src = join(sourceRoot, ...segments);
-      const dest = join(testsGeneratedDir, ...segments);
-      if (!existsSync(src)) {
-        console.warn(pc.yellow(`Baseline folder not found: ${src}`));
-        continue;
-      }
-      console.log(pc.dim(`Copying ${subPath} -> ${dest}`));
-      await mkdir(dirname(dest), { recursive: true });
-      await cp(src, dest, { recursive: true });
-    }
-
-    console.log(pc.green(`Baseline reset complete.\n`));
-  } finally {
-    rmSync(tempDir, { recursive: true, force: true });
-  }
-
-  // Smoke test the full-emit path: delete a couple of fully-generated package
-  // folders and every README.md so regeneration has to recreate them.
-  const deleteIfExists = (path: string) => {
-    if (!existsSync(path)) return;
-    console.log(pc.dim(`Deleting ${path}`));
-    rmSync(path, { recursive: true, force: true });
-  };
-
-  deleteIfExists(join(testsGeneratedDir, "azure", "authentication-http-custom"));
-  deleteIfExists(join(testsGeneratedDir, "unbranded", "encode-array"));
-
-  if (existsSync(testsGeneratedDir)) {
-    const entries = await readdir(testsGeneratedDir, { recursive: true, withFileTypes: true });
-    for (const entry of entries) {
-      if (entry.isFile() && entry.name === "README.md") {
-        deleteIfExists(join(entry.parentPath, entry.name));
-      }
-    }
-  }
-}

package/eng/scripts/ci/regenerate.ts

@@ -22,8 +22,8 @@ import { parseArgs } from "util";
 
 import {
   buildTaskGroups,
+  cleanGeneratedCode,
   getSubdirectories,
-  prepareBaselineOfGeneratedCode,
   preprocess,
   RegenerateContext,
   RegenerateFlags,
@@ -256,7 +256,7 @@ async function main() {
   const startTime = performance.now();
   let success: boolean;
 
-  await prepareBaselineOfGeneratedCode(GENERATED_FOLDER);
+  await cleanGeneratedCode(GENERATED_FOLDER);
 
   if (flavor) {
     success = await regenerateFlavor(flavor, name, debug, jobs);

package/generator/build/lib/pygen/codegen/models/client.py

@@ -53,6 +53,17 @@ class _ClientConfigBase(Generic[ParameterListType], BaseModel):
     def name(self) -> str:
         return self.yaml_data["name"]
 
+    @property
+    def has_docstring_only_keyword(self) -> bool:
+        """Whether the constructor docstring documents a ``:keyword:`` that is not a real
+        keyword-only argument (it is popped from ``kwargs`` instead).
+
+        This happens for params routed to ``**kwargs`` (e.g. ``api_version``): they are
+        still rendered as ``:keyword:`` in the docstring, so we must silence the
+        ``docstring-keyword-should-match-keyword-only`` guideline check.
+        """
+        return any(p for p in self.parameters.method if p.method_location == ParameterMethodLocation.KWARG)
+
 
 class Client(_ClientConfigBase[ClientGlobalParameterList]):
     """Model representing our service client"""
@@ -187,6 +198,8 @@ class Client(_ClientConfigBase[ClientGlobalParameterList]):
             retval = add_to_pylint_disable(retval, "too-many-instance-attributes")
         if len(self.name) > NAME_LENGTH_LIMIT:
             retval = add_to_pylint_disable(retval, "name-too-long")
+        if self.has_docstring_only_keyword or self.has_public_lro_operations:
+            retval = add_to_pylint_disable(retval, "docstring-keyword-should-match-keyword-only")
         return retval
 
     @property
@@ -375,6 +388,8 @@ class Config(_ClientConfigBase[ConfigGlobalParameterList]):
         retval = add_to_pylint_disable("", "too-many-instance-attributes") if self.code_model.is_azure_flavor else ""
         if len(self.name) > NAME_LENGTH_LIMIT:
             retval = add_to_pylint_disable(retval, "name-too-long")
+        if self.has_docstring_only_keyword:
+            retval = add_to_pylint_disable(retval, "docstring-keyword-should-match-keyword-only")
         return retval
 
     @property

package/generator/build/lib/pygen/codegen/models/operation.py

@@ -33,7 +33,7 @@ from .parameter import (
 )
 from .parameter_list import ParameterList
 from .model_type import ModelType
-from .primitive_types import BinaryIteratorType, BinaryType
+from .primitive_types import BinaryIteratorType, BinaryType, ByteArraySchema
 from .base import BaseType
 from .combined_type import CombinedType
 from .request_builder import OverloadedRequestBuilder, RequestBuilder
@@ -224,7 +224,15 @@ class OperationBase(  # pylint: disable=too-many-public-methods,too-many-instanc
 
     @property
     def need_import_iobase(self) -> bool:
-        return self.parameters.has_body and isinstance(self.parameters.body_parameter.type, CombinedType)
+        if not (self.parameters.has_body and isinstance(self.parameters.body_parameter.type, CombinedType)):
+            return False
+        # For a binary `bytes` body the combined type is `bytes` + `IO[bytes]`. Both overloads
+        # serialize to raw content, so the body serialization collapses to a single assignment
+        # without an `isinstance` branch. In that case `IOBase` is never referenced, so avoid
+        # importing it to prevent an unused-import lint error in the generated code.
+        if any(isinstance(t, ByteArraySchema) for t in self.parameters.body_parameter.type.types):
+            return False
+        return True
 
     @staticmethod
     def has_kwargs_to_pop_with_default(

package/generator/build/lib/pygen/codegen/models/operation_group.py

@@ -82,6 +82,8 @@ class OperationGroup(BaseModel):
         retval: str = ""
         if self.has_abstract_operations:
             retval = add_to_pylint_disable(retval, "abstract-class-instantiated")
+        if not self.is_mixin:
+            retval = add_to_pylint_disable(retval, "docstring-missing-param")
         if len(self.operations) > 20:
             retval = add_to_pylint_disable(retval, "too-many-public-methods")
         if len(self.class_name) > NAME_LENGTH_LIMIT and self.class_name[0] != "_":

package/generator/build/lib/pygen/codegen/models/primitive_types.py

@@ -50,6 +50,11 @@ class PrimitiveType(BaseType):
 
 
 class BooleanType(PrimitiveType):
+    def __init__(self, yaml_data: dict[str, Any], code_model: "CodeModel") -> None:
+        super().__init__(yaml_data=yaml_data, code_model=code_model)
+        if yaml_data.get("encode") == "string":
+            self.encode = "str"
+
     def serialization_type(self, **kwargs: Any) -> str:
         return "bool"
 

package/generator/build/lib/pygen/codegen/serializers/builder_serializer.py

@@ -462,6 +462,7 @@ class RequestBuilderSerializer(_BuilderBaseSerializer[RequestBuilderType]):
             check_kwarg_dict=True,
             pop_headers_kwarg=(PopKwargType.CASE_INSENSITIVE if bool(builder.parameters.headers) else PopKwargType.NO),
             pop_params_kwarg=(PopKwargType.CASE_INSENSITIVE if bool(builder.parameters.query) else PopKwargType.NO),
+            is_body_optional=builder.parameters.has_body and builder.parameters.body_parameter.optional,
         )
 
     @staticmethod
@@ -491,6 +492,7 @@ class RequestBuilderSerializer(_BuilderBaseSerializer[RequestBuilderType]):
             for h in builder.parameters.headers
             if not builder.has_form_data_body or h.wire_name.lower() != "content-type"
         ]
+        is_body_optional = builder.parameters.has_body and builder.parameters.body_parameter.optional
         retval = ["# Construct headers"] if headers else []
         for header in headers:
             retval.extend(
@@ -499,6 +501,7 @@ class RequestBuilderSerializer(_BuilderBaseSerializer[RequestBuilderType]):
                     "headers",
                     self.serializer_name,
                     self.code_model.is_legacy,
+                    is_body_optional=is_body_optional,
                 )
             )
         return retval
@@ -793,6 +796,34 @@ class _OperationSerializer(_BuilderBaseSerializer[OperationType]):
             retval.extend(self._serialize_body_parameter(builder))
         return retval
 
+    @staticmethod
+    def _collapsed_binary_bytes_overload(builder: OperationType) -> Optional[OperationType]:
+        """Return the binary overload of a binary ``bytes`` body, or ``None``.
+
+        A binary ``bytes`` body pairs a ``bytes`` overload (binary content type) with the added
+        ``IO[bytes]`` overload. Both serialize to raw content on the same content kwarg, so body
+        serialization collapses to a single unconditional assignment. This returns the binary
+        overload to serialize in that case, or ``None`` when the isinstance branch is needed.
+        """
+        if not builder.overloads:
+            return None
+        binary_ov = next(
+            (o for o in builder.overloads if isinstance(o.parameters.body_parameter.type, BinaryType)), None
+        )
+        other_ov = next(
+            (o for o in builder.overloads if not isinstance(o.parameters.body_parameter.type, BinaryType)), None
+        )
+        if (
+            binary_ov is not None
+            and other_ov is not None
+            and isinstance(other_ov.parameters.body_parameter.type, ByteArraySchema)
+            and other_ov.parameters.body_parameter.default_content_type != "application/json"
+            and binary_ov.request_builder.parameters.body_parameter.client_name
+            == other_ov.request_builder.parameters.body_parameter.client_name
+        ):
+            return cast(OperationType, binary_ov)
+        return None
+
     def _initialize_overloads(self, builder: OperationType, is_paging: bool = False) -> list[str]:
         retval: list[str] = []
         # For paging, we put body parameter in local place outside `prepare_request`
@@ -817,9 +848,26 @@ class _OperationSerializer(_BuilderBaseSerializer[OperationType]):
             all_dpg_model_overloads = all(
                 _is_dpg_or_typeddict_body(o.parameters.body_parameter) for o in builder.overloads
             )
-        if not all_dpg_model_overloads:
+        # A binary `bytes` body pairs a `bytes` overload (binary content type) with the added
+        # `IO[bytes]` overload. Both serialize to raw content on the same content kwarg, so we
+        # emit a single unconditional assignment instead of an `isinstance` branch (which would be
+        # redundant and confuse mypy's type narrowing). Since the assignment is unconditional, the
+        # `_<body> = None` pre-init below is skipped for this case as well.
+        collapsed_binary_bytes_overload = self._collapsed_binary_bytes_overload(builder)
+
+        if not all_dpg_model_overloads and collapsed_binary_bytes_overload is None:
             for v in sorted(set(client_names), key=client_names.index):
                 retval.append(f"_{v} = None")
+
+        if collapsed_binary_bytes_overload is not None:
+            collapsed_body_param = collapsed_binary_bytes_overload.parameters.body_parameter
+            if collapsed_body_param.default_content_type and not same_content_type:
+                retval.append(
+                    f'content_type = content_type or "{collapsed_body_param.default_content_type}"{check_body_suffix}'
+                )
+            retval.extend(self._create_body_parameter(collapsed_binary_bytes_overload))
+            return retval
+
         try:
             # if there is a binary overload, we do a binary check first.
             binary_overload = cast(
@@ -827,6 +875,10 @@ class _OperationSerializer(_BuilderBaseSerializer[OperationType]):
                 next((o for o in builder.overloads if isinstance(o.parameters.body_parameter.type, BinaryType))),
             )
             binary_body_param = binary_overload.parameters.body_parameter
+            other_overload = cast(
+                OperationType,
+                next((o for o in builder.overloads if not isinstance(o.parameters.body_parameter.type, BinaryType))),
+            )
             retval.append(f"if {binary_body_param.type.instance_check_template.format(binary_body_param.client_name)}:")
             if binary_body_param.default_content_type and not same_content_type:
                 retval.append(
@@ -834,10 +886,6 @@ class _OperationSerializer(_BuilderBaseSerializer[OperationType]):
                 )
             retval.extend(f"    {l}" for l in self._create_body_parameter(binary_overload))
             retval.append("else:")
-            other_overload = cast(
-                OperationType,
-                next((o for o in builder.overloads if not isinstance(o.parameters.body_parameter.type, BinaryType))),
-            )
             retval.extend(f"    {l}" for l in self._create_body_parameter(other_overload))
             if other_overload.parameters.body_parameter.default_content_type and not same_content_type:
                 retval.append(

package/generator/build/lib/pygen/codegen/serializers/general_serializer.py

@@ -320,7 +320,27 @@ class GeneralSerializer(BaseSerializer):
 
     def serialize_validation_file(self) -> str:
         template = self.env.get_template("validation.py.jinja2")
-        return template.render(code_model=self.code_model)
+        return template.render(
+            code_model=self.code_model,
+            client_api_version_name=self._api_version_config_attr_name(),
+        )
+
+    def _api_version_config_attr_name(self) -> str:
+        """Name of the config attribute that stores the API version.
+
+        The attribute name is derived from the API-version parameter's ``client_name``
+        (e.g. ``apiVersion`` -> ``api_version``, or Storage's ``version`` -> ``version``).
+        ``_validation.py`` holds a single shared decorator for the whole package, so when
+        every client agrees on the name we bake it in directly; otherwise we fall back to
+        the conventional ``api_version``.
+        """
+        names = {
+            parameter.client_name
+            for client in self.code_model.clients
+            for parameter in client.config.parameters.parameters
+            if parameter.is_api_version
+        }
+        return next(iter(names)) if len(names) == 1 else "api_version"
 
     def serialize_cross_language_definition_file(self) -> str:
         cross_langauge_def_dict = {

package/generator/build/lib/pygen/codegen/serializers/model_serializer.py

@@ -23,7 +23,7 @@ from ..models.primitive_types import (
 )
 from .import_serializer import FileImportSerializer
 from .base_serializer import BaseSerializer
-from ..models.utils import NamespaceType
+from ..models.utils import NamespaceType, add_to_pylint_disable
 
 
 def _get_xml_deserializer_name(prop: Property) -> Optional[str]:  # pylint: disable=too-many-return-statements
@@ -77,7 +77,10 @@ def _documentation_string(
     prop: Property, description_keyword: str, docstring_type_keyword: str, **kwargs: Any
 ) -> list[str]:
     retval: list[str] = []
-    sphinx_prefix = f":{description_keyword} {prop.client_name}:"
+    doc_name = (
+        prop.wire_name if kwargs.get("serialize_namespace_type") == NamespaceType.TYPES_FILE else prop.client_name
+    )
+    sphinx_prefix = f":{description_keyword} {doc_name}:"
     description = prop.description(is_operation_file=False).replace("\\", "\\\\")
     retval.append(f"{sphinx_prefix} {description}" if description else sphinx_prefix)
     # In the types file, use type_annotation (the serialized form) for docstrings
@@ -85,7 +88,7 @@ def _documentation_string(
         doc_type = prop.type.type_annotation(**kwargs)
     else:
         doc_type = prop.type.docstring_type(**kwargs)
-    retval.append(f":{docstring_type_keyword} {prop.client_name}: {doc_type}")
+    retval.append(f":{docstring_type_keyword} {doc_name}: {doc_type}")
     return retval
 
 
@@ -199,6 +202,16 @@ class _ModelSerializer(BaseSerializer, ABC):
     def pylint_disable(self, model: ModelType) -> str:
         return "  # pylint: disable=" + ", ".join(self.pylint_disable_items(model))
 
+    def class_pylint_disable(self, model: ModelType) -> str:
+        """Class-level pylint disables for the model declaration line."""
+        retval = model.pylint_disable()
+        # When the model's only constructor is ``def __init__(self, *args, **kwargs)`` (i.e. no
+        # typed overload is generated), the guideline checker reports the ``*args`` vararg as an
+        # undocumented param. There is no meaningful param to document, so silence the check.
+        if not self.need_init(model) and self.initialize_properties(model):
+            retval = add_to_pylint_disable(retval, "docstring-missing-param")
+        return retval
+
     def global_pylint_disables(self) -> str:
         return ""
 
@@ -244,7 +257,7 @@ class MsrestModelSerializer(_ModelSerializer):
         )
         if model.parents:
             basename = ", ".join([m.name for m in model.parents])
-        return f"class {model.name}({basename}):{model.pylint_disable()}"
+        return f"class {model.name}({basename}):{self.class_pylint_disable(model)}"
 
     @staticmethod
     def get_properties_to_initialize(model: ModelType) -> list[Property]:
@@ -407,7 +420,17 @@ class DpgModelSerializer(_ModelSerializer):
             basename = ", ".join([m.name for m in model.parents])
         if model.discriminator_value:
             basename += f", discriminator='{model.discriminator_value}'"
-        return f"class {model.name}({basename}):{model.pylint_disable()}"
+        return f"class {model.name}({basename}):{self.class_pylint_disable(model)}"
+
+    def class_pylint_disable(self, model: ModelType) -> str:
+        retval = super().class_pylint_disable(model)
+        # DPG models render an empty ``@overload def __init__(self, *, ...)`` body, so the
+        # guideline checker validates the keyword-only arguments against the *class* docstring.
+        # We only document those arguments as instance variables (``:ivar:``) to avoid a redundant
+        # ``:keyword:`` entry per property, so silence the keyword/keyword-only correlation check.
+        if self._init_line_parameters(model):
+            retval = add_to_pylint_disable(retval, "docstring-keyword-should-match-keyword-only")
+        return retval
 
     @staticmethod
     def get_properties_to_declare(model: ModelType) -> list[Property]:

package/generator/build/lib/pygen/codegen/serializers/parameter_serializer.py

@@ -139,6 +139,8 @@ class ParameterSerializer:
         kwarg_name: str,
         serializer_name: str,
         is_legacy: bool,
+        *,
+        is_body_optional: bool = False,
     ) -> list[str]:
         if (
             not is_legacy
@@ -166,7 +168,11 @@ class ParameterSerializer:
             param.wire_name,
             self.serialize_parameter(param, serializer_name),
         )
-        if not param.optional and (param.in_method_signature or param.constant):
+        # When the body is optional, the content-type may legitimately be ``None`` (no body
+        # was sent). In that case the header must be omitted instead of serialized, otherwise
+        # ``_SERIALIZER.header`` raises ``ValueError: No value for given attribute``.
+        is_content_type_optional = getattr(param, "is_content_type", False) and is_body_optional
+        if not param.optional and not is_content_type_optional and (param.in_method_signature or param.constant):
             retval = [set_parameter]
         else:
             retval = [
@@ -184,6 +190,7 @@ class ParameterSerializer:
         check_client_input: bool = False,
         *,
         body_parameter: Optional[BodyParameterType] = None,
+        is_body_optional: Optional[bool] = None,
     ) -> list[str]:
         retval = []
 
@@ -195,7 +202,8 @@ class ParameterSerializer:
 
         append_pop_kwarg("headers", pop_headers_kwarg)
         append_pop_kwarg("params", pop_params_kwarg)
-        is_body_optional = check_body_optional(body_parameter)
+        if is_body_optional is None:
+            is_body_optional = check_body_optional(body_parameter)
         if pop_headers_kwarg != PopKwargType.NO or pop_params_kwarg != PopKwargType.NO:
             retval.append("")
         for kwarg in parameters:
@@ -206,7 +214,13 @@ class ParameterSerializer:
                 if is_content_type_optional and not type_annotation.startswith("Optional[")
                 else type_annotation
             )
-            if kwarg.client_default_value is not None or kwarg.optional or kwarg.constant or kwarg.is_api_version:
+            if (
+                kwarg.client_default_value is not None
+                or kwarg.optional
+                or kwarg.constant
+                or kwarg.is_api_version
+                or is_content_type_optional
+            ):
                 if check_client_input and kwarg.check_client_input:
                     default_value = f"self._config.{kwarg.client_name}"
                 elif kwarg.constant:

package/generator/build/lib/pygen/codegen/serializers/types_serializer.py

@@ -40,13 +40,38 @@ _BUILTIN_TYPE_NAMES = frozenset(
 )
 
 
+# Matches a single- or double-quoted string literal (escape-aware). Used to split an
+# annotation so that bare-identifier rewriting/detection skips text inside string literals
+# such as ``Literal["type"]`` values or quoted forward references like ``"SomeModel"``.
+_STRING_LITERAL_RE = re.compile(r"""('(?:[^'\\]|\\.)*'|"(?:[^"\\]|\\.)*")""")
+
+
+def _annotation_references_builtin(annotation: str, name: str) -> bool:
+    """Whether ``name`` appears as a bare (non-dotted) identifier outside any string literal."""
+    pattern = re.compile(rf"(?<!\.)\b{name}\b")
+    # re.split with a single capturing group yields code/string/code/string/... segments.
+    for index, segment in enumerate(_STRING_LITERAL_RE.split(annotation)):
+        if index % 2 == 0 and pattern.search(segment):
+            return True
+    return False
+
+
 def _qualify_shadowed_builtins(annotation: str, shadowed: frozenset[str]) -> str:
-    """Replace bare builtin type references with builtins.X when shadowed by a field name."""
+    """Replace bare builtin type references with builtins.X when shadowed by a field name.
+
+    Only bare identifiers in real type-expression positions are rewritten; identifiers
+    inside string literals (e.g. ``Literal["type"]`` values, quoted forward references)
+    and already-dotted names are left untouched.
+    """
     if not shadowed:
         return annotation
-    for name in shadowed:
-        annotation = re.sub(rf"\b{name}\b", f"builtins.{name}", annotation)
-    return annotation
+    segments = _STRING_LITERAL_RE.split(annotation)
+    for index in range(0, len(segments), 2):  # even indices are code, odd are string literals
+        segment = segments[index]
+        for name in shadowed:
+            segment = re.sub(rf"(?<!\.)\b{name}\b", f"builtins.{name}", segment)
+        segments[index] = segment
+    return "".join(segments)
 
 
 class TypesSerializer(BaseSerializer):
@@ -164,9 +189,7 @@ class TypesSerializer(BaseSerializer):
         property — are kept, ensuring no forward reference is left undefined.
         """
         needed = self._types_file_model_names
-        candidates = [
-            m for m in self._models if m.base != "json" and not m.discriminated_subtypes and m.name in needed
-        ]
+        candidates = [m for m in self._models if m.base != "json" and not m.discriminated_subtypes and m.name in needed]
         seen_names: dict[str, "ModelType"] = {}
         result: list["ModelType"] = []
         for m in candidates:
@@ -225,22 +248,27 @@ class TypesSerializer(BaseSerializer):
         """Whether any property wire_name is a Python keyword or requires functional TypedDict form."""
         return any(keyword.iskeyword(p.wire_name) or not p.wire_name.isidentifier() for p in model.properties)
 
-    @staticmethod
-    def get_shadowed_builtins(model: ModelType) -> frozenset[str]:
+    def get_shadowed_builtins(self, model: ModelType) -> frozenset[str]:
         """Return the set of builtin type names shadowed by property wire_names in this model.
 
-        Only includes a builtin if it is both used as a wire_name AND referenced
-        in a type annotation within the same model (otherwise no shadowing occurs).
+        Only includes a builtin if it is both used as a wire_name AND referenced as a bare
+        type in an annotation within the same model (otherwise no shadowing occurs). Detection
+        uses the exact ``TYPES_FILE`` annotation emitted for each property so that types which
+        change under the types-file serialization (e.g. ``bytes``/``datetime`` -> ``str``,
+        ``decimal`` -> ``float``) are evaluated as they actually appear in the output.
         """
         wire_builtins = {p.wire_name for p in model.properties if p.wire_name in _BUILTIN_TYPE_NAMES}
         if not wire_builtins:
             return frozenset()
-        # Check which of these builtins actually appear in type annotations
+        # Check which of these builtins actually appear in emitted type annotations
         used = set()
         for prop in model.properties:
-            annotation = prop.type_annotation()
+            annotation = prop.type_annotation(
+                serialize_namespace=self.serialize_namespace,
+                serialize_namespace_type=NamespaceType.TYPES_FILE,
+            )
             for name in wire_builtins:
-                if re.search(rf"\b{name}\b", annotation):
+                if _annotation_references_builtin(annotation, name):
                     used.add(name)
         return frozenset(used)