Metadata-Version: 2.4
Name: ondotori-client
Version: 0.4.0
Summary: Ondotori WebStorage API client for Python
Author-email: Hiroki Tsusaka <tsusaka4research@gmail.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/1160-hrk/ondotori-client
Project-URL: Repository, https://github.com/1160-hrk/ondotori-client
Project-URL: Issues, https://github.com/1160-hrk/ondotori-client/issues
Keywords: ondotori,webstorage,temperature,humidity,sensor
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3
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: Typing :: Typed
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests<3.0,>=2.28
Provides-Extra: dataframe
Requires-Dist: pandas<3.0,>=1.5; extra == "dataframe"
Provides-Extra: dev
Requires-Dist: build>=1.2; extra == "dev"
Requires-Dist: mypy>=1.10; extra == "dev"
Requires-Dist: pandas<3.0,>=1.5; extra == "dev"
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: pytest-cov>=5.0; extra == "dev"
Requires-Dist: ruff>=0.6; extra == "dev"
Requires-Dist: types-requests>=2.31; extra == "dev"
Dynamic: license-file

# ondotori-client

[![CI](https://github.com/1160-hrk/ondotori-client/actions/workflows/ci.yml/badge.svg)](https://github.com/1160-hrk/ondotori-client/actions)
[![PyPI version](https://img.shields.io/pypi/v/ondotori-client.svg)](https://pypi.org/project/ondotori-client/)
[![License](https://img.shields.io/github/license/1160-hrk/ondotori-client.svg)](https://github.com/1160-hrk/ondotori-client/blob/main/LICENSE)

Ondotori WebStorage API を Python から利用するためのクライアントライブラリです．通常機器用エンドポイントと RTR500B 系列用エンドポイントの両方を扱えます．

API 応答の生 JSON はそのまま取得できます．`parse_current()`，`parse_data()`，`get_data_frame()` は，`ch1` を温度，`ch2` を湿度として扱う温湿度機器向けの補助機能です．

## インストール

```bash
pip install ondotori-client
```

DataFrame 出力も使用する場合は，次を実行します．

```bash
pip install "ondotori-client[dataframe]"
```

開発用環境では，リポジトリのルートで次を実行します．

```bash
pip install -e ".[dev,dataframe]"
```

## Quickstart

```python
from zoneinfo import ZoneInfo

from ondotori_client import OndotoriClient, parse_current, parse_data


with OndotoriClient.from_file(
    "configs/config.json",
    default_timezone=ZoneInfo("Asia/Tokyo"),
) as client:
    current_raw = client.get_current("room_default")
    timestamp, temperature, humidity = parse_current(
        current_raw,
        tz=ZoneInfo("Asia/Tokyo"),
    )
    print(timestamp, temperature, humidity)

    data_raw = client.get_data(
        "room_default",
        dt_from="2026-06-01T00:00:00+09:00",
        dt_to="2026-06-02T00:00:00+09:00",
    )
    times, temperatures, humidities = parse_data(
        data_raw,
        tz=ZoneInfo("Asia/Tokyo"),
    )

    frame = client.get_data_frame("room_default", hours=1)
    print(frame.tail())
```

パッケージ直下から主要なクラスと関数を import できます．旧形式の次の import も維持しています．

```python
from ondotori_client.client import OndotoriClient, parse_current, parse_data
```

## 設定ファイル

`configs/config.example.json` をコピーし，実際の認証情報を入力して `configs/config.json` を作成します．

```bash
cp configs/config.example.json configs/config.json
```

```json
{
  "api_key": "<YOUR_API_KEY>",
  "login_id": "<YOUR_LOGIN_ID>",
  "login_pass": "<YOUR_LOGIN_PASSWORD>",
  "default_rtr500_base": "base1",
  "bases": {
    "base1": {
      "serial": "<YOUR_BASE_SERIAL>"
    }
  },
  "remote_map": {
    "room_rtr500": {
      "serial": "<YOUR_RTR500_REMOTE_SERIAL>",
      "type": "rtr500",
      "base": "base1"
    },
    "room_default": {
      "serial": "<YOUR_DEFAULT_DEVICE_SERIAL>",
      "type": "default"
    }
  }
}
```

各項目の意味は次のとおりです．

- `api_key`：WebStorage API キー．
- `login_id`，`login_pass`：WebStorage の認証情報．
- `bases`：RTR500B 親機の名前とシリアル番号の対応．
- `default_rtr500_base`：子機側で `base` を省略した場合に使う親機名．
- `remote_map`：任意の機器名と実シリアル番号の対応．
- `remote_map.*.type`：`default` または `rtr500`．
- `remote_map.*.base`：`bases` に定義した親機名．RTR500 の場合のみ指定できます．

`configs/config.json` には API キーとパスワードが入るため，`.gitignore` で Git 管理から除外しています．`configs/config.example.json` には実データを入力しないでください．

## 主な API

### 生 JSON を取得する

```python
current = client.get_current("room_default")
logs = client.get_data("room_default", hours=24)
latest = client.get_latest_data("room_default")
alerts = client.get_alerts("room_rtr500")
```

`remote_map` にない文字列を渡した場合は，その文字列をシリアル番号として扱います．RTR500 として直接指定する場合は，親機設定も必要です．

```python
logs = client.get_data(
    "DIRECT_REMOTE_SERIAL",
    hours=1,
    device_type="rtr500",
)
```

### 型付きレコードを取得する

```python
record = client.get_current_record("room_default")
records = client.get_data_records("room_default", hours=1)

print(record.timestamp)
print(record.require_channel("ch1").numeric_value)
```

### 温湿度モデルを取得する

```python
reading = client.get_current_temperature_humidity("room_default")
print(reading.temperature_c)
print(reading.humidity_percent)
```

### DataFrame を取得する

```python
frame = client.get_data_frame("room_default", hours=1)
```

列は `timestamp`，`temp_C`，`hum_%` です．この機能は `ch1 = 温度`，`ch2 = 湿度` を仮定します．

## 日時の扱い

Unix time は内部でタイムゾーン付き `datetime` に変換します．デフォルトのタイムゾーンは UTC です．日本時間を使う場合は，クライアントまたはパーサーに明示的に指定してください．

```python
from zoneinfo import ZoneInfo

client = OndotoriClient.from_file(
    "configs/config.json",
    default_timezone=ZoneInfo("Asia/Tokyo"),
)
```

タイムゾーンを含まない ISO 8601 文字列を `get_data()` に渡した場合は，`default_timezone` の時刻として解釈します．再現性のため，通常は `+09:00` などを明示することを推奨します．

## 例外処理

```python
from ondotori_client import (
    AuthenticationError,
    ConfigurationError,
    OndotoriError,
    TransportError,
)

try:
    data = client.get_data("room_default", hours=1)
except AuthenticationError:
    print("認証情報を確認してください")
except ConfigurationError:
    print("config.json を確認してください")
except TransportError:
    print("ネットワーク接続を確認してください")
except OndotoriError as error:
    print(error)
```

## 設定の保存

クライアントは設定を自動保存しません．保存する場合だけ明示的に呼び出します．保存ファイルには認証情報が含まれます．

```python
client.save_config("configs/config.json", overwrite=True)
```

## テスト

通常の単体テストでは実 API を呼び出しません．

```bash
pytest -m "not integration"
```

手元の `configs/config.json` を使って実 API を確認する場合は，明示的に integration test を有効にします．

```bash
ONDOTORI_RUN_INTEGRATION=1 pytest -m integration
```

特定の機器を使う場合は，`remote_map` のキーまたはシリアル番号を指定できます．

```bash
ONDOTORI_RUN_INTEGRATION=1 \
ONDOTORI_REMOTE_KEY=room_default \
pytest -m integration
```

CI では integration test を実行しないため，GitHub Actions に実際の認証情報を登録する必要はありません．

## 開発時の確認

```bash
ruff check .
pytest -m "not integration" --cov=ondotori_client
python -m build
```

## License

MIT © Hiroki Tsusaka
