yicloud-sdk-python 0.1.0__py3-none-any.whl

yicloud/base/errs/__init__.py

@@ -0,0 +1,292 @@
+from typing import Protocol, Any, Optional
+import requests
+
+
+ErrHTTPStatus = "server.HTTPStatusError"
+ErrRetCode = "server.RetCodeError"
+
+
+class Error(Protocol):
+    """Base error interface matching Go's Error interface."""
+
+    def __str__(self) -> str: ...
+
+    @property
+    def action(self) -> str: ...
+
+    @property
+    def code(self) -> int: ...
+
+    @property
+    def message(self) -> str: ...
+
+    @property
+    def status_code(self) -> int: ...
+
+
+# YiCloudException - base exception for all SDK errors
+class YiCloudException(Exception):
+    """Base exception for all YiCloud SDK errors.
+
+    Users can catch this exception type to handle all SDK errors:
+
+        try:
+            client.do_something()
+        except exc.YiCloudException as e:
+            print(f"YiCloud error: {e}")
+    """
+
+    def __str__(self) -> str:
+        return f"YiCloudException: {self}"
+
+    @property
+    def action(self) -> str:
+        return ""
+
+    @property
+    def code(self) -> int:
+        return 0
+
+    @property
+    def message(self) -> str:
+        return str(self) if self else "yicloud error"
+
+    @property
+    def status_code(self) -> int:
+        return 0
+
+
+# ClientException - client-side errors (SDK side issues)
+class ClientException(Error, YiCloudException):
+    """
+    Client-side errors (invalid params, signing, network).
+
+    This is SDK-side errors that occur before or during the request.
+    """
+
+    def __init__(self, action: str, err: Optional[Exception] = None):
+        self._action = action
+        self._err = err
+
+    def __str__(self) -> str:
+        return f"ClientException[action={self._action}]: {self._err}"
+
+    def __repr__(self) -> str:
+        return f"<ClientException action={self._action} err={self._err}>"
+
+    @property
+    def action(self) -> str:
+        return self._action
+
+    @property
+    def code(self) -> int:
+        return -1
+
+    @property
+    def status_code(self) -> int:
+        return 0
+
+    @property
+    def message(self) -> str:
+        return str(self._err) if self._err else "client error"
+
+    @property
+    def err(self) -> Optional[Exception]:
+        return self._err
+
+
+# ServerException - server-side errors (API response issues)
+class ServerException(Error, YiCloudException):
+    """
+    Server-side errors (HTTP status, business return code).
+
+    This is API response errors returned from the server.
+    """
+
+    def __init__(
+        self,
+        action: str,
+        status_code: int = 0,
+        ret_code: int = 0,
+        message: str = "",
+        request_id: str = ""
+    ):
+        self._action = action
+        self._status_code = status_code
+        self._ret_code = ret_code
+        self._message = message if message else "server error"
+        self._request_id = request_id
+
+    def __str__(self) -> str:
+        return (f"ServerException[action={self._action}, status_code={self._status_code}, "
+                f"ret_code={self._ret_code}, request_id={self._request_id}]: {self._message}")
+
+    def __repr__(self) -> str:
+        return (f"<ServerException action={self._action} status_code={self._status_code} "
+                f"ret_code={self._ret_code} request_id={self._request_id}>")
+
+    @property
+    def action(self) -> str:
+        return self._action
+
+    @property
+    def code(self) -> int:
+        return self._ret_code
+
+    @property
+    def status_code(self) -> int:
+        return self._status_code
+
+    @property
+    def message(self) -> str:
+        return self._message
+
+    @property
+    def request_id(self) -> str:
+        return self._request_id
+
+
+# Helper functions for type checking
+def is_client_error(err: Any) -> bool:
+    """
+    Check if error is a ClientException.
+
+    Can be used with Error objects or exceptions.
+    """
+    return isinstance(err, ClientException)
+
+
+def as_client_error(err: Any) -> Optional[ClientException]:
+    """
+    Return error as ClientException if it is one, otherwise None.
+
+    This is a type guard that can be used in if statements.
+    """
+    if is_client_error(err):
+        return err
+    return None
+
+
+def is_server_error(err: Any) -> bool:
+    """
+    Check if error is a ServerException.
+
+    Can be used with Error objects or exceptions.
+    """
+    return isinstance(err, ServerException)
+
+
+def as_server_error(err: Any) -> Optional[ServerException]:
+    """
+    Return error as ServerException if it is one, otherwise None.
+
+    This is a type guard that can be used in if statements.
+    """
+    if is_server_error(err):
+        return err
+    return None
+
+
+def is_network_error(err: Any) -> bool:
+    """
+    Check if the error is from network problem.
+
+    Returns True if the error is a network-related error that might be retryable.
+    """
+    if err is None:
+        return False
+
+    # Check for requests.RequestException (base class for all requests exceptions)
+    if isinstance(err, requests.RequestException):
+        return True
+
+    # Check for common network-related error patterns
+    err_str = str(err).lower()
+    network_patterns = [
+        "connection error",
+        "connect timeout",
+        "read timeout",
+        "connection refused",
+        "connection reset",
+        "network unreachable",
+        "host unreachable",
+        "hostname mismatch",
+        "certificate verify failed",
+        "certificate verify",
+        "ssl",
+        "tls",
+        "request canceled",
+    ]
+
+    for pattern in network_patterns:
+        if pattern in err_str:
+            return True
+
+    # Check for requests specific exception types
+    err_type = type(err).__name__
+    network_types = [
+        "ConnectionError",
+        "Timeout",
+        "HTTPError",
+        "SSLError",
+        "ProxyError",
+        "ChunkedEncodingError",
+        "ContentDecodingError",
+        "TooManyRedirects",
+    ]
+
+    for net_type in network_types:
+        if net_type in err_type:
+            return True
+
+    return False
+
+
+def is_code_error(err: Any) -> bool:
+    """
+    Check if error has non-zero business return code.
+
+    Returns True if the error is a ServerException with non-zero ret_code.
+    """
+    if err is None:
+        return False
+    return isinstance(err, ServerException) and err.code != 0
+
+
+# Factory functions for creating errors
+def new_client_error(action: str, err: Optional[Exception] = None) -> ClientException:
+    """Create a new ClientException."""
+    return ClientException(action, err)
+
+
+def new_server_error(
+    action: str,
+    status_code: int = 0,
+    ret_code: int = 0,
+    message: str = "",
+    request_id: str = ""
+) -> ServerException:
+    """Create a new ServerException."""
+    return ServerException(action, status_code, ret_code, message, request_id)
+
+
+__all__ = [
+    # Exception types
+    "YiCloudException",
+    "ClientException",
+    "ServerException",
+    "Error",
+    # Factory functions
+    "new_client_error",
+    "new_server_error",
+    # Type checking functions
+    "is_client_error",
+    "as_client_error",
+    "is_server_error",
+    "as_server_error",
+    "is_network_error",
+    "is_code_error",
+    # Error constants
+    "ErrHTTPStatus",
+    "ErrRetCode",
+]

