@typespec/http-client-python 0.4.3 → 0.5.0

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

@@ -0,0 +1,204 @@
+# -------------------------------------------------------------------------
+# Copyright (c) Microsoft Corporation. All rights reserved.
+# Licensed under the MIT License. See License.txt in the project root for
+# license information.
+# --------------------------------------------------------------------------
+import logging
+from typing import Any, Dict, Union, Optional
+from .base import BaseModel
+from .base_builder import BaseBuilder, ParameterListType
+from .code_model import CodeModel
+from .client import Client
+from .model_type import ModelType, JSONModelType, DPGModelType, MsrestModelType
+from .dictionary_type import DictionaryType
+from .list_type import ListType
+from .combined_type import CombinedType
+from .primitive_types import (
+    ByteArraySchema,
+    DateType,
+    DatetimeType,
+    DurationType,
+    IntegerType,
+    FloatType,
+    StringType,
+    TimeType,
+    AnyType,
+    PrimitiveType,
+    BinaryType,
+    BooleanType,
+    AnyObjectType,
+    UnixTimeType,
+    SdkCoreType,
+    DecimalType,
+    MultiPartFileType,
+)
+from .enum_type import EnumType, EnumValue
+from .base import BaseType
+from .constant_type import ConstantType
+from .imports import FileImport, ImportType, TypingSection
+from .lro_operation import LROOperation
+from .paging_operation import PagingOperation
+from .parameter import (
+    Parameter,
+    ParameterMethodLocation,
+    ParameterLocation,
+    BodyParameter,
+    ParameterDelimeter,
+    ClientParameter,
+    ConfigParameter,
+)
+from .operation import Operation
+from .property import Property
+from .operation_group import OperationGroup
+from .response import Response
+from .parameter_list import (
+    ParameterList,
+    ClientGlobalParameterList,
+    ConfigGlobalParameterList,
+)
+from .request_builder import (
+    RequestBuilder,
+    OverloadedRequestBuilder,
+    RequestBuilderBase,
+)
+from .lro_paging_operation import LROPagingOperation
+from .request_builder_parameter import (
+    RequestBuilderParameter,
+    RequestBuilderBodyParameter,
+)
+from .credential_types import (
+    TokenCredentialType,
+    KeyCredentialType,
+    ARMChallengeAuthenticationPolicyType,
+    BearerTokenCredentialPolicyType,
+    KeyCredentialPolicyType,
+    CredentialType,
+)
+
+__all__ = [
+    "KeyCredentialPolicyType",
+    "AnyType",
+    "BaseModel",
+    "BaseType",
+    "CodeModel",
+    "Client",
+    "ConstantType",
+    "ModelType",
+    "DictionaryType",
+    "ListType",
+    "EnumType",
+    "EnumValue",
+    "FileImport",
+    "ImportType",
+    "TypingSection",
+    "PrimitiveType",
+    "LROOperation",
+    "Operation",
+    "PagingOperation",
+    "Parameter",
+    "ParameterList",
+    "OperationGroup",
+    "Property",
+    "RequestBuilder",
+    "Response",
+    "TokenCredentialType",
+    "LROPagingOperation",
+    "BaseBuilder",
+    "RequestBuilderParameter",
+    "BinaryType",
+    "ClientGlobalParameterList",
+    "ConfigGlobalParameterList",
+    "ParameterMethodLocation",
+    "ParameterLocation",
+    "OverloadedRequestBuilder",
+    "RequestBuilderBase",
+    "BodyParameter",
+    "RequestBuilderBodyParameter",
+    "ParameterDelimeter",
+    "CredentialType",
+    "ClientParameter",
+    "ConfigParameter",
+    "ParameterListType",
+]
+
+TYPE_TO_OBJECT = {
+    "integer": IntegerType,
+    "float": FloatType,
+    "decimal": DecimalType,
+    "string": StringType,
+    "list": ListType,
+    "dict": DictionaryType,
+    "constant": ConstantType,
+    "enum": EnumType,
+    "enumvalue": EnumValue,
+    "binary": BinaryType,
+    "any": AnyType,
+    "utcDateTime": DatetimeType,
+    "offsetDateTime": DatetimeType,
+    "plainTime": TimeType,
+    "duration": DurationType,
+    "plainDate": DateType,
+    "bytes": ByteArraySchema,
+    "boolean": BooleanType,
+    "combined": CombinedType,
+    "OAuth2": TokenCredentialType,
+    "Key": KeyCredentialType,
+    "ARMChallengeAuthenticationPolicy": ARMChallengeAuthenticationPolicyType,
+    "BearerTokenCredentialPolicy": BearerTokenCredentialPolicyType,
+    "KeyCredentialPolicy": KeyCredentialPolicyType,
+    "any-object": AnyObjectType,
+    "unixtime": UnixTimeType,
+    "credential": StringType,
+    "sdkcore": SdkCoreType,
+    "multipartfile": MultiPartFileType,
+}
+_LOGGER = logging.getLogger(__name__)
+
+
+def build_type(yaml_data: Dict[str, Any], code_model: CodeModel) -> BaseType:
+    yaml_id = id(yaml_data)
+    try:
+        return code_model.lookup_type(yaml_id)
+    except KeyError:
+        # Not created yet, let's create it and add it to the index
+        pass
+    response: Optional[BaseType] = None
+    if yaml_data["type"] == "model":
+        # need to special case model to avoid recursion
+        if yaml_data["base"] == "json" or not code_model.options["models_mode"]:
+            model_type = JSONModelType
+        elif yaml_data["base"] == "dpg":
+            model_type = DPGModelType  # type: ignore
+        else:
+            model_type = MsrestModelType  # type: ignore
+        response = model_type(yaml_data, code_model)
+        code_model.types_map[yaml_id] = response
+        response.fill_instance_from_yaml(yaml_data, code_model)
+    elif yaml_data["type"] == "enum":
+        # avoid recursion because we add the parent enum type to the enum value
+        response = EnumType(
+            yaml_data,
+            code_model,
+            values=[],
+            value_type=build_type(yaml_data["valueType"], code_model),
+        )
+        code_model.types_map[yaml_id] = response
+        response.fill_instance_from_yaml(yaml_data, code_model)
+    else:
+        object_type = yaml_data.get("type")
+        if object_type not in TYPE_TO_OBJECT:
+            _LOGGER.warning(
+                'Unrecognized definition type "%s" is found, falling back it as "string"! ',
+                yaml_data["type"],
+            )
+            object_type = "string"
+        response = TYPE_TO_OBJECT[object_type].from_yaml(yaml_data, code_model)  # type: ignore
+    if response is None:
+        raise ValueError("response can not be None")
+    code_model.types_map[yaml_id] = response
+    return response
+
+
+RequestBuilderType = Union[RequestBuilder, OverloadedRequestBuilder]
+ParameterType = Union[Parameter, RequestBuilderParameter, ClientParameter, ConfigParameter]
+OperationType = Union[Operation, LROOperation, PagingOperation, LROPagingOperation]

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

