Metadata-Version: 2.4
Name: kline-client
Version: 0.1.4
Summary: Realtime A-share quote client for the kline-push WebSocket gateway
Author: WANG MIAO
License: MIT
Keywords: a-share,stocks,realtime,websocket,quotes,klineshare
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Office/Business :: Financial :: Investment
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: websockets>=13

# kline-client

Realtime A-share (China stock market) quote client for the **kline-push**
WebSocket gateway, which redistributes KlineShare whole-market realtime data
(price, 5-level order book, dynamic valuation — 41 fields).

**One object, instant subscription** — instantiating starts a background
receiver with auto-reconnect and automatic full-resync built in:

```python
from kline_client import RealtimeClient

qt = RealtimeClient(symbols=["600519.SS", "000001.SZ"])  # starts receiving

qt.price("600519.SS")      # 1292.3        (float)
qt.pct("600519.SS")        # -0.81         (percent, float)
qt.get("600519.SS")        # full quote dict (41 string fields)
qt["000001.SZ"]            # same, raises KeyError if absent
qt.by_symbol               # {symbol: quote_dict} for the subscription
qt.updated_at / qt.age     # upstream snapshot time / data age in seconds

qt.set_symbols(["300750.SZ"])   # change subscription at runtime
qt.close()                      # stop receiving
```

## Setup

You need an **access token** from the gateway administrator (one per machine).

```
Windows:  set WS_TOKEN=<your token>
Linux:    export WS_TOKEN=<your token>
```

(or put `WS_TOKEN=<your token>` in a `.env` file in your working directory;
`RealtimeClient(token="...")` overrides both.)

The gateway address is pre-configured; override it with the `WS_URL`
environment variable or `RealtimeClient(url="...")` if you run your own
gateway.

## Bandwidth-friendly subscriptions

```python
qt = RealtimeClient(
    symbols=["600519.SS"],                                  # subset of symbols
    fields=["price", "change_percent", "bp1", "bv1", "ap1", "av1"],  # subset of columns
)
```

Frame size scales linearly with symbols x fields; `symbol` is always included.

## Fields

Base (13): `symbol name price open high low pre_close change change_percent
volume turnover timestamp time` — note `change_percent` is a fraction
(-0.0081 = -0.81%).

Order book (20): `bp1~bp5 / bv1~bv5` (bid), `ap1~ap5 / av1~av5` (ask).

Valuation (8): `pe_ttm pe_dynamic pb bps total_market_cap
circulation_market_cap total_shares circulation_shares`.

## Notes

- Python 3.10+; the only dependency is `websockets`.
- Push cadence is ~10-15 seconds per frame (upstream rate-limit driven);
  typical end-to-end data latency is 5-12 seconds.
- Also provides the async engine `QuoteClient` for custom event loops.
