Metadata-Version: 2.4
Name: akshare-one
Version: 0.6.0
Summary: Standardized interface for Chinese financial market data, built on AKShare with unified data formats and simplified APIs
Keywords: akshare,financial-data,stock-data,quant
License-Expression: MIT
Requires-Dist: akshare>=1.18.0
Requires-Dist: pandas>=2.0
Requires-Dist: numpy>=1.24
Requires-Dist: requests>=2.28
Requires-Dist: cachetools>=5.5.0
Requires-Dist: brotli>=1.1.0
Requires-Dist: ta-lib>=0.6.4 ; extra == 'talib'
Requires-Python: >=3.10
Project-URL: Homepage, https://github.com/zwldarren/akshare-one
Project-URL: Repository, https://github.com/zwldarren/akshare-one.git
Provides-Extra: talib
Description-Content-Type: text/markdown

<div align="center">
  <h1>AKShare One</h1>
  <div>
    <a href="README_zh.md">中文</a> | <strong>English</strong>
  </div>
</div>

**AKShare One** is a data interface for obtaining Chinese A-shares, based on [AKShare](https://github.com/akfamily/akshare). It aims to simplify AKShare's usage and unify input/output formats from different data sources, making it easier to pass data to LLM.

## ✨ Features

- 📊 Unified stock code formats across data sources
- 🏗️ Standardized return data structures
- 🛠️ Simplified API parameter design
- ⏱️ Automatic timestamp and adjustment handling

## 🚀 Core Features

| Function | Interface |
|------|------|
| Historical data | `get_hist_data` |
| Real-time quotes | `get_realtime_data` |
| Stock news | `get_news_data` |
| Financial data | `get_balance_sheet`/`get_income_statement`/`get_cash_flow` |
| Futures data | `get_futures_hist_data`/`get_futures_realtime_data` |
| Options data | `get_options_chain`/`get_options_realtime`/`get_options_hist` |
| Internal transactions | `get_inner_trade_data` |
| Basic stock info | `get_basic_info` |
| Financial metrics | `get_financial_metrics` |
| Technical indicators | See [indicators.py](src/akshare_one/indicators.py) |

## 📦 Quick Installation

```bash
pip install akshare-one
```

## 💻 Usage Example

```python
from akshare_one import get_hist_data
from akshare_one.indicators import get_sma

# Get historical data
df = get_hist_data(symbol="600000", interval="day", adjust="hfq")

# Calculate 20-day Simple Moving Average
df_sma = get_sma(df, window=20)
```

## 📚 Documentation

Full API documentation is now available on GitHub Pages:

https://zwldarren.github.io/akshare-one/

## 🧪 Testing

Tests run fully offline by default. Test modules that call live upstream data
providers (EastMoney, Sina, XueQiu, Tonghuashun, the exchanges) are skipped
unless you opt in, because those endpoints apply aggressive rate limits and a
full run can get your IP temporarily blocked:

```bash
pytest                    # offline unit tests only
pytest --run-network      # include live-provider tests
```

## 🧩 Public interface

The public surface is `akshare_one` and `akshare_one.indicators`. Everything
else is internal and may change without a deprecation cycle — that includes
`akshare_one.modules`, and the per-source clients `akshare_one.eastmoney` and
`akshare_one.ths`.

Each domain's output columns are declared in exactly one place,
`akshare_one.modules.<domain>.schema`. Every provider's frame is projected onto
those columns, so a documented column is always present — `NaN` when the
selected source cannot supply it — and always in the documented order.

## ⚠️ Data source notes

- Realtime quotes and basic info fall back across several EastMoney hosts,
  because `push2.eastmoney.com` intermittently returns `502` (notably from
  outside mainland China).
- `xueqiu` realtime quotes need an `xq_a_token` cookie that XueQiu no longer
  hands to anonymous clients, and XueQiu returns `418` once rate-limited.
- `ths` talks to Tonghuashun's public HTTP endpoints, which need no login. It
  serves one security per request, so realtime quotes need a `symbol`; its
  daily history is long but arrives one year per request, and its intraday
  series keeps only a short window. Realtime quotes carry the upstream quote
  time, and the SSE Composite is addressed as `1A0001` (`sh000001` is mapped
  to it).
- `get_options_chain` returns the option contract list with the market-data
  columns left empty; use `get_options_realtime` / `get_options_hist` for
  prices.
- `get_futures_main_contracts()` reflects static exchange snapshots and may be
  slow on the first call (CFFEX); the result is cached for 24 hours.
