ucloud-sdk-python3 0.11.81__py3-none-any.whl

ucloud/core/client/_client.py

@@ -0,0 +1,176 @@
+import typing
+import logging
+import sys
+import time
+
+from ucloud import version
+from ucloud.core.client._cfg import Config
+from ucloud.core.transport import (
+    Transport,
+    RequestsTransport,
+    Request,
+    SSLOption,
+    http,
+)
+from ucloud.core.typesystem import encoder
+from ucloud.core.utils import log
+from ucloud.core.utils.middleware import Middleware
+from ucloud.core import auth, exc
+
+
+class Client:
+    def __init__(
+        self,
+        config: dict,
+        transport: typing.Optional[Transport] = None,
+        middleware: typing.Optional[Middleware] = None,
+        logger: typing.Optional[logging.Logger] = None,
+    ):
+        cfg, cred = self._parse_dict_config(config)
+        self.config = cfg
+        self.credential = cred
+        self.transport = transport or RequestsTransport()
+        self.logger = logger or log.default_logger
+        if middleware is None:
+            middleware = Middleware()
+            middleware.response(self.logged_response_handler)
+            middleware.request(self.logged_request_handler)
+            middleware.exception(self.logged_exception_handler)
+        self._middleware = middleware
+
+    def invoke(self, action: str, args: dict = None, **options) -> dict:
+        """invoke will invoke the action with arguments data and options
+
+        :param str action: the api action, like `CreateUHostInstance`
+        :param dict args: arguments of api(action), see doc: `UCloud API Documentation <https://docs.ucloud.cn/api>`__
+        :return:
+        """
+        retries = 0
+        max_retries = options.get("max_retries") or self.config.max_retries
+        timeout = options.get("timeout") or self.config.timeout
+
+        while retries <= max_retries:
+            try:
+                return self._send(
+                    action, args or {}, max_retries=max_retries, timeout=timeout
+                )
+            except exc.UCloudException as e:
+                if e.retryable and retries != max_retries:
+                    logging.info(
+                        "Retrying {action}: {args}".format(
+                            action=action, args=args
+                        )
+                    )
+                    retries += 1
+                    continue
+                raise e
+
+    @property
+    def middleware(self) -> Middleware:
+        return self._middleware
+
+    def logged_request_handler(self, req):
+        action = req.get("Action", "")
+        self.logger.info("[request] {} {}".format(action, req))
+        return req
+
+    def logged_response_handler(self, resp, http_resp: http.Response = None):
+        action = resp.get("Action", "")
+        request_uuid = http_resp and http_resp.request_uuid
+        self.logger.info(
+            "[response] [{}] {} {}".format(request_uuid or "*", action, resp)
+        )
+        return resp
+
+    def logged_exception_handler(self, e: Exception):
+        if isinstance(e, exc.RetCodeException):
+            self.logger.warning(e)
+        else:
+            self.logger.exception(e)
+        return e
+
+    @staticmethod
+    def _parse_dict_config(
+        config: dict,
+    ) -> typing.Tuple[Config, auth.Credential]:
+        return Config.from_dict(config), auth.Credential.from_dict(config)
+
+    def _send(self, action: str, args: dict, max_retries, timeout) -> dict:
+        args["Action"] = action
+
+        # inject request middleware
+        for handler in self.middleware.request_handlers:
+            args = handler(args)
+
+        # send http request
+        try:
+            req = self._build_http_request(args)
+
+            resp = self.transport.send(
+                req,
+                ssl_option=SSLOption(
+                    self.config.ssl_verify,
+                    self.config.ssl_cacert,
+                    self.config.ssl_cert,
+                    self.config.ssl_key,
+                ),
+                timeout=timeout,
+                max_retries=max_retries,
+            )
+            data = resp.json()
+        except Exception as e:
+            for handler in self.middleware.exception_handlers:
+                handler(e)
+            raise e
+
+        # inject response middleware
+        for handler in self.middleware.response_handlers:
+            data = handler(data, resp)
+
+        # return when successful
+        if int(data.get("RetCode", -1)) == 0:
+            return data
+
+        # inject exception middleware
+        ret_code_exc = exc.RetCodeException(
+            action=req.data.get("Action", ""),
+            code=int(data.get("RetCode", 0)),
+            message=data.get("Message", ""),
+            request_uuid=resp.request_uuid,
+        )
+        for handler in self.middleware.exception_handlers:
+            handler(ret_code_exc)
+        raise ret_code_exc
+
+    def _build_http_request(self, args: dict) -> Request:
+        config = {
+            "Region": self.config.region,
+            "ProjectId": self.config.project_id,
+        }
+        payload = {k: v for k, v in config.items() if v is not None}
+        payload.update({k: v for k, v in args.items() if v is not None})
+        payload = encoder.encode(payload)
+        payload["Signature"] = self.credential.verify_ac(payload)
+
+        return Request(
+            url=self.config.base_url,
+            method="post",
+            data=payload,
+            headers={
+                "User-Agent": self._build_user_agent(),
+                "Content-Type": "application/x-www-form-urlencoded",
+                "U-Timestamp-Ms": str(int(round(time.time() * 1000))),
+            },
+        )
+
+    def _build_user_agent(self) -> str:
+        python_version = "{v[0]}.{v[1]}.{v[2]}".format(v=sys.version_info)
+        user_agent = "Python/{python_version} Python-SDK/{sdk_version}".format(
+            python_version=python_version, sdk_version=version.version
+        ) + (self.config.user_agent or "")
+        return user_agent
+
+    def __repr__(self):
+        return '<{}(region="{}")>'.format(
+            self.__class__.__name__, self.config.region
+        )

