@typespec/http-client-python 0.28.2 → 0.29.0

package/generator/pygen/__init__.py

@@ -16,7 +16,6 @@ from .utils import TYPESPEC_PACKAGE_MODE, VALID_PACKAGE_MODE
 
 from ._version import VERSION
 
-
 __version__ = VERSION
 _LOGGER = logging.getLogger(__name__)
 
@@ -237,8 +236,7 @@ class ReaderAndWriter:
     def write_file(self, filename: Union[str, Path], file_content: str) -> None:
         """Directly writing to disk"""
         file_folder = Path(filename).parent
-        if not Path.is_dir(self.output_folder / file_folder):
-            Path.mkdir(self.output_folder / file_folder, parents=True)
+        Path.mkdir(self.output_folder / file_folder, parents=True, exist_ok=True)
         with open(self.output_folder / Path(filename), "w", encoding="utf-8") as fd:
             fd.write(file_content)
 

package/generator/pygen/codegen/__init__.py

@@ -13,7 +13,6 @@ from ..utils import parse_args
 from .models.code_model import CodeModel
 from .serializers import JinjaSerializer
 
-
 _LOGGER = logging.getLogger(__name__)
 
 

package/generator/pygen/codegen/models/base.py

@@ -7,7 +7,6 @@ from typing import Any, TYPE_CHECKING, Optional
 from abc import ABC, abstractmethod
 from .imports import FileImport
 
-
 if TYPE_CHECKING:
     from .code_model import CodeModel
     from .model_type import ModelType

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

@@ -291,11 +291,12 @@ class Client(_ClientConfigBase[ClientGlobalParameterList]):
                 ImportType.SDKCORE,
             )
 
-        # import for "Self"
+        # import for "Self" (typing.Self available from Python 3.11+)
         file_import.add_submodule_import(
             "typing_extensions",
             "Self",
             ImportType.STDLIB,
+            version_modules=(((3, 11), "typing", None),),
         )
         if self.need_cloud_setting:
             file_import.add_submodule_import("typing", "cast", ImportType.STDLIB)

package/generator/pygen/codegen/models/code_model.py

@@ -95,6 +95,7 @@ class CodeModel:  # pylint: disable=too-many-public-methods, disable=too-many-in
             t for t in self.types_map.values() if isinstance(t, CombinedType) and t.name
         ]
         self.cross_language_package_id = self.yaml_data.get("crossLanguagePackageId")
+        self.cross_language_version = self.yaml_data.get("crossLanguageVersion")
         self.for_test: bool = False
         # key is typespec namespace, value is models/clients/opeartion_groups/enums cache in the namespace
         self._client_namespace_types: dict[str, ClientNamespaceType] = {}

package/generator/pygen/codegen/models/enum_type.py

@@ -10,7 +10,6 @@ from .imports import FileImport, ImportType, TypingSection
 from .utils import NamespaceType, add_to_pylint_disable
 from ...utils import NAME_LENGTH_LIMIT
 
-
 if TYPE_CHECKING:
     from .code_model import CodeModel
 

package/generator/pygen/codegen/models/model_type.py

@@ -5,8 +5,7 @@
 # --------------------------------------------------------------------------
 from enum import Enum
 from collections import OrderedDict
-from typing import Any, Optional, TYPE_CHECKING, cast
-import sys
+from typing import Any, Literal, Optional, TYPE_CHECKING, cast
 from .utils import add_to_pylint_disable, NamespaceType, LOCALS_LENGTH_LIMIT
 from .base import BaseType
 from .constant_type import ConstantType
@@ -14,11 +13,6 @@ from .property import Property
 from .imports import FileImport, ImportType, TypingSection
 from ...utils import NAME_LENGTH_LIMIT
 
-if sys.version_info >= (3, 8):
-    from typing import Literal
-else:
-    from typing_extensions import Literal  # type: ignore
-
 if TYPE_CHECKING:
     from .code_model import CodeModel
 

package/generator/pygen/codegen/models/parameter.py

@@ -61,6 +61,7 @@ class _ParameterBase(BaseModel, abc.ABC):  # pylint: disable=too-many-instance-a
     ) -> 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)
@@ -108,25 +109,24 @@ class _ParameterBase(BaseModel, abc.ABC):  # pylint: disable=too-many-instance-a
         type_description = self.type.description(is_operation_file=True)
         if type_description:
             base_description = add_to_description(base_description, type_description)
