grass-wrapper 0.4.0

General purpose Python wrapper utilities

grass-wrapper

grass-wrapper は Python 3.10+ で動作する汎用ユーティリティ集です。
時系列 API からのデータ取得／加工、ローカル（DuckDB） および Google BigQuery への高速ロードをシンプルな API で提供します。

---

Features

Module	What you get
grass_wrapper.CoinGlass	REST クライアント生成とエンドポイントラッパー 例: get_fr_ohlc_history() で funding-rate OHLC を取得
grass_wrapper.Bybit	Bybit V5 API クライアント • get_tickers() — 最新ティッカー取得 • get_kline() — 任意足のローソク足取得 • get_positions() / get_orders() — ポジション・注文情報取得
grass_wrapper.BigQuery	軽量ラッパークラス BigQuery • upload_rows() — list[dict] をロード • upload_rows_if_absent() — 一意キー重複チェック付きロード（初回に PARTITION BY / CLUSTER BY を自動設定）
grass_wrapper.DuckDB	ローカル高速ストレージ DuckDBClient • .insert_dataframe() — pandas.DataFrame を保存 • .query() — SQLで即時クエリ（バックテスト・長期保存に最適）

---

Installation

pip install grass-wrapper

開発者向け:

git clone https://github.com/grass-labs/grass-wrapper.git
cd grass-wrapper
pip install -e .[dev]   # includes pytest, ruff, black

---

Quick Start

from grass_wrapper.CoinGlass.client import CoinGlass
from grass_wrapper.BigQuery.client import BigQuery
from grass_wrapper.Bybit.client import Bybit
from grass_wrapper.DuckDB.client import DuckDBClient

# API クライアント
cg = CoinGlass()                               # CG_API_KEY は環境変数から読む
byb = Bybit(api_key="...", api_secret="...")   # Bybit V5 REST

# ストレージ
bq = BigQuery(project_id="my-gcp-project")     # 認証は ADC 前提
duck = DuckDBClient("data/grass.duckdb")       # ローカル DuckDB ファイルに保存

# 例: Bybit ティッカーを取得して DuckDB に保存
tickers = byb.get_tickers(category="linear")
import pandas as pd
df = pd.DataFrame(tickers)
duck.insert_dataframe("bybit_tickers", df)

# 例: DuckDB からクエリ
res = duck.query("SELECT * FROM bybit_tickers ORDER BY updatedTime DESC LIMIT 5")
print(res)

---

Requirements

• Python ≥ 3.10
• requests ≥ 2.32
• google-cloud-bigquery ≥ 3.35
• duckdb ≥ 1.4.0
• CoinGlass API key (CG_API_KEY)
• Bybit API key/secret（V5）

BigQuery は ADC（Application Default Credentials）または Service Account JSON に対応。

---

Contributing

1. Fork & clone this repo
2. pip install -e .[dev]
3. ruff check . && pytest -q
4. Make a PR against main

We ♥ contributions — issues, docs, tests, new features!

---

License

This project is licensed under the MIT License – see the LICENSE file for details.