datasinking 0.2.6__tar.gz → 0.2.8__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: datasinking
-Version: 0.2.6
+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.6 → 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.6 → 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.6 → datasinking-0.2.8}/datasinking/_version.py

@@ -1,11 +1,11 @@
-# -*- coding: utf-8 -*-
-"""版本号的**唯一来源**。
-
-pyproject.toml 用 `dynamic = ["version"]` 从这里读，`client.py` 的 User-Agent 也读它。
-
-为什么单独抽一个文件：之前 pyproject.toml 和 `__init__.py` 各写各的版本号，
-结果 `__version__` 长期停在 0.1.0 没跟上（发 0.2.4 时才发现，User-Agent 里也一直
-写着旧版本）。现在只有这一处需要改。
-"""
-
-__version__ = "0.2.6"
+# -*- coding: utf-8 -*-
+"""版本号的**唯一来源**。
+
+pyproject.toml 用 `dynamic = ["version"]` 从这里读，`client.py` 的 User-Agent 也读它。
+
+为什么单独抽一个文件：之前 pyproject.toml 和 `__init__.py` 各写各的版本号，
+结果 `__version__` 长期停在 0.1.0 没跟上（发 0.2.4 时才发现，User-Agent 里也一直
+写着旧版本）。现在只有这一处需要改。
+"""
+
+__version__ = "0.2.8"

{datasinking-0.2.6 → 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.8/datasinking/mcp_server.py

@@ -0,0 +1,165 @@
+# -*- coding: utf-8 -*-
+"""DataSinking MCP server (Model Context Protocol).
+
+Expose the DataSinking API — full-text financial reports across Asia
+(China, Korea, Japan) as clean Markdown — to AI agents (Claude, Cursor,
+Codex, DeepSeek, Windsurf, …).
+
+Install the MCP extra::
+
+    pip install "datasinking[mcp]"
+
+Then run::
+
+    datasinking-mcp
+
+or add to any MCP client with ``command: datasinking-mcp`` (stdio). Requires
+the environment variable ``DATASINK_API_KEY`` (get a free key at
+https://datasink.ing).
+"""
+
+import os
+from typing import Annotated, Optional
+
+import requests
+from pydantic import Field
+
+from ._version import __version__  # 版本号唯一来源（原来是硬编码，漂到了 0.2.3）
+
+# mcp v1 uses FastMCP; v2 renamed it to MCPServer. Support both.
+try:
+    from mcp.server.fastmcp import FastMCP  # mcp v1
+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", "")
+
+mcp = FastMCP(
+    "DataSinking",
+    title="DataSinking — Full-text Asian Financial Reports",
+    description="Full-text Asian financial reports (China, Korea, Japan, Taiwan) as clean Markdown via API, with chapter-level access for RAG and AI agents.",
+    version=__version__,
+    instructions=(
+        "DataSinking serves full-text financial reports (annual / semi-annual / quarterly) "
+        "from China, Korea, Japan and Taiwan as clean Markdown, ready for LLM reading and RAG. "
+        "Use FMP-style symbols: 600519.SS (Kweichow Moutai), 005930.KS (Samsung Electronics), "
+        "7203.T (Toyota), 2330.TW (TSMC). To save tokens, prefer get_section to pull one chapter "
+        "(e.g. MD&A) instead of get_report for the whole document."
+    ),
+)
+
+
+def _get(path: str, params: Optional[dict] = None) -> dict:
+    """Call the DataSinking API, carrying the API key automatically."""
+    if not API_KEY:
+        raise RuntimeError(
+            "Missing DATASINK_API_KEY environment variable (get a free key at https://datasink.ing)"
+        )
+    p = dict(params or {})
+    p["apikey"] = API_KEY
+    r = requests.get(f"{BASE_URL}{path}", params=p, timeout=90)
+    r.raise_for_status()
+    return r.json()
+
+
+@mcp.tool()
+def list_exchanges() -> list:
+    """List the exchanges DataSinking covers and their report counts.
+
+    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: 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: 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.
+
+    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: Annotated[int, Field(description="Report id, from list_reports items[].id")],
+) -> dict:
+    """Fetch a single report's full text (metadata + Markdown body).
+
+    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: 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).
+
+    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: 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})
+
+
+def main() -> None:
+    """Entry point for the ``datasinking-mcp`` console script."""
+    mcp.run()
+
+
+if __name__ == "__main__":
+    main()

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: datasinking
-Version: 0.2.6
+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.6 → 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.6 → 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"

