datasinking 0.1.0__tar.gz

datasinking-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 DataSinking
+
+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.

datasinking-0.1.0/PKG-INFO

@@ -0,0 +1,123 @@
+Metadata-Version: 2.4
+Name: datasinking
+Version: 0.1.0
+Summary: Python client for DataSinking — full-text China A-share financial reports as Markdown.
+Author: DataSinking
+License: MIT
+Project-URL: Homepage, https://datasink.ing
+Project-URL: Documentation, https://datasink.ing/docs
+Project-URL: Repository, https://github.com/heubme2020/datasinking
+Keywords: a-share,china,financial reports,markdown,api,stock
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Office/Business :: Financial
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: requests
+Dynamic: license-file
+
+# DataSinking
+
+**Full-text A-share financial reports, as clean Markdown.**
+
+[DataSinking](https://datasink.ing) is a **China stock market data API** that serves
+**full-text A-share financial reports** — annual, semi-annual and quarterly — as clean
+**Markdown**. Download China A-share financial statements (balance sheet, income statement,
+cash flow) by FMP-style symbol (`600519.SS`) or filter by exchange / report period, through a
+simple REST API. Raw PDFs are sourced from [cninfo.com.cn](http://www.cninfo.com.cn) (the
+officially designated disclosure platform) and parsed into structured Markdown with YAML
+frontmatter, preserved headings, paragraphs and tables — ready for LLM reading and analysis.
+
+---
+
+## What this repo is
+
+Examples, research and tutorials showing how to work with financial report data, including reproducing the presentation styles found in financial-report research papers.
+
+```
+datasinking/
+├── examples/     # Example scripts: pull data from the API and analyze it
+├── research/     # Research notes / blog posts (reproducing paper-style presentation)
+├── datasinking/  # Python client — pip install datasinking
+├── llm-examples.md  # Ask an LLM — no code needed (3 end-to-end examples)
+└── README.md
+```
+
+## Quick start
+
+1. Get an API key at [datasink.ing](https://datasink.ing)
+2. Pull data (FMP-style `?apikey=`):
+
+```bash
+# List exchanges
+curl "https://api.datasink.ing/exchanges?apikey=YOUR_KEY"
+
+# List all of Kweichow Moutai's reports
+curl "https://api.datasink.ing/documents?symbol=600519.SS&apikey=YOUR_KEY"
+```
+
+3. Or use the Python client:
+
+```bash
+pip install datasinking
+```
+
+```python
+from datasinking import DataSinking
+
+ds = DataSinking("YOUR_KEY")
+
+# Latest 3 reports of Kweichow Moutai (full markdown content included)
+for r in ds.get_stock_reports("600519.SS", limit=3):
+    print(r["report_period"], r["title"], len(r["content"]), "chars")
+```
+
+## Ask an LLM (no code)
+
+Don't want to write code? Point any LLM at [datasink.ing](https://datasink.ing),
+give it your API key, and ask in plain language. See
+[`llm-examples.md`](llm-examples.md) for three end-to-end examples — explore
+coverage, list a company's reports, and extract a figure with correct units.
+
+## Examples (`examples/`)
+
+| File | What it does |
+|---|---|
+| `01_quickstart.py` | The 5 core functions: list exchanges / stocks / reports / fetch a report / fetch a stock's reports |
+| `02_download_company.py` | Download a company's full reports to local Markdown files |
+| `03_download_exchange.py` | Download an entire exchange's reports (all stocks) to local Markdown files |
+
+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 — 130k+ documents). Free keys work too, but fall back to slow per-document fetching (1 req/s + shared daily quota); a **paid (yearly)** key is strongly recommended for full-exchange downloads.
+
+## Research (`research/`)
+
+`research/` hosts research notes and blog posts, each based on DataSinking data with the source cited. You can reproduce charts and presentations found in financial-report research papers, e.g.:
+
+- Long-term revenue / profit trends
+- Industry comparison and distribution
+- Time series of financial metrics
+
+Start from [`research/TEMPLATE.md`](research/TEMPLATE.md).
+
+## Data overview
+
+| | |
+|---|---|
+| Coverage | SSE / SZSE / BSE, 5,000+ A-share companies |
+| Document types | annual / semiannual / q1 / q3 / amendment |
+| Format | Full-text Markdown (with YAML frontmatter) |
+| API | REST — `GET /documents`, batch download, `with_content=1` for full text |
+| Symbols | FMP style: `600519.SS` / `000001.SZ` / `830799.BJ` |
+| Auth | `?apikey=` query parameter (FMP style) |
+
+## Data source
+
+All reports originate from [cninfo.com.cn](http://www.cninfo.com.cn), the officially designated information disclosure platform of China's listed companies.
+
+## License
+
+[MIT](LICENSE)

datasinking-0.1.0/README.md

@@ -0,0 +1,103 @@
+# DataSinking
+
+**Full-text A-share financial reports, as clean Markdown.**
+
+[DataSinking](https://datasink.ing) is a **China stock market data API** that serves
+**full-text A-share financial reports** — annual, semi-annual and quarterly — as clean
+**Markdown**. Download China A-share financial statements (balance sheet, income statement,
+cash flow) by FMP-style symbol (`600519.SS`) or filter by exchange / report period, through a
+simple REST API. Raw PDFs are sourced from [cninfo.com.cn](http://www.cninfo.com.cn) (the
+officially designated disclosure platform) and parsed into structured Markdown with YAML
+frontmatter, preserved headings, paragraphs and tables — ready for LLM reading and analysis.
+
+---
+
+## What this repo is
+
+Examples, research and tutorials showing how to work with financial report data, including reproducing the presentation styles found in financial-report research papers.
+
+```
+datasinking/
+├── examples/     # Example scripts: pull data from the API and analyze it
+├── research/     # Research notes / blog posts (reproducing paper-style presentation)
+├── datasinking/  # Python client — pip install datasinking
+├── llm-examples.md  # Ask an LLM — no code needed (3 end-to-end examples)
+└── README.md
+```
+
+## Quick start
+
+1. Get an API key at [datasink.ing](https://datasink.ing)
+2. Pull data (FMP-style `?apikey=`):
+
+```bash
+# List exchanges
+curl "https://api.datasink.ing/exchanges?apikey=YOUR_KEY"
+
+# List all of Kweichow Moutai's reports
+curl "https://api.datasink.ing/documents?symbol=600519.SS&apikey=YOUR_KEY"
+```
+
+3. Or use the Python client:
+
+```bash
+pip install datasinking
+```
+
+```python
+from datasinking import DataSinking
+
+ds = DataSinking("YOUR_KEY")
+
+# Latest 3 reports of Kweichow Moutai (full markdown content included)
+for r in ds.get_stock_reports("600519.SS", limit=3):
+    print(r["report_period"], r["title"], len(r["content"]), "chars")
+```
+
+## Ask an LLM (no code)
+
+Don't want to write code? Point any LLM at [datasink.ing](https://datasink.ing),
+give it your API key, and ask in plain language. See
+[`llm-examples.md`](llm-examples.md) for three end-to-end examples — explore
+coverage, list a company's reports, and extract a figure with correct units.
+
+## Examples (`examples/`)
+
+| File | What it does |
+|---|---|
+| `01_quickstart.py` | The 5 core functions: list exchanges / stocks / reports / fetch a report / fetch a stock's reports |
+| `02_download_company.py` | Download a company's full reports to local Markdown files |
+| `03_download_exchange.py` | Download an entire exchange's reports (all stocks) to local Markdown files |
+
+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 — 130k+ documents). Free keys work too, but fall back to slow per-document fetching (1 req/s + shared daily quota); a **paid (yearly)** key is strongly recommended for full-exchange downloads.
+
+## Research (`research/`)
+
+`research/` hosts research notes and blog posts, each based on DataSinking data with the source cited. You can reproduce charts and presentations found in financial-report research papers, e.g.:
+
+- Long-term revenue / profit trends
+- Industry comparison and distribution
+- Time series of financial metrics
+
+Start from [`research/TEMPLATE.md`](research/TEMPLATE.md).
+
+## Data overview
+
+| | |
+|---|---|
+| Coverage | SSE / SZSE / BSE, 5,000+ A-share companies |
+| Document types | annual / semiannual / q1 / q3 / amendment |
+| Format | Full-text Markdown (with YAML frontmatter) |
+| API | REST — `GET /documents`, batch download, `with_content=1` for full text |
+| Symbols | FMP style: `600519.SS` / `000001.SZ` / `830799.BJ` |
+| Auth | `?apikey=` query parameter (FMP style) |
+
+## Data source
+
+All reports originate from [cninfo.com.cn](http://www.cninfo.com.cn), the officially designated information disclosure platform of China's listed companies.
+
+## License
+
+[MIT](LICENSE)

datasinking-0.1.0/datasinking/__init__.py

@@ -0,0 +1,12 @@
+# -*- coding: utf-8 -*-
+"""DataSinking Python client.
+
+Usage:
+    from datasinking import DataSinking
+    ds = DataSinking("YOUR_API_KEY")
+    ds.list_exchanges()
+"""
+from .client import DataSinking
+
+__version__ = "0.1.0"
+__all__ = ["DataSinking"]

datasinking-0.1.0/datasinking/client.py

@@ -0,0 +1,126 @@
+# -*- coding: utf-8 -*-
+"""DataSinking Python client — 5 个核心函数。
+
+    list_exchanges()                         列交易所
+    list_stocks(exchange)                    列某交易所的股票
+    list_reports(symbol, doc_type=?)         列某股票的报告列表(元数据, 无全文)
+    get_report(doc_id)                       拉指定报告(全文)
+    get_stock_reports(symbol, ..., limit=7)  拉某股票的报告(全文)
+
+返回类型约定: list_* 一律返回 list, get_report 返回单个 dict, get_stock_reports 返回 list。
+"""
+import time
+
+import requests
+
+
+class DataSinking:
+    def __init__(self, api_key, base_url="https://api.datasink.ing"):
+        self.base_url = base_url.rstrip("/")
+        self.api_key = api_key
+        self.session = requests.Session()
+
+    # ---- 内部方法 ----
+    def _get(self, path, params=None, retries=5):
+        params = {**(params or {}), "apikey": self.api_key}
+        for i in range(retries):
+            try:
+                r = self.session.get(f"{self.base_url}{path}", params=params, timeout=60)
+                if r.status_code == 429:  # 限流, 稍等重试
+                    time.sleep(2)
+                    continue
+                r.raise_for_status()
+                return r.json()
+            except (requests.exceptions.SSLError, requests.exceptions.ConnectionError):
+                time.sleep(1 + i)
+        raise RuntimeError("Request failed after multiple retries")
+
+    def _post(self, path, json=None, retries=5):
+        params = {"apikey": self.api_key}
+        for i in range(retries):
+            try:
+                r = self.session.post(f"{self.base_url}{path}", params=params, json=json, timeout=60)
+                if r.status_code == 429:
+                    time.sleep(2)
+                    continue
+                r.raise_for_status()
+                return r.json()
+            except (requests.exceptions.SSLError, requests.exceptions.ConnectionError):
+                time.sleep(1 + i)
+        raise RuntimeError("Request failed after multiple retries")
+
+    def _fetch_all_meta(self, params):
+        """分页拉全 metadata(无 content), 200/页"""
+        items = []
+        page = 1
+        while True:
+            d = self._get("/documents", dict(params, page=page, size=200))
+            items.extend(d["items"])
+            if not d["items"] or len(items) >= d["total"]:
+                break
+            page += 1
+        return items
+
+    def _batch_content(self, ids, batch_size=127):
+        """批量拉全文; free 计划 batch 返回 403 时自动回退逐篇拉取"""
+        items = []
+        batch_ok = True
+        for i in range(0, len(ids), batch_size):
+            chunk = ids[i : i + batch_size]
+            if batch_ok:
+                try:
+                    b = self._post("/documents/batch", {"doc_ids": chunk})
+                    items.extend(b["items"])
+                    continue
+                except requests.exceptions.HTTPError as e:
+                    if e.response is not None and e.response.status_code == 403:
+                        batch_ok = False
+                    else:
+                        raise
+            for did in chunk:
+                items.append(self._get(f"/documents/{did}"))
+        return items
+
+    # ---- 5 个核心函数 ----
+    def list_exchanges(self):
+        """列交易所 -> list[str], 如 ['bj', 'sse', 'szse']"""
+        return self._get("/exchanges")["exchanges"]
+
+    def list_stocks(self, exchange):
+        """列某交易所的股票 -> list[dict] (stock_code / stock_name / report_count)"""
+        return self._get("/stocks", {"exchange": exchange})["items"]
+
+    def list_reports(self, symbol, doc_type=None):
+        """列某股票的报告列表(元数据, 无全文) -> list[dict]
+
+        doc_type: annual / semiannual / q1 / q3 / amendment
+        """
+        params = {"symbol": symbol}
+        if doc_type:
+            params["doc_type"] = doc_type
+        return self._fetch_all_meta(params)
+
+    def get_report(self, doc_id):
+        """拉指定报告(全文) -> dict, 含 content"""
+        return self._get(f"/documents/{doc_id}")
+
+    def get_stock_reports(self, symbol, period_from=None, period_to=None, limit=7, doc_type=None):
+        """拉某股票的报告(全文) -> list[dict]
+
+        period_from / period_to: 按报告期(report_period, YYYY-MM-DD), 不是发布日。
+        limit: 最近 N 篇(按报告期倒序); -1 = 全部(自动分页拉全)。
+        doc_type: annual / semiannual / q1 / q3 / amendment
+        """
+        params = {"symbol": symbol}
+        if period_from:
+            params["report_period_from"] = period_from
+        if period_to:
+            params["report_period_to"] = period_to
+        if doc_type:
+            params["doc_type"] = doc_type
+        if limit == -1:
+            ids = [m["id"] for m in self._fetch_all_meta(params)]
+        else:
+            d = self._get("/documents", dict(params, size=limit, order="desc"))
+            ids = [it["id"] for it in d["items"]]
+        return self._batch_content(ids)

datasinking-0.1.0/datasinking.egg-info/PKG-INFO

@@ -0,0 +1,123 @@
+Metadata-Version: 2.4
+Name: datasinking
+Version: 0.1.0
+Summary: Python client for DataSinking — full-text China A-share financial reports as Markdown.
+Author: DataSinking
+License: MIT
+Project-URL: Homepage, https://datasink.ing
+Project-URL: Documentation, https://datasink.ing/docs
+Project-URL: Repository, https://github.com/heubme2020/datasinking
+Keywords: a-share,china,financial reports,markdown,api,stock
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Office/Business :: Financial
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: requests
+Dynamic: license-file
+
+# DataSinking
+
+**Full-text A-share financial reports, as clean Markdown.**
+
+[DataSinking](https://datasink.ing) is a **China stock market data API** that serves
+**full-text A-share financial reports** — annual, semi-annual and quarterly — as clean
+**Markdown**. Download China A-share financial statements (balance sheet, income statement,
+cash flow) by FMP-style symbol (`600519.SS`) or filter by exchange / report period, through a
+simple REST API. Raw PDFs are sourced from [cninfo.com.cn](http://www.cninfo.com.cn) (the
+officially designated disclosure platform) and parsed into structured Markdown with YAML
+frontmatter, preserved headings, paragraphs and tables — ready for LLM reading and analysis.
+
+---
+
+## What this repo is
+
+Examples, research and tutorials showing how to work with financial report data, including reproducing the presentation styles found in financial-report research papers.
+
+```
+datasinking/
+├── examples/     # Example scripts: pull data from the API and analyze it
+├── research/     # Research notes / blog posts (reproducing paper-style presentation)
+├── datasinking/  # Python client — pip install datasinking
+├── llm-examples.md  # Ask an LLM — no code needed (3 end-to-end examples)
+└── README.md
+```
+
+## Quick start
+
+1. Get an API key at [datasink.ing](https://datasink.ing)
+2. Pull data (FMP-style `?apikey=`):
+
+```bash
+# List exchanges
+curl "https://api.datasink.ing/exchanges?apikey=YOUR_KEY"
+
+# List all of Kweichow Moutai's reports
+curl "https://api.datasink.ing/documents?symbol=600519.SS&apikey=YOUR_KEY"
+```
+
+3. Or use the Python client:
+
+```bash
+pip install datasinking
+```
+
+```python
+from datasinking import DataSinking
+
+ds = DataSinking("YOUR_KEY")
+
+# Latest 3 reports of Kweichow Moutai (full markdown content included)
+for r in ds.get_stock_reports("600519.SS", limit=3):
+    print(r["report_period"], r["title"], len(r["content"]), "chars")
+```
+
+## Ask an LLM (no code)
+
+Don't want to write code? Point any LLM at [datasink.ing](https://datasink.ing),
+give it your API key, and ask in plain language. See
+[`llm-examples.md`](llm-examples.md) for three end-to-end examples — explore
+coverage, list a company's reports, and extract a figure with correct units.
+
+## Examples (`examples/`)
+
+| File | What it does |
+|---|---|
+| `01_quickstart.py` | The 5 core functions: list exchanges / stocks / reports / fetch a report / fetch a stock's reports |
+| `02_download_company.py` | Download a company's full reports to local Markdown files |
+| `03_download_exchange.py` | Download an entire exchange's reports (all stocks) to local Markdown files |
+
+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 — 130k+ documents). Free keys work too, but fall back to slow per-document fetching (1 req/s + shared daily quota); a **paid (yearly)** key is strongly recommended for full-exchange downloads.
+
+## Research (`research/`)
+
+`research/` hosts research notes and blog posts, each based on DataSinking data with the source cited. You can reproduce charts and presentations found in financial-report research papers, e.g.:
+
+- Long-term revenue / profit trends
+- Industry comparison and distribution
+- Time series of financial metrics
+
+Start from [`research/TEMPLATE.md`](research/TEMPLATE.md).
+
+## Data overview
+
+| | |
+|---|---|
+| Coverage | SSE / SZSE / BSE, 5,000+ A-share companies |
+| Document types | annual / semiannual / q1 / q3 / amendment |
+| Format | Full-text Markdown (with YAML frontmatter) |
+| API | REST — `GET /documents`, batch download, `with_content=1` for full text |
+| Symbols | FMP style: `600519.SS` / `000001.SZ` / `830799.BJ` |
+| Auth | `?apikey=` query parameter (FMP style) |
+
+## Data source
+
+All reports originate from [cninfo.com.cn](http://www.cninfo.com.cn), the officially designated information disclosure platform of China's listed companies.
+
+## License
+
+[MIT](LICENSE)

datasinking-0.1.0/datasinking.egg-info/SOURCES.txt

@@ -0,0 +1,10 @@
+LICENSE
+README.md
+pyproject.toml
+datasinking/__init__.py
+datasinking/client.py
+datasinking.egg-info/PKG-INFO
+datasinking.egg-info/SOURCES.txt
+datasinking.egg-info/dependency_links.txt
+datasinking.egg-info/requires.txt
+datasinking.egg-info/top_level.txt

datasinking-0.1.0/datasinking.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

datasinking-0.1.0/datasinking.egg-info/requires.txt

@@ -0,0 +1 @@
+requests

datasinking-0.1.0/datasinking.egg-info/top_level.txt

@@ -0,0 +1 @@
+datasinking

datasinking-0.1.0/pyproject.toml

@@ -0,0 +1,28 @@
+[build-system]
+requires = ["setuptools>=61.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "datasinking"
+version = "0.1.0"
+description = "Python client for DataSinking — full-text China A-share financial reports as Markdown."
+readme = "README.md"
+requires-python = ">=3.8"
+license = { text = "MIT" }
+authors = [{ name = "DataSinking" }]
+keywords = ["a-share", "china", "financial reports", "markdown", "api", "stock"]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Topic :: Office/Business :: Financial",
+]
+dependencies = ["requests"]
+
+[project.urls]
+Homepage = "https://datasink.ing"
+Documentation = "https://datasink.ing/docs"
+Repository = "https://github.com/heubme2020/datasinking"
+
+[tool.setuptools]
+packages = ["datasinking"]

datasinking-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+