py_wisharetec_toolkit 3.0.2__py3-none-any.whl

py_wisharetec_toolkit/__init__.py

@@ -0,0 +1,11 @@
+#!/usr/bin/env python3
+# -*- coding: UTF-8 -*-
+"""py_wisharetec_toolkit 顶层包。
+
+可供他人通过 `import py_wisharetec_toolkit` 导入。
+"""
+
+__version__ = "3.0.2"
+__all__ = ["shanshu"]
+
+from . import shanshu  # noqa: E402

py_wisharetec_toolkit/shanshu/__init__.py

@@ -0,0 +1,18 @@
+#!/usr/bin/env python3
+# -*- coding: UTF-8 -*-
+
+"""shanshu 子包。
+
+可供他人通过 `from py_wisharetec_toolkit import shanshu` 或
+`from py_wisharetec_toolkit.shanshu import client, models, auth` 导入。
+"""
+
+__version__ = "3.0.2"
+__all__ = ["client", "models", "auth"]
+
+from . import client  # noqa: E402
+from . import models  # noqa: E402
+from . import auth  # noqa: E402
+
+# 将异步客户端类也导出到顶层，方便直接使用
+from .client import AsyncShanshuClient, AsyncShanshuClientConfig  # noqa: E402

py_wisharetec_toolkit/shanshu/auth.py

@@ -0,0 +1,143 @@
+#!/usr/bin/env python3
+# -*- coding: UTF-8 -*-
+
+"""Shanshu 登录认证与 Token 缓存。
+
+提供基于 httpx 的 ``/api/user/loginInteractive`` 接口调用，
+并支持 memory / diskcache / redis 三种 Token 缓存后端。
+
+缓存 key 格式：py_wisharetec_toolkit:shanshu:authorization_token:{account}
+便于缓存不同用户的登录 token。
+"""
+
+from __future__ import annotations
+
+import hashlib
+import threading
+from typing import Any, Protocol, runtime_checkable
+
+LOGIN_PATH = "api/user/loginInteractive"
+CACHE_KEY_PREFIX = "py_wisharetec_toolkit:shanshu:authorization_token"
+
+
+def cache_key(account: str) -> str:
+    """构造 Token 缓存 key。
+
+    格式：py_wisharetec_toolkit:shanshu:authorization_token:{account}
+    """
+    return f"{CACHE_KEY_PREFIX}:{account}"
+
+
+@runtime_checkable
+class ShanshuTokenCache(Protocol):
+    """Token 缓存协议，key 为 cache_key(account) 生成的字符串。"""
+
+    def get(self, key: str) -> str | None: ...
+
+    def set(self, key: str, token: str, ttl: int | None = None) -> None: ...
+
+
+class ShanshuMemoryTokenCache:
+    """进程内内存缓存（默认后端，无需额外依赖，线程安全）。"""
+
+    def __init__(self) -> None:
+        self._tokens: dict[str, str] = {}
+        self._lock = threading.Lock()
+
+    def get(self, key: str) -> str | None:
+        with self._lock:
+            return self._tokens.get(key)
+
+    def set(self, key: str, token: str, ttl: int | None = None) -> None:
+        with self._lock:
+            self._tokens[key] = token
+
+
+class ShanshuDiskCacheTokenCache:
+    """基于 diskcache 的持久化缓存。
+
+    需要额外安装：pip install diskcache
+    """
+
+    def __init__(
+        self,
+        cache_dir: str = ".runtime/cache/diskcache",
+        table: str = "token",
+        expire: int | None = None,
+    ) -> None:
+        try:
+            import diskcache as dc
+        except ImportError as exc:  # pragma: no cover
+            raise ImportError(
+                "使用 ShanshuDiskCacheTokenCache 需要安装 diskcache: pip install diskcache"
+            ) from exc
+        self._cache = dc.Cache(cache_dir, table=table)
+        self._expire = expire
+
+    def get(self, key: str) -> str | None:
+        return self._cache.get(key)
+
+    def set(self, key: str, token: str, ttl: int | None = None) -> None:
+        expire = ttl if ttl is not None else self._expire
+        self._cache.set(key, token, expire=expire)
+
+
+class ShanshuRedisTokenCache:
+    """基于 redis 的缓存。
+
+    需要额外安装：pip install redis
+    """
+
+    def __init__(
+        self,
+        host: str = "localhost",
+        port: int = 6379,
+        db: int = 0,
+        password: str | None = None,
+        expire: int | None = None,
+        **kwargs: Any,
+    ) -> None:
+        try:
+            import redis as redis_lib
+        except ImportError as exc:  # pragma: no cover
+            raise ImportError(
+                "使用 ShanshuRedisTokenCache 需要安装 redis: pip install redis"
+            ) from exc
+        self._client = redis_lib.Redis(
+            host=host,
+            port=port,
+            db=db,
+            password=password,
+            **kwargs,
+        )
+        self._expire = expire
+
+    def get(self, key: str) -> str | None:
+        val = self._client.get(key)
+        if val is None:
+            return None
+        return val.decode() if isinstance(val, bytes) else val
+
+    def set(self, key: str, token: str, ttl: int | None = None) -> None:
+        expire = ttl if ttl is not None else self._expire
+        if expire is not None:
+            self._client.set(key, token, ex=expire)
+        else:
+            self._client.set(key, token)
+
+
+def md5(text: str) -> str:
+    """计算字符串的 MD5 哈希（小写十六进制）。"""
+    return hashlib.md5(text.encode("utf-8")).hexdigest()
+
+
+__all__ = [
+    "LOGIN_PATH",
+    "CACHE_KEY_PREFIX",
+    "cache_key",
+    "ShanshuTokenCache",
+    "ShanshuMemoryTokenCache",
+    "ShanshuDiskCacheTokenCache",
+    "ShanshuRedisTokenCache",
+    "md5",
+]