datasinking-0.2.6/datasinking/mcp_server.py

@@ -1,134 +0,0 @@
-# -*- coding: utf-8 -*-
-"""DataSinking MCP server (Model Context Protocol).
-
-Expose the DataSinking API — full-text financial reports across Asia
-(China, Korea, Japan) as clean Markdown — to AI agents (Claude, Cursor,
-Codex, DeepSeek, Windsurf, …).
-
-Install the MCP extra::
-
-    pip install "datasinking[mcp]"
-
-Then run::
-
-    datasinking-mcp
-
-or add to any MCP client with ``command: datasinking-mcp`` (stdio). Requires
-the environment variable ``DATASINK_API_KEY`` (get a free key at
-https://datasink.ing).
-"""
-
-import os
-from typing import Optional
-
-import requests
-
-# mcp v1 uses FastMCP; v2 renamed it to MCPServer. Support both.
-try:
-    from mcp.server.fastmcp import FastMCP  # mcp v1
-except ImportError:  # pragma: no cover
-    from mcp.server.mcpserver import MCPServer as FastMCP  # mcp v2
-
-BASE_URL = "https://api.datasink.ing"
-API_KEY = os.environ.get("DATASINK_API_KEY", "")
-
-mcp = FastMCP(
-    "DataSinking",
-    title="DataSinking — Full-text Asian Financial Reports",
-    description="Full-text Asian financial reports (China, Korea, Japan) as clean Markdown via API, with chapter-level access for RAG and AI agents.",
-    version="0.2.3",
-    instructions=(
-        "DataSinking serves full-text financial reports (annual / semi-annual / quarterly) "
-        "from China, Korea and Japan as clean Markdown, ready for LLM reading and RAG. "
-        "Use FMP-style symbols: 600519.SS (Kweichow Moutai), 005930.KS (Samsung Electronics), "
-        "7203.T (Toyota). To save tokens, prefer get_section to pull one chapter (e.g. MD&A) "
-        "instead of get_report for the whole document."
-    ),
-)
-
-
-def _get(path: str, params: Optional[dict] = None) -> dict:
-    """Call the DataSinking API, carrying the API key automatically."""
-    if not API_KEY:
-        raise RuntimeError(
-            "Missing DATASINK_API_KEY environment variable (get a free key at https://datasink.ing)"
-        )
-    p = dict(params or {})
-    p["apikey"] = API_KEY
-    r = requests.get(f"{BASE_URL}{path}", params=p, timeout=90)
-    r.raise_for_status()
-    return r.json()
-
-
-@mcp.tool()
-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.
-    """
-    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.
-    """
-    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:
-    """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).
-    """
-    return _get("/documents", {"symbol": symbol, "doc_type": doc_type, "size": size})
-
-
-@mcp.tool()
-def get_report(document_id: int) -> dict:
-    """Fetch a single report's full text (metadata + Markdown body).
-
-    Args:
-        document_id: Report id, from list_reports items[].id
-    """
-    return _get(f"/documents/{document_id}")
-
-
-@mcp.tool()
-def list_sections(document_id: int) -> dict:
-    """List every section heading in a report (feed the headings to get_section).
-
-    Args:
-        document_id: Report id
-    """
-    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"
-    """
-    return _get(f"/documents/{document_id}", {"section": section})
-
-
-def main() -> None:
-    """Entry point for the ``datasinking-mcp`` console script."""
-    mcp.run()
-
-
-if __name__ == "__main__":
-    main()