Metadata-Version: 2.4
Name: tickerlab
Version: 1.0.0
Summary: Official Python SDK for TickerLab Quantitative Financial Market Data Platform
Author-email: TickerLab Team <contact@tickerlab.org>
Project-URL: Homepage, https://tickerlab.org
Project-URL: Documentation, https://tickerlab.org/zh/docs
Project-URL: Bug Tracker, https://github.com/tickerlab/tickerlab-python/issues
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Topic :: Office/Business :: Financial :: Investment
Requires-Python: >=3.8
Description-Content-Type: text/markdown
Provides-Extra: pandas
Requires-Dist: pandas>=1.3.0; extra == "pandas"
Provides-Extra: full
Requires-Dist: pandas>=1.3.0; extra == "full"
Requires-Dist: requests>=2.25.0; extra == "full"

# TickerLab Python SDK

Official Python Client for the [TickerLab](https://tickerlab.org) Quantitative Financial Market Data Platform.

---

## ⚡ 快速安装 (Installation)

```bash
pip install tickerlab
# 或安装带有 Pandas 支持的完整版：
pip install "tickerlab[pandas]"
```

---

## 🚀 3 行代码快速上手 (Quickstart)

```python
import tickerlab as tl

# 1. 设置您的 API Key (可在控制台 https://tickerlab.org/dashboard 生成)
tl.set_token("mc_live_your_api_key")

# 2. 获取股票日线行情 (自动返回 Pandas DataFrame)
df = tl.get_kline("000001.SZ", period="1d", start="2026-01-01", adjust="qfq")
print(df.tail())

# 3. 获取实时行情快照
snapshot = tl.get_snapshot("600519.SH")
print(snapshot)

# 4. 获取技术指标 (MACD / RSI / KDJ / BOLL / MA)
macd_df = tl.get_indicators("000001.SZ", indicator="macd")
print(macd_df.tail())
```

---

## 📚 常用 API 清单

| 方法 | 说明 | 返回类型 |
|---|---|---|
| `tl.get_kline(symbol, period='1d', start=None, end=None, adjust='qfq')` | 获取历史 K 线时间序列 | `pd.DataFrame` |
| `tl.get_snapshot(symbol)` | 实时市场行情快照 | `dict` / `DataFrame` |
| `tl.get_daily_basic(symbol, start=None, end=None)` | 每日基本面与估值指标 (PE, PB, 换手率, 市值) | `pd.DataFrame` |
| `tl.get_indicators(symbol, indicator='macd', period='1d')` | 计算技术指标 (MACD, RSI, KDJ 等) | `pd.DataFrame` |
| `tl.get_trade_calendar(start=None, end=None)` | 交易日历与休市安排 (0-credit 免费) | `pd.DataFrame` |
| `tl.search_stocks(query='平安')` | 快速代码/拼音/名称搜索 (0-credit 免费) | `pd.DataFrame` |
| `tl.get_stock_list()` | 全市场股票基础列表 (0-credit 免费) | `pd.DataFrame` |
| `tl.get_macro(indicator='cpi')` | 宏观经济数据 (CPI, PPI, GDP, PMI, LPR 等) | `pd.DataFrame` |
| `tl.get_market_sentiment()` | 市场情绪与多空全景概览 | `dict` |
| `tl.get_financial_ratios(symbol)` | 财务核心比率与财报核心指标 | `pd.DataFrame` |
| `tl.query(endpoint, params={})` | 通用底层接口调用 | `Any` |

---

## 🔑 环境变量支持

除了 `tl.set_token(...)` 外，SDK 会自动检测 `TICKERLAB_API_KEY` 环境变量：

```bash
export TICKERLAB_API_KEY="mc_live_xxxx"
```

```python
import tickerlab as tl

# 无需手动 set_token，自动从环境变量加载
df = tl.get_kline("000001.SZ")
```
