litequant 3.0.0__py3-none-any.whl

litequant/__init__.py

@@ -0,0 +1,54 @@
+# -*- coding: utf-8 -*-
+
+# LiteQuant Client SDK
+from .LiteQuantClient import DataTicket, LiteQuantClient
+
+from .ParquetManager import ParquetDataManager
+from .exceptions import (
+    LiteQuantError,
+    AuthError,
+    HostSelectionError,
+    RemoteDataError,
+    SerializationError,
+    LocalStorageError,
+    CategoryError,
+    CategoryNotFoundError,
+    InvalidCategoryError,
+    MetaError,
+    ProtocolError,
+    TicketExpiredError,
+    QuotaExceededError,
+    PermissionDeniedError,
+    NetworkError,
+    DataConnectionError,
+    ServiceUnavailableError,
+    SyncError,
+    APIError,
+)
+
+__version__ = "3.0.0"
+__all__ = [
+    # Client
+    "LiteQuantClient",
+    "DataTicket",
+    "ParquetDataManager",
+    "LiteQuantError",
+    "AuthError",
+    "HostSelectionError",
+    "RemoteDataError",
+    "SerializationError",
+    "LocalStorageError",
+    "CategoryError",
+    "CategoryNotFoundError",
+    "InvalidCategoryError",
+    "MetaError",
+    "ProtocolError",
+    "TicketExpiredError",
+    "QuotaExceededError",
+    "PermissionDeniedError",
+    "NetworkError",
+    "DataConnectionError",
+    "ServiceUnavailableError",
+    "SyncError",
+    "APIError",
+]

litequant/exceptions.py

@@ -0,0 +1,168 @@
+# -*- coding: utf-8 -*-
+
+
+class LiteQuantError(Exception):
+    """Base SDK error with a public, privacy-safe message."""
+
+    code = "SERVICE_UNAVAILABLE"
+    user_message = "服务暂时不可用，请稍后重试"
+    retryable = False
+
+    def __init__(self, message=None, *, code=None, user_message=None, retryable=None, detail=None):
+        # Keep the public exception object privacy-safe. Internal implementation
+        # errors must not be attached here because users may print or inspect it.
+        self.detail = None
+        self.code = code or self.code
+        self.user_message = user_message or self.user_message
+        self.retryable = self.retryable if retryable is None else retryable
+        super().__init__(self.user_message)
+
+    def __str__(self):
+        return self.user_message
+
+    def __repr__(self):
+        return f"{self.__class__.__name__}(code={self.code!r}, user_message={self.user_message!r})"
+
+
+class AuthError(LiteQuantError):
+    """Authentication failed."""
+
+    code = "AUTH_INVALID"
+    user_message = "API 凭证无效或已过期，请检查后重试"
+    retryable = False
+
+
+class HostSelectionError(LiteQuantError):
+    """Host selection failed."""
+
+    code = "SERVICE_UNAVAILABLE"
+    user_message = "服务暂时不可用，请稍后重试"
+    retryable = True
+
+
+class NetworkError(LiteQuantError):
+    """Network request failed."""
+
+    code = "CONNECTION_INTERRUPTED"
+    user_message = "连接中断，请检查网络后重试"
+    retryable = True
+
+
+class DataConnectionError(LiteQuantError):
+    """Data connection failed."""
+
+    code = "CONNECTION_INTERRUPTED"
+    user_message = "连接中断，请重新初始化客户端"
+    retryable = True
+
+
+class RemoteDataError(LiteQuantError):
+    """Remote data read failed."""
+
+    code = "DATA_UNAVAILABLE"
+    user_message = "数据暂时不可用，请稍后重试"
+    retryable = True
+
+
+class SerializationError(LiteQuantError):
+    """Serialization or validation failed."""
+
+    code = "DATA_VERIFY_FAILED"
+    user_message = "数据校验失败，请重新同步"
+    retryable = True
+
+
+class LocalStorageError(LiteQuantError):
+    """Local storage failed."""
+
+    code = "DATA_UNAVAILABLE"
+    user_message = "本地数据保存失败，请检查存储路径"
+    retryable = False
+
+
+class CategoryError(LiteQuantError):
+    """Category related error."""
+
+    code = "DATA_UNAVAILABLE"
+    user_message = "数据类别不可用"
+    retryable = False
+
+
+class CategoryNotFoundError(CategoryError):
+    """Category does not exist."""
+
+    code = "DATA_UNAVAILABLE"
+    user_message = "数据类别不存在或当前账号无权访问"
+    retryable = False
+
+
+class InvalidCategoryError(CategoryError):
+    """Category name is invalid."""
+
+    code = "REQUEST_INVALID"
+    user_message = "数据类别名称无效"
+    retryable = False
+
+
+class MetaError(LiteQuantError):
+    """Metadata error."""
+
+    code = "DATA_UNAVAILABLE"
+    user_message = "数据暂时不可用，请稍后重试"
+    retryable = True
+
+
+class ProtocolError(LiteQuantError):
+    """Protocol mismatch."""
+
+    code = "SERVICE_UNAVAILABLE"
+    user_message = "服务暂时不可用，请升级客户端或稍后重试"
+    retryable = False
+
+
+class TicketExpiredError(LiteQuantError):
+    """Connection credential expired."""
+
+    code = "CONNECTION_INTERRUPTED"
+    user_message = "连接已中断，请重新初始化客户端"
+    retryable = True
+
+
+class QuotaExceededError(LiteQuantError):
+    """Quota or connection limit exceeded."""
+
+    code = "CONNECTION_LIMIT"
+    user_message = "连接数已达上限，请关闭其他连接后重试"
+    retryable = True
+
+
+class PermissionDeniedError(LiteQuantError):
+    """Permission denied."""
+
+    code = "PERMISSION_DENIED"
+    user_message = "权限不足：当前账号没有该数据权限"
+    retryable = False
+
+
+class ServiceUnavailableError(LiteQuantError):
+    """Service unavailable."""
+
+    code = "SERVICE_UNAVAILABLE"
+    user_message = "服务暂时不可用，请稍后重试"
+    retryable = True
+
+
+class SyncError(LiteQuantError):
+    """One or more data sync tasks failed."""
+
+    code = "DATA_UNAVAILABLE"
+    user_message = "部分数据更新失败，请稍后重试"
+    retryable = True
+
+
+class APIError(LiteQuantError):
+    """Generic API call failed."""
+
+    code = "SERVICE_UNAVAILABLE"
+    user_message = "服务暂时不可用，请稍后重试"
+    retryable = True

