パッケージ管理したい（`hatch`）

// プロジェクト初期化
$ hatch new プロジェクト名

// 環境管理
$ hatch shell
$ hatch env show
$ hatch env remove 環境名

// パッケージ実行と開発
$ hatch run コマンド
$ hatch run pytest

// テスト実行
$ hatch test

// パッケージ公開
$ hatch build
$ hatch publish

hatchはPythonプロジェクトの開発から公開まで、統合的に管理できるツールです。 pyproject.tomlで依存関係を管理し、複数のPythonバージョン環境を自動で構築・テストできます。

注釈

hatchはパッケージ開発に特化しており、テストやビルド、公開までのワークフローが統合されています。

インストールしたい（`hatch`）

$ brew install hatch

$ which -a hatch
/opt/homebrew/bin/hatch

$ hatch --version
hatch, version 1.13.0

hatchはHomebrewでインストールできます。 pipxを使ったインストール方法もあります。

注釈

pipやpipxでもインストールできます。推奨されるインストール方法はpipx install hatchです。

仮想環境したい（`hatch env`）

$ cd PROJECT_NAME
$ hatch shell
Creating environment: default
Python 3.12.7

(default) $

hatch shellコマンドで仮想環境を作成・アクティブ化できます。デフォルトでdefaultという名前の環境が作成されます。環境はプロジェクトディレクトリの.venv（または他の場所）に保存されます。

注釈

hatch env createで環境を明示的に作成することもできますが、通常はhatch shellやhatch runで自動的に作成されます。

依存関係を管理したい（`pyproject.toml`）

hatchではpyproject.tomlを直接編集して依存関係を管理します。 hatchにはコマンドで依存関係を追加・削除する機能がありません。

# プロジェクトの依存関係
[project]
dependencies = [
  "requests>=2.28.0",
  "click>=8.0.0",
]

# 開発用の依存関係
[project.optional-dependencies]
dev = [
  "pytest>=8.0",
  "pytest-cov>=4.0",
]

# テスト環境の依存関係
[tool.hatch.envs.test]
dependencies = [
  "pytest>=8.0",
  "pytest-cov>=4.0",
]

pyproject.tomlを編集した後、以下のコマンドで環境を更新できます：

$ hatch env create
Creating environment: default

$ hatch run pytest
Running tests in default environment...

hatchは自動的に依存関係を解決してインストールします。

注釈

pyproject.tomlを編集したら、hatch shellやhatch runで環境を再作成すると自動的に依存関係が更新されます。

新規プロジェクトしたい（`hatch new`）

$ hatch --version
hatch, version 1.13.0

$ hatch new PROJECT_NAME
Created project `PROJECT_NAME` at `/path/to/PROJECT_NAME`

hatch newコマンドでプロジェクトを初期化できます。同名のプロジェクトがすでに存在する場合は、エラーになります。

hatchで作成されるプロジェクト構造は、Pythonパッケージ開発に最適化されています：

$ tree PROJECT_NAME
PROJECT_NAME
├── README.md
├── LICENSE.txt
├── pyproject.toml
├── src/
│   └── project_name/
│       ├── __about__.py
│       └── __init__.py
└── tests/
    ├── __init__.py
    └── test_example.py

src/レイアウトを使用することで、パッケージの依存関係の問題を回避できます。 __about__.pyにバージョン情報が集約されており、バージョン管理が簡単です。

注釈

hatch newは対話形式で詳細情報を入力することもできます。 hatch new -iで対話モードを起動できます。

パッケージを実行したい（`hatch run`）

$ hatch run コマンド名

// ユニットテストを実行
$ hatch run pytest

// フォーマッターを実行
$ hatch run ruff format

// 自作スクリプトを実行
$ hatch run python src/my_script.py [オプション]

hatch runで仮想環境内のパッケージを実行できます。またpyproject.tomlの[project.scripts]で設定したスクリプトエントリーポイントも実行できます。

pyproject.tomlに環境別のスクリプトを定義することもできます：

[tool.hatch.envs.default.scripts]
format = "ruff format ."
lint = "ruff check ."
test = "pytest"

定義したスクリプトは以下のように実行できます：

$ hatch run format
$ hatch run lint
$ hatch run test

注釈

