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

version.py

@@ -0,0 +1,9 @@
+__version__ = "0.1.0"
+
+
+def Version() -> str:
+    return __version__
+
+
+def UserAgent() -> str:
+    return f"openapi-sdk-python/{__version__}"

yicloud/__init__.py

@@ -0,0 +1,7 @@
+"""
+YiCloud Python SDK
+
+A Python SDK for the YiCloud OpenAPI service.
+"""
+
+__version__ = "0.1.0"

yicloud/base/__init__.py

@@ -0,0 +1,58 @@
+from yicloud.base.client import (
+    Client,
+    DefaultClient,
+    new_client,
+    get,
+    post,
+    with_transport,
+    with_http_client,
+    with_host,
+    with_config,
+    with_credential,
+    with_logger,
+    new_net_err,
+    is_net_err,
+    action_of_path,
+)
+
+from yicloud.base import auth, config, errs, log, msgs, utils
+
+
+def new_config() -> config.Config:
+    """Create a new config with default values from environment."""
+    return config.Config.new()
+
+
+def new_credential() -> auth.Credential:
+    """Create a new credential with default values from environment."""
+    return auth.Credential.new_credential()
+
+
+__all__ = [
+    "Client",
+    "DefaultClient",
+    "new_client",
+    "new_config",
+    "new_credential",
+    "get",
+    "post",
+    "with_transport",
+    "with_http_client",
+    "with_host",
+    "with_config",
+    "with_credential",
+    "with_logger",
+    "new_net_err",
+    "is_net_err",
+    "action_of_path",
+    "auth",
+    "config",
+    "errs",
+    "exc",
+    "log",
+    "msgs",
+    "utils",
+]
+
+# exc alias for convenience, matches ucloud-sdk pattern
+exc = errs

yicloud/base/auth/__init__.py

@@ -0,0 +1,10 @@
+from yicloud.base.auth.credential import Credential, DefaultCredential, sign
+from yicloud.base.auth.sign import hmac_sign, parse_and_sort_query
+
+__all__ = [
+    "Credential",
+    "DefaultCredential",
+    "sign",
+    "hmac_sign",
+    "parse_and_sort_query",
+]

yicloud/base/auth/credential.py

@@ -0,0 +1,64 @@
+import os
+import time
+import json as json_module
+from typing import Any
+from yicloud.base.auth.sign import hmac_sign
+
+
+class Credential:
+    """Credential struct matching Go SDK's auth.Credential."""
+
+    def __init__(self, public_key: str = "", private_key: str = ""):
+        self.public_key = public_key
+        self.private_key = private_key
+
+    @classmethod
+    def new_credential(cls) -> "Credential":
+        """Return credential with default values from env."""
+        cred = cls()
+        cred._apply_env()
+        return cred
+
+    def _apply_env(self):
+        """Apply environment variables to credential."""
+        v = os.getenv("YICLOUD_PUBLIC_KEY")
+        if v and v.strip():
+            self.public_key = v
+
+        v = os.getenv("YICLOUD_SECRET_KEY")
+        if v and v.strip():
+            self.private_key = v
+
+    def sign(self, tick: time.struct_time, query: str, body: Any) -> str:
+        """Create signature encoding query string to credential signature."""
+        body_str = Credential._any_to_string(body)
+        timestamp = str(int(time.mktime(tick) * 1000))
+        return hmac_sign(timestamp, self.public_key, self.private_key, query, body_str)
+
+    @staticmethod
+    def _any_to_string(value: Any) -> str:
+        """Convert any type to signature string, matching Go SDK's anyToString."""
+        if value is None:
+            return ""
+
+        if isinstance(value, str):
+            return value
+
+        if isinstance(value, bytes):
+            return value.decode("utf-8")
+
+        # For complex types (dict, list, etc.), use JSON serialization
+        if isinstance(value, (dict, list)):
+            return json_module.dumps(value, separators=(",", ":"))
+
+        # For simple types, use str()
+        return str(value)
+
+
+# Default credential singleton
+DefaultCredential = Credential.new_credential()
+
+
+def sign(tick: time.struct_time, query: str, body: Any) -> str:
+    """Package-level sign function using DefaultCredential."""
+    return DefaultCredential.sign(tick, query, body)