-        if self.optional and isinstance(self.type, ConstantType):
-            if self.is_api_version:
-                base_description = add_to_description(
-                    base_description,
-                    f"Known values are {self.get_declaration()}.",
-                )
-            else:
-                base_description = add_to_description(
-                    base_description,
-                    f"Known values are {self.get_declaration()} and None.",
-                )
+        if (self.optional or self.is_api_version) and isinstance(self.type, ConstantType):
+            base_description = add_to_description(
+                base_description,
+                f"Known values are {self.get_declaration()} and None.",
+            )
         if not (self.optional or self.client_default_value):
             base_description = add_to_description(base_description, "Required.")
-        if self.client_default_value is not None:
+        if self.is_api_version:
+            base_description = add_to_description(
+                base_description,
+                "Default value is None. If not set, the operation's default API version will be used.",
+            )
+        elif self.client_default_value is not None:
             base_description = add_to_description(
                 base_description,
                 f"Default value is {self.client_default_value_declaration}.",
             )
-        if self.optional and self.client_default_value is None:
+        elif self.optional:
             base_description = add_to_description(
                 base_description,
                 f"Default value is {self.client_default_value_declaration}.",
@@ -378,6 +378,8 @@ class ClientParameter(Parameter):
     def method_location(self) -> ParameterMethodLocation:
         if self.constant:
             return ParameterMethodLocation.KWARG
+        if self.is_api_version:
+            return ParameterMethodLocation.KWARG
         if (
             self.is_host
             and (self.code_model.options["version-tolerant"] or self.code_model.options["low-level-client"])
@@ -409,6 +411,6 @@ class ConfigParameter(Parameter):
 
     @property
     def method_location(self) -> ParameterMethodLocation:
-        if self.constant:
+        if self.constant or self.is_api_version:
             return ParameterMethodLocation.KWARG
         return ParameterMethodLocation.POSITIONAL

package/generator/pygen/codegen/serializers/__init__.py

@@ -42,15 +42,15 @@ __all__ = [
     "JinjaSerializer",
 ]
 
-_PACKAGE_FILES = [
+_DEFAULT_PACKAGE_FILES = (
     "CHANGELOG.md.jinja2",
     "dev_requirements.txt.jinja2",
     "LICENSE.jinja2",
     "MANIFEST.in.jinja2",
     "README.md.jinja2",
-]
+)
 
-_REGENERATE_FILES = {"MANIFEST.in"}
+_DEFAULT_REGENERATE_FILES = frozenset({"MANIFEST.in"})
 AsyncInfo = namedtuple("AsyncInfo", ["async_mode", "async_path"])
 
 
@@ -75,15 +75,17 @@ class JinjaSerializer(ReaderAndWriter):
     ) -> None:
         super().__init__(output_folder=output_folder, **kwargs)
         self.code_model = code_model
+        self._package_files: list[str] = list(_DEFAULT_PACKAGE_FILES)
+        self._regenerate_files: set[str] = set(_DEFAULT_REGENERATE_FILES)
         self._regenerate_setup_py()
 
     def _regenerate_setup_py(self):
         if self.code_model.options["keep-setup-py"] or self.code_model.options["basic-setup-py"]:
-            _PACKAGE_FILES.append("setup.py.jinja2")
-            _REGENERATE_FILES.add("setup.py")
+            self._package_files.append("setup.py.jinja2")
+            self._regenerate_files.add("setup.py")
         else:
-            _PACKAGE_FILES.append("pyproject.toml.jinja2")
-            _REGENERATE_FILES.add("pyproject.toml")
+            self._package_files.append("pyproject.toml.jinja2")
+            self._regenerate_files.add("pyproject.toml")
 
     @property
     def has_aio_folder(self) -> bool:
@@ -180,6 +182,17 @@ class JinjaSerializer(ReaderAndWriter):
             elif client_namespace_type.clients:
                 # add clients folder if there are clients in this namespace
                 self._serialize_client_and_config_files(client_namespace, client_namespace_type.clients, env)
+                # When generation-subdir is configured, generated code goes into a subdirectory
+                # (e.g., _generated/). We also need an __init__.py in the parent namespace dir
+                # so that the package is discoverable by find_packages() / pip install.
+                root_dir = self.code_model.get_root_dir()
+                if self.code_model.options.get("generation-subdir") and not self.read_file(
+                    root_dir / Path("__init__.py")
+                ):
+                    self.write_file(
+                        root_dir / Path("__init__.py"),
+                        general_serializer.serialize_pkgutil_init_file(),
+                    )
             else:
                 # add pkgutil init file if no clients in this namespace
                 self.write_file(
@@ -242,7 +255,7 @@ class JinjaSerializer(ReaderAndWriter):
                 lstrip_blocks=True,
             )
 
-            package_files = _PACKAGE_FILES
+            package_files = list(self._package_files)
             if not self.code_model.license_description:
                 package_files.remove("LICENSE.jinja2")
         elif Path(self.code_model.options["package-mode"]).exists():
@@ -261,7 +274,7 @@ class JinjaSerializer(ReaderAndWriter):
                 continue
             file = template_name.replace(".jinja2", "")
             output_file = root_of_sdk / file
-            if not self.read_file(output_file) or file in _REGENERATE_FILES:
+            if not self.read_file(output_file) or file in self._regenerate_files:
                 if self.keep_version_file and file == "setup.py" and not self.code_model.options["azure-arm"]:
                     # don't regenerate setup.py file if the version file is more up to date for data-plane
                     continue
@@ -482,32 +495,34 @@ class JinjaSerializer(ReaderAndWriter):
 
     def _serialize_and_write_top_level_folder(self, env: Environment, namespace: str) -> None:
         root_dir = self.code_model.get_root_dir()
+        generation_dir = self.code_model.get_generation_dir(namespace)
         # write _utils folder
         self._serialize_and_write_utils_folder(env, self.code_model.namespace)
 
         general_serializer = GeneralSerializer(code_model=self.code_model, env=env, async_mode=False)
 
         # write _version.py
+        # Always write at root namespace since pyproject.toml references it there
         self._serialize_and_write_version_file(general_serializer)
-        # if there's a subdir, we need to write another version file in the subdir
         if self.code_model.options.get("generation-subdir"):
             self._serialize_and_write_version_file(general_serializer, namespace)
 
         # write the empty py.typed file
+        # Always write at root namespace since MANIFEST.in references it there
         pytyped_value = "# Marker file for PEP 561."
         self.write_file(root_dir / Path("py.typed"), pytyped_value)
 
         # write _validation.py
         if any(og for client in self.code_model.clients for og in client.operation_groups if og.need_validation):
             self.write_file(
-                root_dir / Path("_validation.py"),
+                generation_dir / Path("_validation.py"),
                 general_serializer.serialize_validation_file(),
             )
 
         # write _types.py
         if self.code_model.named_unions:
             self.write_file(
-                root_dir / Path("_types.py"),
+                generation_dir / Path("_types.py"),
                 TypesSerializer(code_model=self.code_model, env=env).serialize(),
             )
 

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

@@ -107,10 +107,18 @@ def _serialize_grouped_body(builder: BuilderType) -> list[str]:
     groupers = [p for p in builder.parameters if p.grouper]
     for grouper in groupers:
         retval.append(f"if {grouper.client_name} is not None:")
+        # Keys in property_to_parameter_name are original client names (e.g. "from", "custom_header").
+        # Attribute access needs the padded client_name from the model property (e.g. "from_property").
+        # Build lookup from both wire_name and client_name to handle all cases.
+        grouper_model = cast(ModelType, grouper.type)
+        prop_name_to_client = {}
+        for prop in grouper_model.properties:
+            prop_name_to_client[prop.wire_name] = prop.client_name
+            prop_name_to_client[prop.client_name] = prop.client_name
         retval.extend(
             [
-                f"    {parameter} = {grouper.client_name}.{property}"
-                for property, parameter in grouper.property_to_parameter_name.items()
+                f"    {parameter} = {grouper.client_name}.{prop_name_to_client[prop_name]}"
+                for prop_name, parameter in grouper.property_to_parameter_name.items()
             ]
         )
     return retval
@@ -1353,7 +1361,8 @@ class _PagingOperationSerializer(_OperationSerializer[PagingOperationType]):
         except StopIteration:
             pass
 
-        retval.append(f'_request = HttpRequest("{builder.next_link_verb}", {next_link_str}{query_str})')
+        header_str = ", headers=_headers"
+        retval.append(f'_request = HttpRequest("{builder.next_link_verb}", {next_link_str}{header_str}{query_str})')
         retval.extend(self._postprocess_http_request(builder, "_request.url"))
 
         return retval

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

@@ -28,7 +28,7 @@ VERSION_MAP = {
     "corehttp": "1.0.0b6",
 }
 
-MIN_PYTHON_VERSION = "3.9"
+MIN_PYTHON_VERSION = "3.10"
 MAX_PYTHON_VERSION = "3.13"
 
 
@@ -155,7 +155,10 @@ class GeneralSerializer(BaseSerializer):
             "VERSION_MAP": VERSION_MAP,
             "MIN_PYTHON_VERSION": MIN_PYTHON_VERSION,
             "MAX_PYTHON_VERSION": MAX_PYTHON_VERSION,
-            "ADDITIONAL_DEPENDENCIES": [f"{item[0]}>={item[1]}" for item in additional_version_map.items()],
+            "ADDITIONAL_DEPENDENCIES": [
+                dep if dep.startswith('"') else f'"{dep}"'
+                for dep in (f"{item[0]}>={item[1]}" for item in additional_version_map.items())
+            ],
         }
         params |= {"options": self.code_model.options}
         params |= kwargs
