@typespec/http-client-python 0.34.1 → 0.35.0

package/generator/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/pygen/codegen/serializers/builder_serializer.py

@@ -793,6 +793,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 +845,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 +872,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 +883,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/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
@@ -199,6 +199,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 +254,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 +417,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/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):
@@ -225,22 +250,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)
 

package/generator/pygen/codegen/templates/model_base.py.jinja2

@@ -161,7 +161,15 @@ def _is_readonly(p):
 
 
 class SdkJSONEncoder(JSONEncoder):
-    """A JSON encoder that's capable of serializing datetime objects and bytes."""
+    """A JSON encoder that's capable of serializing datetime objects and bytes.
+
+    :param args: Additional positional arguments passed to the base ``JSONEncoder``.
+    :type args: typing.Any
+    :keyword exclude_readonly: Whether to exclude readonly properties. Defaults to False.
+    :paramtype exclude_readonly: bool
+    :keyword format: The format to use for serialization. Defaults to None.
+    :paramtype format: typing.Optional[str]
+    """
 
     def __init__(self, *args, exclude_readonly: bool = False, format: typing.Optional[str] = None, **kwargs):
         super().__init__(*args, **kwargs)
@@ -348,6 +356,12 @@ def _deserialize_int_as_str(attr):
     return int(attr)
 
 
