Metadata-Version: 2.4
Name: pyjvlink
Version: 0.8.1
Summary: JRA-VAN Data Lab JV-Link Python client
Project-URL: Homepage, https://github.com/nyoki-mtl/JVLinkServer
Project-URL: Repository, https://github.com/nyoki-mtl/JVLinkServer
Author-email: Hiroki Taniai <charmer.popopo@gmail.com>
License-Expression: MIT
License-File: LICENSE
Keywords: api-client,horse-racing,jra,jra-van,jv-link
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: Microsoft :: Windows :: Windows 10
Classifier: Operating System :: Microsoft :: Windows :: Windows 11
Classifier: Operating System :: POSIX :: Linux
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: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Requires-Dist: httpx>=0.28.1
Requires-Dist: psutil>=7.0.0
Provides-Extra: dev
Requires-Dist: mkdocs-material>=9.5.0; extra == 'dev'
Requires-Dist: mkdocs>=1.6.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.26.0; extra == 'dev'
Requires-Dist: pytest-cov>=4.1.0; extra == 'dev'
Requires-Dist: pytest>=8.3.5; extra == 'dev'
Requires-Dist: ruff>=0.11.11; extra == 'dev'
Requires-Dist: ty>=0.0.19; extra == 'dev'
Provides-Extra: docs
Requires-Dist: mkdocs-material>=9.5.0; extra == 'docs'
Requires-Dist: mkdocs>=1.6.0; extra == 'docs'
Description-Content-Type: text/markdown

# PyJVLink

JRA-VAN Data Lab JV-Link を Python から利用するための非同期クライアントライブラリ。

Windows では `JVLinkServer.exe` の自動起動に対応し、Linux/macOS ではリモート接続モードで利用できます。

[オンラインドキュメント](https://nyoki-mtl.github.io/JVLinkServer/) | [PyPI](https://pypi.org/project/pyjvlink/) | [Releases](https://github.com/nyoki-mtl/JVLinkServer/releases)

## 特徴

- `async/await` ベースの API
- NDJSON ストリーミング対応
- typed query / raw query の両系統
- `RecordEnvelope` で一貫した戻り値
- `Sequence[JVDataSpec | str]` を受け取る柔軟な DataSpec 指定
- realtime race key helper (`RaceKeyParts`, `build_race_key*`)
- SSE イベント監視 (`watch_events`, `stream_events`)

## 前提条件

- Python 3.10 以上
- 接続先の JVLinkServer
  - Windows: ローカル自動起動
  - Linux/macOS: Windows 上の JVLinkServer へ接続

## インストール

```bash
pip install git+https://github.com/nyoki-mtl/JVLinkServer.git#subdirectory=python
```

## クイックスタート

```python
import asyncio
from pyjvlink import Client

async def main() -> None:
    async with Client() as client:
        result = await client.query_stored(
            dataspec=["RACE", "TOKU"],
            from_datetime="20240101",
            option=1,
            record_types=["RA", "TK"],
        )

        print(result.meta)

        async for envelope in result.records:
            print(envelope.type)

if __name__ == "__main__":
    asyncio.run(main())
```

## 主要API

- `Client.query_stored(...) -> StoredResult[DomainRecord]`
- `Client.query_realtime(...) -> RealtimeResult[DomainRecord]`
- `Client.query_stored_raw(...) -> StoredResult[WireRecord]`
- `Client.query_realtime_raw(...) -> RealtimeResult[WireRecord]`
- `Client.watch_events() -> AsyncContextManager[AsyncIterator[JVLinkEvent]]`
- `Client.stream_events() -> AsyncIterator[JVLinkEvent]`
- `Client.delete_file(filename) -> dict`
- `Client.get_uniform(pattern) -> bytes`
- `Client.save_uniform(pattern, filepath) -> dict`
- `Client.get_course(key) -> tuple[bytes, str]`
- `Client.get_course_file(key) -> dict`
- `Client.save_course(key, filepath) -> dict`

`StoredResult` / `RealtimeResult` は次の構造です。

- `meta`: サーバーからのメタ情報
- `records`: `RecordEnvelope` の非同期イテレータ

realtime 系では `key` に文字列だけでなく `date` / `datetime` / `RaceKeyParts` も渡せます。

## API 方針

公開クライアントは `Client` を使用します。

## CLI

```bash
pyjvlink health
pyjvlink version
pyjvlink query-stored RACE 20240101 1 --max-records 10
pyjvlink query-realtime 0B12 --key 202401070511
```

## 開発

```bash
make sync
make check-full
make docs
```