ucloud/core/exc/__init__.py

@@ -0,0 +1,9 @@
+from ucloud.core.exc._exc import (
+    UCloudException,
+    ValidationException,
+    RetCodeException,
+    RetryTimeoutException,
+    TransportException,
+    HTTPStatusException,
+    InvalidResponseException,
+)

ucloud/core/exc/_exc.py

@@ -0,0 +1,94 @@
+from collections.abc import Iterable
+
+from ucloud.core.utils import compat
+
+
+class UCloudException(Exception):
+    @property
+    def retryable(self):
+        return False
+
+
+MAX_COMMON_RET_CODE = 2000
+
+
+class TransportException(UCloudException):
+    pass
+
+
+class HTTPStatusException(TransportException):
+    def __init__(self, status_code: int, request_uuid: str = None):
+        self.status_code = status_code
+        self.request_uuid = request_uuid
+
+    @property
+    def retryable(self):
+        return self.status_code in [429, 502, 503, 504]
+
+    def __str__(self):
+        return "[{uuid}] {self.status_code} http status error".format(
+            self=self, uuid=self.request_uuid or "*"
+        )
+
+
+class InvalidResponseException(TransportException):
+    def __init__(self, content: bytes, message: str, request_uuid: str = None):
+        self.content = content
+        self.message = message
+        self.request_uuid = request_uuid
+
+    @property
+    def retryable(self):
+        return False
+
+    def __str__(self):
+        return "[{uuid}] {self.message}: {self.content}".format(
+            self=self, uuid=self.request_uuid or "*"
+        )
+
+
+class RetCodeException(UCloudException):
+    def __init__(
+        self, action: str, code: int, message: str, request_uuid: str = None
+    ):
+        self.action = action
+        self.code = code
+        self.message = message
+        self.request_uuid = request_uuid
+
+    @property
+    def retryable(self):
+        return self.code > MAX_COMMON_RET_CODE
+
+    def __str__(self):
+        return "[{uuid}] {self.action} - {self.code}: {self.message}".format(
+            self=self, uuid=self.request_uuid or "*"
+        )
+
+    def json(self):
+        return {
+            "RetCode": self.code,
+            "Message": self.message or "",
+            "Action": self.action or "",
+        }
+
+
+class RetryTimeoutException(UCloudException):
+    pass
+
+
+class ValidationException(UCloudException):
+    def __init__(self, e=None):
+        if isinstance(e, compat.string_types):
+            self.errors = [e]
+        elif isinstance(e, Iterable):
+            self.errors = e or []
+        else:
+            self.errors = [e]
+
+    @property
+    def retryable(self):
+        return False
+
+    def __str__(self):
+        return str([str(e) for e in self.errors])

