@typespec/http-client-python 0.31.1 → 0.33.0

package/generator/build/lib/pygen/__init__.py

@@ -29,6 +29,7 @@ class OptionsDict(MutableMapping):
         "from-typespec": False,
         "generate-sample": False,
         "keep-setup-py": False,
+        "keep-pyproject-fields": "",
         "generate-test": False,
         "head-as-boolean": True,
         "keep-version-file": False,

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

@@ -522,8 +522,22 @@ class DateType(PrimitiveType):
 
 
 class DurationType(PrimitiveType):
+    def __init__(self, yaml_data: dict[str, Any], code_model: "CodeModel") -> None:
+        super().__init__(yaml_data=yaml_data, code_model=code_model)
+        # ``seconds`` and ``milliseconds`` encodings serialize a timedelta to a numeric
+        # wire value. ``encode`` is set to a combined format token (e.g.
+        # ``duration-seconds-int``) so that serialization/deserialization can convert
+        # between ``datetime.timedelta`` and the numeric wire type. ISO8601 (the default)
+        # leaves ``encode`` unset and keeps the legacy ISO 8601 string behavior.
+        self.encode: Optional[str] = None
+        encode = yaml_data.get("encode")
+        if encode in ("seconds", "milliseconds"):
+            wire_type = yaml_data.get("wireType") or {}
+            wire = "int" if wire_type.get("type") == "integer" else "float"
+            self.encode = f"duration-{encode}-{wire}"
+
     def serialization_type(self, **kwargs: Any) -> str:
-        return "duration"
+        return self.encode or "duration"
 
     def docstring_type(self, **kwargs: Any) -> str:
         return "~" + self.type_annotation()

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

@@ -7,14 +7,25 @@ from typing import TypeVar
 
 from enum import Enum
 
+from ...utils import description_ends_with_code_block
+
 T = TypeVar("T")
 OrderedSet = dict[T, None]
 
 
 def add_to_description(description: str, entry: str) -> str:
-    if description:
-        return f"{description} {entry}"
-    return entry
+    if not description:
+        return entry
+    if not entry:
+        return description
+    # When the description ends with a code block, prepend the entry (e.g. "Required.") so
+    # it appears before the prose instead of after the block. Appending inline (e.g.
+    # "]. Required.") would land it inside the rendered literal block and break Sphinx, and a
+    # trailing paragraph reads awkwardly. The code block stays at the very end where it renders
+    # cleanly. (Code-block descriptions only ever carry a single annotation in practice.)
+    if description_ends_with_code_block(description):
+        return f"{entry} {description.lstrip()}"
+    return f"{description} {entry}"
 
 
 def add_to_pylint_disable(curr_str: str, entry: str) -> str:
@@ -34,6 +45,10 @@ class NamespaceType(str, Enum):
 
 LOCALS_LENGTH_LIMIT = 25
 
-REQUEST_BUILDER_BODY_VARIABLES_LENGTH = 6  # how many body variables are present in a request builder
+REQUEST_BUILDER_BODY_VARIABLES_LENGTH = (
+    6  # how many body variables are present in a request builder
+)
 
-OPERATION_BODY_VARIABLES_LENGTH = 14  # how many body variables are present in an operation
+OPERATION_BODY_VARIABLES_LENGTH = (
+    14  # how many body variables are present in an operation
+)

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

@@ -931,7 +931,8 @@ class _OperationSerializer(_BuilderBaseSerializer[OperationType]):
         if builder.parameters.has_body and builder.parameters.body_parameter.flattened:
             # serialize flattened body before passing to request builder as well
             retval.extend(_serialize_flattened_body(builder.parameters.body_parameter))
-        if is_json_model_type(builder.parameters):
+        if is_json_model_type(builder.parameters) and not is_paging:
+            # For paging, we put the json model body outside `prepare_request`
             retval.extend(_serialize_json_model_body(builder.parameters.body_parameter, builder.parameters.parameters))
         if builder.has_form_data_body:
             retval.extend(self._create_body_parameter(builder))