@@ -326,6 +329,7 @@ class GeneralSerializer(BaseSerializer):
             {
                 "CrossLanguagePackageId": self.code_model.cross_language_package_id,
                 "CrossLanguageDefinitionId": cross_langauge_def_dict,
+                "CrossLanguageVersion": self.code_model.cross_language_version,
             },
             indent=4,
         )

package/generator/pygen/codegen/serializers/import_serializer.py

@@ -50,20 +50,25 @@ def _serialize_import_type(imports: list[ImportModel], delimiter: str) -> str:
     import_list = []
     for module_name in sorted(set(i.module_name for i in imports)):
         normal_imports = [i for i in imports if i.module_name == module_name and not i.version_modules]
-        versioned_imports = [i for i in imports if i.module_name == module_name and i.version_modules]
         if normal_imports:
             import_list.append(_serialize_package(normal_imports, delimiter))
-        for i in versioned_imports:
-            import_list.append(_serialize_versioned_package(i, delimiter))
     return delimiter.join(import_list)
 
 
+def _serialize_versioned_imports(imports: list[ImportModel], delimiter: str) -> str:
+    """Serialize all versioned imports together, to be emitted after all regular imports."""
+    return delimiter.join(_serialize_versioned_package(i, delimiter) for i in imports if i.version_modules)
+
+
 def _get_import_clauses(imports: list[ImportModel], delimiter: str) -> list[str]:
     import_clause = []
     for import_type in ImportType:
-        imports_with_import_type = [i for i in imports if i.import_type == import_type]
+        imports_with_import_type = [i for i in imports if i.import_type == import_type and not i.version_modules]
         if imports_with_import_type:
             import_clause.append(_serialize_import_type(imports_with_import_type, delimiter))
+    versioned = [i for i in imports if i.version_modules]
+    if versioned:
+        import_clause.append(_serialize_versioned_imports(versioned, delimiter))
     return import_clause
 
 
@@ -79,6 +84,13 @@ class FileImportSerializer:
         if any(self.file_import.get_imports_from_section(TypingSection.TYPING)):
             self.file_import.add_submodule_import("typing", "TYPE_CHECKING", ImportType.STDLIB)
 
+    def _add_sys_import_if_needed(self):
+        all_imports = list(self.file_import.get_imports_from_section(TypingSection.REGULAR)) + list(
+            self.file_import.get_imports_from_section(TypingSection.TYPING)
+        )
+        if any(i.version_modules for i in all_imports):
+            self.file_import.add_import("sys", ImportType.STDLIB)
+
     def get_typing_definitions(self) -> str:
         def declare_definition(type_name: str, type_definition: TypeDefinition) -> list[str]:
             ret: list[str] = []
@@ -95,6 +107,7 @@ class FileImportSerializer:
 
     def __str__(self) -> str:
         self._add_type_checking_import()
+        self._add_sys_import_if_needed()
         regular_imports = ""
         regular_imports_list = self._get_imports_list(TypingSection.REGULAR)
 

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

@@ -39,16 +39,6 @@ SPECIAL_HEADER_SERIALIZATION: dict[str, list[str]] = {
     "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 @@ class ParameterSerializer:
         ):
             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,
@@ -202,11 +206,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:
+            if kwarg.client_default_value is not None or kwarg.optional or kwarg.constant or kwarg.is_api_version:
                 if check_client_input and kwarg.check_client_input:
                     default_value = f"self._config.{kwarg.client_name}"
                 elif kwarg.constant:
                     default_value = kwarg.type.get_declaration(None)
+                elif kwarg.is_api_version and kwarg.client_default_value is None and kwarg.api_versions:
+                    default_value = f'"{kwarg.api_versions[-1]}"'
                 else:
                     default_value = kwarg.client_default_value_declaration
                 if check_kwarg_dict and (kwarg.location in [ParameterLocation.HEADER, ParameterLocation.QUERY]):