Metadata-Version: 2.4
Name: tickerlab
Version: 0.1.0
Summary: Python client for the TickerLab financial market data API
Author-email: TickerLab Team <contact@tickerlab.org>
License-Expression: MIT
Project-URL: Homepage, https://tickerlab.org
Project-URL: Documentation, https://tickerlab.org/en/docs
Project-URL: Bug Tracker, https://gitea.stonyground.com/ndiy/tickerlab/issues
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
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: Programming Language :: Python :: 3.13
Classifier: Operating System :: OS Independent
Classifier: Topic :: Office/Business :: Financial :: Investment
Classifier: Intended Audience :: Financial and Insurance Industry
Classifier: Intended Audience :: Developers
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
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"
Dynamic: license-file

# TickerLab Python SDK

Python client library for the [TickerLab](https://tickerlab.org) financial market data API.

## Installation

```bash
pip install tickerlab
```

To enable automatic Pandas DataFrame conversion for time-series and tabular data:

```bash
pip install "tickerlab[pandas]"
```

## Quick Start

```python
import tickerlab as tl

# Set API authentication token
tl.set_token("YOUR_API_KEY")

# Fetch daily historical K-line data
df = tl.get_kline("000001.SZ", period="1d", start="2026-01-01", adjust="qfq")
print(df.tail())

# Fetch real-time market quote snapshot
snapshot = tl.get_snapshot("600519.SH")
print(snapshot)

# Fetch technical indicators (MACD, RSI, KDJ, BOLL, MA, EMA)
macd = tl.get_indicators("000001.SZ", indicator="macd")
print(macd.tail())
```

## Authentication

Authentication can be configured programmatically or via environment variable:

```bash
export TICKERLAB_API_KEY="YOUR_API_KEY"
```

```python
import tickerlab as tl

# When TICKERLAB_API_KEY is present in environment, manual set_token is optional
df = tl.get_kline("000001.SZ")
```

## Method Reference

| Method | Description | Return Type |
|---|---|---|
| `get_kline(symbol, period='1d', start=None, end=None, adjust='qfq')` | Historical OHLCV market bars | `DataFrame` / `dict` |
| `get_snapshot(symbol)` | Real-time market quote snapshot | `dict` / `DataFrame` |
| `get_daily_basic(symbol, start=None, end=None)` | Valuation metrics (PE, PB, turnover, market cap) | `DataFrame` |
| `get_indicators(symbol, indicator='macd', period='1d')` | Calculated technical indicators | `DataFrame` |
| `get_trade_calendar(start=None, end=None)` | Market trading days and settlement schedule | `DataFrame` |
| `get_stock_list()` | Master instrument list and metadata | `DataFrame` |
| `search_stocks(query)` | Symbol and name search | `DataFrame` |
| `get_macro(indicator='cpi')` | Macroeconomic indicator series | `DataFrame` |
| `get_financial_ratios(symbol)` | Financial statement ratios | `DataFrame` |
| `query(endpoint, params={})` | Low-level generic API request | `dict` / `list` |

## License

MIT License. See [LICENSE](LICENSE) for details.
