Metadata-Version: 2.4
Name: seeddata-quant
Version: 1.0.5
Summary: SeedData Python client SDK
Author-email: SeedData <2236158935@qq.com>
License-Expression: LicenseRef-Proprietary
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Financial and Insurance Industry
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
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: Topic :: Office/Business :: Financial
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: httpx>=0.27.0
Requires-Dist: pandas<3.0,>=2.2.0
Requires-Dist: pandas_market_calendars<6.0,>=5.4.0
Requires-Dist: pyarrow>=23.0.0
Requires-Dist: sqlglot>=25.20.0

# SeedData Python SDK

SeedData is a Python client SDK for accessing SeedData market data services.

This package only contains the client SDK. The server-side gateway and worker components are not included in this PyPI distribution.

## Installation

```bash
pip install seeddata-quant
```

## Quick Start

```python
import seeddata as sd

sd.set_token("YOUR_TOKEN")

result = sd.query("SELECT * FROM trade_date LIMIT 5")
print(result.df)
```

## Common APIs

```python
import seeddata as sd

sd.set_token("YOUR_TOKEN")

df = sd.get_klines(
    instruments=["000001.SZ"],
    fields=["close"],
    start_time="2024-01-01",
    end_time="2024-01-31",
    period="1d",
    adjust="none",
    market_type="cn_stock",
)

realtime_1min = sd.query(
    "SELECT * FROM cn_stock_1min_realtime_data "
    "LATEST ON trade_time PARTITION BY ts_code LIMIT 20"
).df
```

## Trading Calendars

`seeddata_calendars` provides trading-calendar helpers. It is pure client-side
(no network calls): it reuses `pandas_market_calendars` for A-share / HK / US
equities and ships a packaged parquet for China futures.

```python
import seeddata_calendars as cal

cal.get_calendar_names()                          # supported MIC names
c = cal.get_calendar("XNYS")                      # NYSE-listed ordinary equities

c.valid_days("2026-06-01", "2026-06-30")          # trading days in range
c.is_valid_day("2026-06-19")                      # False (Juneteenth)
c.date_to_valid_day("2026-06-06", direction="next")  # next trading day
c.valid_days_window("2026-06-02", 5)              # 5 trading days forward

c.schedule("2026-11-27")                          # regular session, 09:30-13:00 ET
c.schedule("2026-11-27", session="extended")      # pre/open/close/post
c.schedule("2026-06-01", session="extended", tz="Asia/Shanghai")
c.early_closes("2026-01-01", "2026-12-31")
c.is_open_at("2026-06-01 22:00:00+08:00", session="regular")
```

Supported MICs: `CCFX GFEX XDCE XHKG XINE XNAS XNYS XSGE XSHE XSHG XZCE CN_FUTURES`.
China futures (`CCFX/XDCE/XZCE/XSGE/XINE/GFEX`) and `CN_FUTURES` (their union)
are backed by packaged data. A-share / HK / US calendars use
`pandas_market_calendars`; `XNYS` and `XNAS` map to its `NYSE` and `NASDAQ`
ordinary-equity rules. Names are ISO 10383 MIC only. Returns default to each
market's local timezone. US calendars additionally provide regular/extended
`schedule()`, `early_closes()`, `late_opens()`, and `is_open_at()`; China-futures
`schedule()` raises `NotImplementedError`.

## Token

Non-local SeedData gateways require a token:

```python
sd.set_token("YOUR_TOKEN")
```

You can also set the token through an environment variable:

```bash
export SEEDDATA_TOKEN="YOUR_TOKEN"
```

A gateway running on your local machine may allow anonymous local access. In
that case the SDK can send requests without `sd.set_token(...)`; the server
decides whether anonymous requests are allowed.

## Base URL

By default, the SDK targets the local gateway of a standard SeedData private
deployment:

- history: `http://127.0.0.1:28637`
- realtime: `http://127.0.0.1:28637`

A single gateway serves both history and realtime endpoints, so with the
SeedData database package installed on the same machine, the SDK works out of
the box. If your gateway runs on another host, point the SDK at it:

```python
sd.set_base_url(
    history="http://192.168.1.10:28637",
    realtime="http://192.168.1.10:28637",
)
```

You can set only one side if needed:

```python
sd.set_base_url(history="http://192.168.1.10:28637")
sd.set_base_url(realtime="http://192.168.1.10:28637")
```

Missing arguments keep their current values. Trailing slashes are removed, and
empty values raise an error. This function only configures request URLs and does
not check network connectivity.

## Server compatibility

This SDK requires a SeedData server of version 0.1.10 or newer. The query API
returns results as an Apache Arrow stream; the staged large-result download mode
of SDK 1.0.4 is no longer supported. Floating-point query results are returned
exactly as stored, without implicit rounding (server 0.1.10 behavior).

## License

This package is proprietary software. Installation and use require authorization from SeedData.
