ftshare 1.0.9__tar.gz

ftshare-1.0.9/.github/workflows/ci.yml

@@ -0,0 +1,25 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.9", "3.10", "3.11", "3.12"]
+    steps:
+      - uses: actions/checkout@v4
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install package and test dependencies
+        run: pip install -e ".[test]"
+      - name: Run tests
+        run: python -m pytest -q

ftshare-1.0.9/.github/workflows/publish.yml

@@ -0,0 +1,43 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  build:
+    name: Build distribution
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Install build tooling
+        run: python -m pip install --upgrade build
+      - name: Build sdist and wheel
+        run: python -m build
+      - name: Upload distribution artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    name: Publish to PyPI
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/ftshare
+    permissions:
+      id-token: write
+    steps:
+      - name: Download distribution artifacts
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

ftshare-1.0.9/.gitignore

@@ -0,0 +1,46 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.egg-info/
+*.egg
+build/
+dist/
+.eggs/
+
+# Virtual environments
+.venv/
+venv/
+env/
+
+# Test / coverage
+.pytest_cache/
+.coverage
+.coverage.*
+htmlcov/
+.tox/
+
+# Type / lint caches
+.mypy_cache/
+.ruff_cache/
+.pyre/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+.DS_Store
+
+# Logs / runtime
+*.log
+
+# Local API documentation checkout used to regenerate SDK metadata
+ftshare-doc/
+
+# Local SDK verification workspace; not shipped with package releases
+sdk_smoke_test/
+
+# Secrets / env
+.env
+.env.local
+*.pem

ftshare-1.0.9/CHANGELOG.md

@@ -0,0 +1,34 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### Fixed
+- 24 paginated endpoints exposed only `page`/`page_size`; they now also accept `limit`, `all_pages`, and `max_pages`.
+- `bse_mapping` endpoint metadata now records its `page`/`page_size` parameters and documented 500-row page cap.
+- Documented per-endpoint `page_size` caps (up to 4000) are now validated client-side.
+- `tdx_board_daily`/`tdx_board_index`/`tdx_board_members` exposed the dead parameters `idx_name`/`idx_type`/`idx_type_code`; they are now `board_name`/`board_type`/`board_type_code`, which the service actually honors. The three endpoints also document their full parameter set and enforce the documented 1000-row page cap.
+- `limit_event_timeline_3s` exposed only `symbol`/`trade_date`; it now records its documented `page`/`page_size` parameters and accepts `limit`, `all_pages`, and `max_pages`, with the documented 200-row page cap.
+- `etf_pcf_infos` referenced the non-existent doc `ETF-PCF信息.md`; corrected to `ETF申赎清单.md`.
+- `ashare_rating_factor_snapshot` referenced the non-existent doc `A股相关性Top-K.md`; corrected to `A股相关性 Top-K.md`.
+- `goodwill_industry` declared `page`/`page_size` although the service ignores both and returns every industry in one response, which made `all_pages=True` re-fetch the same rows forever. The endpoint now exposes only its documented `date` parameter.
+
+## [0.1.1] - 2026-06-29
+
+### Changed
+- Default `base_url` changed from `https://market.ft.tech/data/` to `https://market.ft.tech/gateway/`.
+- Endpoint and API mixin registries are now split by `ftshare-doc/api-doc` topic.
+- SDK coverage updated to 179 market-data endpoints.
+
+## [0.1.0] - 2026-06-23
+
+### Added
+- First public release of the `ftshare` Python SDK.
+- Synchronous client (`ftshare.market_api`) returning pandas `DataFrame` by default.
+- 176 market-data endpoints generated from the API documentation.
+- Field selection (`fields`), pagination (`page`/`page_size`/`limit`/`all_pages`), and `raw`/`as_dataframe` return controls.
+- MIT license and open-source project scaffolding (`.gitignore`, `CHANGELOG.md`, `CONTRIBUTING.md`, `SECURITY.md`, CI workflow).

ftshare-1.0.9/CONTRIBUTING.md