yicloud/base/log/__init__.py

@@ -0,0 +1,43 @@
+from yicloud.base.log.logger import (
+    Logger,
+    Level,
+    new,
+    new_with_writer,
+    get_default_logger,
+    debug,
+    debugf,
+    info,
+    infof,
+    warn,
+    warnf,
+    error,
+    errorf,
+    set_output,
+    set_writer,
+    set_level,
+    get_level,
+)
+from yicloud.base.log.std import StdLogger, new_std_logger, new_std_logger_with_writer
+
+__all__ = [
+    "Logger",
+    "Level",
+    "StdLogger",
+    "new",
+    "new_with_writer",
+    "new_std_logger",
+    "new_std_logger_with_writer",
+    "get_default_logger",
+    "debug",
+    "debugf",
+    "info",
+    "infof",
+    "warn",
+    "warnf",
+    "error",
+    "errorf",
+    "set_output",
+    "set_writer",
+    "set_level",
+    "get_level",
+]

yicloud/base/log/logger.py

@@ -0,0 +1,123 @@
+from abc import ABC, abstractmethod
+from typing import Any, Protocol, runtime_checkable, TextIO
+
+
+class Level:
+    """Log level constants matching Go SDK."""
+    DEBUG = 0
+    INFO = 1
+    WARN = 2
+    ERROR = 3
+
+    @classmethod
+    def string(cls, level: int) -> str:
+        if level == cls.DEBUG:
+            return "debug"
+        elif level == cls.INFO:
+            return "info"
+        elif level == cls.WARN:
+            return "warn"
+        elif level == cls.ERROR:
+            return "error"
+        return "unknown"
+
+
+@runtime_checkable
+class Logger(Protocol):
+    """Logger interface matching Go SDK's Logger."""
+
+    def debug(self, *args: Any): ...
+
+    def debugf(self, format: str, *args: Any): ...
+
+    def info(self, *args: Any): ...
+
+    def infof(self, format: str, *args: Any): ...
+
+    def warn(self, *args: Any): ...
+
+    def warnf(self, format: str, *args: Any): ...
+
+    def error(self, *args: Any): ...
+
+    def errorf(self, format: str, *args: Any): ...
+
+    def set_output(self, output: TextIO): ...
+
+    def set_level(self, level: int): ...
+
+    def get_level(self) -> int: ...
+
+
+def new() -> Logger:
+    return new_with_writer(None)
+
+
+def new_with_writer(output: TextIO) -> Logger:
+    from .std import new_std_logger_with_writer
+    return new_std_logger_with_writer(output)
+
+
+defaultLogger: Logger = None
+
+
+def _init():
+    global defaultLogger
+    defaultLogger = new()
+
+
+_init()
+
+
+def get_default_logger() -> Logger:
+    return defaultLogger
+
+
+def debug(*args: Any):
+    defaultLogger.debug(*args)
+
+
+def debugf(format: str, *args: Any):
+    defaultLogger.debugf(format, *args)
+
+
+def info(*args: Any):
+    defaultLogger.info(*args)
+
+
+def infof(format: str, *args: Any):
+    defaultLogger.infof(format, *args)
+
+
+def warn(*args: Any):
+    defaultLogger.warn(*args)
+
+
+def warnf(format: str, *args: Any):
+    defaultLogger.warnf(format, *args)
+
+
+def error(*args: Any):
+    defaultLogger.error(*args)
+
+
+def errorf(format: str, *args: Any):
+    defaultLogger.errorf(format, *args)
+
+
+def set_output(output: TextIO):
+    defaultLogger.set_output(output)
+
+
+def set_writer(output: TextIO):
+    """Set default output writer for third-party logger integration."""
+    global defaultLogger
+    defaultLogger = new_with_writer(output)
+
+
+def set_level(level: int):
+    defaultLogger.set_level(level)
+
+
+def get_level() -> int:
+    return defaultLogger.get_level()

