TestPyPI パッケージ動作テストガイド

TestPyPI パッケージ動作テストガイド#

このドキュメントでは、TestPyPIに公開したパッケージの動作をローカルで検証する方法を説明します。

概要#

パッケージをTestPyPIに公開した後、本番環境でのリリース前に、隔離されたローカル環境で正常に動作することを確認する必要があります。 このガイドでは、複数の隔離環境を使用した検証方法を提供します。

目的

開発環境の汚染を避けつつ、TestPyPIで公開されたパッケージの動作を完全に検証する

クイックスタート#

最小限の検証を迅速に行いたい場合

# 1. 仮想環境を作成
python3 -m venv /tmp/test-env
source /tmp/test-env/bin/activate

# 仮想環境が有効になるとプロンプトに (test-env) と表示
# (test-env) $

# 2. TestPyPIからインストール
(test-env) $ pip install --index-url https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple/ haniwers

# 3. インストール確認
(test-env) $ haniwers version

# 4. 基本的な動作確認
(test-env) $ haniwers --help

# 5. 終了
(test-env) $ deactivate
$ rm -rf /tmp/test-env

セットアップ方法#

方法1: Python標準の venv（推奨・シンプル）#

利点:

  • 外部ツール不要

  • セットアップが簡単

  • 開発環境に影響なし

手順:

# 1. 仮想環境を作成
python3 -m venv /tmp/test-env

# 2. 仮想環境をアクティベート
source /tmp/test-env/bin/activate  # macOS/Linux
# または
/tmp/test-env/Scripts/activate  # Windows

# 仮想環境が有効になるとプロンプトに (test-env) と表示
# (test-env) $

# 3. pipをアップグレード
(test-env) $ pip install --upgrade pip

# 4. TestPyPIからインストール
(test-env) $ pip install --index-url https://test.pypi.org/simple/ \
    --extra-index-url https://pypi.org/simple/ \
    haniwers

# 5. インストール確認
(test-env) $ pip list

# 6. テスト完了後、終了
(test-env) $ deactivate

# 仮想環境が無効になるとプロンプトが通常に戻る
# $

# 7. 環境を削除（オプション）
$ rm -rf /tmp/test-env

パスの説明:

  • /tmp/test-env: テンポラリディレクトリに環境を作成（終了後も一定期間の保持が可能）

  • または ~/test-test などローカルに作成してもよい

方法2: uv を使用（高速・モダン）#

利点:

  • 非常に高速

  • 複数Python版の管理が容易

  • Poetry と共存可能

セットアップ:

# uv をインストール（まだの場合）
curl -LsSf https://astral.sh/uv/install.sh | sh

# または pipx で
pipx install uv

使用方法:

# 1. 仮想環境を作成（任意のPythonバージョン指定可能）
uv venv /tmp/test-env --python 3.11

# 2. アクティベート
source /tmp/test-env/bin/activate

# 仮想環境が有効になるとプロンプトに (test-env) と表示
# (test-env) $

# 3. TestPyPIからインストール
(test-env) $ uv pip install --index-url https://test.pypi.org/simple/ \
    --extra-index-url https://pypi.org/simple/ \
    haniwers

# 4. インストール確認
(test-env) $ uv pip list

# 5. 終了
(test-env) $ deactivate

複数Pythonバージョンでのテスト:

# Python 3.11 環境でテスト
uv venv /tmp/testpypi-3.11 --python 3.11
source /tmp/testpypi-3.11/bin/activate

# (testpypi-3.11) $
(testpypi-3.11) $ uv pip install --index-url https://test.pypi.org/simple/ \
    --extra-index-url https://pypi.org/simple/ \
    haniwers
(testpypi-3.11) $ haniwers version
(testpypi-3.11) $ deactivate

# Python 3.12 環境でテスト
uv venv /tmp/testpypi-3.12 --python 3.12
source /tmp/testpypi-3.12/bin/activate