@@ -0,0 +1,40 @@
+# Contributing to ftshare
+
+Thanks for your interest in contributing! This is a short guide to get you started.
+
+## Development setup
+
+Clone the repository and install the package with its test dependencies in editable mode:
+
+```bash
+git clone git@github.com:ftshare-lab/ftshare-python-sdk.git
+cd ftshare-python-sdk
+pip install -e ".[test]"
+```
+
+> Replace the repository URL above with your fork once you have one.
+
+## Running tests
+
+The unit test suite uses mocked HTTP and does not require network access:
+
+```bash
+python3 -m pytest
+```
+
+Real-API integration tests are skipped by default. To run them against a reachable FTShare service:
+
+```bash
+FTSHARE_RUN_INTEGRATION=1 python3 -m pytest tests/test_integration_market.py
+```
+
+## Making changes
+
+1. Open an issue to discuss significant changes before starting work.
+2. Keep the public API surface stable unless an issue calls for a breaking change.
+3. Make sure `python3 -m pytest` passes.
+4. Submit a pull request with a clear description of the change and motivation.
+
+## Reporting issues
+
+Use the issue tracker for bug reports and feature requests. For security-sensitive reports, see [SECURITY.md](SECURITY.md).

ftshare-1.0.9/LICENSE

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

ftshare-1.0.9/PKG-INFO

