litequant 3.0.0__tar.gz → 3.0.2__tar.gz

{litequant-3.0.0 → litequant-3.0.2}/LiteQuantClient.py

@@ -16,7 +16,7 @@ LiteQuant 3.0 Client - 独立简洁版
         save_path='D:/LiteQuant/'
     )
     
-    client.UpdateAllCategory(update_method='full')
+    client.UpdateAllCategory(update_method='full')
     df = client.GetCategory("cn_stock_pivot#open")
     
     # 使用 with 语句（自动关闭）
@@ -29,9 +29,10 @@ import io
 import json
 import logging
 import os
+import fnmatch
 import time
-import threading
-from typing import Any, Dict, List, Optional, Literal
+import threading
+from typing import Any, Dict, List, Optional, Literal
 from dataclasses import dataclass
 from datetime import datetime, timedelta
 
@@ -41,54 +42,55 @@ import requests
 from tqdm import tqdm
 
 from .ParquetManager import ParquetDataManager
-from .exceptions import (
-    LiteQuantError,
-    AuthError,
-    CategoryNotFoundError,
-    InvalidCategoryError,
-    RemoteDataError,
-    SerializationError,
-    MetaError,
-    ProtocolError,
-    TicketExpiredError,
-    QuotaExceededError,
-    PermissionDeniedError,
-    NetworkError,
-    DataConnectionError,
-    ServiceUnavailableError,
-    SyncError,
-    APIError,
-)
+from .exceptions import (
+    LiteQuantError,
+    AuthError,
+    CategoryNotFoundError,
+    InvalidCategoryError,
+    RemoteDataError,
+    SerializationError,
+    MetaError,
+    ProtocolError,
+    TicketExpiredError,
+    QuotaExceededError,
+    PermissionDeniedError,
+    NetworkError,
+    DataConnectionError,
+    ServiceUnavailableError,
+    SyncError,
+    APIError,
+)
 from .log import GetLogger
 
 
 # ============ 数据模型 ============
 
-@dataclass(repr=False)
-class DataTicket:
-    """Data Ticket data returned by the service."""
-    ticket_id: str
-    session_id: str
-    redis_host: str
-    redis_port: int
-    redis_password: str
-    expires_at: datetime
-    datasets: List[str]
-    key_patterns: List[str]
-    redis_username: Optional[str] = None
-    redis_ssl: bool = False
+@dataclass(repr=False)
+class DataTicket:
+    """Data Ticket data returned by the service."""
+    ticket_id: str
+    session_id: str
+    redis_host: str
+    redis_port: int
+    redis_password: str
+    expires_at: datetime
+    datasets: List[str]
+    key_patterns: List[str]
+    category_patterns: Optional[List[str]] = None
+    redis_username: Optional[str] = None
+    redis_ssl: bool = False
     
     @property
     def is_expired(self) -> bool:
         return datetime.now() >= self.expires_at
     
     @property
-    def ttl_seconds(self) -> float:
-        delta = self.expires_at - datetime.now()
-        return max(0, delta.total_seconds())
-
-    def __repr__(self) -> str:
-        return "DataTicket(<hidden>)"
+    def ttl_seconds(self) -> float:
+        delta = self.expires_at - datetime.now()
+        return max(0, delta.total_seconds())
+
+    def __repr__(self) -> str:
+        return "DataTicket(<hidden>)"
 
 
 # ============ 核心客户端 ============
