@typespec/http-client-python 0.34.2 → 0.35.0

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:

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.2",
+  "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/**",