yicloud/base/log/std.py

@@ -0,0 +1,70 @@
+import sys
+import datetime
+from typing import Any, TextIO
+from yicloud.base.log.logger import Logger, Level
+
+
+class StdLogger(Logger):
+    """Std logger using standard library output, matching Go SDK's stdLogger."""
+
+    def __init__(self, output: TextIO = None):
+        self.level = Level.WARN
+        self.output = output if output else sys.stdout
+
+    def _is_enabled(self, level: int) -> bool:
+        return level >= self.level
+
+    def _log(self, level: int, *args: Any):
+        if not self._is_enabled(level):
+            return
+        msg = " ".join(str(arg) for arg in args)
+        timestamp = datetime.datetime.now().strftime("%Y/%m/%d %H:%M:%S")
+        print(f"[{timestamp}] [{Level.string(level)}] {msg}", file=self.output)
+
+    def _logf(self, level: int, format: str, *args: Any):
+        if not self._is_enabled(level):
+            return
+        timestamp = datetime.datetime.now().strftime("%Y/%m/%d %H:%M:%S")
+        msg = format % args if args else format
+        print(f"[{timestamp}] [{Level.string(level)}] {msg}", file=self.output)
+
+    def debug(self, *args: Any):
+        self._log(Level.DEBUG, *args)
+
+    def debugf(self, format: str, *args: Any):
+        self._logf(Level.DEBUG, format, *args)
+
+    def info(self, *args: Any):
+        self._log(Level.INFO, *args)
+
+    def infof(self, format: str, *args: Any):
+        self._logf(Level.INFO, format, *args)
+
+    def warn(self, *args: Any):
+        self._log(Level.WARN, *args)
+
+    def warnf(self, format: str, *args: Any):
+        self._logf(Level.WARN, format, *args)
+
+    def error(self, *args: Any):
+        self._log(Level.ERROR, *args)
+
+    def errorf(self, format: str, *args: Any):
+        self._logf(Level.ERROR, format, *args)
+
+    def set_output(self, output: TextIO):
+        self.output = output
+
+    def set_level(self, level: int):
+        self.level = level
+
+    def get_level(self) -> int:
+        return self.level
+
+
+def new_std_logger() -> StdLogger:
+    return new_std_logger_with_writer(None)
+
+
+def new_std_logger_with_writer(output: TextIO) -> StdLogger:
+    return StdLogger(output)