@@ -107,7 +109,7 @@ class LiteQuantClient:
     """
     
     # 常量配置
-    DEFAULT_API_URL = os.environ.get('LITEQUANT_API_URL', 'https://www.litequant.pro')
+    DEFAULT_API_URL = os.environ.get('LITEQUANT_API_URL', 'https://www.litequant.pro')
     PROTOCOL_VERSION = 1
     DATA_FORMAT = "parquet"
     
@@ -116,69 +118,69 @@ class LiteQuantClient:
     TICKET_REFRESH_THRESHOLD = 30  # 过期前30秒续租
     
     # Redis Key 前缀
-    META_CATEGORIES_KEY = "litequant:meta:categories"
-    META_CATEGORY_KEY_PREFIX = "litequant:meta:category:"
-    META_PARTITION_KEY_PREFIX = "litequant:meta:partition:"
-    
-    PUBLIC_ERROR_MESSAGES = {
-        "AUTH_INVALID": "API 凭证无效或已过期，请检查后重试",
-        "ACCOUNT_UNAVAILABLE": "账号不可用，请联系管理员处理",
-        "SUBSCRIPTION_UNAVAILABLE": "套餐不可用或已过期，请续费后重试",
-        "PERMISSION_DENIED": "权限不足：当前账号没有该数据权限",
-        "CONNECTION_LIMIT": "连接数已达上限，请关闭其他连接后重试",
-        "CONNECTION_INTERRUPTED": "连接中断，请重新初始化客户端",
-        "REQUEST_INVALID": "请求参数无效，请检查输入后重试",
-        "SERVICE_UNAVAILABLE": "服务暂时不可用，请稍后重试",
-        "DATA_UNAVAILABLE": "数据暂时不可用，请稍后重试",
-        "DATA_VERIFY_FAILED": "数据校验失败，请重新同步",
-    }
-    LEGACY_ERROR_CODE_MAP = {
-        "Unauthorized": "AUTH_INVALID",
-        "UserDisabled": "ACCOUNT_UNAVAILABLE",
-        "SubscriptionInvalid": "SUBSCRIPTION_UNAVAILABLE",
-        "SubscriptionExpired": "SUBSCRIPTION_UNAVAILABLE",
-        "NoDatasetAccess": "PERMISSION_DENIED",
-        "ConnectionLimitExceeded": "CONNECTION_LIMIT",
-        "InvalidRequest": "REQUEST_INVALID",
-        "MissingParameters": "REQUEST_INVALID",
-        "TicketNotFound": "CONNECTION_INTERRUPTED",
-        "TicketExpired": "CONNECTION_INTERRUPTED",
-        "SessionNotFound": "CONNECTION_INTERRUPTED",
-        "SessionExpired": "CONNECTION_INTERRUPTED",
-        "RenewFailed": "CONNECTION_INTERRUPTED",
-        "InternalError": "SERVICE_UNAVAILABLE",
-    }
-    ERROR_CLASS_MAP = {
-        "AUTH_INVALID": AuthError,
-        "ACCOUNT_UNAVAILABLE": PermissionDeniedError,
-        "SUBSCRIPTION_UNAVAILABLE": PermissionDeniedError,
-        "PERMISSION_DENIED": PermissionDeniedError,
-        "CONNECTION_LIMIT": QuotaExceededError,
-        "CONNECTION_INTERRUPTED": DataConnectionError,
-        "REQUEST_INVALID": APIError,
-        "SERVICE_UNAVAILABLE": ServiceUnavailableError,
-        "DATA_UNAVAILABLE": RemoteDataError,
-        "DATA_VERIFY_FAILED": SerializationError,
-    }
+    META_CATEGORIES_KEY = "litequant:meta:categories"
+    META_CATEGORY_KEY_PREFIX = "litequant:meta:category:"
+    META_PARTITION_KEY_PREFIX = "litequant:meta:partition:"
+    
+    PUBLIC_ERROR_MESSAGES = {
+        "AUTH_INVALID": "API 凭证无效或已过期，请检查后重试",
+        "ACCOUNT_UNAVAILABLE": "账号不可用，请联系管理员处理",
+        "SUBSCRIPTION_UNAVAILABLE": "套餐不可用或已过期，请续费后重试",
+        "PERMISSION_DENIED": "权限不足：当前账号没有该数据权限",
+        "CONNECTION_LIMIT": "连接数已达上限，请关闭其他连接后重试",
+        "CONNECTION_INTERRUPTED": "连接中断，请重新初始化客户端",
+        "REQUEST_INVALID": "请求参数无效，请检查输入后重试",
+        "SERVICE_UNAVAILABLE": "服务暂时不可用，请稍后重试",
+        "DATA_UNAVAILABLE": "数据暂时不可用，请稍后重试",
+        "DATA_VERIFY_FAILED": "数据校验失败，请重新同步",
+    }
+    LEGACY_ERROR_CODE_MAP = {
+        "Unauthorized": "AUTH_INVALID",
+        "UserDisabled": "ACCOUNT_UNAVAILABLE",
+        "SubscriptionInvalid": "SUBSCRIPTION_UNAVAILABLE",
+        "SubscriptionExpired": "SUBSCRIPTION_UNAVAILABLE",
+        "NoDatasetAccess": "PERMISSION_DENIED",
+        "ConnectionLimitExceeded": "CONNECTION_LIMIT",
+        "InvalidRequest": "REQUEST_INVALID",
+        "MissingParameters": "REQUEST_INVALID",
+        "TicketNotFound": "CONNECTION_INTERRUPTED",
+        "TicketExpired": "CONNECTION_INTERRUPTED",
+        "SessionNotFound": "CONNECTION_INTERRUPTED",
+        "SessionExpired": "CONNECTION_INTERRUPTED",
+        "RenewFailed": "CONNECTION_INTERRUPTED",
+        "InternalError": "SERVICE_UNAVAILABLE",
+    }
+    ERROR_CLASS_MAP = {
+        "AUTH_INVALID": AuthError,
+        "ACCOUNT_UNAVAILABLE": PermissionDeniedError,
+        "SUBSCRIPTION_UNAVAILABLE": PermissionDeniedError,
+        "PERMISSION_DENIED": PermissionDeniedError,
+        "CONNECTION_LIMIT": QuotaExceededError,
+        "CONNECTION_INTERRUPTED": DataConnectionError,
+        "REQUEST_INVALID": APIError,
+        "SERVICE_UNAVAILABLE": ServiceUnavailableError,
+        "DATA_UNAVAILABLE": RemoteDataError,
+        "DATA_VERIFY_FAILED": SerializationError,
+    }
     
     def __init__(
         self,
         api_token: str,
-        save_path: str,
-        api_url: str = None,
-        log_level: int = logging.INFO,
-        display_errors: bool = True,
-    ):
-        self.api_token = api_token
-        self.api_url = (api_url or os.environ.get('LITEQUANT_API_URL', self.DEFAULT_API_URL)).rstrip("/")
-        self.save_path = os.path.abspath(save_path)
-        self.display_errors = display_errors
+        save_path: str,
+        api_url: str = None,
+        log_level: int = logging.INFO,
+        display_errors: bool = True,
+    ):
+        self.api_token = api_token
+        self.api_url = (api_url or os.environ.get('LITEQUANT_API_URL', self.DEFAULT_API_URL)).rstrip("/")
+        self.save_path = os.path.abspath(save_path)
+        self.display_errors = display_errors
         
         # 确保路径存在
         os.makedirs(self.save_path, exist_ok=True)
         
         # 日志（使用 token 前8位作为标识）
-        self.logger = GetLogger("litequant", level=log_level)
+        self.logger = GetLogger("litequant", level=log_level)
         self.logger.info(f"初始化 LiteQuantClient")
         
         # 数据管理器
@@ -197,17 +199,17 @@ class LiteQuantClient:
         self._remote_categories_set = set()
         
         # 初始化连接
-        try:
-            self._init_connection()
-            self._start_heartbeat()
-        except LiteQuantError as e:
-            err = self._public_error_clone(e)
-            self._display_error(err)
-            raise err from None
-        except Exception as e:
-            err = ServiceUnavailableError()
-            self._display_error(err)
-            raise err from None
+        try:
+            self._init_connection()
+            self._start_heartbeat()
+        except LiteQuantError as e:
+            err = self._public_error_clone(e)
+            self._display_error(err)
+            raise err from None
+        except Exception as e:
+            err = ServiceUnavailableError()
+            self._display_error(err)
+            raise err from None
         
         # 启动心跳
         
@@ -215,93 +217,93 @@ class LiteQuantClient:
     
     # ============ 连接管理 ============
     
-    def _display_error(self, error: LiteQuantError) -> None:
-        """Print a privacy-safe user message to the configured SDK logger."""
-        if self.display_errors:
-            self.logger.error(error.user_message)
-
-    def _public_error_clone(self, error: LiteQuantError) -> LiteQuantError:
-        """Return a fresh privacy-safe exception without traceback/cause state."""
-        return error.__class__(
-            code=error.code,
-            user_message=error.user_message,
-            retryable=error.retryable,
-        )
-
-    def _as_litequant_error(self, error: Exception) -> LiteQuantError:
-        if isinstance(error, LiteQuantError):
-            return self._public_error_clone(error)
-        return ServiceUnavailableError()
-
-    def _api_post_json(self, endpoint: str, payload: dict, timeout: int) -> dict:
-        url = f"{self.api_url}{endpoint}"
-        headers = {
-            "Authorization": f"Bearer {self.api_token}",
-            "Content-Type": "application/json",
-        }
-        try:
-            response = requests.post(url, headers=headers, json=payload, timeout=timeout)
-        except (requests.exceptions.Timeout, requests.exceptions.ConnectionError):
-            raise NetworkError() from None
-        except requests.exceptions.RequestException:
-            raise ServiceUnavailableError() from None
-
-        return self._parse_api_response(response)
-
-    def _parse_api_response(self, response: Any) -> dict:
-        status_code = getattr(response, "status_code", 200)
-        ok = getattr(response, "ok", 200 <= status_code < 300)
-        try:
-            data = response.json()
-        except ValueError:
-            public_code = self._public_code_from_status(status_code)
-            raise self._build_public_error(public_code) from None
-
-        if not isinstance(data, dict):
-            raise ServiceUnavailableError(detail="invalid response shape")
-
-        if ok and data.get("success", True):
-            return data
-
-        public_code = self._normalize_error_code(data.get("error"), status_code)
-        raise self._build_public_error(public_code) from None
-
-    def _normalize_error_code(self, raw_code: Any, status_code: int = None) -> str:
-        if raw_code:
-            raw_code = str(raw_code)
-            public_code = self.LEGACY_ERROR_CODE_MAP.get(raw_code, raw_code)
-            if public_code in self.PUBLIC_ERROR_MESSAGES:
-                return public_code
-        return self._public_code_from_status(status_code)
-
-    def _public_code_from_status(self, status_code: int = None) -> str:
-        if status_code == 401:
-            return "AUTH_INVALID"
-        if status_code == 403:
-            return "PERMISSION_DENIED"
-        if status_code == 429:
-            return "CONNECTION_LIMIT"
-        if status_code == 400:
-            return "REQUEST_INVALID"
-        if status_code and status_code >= 500:
-            return "SERVICE_UNAVAILABLE"
-        return "SERVICE_UNAVAILABLE"
-
-    def _build_public_error(self, public_code: str, detail: Any = None) -> LiteQuantError:
-        error_cls = self.ERROR_CLASS_MAP.get(public_code, ServiceUnavailableError)
-        return error_cls(
-            code=public_code,
-            user_message=self.PUBLIC_ERROR_MESSAGES.get(public_code, self.PUBLIC_ERROR_MESSAGES["SERVICE_UNAVAILABLE"]),
-            retryable=public_code in {
-                "CONNECTION_LIMIT",
-                "CONNECTION_INTERRUPTED",
-                "SERVICE_UNAVAILABLE",
-                "DATA_UNAVAILABLE",
-                "DATA_VERIFY_FAILED",
-            },
-        )
-
-    def _init_connection(self):
+    def _display_error(self, error: LiteQuantError) -> None:
+        """Print a privacy-safe user message to the configured SDK logger."""
+        if self.display_errors:
+            self.logger.error(error.user_message)
+
+    def _public_error_clone(self, error: LiteQuantError) -> LiteQuantError:
+        """Return a fresh privacy-safe exception without traceback/cause state."""
+        return error.__class__(
+            code=error.code,
+            user_message=error.user_message,
+            retryable=error.retryable,
+        )
+
+    def _as_litequant_error(self, error: Exception) -> LiteQuantError:
+        if isinstance(error, LiteQuantError):
+            return self._public_error_clone(error)
+        return ServiceUnavailableError()
+
+    def _api_post_json(self, endpoint: str, payload: dict, timeout: int) -> dict:
+        url = f"{self.api_url}{endpoint}"
+        headers = {
+            "Authorization": f"Bearer {self.api_token}",
+            "Content-Type": "application/json",
+        }
+        try:
+            response = requests.post(url, headers=headers, json=payload, timeout=timeout)
+        except (requests.exceptions.Timeout, requests.exceptions.ConnectionError):
+            raise NetworkError() from None
+        except requests.exceptions.RequestException:
+            raise ServiceUnavailableError() from None
+
+        return self._parse_api_response(response)
+
+    def _parse_api_response(self, response: Any) -> dict:
+        status_code = getattr(response, "status_code", 200)
+        ok = getattr(response, "ok", 200 <= status_code < 300)
+        try:
+            data = response.json()
+        except ValueError:
+            public_code = self._public_code_from_status(status_code)
+            raise self._build_public_error(public_code) from None
+
+        if not isinstance(data, dict):
+            raise ServiceUnavailableError(detail="invalid response shape")
+
+        if ok and data.get("success", True):
+            return data
+
+        public_code = self._normalize_error_code(data.get("error"), status_code)
+        raise self._build_public_error(public_code) from None
+
+    def _normalize_error_code(self, raw_code: Any, status_code: int = None) -> str:
+        if raw_code:
+            raw_code = str(raw_code)
+            public_code = self.LEGACY_ERROR_CODE_MAP.get(raw_code, raw_code)
+            if public_code in self.PUBLIC_ERROR_MESSAGES:
+                return public_code
+        return self._public_code_from_status(status_code)
+
+    def _public_code_from_status(self, status_code: int = None) -> str:
+        if status_code == 401:
+            return "AUTH_INVALID"
+        if status_code == 403:
+            return "PERMISSION_DENIED"
+        if status_code == 429:
+            return "CONNECTION_LIMIT"
+        if status_code == 400:
+            return "REQUEST_INVALID"
+        if status_code and status_code >= 500:
+            return "SERVICE_UNAVAILABLE"
+        return "SERVICE_UNAVAILABLE"
+
+    def _build_public_error(self, public_code: str, detail: Any = None) -> LiteQuantError:
+        error_cls = self.ERROR_CLASS_MAP.get(public_code, ServiceUnavailableError)
+        return error_cls(
+            code=public_code,
+            user_message=self.PUBLIC_ERROR_MESSAGES.get(public_code, self.PUBLIC_ERROR_MESSAGES["SERVICE_UNAVAILABLE"]),
+            retryable=public_code in {
+                "CONNECTION_LIMIT",
+                "CONNECTION_INTERRUPTED",
+                "SERVICE_UNAVAILABLE",
+                "DATA_UNAVAILABLE",
+                "DATA_VERIFY_FAILED",
+            },
+        )
+
+    def _init_connection(self):
         """初始化连接（获取 Ticket + 连接 Redis）"""
         self._fetch_ticket()
         self._connect_redis()
@@ -309,87 +311,88 @@ class LiteQuantClient:
     
     def _fetch_ticket(self) -> DataTicket:
         """从 Django API 获取 Data Ticket"""
-        try:
-            data = self._api_post_json(
-                "/api/v1/data/ticket/",
-                {"client_version": "3.0.0"},
-                timeout=30,
-            )
-            
-            redis_info = data["redis"]
-            scope = data.get("scope", {})
-            redis_username = redis_info.get("username")
-            redis_ssl = bool(redis_info.get("ssl", False))
-            
-            self._ticket = DataTicket(
-                ticket_id=data["ticket"],
-                session_id=data["session_id"],
-                redis_host=redis_info["host"],
-                redis_port=redis_info["port"],
-                redis_password=redis_info["password"],
-                expires_at=datetime.now() + timedelta(seconds=data["expires_in"]),
-                datasets=scope.get("datasets", []),
-                key_patterns=scope.get("key_patterns", []),
-                redis_username=redis_username,
-                redis_ssl=redis_ssl,
-            )
+        try:
+            data = self._api_post_json(
+                "/api/v1/data/ticket/",
+                {"client_version": "3.0.2"},
+                timeout=30,
+            )
+            
+            redis_info = data["redis"]
+            scope = data.get("scope", {})
+            redis_username = redis_info.get("username")
+            redis_ssl = bool(redis_info.get("ssl", False))
+            
+            self._ticket = DataTicket(
+                ticket_id=data["ticket"],
+                session_id=data["session_id"],
+                redis_host=redis_info["host"],
+                redis_port=redis_info["port"],
+                redis_password=redis_info["password"],
+                expires_at=datetime.now() + timedelta(seconds=data["expires_in"]),
+                datasets=scope.get("datasets", []),
+                key_patterns=scope.get("key_patterns", []),
+                category_patterns=scope.get("category_patterns", []),
+                redis_username=redis_username,
+                redis_ssl=redis_ssl,
+            )
+            
+            self.logger.debug("连接凭证已获取")
+            return self._ticket
             
-            self.logger.debug("连接凭证已获取")
-            return self._ticket
-            
-        except LiteQuantError:
-            raise
-        except (KeyError, TypeError, ValueError):
-            raise ServiceUnavailableError() from None
+        except LiteQuantError:
+            raise
+        except (KeyError, TypeError, ValueError):
+            raise ServiceUnavailableError() from None
     
     def _connect_redis(self):
         """使用 Ticket 连接 Redis"""
-        if not self._ticket:
-            raise DataConnectionError()
-        
-        try:
-            redis_kwargs = {
-                "host": self._ticket.redis_host,
-                "port": self._ticket.redis_port,
-                "password": self._ticket.redis_password,
-                "socket_timeout": 20,
-                "socket_connect_timeout": 5,
-                "decode_responses": False,
-            }
-            if self._ticket.redis_username:
-                redis_kwargs["username"] = self._ticket.redis_username
-                redis_kwargs["ssl"] = self._ticket.redis_ssl
-            else:
-                # Aliyun Tair can use password formatted as "username:password".
-                redis_kwargs["db"] = 0
-
-            for attempt in range(6):
-                self._redis_client = redis.Redis(**redis_kwargs)
-                try:
-                    if not self._redis_client.ping():
-                        raise DataConnectionError()
-                    break
-                except redis.AuthenticationError:
-                    try:
-                        self._redis_client.close()
-                    except Exception:
-                        pass
-                    self._redis_client = None
-                    if attempt >= 5:
-                        raise
-                    self.logger.warning(f"数据连接暂未就绪，正在重试 {attempt + 1}/5")
-                    time.sleep(3)
-            else:
-                raise DataConnectionError()
-            
-            self.logger.info("数据连接已建立")
+        if not self._ticket:
+            raise DataConnectionError()
+        
+        try:
+            redis_kwargs = {
+                "host": self._ticket.redis_host,
+                "port": self._ticket.redis_port,
+                "password": self._ticket.redis_password,
+                "socket_timeout": 20,
+                "socket_connect_timeout": 5,
+                "decode_responses": False,
+            }
+            if self._ticket.redis_username:
+                redis_kwargs["username"] = self._ticket.redis_username
+                redis_kwargs["ssl"] = self._ticket.redis_ssl
+            else:
+                # Aliyun Tair can use password formatted as "username:password".
+                redis_kwargs["db"] = 0
+
+            for attempt in range(6):
+                self._redis_client = redis.Redis(**redis_kwargs)
+                try:
+                    if not self._redis_client.ping():
+                        raise DataConnectionError()
+                    break
+                except redis.AuthenticationError:
+                    try:
+                        self._redis_client.close()
+                    except Exception:
+                        pass
+                    self._redis_client = None
+                    if attempt >= 5:
+                        raise
+                    self.logger.warning(f"数据连接暂未就绪，正在重试 {attempt + 1}/5")
+                    time.sleep(3)
+            else:
+                raise DataConnectionError()
             
-        except redis.AuthenticationError:
-            raise DataConnectionError() from None
-        except Exception as e:
-            if isinstance(e, LiteQuantError):
-                raise self._public_error_clone(e) from None
-            raise DataConnectionError() from None
+            self.logger.info("数据连接已建立")
+            
+        except redis.AuthenticationError:
+            raise DataConnectionError() from None
+        except Exception as e:
+            if isinstance(e, LiteQuantError):
+                raise self._public_error_clone(e) from None
+            raise DataConnectionError() from None
     
     def _disconnect_server(self):
         """通知服务器断开连接"""
@@ -415,35 +418,35 @@ class LiteQuantClient:
     def _ensure_connection(self):
         """确保连接有效（过期时自动刷新）"""
         if not self._ticket or self._ticket.is_expired:
-            self.logger.info("连接已过期，正在重新连接...")
+            self.logger.info("连接已过期，正在重新连接...")
             self._fetch_ticket()
             self._connect_redis()
         elif self._ticket.ttl_seconds < self.TICKET_REFRESH_THRESHOLD:
             self._renew_ticket()
     
-    def _renew_ticket(self):
-        """续租 Ticket"""
-        if not self._ticket:
-            raise DataConnectionError()
-        try:
-            data = self._api_post_json(
-                "/api/v1/data/heartbeat/",
-                {
-                    "ticket": self._ticket.ticket_id,
-                    "session_id": self._ticket.session_id,
-                },
-                timeout=10,
-            )
-            self._ticket.expires_at = datetime.now() + timedelta(seconds=data.get("expires_in", 60))
-            self.logger.debug("连接已保持")
-        except DataConnectionError:
-            self.logger.warning("连接已中断，正在重新连接...")
-            self._fetch_ticket()
-            self._connect_redis()
-        except LiteQuantError:
-            raise
-        except Exception:
-            raise ServiceUnavailableError() from None
+    def _renew_ticket(self):
+        """续租 Ticket"""
+        if not self._ticket:
+            raise DataConnectionError()
+        try:
+            data = self._api_post_json(
+                "/api/v1/data/heartbeat/",
+                {
+                    "ticket": self._ticket.ticket_id,
+                    "session_id": self._ticket.session_id,
+                },
+                timeout=10,
+            )
+            self._ticket.expires_at = datetime.now() + timedelta(seconds=data.get("expires_in", 60))
+            self.logger.debug("连接已保持")
+        except DataConnectionError:
+            self.logger.warning("连接已中断，正在重新连接...")
+            self._fetch_ticket()
+            self._connect_redis()
+        except LiteQuantError:
+            raise
+        except Exception:
+            raise ServiceUnavailableError() from None
     
     def _start_heartbeat(self):
         """启动后台心跳线程"""
@@ -455,45 +458,45 @@ class LiteQuantClient:
     def _heartbeat_loop(self):
         """心跳循环"""
         while not self._stop_heartbeat.wait(self.HEARTBEAT_INTERVAL):
-            try:
-                if self._ticket and self._ticket.ttl_seconds < self.TICKET_REFRESH_THRESHOLD:
-                    self._renew_ticket()
-            except LiteQuantError as e:
-                self.logger.warning(e.user_message)
-            except Exception:
-                self.logger.warning(ServiceUnavailableError().user_message)
+            try:
+                if self._ticket and self._ticket.ttl_seconds < self.TICKET_REFRESH_THRESHOLD:
+                    self._renew_ticket()
+            except LiteQuantError as e:
+                self.logger.warning(e.user_message)
+            except Exception:
+                self.logger.warning(ServiceUnavailableError().user_message)
     
     # ============ 核心用户接口 ============
     
-    def UpdateAllCategory(self, update_method: Literal['full', 'incremental'] = 'full') -> None:
-        """更新所有已授权的数据类别。"""
-        try:
-            return self._update_all_category(update_method)
-        except LiteQuantError as e:
-            err = self._public_error_clone(e)
-            self._display_error(err)
-            raise err from None
-        except Exception as e:
-            err = ServiceUnavailableError()
-            self._display_error(err)
-            raise err from None
-
-    def _update_all_category(self, update_method: Literal['full', 'incremental'] = 'full') -> None:
+    def UpdateAllCategory(self, update_method: Literal['full', 'incremental'] = 'full') -> None:
+        """更新所有已授权的数据类别。"""
+        try:
+            return self._update_all_category(update_method)
+        except LiteQuantError as e:
+            err = self._public_error_clone(e)
+            self._display_error(err)
+            raise err from None
+        except Exception as e:
+            err = ServiceUnavailableError()
+            self._display_error(err)
+            raise err from None
+
+    def _update_all_category(self, update_method: Literal['full', 'incremental'] = 'full') -> None:
         """
         更新所有授权的数据类别
         