ucloud/core/transport/__init__.py

@@ -0,0 +1,4 @@
+from ucloud.core.transport.http import Request, Response, Transport, SSLOption
+from ucloud.core.transport._requests import RequestsTransport
+
+__all__ = ["Request", "Response", "Transport", "RequestsTransport", "SSLOption"]

ucloud/core/transport/_requests.py

@@ -0,0 +1,135 @@
+import time
+import typing
+import requests
+from urllib3.util.retry import Retry
+from requests.adapters import HTTPAdapter
+from ucloud.core.transport import http
+from ucloud.core.transport.http import Request, Response, SSLOption
+from ucloud.core.utils.middleware import Middleware
+from ucloud.core import exc
+
+
+class RequestsTransport(http.Transport):
+    """transport is the implementation of http client, use for send a request and return a http response
+
+    :type max_retries: int
+    :param max_retries: max retries is the max number of transport request when occur http error
+    :type backoff_factor: float
+    :param backoff_factor: backoff factor will calculate the backoff delay during retrying,
+        the backoff delay = {backoff factor} * (2 ^ ({number of total retries} - 1))
+    :type status_forcelist: tuple
+    :param status_forcelist: the status code list that could be retried
+    """
+
+    def __init__(
+        self,
+        max_retries: int = 3,
+        backoff_factor: float = 0.3,
+        status_forcelist: typing.Tuple[int] = (500, 502, 504),
+    ):
+        self.max_retries = max_retries
+        self.backoff_factor = backoff_factor
+        self.status_forcelist = status_forcelist
+
+        self._adapter = self._load_adapter(max_retries)
+        self._middleware = Middleware()
+
+    def send(self, req: Request, **options: typing.Any) -> http.Response:
+        """send request and return the response
+
+        :param req: the full http request descriptor
+        :return: the response of http request
+        """
+        for handler in self.middleware.request_handlers:
+            req = handler(req)
+
+        try:
+            resp = self._send(req, **options)
+        except Exception as e:
+            for handler in self.middleware.exception_handlers:
+                handler(e)
+            raise e
+
+        for handler in self.middleware.response_handlers:
+            resp = handler(resp)
+
+        return resp
+
+    @property
+    def middleware(self) -> Middleware:
+        """the middleware object, see :mod:
+
+        :return: the transport middleware
+        """
+        return self._middleware
+
+    def _send(self, req: Request, **options: typing.Any) -> requests.Response:
+        with requests.Session() as session:
+            adapter = self._load_adapter(options.get("max_retries"))
+            session.mount("http://", adapter=adapter)
+            session.mount("https://", adapter=adapter)
+
+            ssl_option = options.get("ssl_option")
+            kwargs = self._build_ssl_option(ssl_option) if ssl_option else {}
+
+            req.request_time = time.time()
+            session_resp = session.request(
+                method=req.method.upper(),
+                url=req.url,
+                json=req.json,
+                data=req.data,
+                params=req.params,
+                headers=req.headers,
+                timeout=options.get("timeout"),
+                **kwargs
+            )
+            resp = self.convert_response(session_resp)
+            resp.request = req
+            resp.response_time = time.time()
+
+            if resp.status_code >= 400:
+                raise exc.HTTPStatusException(
+                    resp.status_code, resp.request_uuid
+                )
+            return resp
+
+    @staticmethod
+    def _build_ssl_option(ssl_option):
+        kwargs = {"verify": ssl_option.ssl_verify and ssl_option.ssl_cacert}
+        if not ssl_option.ssl_cert:
+            return kwargs
+
+        if ssl_option.ssl_key:
+            kwargs["cert"] = (ssl_option.ssl_cert, ssl_option.ssl_key)
+        else:
+            kwargs["cert"] = ssl_option.ssl_cert
+        return kwargs
+
+    def _load_adapter(
+        self, max_retries: typing.Optional[int] = None
+    ) -> HTTPAdapter:
+        if max_retries is None and self._adapter is not None:
+            return self._adapter
+
+        max_retries = max_retries or 0
+        adapter = HTTPAdapter()
+        adapter.max_retries = Retry(
+            total=max_retries,
+            read=max_retries,
+            connect=max_retries,
+            backoff_factor=self.backoff_factor,
+            status_forcelist=self.status_forcelist,
+        )
+        return adapter
+
+    @staticmethod
+    def convert_response(r: requests.Response) -> Response:
+        return Response(
+            url=r.url,
+            method=r.request.method,
+            status_code=r.status_code,
+            reason=r.reason,
+            headers=r.headers,
+            content=r.content,
+            encoding=r.encoding or r.apparent_encoding,
+        )

