Metadata-Version: 2.4
Name: enecoq-data-fetcher
Version: 1.0.0
Summary: enecoQ power data fetcher - Fetch power usage, cost, and CO2 emission data from enecoQ web service
Project-URL: Homepage, https://github.com/rewse/enecoq-data-fetcher
Project-URL: Repository, https://github.com/rewse/enecoq-data-fetcher
Project-URL: Issues, https://github.com/rewse/enecoq-data-fetcher/issues
Author: Shibata, Tats
License: MIT
License-File: LICENSE
Keywords: cli,cyberhome,data,enecoq,energy,fetcher,power
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: End Users/Desktop
Classifier: Intended Audience :: System Administrators
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
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: Programming Language :: Python :: 3.14
Classifier: Topic :: Home Automation
Classifier: Topic :: Utilities
Requires-Python: >=3.9
Requires-Dist: click>=8.1.0
Requires-Dist: playwright>=1.40.0
Description-Content-Type: text/markdown

# enecoQ Data Fetcher

enecoQ Web Service から電力使用量、電力使用料金、CO2排出量を取得するCLIツールです。

## 概要

enecoQは株式会社ファミリーネットジャパンが提供するCYBERHOMEサービス内の電力データ管理Webサービスです。このツールは、enecoQから電力データをプログラマティックに取得し、JSON形式やコンソール表示で出力します。

## 主な機能

- 電力使用量データの取得
- 電力使用料金データの取得
- CO2排出量データの取得
- 今日または今月のデータ取得
- JSON形式またはコンソール表示での出力

## 必要要件

- CYBERHOME（enecoQ）のアカウント
- Python 3.9以上
- uv（Pythonパッケージマネージャー）
- Playwright（ブラウザ自動化）

## インストール

### 1. uvのインストール（初回のみ）

uvがインストールされていない場合は、以下のコマンドでインストールしてください：

```bash
# macOS/Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# Windows (PowerShell)
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

# または Homebrew (macOS/Linux)
brew install uv
```

### 2. パッケージのインストール（初回のみ）

```bash
# リポジトリをクローン
git clone <repository-url>
cd enecoq-data-fetcher

# 仮想環境の作成と依存関係のインストール
uv sync

# Playwrightブラウザのインストール
uv run playwright install
```
## 使用方法

### 基本的な使い方

```bash
uv run enecoq-fetch --email your@email.com --password yourpassword
```

### コマンドライン引数

| 引数 | 説明 | デフォルト値 | 必須 |
|------|------|--------------|------|
| `--email` | CYBERHOME (enecoQ) のメールアドレス | - | ✓ |
| `--password` | CYBERHOME (enecoQ) のパスワード | - | ✓ |
| `--period` | データ取得期間（`today` または `month`） | `month` | |
| `--format` | 出力形式（`json` または `console`） | `json` | |
| `--output` | JSON出力先ファイルパス | - | |
| `--log-level` | ログレベル（`DEBUG`, `INFO`, `WARNING`, `ERROR`） | `INFO` | |

### 使用例

#### 今月のデータをJSON形式で取得

```bash
uv run enecoq-fetch --email your@email.com --password yourpassword --period month --format json
```

#### 今日のデータをコンソールに表示

```bash
uv run enecoq-fetch --email your@email.com --password yourpassword --period today --format console
```

#### JSON出力をファイルに保存

```bash
uv run enecoq-fetch --email your@email.com --password yourpassword --output data/power_data.json
```

#### デバッグモードで実行

```bash
uv run enecoq-fetch --email your@email.com --password yourpassword --log-level DEBUG
```

## 出力形式

### JSON形式

```json
{
  "period": "month",
  "timestamp": "2024-01-15T10:30:00.123456",
  "usage": 250.5,
  "cost": 7515.0,
  "co2": 125.25
}
```

注: JSON出力では単位情報は含まれません。単位は以下の通りです：
- `usage`: kWh（キロワット時）
- `cost`: JPY（日本円）
- `co2`: kg（キログラム）

### コンソール形式

```
==============================
enecoQ Data
==============================

Period: month
Timestamp: 2024-01-15 10:30:00

Power Usage: 250.5 kWh
Power Cost: 7515.0 JPY
CO2 Emission: 125.25 kg

==============================
```

## ログ

ログは以下の場所に出力されます：

- **コンソール**: INFOレベル以上
- **ファイル**: `logs/enecoq.log`（DEBUGレベル以上）

ログファイルには認証情報は記録されません。

## 高度な設定（オプション）

`config.yaml` ファイルを作成することで、デフォルト設定をカスタマイズできます：

```yaml
log_level: INFO
log_file: logs/enecoq.log
timeout: 30
max_retries: 3
user_agent: "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36"
```