yicloud/base/auth/sign.py

@@ -0,0 +1,80 @@
+import hmac
+import hashlib
+from urllib.parse import unquote, quote
+
+
+class KV:
+    """KV represents a query parameter (preserve order)."""
+
+    def __init__(self, key: str, value: str):
+        self.key = key
+        self.value = value
+
+
+def parse_and_sort_query(raw: str) -> str:
+    """
+    Parse and sort query string.
+    Matches Go SDK's parseAndSortQuery function.
+    """
+    if not raw:
+        return ""
+
+    parts = raw.split("&")
+    kvs = []
+
+    for p in parts:
+        if not p:
+            continue
+
+        if "=" in p:
+            arr = p.split("=", 1)
+            key = unquote(arr[0]) if arr[0] else ""
+            val = unquote(arr[1]) if len(arr) > 1 else ""
+        else:
+            key = unquote(p) if p else ""
+            val = ""
+
+        kvs.append(KV(key, val))
+
+    # Stable sort: key ASC, same key keeps original order
+    kvs.sort(key=lambda kv: kv.key)
+
+    # Concatenate: key + value
+    result = ""
+    for kv in kvs:
+        result += kv.key + kv.value
+
+    return result
+
+
+def hmac_sign(
+    ts: str, accessKey: str, secretKey: str, query: str, body: str
+) -> str:
+    """
+    Generate HMAC-SHA256 signature following the pattern:
+    ts + accessKey + sortedQuery + body
+    Matches Go SDK's HmacSign function.
+
+    Args:
+        ts: timestamp string, e.g., "1678901234"
+        accessKey: user's accessKey
+        secretKey: user's secretKey
+        query: query parameters
+        body: request body, if JSON object, structure as dict, no body can be None
+
+    Returns:
+        hex-encoded HMAC-SHA256 signature
+    """
+    # 1. Process query parameters
+    QS = parse_and_sort_query(query)
+
+    # 2. Build string to sign
+    toSign = ts + accessKey + QS + body
+
+    # 3. HMAC-SHA256
+    mac = hmac.new(
+        secretKey.encode("utf-8"), toSign.encode("utf-8"), hashlib.sha256
+    )
+    signature = mac.hexdigest()
+
+    return signature

yicloud/base/client.py