+def _deserialize_bool_as_str(attr):
+    if isinstance(attr, bool):
+        return attr
+    return attr.lower() == "true"
+
+
 _DESERIALIZE_MAPPING = {
     datetime: _deserialize_datetime,
     date: _deserialize_date,
@@ -375,6 +389,8 @@ _DESERIALIZE_MAPPING_WITHFORMAT = {
 def get_deserializer(annotation: typing.Any, rf: typing.Optional["_RestField"] = None):
     if annotation is int and rf and rf._format == "str":
         return _deserialize_int_as_str
+    if annotation is bool and rf and rf._format == "str":
+        return _deserialize_bool_as_str
     if annotation is str and rf and rf._format in _ARRAY_ENCODE_MAPPING:
         return functools.partial(_deserialize_array_encoded, _ARRAY_ENCODE_MAPPING[rf._format])
     if rf and rf._format:
@@ -470,21 +486,21 @@ class _MyMutableMapping(MutableMapping[str, typing.Any]):
 
     def keys(self) -> typing.KeysView[str]:
         """
-        :returns: a set-like object providing a view on D's keys
+        :returns: a set-like object providing a view on the mapping's keys
         :rtype: ~typing.KeysView
         """
         return self._data.keys()
 
     def values(self) -> typing.ValuesView[typing.Any]:
         """
-        :returns: an object providing a view on D's values
+        :returns: an object providing a view on the mapping's values
         :rtype: ~typing.ValuesView
         """
         return self._data.values()
 
     def items(self) -> typing.ItemsView[str, typing.Any]:
         """
-        :returns: set-like object providing a view on D's items
+        :returns: a set-like object providing a view on the mapping's items
         :rtype: ~typing.ItemsView
         """
         return self._data.items()
@@ -494,7 +510,7 @@ class _MyMutableMapping(MutableMapping[str, typing.Any]):
         Get the value for key if key is in the dictionary, else default.
         :param str key: The key to look up.
         :param any default: The value to return if key is not in the dictionary. Defaults to None
-        :returns: D[k] if k in D, else d.
+        :returns: The value for key if key is in the dictionary, else default.
         :rtype: any
         """
         try:
@@ -529,19 +545,19 @@ class _MyMutableMapping(MutableMapping[str, typing.Any]):
         Removes and returns some (key, value) pair
         :returns: The (key, value) pair.
         :rtype: tuple
-        :raises KeyError: if D is empty.
+        :raises KeyError: if the dictionary is empty.
         """
         return self._data.popitem()
 
     def clear(self) -> None:
         """
-        Remove all items from D.
+        Remove all items from the dictionary.
         """
         self._data.clear()
 
     def update(self, *args: typing.Any, **kwargs: typing.Any) -> None:  # pylint: disable=arguments-differ
         """
-        Updates D from mapping/iterable E and F.
+        Update the dictionary from a mapping or an iterable of key-value pairs.
         :param any args: Either a mapping object or an iterable of key-value pairs.
         """
         self._data.update(*args, **kwargs)
@@ -554,10 +570,11 @@ class _MyMutableMapping(MutableMapping[str, typing.Any]):
 
     def setdefault(self, key: str, default: typing.Any = _UNSET) -> typing.Any:
         """
-        Same as calling D.get(k, d), and setting D[k]=d if k not found
+        Return the value for key if key is in the dictionary; otherwise set the key to
+        default and return default.
         :param str key: The key to look up.
         :param any default: The value to set if key is not in the dictionary
-        :returns: D[k] if k in D, else d.
+        :returns: The value for key if key is in the dictionary, else default.
         :rtype: any
         """
         if default is _UNSET:

package/generator/pygen/codegen/templates/serialization.py.jinja2

@@ -476,7 +476,11 @@ def _decode_attribute_map_key(key):
 
 
 class Serializer:  # pylint: disable=too-many-public-methods
-    """Request object model serializer."""
+    """Request object model serializer.
+
+    :param classes: Mapping of model names to model types, used to resolve models during serialization.
+    :type classes: typing.Optional[typing.Mapping[str, type]]
+    """
 
     basic_types = {str: "str", int: "int", bool: "bool", float: "float"}
 

package/generator/pygen/preprocess/__init__.py

@@ -399,6 +399,25 @@ class PreProcessPlugin(YamlUpdatePlugin):
         code_model: dict[str, Any],
         body_parameter: dict[str, Any],
     ):
+        # For a binary `bytes` body (e.g. content type application/octet-stream or a custom
+        # binary media type), add an IO overload alongside the `bytes` one. This keeps backward
+        # compatibility for services migrating from swagger, whose binary bodies were typed as IO.
+        is_multipart = self.is_tsp and has_multi_part_content_type(body_parameter)
+        is_binary_body = not has_json_content_type(body_parameter) and not is_multipart
+        if (
+            body_parameter
+            and body_parameter["type"]["type"] == "bytes"
+            and is_binary_body
+            and self.options["models-mode"] != "typeddict"
+            and not any(t for t in ["flattened", "groupedBy"] if body_parameter.get(t))
+        ):
+            body_parameter["type"] = {
+                "type": "combined",
+                "types": [body_parameter["type"], KNOWN_TYPES["binary"]],
+            }
+            code_model["types"].append(body_parameter["type"])
+            return
+
         # only add overload for special content type
         if (  # pylint: disable=too-many-boolean-expressions
             body_parameter

package/generator/pygen/utils.py

@@ -109,7 +109,7 @@ def parse_args(
 
 
 def get_body_type_for_description(body_parameter: dict[str, Any]) -> str:
-    if body_parameter["type"]["type"] == "binary":
+    if body_parameter["type"]["type"] in ("binary", "bytes"):
         return "binary"
     if body_parameter["type"]["type"] == "string":
         return "string"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@typespec/http-client-python",
-  "version": "0.34.1",
+  "version": "0.35.0",
   "author": "Microsoft Corporation",
   "description": "TypeSpec emitter for Python SDKs",
   "homepage": "https://typespec.io",
@@ -54,7 +54,8 @@
     "ci:generated": "tsx ./eng/scripts/ci/run-tests.ts --generator --env=ci",
     "change:version": "pnpm chronus version --ignore-policies --only @typespec/http-client-python",
     "change:add": "pnpm chronus add",
-    "regen-docs": "node ../../packages/tspd/cmd/tspd.js doc . --enable-experimental --output-dir ../../website/src/content/docs/docs/emitters/clients/http-client-python/reference --skip-js"
+    "regen-docs": "node ../../packages/tspd/cmd/tspd.js doc . --enable-experimental --output-dir ../../website/src/content/docs/docs/emitters/clients/http-client-python/reference --skip-js",
+    "diff-spector-tests": "node ../../eng/emitter-diff/src/cli.ts --emitter python"
   },
   "files": [
     "dist/**",
@@ -64,20 +65,20 @@
     "emitter"
   ],
   "peerDependencies": {
-    "@azure-tools/typespec-autorest": ">=0.69.1 <1.0.0",
-    "@azure-tools/typespec-azure-core": ">=0.69.0 <1.0.0",
-    "@azure-tools/typespec-azure-resource-manager": ">=0.69.1 <1.0.0",
-    "@azure-tools/typespec-azure-rulesets": ">=0.69.1 <1.0.0",
-    "@azure-tools/typespec-client-generator-core": ">=0.69.1 <1.0.0",
-    "@typespec/compiler": "^1.13.0",
-    "@typespec/http": "^1.13.0",
-    "@typespec/openapi": "^1.13.0",
-    "@typespec/rest": ">=0.83.0 <1.0.0",
-    "@typespec/versioning": ">=0.83.0 <1.0.0",
-    "@typespec/events": ">=0.83.0 <1.0.0",
-    "@typespec/sse": ">=0.83.0 <1.0.0",
-    "@typespec/streams": ">=0.83.0 <1.0.0",
-    "@typespec/xml": ">=0.83.0 <1.0.0"
+    "@azure-tools/typespec-autorest": ">=0.70.0 <1.0.0",
+    "@azure-tools/typespec-azure-core": ">=0.70.0 <1.0.0",
+    "@azure-tools/typespec-azure-resource-manager": ">=0.70.0 <1.0.0",
+    "@azure-tools/typespec-azure-rulesets": ">=0.70.0 <1.0.0",
+    "@azure-tools/typespec-client-generator-core": ">=0.70.0 <1.0.0",
+    "@typespec/compiler": "^1.14.0",
+    "@typespec/http": "^1.14.0",
+    "@typespec/openapi": "^1.14.0",
+    "@typespec/rest": ">=0.84.0 <1.0.0",
+    "@typespec/versioning": ">=0.84.0 <1.0.0",
+    "@typespec/events": ">=0.84.0 <1.0.0",
+    "@typespec/sse": ">=0.84.0 <1.0.0",
+    "@typespec/streams": ">=0.84.0 <1.0.0",
+    "@typespec/xml": ">=0.84.0 <1.0.0"
   },
   "playgroundConfig": {
     "assets": [
@@ -102,24 +103,24 @@
     "tsx": "^4.21.0"
   },
   "devDependencies": {
-    "@azure-tools/typespec-autorest": "~0.69.1",
-    "@azure-tools/typespec-azure-core": "~0.69.0",
-    "@azure-tools/typespec-azure-resource-manager": "~0.69.1",
-    "@azure-tools/typespec-azure-rulesets": "~0.69.1",
-    "@azure-tools/typespec-client-generator-core": "~0.69.1",
-    "@azure-tools/azure-http-specs": "0.1.0-alpha.42",
-    "@typespec/compiler": "^1.13.0",
-    "@typespec/http": "^1.13.0",
-    "@typespec/openapi": "^1.13.0",
-    "@typespec/rest": "~0.83.0",
-    "@typespec/versioning": "~0.83.0",
-    "@typespec/events": "~0.83.0",
-    "@typespec/spector": "0.1.0-alpha.25",
-    "@typespec/spec-api": "0.1.0-alpha.14",
-    "@typespec/sse": "~0.83.0",
-    "@typespec/streams": "~0.83.0",
-    "@typespec/xml": "~0.83.0",
-    "@typespec/http-specs": "0.1.0-alpha.39-dev.2",
+    "@azure-tools/typespec-autorest": "~0.70.0",
+    "@azure-tools/typespec-azure-core": "~0.70.0",
+    "@azure-tools/typespec-azure-resource-manager": "~0.70.0",
+    "@azure-tools/typespec-azure-rulesets": "~0.70.0",
+    "@azure-tools/typespec-client-generator-core": "~0.70.0",
+    "@azure-tools/azure-http-specs": "0.1.0-alpha.43",
+    "@typespec/compiler": "^1.14.0",
+    "@typespec/http": "^1.14.0",
+    "@typespec/openapi": "^1.14.0",
+    "@typespec/rest": "~0.84.0",
+    "@typespec/versioning": "~0.84.0",
+    "@typespec/events": "~0.84.0",
+    "@typespec/spector": "0.1.0-alpha.26",
+    "@typespec/spec-api": "0.1.0-alpha.15",
+    "@typespec/sse": "~0.84.0",
+    "@typespec/streams": "~0.84.0",
+    "@typespec/xml": "~0.84.0",
+    "@typespec/http-specs": "0.1.0-alpha.39",
     "@types/js-yaml": "~4.0.5",
     "@types/node": "~25.0.2",
     "@types/semver": "7.5.8",