quantdb-sdk 0.4.3__tar.gz → 0.4.4__tar.gz

{quantdb_sdk-0.4.3 → quantdb_sdk-0.4.4}/CHANGELOG.md

@@ -3,6 +3,22 @@
 所有 notable 变更都会记录在此文件。格式基于 [Keep a Changelog](https://keepachangelog.com/zh-CN/1.1.0/)，
 版本号遵循 [Semantic Versioning](https://semver.org/lang/zh-CN/)。
 
+## \[0.4.4] - 2026-10-11
+
+### Fixed
+
+- **`get_usage()` / `a_get_usage()` 漏算流量包额度**：旧实现用 `remaining = traffic_limit + credit_limit + purchased_traffic - used_traffic`，**完全没算流量包**，导致持有流量包的用户剩余流量被低估（少报的量正好等于流量包余额），`is_active` 也会在仍有流量包可用时被误判为 `False`。
+
+  修正后的口径与后端下载预扣一致：可用总额度 = 套餐额度（`traffic_limit + credit_limit + purchased_traffic`）+ 流量包总额；可用剩余 = (套餐额度 − 已用) + 流量包剩余。因用量接口返回的 `package_traffic` 是流量包**剩余量**，总额从 `GET /api/v1/subscription/traffic-packages` 台账累加；台账接口不可用时退化为「总额 = 剩余」，保证 `get_usage()` 在旧版服务端上依然可用。
+
+### Added
+
+- **`get_usage()` / `a_get_usage()` 新增额度明细字段**（原有字段全部保留，取值已修正）：
+  - 合计：`total_gb` / `used_gb` / `remaining_gb`
+  - 套餐额度：`plan_total_gb` / `plan_used_gb` / `plan_remaining_gb`
+  - 流量包额度：`package_total_gb` / `package_used_gb` / `package_remaining_gb`
+- **`quantdb usage` CLI** 改为分行展示套餐 / 流量包 / 合计的已用、总额与剩余，不再只显示一个总额。
+
 ## \[0.4.3] - 2026-10-05
 
 ### Changed

{quantdb_sdk-0.4.3/quantdb_sdk.egg-info → quantdb_sdk-0.4.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: quantdb-sdk
-Version: 0.4.3
+Version: 0.4.4
 Summary: QuantDB 量化数据平台官方 Python SDK
 Author: QuantDB Team
 License: MIT

{quantdb_sdk-0.4.3 → quantdb_sdk-0.4.4}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "quantdb-sdk"
-version = "0.4.3"
+version = "0.4.4"
 description = "QuantDB 量化数据平台官方 Python SDK"
 readme = "README.md"
 license = {text = "MIT"}

{quantdb_sdk-0.4.3 → quantdb_sdk-0.4.4}/quantdb_sdk/__init__.py

@@ -5,7 +5,7 @@ try:
     # 注意：此处用 PyPI 包名（连字符）查找版本号，不是模块名（下划线）
     __version__ = version("quantdb-sdk")
 except ImportError:
-    __version__ = "0.4.3"
+    __version__ = "0.4.4"
 
 from . import layout
 from ._utils import scan_local_directory

{quantdb_sdk-0.4.3 → quantdb_sdk-0.4.4}/quantdb_sdk/__main__.py

@@ -135,9 +135,12 @@ def main() -> int:
         if args.command == "usage":
             usage = client.get_usage()
             print(f"账户用量:")
-            print(f"  已用: {usage['used_gb']:.2f} GB")
-            print(f"  限额: {usage['limit_gb']:.1f} GB")
-            print(f"  剩余: {usage['remaining_gb']:.2f} GB")
+            print(f"  套餐:   已用 {usage['plan_used_gb']:.2f} GB / {usage['plan_total_gb']:.2f} GB"
+                  f"（剩余 {usage['plan_remaining_gb']:.2f} GB）")
+            print(f"  流量包: 已用 {usage['package_used_gb']:.2f} GB / {usage['package_total_gb']:.2f} GB"
+                  f"（剩余 {usage['package_remaining_gb']:.2f} GB）")
+            print(f"  合计:   已用 {usage['used_gb']:.2f} GB / {usage['total_gb']:.2f} GB"
+                  f"（剩余 {usage['remaining_gb']:.2f} GB）")
             print(f"  余额: ¥{usage['balance_yuan']:.2f}")
             sub = usage.get("subscription", {})
             print(f"  订阅: {sub.get('status', 'none')}")

{quantdb_sdk-0.4.3 → quantdb_sdk-0.4.4}/quantdb_sdk/async_client.py

@@ -28,7 +28,7 @@ from .errors import (
 )
 
 # 维护提示：每次发版必须与 pyproject.toml 版本号同步
-_USER_AGENT = "QuantDB-Python-SDK/0.4.3"
+_USER_AGENT = "QuantDB-Python-SDK/0.4.4"
 
 
 def _etag_hex(value: Optional[str]) -> Optional[str]:
@@ -287,21 +287,56 @@ class AsyncQuantDBClient:
         return await self._get("/api/v1/auth/me")
 
     async def a_get_usage(self) -> Dict[str, Any]:
+        """获取当前账户流量与订阅使用情况（异步版，字段含义见 ``QuantDBClient.get_usage``）。"""
         data = await self._get("/api/v1/auth/usage")
         used = data.get("used_traffic", 0)
         limit = data.get("traffic_limit", 0)
         credit = data.get("credit_limit", 0)
         purchased = data.get("purchased_traffic", 0)
+        package_remaining = data.get("package_traffic", 0)
         subscription = data.get("subscription", {}) or {}
+
+        plan_total = limit + credit + purchased
+        plan_remaining = max(0, plan_total - used)
+
+        # 流量包总额只能从台账取（用量接口只给剩余量）。台账接口不可用时退化为
+        # 「总额 = 剩余」，保证 a_get_usage 在旧版服务端上依然可用。
+        package_total = package_remaining
+        try:
+            ledger = await self._get("/api/v1/subscription/traffic-packages")
+            active = [
+                p for p in (ledger.get("packages") or [])
+                if str(p.get("status", "")).lower() == "active"
+            ]
+            if active:
+                package_total = sum(int(p.get("quota_bytes") or 0) for p in active)
+        except QuantDBError:
+            pass
+
+        package_used = max(0, package_total - package_remaining)
+        total = plan_total + package_total
+        remaining = plan_remaining + package_remaining
+
         return {
+            # 合计
+            "total_gb": bytes_to_gb(total),
             "used_gb": bytes_to_gb(used),
+            "remaining_gb": bytes_to_gb(remaining),
+            # 套餐额度（月度重置）
+            "plan_total_gb": bytes_to_gb(plan_total),
+            "plan_used_gb": bytes_to_gb(used),
+            "plan_remaining_gb": bytes_to_gb(plan_remaining),
+            # 流量包额度（一年有效、可叠加）
+            "package_total_gb": bytes_to_gb(package_total),
+            "package_used_gb": bytes_to_gb(package_used),
+            "package_remaining_gb": bytes_to_gb(package_remaining),
+            # 兼容旧字段
             "limit_gb": bytes_to_gb(limit),
             "credit_gb": bytes_to_gb(credit),
             "purchased_gb": bytes_to_gb(purchased),
-            "remaining_gb": max(0.0, bytes_to_gb(limit + credit + purchased - used)),
             "balance_yuan": data.get("balance_yuan", 0.0),
             "subscription": subscription,
-            "is_active": subscription.get("status") == "active" and used < limit + credit + purchased,
+            "is_active": subscription.get("status") == "active" and remaining > 0,
         }
 
     async def a_register(self, username: str, email: str, password: str) -> Dict[str, Any]:

{quantdb_sdk-0.4.3 → quantdb_sdk-0.4.4}/quantdb_sdk/client.py

@@ -32,7 +32,7 @@ from .errors import (
 )
 
 # 维护提示：每次发版必须与 pyproject.toml 版本号同步
-_USER_AGENT = "QuantDB-Python-SDK/0.4.3"
+_USER_AGENT = "QuantDB-Python-SDK/0.4.4"
 
 
 def _etag_hex(value: Optional[str]) -> Optional[str]:
@@ -325,22 +325,72 @@ class QuantDBClient:
         return self._get("/api/v1/auth/me")
 
     def get_usage(self) -> Dict[str, Any]:
-        """获取当前账户流量与订阅使用情况。"""
+        """获取当前账户流量与订阅使用情况。
+
+        额度模型（与后端下载预扣逻辑一致）：
+
+        - **套餐额度**（月度重置）：``traffic_limit + credit_limit + purchased_traffic``，
+          下载时优先从该额度池扣减，已用量即 ``used_traffic``；
+        - **流量包额度**（一年有效、可叠加）：台账 ``traffic_packages``。
+          接口返回的 ``package_traffic`` 是流量包**剩余量**，总额需从台账累加。
+
+        因此：可用总额度 = 套餐额度 + 流量包总额；
+        可用剩余 = (套餐额度 - 已用) + 流量包剩余。
+
+        Returns:
+            用量字典，包含合计（``total_gb``/``used_gb``/``remaining_gb``）、
+            套餐额度（``plan_*``）、流量包额度（``package_*``）三组字段，
+            以及兼容旧版的 ``limit_gb``/``credit_gb``/``purchased_gb``。
+        """
         data = self._get("/api/v1/auth/usage")
         used = data.get("used_traffic", 0)
         limit = data.get("traffic_limit", 0)
         credit = data.get("credit_limit", 0)
         purchased = data.get("purchased_traffic", 0)
+        package_remaining = data.get("package_traffic", 0)
         subscription = data.get("subscription", {}) or {}
+
+        plan_total = limit + credit + purchased
+        plan_remaining = max(0, plan_total - used)
+
+        # 流量包总额只能从台账取（用量接口只给剩余量）。台账接口不可用时退化为
+        # 「总额 = 剩余」，保证 get_usage 在旧版服务端上依然可用。
+        package_total = package_remaining
+        try:
+            ledger = self._get("/api/v1/subscription/traffic-packages")
+            active = [
+                p for p in (ledger.get("packages") or [])
+                if str(p.get("status", "")).lower() == "active"
+            ]
+            if active:
+                package_total = sum(int(p.get("quota_bytes") or 0) for p in active)
+        except QuantDBError:
+            pass
+
+        package_used = max(0, package_total - package_remaining)
+        total = plan_total + package_total
+        remaining = plan_remaining + package_remaining
+
         return {
+            # 合计
+            "total_gb": bytes_to_gb(total),
             "used_gb": bytes_to_gb(used),
+            "remaining_gb": bytes_to_gb(remaining),
+            # 套餐额度（月度重置）
+            "plan_total_gb": bytes_to_gb(plan_total),
+            "plan_used_gb": bytes_to_gb(used),
+            "plan_remaining_gb": bytes_to_gb(plan_remaining),
+            # 流量包额度（一年有效、可叠加）
+            "package_total_gb": bytes_to_gb(package_total),
+            "package_used_gb": bytes_to_gb(package_used),
+            "package_remaining_gb": bytes_to_gb(package_remaining),
+            # 兼容旧字段
             "limit_gb": bytes_to_gb(limit),
             "credit_gb": bytes_to_gb(credit),
             "purchased_gb": bytes_to_gb(purchased),
-            "remaining_gb": max(0.0, bytes_to_gb(limit + credit + purchased - used)),
             "balance_yuan": data.get("balance_yuan", 0.0),
             "subscription": subscription,
-            "is_active": subscription.get("status") == "active" and used < limit + credit + purchased,
+            "is_active": subscription.get("status") == "active" and remaining > 0,
         }
 
     def register(self, username: str, email: str, password: str) -> Dict[str, Any]:

{quantdb_sdk-0.4.3 → quantdb_sdk-0.4.4}/quantdb_sdk/examples/demo_01_connect_basics.py

@@ -30,7 +30,12 @@ def main() -> None:
     print("账户:", me.get("username"), "| ID:", me.get("id"))
 
     usage = client.get_usage()
-    print(f"流量: 已用 {usage['used_gb']:.2f} GB / 限额 {usage['limit_gb']:.1f} GB / 剩余 {usage['remaining_gb']:.2f} GB")
+    print(f"套餐: 已用 {usage['plan_used_gb']:.2f} GB / {usage['plan_total_gb']:.2f} GB"
+          f" / 剩余 {usage['plan_remaining_gb']:.2f} GB")
+    print(f"流量包: 已用 {usage['package_used_gb']:.2f} GB / {usage['package_total_gb']:.2f} GB"
+          f" / 剩余 {usage['package_remaining_gb']:.2f} GB")
+    print(f"合计: 已用 {usage['used_gb']:.2f} GB / {usage['total_gb']:.2f} GB"
+          f" / 剩余 {usage['remaining_gb']:.2f} GB")
     print("订阅:", usage.get("subscription", {}).get("status", "none"))
 
     stocks = client.query_stock_list(keyword=args.keyword, limit=5)

{quantdb_sdk-0.4.3 → quantdb_sdk-0.4.4/quantdb_sdk.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: quantdb-sdk
-Version: 0.4.3
+Version: 0.4.4
 Summary: QuantDB 量化数据平台官方 Python SDK
 Author: QuantDB Team
 License: MIT