開発者向けガイド

開発者向けガイド#

このセクションは、haniwers プロジェクトに貢献したい「開発者（Developer）」向けのドキュメントです。

開発環境のセットアップから、コードの理解、テストの実行、そして貢献の方法まで、開発に必要な情報を提供します。

このセクションの目標

コードを理解して、測定ツールを改善し、プロジェクトに貢献できるようになる

コンテンツ#

開発環境の構築手順#

基本セットアップ#

git clone https://gitlab.com/qumasan/haniwers
cd haniwers
poetry install --with docs,dev

開発用依存関係の確認#

poetry show --tree
poetry run haniwers version --env

開発・テスト方法#

Sandboxディレクトリでの開発・テスト#

sandbox/ディレクトリは、開発・テスト用の隔離された環境として機能します。実際のデータやハードウェアなしでコマンドテストを実行できます。

Sandboxの役割:

  • 設定ファイルのテスト環境

  • モックデバイスでの動作確認

  • CLI コマンドの検証

  • 新機能の動作確認

基本的な使用方法:

# Sandbox ディレクトリに移動
cd sandbox

# ヘルプの確認
poetry run haniwers --help
poetry run haniwers-v1 --help

# ポート確認（実際のシリアルポート表示）
poetry run haniwers ports list
poetry run haniwers ports test /dev/cu.usbserial-140

# バージョン・環境情報の確認
poetry run haniwers version
poetry run haniwers version --env

設定ファイルでのテスト:

# Sandbox内で設定ファイルを作成・テスト
cp ../examples/daq.toml ./daq.toml
cp ../examples/config.toml ./config.toml

# モックデバイスでDAQをテスト（設定ファイル使用）
poetry run haniwers-v1 daq --config daq.toml --mock

# スレッショルドスキャンのテスト
poetry run haniwers-v1 scan serial --help

Mockerを使ったテスト:

# ランダムイベント生成でDAQテスト
poetry run haniwers-v1 daq --mock --mock-speed 10.0

# 既存CSVファイル再生でテスト
poetry run haniwers-v1 daq --mock --mock-file sample.csv

Sandboxディレクトリの構成:

sandbox/
├── config.toml           # グローバル設定
├── daq.toml             # DAQ設定
├── scan.toml            # スレッショルドスキャン設定
├── data/                # 処理済みデータ
├── logs/                # ログファイル
└── .env.haniwers        # 環境変数（オプション）

ユニットテスト#

# 基本テスト実行
poetry run pytest

# カバレッジ付きテスト
poetry run pytest --cov=haniwers --cov-report=html

# 特定のテストモジュール実行
poetry run pytest tests/test_config.py -v

コード品質チェック#

# フォーマット
poetry run ruff format .

# 静的解析
poetry run ruff check .

# 型チェック（mypy設定がある場合）
# poetry run mypy haniwers/

# pre-commitフック実行
poetry run pre-commit run --all-files

現在のモジュール構成（v0.23.1）#

haniwers/cli.py#

メインのCLIエントリーポイント：

  • Typerベースのコマンド定義

  • daq, scan, fit, vth, ports等のサブコマンド

  • ログ設定とオプション解析

haniwers/config.py#

設定管理：

  • Config, RunData, UserSettingsクラス

  • TOML設定ファイル（daq.toml, scan.toml）の読み込み

  • パス管理と環境固有設定

haniwers/daq.py#

データ取得（DAQ）：

  • シリアル通信（pyserial）による測定器制御

  • RealEventクラスによるイベントデータ構造

  • ファイル保存とタイムスタンプ管理

haniwers/threshold.py#

スレッショルド制御：

  • scan_thresholds_in_parallel: 並列スレッショルド測定

  • Countデータクラス: 測定結果の構造化

  • フィット処理とCSV出力

haniwers/dataset.py#

データ処理：

  • Runクラス: 測定データへのアクセス

  • パス管理とファイル操作

  • データフレーム変換

haniwers/preprocess.py & haniwers/postprocess.py#

データ処理パイプライン：

  • 生データの前処理とリサンプリング

  • 可視化とプロット機能

  • CSV形式への変換

現在の設計方針#

アーキテクチャ#

  • モジュールごとの責務分離

    • CLI: コマンド定義とオプション解析（cli.py）

    • DAQ: ハードウェア制御とデータ取得（daq.py）

    • 設定: TOML設定の管理（config.py）

    • データ処理: 前処理・後処理・可視化（preprocess.py, postprocess.py）

  • CLIはTyperベース

    • haniwers COMMAND [OPTIONS] 形式

    • サブコマンド: daq, scan, fit, vth, ports, run2csv

    • 統一されたログ出力とエラー処理

  • 設定ファイルによる柔軟性

    • daq.toml: データ取得設定

    • scan.toml: スレッショルドスキャン設定

    • runs.csv: 実験ラン管理

  • データフロー

    • 生データ取得 → 前処理 → CSV保存 → 可視化・解析

    • タイムスタンプベースのファイル管理

    • Pandas/Polarsによる効率的なデータ処理

開発のベストプラクティス#

コーディング規約#

  • Conventional Commits: コミットメッセージ規約の遵守

  • Ruff: フォーマットと静的解析

  • 型ヒント: 可能な限りtype hintsを使用

  • Docstring: 公開関数には説明を記載

リリース手順#

# 1. 機能開発・バグ修正
git commit -m "feat: add new feature"

# 2. バージョン管理
poetry run cz bump --dry-run  # 確認
poetry run cz bump -cc -ch    # 実行

# 3. パッケージ公開
poetry build
poetry publish --repository testpypi  # テスト
poetry publish                        # 本番

# 4. タグプッシュ
git push origin main --tags

デバッグとテスト#

  • ログレベル: --log-level DEBUGでデバッグ情報表示

  • モック: haniwers/mimic.pyで擬似データ生成

  • 単体テスト: 新機能追加時はテストも併せて作成

開発や改修を行う際は、以下も併せてお願いします：

  • 対応するテストの追加・更新

  • ドキュメントの更新

  • リリースノートへの変更点記載

目次