ucloud/core/transport/http.py

@@ -0,0 +1,120 @@
+import typing
+import logging
+import json as json_mod
+
+from ucloud.core import exc
+from ucloud.core.transport import utils
+from ucloud.core.utils.compat import str
+
+logger = logging.getLogger(__name__)
+
+
+class Request:
+    def __init__(
+        self,
+        url: str,
+        method: str = "GET",
+        params: dict = None,
+        data: dict = None,
+        json: dict = None,
+        headers: dict = None,
+        **kwargs
+    ):
+        self.url = url
+        self.method = method
+        self.params = params
+        self.data = data
+        self.json = json
+        self.headers = headers
+        self.request_time = 0
+
+    def payload(self):
+        payload = (self.params or {}).copy()
+        payload.update(self.data or {})
+        payload.update(self.json or {})
+        return payload
+
+
+REQUEST_UUID_HEADER_KEY = "X-UCLOUD-REQUEST-UUID"
+
+
+class Response:
+    def __init__(
+        self,
+        url: str,
+        method: str,
+        request: Request = None,
+        status_code: int = None,
+        reason: str = None,
+        headers: dict = None,
+        content: bytes = None,
+        encoding: str = None,
+        **kwargs
+    ):
+        self.url = url
+        self.method = method
+        self.request = request
+        self.status_code = status_code
+        self.reason = reason
+        self.content = content
+        self.encoding = encoding
+        self.response_time = 0
+        self.headers = headers or {}
+        self.request_uuid = self.headers.get(REQUEST_UUID_HEADER_KEY)
+
+    def json(self, **kwargs) -> typing.Optional[dict]:
+        """json will return the bytes of content"""
+        if not self.content:
+            return None
+
+        try:
+            return self._decode_json(**kwargs)
+        except Exception as e:
+            raise exc.InvalidResponseException(
+                self.content, str(e), request_uuid=self.request_uuid
+            )
+
+    @property
+    def text(self):
+        """text will return the unicode string of content,
+        see `requests.Response.text`
+        """
+        if not self.content:
+            return str("")
+
+        # Decode unicode from given encoding.
+        try:
+            content = str(self.content, self.encoding, errors="replace")
+        except (LookupError, TypeError):
+            content = str(self.content, errors="replace")
+        return content
+
+    def _decode_json(self, **kwargs):
+        encoding = utils.guess_json_utf(self.content)
+        if encoding is not None:
+            try:
+                return json_mod.loads(self.content.decode(encoding), **kwargs)
+            except UnicodeDecodeError:
+                pass
+        return json_mod.loads(self.text, **kwargs)
+
+
+class SSLOption:
+    def __init__(
+        self,
+        ssl_verify: bool = True,
+        ssl_cacert: str = None,
+        ssl_cert: str = None,
+        ssl_key: str = None,
+    ):
+        self.ssl_verify = ssl_verify
+        self.ssl_cacert = ssl_cacert
+        self.ssl_cert = ssl_cert
+        self.ssl_key = ssl_key
+
+
+class Transport:
+    """the abstract class of transport implementation"""
+
+    def send(self, req: Request, **options: typing.Any) -> Response:
+        raise NotImplementedError

ucloud/core/transport/utils.py