@@ -0,0 +1,186 @@
+# -------------------------------------------------------------------------
+# Copyright (c) Microsoft Corporation. All rights reserved.
+# Licensed under the MIT License. See License.txt in the project root for
+# license information.
+# --------------------------------------------------------------------------
+from typing import Any, Dict, TYPE_CHECKING, List, Optional
+from abc import ABC, abstractmethod
+from .imports import FileImport
+
+
+if TYPE_CHECKING:
+    from .code_model import CodeModel
+    from .model_type import ModelType
+
+
+class BaseModel:
+    """This is the base class for model representations that are based on some YAML data.
+
+    :param yaml_data: the yaml data for this schema
+    :type yaml_data: dict[str, Any]
+    """
+
+    def __init__(self, yaml_data: Dict[str, Any], code_model: "CodeModel") -> None:
+        self.yaml_data = yaml_data
+        self.code_model = code_model
+
+    @property
+    def id(self) -> int:
+        return id(self.yaml_data)
+
+    def __repr__(self):
+        return f"<{self.__class__.__name__}>"
+
+
+class BaseType(BaseModel, ABC):  # pylint: disable=too-many-public-methods
+    """This is the base class for all types.
+
+    :param yaml_data: the yaml data for this schema
+    :type yaml_data: dict[str, Any]
+    """
+
+    def __init__(self, yaml_data: Dict[str, Any], code_model: "CodeModel") -> None:
+        super().__init__(yaml_data, code_model)
+        self.type = yaml_data["type"]  # the type discriminator
+        self.api_versions: List[str] = yaml_data.get("apiVersions", [])  # api versions this type is in.
+
+    @classmethod
+    def from_yaml(cls, yaml_data: Dict[str, Any], code_model: "CodeModel") -> "BaseType":
+        return cls(yaml_data=yaml_data, code_model=code_model)
+
+    def imports(self, **kwargs) -> FileImport:  # pylint: disable=unused-argument
+        return FileImport(self.code_model)
+
+    def imports_for_multiapi(self, **kwargs: Any) -> FileImport:
+        return self.imports(**kwargs)
+
+    def imports_for_sample(self) -> FileImport:
+        return FileImport(self.code_model)
+
+    @staticmethod
+    def serialize_sample_value(value: Any) -> str:
+        return repr(value)
+
+    @property
+    def xml_metadata(self) -> Dict[str, Any]:
+        """XML metadata for the type, if the type has it."""
+        return self.yaml_data.get("xmlMetadata", {})
+
+    @property
+    def is_xml(self) -> bool:
+        """Whether the type is an XML type or not. Most likely not."""
+        return bool(self.xml_metadata)
+
+    @property
+    def xml_serialization_ctxt(self) -> Optional[str]:
+        """Return the serialization context in case this schema is used in an operation."""
+        attrs_list = []
+        if self.xml_metadata.get("name"):
+            attrs_list.append(f"'name': '{self.xml_metadata['name']}'")
+        if self.xml_metadata.get("attribute", False):
+            attrs_list.append("'attr': True")
+        if self.xml_metadata.get("prefix", False):
+            attrs_list.append(f"'prefix': '{self.xml_metadata['prefix']}'")
+        if self.xml_metadata.get("namespace", False):
+            attrs_list.append(f"'ns': '{self.xml_metadata['namespace']}'")
+        if self.xml_metadata.get("text"):
+            attrs_list.append("'text': True")
+        return ", ".join(attrs_list)
+
+    @property
+    def serialization_type(self) -> str:
+        """The tag recognized by 'msrest' as a serialization/deserialization.
+
+        'str', 'int', 'float', 'bool' or
+        https://github.com/Azure/msrest-for-python/blob/b505e3627b547bd8fdc38327e86c70bdb16df061/msrest/serialization.py#L407-L416
+
+        or the object schema name (e.g. DotSalmon).
+
+        If list: '[str]'
+        If dict: '{str}'
+        """
+        raise NotImplementedError()
+
+    @property
+    def msrest_deserialization_key(self) -> str:
+        return self.serialization_type
+
+    @property
+    def client_default_value(self) -> Any:
+        """Whether there's a client default value for this type"""
+        return self.yaml_data.get("clientDefaultValue")
+
+    @abstractmethod
+    def description(self, *, is_operation_file: bool) -> str:
+        """The description"""
+
+    @abstractmethod
+    def docstring_text(self, **kwargs: Any) -> str:
+        """The names used in rtype documentation"""
+
+    @abstractmethod
+    def docstring_type(self, **kwargs: Any) -> str:
+        """The python type used for RST syntax input.
+
+        Special case for enum, for instance: 'str or ~namespace.EnumName'
+        """
+
+    @abstractmethod
+    def type_annotation(self, **kwargs: Any) -> str:
+        """The python type used for type annotation
+
+        Special case for enum, for instance: Union[str, "EnumName"]
+        """
+
+    @property
+    def validation(self) -> Optional[Dict[str, Any]]:
+        """Whether there's any validation constraints on this type.
+
+        Even though we generate validation maps if there are validation constraints,
+        only SDKs with client-side-validate=true (0.001% libraries, if any) actually raise in this case.
+        """
+        return None
+
+    def get_declaration(self, value: Any) -> str:
+        """Return the current value from YAML as a Python string that represents the constant.
+
+        Example, if schema is "bytearray" and value is "foo",
+        should return bytearray("foo", encoding="utf-8")
+        as a string.
+
+        This is important for constant serialization.
+
+        By default, return value, since it works sometimes (integer)
+        """
+        return str(value)
+
+    @abstractmethod
+    def get_json_template_representation(
+        self,
+        *,
+        client_default_value_declaration: Optional[str] = None,
+    ) -> Any:
+        """Template of what this schema would look like as JSON input"""
+
+    def get_polymorphic_subtypes(
+        self, polymorphic_subtypes: List["ModelType"]  # pylint: disable=unused-argument
+    ) -> None:
+        return None
+
+    @property
+    @abstractmethod
+    def instance_check_template(self) -> str:
+        """Template of what an instance check of a variable for this type would look like"""
+
+    @property
+    def serialization_constraints(self) -> List[str]:
+        """Whether there are any serialization constraints when serializing this type."""
+        return []
+
+    @property
+    def type_description(self) -> str:
+        return self.type_annotation()
+
+    @property
+    def is_form_data(self) -> bool:
+        return False

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