@@ -1369,7 +1370,13 @@ class _PagingOperationSerializer(_OperationSerializer[PagingOperationType]):
         return retval
 
     def _prepare_request_callback(self, builder: PagingOperationType) -> list[str]:
-        retval = self._initialize_overloads(builder)
+        retval: list[str] = []
+        # The json model body must be constructed before `_initialize_overloads`
+        # serializes it into the request content, and outside `prepare_request` so
+        # the closure doesn't treat `body` as an unbound local.
+        if is_json_model_type(builder.parameters):
+            retval.extend(_serialize_json_model_body(builder.parameters.body_parameter, builder.parameters.parameters))
+        retval.extend(self._initialize_overloads(builder))
         if builder.has_continuation_token:
             retval.append(f"def prepare_request({builder.next_variable_name}=None):")
             retval.extend([f"    {line}" for line in self.call_request_builder(builder, is_paging=True)])

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

@@ -66,7 +66,26 @@ class GeneralSerializer(BaseSerializer):
         if dep_version > default_version:
             version_map[dep_name] = str(dep_version)
 
-    def external_lib_version_map(self, file_content: str, additional_version_map: dict[str, str]) -> dict:
+    # Project-level pyproject.toml fields that may be preserved across regeneration
+    # via the "keep-pyproject-fields" option.
+    KEEPABLE_PROJECT_FIELDS = ("authors", "description", "classifiers", "urls")
+
+    @staticmethod
+    def _parse_keep_pyproject_fields(value: Any) -> tuple[str, ...]:
+        # The "keep-pyproject-fields" option may be a comma-separated string (e.g.
+        # "authors,description") or an already-parsed sequence of field names.
+        if not value:
+            return ()
+        if isinstance(value, str):
+            return tuple(field.strip() for field in value.split(",") if field.strip())
+        return tuple(value)
+
+    def external_lib_version_map(
+        self,
+        file_content: str,
+        additional_version_map: dict[str, str],
+        keep_pyproject_fields: tuple[str, ...] = (),
+    ) -> dict:
         # Load the pyproject.toml file if it exists and extract fields to keep.
         result: dict = {"KEEP_FIELDS": {}}
         try:
@@ -85,6 +104,14 @@ class GeneralSerializer(BaseSerializer):
 
         # Process dependencies
         if "project" in loaded_pyproject_toml:
+            project = loaded_pyproject_toml["project"]
+
+            # Keep manually customized project fields the emitter would otherwise overwrite.
+            # Only the fields explicitly listed in the "keep-pyproject-fields" option are preserved.
+            for field in keep_pyproject_fields:
+                if field in self.KEEPABLE_PROJECT_FIELDS and field in project:
+                    result["KEEP_FIELDS"][f"project.{field}"] = project[field]
+
             # Handle main dependencies
             if "dependencies" in loaded_pyproject_toml["project"]:
                 kept_deps = []
@@ -127,7 +154,10 @@ class GeneralSerializer(BaseSerializer):
 
         # Add fields to keep from an existing pyproject.toml
         if template_name == "pyproject.toml.jinja2":
-            params = self.external_lib_version_map(file_content, additional_version_map)
+            keep_pyproject_fields = self._parse_keep_pyproject_fields(
+                self.code_model.options.get("keep-pyproject-fields")
+            )
+            params = self.external_lib_version_map(file_content, additional_version_map, keep_pyproject_fields)
         else:
             params = {}
 

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

@@ -112,6 +112,29 @@ def _serialize_bytes(o, format: typing.Optional[str] = None) -> str:
     return encoded
 
 