@@ -0,0 +1,256 @@
+Metadata-Version: 2.5
+Name: ftshare
+Version: 1.0.9
+Summary: Python SDK for FTShare market data APIs.
+Project-URL: Homepage, https://ftai.chat/ftshare
+Project-URL: Documentation, https://market.ft.tech/
+Project-URL: Source, https://github.com/ftshare-lab/ftshare-python-sdk
+Project-URL: Issues, https://github.com/ftshare-lab/ftshare-python-sdk/issues
+Project-URL: Changelog, https://github.com/ftshare-lab/ftshare-python-sdk/blob/main/CHANGELOG.md
+Author-email: FTShare <liulei@ft.tech>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: finance,ftshare,market-data,sdk
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Financial and Insurance Industry
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+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: Typing :: Typed
+Requires-Python: >=3.9
+Requires-Dist: pandas>=1.5
+Requires-Dist: requests>=2.31.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Provides-Extra: test
+Requires-Dist: pytest>=7.0; extra == 'test'
+Description-Content-Type: text/markdown
+
+<p align="center">
+  <img src="./docs/assets/readme/hero.svg" width="100%" alt="FTShare Python SDK，用 Python 和 pandas 接入金融数据">
+</p>
+
+<p align="center">
+  <a href="https://github.com/FTShare-Lab/FTShare-python-sdk/releases/tag/v1.0.1"><img src="https://img.shields.io/badge/release-v1.0.1-3563E9" alt="FTShare Python SDK v1.0.1"></a>
+  <a href="https://www.python.org/downloads/"><img src="https://img.shields.io/badge/python-3.9%2B-111827" alt="Python 3.9 or later"></a>
+  <a href="https://github.com/FTShare-Lab/FTShare-python-sdk/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-MIT-667085" alt="MIT License"></a>
+</p>
+
+<p align="center">
+  <strong>让金融数据成为 AI 的可靠上下文。</strong><br>
+  FTShare 面向 AI Agent、量化研究和金融应用提供统一、可验证、可扩展的金融数据服务。
+</p>
+
+<p align="center">
+  <a href="https://ftai.chat/ftshare"><strong>FTShare 官网</strong></a>
+  · <a href="https://ftai.chat/me/profile">获取 API Key</a>
+  · <a href="https://market.ft.tech/gateway/doc">数据接口文档</a>
+  · <a href="https://github.com/FTShare-Lab/FTShare-python-sdk/issues">问题反馈</a>
+</p>
+
+> [!IMPORTANT]
+> 使用托管数据服务前，请先登录 FTShare 获取 API Key，并通过环境变量 `FTSHARE_API_KEY` 或 `market_api(api_key=...)` 配置鉴权。
+
+## 先看它能做什么
+
+`FTShare-python-sdk` 是 FTShare 的 Python 数据接入层。它将基础金融数据和 FTShare 特色因子统一成 Python 调用方式，默认返回 pandas `DataFrame`，可以直接进入分析、研究和应用开发流程。
+
+<p align="center">
+  <a href="https://ftai.chat/ftshare"><img src="./docs/assets/readme/ftshare-website.png" width="100%" alt="FTShare 官网横幅，展示金融数据服务及 SDK、MCP、Skills 接入入口"></a>
+</p>
+
+<p align="center"><sub>FTShare 官网。点击图片进入产品与套餐页面。</sub></p>
+
+## 三步跑通第一次调用
+
+### 1. 获取 API Key
+
+登录 [FTShare 账号中心](https://ftai.chat/me/profile)，获取当前账号的 API Key。
+
+### 2. 安装 SDK
+
+当前从 GitHub 源码安装：
+
+```bash
+git clone https://github.com/FTShare-Lab/FTShare-python-sdk.git
+cd FTShare-python-sdk
+pip install -e .
+```
+
+### 3. 查询数据
+
+```bash
+export FTSHARE_API_KEY="your_api_key"
+```
+
+```python
+import ftshare as ft
+
+market = ft.market_api()
+
+df = market.ashare_news_sentiment_factors(
+    trade_code="600519.SH",
+    start_date="20260801",
+    end_date="20260831",
+    limit=5,
+)
+
+print(df.head())
+```
+
+> [!NOTE]
+> `ashare_news_sentiment_factors` 是 FTShare 的 A 股新闻情绪因子接口。它返回研究数据，不构成股票推荐或未来收益判断；具体字段和数据范围以当前接口文档与账号权限为准。
+
+## 选择适合你的 FTShare 接入方式
+
+| 接入方式 | 适合场景 | 返回或调用形态 | 仓库 |
+|---|---|---|---|
+| **Python SDK** | Python 程序、数据分析、量化研究 | pandas `DataFrame`、Python rows、原始 JSON | 当前仓库 |
+| **MCP** | 支持 MCP 的 AI 客户端与 Agent | 标准 MCP 工具、结构化结果 | [FTShare-MCP](https://github.com/FTShare-Lab/FTShare-MCP) |
+| **Skill** | Claude Code、Codex、OpenClaw 等 Agent 运行时 | 自然语言到数据接口的路由 | [FTShare-skill](https://github.com/FTShare-Lab/FTShare-skill) |
+
+三种方式连接同一套 FTShare 金融数据服务。SDK 适合稳定编程，MCP 适合标准 Agent 工具调用，Skill 适合由 Agent 理解问题并选择数据接口。
+
+## 为什么使用 Python SDK
+
+- **DataFrame-first：** 默认返回 pandas `DataFrame`，减少重复的数据转换工作。
+- **统一入口：** 通过 `ft.market_api()` 创建客户端，同时接入基础金融数据与 FTShare 特色因子。
+- **多种返回形态：** 支持 DataFrame、Python 行数据与原始 JSON。
+- **字段与分页：** 支持字段筛选、分页和多页拉取。
+- **明确异常：** 区分 HTTP、JSON 解析和服务端业务错误。
+- **可复用底座：** 可用于研究脚本、数据应用、MCP 工具和 Agent 工作流的数据接入层。
+
+## 常用客户端配置
+
+```python
+import ftshare as ft
+
+# 默认从 FTSHARE_API_KEY 环境变量读取
+market = ft.market_api(timeout=20)
+
+# 也可以显式传入
+market = ft.market_api(api_key="your_api_key", timeout=20)
+```
+
+自定义 Base URL：
+
+```python
+market = ft.market_api(
+    base_url="https://market.ft.tech/gateway/",
+    timeout=20,
+)
+```
+
+## 返回类型
+
+默认返回 DataFrame：
+
+```python
+df = market.ashare_news_sentiment_factors(
+    trade_code="600519.SH",
+    limit=10,
+)
+```
+
+返回 Python 行数据：
+
+```python
+rows = market.ashare_news_sentiment_factors(
+    trade_code="600519.SH",
+    limit=10,
+    as_dataframe=False,
+)
+```
+
+返回服务端完整 JSON：
+
+```python
+payload = market.ashare_news_sentiment_factors(
+    trade_code="600519.SH",
+    limit=10,
+    raw=True,
+)
+```
+
+## 分页与结果控制
+
+```python
+df = market.ashare_news_sentiment_factors(
+    trade_code="600519.SH",
+    page=1,
+    page_size=20,
+)
+```
+
+```python
+df = market.ashare_news_sentiment_factors(
+    trade_code="600519.SH",
+    all_pages=True,
+    max_pages=3,
+)
+```
+
+详细的接口参数、字段与专题说明请查看 [FTShare 数据接口文档](https://market.ft.tech/gateway/doc)。
+
+## 错误处理
+
+```python
+from ftshare import (
+    FtshareAPIError,
+    FtshareDecodeError,
+    FtshareHTTPError,
+)
+```
+
+- `FtshareHTTPError`：HTTP 状态码不是 2xx。
+- `FtshareDecodeError`：响应不是合法 JSON。
+- `FtshareAPIError`：服务端返回业务错误。
+
+## 开发与测试
+
+```bash
+git clone https://github.com/FTShare-Lab/FTShare-python-sdk.git
+cd FTShare-python-sdk
+pip install -e ".[test]"
+python3 -m pytest
+```
+
+真实接口集成测试默认跳过：
+
+```bash
+FTSHARE_RUN_INTEGRATION=1 python3 -m pytest tests/test_integration_market.py
+```
+
+## 开源代码与数据服务边界
+
+本仓库代码采用 MIT License。开源许可证覆盖本仓库代码，不自动包含 FTShare 托管数据服务的访问额度、数据授权、再分发权或商业数据使用权；相关范围以产品页面和服务条款为准。
+
+## 社区与反馈
+
+- 使用问题与功能建议：[GitHub Issues](https://github.com/FTShare-Lab/FTShare-python-sdk/issues)
+- 正式产品与套餐：[FTShare](https://ftai.chat/ftshare)
+- API Key 管理：[账号中心](https://ftai.chat/me/profile)
+- MCP 接入：[FTShare-MCP](https://github.com/FTShare-Lab/FTShare-MCP)
+- Agent Skill：[FTShare-skill](https://github.com/FTShare-Lab/FTShare-skill)
+
+### 加入 FTShare 社区交流群
+
+欢迎加入 FTShare 社区交流群，讨论 Python SDK、特色因子、金融数据接口、MCP、Skill 和 Agent 使用。
+
+<p align="center">
+  <img src="./docs/assets/wechat-group-20260929.png" width="320" alt="FTShare 微信社区交流群二维码，有效期至 2026 年 9 月 29 日">
+</p>
+
+> 群内用于交流使用经验和补充问题信息；Bug、功能需求和接口问题建议优先通过 GitHub Issues 提交，便于公开跟踪和沉淀。
+
+**二维码有效期至 2026 年 9 月 29 日。** 如二维码失效，请在 Issues 中留言。
+
+---
+
+<p align="center">
+  <strong>FTShare</strong> · 让金融数据成为 AI 的可靠上下文
+</p>

ftshare-1.0.9/README.md

@@ -0,0 +1,224 @@
+<p align="center">
+  <img src="./docs/assets/readme/hero.svg" width="100%" alt="FTShare Python SDK，用 Python 和 pandas 接入金融数据">
+</p>
+
+<p align="center">
+  <a href="https://github.com/FTShare-Lab/FTShare-python-sdk/releases/tag/v1.0.1"><img src="https://img.shields.io/badge/release-v1.0.1-3563E9" alt="FTShare Python SDK v1.0.1"></a>
+  <a href="https://www.python.org/downloads/"><img src="https://img.shields.io/badge/python-3.9%2B-111827" alt="Python 3.9 or later"></a>
+  <a href="https://github.com/FTShare-Lab/FTShare-python-sdk/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-MIT-667085" alt="MIT License"></a>
+</p>
+
+<p align="center">
+  <strong>让金融数据成为 AI 的可靠上下文。</strong><br>
+  FTShare 面向 AI Agent、量化研究和金融应用提供统一、可验证、可扩展的金融数据服务。
+</p>
+
+<p align="center">
+  <a href="https://ftai.chat/ftshare"><strong>FTShare 官网</strong></a>
+  · <a href="https://ftai.chat/me/profile">获取 API Key</a>
+  · <a href="https://market.ft.tech/gateway/doc">数据接口文档</a>
+  · <a href="https://github.com/FTShare-Lab/FTShare-python-sdk/issues">问题反馈</a>
+</p>
+
+> [!IMPORTANT]
+> 使用托管数据服务前，请先登录 FTShare 获取 API Key，并通过环境变量 `FTSHARE_API_KEY` 或 `market_api(api_key=...)` 配置鉴权。
+
+## 先看它能做什么
+
+`FTShare-python-sdk` 是 FTShare 的 Python 数据接入层。它将基础金融数据和 FTShare 特色因子统一成 Python 调用方式，默认返回 pandas `DataFrame`，可以直接进入分析、研究和应用开发流程。
+
+<p align="center">
+  <a href="https://ftai.chat/ftshare"><img src="./docs/assets/readme/ftshare-website.png" width="100%" alt="FTShare 官网横幅，展示金融数据服务及 SDK、MCP、Skills 接入入口"></a>
+</p>
+
+<p align="center"><sub>FTShare 官网。点击图片进入产品与套餐页面。</sub></p>
+
+## 三步跑通第一次调用
+
+### 1. 获取 API Key
+
+登录 [FTShare 账号中心](https://ftai.chat/me/profile)，获取当前账号的 API Key。
+
+### 2. 安装 SDK
+
+当前从 GitHub 源码安装：
+
+```bash
+git clone https://github.com/FTShare-Lab/FTShare-python-sdk.git
+cd FTShare-python-sdk
+pip install -e .
+```
+
+### 3. 查询数据
+
+```bash
+export FTSHARE_API_KEY="your_api_key"
+```
+
+```python
+import ftshare as ft
+
+market = ft.market_api()
+
+df = market.ashare_news_sentiment_factors(
+    trade_code="600519.SH",
+    start_date="20260801",
+    end_date="20260831",
+    limit=5,
+)
+
+print(df.head())
+```
+
+> [!NOTE]
+> `ashare_news_sentiment_factors` 是 FTShare 的 A 股新闻情绪因子接口。它返回研究数据，不构成股票推荐或未来收益判断；具体字段和数据范围以当前接口文档与账号权限为准。
+
+## 选择适合你的 FTShare 接入方式
+
+| 接入方式 | 适合场景 | 返回或调用形态 | 仓库 |
+|---|---|---|---|
+| **Python SDK** | Python 程序、数据分析、量化研究 | pandas `DataFrame`、Python rows、原始 JSON | 当前仓库 |
+| **MCP** | 支持 MCP 的 AI 客户端与 Agent | 标准 MCP 工具、结构化结果 | [FTShare-MCP](https://github.com/FTShare-Lab/FTShare-MCP) |
+| **Skill** | Claude Code、Codex、OpenClaw 等 Agent 运行时 | 自然语言到数据接口的路由 | [FTShare-skill](https://github.com/FTShare-Lab/FTShare-skill) |
+
+三种方式连接同一套 FTShare 金融数据服务。SDK 适合稳定编程，MCP 适合标准 Agent 工具调用，Skill 适合由 Agent 理解问题并选择数据接口。
+
+## 为什么使用 Python SDK
+
+- **DataFrame-first：** 默认返回 pandas `DataFrame`，减少重复的数据转换工作。
+- **统一入口：** 通过 `ft.market_api()` 创建客户端，同时接入基础金融数据与 FTShare 特色因子。
+- **多种返回形态：** 支持 DataFrame、Python 行数据与原始 JSON。
+- **字段与分页：** 支持字段筛选、分页和多页拉取。
+- **明确异常：** 区分 HTTP、JSON 解析和服务端业务错误。
+- **可复用底座：** 可用于研究脚本、数据应用、MCP 工具和 Agent 工作流的数据接入层。
+
+## 常用客户端配置
+
+```python
+import ftshare as ft
+
+# 默认从 FTSHARE_API_KEY 环境变量读取
+market = ft.market_api(timeout=20)
+
+# 也可以显式传入
+market = ft.market_api(api_key="your_api_key", timeout=20)
+```
+
+自定义 Base URL：
+
+```python
+market = ft.market_api(
+    base_url="https://market.ft.tech/gateway/",
+    timeout=20,
+)
+```
+
+## 返回类型
+
+默认返回 DataFrame：
+
+```python
+df = market.ashare_news_sentiment_factors(
+    trade_code="600519.SH",
+    limit=10,
+)
+```
+
+返回 Python 行数据：
+
+```python
+rows = market.ashare_news_sentiment_factors(
+    trade_code="600519.SH",
+    limit=10,
+    as_dataframe=False,
+)
+```
+
+返回服务端完整 JSON：
+
+```python
+payload = market.ashare_news_sentiment_factors(
+    trade_code="600519.SH",
+    limit=10,
+    raw=True,
+)
+```
+
+## 分页与结果控制
+
+```python
+df = market.ashare_news_sentiment_factors(
+    trade_code="600519.SH",
+    page=1,
+    page_size=20,
+)
+```
+
+```python
+df = market.ashare_news_sentiment_factors(
+    trade_code="600519.SH",
+    all_pages=True,
+    max_pages=3,
+)
+```
+
+详细的接口参数、字段与专题说明请查看 [FTShare 数据接口文档](https://market.ft.tech/gateway/doc)。
+
+## 错误处理
+
+```python
+from ftshare import (
+    FtshareAPIError,
+    FtshareDecodeError,
+    FtshareHTTPError,
+)
+```
+
+- `FtshareHTTPError`：HTTP 状态码不是 2xx。
+- `FtshareDecodeError`：响应不是合法 JSON。
+- `FtshareAPIError`：服务端返回业务错误。
+
+## 开发与测试
+
+```bash
+git clone https://github.com/FTShare-Lab/FTShare-python-sdk.git
+cd FTShare-python-sdk
+pip install -e ".[test]"
+python3 -m pytest
+```
+
+真实接口集成测试默认跳过：
+
+```bash
+FTSHARE_RUN_INTEGRATION=1 python3 -m pytest tests/test_integration_market.py
+```
+
+## 开源代码与数据服务边界
+
+本仓库代码采用 MIT License。开源许可证覆盖本仓库代码，不自动包含 FTShare 托管数据服务的访问额度、数据授权、再分发权或商业数据使用权；相关范围以产品页面和服务条款为准。
+
+## 社区与反馈
+
+- 使用问题与功能建议：[GitHub Issues](https://github.com/FTShare-Lab/FTShare-python-sdk/issues)
+- 正式产品与套餐：[FTShare](https://ftai.chat/ftshare)
+- API Key 管理：[账号中心](https://ftai.chat/me/profile)
+- MCP 接入：[FTShare-MCP](https://github.com/FTShare-Lab/FTShare-MCP)
+- Agent Skill：[FTShare-skill](https://github.com/FTShare-Lab/FTShare-skill)
+
+### 加入 FTShare 社区交流群
+
+欢迎加入 FTShare 社区交流群，讨论 Python SDK、特色因子、金融数据接口、MCP、Skill 和 Agent 使用。
+
+<p align="center">
+  <img src="./docs/assets/wechat-group-20260929.png" width="320" alt="FTShare 微信社区交流群二维码，有效期至 2026 年 9 月 29 日">
+</p>
+
+> 群内用于交流使用经验和补充问题信息；Bug、功能需求和接口问题建议优先通过 GitHub Issues 提交，便于公开跟踪和沉淀。
+
+**二维码有效期至 2026 年 9 月 29 日。** 如二维码失效，请在 Issues 中留言。
+
+---
+
+<p align="center">
+  <strong>FTShare</strong> · 让金融数据成为 AI 的可靠上下文
+</p>