設定ファイルを使用する場合：

```bash
uv run enecoq-fetch --email your@email.com --password yourpassword --config config.yaml
```

## 他システムとの連携例

### cronでの定期実行

毎時42分にデータを取得してファイルに保存する例（負荷分散のため0〜60秒のランダム待機）：

```bash
# crontabを編集
crontab -e

# 以下を追加（プロジェクトディレクトリのパスを指定）
42 * * * * cd /path/to/enecoq-data-fetcher && sleep $((RANDOM \% 60)) && /path/to/uv run enecoq-fetch --email your@email.com --password yourpassword --output /path/to/enecoq_data.json
```

注: 負荷分散のため、42を別の数字（59以下の任意の値）に変更することを推奨します。多くのユーザーが同じ時刻にアクセスするとサーバーに負荷がかかるため、0以外のランダムな時刻を選択してください。

### Home Assistantとの連携

cronで定期的に保存したJSONファイルを読み込む方法：

```yaml
# configuration.yaml
command_line:
  - sensor:
      name: "enecoQ Power Usage"
      command: "cat /config/data/enecoq_data.json"
      value_template: "{{ value_json.usage }}"
      unit_of_measurement: "kWh"
      device_class: energy
      state_class: total_increasing
      icon: mdi:lightning-bolt
      scan_interval: 300  # 5分ごとに更新
  - sensor:
      name: "enecoQ Power Cost"
      command: "cat /config/data/enecoq_data.json"
      value_template: "{{ value_json.cost }}"
      unit_of_measurement: "JPY"
      device_class: monetary
      state_class: total_increasing
      icon: mdi:cash
      scan_interval: 300
  - sensor:
      name: "enecoQ CO2 Emission"
      command: "cat /config/data/enecoq_data.json"
      value_template: "{{ value_json.co2 }}"
      unit_of_measurement: "kg"
      state_class: total_increasing
      icon: mdi:molecule-co2
      scan_interval: 300
```

注: cronがデータを取得して `/config/data/` に保存し、複数のセンサーがそのファイルを読むことで、スクレイピングの回数を1回で済ませます。

#### Utility Meter で差分を取得

このツールが返す値は累計値です。差分が必要な場合は、Utility Meter を使用してください。

累計値から時間ごとの使用量を計算する例：

```yaml
# configuration.yaml
utility_meter:
  enecoq_power_usage_hourly:
    source: sensor.enecoq_power_usage
    cycle: hourly
  enecoq_power_cost_hourly:
    source: sensor.enecoq_power_cost
    cycle: hourly
  enecoq_co2_emission_hourly:
    source: sensor.enecoq_co2_emission
    cycle: hourly
```

これにより、以下のセンサーが作成されます：
- `sensor.enecoq_power_usage_hourly`: 1時間あたりの電力使用量（kWh）
- `sensor.enecoq_power_cost_hourly`: 1時間あたりの電力使用料金（JPY）
- `sensor.enecoq_co2_emission_hourly`: 1時間あたりのCO2排出量（kg）

同様の方法で ``--period month`` で取得したデータから日次センサーを作ることもできます。

累計値から日付ごとの使用量を計算する例：

```yaml
# configuration.yaml
utility_meter:
  enecoq_power_usage_daily:
    source: sensor.enecoq_power_usage
    cycle: daily
  enecoq_power_cost_daily:
    source: sensor.enecoq_power_cost
    cycle: daily
  enecoq_co2_emission_daily:
    source: sensor.enecoq_co2_emission
    cycle: daily
```

これにより、以下のセンサーが作成されます：
- `sensor.enecoq_power_usage_daily`: 1日あたりの電力使用量（kWh）
- `sensor.enecoq_power_cost_daily`: 1日あたりの電力使用料金（JPY）
- `sensor.enecoq_co2_emission_daily`: 1日あたりのCO2排出量（kg）

## 開発

### テストの実行

#### 全テストの実行

```bash
# テストスクリプトを使用（推奨）
./tests/run_tests.sh
```

#### 個別テストの実行

```bash
# PYTHONPATHを設定して実行
PYTHONPATH=src uv run python tests/test_exporter.py
```

詳細なテスト情報は [tests/README.md](tests/README.md) を参照してください。

### パッケージのビルド

```bash
uv build
```

## トラブルシューティング

### 認証エラーが発生する

- メールアドレスとパスワードが正しいか確認してください
- enecoQ Web Service にブラウザから直接ログインできるか確認してください

### データが取得できない

- `--log-level DEBUG` オプションを使用して詳細なログを確認してください
- enecoQ Web Service が利用可能か確認してください
