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

ucloud/core/typesystem/fields.py

@@ -0,0 +1,149 @@
+import base64
+import typing
+from collections.abc import Iterable
+
+from ucloud.core.typesystem import abstract
+from ucloud.core.exc import ValidationException
+from ucloud.core.utils.compat import str
+
+
+class List(abstract.Field):
+    """array param is the custom field to parse custom param such as:
+
+    - IP.N
+    - UDisk.N.Size
+    - NetInterface.N.EIP.Bandwidth
+    """
+
+    def __init__(
+        self,
+        item: typing.Union[abstract.Field, abstract.Schema],
+        default=list,
+        **kwargs
+    ):
+        super(List, self).__init__(default=default, **kwargs)
+        self.item = item
+
+    def dumps(self, value, name=None, **kwargs):
+        if not isinstance(value, Iterable):
+            raise ValidationException(
+                "invalid field {}, expect list, got {}".format(
+                    name, type(value)
+                )
+            )
+
+        errors = []
+        values = []
+        for each in value:
+            try:
+                v = self.item.dumps(each)
+            except ValidationException as e:
+                errors.extend(e.errors)
+            else:
+                values.append(v)
+
+        if len(errors) > 0:
+            raise ValidationException(errors)
+
+        return values
+
+    def loads(self, value, name=None, **kwargs):
+        if not isinstance(value, Iterable):
+            raise ValidationException(
+                "invalid field {}, expect list, got {}".format(
+                    name, type(value)
+                )
+            )
+
+        errors = []
+        values = []
+        for each in value:
+            try:
+                v = self.item.loads(each)
+            except ValidationException as e:
+                errors.extend(e.errors)
+            else:
+                values.append(v)
+
+        if len(errors) > 0:
+            raise ValidationException(errors)
+
+        return values
+
+
+class Str(abstract.Field):
+    def dumps(self, value, name=None, **kwargs):
+        return self._convert(value, name)
+
+    def loads(self, value, name=None, **kwargs):
+        return self._convert(value, name)
+
+    def _convert(self, value, name=None):
+        if self.strict and not isinstance(value, str):
+            self.fail(name, "str", type(value))
+
+        return str(value)
+
+
+class Base64(Str):
+    def dumps(self, value, name=None, **kwargs):
+        s = super(Base64, self).dumps(value, name)
+        return base64.b64encode(s.encode()).decode()
+
+    def loads(self, value, name=None, **kwargs):
+        s = super(Base64, self).loads(value, name)
+        return base64.b64decode(s.encode()).decode()
+
+
+class Int(abstract.Field):
+    def dumps(self, value, name=None, **kwargs):
+        return self._convert(value, name)
+
+    def loads(self, value, name=None, **kwargs):
+        return self._convert(value, name)
+
+    def _convert(self, value, name=None):
+        if self.strict and not isinstance(value, int):
+            self.fail(name, "int", type(value))
+
+        try:
+            return int(value)
+        except ValueError:
+            self.fail(name, "int", type(value))
+
+
+class Float(abstract.Field):
+    def dumps(self, value, name=None, **kwargs):
+        return self._convert(value, name)
+
+    def loads(self, value, name=None, **kwargs):
+        return self._convert(value, name)
+
+    def _convert(self, value, name=None):
+        if self.strict and not isinstance(value, float):
+            self.fail(name, "float", type(value))
+
+        try:
+            return float(value)
+        except ValueError:
+            self.fail(name, "float", type(value))
+
+
+class Bool(abstract.Field):
+    def dumps(self, value, name=None, **kwargs):
+        return self._convert(value, name)
+
+    def loads(self, value, name=None, **kwargs):
+        return self._convert(value, name)
+
+    def _convert(self, value, name=None):
+        if self.strict and not isinstance(value, bool):
+            self.fail(name, "bool", type(value))
+
+        if value == "true" or value is True:
+            return True
+
+        if value == "false" or value is False:
+            return False
+
+        self.fail(name, "bool", type(value))

ucloud/core/typesystem/schema.py

