datasinking 0.2.7__tar.gz → 0.2.8__tar.gz

{datasinking-0.2.7 → datasinking-0.2.8}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: datasinking
-Version: 0.2.7
+Version: 0.2.8
 Summary: Python client for DataSinking — full-text Asian financial reports (China, Korea, Japan, Taiwan) as Markdown.
 Author: DataSinking
 License: MIT
@@ -18,6 +18,7 @@ License-File: LICENSE
 Provides-Extra: mcp
 Requires-Dist: mcp>=1.0.0; extra == "mcp"
 Requires-Dist: requests>=2.28; extra == "mcp"
+Requires-Dist: pydantic>=2.0; extra == "mcp"
 Dynamic: license-file
 
 # DataSinking
@@ -111,7 +112,7 @@ coverage, list a company's reports, and extract a figure with correct units.
 
 Every example pulls from the live API and runs as-is.
 
-> `03_download_exchange.py` fetches every report on an exchange (e.g. all of Shenzhen — 150k+ documents). Quotas count **documents, not requests**, and apply over a rolling 31-day window as well as per day: a free key gets 3 req/s and 8,191 documents/day, inside a pool of 131,071/day and 524,287 per 31 days shared by all free users. A whole exchange will therefore take more than a day on a free key — a **paid (yearly)** key (31 req/s, 131,071 documents/day, 524,287 per 31 days) is strongly recommended.
+> `03_download_exchange.py` fetches every report on an exchange (e.g. all of Shenzhen — 150k+ documents). Quotas count **documents, not requests**, over a rolling 7-day window: a free key gets 3 req/s and 8,191 documents per 7 days, inside a pool of 524,287 per 7 days shared by all free users and website visitors. A whole exchange will therefore take well over a week on a free key — a **paid (yearly)** key (31 req/s, 524,287 documents per 7 days) is strongly recommended.
 
 ## Research (`research/`)
 

{datasinking-0.2.7 → datasinking-0.2.8}/README.md

@@ -89,7 +89,7 @@ coverage, list a company's reports, and extract a figure with correct units.
 
 Every example pulls from the live API and runs as-is.
 
-> `03_download_exchange.py` fetches every report on an exchange (e.g. all of Shenzhen — 150k+ documents). Quotas count **documents, not requests**, and apply over a rolling 31-day window as well as per day: a free key gets 3 req/s and 8,191 documents/day, inside a pool of 131,071/day and 524,287 per 31 days shared by all free users. A whole exchange will therefore take more than a day on a free key — a **paid (yearly)** key (31 req/s, 131,071 documents/day, 524,287 per 31 days) is strongly recommended.
+> `03_download_exchange.py` fetches every report on an exchange (e.g. all of Shenzhen — 150k+ documents). Quotas count **documents, not requests**, over a rolling 7-day window: a free key gets 3 req/s and 8,191 documents per 7 days, inside a pool of 524,287 per 7 days shared by all free users and website visitors. A whole exchange will therefore take well over a week on a free key — a **paid (yearly)** key (31 req/s, 524,287 documents per 7 days) is strongly recommended.
 
 ## Research (`research/`)
 

{datasinking-0.2.7 → datasinking-0.2.8}/datasinking/__init__.py

@@ -11,7 +11,7 @@ Usage:
     try:
         ds.get_stock_reports("600519.SS", limit=-1)
     except QuotaExceeded as e:
-        print(e.code, e)   # e.g. quota_month / free_quota_global
+        print(e.code, e)   # e.g. quota_7d / free_quota_key / free_quota_global
 """
 from ._version import __version__
 from .client import DataSinking, QuotaExceeded

{datasinking-0.2.7 → datasinking-0.2.8}/datasinking/_version.py

@@ -8,4 +8,4 @@ pyproject.toml 用 `dynamic = ["version"]` 从这里读，`client.py` 的 User-A
 写着旧版本）。现在只有这一处需要改。
 """
 
-__version__ = "0.2.7"
+__version__ = "0.2.8"

{datasinking-0.2.7 → datasinking-0.2.8}/datasinking/client.py

@@ -24,14 +24,13 @@ class QuotaExceeded(RuntimeError):
     """额度用尽（HTTP 429 + 服务端返回的 `code`）。
 
     和「限流」不是一回事：限流等几秒就好（客户端自己会重试），
-    额度类要等**日/月窗口滚动**才有用 —— 重试没有意义，所以直接抛出来，不再重试。
-
-    常见 code：
-      quota_day          年费 key 当日额度用尽（UTC 次日 00:00 恢复）
-      quota_month        年费 key 最近 31 天额度用尽
-      free_quota_key     免费 key 当日额度用尽
-      free_quota_global  免费共享池 当日额度用尽（所有免费用户合计）
-      free_quota_month   免费共享池 最近 31 天额度用尽（所有免费用户合计）
+    额度类要等**7 天窗口滚动**才有用 —— 重试没有意义，所以直接抛出来，不再重试。
+
+    常见 code（2026-09-21 起配额统一成「每 7 天 rolling」，日/月两层已取消）：
+      quota_7d           年费 key 的 7 天额度用尽（每 7 天 524,287 篇）
+      free_quota_key     免费 key 的 7 天额度用尽（每 7 天 8,191 篇）
+      free_quota_global  免费共享池的 7 天额度用尽
+                         （所有免费 key + 网页访客合计每 7 天 524,287 篇）
     """
 
     def __init__(self, code=None, detail=None):