+def _serialize_duration(td: timedelta, format: typing.Optional[str] = None):
+    """Serialize a timedelta to its wire representation.
+
+    For the ``seconds``/``milliseconds`` encodings the value is converted to a
+    numeric value, otherwise it falls back to an ISO 8601 duration string.
+
+    :param timedelta td: The timedelta to serialize.
+    :param str format: The duration encoding format.
+    :rtype: int or float or str
+    :return: serialized duration
+    """
+    seconds = td.total_seconds()
+    if format == "duration-seconds-int":
+        return int(seconds)
+    if format == "duration-seconds-float":
+        return seconds
+    if format == "duration-milliseconds-int":
+        return int(seconds * 1000)
+    if format == "duration-milliseconds-float":
+        return seconds * 1000
+    return _timedelta_as_isostr(td)
+
+
 def _serialize_datetime(o, format: typing.Optional[str] = None):
     if hasattr(o, "year") and hasattr(o, "hour"):
         if format == "rfc7231":
@@ -307,6 +330,12 @@ def _deserialize_duration(attr):
     return isodate.parse_duration(attr)
 
 
+def _deserialize_duration_numeric(attr, unit):
+    if isinstance(attr, timedelta):
+        return attr
+    return timedelta(**{unit: float(attr)})
+
+
 def _deserialize_decimal(attr):
     if isinstance(attr, decimal.Decimal):
         return attr
@@ -336,6 +365,10 @@ _DESERIALIZE_MAPPING_WITHFORMAT = {
     "unix-timestamp": _deserialize_datetime_unix_timestamp,
     "base64": _deserialize_bytes,
     "base64url": _deserialize_bytes_base64,
+    "duration-seconds-int": functools.partial(_deserialize_duration_numeric, unit="seconds"),
+    "duration-seconds-float": functools.partial(_deserialize_duration_numeric, unit="seconds"),
+    "duration-milliseconds-int": functools.partial(_deserialize_duration_numeric, unit="milliseconds"),
+    "duration-milliseconds-float": functools.partial(_deserialize_duration_numeric, unit="milliseconds"),
 }
 
 
@@ -576,7 +609,7 @@ def _serialize(o, format: typing.Optional[str] = None):  # pylint: disable=too-m
         pass
     # Last, try datetime.timedelta
     try:
-        return _timedelta_as_isostr(o)
+        return _serialize_duration(o, format)
     except AttributeError:
         # This will be raised when it hits value.total_seconds in the method above
         pass

package/generator/build/lib/pygen/codegen/templates/packaging_templates/pyproject.toml.jinja2

@@ -11,15 +11,32 @@ build-backend = "setuptools.build_meta"
 [project]
 name = "{{ options.get('package-name')|lower }}"
 {% if options.get('package-mode') %}
+{% if KEEP_FIELDS and KEEP_FIELDS.get('project.authors') %}
+authors = [
+  {% for author in KEEP_FIELDS.get('project.authors') %}
+  { {% for key, val in author.items() %}{{ key }} = {{ val|tojson }}{% if not loop.last %}, {% endif %}{% endfor %} },
+  {% endfor %}
+]
+{% else %}
 authors = [
   { name = "{{ code_model.company_name }}"{% if code_model.is_azure_flavor %}, email = "azpysdkhelp@microsoft.com"{% endif %} },
 ]
-{% if options.get("azure-arm") %}
+{% endif %}
+{% if KEEP_FIELDS and KEEP_FIELDS.get('project.description') %}
+description = {{ KEEP_FIELDS.get('project.description')|tojson }}
+{% elif options.get("azure-arm") %}
 description = "Microsoft Azure {{ options.get('package-pprint-name') }} Client Library for Python"
 {% else %}
 description = "{{ code_model.company_name }} {% if code_model.is_azure_flavor and not options.get('package-pprint-name').startswith('Azure ') %}Azure {% endif %}{{ options.get('package-pprint-name') }} Client Library for Python"
 {% endif %}
 license = "MIT"