@@ -0,0 +1,40 @@
+import codecs
+
+# Null bytes; no need to recreate these on each call to guess_json_utf
+_null = "\x00".encode("ascii")  # encoding to ASCII for Python 3
+_null2 = _null * 2
+_null3 = _null * 3
+
+
+def guess_json_utf(data):
+    """guess_json_utf will detect the encoding of bytes,
+    see `requests.utils.guess_json_utf`
+
+    :rtype: str
+    """
+    # JSON always starts with two ASCII characters, so detection is as
+    # easy as counting the nulls and from their location and count
+    # determine the encoding. Also detect a BOM, if present.
+    sample = data[:4]
+    if sample in (codecs.BOM_UTF32_LE, codecs.BOM_UTF32_BE):
+        return "utf-32"  # BOM included
+    if sample[:3] == codecs.BOM_UTF8:
+        return "utf-8-sig"  # BOM included, MS style (discouraged)
+    if sample[:2] in (codecs.BOM_UTF16_LE, codecs.BOM_UTF16_BE):
+        return "utf-16"  # BOM included
+    nullcount = sample.count(_null)
+    if nullcount == 0:
+        return "utf-8"
+    if nullcount == 2:
+        if sample[::2] == _null2:  # 1st and 3rd are null
+            return "utf-16-be"
+        if sample[1::2] == _null2:  # 2nd and 4th are null
+            return "utf-16-le"
+        # Did not detect 2 valid UTF-16 ascii-range characters
+    if nullcount == 3:
+        if sample[:3] == _null3:
+            return "utf-32-be"
+        if sample[1:] == _null3:
+            return "utf-32-le"
+        # Did not detect a valid UTF-32 ascii-range character
+    return None

ucloud/core/typesystem/abstract.py

@@ -0,0 +1,60 @@
+import typing
+
+from ucloud.core import exc
+
+
+class Field(object):
+    def __init__(
+        self,
+        required: bool = False,
+        default: typing.Any = None,
+        dump_to: str = None,
+        load_from: str = None,
+        strict: bool = None,
+        **kwargs
+    ):
+        self.required = required
+        self.default = default
+        self.dump_to = dump_to
+        self.load_from = load_from
+        self.options = kwargs
+        self.strict = bool(strict)  # None as False
+
+    def dumps(self, value, **kwargs):
+        raise NotImplementedError
+
+    def loads(self, value, **kwargs):
+        raise NotImplementedError
+
+    @staticmethod
+    def fail(name, expected, got):
+        msg = "invalid field {}, expect {}, got {}".format(name, expected, got)
+        raise exc.ValidationException(msg)
+
+
+class Schema(object):
+    fields = {}
+
+    def __init__(
+        self,
+        required: bool = False,
+        default: typing.Union[typing.Callable, typing.Any] = dict,
+        dump_to: str = None,
+        load_from: str = None,
+        strict: bool = False,
+        case_sensitive: bool = False,
+        **kwargs
+    ):
+        self.required = required
+        self.default = default
+        self.dump_to = dump_to
+        self.load_from = load_from
+        self.options = kwargs
+        self.strict = strict
+        self.case_sensitive = case_sensitive
+
+    def dumps(self, d: dict) -> dict:
+        raise NotImplementedError
+
+    def loads(self, d: dict) -> dict:
+        raise NotImplementedError

ucloud/core/typesystem/encoder.py

@@ -0,0 +1,33 @@
+from ucloud.core.utils.compat import str
+
+
+def encode(d: dict) -> dict:
+    result = {}
+
+    for k, v in d.items():
+        if isinstance(v, dict):
+            for ek, ev in encode(v).items():
+                result["{}.{}".format(k, ek)] = encode_value(ev)
+        elif isinstance(v, list):
+            for i, item in enumerate(v):
+                if isinstance(item, dict):
+                    for ek, ev in encode(item).items():
+                        result["{}.{}.{}".format(k, i, ek)] = encode_value(ev)
+                else:
+                    result["{}.{}".format(k, i)] = encode_value(item)
+        else:
+            result[k] = encode_value(v)
+
+    return result
+
+
+def encode_value(v):
+    # bool only accept lower case
+    if isinstance(v, bool):
+        return "true" if v else "false"
+
+    # api gateway will try to decode float as int in lua syntax
+    if isinstance(v, float):
+        return str(int(v)) if v % 1 == 0 else str(v)
+
+    return str(v)