hatch runは指定した環境内でコマンドを実行します。環境を指定しない場合はデフォルト環境で実行されます。

パッケージを公開したい（`hatch build` / `hatch publish`）

$ hatch build
Building `wheel` wheel (src/project_name)
Successfully built dist/project_name-0.0.1-py3-none-any.whl
Building `sdist` sdist (src/project_name)
Successfully built dist/project_name-0.0.1.tar.gz

$ hatch publish
Publishing to PyPI with token

hatch buildコマンドでパッケージを作成できます。 dist/ディレクトリ内にsdist形式（.tar.gz）とwheel形式（.whl）のパッケージが生成されます。

hatch publishコマンドでPyPIにパッケージを公開できます。初回公開時はTestPyPIにテスト公開することをオススメします：

$ hatch publish -r testpypi
Publishing to https://test.pypi.org/legacy/

PyPIへのアップロード前に、PyPIアカウントとAPIトークンを用意する必要があります。

注意

同じパッケージ名はPyPIに登録できません。パッケージを公開する前に名前の重複がないか確認が必要です。

また、同じバージョンの再アップロード（上書き）はできません。変更内容に応じてバージョンを更新する必要があります。

複数のPythonバージョンでテストしたい（`hatch test`）

$ hatch test
Running tests for multiple Python versions...
3.10: PASSED
3.11: PASSED
3.12: PASSED

hatch testコマンドで複数のPythonバージョンを使用してテストを実行できます。 hatchは必要なPythonディストリビューションを自動的にダウンロードするため、事前インストールが不要です。

テスト対象のPythonバージョンはpyproject.tomlで指定します：

[tool.hatch.envs.test]
python = ["3.10", "3.11", "3.12"]

テスト実行時のオプション：

$ hatch test --parallel
$ hatch test --cover
$ hatch test 3.12

--parallelオプションで複数バージョンのテストを並列実行できます。 --coverオプションでコードカバレッジを測定できます。

注釈

hatchは複数のPythonバージョン環境を自動的に管理し、各バージョンで同じテストスイートを実行します。

バージョンを管理したい（`hatch version`）

$ hatch version
0.0.1

$ hatch version patch
Bumped version from 0.0.1 to 0.0.2

$ hatch version minor
Bumped version from 0.0.2 to 0.1.0

$ hatch version major
Bumped version from 0.1.0 to 1.0.0

hatch versionでプロジェクトのバージョンを管理できます。バージョン情報はsrc/project_name/__about__.pyに保存されます。

バージョンバンプコマンド：

hatch version patch：パッチバージョンをアップ（バグ修正）
hatch version minor：マイナーバージョンをアップ（新機能）
hatch version major：メジャーバージョンをアップ（大きな変更）

注釈

hatchはsrc/レイアウトを採用しており、バージョン情報は__about__.pyで一元管理されます。

hatchとpytestの統合

hatchで作成したプロジェクトには、デフォルトでpytestがテスト環境に含まれています。以下のコマンドでテストを実行できます：

$ hatch run test
Running tests...
tests/test_example.py .                                    [100%]
1 passed

$ hatch run pytest tests/
Running tests...
tests/test_example.py .                                    [100%]
1 passed

$ hatch run pytest tests/ -v
Running tests...
tests/test_example.py::test_example PASSED              [100%]
1 passed

hatchは複数のPythonバージョンでテストを実行する機能が統合されているため、 CI/CDパイプラインの設定も簡単です。

hatchとpyprojectの関係

hatchはPEP 517/518に完全準拠しており、pyproject.tomlは標準的なPythonパッケージング仕様にしたがっています。これにより、他のツール（pip、buildなど）との互換性が保証されています。

注釈

pyproject.tomlはPythonパッケージの標準メタデータ形式です。 hatchはこの仕様に準拠した最新のパッケージマネージャーです。

パッケージ管理したい（hatch）

インストールしたい（hatch）

仮想環境したい（hatch env）

依存関係を管理したい（pyproject.toml）

新規プロジェクトしたい（hatch new）

パッケージを実行したい（hatch run）

パッケージを公開したい（hatch build / hatch publish）

複数のPythonバージョンでテストしたい（hatch test）

バージョンを管理したい（hatch version）