-        Args:
-            update_method: 更新方式
-                - 'full' - 全量更新，扫描所有数据（首次使用或需要完整数据时）
-                - 'incremental' - 增量更新，只扫描最近两个月的数据（日常使用）
-        """
-        if update_method not in ('full', 'incremental'):
-            raise ValueError("update_method must be 'full' or 'incremental'")
-
-        self.logger.info(f"开始更新数据 [方式: {update_method}]")
-        
-        # 计算增量更新的日期范围（最近两个月）
-        incremental_start_date = None
+        Args:
+            update_method: 更新方式
+                - 'full' - 全量更新，扫描所有数据（首次使用或需要完整数据时）
+                - 'incremental' - 增量更新，只扫描最近两个月的数据（日常使用）
+        """
+        if update_method not in ('full', 'incremental'):
+            raise ValueError("update_method must be 'full' or 'incremental'")
+
+        self.logger.info(f"开始更新数据 [方式: {update_method}]")
+        
+        # 计算增量更新的日期范围（最近两个月）
+        incremental_start_date = None
         if update_method == 'incremental':
             incremental_start_date = datetime.now() - timedelta(days=60)
             self.logger.info(f"增量更新起始日期: {incremental_start_date.strftime('%Y-%m-%d')}")
@@ -508,48 +511,48 @@ class LiteQuantClient:
             self.logger.warning("没有可更新的数据类别")
             return
         