@@ -0,0 +1,313 @@
+import dataclasses
+import json
+import time
+from pathlib import Path
+from typing import Any, Callable, Optional
+import requests
+
+from yicloud.base import config, auth, errs, log, msgs, utils
+from yicloud.base.utils.retry import retry, with_attempts
+
+
+class DataclassEncoder(json.JSONEncoder):
+    def default(self, o):
+        if dataclasses.is_dataclass(o):
+            return dataclasses.asdict(o)
+        return super().default(o)
+
+
+Context = Optional[dict]
+
+
+class Client:
+    """Client struct matching Go SDK's base.Client."""
+
+    def __init__(
+        self,
+        cfg: config.Config = None,
+        crede: auth.Credential = None,
+        http_client=None,
+        transport=None,
+        logger: log.Logger = None,
+        host: str = "",
+    ):
+        self.config = cfg or config.DefaultConfig
+        self.crede = crede or auth.DefaultCredential
+        self.transport = transport
+        self.logger = logger or log.get_default_logger()
+        self.host = host
+
+        # Create requests session
+        if http_client:
+            self.http_client = http_client
+        else:
+            self.http_client = requests.Session()
+            self.http_client.verify = True  # SSL verification
+
+    @classmethod
+    def new(cls, *options: Callable[["Client"], None]) -> "Client":
+        """Create client with options."""
+        c = cls(
+            cfg=config.DefaultConfig,
+            crede=auth.DefaultCredential,
+            logger=log.get_default_logger(),
+        )
+
+        for opt in options:
+            opt(c)
+
+        # Recreate http_client if transport was set
+        if c.transport:
+            c.http_client = requests.Session()
+            c.http_client.verify = True
+
+        return c
+
+
+def new_client(*options: Callable[["Client"], None]) -> Client:
+    """Module-level function to create a client with options."""
+    return Client.new(*options)
+
+
+# Default client singleton
+DefaultClient = new_client()
+
+
+def with_transport(transport) -> Callable[[Client], None]:
+    return lambda c: setattr(c, "transport", transport)
+
+
+def with_http_client(http_client) -> Callable[[Client], None]:
+    return lambda c: setattr(c, "http_client", http_client)
+
+
+def with_host(host: str) -> Callable[[Client], None]:
+    return lambda c: setattr(c, "host", host)
+
+
+def with_config(cfg: config.Config) -> Callable[[Client], None]:
+    return lambda c: setattr(c, "config", cfg)
+
+
+def with_credential(crede: auth.Credential) -> Callable[[Client], None]:
+    return lambda c: setattr(c, "crede", crede)
+
+
+def with_logger(l: log.Logger) -> Callable[[Client], None]:
+    return lambda c: setattr(c, "logger", l)
+
+
+class netErr(Exception):
+    """Network error type matching Go SDK's netErr."""
+    def __init__(self, desc: str):
+        self.desc = desc
+
+    def __str__(self) -> str:
+        return self.desc
+
+
+def new_net_err(desc: str) -> netErr:
+    return netErr(desc)
+
+
+def is_net_err(err: Exception) -> bool:
+    return isinstance(err, netErr)
+
+
+def action_of_path(p: str) -> str:
+    """Extract action name from path."""
+    return Path(p).name
+
+
+# Module-level get using DefaultClient
+def get(ctx: Context, path: str, query: Any, rsp: msgs.Response) -> None:
+    """GET request using DefaultClient.
+
+    Raises YiCloudException on error.
+    """
+    DefaultClient.get(ctx, path, query, rsp)
+
+
+def get(self, ctx: Context, path: str, query: Any, rsp: msgs.Response) -> None:
+    """GET request, matching Go SDK's Get.
+
+    Raises YiCloudException on error.
+    """
+    query_str = utils.build_query(query)
+    err = self._request(ctx, "GET", path, query_str, None, rsp)
+    if err:
+        raise err
+
+
+# Add get method to Client class
+Client.get = get
+
+
+# Module-level post using DefaultClient
+def post(ctx: Context, path: str, body: Any, rsp: msgs.Response) -> None:
+    """POST request using DefaultClient.
+
+    Raises YiCloudException on error.
+    """
+    DefaultClient.post(ctx, path, body, rsp)
+
+
+def post(self, ctx: Context, path: str, body: Any, rsp: msgs.Response) -> None:
+    """POST request, matching Go SDK's Post.
+
+    Raises YiCloudException on error.
+    """
+    err = self._request(ctx, "POST", path, "", body, rsp)
+    if err:
+        raise err
+
+
+# Add post method to Client class
+Client.post = post
+
+
+def _request(
+    self,
+    ctx: Context,
+    method: str,
+    path: str,
+    query: str,
+    body: Any,
+    rsp: msgs.Response,
+) -> Optional[errs.YiCloudException]:
+    """
+    Core request method matching Go SDK's request.
+
+    Returns None on success, or a YiCloudException on error.
+    """
+    action = action_of_path(path)
+
+    # Validate credential
+    if not self.crede.public_key or not self.crede.private_key:
+        return errs.new_client_error(
+            action,
+            Exception("public key or secret key not provided")
+        )
+
+    now = time.localtime()
+    tick_str = str(int(time.mktime(now) * 1000))
+
+    # Validate response
+    if rsp is None:
+        return errs.new_client_error(action, Exception("rsp cannot be None"))
+
+    # Build URL
+    full_url = self.config.host + path
+    if query:
+        full_url += "?" + query
+
+    # Build body
+    req_body = None
+    body_str = ""
+    if body is not None:
+        try:
+            bs = json.dumps(body, separators=(",", ":"), cls=DataclassEncoder)
+            body_str = bs
+            req_body = bs
+        except Exception as e:
+            return errs.new_client_error(action, e)
+
+    # Generate signature
+    try:
+        sign = self.crede.sign(now, query, body_str)
+    except Exception as e:
+        return errs.new_client_error(action, e)
+
+    # Build headers
+    headers = {
+        "Content-Type": "application/json",
+        "User-Agent": self.config.get_user_agent(),
+        "X-OGW-PUBLIC-KEY": self.crede.public_key,
+        "X-OGW-TICK": tick_str,
+        "X-OGW-SIGN": sign,
+    }
+
+    # Execute request
+    resp: Optional[requests.Response] = None
+    try:
+        if self.config.max_retries > 0:
+            # Retry logic for network errors only
+            def request_fn(cl_ctx: Context) -> requests.Response:
+                nonlocal resp
+                resp = self.http_client.request(
+                    method=method,
+                    url=full_url,
+                    headers=headers,
+                    data=req_body,
+                    timeout=self.config.timeout,
+                )
+                return resp
+
+            resp = retry(ctx, request_fn, with_attempts(self.config.max_retries))
+        else:
+            resp = self.http_client.request(
+                method=method,
+                url=full_url,
+                headers=headers,
+                data=req_body,
+                timeout=self.config.timeout,
+            )
+    except requests.RequestException as e:
+        return errs.new_client_error(action, e)
+
+    # Parse response headers
+    request_id = resp.headers.get("X-OGW-Request-Id", "")
+
+    # Write meta to context
+    meta, ok = msgs.get_rsp_meta(ctx)
+    if ok and meta:
+        meta.request_id = request_id
+
+    # HTTP status check
+    if resp.status_code != 200:
+        return errs.new_server_error(action, resp.status_code)
+
+    # Parse response body
+    resp_bytes = resp.content
+
+    # Deserialize
+    try:
+        resp_dict = json.loads(resp_bytes)
+    except Exception as e:
+        return errs.new_client_error(action, e)
+
+    # Fill response from JSON
+    if isinstance(rsp, msgs.Rsp):
+        # Header
+        rsp.header = msgs.Header(
+            code=resp_dict.get("Code", 0),
+            msg=resp_dict.get("Msg", ""),
+            cost=resp_dict.get("_cost", 0),
+            err=resp_dict.get("_err", "")
+        )
+
+        # Data
+        if "Data" in resp_dict and resp_dict["Data"] is not None:
+            rsp.data = resp_dict["Data"]
+
+    # Update meta with cost and error
+    if ok and meta:
+        if hasattr(rsp, "header"):
+            meta.cost = rsp.header.cost
+            meta.err = rsp.header.err
+
+    # Business return code check
+    if rsp.get_code() != 0:
+        return errs.new_server_error(
+            action,
+            resp.status_code,
+            rsp.get_code(),
+            rsp.get_msg(),
+            request_id
+        )
+
+    return None
+
+
+# Add _request method to Client class
+Client._request = _request