litequant/log.py

@@ -0,0 +1,24 @@
+# -*- coding: utf-8 -*-
+
+import logging
+import sys
+
+
+def GetLogger(name: str = "litequant", level: int = logging.INFO) -> logging.Logger:
+    logger = logging.getLogger(name)
+
+    if logger.handlers:
+        logger.setLevel(level)
+        return logger
+
+    logger.setLevel(level)
+    logger.propagate = False
+
+    handler = logging.StreamHandler(sys.stdout)
+    formatter = logging.Formatter(
+        fmt="%(asctime)s | %(levelname)s | %(name)s | %(message)s",
+        datefmt="%Y-%m-%d %H:%M:%S",
+    )
+    handler.setFormatter(formatter)
+    logger.addHandler(handler)
+    return logger

litequant-3.0.0.dist-info/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 LiteQuant
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

litequant-3.0.0.dist-info/METADATA

@@ -0,0 +1,139 @@
+Metadata-Version: 2.2
+Name: litequant
+Version: 3.0.0
+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
+Keywords: quant,finance,data,parquet,pandas
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Financial and Insurance Industry
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Office/Business :: Financial
+Classifier: Topic :: Scientific/Engineering
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pandas>=1.3.0
+Requires-Dist: pyarrow>=10.0.0
+Requires-Dist: redis>=4.0.0
+Requires-Dist: requests>=2.25.0
+Requires-Dist: tqdm>=4.60.0
+Provides-Extra: test
+Requires-Dist: pytest<8.4,>=7.0; extra == "test"
+Provides-Extra: release
+Requires-Dist: build>=1.0; extra == "release"
+Requires-Dist: twine>=5.0; extra == "release"
+Provides-Extra: dev
+Requires-Dist: pytest<8.4,>=7.0; extra == "dev"
+Requires-Dist: build>=1.0; extra == "dev"
+Requires-Dist: twine>=5.0; extra == "dev"
+
+# LiteQuant Python SDK
+
+LiteQuant Python SDK 用于在本地下载和读取 LiteQuant 数据。SDK 会自动处理连接、同步、本地 Parquet 缓存和常见错误提示。
+
+支持 Python 3.8 及以上版本。
+
+## Installation
+
+```bash
+pip install litequant
+```
+
+## Quick Start
+
+```python
+from litequant import LiteQuantClient
+
+client = LiteQuantClient(
+    api_token="your_api_token",
+    save_path="./litequant_data",
+)
+
+client.UpdateAllCategory(update_method="incremental")
+df = client.GetCategory("cn_stock_pivot#open")
+print(df.tail())
+
+client.close()
+```
+
+推荐使用上下文管理器自动关闭连接：
+
+```python
+from litequant import LiteQuantClient
+
+with LiteQuantClient(api_token="your_api_token", save_path="./litequant_data") as client:
+    categories = client.ListCategories()
+    df = client.GetCategory(categories[0])
+```
+
+默认 API 地址为 `https://www.litequant.pro`。如需连接测试环境，可以传入 `api_url` 或设置环境变量 `LITEQUANT_API_URL`。
+
+## Error Handling
+
+SDK 默认会在 Python 终端输出功能面错误提示，同时抛出类型化异常。错误信息不会展示后端细节。
+
+```python
+from litequant import LiteQuantClient, LiteQuantError
+
+try:
+    with LiteQuantClient(api_token="your_api_token", save_path="./litequant_data") as client:
+        df = client.GetCategory("cn_stock_pivot#open")
+except LiteQuantError as exc:
+    print(exc.code)
+    print(exc.user_message)
+    print(exc.retryable)
+```
+
+如果你希望完全自己处理错误提示，可以关闭终端输出：
+
+```python
+client = LiteQuantClient(
+    api_token="your_api_token",
+    save_path="./litequant_data",
+    display_errors=False,
+)
+```
+
+常见公开错误码：
+
+- `AUTH_INVALID`：API 凭证无效或已过期
+- `ACCOUNT_UNAVAILABLE`：账号不可用
+- `SUBSCRIPTION_UNAVAILABLE`：套餐不可用或已过期
+- `PERMISSION_DENIED`：权限不足
+- `CONNECTION_LIMIT`：连接数已达上限
+- `CONNECTION_INTERRUPTED`：连接已中断，请重新连接
+- `REQUEST_INVALID`：请求参数无效
+- `SERVICE_UNAVAILABLE`：服务暂时不可用
+- `DATA_UNAVAILABLE`：数据暂时不可用
+- `DATA_VERIFY_FAILED`：数据校验失败
+
+## Data Cache
+
+SDK 会把数据保存为本地 Parquet 缓存。再次读取同一数据类别时，会优先使用本地缓存；如果本地没有该数据类别，SDK 会自动同步。
+
+当前 pivot 数据支持 `monthly` 和 `daily` 两种分区模式。后续可以在服务端元信息和客户端缓存层一起扩展更多分区模式。
+
+## Metadata Contract
+
+数据服务会提供客户端可识别的类别列表、类别元信息和分区元信息。客户端会自动读取这些元信息并完成数据同步。
+
+公开稳定字段包括：
+
+- `partition_mode`：pivot 分区模式，目前支持 `monthly` 和 `daily`
+- `partition_keys`：数据分区标识列表
+- `hash`：数据校验值
+- `key_columns` / `dedupe_keys`：unstack 数据去重键
+
+普通用户通常不需要直接使用这些字段。