+{% if KEEP_FIELDS and KEEP_FIELDS.get('project.classifiers') %}
+classifiers = [
+    {% for classifier in KEEP_FIELDS.get('project.classifiers') %}
+    {{ classifier|tojson }},
+    {% endfor %}
+]
+{% else %}
 classifiers = [
     "Development Status :: {{ dev_status }}",
     "Programming Language :: Python",
@@ -29,10 +46,15 @@ classifiers = [
     "Programming Language :: Python :: 3.{{ version }}",
     {% endfor %}
 ]
+{% endif %}
 requires-python = ">={{ MIN_PYTHON_VERSION }}"
 {% else %}
+{% if KEEP_FIELDS and KEEP_FIELDS.get('project.description') %}
+description = {{ KEEP_FIELDS.get('project.description')|tojson }}
+{% else %}
 description = "{{ options.get('package-name') }}"
 {% endif %}
+{% endif %}
 {% if code_model.is_azure_flavor %}
 keywords = ["azure", "azure sdk"]
 {% endif %}
@@ -77,7 +99,13 @@ version = "{{ options.get("package-version", "unknown") }}"
 ]
 {% endfor %}
 {% endif %}
-{% if code_model.is_azure_flavor %}
+{% if KEEP_FIELDS and KEEP_FIELDS.get('project.urls') %}
+
+[project.urls]
+{% for key, val in KEEP_FIELDS.get('project.urls').items() %}
+{{ key }} = {{ val|tojson }}
+{% endfor %}
+{% elif code_model.is_azure_flavor %}
 
 [project.urls]
 repository = "https://github.com/Azure/azure-sdk-for-python"

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

@@ -516,6 +516,10 @@ class Serializer:  # pylint: disable=too-many-public-methods
             "rfc-1123": Serializer.serialize_rfc,
             "unix-time": Serializer.serialize_unix,
             "duration": Serializer.serialize_duration,
+            "duration-seconds-int": Serializer.serialize_duration_seconds_int,
+            "duration-seconds-float": Serializer.serialize_duration_seconds_float,
+            "duration-milliseconds-int": Serializer.serialize_duration_milliseconds_int,
+            "duration-milliseconds-float": Serializer.serialize_duration_milliseconds_float,
             "date": Serializer.serialize_date,
             "time": Serializer.serialize_time,
             "decimal": Serializer.serialize_decimal,
@@ -1105,6 +1109,61 @@ class Serializer:  # pylint: disable=too-many-public-methods
             attr = isodate.parse_duration(attr)
         return isodate.duration_isoformat(attr)
 