-        self.logger.info(f"发现 {len(self._remote_categories)} 个类别")
-        
-        # 同步所有类别
-        failures = []
-        for category in self._remote_categories:
-            try:
-                self.logger.info(f"正在同步: {category}")
-                self._sync_category(category, incremental_start_date=incremental_start_date)
-            except Exception as e:
-                err = self._as_litequant_error(e)
-                failures.append((category, err))
-                self.logger.error(f"{category}: {err.user_message}")
-        
-        if failures:
-            raise SyncError(user_message=f"部分数据更新失败：{len(failures)} 个数据类别未完成")
-        
-        self.logger.info("数据更新完成")
-    
-    def GetCategory(
-        self,
-        category: str,
-        start_date: Optional[str] = None,
-        end_date: Optional[str] = None,
-    ) -> pd.DataFrame:
-        """读取指定数据类别。"""
-        try:
-            return self._get_category(category, start_date, end_date)
-        except LiteQuantError as e:
-            err = self._public_error_clone(e)
-            self._display_error(err)
-            raise err from None
-        except Exception as e:
-            err = ServiceUnavailableError()
-            self._display_error(err)
-            raise err from None
-
-    def _get_category(
-        self,
-        category: str,
-        start_date: Optional[str] = None,
-        end_date: Optional[str] = None,
-    ) -> pd.DataFrame:
+        self.logger.info(f"发现 {len(self._remote_categories)} 个类别")
+        
+        # 同步所有类别
+        failures = []
+        for category in self._remote_categories:
+            try:
+                self.logger.info(f"正在同步: {category}")
+                self._sync_category(category, incremental_start_date=incremental_start_date)
+            except Exception as e:
+                err = self._as_litequant_error(e)
+                failures.append((category, err))
+                self.logger.error(f"{category}: {err.user_message}")
+        
+        if failures:
+            raise SyncError(user_message=f"部分数据更新失败：{len(failures)} 个数据类别未完成")
+        
+        self.logger.info("数据更新完成")
+    
+    def GetCategory(
+        self,
+        category: str,
+        start_date: Optional[str] = None,
+        end_date: Optional[str] = None,
+    ) -> pd.DataFrame:
+        """读取指定数据类别。"""
+        try:
+            return self._get_category(category, start_date, end_date)
+        except LiteQuantError as e:
+            err = self._public_error_clone(e)
+            self._display_error(err)
+            raise err from None
+        except Exception as e:
+            err = ServiceUnavailableError()
+            self._display_error(err)
+            raise err from None
+
+    def _get_category(
+        self,
+        category: str,
+        start_date: Optional[str] = None,
+        end_date: Optional[str] = None,
+    ) -> pd.DataFrame:
         """
         读取数据类别
         
@@ -586,24 +589,24 @@ class LiteQuantClient:
         else:
             return self.LQ_db.read_unstack_category(category)
     
-    def ListCategories(self) -> List[str]:
-        """列出所有可用的数据类别（远程）"""
-        try:
-            return self._list_categories()
-        except LiteQuantError as e:
-            err = self._public_error_clone(e)
-            self._display_error(err)
-            raise err from None
-        except Exception as e:
-            err = ServiceUnavailableError()
-            self._display_error(err)
-            raise err from None
-
-    def _list_categories(self) -> List[str]:
-        """列出所有可用的数据类别（远程）"""
-        self._ensure_connection()
-        self._refresh_categories()
-        return list(self._remote_categories)
+    def ListCategories(self) -> List[str]:
+        """列出所有可用的数据类别（远程）"""
+        try:
+            return self._list_categories()
+        except LiteQuantError as e:
+            err = self._public_error_clone(e)
+            self._display_error(err)
+            raise err from None
+        except Exception as e:
+            err = ServiceUnavailableError()
+            self._display_error(err)
+            raise err from None
+
+    def _list_categories(self) -> List[str]:
+        """列出所有可用的数据类别（远程）"""
+        self._ensure_connection()
+        self._refresh_categories()
+        return list(self._remote_categories)
     
     def ListLocalCategories(self) -> List[str]:
         """列出本地已存储的数据类别"""
@@ -650,13 +653,20 @@ class LiteQuantClient:
         all_categories = [str(x) for x in categories]
         
         # 过滤：只保留授权数据集的类别
-        if self._ticket and self._ticket.datasets:
+        if self._ticket and self._ticket.category_patterns:
+            authorized_patterns = [str(x) for x in self._ticket.category_patterns]
+            filtered_categories = [
+                cat for cat in all_categories
+                if any(fnmatch.fnmatchcase(cat, pattern) for pattern in authorized_patterns)
+            ]
+            self.logger.debug("??????: %s -> %s", len(all_categories), len(filtered_categories))
+        elif self._ticket and self._ticket.datasets:
             authorized_datasets = set(self._ticket.datasets)
             filtered_categories = [
                 cat for cat in all_categories
                 if any(cat.startswith(f"{ds}#") for ds in authorized_datasets)
             ]
-            self.logger.debug("过滤类别: %s -> %s", len(all_categories), len(filtered_categories))
+            self.logger.debug("??????: %s -> %s", len(all_categories), len(filtered_categories))
         else:
             filtered_categories = all_categories
         
@@ -673,17 +683,17 @@ class LiteQuantClient:
         else:
             self._sync_unstack_category(category)
     
-    def _sync_pivot_category(self, category: str, incremental_start_date: datetime = None):
-        """同步 Pivot 类别"""
-        if isinstance(incremental_start_date, str):
-            incremental_start_date = datetime.strptime(incremental_start_date, "%Y-%m-%d")
-
-        meta = self._get_category_meta(category)
-        self.LQ_db.set_category_meta(category, meta, merge=True)
-        partitions = meta.get("partition_keys", [])
-        partition_mode = meta.get("partition_mode", "monthly")
-        if partition_mode not in ("daily", "monthly"):
-            raise ProtocolError()
+    def _sync_pivot_category(self, category: str, incremental_start_date: datetime = None):
+        """同步 Pivot 类别"""
+        if isinstance(incremental_start_date, str):
+            incremental_start_date = datetime.strptime(incremental_start_date, "%Y-%m-%d")
+
+        meta = self._get_category_meta(category)
+        self.LQ_db.set_category_meta(category, meta, merge=True)
+        partitions = meta.get("partition_keys", [])
+        partition_mode = meta.get("partition_mode", "monthly")
+        if partition_mode not in ("daily", "monthly"):
+            raise ProtocolError()
         
         if not partitions:
             self.logger.info(f"{category}: 没有分区")
@@ -712,53 +722,53 @@ class LiteQuantClient:
             if remote_hash:
                 self._write_local_hash(category, partition, remote_hash)
     
-    def _sync_unstack_category(self, category: str):
-        """同步 Unstack 类别（unstack类型通常不分区，直接全量同步）"""
-        partition = "full"
-        category_meta = self._get_category_meta(category)
-        self.LQ_db.set_category_meta(category, category_meta, merge=True)
-        partition_meta = self._get_partition_meta(category, partition)
-        remote_hash = partition_meta.get("hash")
-        duplicate_keys = (
-            partition_meta.get("duplicate_keys")
-            or category_meta.get("duplicate_keys")
-            or partition_meta.get("key_columns")
-            or partition_meta.get("dedupe_keys")
-            or category_meta.get("key_columns")
-            or category_meta.get("dedupe_keys")
-        )
-        
-        df = self._download_partition(category, partition, partition_meta)
-        if not isinstance(duplicate_keys, (list, tuple, str)):
-            duplicate_keys = None
-        self.LQ_db.update_unstack_category(category=category, sub_df=df, duplicate_keys=duplicate_keys)
+    def _sync_unstack_category(self, category: str):
+        """同步 Unstack 类别（unstack类型通常不分区，直接全量同步）"""
+        partition = "full"
+        category_meta = self._get_category_meta(category)
+        self.LQ_db.set_category_meta(category, category_meta, merge=True)
+        partition_meta = self._get_partition_meta(category, partition)
+        remote_hash = partition_meta.get("hash")
+        duplicate_keys = (
+            partition_meta.get("duplicate_keys")
+            or category_meta.get("duplicate_keys")
+            or partition_meta.get("key_columns")
+            or partition_meta.get("dedupe_keys")
+            or category_meta.get("key_columns")
+            or category_meta.get("dedupe_keys")
+        )
+        
+        df = self._download_partition(category, partition, partition_meta)
+        if not isinstance(duplicate_keys, (list, tuple, str)):
+            duplicate_keys = None
+        self.LQ_db.update_unstack_category(category=category, sub_df=df, duplicate_keys=duplicate_keys)
         
         if remote_hash:
             self._write_local_hash(category, partition, remote_hash)
     
     def _download_partition(self, category: str, partition: str, partition_meta: dict) -> pd.DataFrame:
         """下载分区数据"""
-        data_key = partition_meta.get("data_key")
-        if not data_key:
-            raise MetaError()
+        data_key = partition_meta.get("data_key")
+        if not data_key:
+            raise MetaError()
         
         # 获取数据（带重试）
-        payload = self._redis_get_with_retry(data_key)
-        if payload is None:
-            raise RemoteDataError()
+        payload = self._redis_get_with_retry(data_key)
+        if payload is None:
+            raise RemoteDataError()
         
         # 校验 hash
         remote_hash = partition_meta.get("hash")
         if remote_hash:
-            local_hash = "sha256:" + hashlib.sha256(payload).hexdigest()
-            if local_hash != remote_hash:
-                raise SerializationError()
+            local_hash = "sha256:" + hashlib.sha256(payload).hexdigest()
+            if local_hash != remote_hash:
+                raise SerializationError()
         
         # 解析 Parquet
-        try:
-            return pd.read_parquet(io.BytesIO(payload))
-        except Exception:
-            raise SerializationError() from None
+        try:
+            return pd.read_parquet(io.BytesIO(payload))
+        except Exception:
+            raise SerializationError() from None
     
     def _redis_get_with_retry(self, key: str, max_retries: int = 2) -> bytes:
         """带重试的 Redis GET"""
@@ -766,38 +776,38 @@ class LiteQuantClient:
             try:
                 self._ensure_connection()
                 return self._redis_client.get(key)
-            except redis.AuthenticationError:
-                if attempt < max_retries:
-                    self._fetch_ticket()
-                    self._connect_redis()
-                else:
-                    raise DataConnectionError()
-            except Exception as e:
-                if isinstance(e, LiteQuantError):
-                    raise self._public_error_clone(e) from None
-                if attempt < max_retries:
-                    time.sleep(0.5)
-                else:
-                    raise RemoteDataError() from None
+            except redis.AuthenticationError:
+                if attempt < max_retries:
+                    self._fetch_ticket()
+                    self._connect_redis()
+                else:
+                    raise DataConnectionError()
+            except Exception as e:
+                if isinstance(e, LiteQuantError):
+                    raise self._public_error_clone(e) from None
+                if attempt < max_retries:
+                    time.sleep(0.5)
+                else:
+                    raise RemoteDataError() from None
     
     def _json_get(self, key: str):
         """获取 JSON 数据"""
         data = self._redis_get_with_retry(key)
         if data is None:
             return None
-        try:
-            if isinstance(data, bytes):
-                data = data.decode("utf-8")
-            return json.loads(data)
-        except Exception:
-            raise SerializationError() from None
+        try:
+            if isinstance(data, bytes):
+                data = data.decode("utf-8")
+            return json.loads(data)
+        except Exception:
+            raise SerializationError() from None
     
     def _json_get_required(self, key: str):
         """获取必需的 JSON 数据"""
-        obj = self._json_get(key)
-        if obj is None:
-            raise MetaError()
-        return obj
+        obj = self._json_get(key)
+        if obj is None:
+            raise MetaError()
+        return obj
     
     def _get_category_meta(self, category: str) -> dict:
         """获取类别元数据"""
@@ -814,19 +824,19 @@ class LiteQuantClient:
         return meta
     
     def _validate_protocol(self, meta: dict):
-        """验证协议版本"""
-        if meta.get("protocol_version") != self.PROTOCOL_VERSION:
-            raise ProtocolError()
-        if meta.get("data_format") != self.DATA_FORMAT:
-            raise ProtocolError()
+        """验证协议版本"""
+        if meta.get("protocol_version") != self.PROTOCOL_VERSION:
+            raise ProtocolError()
+        if meta.get("data_format") != self.DATA_FORMAT:
+            raise ProtocolError()
     
     def _validate_category_name(self, category: str) -> str:
         """验证类别名称"""
-        if "pivot#" in category:
-            return "pivot"
-        if "unstack#" in category:
-            return "unstack"
-        raise InvalidCategoryError()
+        if "pivot#" in category:
+            return "pivot"
+        if "unstack#" in category:
+            return "unstack"
+        raise InvalidCategoryError()
     
     def _get_hash_path(self, category: str, partition: str) -> str:
         """获取 hash 文件路径"""

{litequant-3.0.0 → litequant-3.0.2}/PKG-INFO

@@ -1,12 +1,12 @@
 Metadata-Version: 2.2
 Name: litequant
-Version: 3.0.0
+Version: 3.0.2
 Summary: LiteQuant Python client SDK
 Author: LiteQuant Team
 License: MIT
-Project-URL: Homepage, https://litequant.com
-Project-URL: Documentation, https://litequant.com/docs
-Project-URL: Issues, https://litequant.com/support
+Project-URL: Homepage, https://litequant.pro
+Project-URL: Documentation, https://litequant.pro/docs
+Project-URL: Issues, https://litequant.pro/support
 Keywords: quant,finance,data,parquet,pandas
 Classifier: Development Status :: 4 - Beta
 Classifier: Intended Audience :: Developers

{litequant-3.0.0 → litequant-3.0.2}/__init__.py

@@ -26,7 +26,7 @@ from .exceptions import (
     APIError,
 )
 
-__version__ = "3.0.0"
+__version__ = "3.0.2"
 __all__ = [
     # Client
     "LiteQuantClient",

{litequant-3.0.0 → litequant-3.0.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "litequant"
-version = "3.0.0"
+version = "3.0.2"
 description = "LiteQuant Python client SDK"
 readme = "README.md"
 license = {text = "MIT"}
@@ -51,9 +51,9 @@ dev = [
 ]
 
 [project.urls]
-Homepage = "https://litequant.com"
-Documentation = "https://litequant.com/docs"
-Issues = "https://litequant.com/support"
+Homepage = "https://litequant.pro"
+Documentation = "https://litequant.pro/docs"
+Issues = "https://litequant.pro/support"
 
 [tool.setuptools]
 packages = ["litequant"]