yicloud/base/config.py

@@ -0,0 +1,62 @@
+import os
+import version
+from yicloud.base.log import Level
+
+
+class Config:
+    """Config struct matching Go SDK's config.Config."""
+
+    def __init__(
+        self,
+        host: str = "",
+        user_agent: str = "",
+        timeout: float = 30.0,
+        max_retries: int = 0,
+        log_level: int = Level.WARN,
+    ):
+        self.host = host
+        self.user_agent = user_agent
+        self.timeout = timeout
+        self.max_retries = max_retries
+        self.log_level = log_level
+
+    def get_user_agent(self) -> str:
+        return self.user_agent
+
+    @staticmethod
+    def new_default_config() -> "Config":
+        cfg = Config(
+            host="https://gate.yicloud.com",
+            user_agent=version.UserAgent(),
+            timeout=30.0,
+            max_retries=0,
+            log_level=Level.WARN,
+        )
+        cfg._apply_env()
+        return cfg
+
+    def _apply_env(self):
+        """Apply environment variables to config."""
+        v = os.getenv("YICLOUD_API_HOST")
+        if v and v.strip():
+            self.host = v
+
+        v = os.getenv("YICLOUD_TIMEOUT")
+        if v and v.strip():
+            if v.isdigit():
+                self.timeout = float(v)
+
+        v = os.getenv("YICLOUD_MAX_RETRIES")
+        if v and v.strip():
+            try:
+                self.max_retries = int(v)
+            except ValueError:
+                pass
+
+    @staticmethod
+    def new() -> "Config":
+        return Config.new_default_config()
+
+
+# Default config singleton
+DefaultConfig = Config.new_default_config()