+    @staticmethod
+    def _serialize_duration_numeric(attr, scale, as_int):
+        """Serialize a TimeDelta into a numeric value scaled to the wire unit.
+
+        :param TimeDelta attr: Object to be serialized.
+        :param int scale: Multiplier applied to total seconds (1 for seconds, 1000 for milliseconds).
+        :param bool as_int: Whether to truncate the result to an int.
+        :rtype: int or float
+        :return: serialized duration
+        """
+        if isinstance(attr, str):
+            attr = isodate.parse_duration(attr)
+        value = attr.total_seconds() * scale if isinstance(attr, datetime.timedelta) else attr
+        return int(value) if as_int else float(value)
+
+    @staticmethod
+    def serialize_duration_seconds_int(attr, **kwargs):  # pylint: disable=unused-argument
+        """Serialize TimeDelta object into an integer number of seconds.
+
+        :param TimeDelta attr: Object to be serialized.
+        :rtype: int
+        :return: serialized duration
+        """
+        return Serializer._serialize_duration_numeric(attr, 1, True)
+
+    @staticmethod
+    def serialize_duration_seconds_float(attr, **kwargs):  # pylint: disable=unused-argument
+        """Serialize TimeDelta object into a floating point number of seconds.
+
+        :param TimeDelta attr: Object to be serialized.
+        :rtype: float
+        :return: serialized duration
+        """
+        return Serializer._serialize_duration_numeric(attr, 1, False)
+
+    @staticmethod
+    def serialize_duration_milliseconds_int(attr, **kwargs):  # pylint: disable=unused-argument
+        """Serialize TimeDelta object into an integer number of milliseconds.
+
+        :param TimeDelta attr: Object to be serialized.
+        :rtype: int
+        :return: serialized duration
+        """
+        return Serializer._serialize_duration_numeric(attr, 1000, True)
+
+    @staticmethod
+    def serialize_duration_milliseconds_float(attr, **kwargs):  # pylint: disable=unused-argument
+        """Serialize TimeDelta object into a floating point number of milliseconds.
+
+        :param TimeDelta attr: Object to be serialized.
+        :rtype: float
+        :return: serialized duration
+        """
+        return Serializer._serialize_duration_numeric(attr, 1000, False)
+
     @staticmethod
     def serialize_rfc(attr, **kwargs):  # pylint: disable=unused-argument
         """Serialize Datetime object into RFC-1123 formatted string.
@@ -1377,6 +1436,10 @@ class Deserializer:
             "rfc-1123": Deserializer.deserialize_rfc,
             "unix-time": Deserializer.deserialize_unix,
             "duration": Deserializer.deserialize_duration,
+            "duration-seconds-int": Deserializer.deserialize_duration_seconds,
+            "duration-seconds-float": Deserializer.deserialize_duration_seconds,
+            "duration-milliseconds-int": Deserializer.deserialize_duration_milliseconds,
+            "duration-milliseconds-float": Deserializer.deserialize_duration_milliseconds,
             "date": Deserializer.deserialize_date,
             "time": Deserializer.deserialize_time,
             "decimal": Deserializer.deserialize_decimal,
@@ -1389,6 +1452,10 @@ class Deserializer:
         }
         self.deserialize_expected_types = {
             "duration": (isodate.Duration, datetime.timedelta),
+            "duration-seconds-int": (isodate.Duration, datetime.timedelta),
+            "duration-seconds-float": (isodate.Duration, datetime.timedelta),
+            "duration-milliseconds-int": (isodate.Duration, datetime.timedelta),
+            "duration-milliseconds-float": (isodate.Duration, datetime.timedelta),
             "iso-8601": (datetime.datetime),
         }
         self.dependencies: dict[str, type] = dict(classes) if classes else {}
@@ -1950,6 +2017,48 @@ class Deserializer:
             raise DeserializationError(msg) from err
         return duration
 
+    @staticmethod
+    def _deserialize_duration_numeric(attr, unit):
+        """Deserialize a numeric duration value into a TimeDelta object.
+
+        :param float attr: response value to be deserialized.
+        :param str unit: The wire unit, used as the ``timedelta`` keyword
+            (``"seconds"`` or ``"milliseconds"``).
+        :return: Deserialized duration
+        :rtype: TimeDelta
+        :raises DeserializationError: if value is invalid.
+        """
+        if isinstance(attr, ET.Element):
+            attr = attr.text
+        try:
+            duration = datetime.timedelta(**{unit: float(attr)})  # type: ignore
+        except (ValueError, OverflowError, TypeError) as err:
+            msg = "Cannot deserialize duration object."
+            raise DeserializationError(msg) from err
+        return duration
+
+    @staticmethod
+    def deserialize_duration_seconds(attr):
+        """Deserialize a numeric number of seconds into a TimeDelta object.
+
+        :param float attr: response value to be deserialized.
+        :return: Deserialized duration
+        :rtype: TimeDelta
+        :raises DeserializationError: if value is invalid.
+        """
+        return Deserializer._deserialize_duration_numeric(attr, "seconds")
+
+    @staticmethod
+    def deserialize_duration_milliseconds(attr):
+        """Deserialize a numeric number of milliseconds into a TimeDelta object.
+
+        :param float attr: response value to be deserialized.
+        :return: Deserialized duration
+        :rtype: TimeDelta
+        :raises DeserializationError: if value is invalid.
+        """
+        return Deserializer._deserialize_duration_numeric(attr, "milliseconds")
+
     @staticmethod
     def deserialize_date(attr):
         """Deserialize ISO-8601 formatted string into Date object.