@@ -0,0 +1,118 @@
+# -------------------------------------------------------------------------
+# Copyright (c) Microsoft Corporation. All rights reserved.
+# Licensed under the MIT License. See License.txt in the project root for
+# license information.
+# --------------------------------------------------------------------------
+import logging
+from typing import (
+    List,
+    Dict,
+    Any,
+    Generic,
+    TypeVar,
+    Optional,
+    Union,
+    TYPE_CHECKING,
+    cast,
+)
+from abc import abstractmethod
+
+from .base import BaseModel
+from .parameter_list import (
+    ParameterList,
+    RequestBuilderParameterList,
+    OverloadedRequestBuilderParameterList,
+)
+
+ParameterListType = TypeVar(
+    "ParameterListType",
+    bound=Union[
+        ParameterList,
+        RequestBuilderParameterList,
+        OverloadedRequestBuilderParameterList,
+    ],
+)
+if TYPE_CHECKING:
+    from .code_model import CodeModel
+    from .client import Client
+    from .operation import Operation
+    from .request_builder import RequestBuilder
+
+
+OverloadListType = TypeVar("OverloadListType", bound=Union[List["Operation"], List["RequestBuilder"]])
+
+_LOGGER = logging.getLogger(__name__)
+
+
+class BaseBuilder(
+    Generic[ParameterListType, OverloadListType], BaseModel
+):  # pylint: disable=too-many-instance-attributes
+    """Base class for Operations and Request Builders"""
+
+    def __init__(
+        self,
+        yaml_data: Dict[str, Any],
+        code_model: "CodeModel",
+        client: "Client",
+        name: str,
+        parameters: ParameterListType,
+        *,
+        overloads: Optional[OverloadListType] = None,
+    ) -> None:
+        super().__init__(yaml_data=yaml_data, code_model=code_model)
+        self.client = client
+        self.name = name
+        self._description: str = yaml_data.get("description", "")
+        self.parameters = parameters
+        self.overloads = overloads or cast(OverloadListType, [])
+        self._summary: str = yaml_data.get("summary", "")
+        self.want_tracing: bool = yaml_data.get("wantTracing", True)
+        self.group_name: str = yaml_data["groupName"]  # either operationGroup or client I am on
+        self.is_overload: bool = yaml_data["isOverload"]
+        self.api_versions: List[str] = yaml_data["apiVersions"]
+        self.added_on: Optional[str] = yaml_data.get("addedOn")
+        self.external_docs: Optional[Dict[str, Any]] = yaml_data.get("externalDocs")
+
+        if code_model.options["version_tolerant"] and yaml_data.get("abstract"):
+            _LOGGER.warning(
+                'Not going to generate operation "%s" because we are unable to generate this '
+                "type of operation right now. "
+                'Please write your own custom operation in the "_patch.py" file '
+                "following https://aka.ms/azsdk/python/dpcodegen/python/customize",
+                name,
+            )
+            self.abstract = True
+        else:
+            self.abstract = False
+
+    @property
+    def summary(self) -> Optional[str]:
+        if self.abstract:
+            return None
+        return self._summary
+
+    def pylint_disable(self, async_mode: bool) -> str:  # pylint: disable=unused-argument
+        return ""
+
+    @abstractmethod
+    def response_type_annotation(self, **kwargs) -> str: ...
+
+    @abstractmethod
+    def response_docstring_text(self, **kwargs) -> str: ...
+
+    @abstractmethod
+    def response_docstring_type(self, **kwargs) -> str: ...
+
+    @property
+    def description(self) -> str:
+        if self.abstract:
+            return (
+                f'You need to write a custom operation for "{self.name}". Please refer to '
+                "https://aka.ms/azsdk/python/dpcodegen/python/customize to learn how to customize."
+            )
+        return self._description or self.name
+
+    def method_signature(self, async_mode: bool) -> List[str]:
+        if self.abstract:
+            return ["*args,", "**kwargs"]
+        return self.parameters.method_signature(async_mode)