@@ -0,0 +1,97 @@
+import logging
+from ucloud.core.typesystem import abstract
+from ucloud.core.exc import ValidationException
+from ucloud.core.utils import compat
+
+logger = logging.getLogger(__name__)
+
+
+class Schema(abstract.Schema):
+    fields = {}  # noqa: F811
+
+    def dumps(self, d: dict, name=None, **kwargs) -> dict:
+        result = {}
+        errors = []
+
+        for k, field in self.fields.items():
+            v = d.get(k)
+
+            # resolve value is empty
+            if v is None:
+                if field.required:
+                    errors.append(
+                        ValidationException(
+                            "the field {k} is required".format(k=k)
+                        )
+                    )
+                    continue
+
+                if field.default is None:
+                    continue
+
+                if isinstance(field.default, compat.Callable):
+                    v = field.default()
+                else:
+                    v = field.default
+
+            try:
+                serialized = field.dumps(v, name=k)
+            except ValidationException as e:
+                errors.extend(e.errors)
+                continue
+
+            result[field.dump_to or k] = serialized
+
+        if len(errors) > 0:
+            raise ValidationException(errors)
+
+        return result
+
+    def loads(self, d: dict, name=None, **kwargs) -> dict:
+        result = {}
+        errors = []
+
+        if not self.case_sensitive:
+            d = {k.lower(): v for k, v in d.items()}
+
+        for k, field in self.fields.items():
+            load_key = field.load_from or k
+            v = d.get(load_key if self.case_sensitive else load_key.lower())
+            if v is None:
+                if field.default is None:
+                    continue
+
+                if isinstance(field.default, compat.Callable):
+                    v = field.default()
+                else:
+                    v = field.default
+
+            try:
+                serialized = field.loads(v, name=k)
+            except ValidationException as e:
+                errors.extend(e.errors)
+                continue
+
+            result[k] = serialized
+
+        if len(errors) > 0:
+            raise ValidationException(errors)
+
+        return result
+
+
+class RequestSchema(Schema):
+    fields = {}  # noqa: F811
+
+    def dumps(self, d: dict, name=None, **kwargs) -> dict:
+        if not isinstance(d, dict):
+            raise ValidationException(
+                "invalid field {}, expect dict, got {}".format(name, type(d))
+            )
+
+        result = super(RequestSchema, self).dumps(d, name=name, **kwargs)
+        return result
+
+
+class ResponseSchema(Schema):
+    pass

ucloud/core/utils/compat.py

@@ -0,0 +1,15 @@
+import sys
+
+PY3 = sys.version_info[0] == 3
+
+if PY3:
+    str = str
+    string_types = (str,)
+    from collections.abc import Callable
+else:
+    import types
+
+    str = unicode  # noqa: F821
+    string_types = types.StringTypes
+
+    from collections import Callable

ucloud/core/utils/deco.py

@@ -0,0 +1,31 @@
+import functools
+import logging
+
+logger = logging.getLogger("ucloud")
+
+
+def deprecated(instead_of="", message=""):
+    """deprecated is a decorator to mark a function is deprecated.
+    it will logging warning when this function called
+
+    >>> @deprecated(instead_of="new_function")
+    ... def an_old_function():
+    ...     pass
+    """
+
+    def deco(fn):
+        @functools.wraps(fn)
+        def wrapper(*args, **kwargs):
+            msg = [
+                "this function/method `{}` is deprecated".format(fn.__name__)
+            ]
+            instead_of and msg.append(
+                "please use `{}` instead".format(instead_of)
+            )
+            message and msg.append(message)
+            logger.warning(", ".join(msg))
+            return fn(*args, **kwargs)
+
+        return wrapper
+
+    return deco

ucloud/core/utils/log.py

@@ -0,0 +1,29 @@
+import logging
+
+DEFAULT_LOGGER_NAME = "ucloud"
+DEFAULT_FORMAT = "%(asctime)s [%(levelname)8s] %(message)s (%(filename)s:%(lineno)s %(name)s)"
+DEFAULT_LEVEL = logging.INFO
+
+
+def init_default_logger():
+    logger = logging.getLogger(DEFAULT_LOGGER_NAME)
+    logger.setLevel(DEFAULT_LEVEL)
+
+    # create console handler and set level to debug
+    ch = logging.StreamHandler()
+    ch.setLevel(DEFAULT_LEVEL)
+
+    # create formatter
+    formatter = logging.Formatter(DEFAULT_FORMAT)
+
+    # add formatter to ch
+    ch.setFormatter(formatter)
+
+    # add ch to logger
+    logger.removeHandler(ch)
+    logger.addHandler(ch)
+
+    return logger
+
+
+default_logger = init_default_logger()

