Metadata-Version: 2.4
Name: seeddata-quant
Version: 1.0.3
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

Public 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"
```

Private deployments 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 configures only the public history gateway:

- history: `https://history.seeddata.cn`
- realtime: not configured until the public realtime service is deployed

Realtime calls fail locally with a configuration error until an address is set explicitly.

For local development or private deployments, configure the gateways in code:

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

You can set only one side if needed:

```python
sd.set_base_url(history="http://127.0.0.1:28637")
sd.set_base_url(realtime="http://127.0.0.1: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.

## License

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