litequant-3.0.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+litequant/LiteQuantClient.py,sha256=6rob4I0a8sohfoeG68xwoQnXbUECwmaA-eoE10KtZRc,33397
+litequant/ParquetManager.py,sha256=eYoq-veV8DH7RjZHaTBxHWhAJ-B4UV6dnrGIoSIfRuM,55694
+litequant/__init__.py,sha256=7TkrmgWx97ndsIdz8cvy_rcpoiBmgONzBgRfxY64Ca8,1208
+litequant/exceptions.py,sha256=p93kxzaPvP_vQ_p9XsITxzOwANcLUbRbgyJayPa9T84,4428
+litequant/log.py,sha256=dRE9oXTyyNoGBpU67Suaz4mITzZXtuRpkp188qEeUWQ,612
+litequant-3.0.0.dist-info/LICENSE,sha256=v4ndfeoLXVjQaijygqdq6QPTg9iS3RKofG1EKNRhUZg,1066
+litequant-3.0.0.dist-info/METADATA,sha256=MDirJTDKALBKEol1co6Pqz4teX3BOn7kBEYRwQ-QvHg,4687
+litequant-3.0.0.dist-info/WHEEL,sha256=beeZ86-EfXScwlR_HKu4SllMC9wUEj_8Z_4FJ3egI2w,91
+litequant-3.0.0.dist-info/top_level.txt,sha256=ktSowtaruI9jxc1qPpgwBQjR0UvDgDEf15s92HqCzLw,10
+litequant-3.0.0.dist-info/RECORD,,

litequant-3.0.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (76.1.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

litequant-3.0.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+litequant