ucloud/core/utils/middleware.py

@@ -0,0 +1,63 @@
+class Middleware:
+    """middleware is the object to store request/response handlers
+
+    >>> middleware = Middleware()
+
+    Add a request handler to prepare the request
+
+    >>> @middleware.request
+    ... def prepare(req):
+    ...     req['Region'] = 'cn-bj2'
+    ...     return req
+
+    Add a response handler to log the response detail
+
+    >>> @middleware.response
+    ... def logged(resp):
+    ...     print(resp)
+    ...     return resp
+
+    >>> len(middleware.request_handlers), len(middleware.response_handlers)
+    (1, 1)
+    """
+
+    def __init__(self):
+        self.request_handlers = []
+        self.response_handlers = []
+        self.exception_handlers = []
+
+    def request(self, handler, index=-1):
+        """request is the request handler register to add request handler.
+
+        :param handler: request handler function, receive request object
+                        and return a new request
+        :param int index: the position of request in the handler list,
+                          default is append it to end
+        :return:
+        """
+        self.request_handlers.insert(index, handler)
+        return handler
+
+    def response(self, handler, index=-1):
+        """response is the response handler register to add response handler.
+
+        :param handler: response handler function, receive response object
+                        and return a new response
+        :param int index: the position of response in the handler list,
+                          default is append it to end
+        :return:
+        """
+        self.response_handlers.insert(index, handler)
+        return handler
+
+    def exception(self, handler, index=-1):
+        """exception is the exception handler register to add exception handler.
+
+        :param handler: exception handler function, receive exception object
+                        and raise a new exception or ignore it
+        :param int index: the position of handler in the handler list,
+                          default is append it to end
+        :return:
+        """
+        self.exception_handlers.insert(index, handler)
+        return handler

ucloud/helpers/utils.py

@@ -0,0 +1,90 @@
+import random
+import base64
+import typing
+
+_lowercase = "abcdefghijklmnopqrstuvwxyz"
+_uppercase = "ABCDEFGHIJKLMNOPQRSTUVWXYZ"
+_numbers = "0123456789"
+_specials = "_"
+
+
+def gen_password(
+    n: int,
+    lower_letters: str = _lowercase,
+    upper_letters: str = _uppercase,
+    number_letters: str = _numbers,
+    special_letters: str = _specials,
+    min_lower: int = 1,
+    min_upper: int = 1,
+    min_number: int = 1,
+    min_specials: int = 1,
+):
+    """generate password for any resource
+
+    >>> len(gen_password(20))
+    20
+
+    :param int n: password total length
+    :param str lower_letters: all lowercase letters
+    :param str upper_letters: all uppercase letters
+    :param str number_letters: all number letters
+    :param str special_letters: all special letters
+    :param int min_lower: minimal number of lowercase letters
+    :param int min_upper: minimal number of uppercase letters
+    :param int min_number: minimal number of number letters
+    :param int min_specials: minimal number of special letters
+    :return:
+    """
+    all_letters = "".join(
+        [lower_letters, upper_letters, number_letters, special_letters]
+    )
+    minimal_total = min_lower + min_upper + min_number + min_specials
+    if n < minimal_total:
+        raise ValueError(
+            (
+                "the length of password must be larger than "
+                "total minimal letters number"
+            )
+        )
+
+    minimal_letters = "".join(
+        [
+            gen_string(lower_letters, min_lower),
+            gen_string(upper_letters, min_upper),
+            gen_string(number_letters, min_number),
+            gen_string(special_letters, min_specials),
+        ]
+    )
+
+    additional_letters = random.sample(all_letters, n - minimal_total)
+    results = list(minimal_letters) + additional_letters
+    random.shuffle(results)
+    return "".join(results)
+
+
+def gen_string(letters: str, length: int):
+    return "".join([random.choice(letters) for i in range(length)])
+
+
+def first(arr: typing.List[typing.Any]) -> typing.Any:
+    if len(arr) == 0:
+        return None
+    return arr[0]
+
+
+def b64encode(s: str) -> str:
+    """base64 encode
+
+    :param str s: input string
+    :return: base64 string
+    """
+    return base64.b64encode(s.encode()).decode()
+
+
+def b64decode(s: str) -> str:
+    """base64 decode
+
+    :param str s: base64 string
+    :return: output string
+    """
+    return base64.b64decode(s.encode()).decode()