@@ -81,8 +80,8 @@ class DataSinking:
                     raise  # 401/403/404/400… 直接抛给上层
                 code, detail = _error_info(e)
                 if code:
-                    # 额度类 429：要等日/月窗口滚动，重试没有意义 —— 立刻抛，并带上服务端的原因。
-                    # （以前这里不分青红皂白 sleep(2) 重试，月度额度打满时会空转，
+                    # 额度类 429：要等 7 天窗口滚动，重试没有意义 —— 立刻抛，并带上服务端的原因。
+                    # （以前这里不分青红皂白 sleep(2) 重试，额度打满时会空转，
                     #   最后还抛出一句 "Request failed after retries: None" —— last 变量
                     #   只在网络异常分支被赋值，429 分支根本不赋值。）
                     raise QuotaExceeded(code, detail)

{datasinking-0.2.7 → datasinking-0.2.8}/datasinking/mcp_server.py

@@ -19,9 +19,10 @@ https://datasink.ing).
 """
 
 import os
-from typing import Optional
+from typing import Annotated, Optional
 
 import requests
+from pydantic import Field
 
 from ._version import __version__  # 版本号唯一来源（原来是硬编码，漂到了 0.2.3）
 
@@ -31,6 +32,11 @@ try:
 except ImportError:  # pragma: no cover
     from mcp.server.mcpserver import MCPServer as FastMCP  # mcp v2
 
+# ⚠️ 参数描述必须写成 `Annotated[T, Field(description=...)]`，**不能只靠 docstring 的 Args 段**。
+#    mcp v2（MCPServer）不再解析 docstring 的 Args —— 实测把整段 Args 当散文塞进工具描述，
+#    参数级 description 全是空的（2026-09-22 用真实 stdio 握手验证）。v1 两种都认，所以这样写两边通用。
+
+
 BASE_URL = "https://api.datasink.ing"
 API_KEY = os.environ.get("DATASINK_API_KEY", "")
 
@@ -66,64 +72,87 @@ def _get(path: str, params: Optional[dict] = None) -> dict:
 def list_exchanges() -> list:
     """List the exchanges DataSinking covers and their report counts.
 
-    Returns exchange codes (sse / szse / bj / ksc / koe / knx / jpx) with the number
-    of reports available per exchange. Call this first to discover coverage.
+    Returns exchange codes (sse / szse / bj / ksc / koe / knx / jpx / twse / tpex) with
+    the number of reports available per exchange. Call this first to discover coverage.
+    Sources: A-shares = cninfo.com.cn, Korea = DART, Japan = EDINET, Taiwan = MOPS.
     """
     return _get("/exchanges").get("exchanges", [])
 
 
 @mcp.tool()
-def list_stocks(exchange: str, limit: int = 20) -> dict:
-    """List stocks on an exchange, including the report count per company.
-
-    Args:
-        exchange: Exchange code, e.g. sse / szse / bj / ksc / koe / knx / jpx
-        limit: Return the first N companies (default 20) to keep responses short.
-    """
+def list_stocks(
+    exchange: Annotated[
+        str, Field(description="Exchange code: sse / szse / bj / ksc / koe / knx / jpx / twse / tpex")
+    ],
+    limit: Annotated[
+        int, Field(description="Return only the first N companies (default 20) to keep the response short.")
+    ] = 20,
+) -> dict:
+    """List stocks on an exchange, including the report count per company."""
     data = _get("/stocks", {"exchange": exchange})
     return {"exchange": exchange, "total": data.get("total", 0), "items": data.get("items", [])[:limit]}
 
 
 @mcp.tool()
-def list_reports(symbol: str, doc_type: str = "annual", size: int = 10) -> dict:
+def list_reports(
+    symbol: Annotated[
+        str, Field(description="FMP-style symbol, e.g. 600519.SS / 005930.KS / 7203.T / 2330.TW")
+    ],
+    doc_type: Annotated[
+        str, Field(description="annual / semiannual / q1 / q3")
+    ] = "annual",
+    size: Annotated[int, Field(description="Number of reports to return (default 10).")] = 10,
+) -> dict:
     """List a company's reports — metadata only (id, title, period), no body text.
 