# (testpypi-3.12) $
(testpypi-3.12) $ uv pip install --index-url https://test.pypi.org/simple/ \
    --extra-index-url https://pypi.org/simple/ \
    haniwers
(testpypi-3.12) $ haniwers version
(testpypi-3.12) $ deactivate

パッケージの動作テスト#

1. インストール確認#

# インストール済みパッケージを確認
(test-env) $ pip show haniwers

# 出力例
# Name: haniwers
# Version: 1.4.0
# Summary: Cosmic ray detection analysis tool
# Location: /path/to/venv/lib/python3.11/site-packages

2. CLI動作確認#

# 仮想環境内で実行（プロンプトに環境名が表示されている状態）
(test-env) $ haniwers version

# 詳細な環境情報
(test-env) $ haniwers version --env

# ヘルプ表示
(test-env) $ haniwers --help

# サブコマンド確認
(test-env) $ haniwers-v0 --help
(test-env) $ haniwers-v1 --help

3. 基本コマンドテスト#

# 仮想環境内で実行
# ポート一覧表示（ハードウェア接続不要）
(test-env) $ haniwers-v1 port list

# モックデバイスでDAQテスト
(test-env) $ haniwers-v1 daq --help

# 設定ファイル機能テスト
(test-env) $ haniwers-v1 config --help

4. Pythonモジュールテスト#

# 仮想環境内で実行
# Pythonコードでモジュール導入可能か確認
(test-env) $ python3 -c "import haniwers; print(haniwers.__version__)"

# v0モジュール確認
(test-env) $ python3 -c "from haniwers.v0 import cli; print('v0 imported')"

# v1モジュール確認
(test-env) $ python3 -c "from haniwers.v1 import cli; print('v1 imported')"

5. 依存関係確認#

# 仮想環境内で実行
# インストール済み依存パッケージを確認
(test-env) $ pip list

# 特定パッケージの確認（例：typer）
(test-env) $ pip show typer
(test-env) $ pip show pydantic

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

インストール失敗：「Package not found」#

原因: TestPyPIに公開されていない、またはバージョン番号が間違っている

対処:

# TestPyPIのパッケージページを確認
# https://test.pypi.org/project/haniwers/

# 最新版のバージョン番号を確認
pip index versions --index-url https://test.pypi.org/simple/ haniwers

# 具体的なバージョンを指定してインストール
pip install --index-url https://test.pypi.org/simple/ \
    --extra-index-url https://pypi.org/simple/ \
    haniwers==1.4.0

インストール失敗：依存パッケージの解決エラー#

原因: 依存関係が PyPI に存在しない

対処:

# 詳細なエラーメッセージを確認
pip install --index-url https://test.pypi.org/simple/ \
    --extra-index-url https://pypi.org/simple/ \
    -v haniwers

# キャッシュをクリアして再試行
pip cache purge
pip install --index-url https://test.pypi.org/simple/ \
    --extra-index-url https://pypi.org/simple/ \
    haniwers

インストール成功したがコマンドが見つからない#

原因: 仮想環境が正しくアクティベートされていない、または PATH が設定されていない

対処:

# 仮想環境をアクティベート（再度実行）
source /tmp/test-env/bin/activate

# which コマンドで確認
(test-env) $ which haniwers
(test-env) $ which haniwers-v1

# フルパスで実行
(test-env) $ /tmp/test-env/bin/haniwers --help

古いバージョンがインストールされてしまう#

原因: pip のキャッシュが古い、またはシステムワイドのインストール版が干渉している

対処:

# キャッシュをクリア
(test-env) $ pip cache purge

# 既存インストール削除
(test-env) $ pip uninstall haniwers -y

# 再度インストール
(test-env) $ pip install --index-url https://test.pypi.org/simple/ \
    --extra-index-url https://pypi.org/simple/ \
    haniwers --no-cache-dir

ImportError: No module named ‘haniwers’#

原因: Python が仮想環境を使用していない、またはインストールが不完全

対処:

# 仮想環境内の Python を使用
source /tmp/test-env/bin/activate