ucloud/helpers/wait.py

@@ -0,0 +1,108 @@
+import time
+import typing
+import logging
+from ucloud.core import exc
+
+
+MAX_BACKOFF_INTERVAL = 10
+
+logger = logging.getLogger(__name__)
+
+
+class WaitTimeoutException(exc.UCloudException):
+    pass
+
+
+class StateConf:
+    """StateConf is the utilities class to wait the state return by refresh function achieve the specific state,
+    the generally usage is wait the cloud resource, such as uhost, udb ... is
+    ready after created.
+    """
+
+    def __init__(
+        self,
+        pending: typing.List[str],
+        target: typing.List[str],
+        refresh: typing.Callable,
+        timeout: float,
+        startup_delay: float = 0,
+        min_backoff_interval: float = 0.1,
+        max_backoff_interval: float = MAX_BACKOFF_INTERVAL,
+    ):
+        self.pending = pending
+        self.target = target
+        self.refresh = refresh
+        self.timeout = timeout
+        self.startup_delay = startup_delay
+        self.min_backoff_interval = min_backoff_interval
+        self.max_backoff_interval = max_backoff_interval
+
+    def wait(self):
+        start_time = time.time()
+        interval = self.min_backoff_interval
+
+        # delay on start up
+        time.sleep(self.startup_delay)
+
+        # waiting for state changed to target state
+        while time.time() - start_time < self.timeout:
+            state = self.refresh()
+
+            if state in self.pending:
+                time.sleep(interval)
+                interval *= 2
+                if interval > self.max_backoff_interval:
+                    interval = self.max_backoff_interval
+                logger.info(
+                    "waiting state for {self.refresh}, got state {state}".format(
+                        self=self, state=state
+                    )
+                )
+                continue
+
+            if state in self.target:
+                return
+
+        raise WaitTimeoutException(
+            "wait timeout {self.timeout}s for {self.refresh}".format(self=self)
+        )
+
+
+def wait_for_state(
+    pending: typing.List[str],
+    target: typing.List[str],
+    refresh: typing.Callable,
+    timeout: float,
+    startup_delay: float = 0,
+    min_backoff_interval: float = 0.1,
+    max_backoff_interval: float = MAX_BACKOFF_INTERVAL,
+):
+    """wait_for_state is a utilities function to wait the state return by refresh function achieve the specific state,
+    the generally usage is wait the cloud resource, such as uhost, udb ... is
+    ready after created.
+
+    >>> wait_for_state(
+    ...     pending=["pending"],
+    ...     target=["running"],
+    ...     refresh=lambda: "running",
+    ...     timeout=0.5,
+    ... )
+
+    :param pending: pending is the list of pending state, the state is returned by refresh function
+    :param target: target is the list of target state, it is usually the terminate state, eg. running and fail
+    :param refresh: the customized refresh function, expect no arguments and return a state
+    :param timeout: timeout is the total time to wait state is achieved
+    :param startup_delay: the time to wait before first refresh function is called
+    :param min_backoff_interval: the backoff time for first refresh interval
+    :param max_backoff_interval: the max backoff time for refresh interval
+    """
+    conf = StateConf(
+        pending=pending,
+        target=target,
+        refresh=refresh,
+        timeout=timeout,
+        startup_delay=startup_delay,
+        min_backoff_interval=min_backoff_interval,
+        max_backoff_interval=max_backoff_interval,
+    )
+    return conf.wait()