-    Args:
-        symbol: FMP-style symbol, e.g. 600519.SS / 005930.KS / 7203.T
-        doc_type: annual / semiannual / q1 / q3
-        size: Number of reports to return (default 10).
+    Each item carries a ``source`` field naming the official disclosure platform;
+    keep that attribution when you cite it.
     """
     return _get("/documents", {"symbol": symbol, "doc_type": doc_type, "size": size})
 
 
 @mcp.tool()
-def get_report(document_id: int) -> dict:
+def get_report(
+    document_id: Annotated[int, Field(description="Report id, from list_reports items[].id")],
+) -> dict:
     """Fetch a single report's full text (metadata + Markdown body).
 
-    Args:
-        document_id: Report id, from list_reports items[].id
+    The ``source`` field names the official disclosure platform; keep that attribution
+    when you cite it. Expensive in tokens — prefer get_section when you only need one chapter.
     """
     return _get(f"/documents/{document_id}")
 
 
 @mcp.tool()
-def list_sections(document_id: int) -> dict:
+def list_sections(
+    document_id: Annotated[int, Field(description="Report id, from list_reports items[].id")],
+) -> dict:
     """List every section heading in a report (feed the headings to get_section).
 
-    Args:
-        document_id: Report id
+    Call this before get_section to see the exact headings — the headings are in the
+    report's own language.
     """
     return _get(f"/documents/{document_id}/sections")
 
 
 @mcp.tool()
-def get_section(document_id: int, section: str) -> dict:
-    """Fetch only one section of a report by keyword — cheaper than get_report for RAG.
-
-    Args:
-        document_id: Report id
-        section: Heading keyword, e.g. "management discussion" / "MD&A" / "financial statements" / "notes"
-    """
+def get_section(
+    document_id: Annotated[int, Field(description="Report id, from list_reports items[].id")],
+    section: Annotated[
+        str,
+        Field(
+            description=(
+                "Heading keyword, matched as a substring against the report's OWN headings, "
+                "so pass it in the report's language. A-share reports have Chinese headings "
+                "(e.g. 第三节管理层讨论与分析) — use 管理层讨论与分析 / 财务报告 there. "
+                "For English-language filings, \"MD&A\" / \"financial statements\" / \"notes\" work. "
+                "If nothing matches, the API returns 404 with the real headings — retry with one "
+                "of those, or call list_sections first."
+            )
+        ),
+    ],
+) -> dict:
+    """Fetch only one section of a report by keyword — cheaper than get_report for RAG."""
     return _get(f"/documents/{document_id}", {"section": section})
 
 

{datasinking-0.2.7 → datasinking-0.2.8}/datasinking.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: datasinking
-Version: 0.2.7
+Version: 0.2.8
 Summary: Python client for DataSinking — full-text Asian financial reports (China, Korea, Japan, Taiwan) as Markdown.
 Author: DataSinking
 License: MIT
@@ -18,6 +18,7 @@ License-File: LICENSE
 Provides-Extra: mcp
 Requires-Dist: mcp>=1.0.0; extra == "mcp"
 Requires-Dist: requests>=2.28; extra == "mcp"
+Requires-Dist: pydantic>=2.0; extra == "mcp"
 Dynamic: license-file
 
 # DataSinking
@@ -111,7 +112,7 @@ coverage, list a company's reports, and extract a figure with correct units.
 
 Every example pulls from the live API and runs as-is.
 
-> `03_download_exchange.py` fetches every report on an exchange (e.g. all of Shenzhen — 150k+ documents). Quotas count **documents, not requests**, and apply over a rolling 31-day window as well as per day: a free key gets 3 req/s and 8,191 documents/day, inside a pool of 131,071/day and 524,287 per 31 days shared by all free users. A whole exchange will therefore take more than a day on a free key — a **paid (yearly)** key (31 req/s, 131,071 documents/day, 524,287 per 31 days) is strongly recommended.
+> `03_download_exchange.py` fetches every report on an exchange (e.g. all of Shenzhen — 150k+ documents). Quotas count **documents, not requests**, over a rolling 7-day window: a free key gets 3 req/s and 8,191 documents per 7 days, inside a pool of 524,287 per 7 days shared by all free users and website visitors. A whole exchange will therefore take well over a week on a free key — a **paid (yearly)** key (31 req/s, 524,287 documents per 7 days) is strongly recommended.
 
 ## Research (`research/`)
 

{datasinking-0.2.7 → datasinking-0.2.8}/datasinking.egg-info/requires.txt

@@ -2,3 +2,4 @@
 [mcp]
 mcp>=1.0.0
 requests>=2.28
+pydantic>=2.0

{datasinking-0.2.7 → datasinking-0.2.8}/pyproject.toml

@@ -22,7 +22,7 @@ classifiers = [
 dependencies = []
 
 [project.optional-dependencies]
-mcp = ["mcp>=1.0.0", "requests>=2.28"]
+mcp = ["mcp>=1.0.0", "requests>=2.28", "pydantic>=2.0"]
 
 [project.scripts]
 datasinking-mcp = "datasinking.mcp_server:main"