Content
ftshare Python SDKLicense: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[](https://www.python.org/downloads/)
[
`ftshare-python-sdk` is a Python SDK for FTShare financial data capabilities for developers who need to access data such as market data, financial data, macroeconomic data, fund data futures data.
It provides a unified Python calling method that returns pandasFrame` by default, making it convenient for developers to use FTShare data in data analysis, quantitative research, financial application development, MCP tool encapsulation, Skill construction, and Agent research process.
in ftshare Ecosystem
`ftshare-python-sdk` is the data access layer of the ftshare ecosystem. It connects to FTShare data and provides a stable MCP, Skill, and Agent applications upwards.
```text Data Services
↓
ftshare-python-sdk # Python
↓
ftshare-mcp # Agent Callable Tool Layer
↓
ftshare-skills # Research Task and Business Workflow Layer
↓
Agent Applications # Research Analysis Experience for End Users
```
## Installation
Clone the repository and install it in editable mode (including test dependencies):
```bash
git clone git@github.com:ftshare-lab/ftshare-python-sdk.git
cd ftshare-python-sdk
pip install -e ".[test]"
```
`pandas` and `requests` are runtime dependencies and will be installed by default with the SDK.
## Quick Start
```python
import ftshare as ft = ft.market_api()
df = market.baidu_financial_calendar(
="2026-05-26",
end_date="-05-27",
category="economic",
limit)
print(df)
```
is a pandas `Data For example, the financial calendar like:
```text category stat_date region ... star negative positive capitalization economic 202-26 英07:01 ... 1 0
2026-26 新加坡 13:00 ... 1 0
```
## Using in Another Project
Method 1: Install the SDK first.
```bash
pip install -e .
```
Then in any Python project:
```python
import ftshare as ft
market = ft.market_api()
df = market.eastmoney_us_stock_list(limit=5)
print(df)
```
## Client Entrance
Create a client:
```python
as ft
market = ft.market_api(timeout=20)
the request header:
``` = ft.market_apiUser-Agent": "my-appContext management:
```python.market_api(timeout= as market:
dfk_limit(limit=10)
Base URL Configuration
Default value:
```python
import ftshare as ft
print(ft.BASE_URL)
# https://market.ft.tech/data/
```
Global modification, affecting new clients created afterwards:
```python
ft.set_base_url(".ft.tech/data/")
market = ft.market_api()
```
Modify certain client:
```python
market = ft.market_apihttps://market.ft.tech/data/")
```
The SDK will normalize the both `https://host/data` and `host/data/` are acceptable.
## Return Type
Default return pandas `DataFrame`:
```python
df = market.stk_limit(trade_date=20260608, limit=10)
```
Return Python row data:
```python
rows = market.stk_limit(
trade_date=20260608,
limit=10,
as_dataframe=False,
)
```
Return the complete JSON from the server:
```python
payload = market.stk_limit(
trade_date=20260608,
limit=10,
raw=True,
)
```
The SDK will table data from common response- `data.records`
data.items`
- Top-level `items`
- Top-level array the response is not structure, the SDK will preserve and convert it to-row `DataFrame` losing fields.
## Field Screening
`fields` can be list or a comma:
```python
df = market.eastmoney_us_stock_list(
limit=5,
fields=["code", "name", "latest_price", "change_pct```
```python
df = market.eastmoney_us_stock_list(
limit=5,
fields="code,name,latest_price,change_pct",
)
```
Field screening is performed after the SDK extracts the table data.
## Pagination
The paging interface supports both traditional `page/page_size` and more convenient `limit/all_pages`.
Get up to N items:
```python
df = market.baidu_financial_calendar(
start_date="2026-05-26",
end_date="2026-05-27",
category="economic",
limit=300,
)
```
When `limit` is greater than the single-page limit, the SDK will automatically paginate and merge the results.
Automatic paging:
```python
df = market.baidu_financial_calendar(
start_date="2026-05-26",
end_date="2026-05-27",
category="economic",
all_pages=True,
page_size=200,
max_pages=5,
)
```
Precise page number specification:
```python
df = market.baidu_financial_calendar(
start_date="2026-05-26",
end_date="2026-05-27",
page=2,
page_size=50,
)
```
General paging entrance:
```python
df = market.fetch_all(
"baancial_calendar",
start_date="2026-05-26",
end_date="2026-05-27",
="economic",
page_size=200,
)
```
Paging- Most interfaces have a default single-page limit of `200 `stk_limit` and `stk_premarket` have a single-page limit of `500`.
- If `page_size` interface limit, the SDK will directly raise a `ValueError`.
- `limit` represents the maximum number of items to return, allowing it to be greater than the single-page limit, and the SDK will make multiple page requests.
## Common Invocation Examples
Financial calendar:
```python
df = market.baidu_financial_calendar(
start_date="2026-05-26",
end_date="2026-05-27",
category="economic",
limit=20,
)
```
US stock list:
```python
df = market.eastmoney_us_stock_list(
limit=10,
fields=["code", "name", "latest_price", "change_pct"],
A-share limit up and down prices:
```python
dfk_limit(
trade_date=20260608,
100,
fields=["ts_code", "up_limit_limit"],
)
```
Stock intraday ticks:
```python
df = market.stock_intraday(symbol="600000.X```
Stock previous close price:
```python
df = market.stock_prev_close(
symbol="600000.XSHG",
="20240501",
until="20240531",
)
```
## Viewing Available Interfaces
View all SDK methods:
```python
from ftshare.endpointsPOINTS
print(lenPOINTS))
print(sortedPOINTS))
```
View metadata for a specific interface:
```python
from ftshare.endpoints importS
endpointPOINTS["baidu_fin"]
print(endpoint.path)
print(endpoint.params)
print(endpoint.doc_file)
```
The current SDK generates a corresponding Python method for each exposed interface.
## Exception Handling
```python
import ftshare as ft
market = ft.market_api(timeout=20)
try:
df = market.baidu_financial_calendar(
start_date="2026-05-26",
end_date="-05",
limit= )
except ft.FHTTPError as exc print("HTTP error:",_code, exc.url)
.FtshareDecodeError print("JSON:", exc.url)
tshareAPIError:
print("API.code, exc.messageException types:
-HTTPError`: HTTP2xx.
- `DecodeError`: Response is.
- `APIError`: Server-side business status code failure.
## Testing unit tests use mock HTTP and do not depend on online```bash
python3 -m pytest
```
Integration tests are skipped by default. Enable them explicitly when accessing:
```bash
FTSHARE_RUN_INTEGRATION3 -m pytest tests/test_integration_market.py
```
## Project Structure
```/ftshare/
py # Package entrance, exporting market_api, and exception types
base.py # Base request orchestration, session lifecycle, and pagination process
# FtshareClient market_api factory.py # BASE_URL, default pagination size, and dataframe.py # pandas DataFrame conversion
# Interface path registry
exceptions.py exception types
fields.py # fields parameter parsing and pagination.py # page/page_size/limit/max response.py # API business errors,,
Connection Info
You Might Also Like
No recommendations available