# 仮想環境内の Python で実行
(test-env) $ /tmp/testpypi-env/bin/python -c "import haniwers; print(haniwers.__version__)"

# 再インストール
(test-env) $ pip uninstall haniwers -y
(test-env) $ pip install --index-url https://test.pypi.org/simple/ \
    --extra-index-url https://pypi.org/simple/ \
    haniwers

複数環境での並行テスト#

同じマシンで複数の隔離環境を使用する場合：

# テスト環境リスト
/tmp/testpypi-env-3.11  # Python 3.11用
/tmp/testpypi-env-3.12  # Python 3.12用
/tmp/testpypi-env-dev   # 開発版テスト用

# 環境1でテスト実行
source /tmp/testpypi-env-3.11/bin/activate
(testpypi-env-3.11) $ haniwers version
(testpypi-env-3.11) $ deactivate

# 環境2でテスト実行
source /tmp/testpypi-env-3.12/bin/activate
(testpypi-env-3.12) $ haniwers version
(testpypi-env-3.12) $ deactivate

# 結果を記録
echo "Python 3.11: $(source /tmp/testpypi-env-3.11/bin/activate && haniwers version)"
echo "Python 3.12: $(source /tmp/testpypi-env-3.12/bin/activate && haniwers version)"

環境のクリーンアップ#

テスト完了後の環境削除：

# 仮想環境をアクティベート解除
deactivate

# ディレクトリを削除
rm -rf /tmp/testpypi-env

# 複数環境がある場合
rm -rf /tmp/testpypi-env-*

# pip キャッシュをクリア（オプション）
pip cache purge

ベストプラクティス#

1. 環境名を記述的につける#

# 良い例
/tmp/testpypi-haniwers-1.4.0-py311
/tmp/testpypi-haniwers-1.4.0-py312

# 悪い例
/tmp/test
/tmp/env

2. テスト結果を記録する#

# テスト結果をログファイルに保存
{
  echo "=== TestPyPI Package Test Log ==="
  echo "Date: $(date)"
  echo "Package: haniwers"

  source /tmp/testpypi-env/bin/activate
  echo "Version: $(haniwers version)"
  echo "Environment:"
  haniwers version --env
  echo ""
  echo "CLI Tests:"
  haniwers --help
  deactivate
} > /tmp/testpypi-test-results.log

# ログファイルの内容を表示
$ cat /tmp/testpypi-test-results.log

3. テストスクリプトを自動化する#

#!/bin/bash
# test-testpypi.sh - TestPyPI パッケージテストスクリプト

VERSION=${1:-latest}
ENV_PATH="/tmp/testpypi-env-${VERSION}"

echo "Creating test environment: $ENV_PATH"
python3 -m venv "$ENV_PATH"

source "$ENV_PATH/bin/activate"

# 仮想環境がアクティベートされていることを表示
echo "Virtual environment activated: $ENV_PATH"
echo "Prompt will show: ($ENV_PATH) $"

pip install --upgrade pip

echo "Installing haniwers from TestPyPI..."
pip install --index-url https://test.pypi.org/simple/ \
    --extra-index-url https://pypi.org/simple/ \
    haniwers

echo "Running tests..."
haniwers version
haniwers --help
haniwers-v1 port list

deactivate

echo "Test completed. Environment: $ENV_PATH"
echo "To clean up: rm -rf $ENV_PATH"

実行方法:

$ chmod +x test-testpypi.sh
$ ./test-testpypi.sh 1.4.0

4. 検証チェックリスト#

テスト時には以下の項目を確認してください：

  • インストールが成功した

  • haniwers version でバージョンが表示される

  • haniwers --help でコマンド一覧が表示される

  • haniwers-v0 --help が動作する

  • haniwers-v1 --help が動作する

  • haniwers-v1 port list が動作する

  • Python モジュールとしてインポート可能 (import haniwers)

  • 依存パッケージがすべてインストールされている (pip list で確認)

  • 既存の開発環境に影響がない（別の仮想環境で実行）

関連ドキュメント#

目次