ondotori-client 0.4.0

Ondotori WebStorage API client for Python

ondotori-client

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

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

インストール

pip install ondotori-client

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

pip install "ondotori-client[dataframe]"

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

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

Quickstart

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 も維持しています．

from ondotori_client.client import OndotoriClient, parse_current, parse_data

設定ファイル

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

cp configs/config.example.json configs/config.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 を取得する

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 として直接指定する場合は，親機設定も必要です．

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

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

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)

温湿度モデルを取得する

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

DataFrame を取得する

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

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

日時の扱い

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

from zoneinfo import ZoneInfo

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

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

例外処理

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)

設定の保存

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

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

テスト

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

pytest -m "not integration"

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

ONDOTORI_RUN_INTEGRATION=1 pytest -m integration

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

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

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

開発時の確認

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

License

MIT © Hiroki Tsusaka