純粋な Python パッケージで Hatch 環境を使う#

このレッスンについて

前のレッスンでは、pyOpenSci コピーテンプレートを使用して Python パッケージを作成する方法を学びました。このレッスンでは、このレッスンを完了するために必要なもの によってセットアップされた Hatch 環境を管理および使用する方法を学習します。

このレッスンを完了するには、コンピュータにローカルの Python 環境とシェルが必要です。pyOpenSci copier テンプレートを使ってパッケージを作成しておく必要があります。また、Hatch がインストールされている必要があります。

Windows を使用している場合やシェルに慣れていない場合は、Carpentries のシェルレッスンを参照するとよいでしょう。Windows ユーザーは、シェルや git に関連するステップのために GitBash などのツールを設定する必要があるでしょう。

ピカピカの新しいパッケージへようこそ!このページは、Hatch を使用してテストを実行し、パッケージをビルドおよびチェックし、ドキュメントをビルドする方法を開始するのに役立ちます。

まず、パッケージディレクトリ内の pyproject.toml ファイルを見てください。このファイルにはパッケージの構成が含まれており、TOML 形式を使用して書かれています。 TL&DRは次のとおりです。

tomlファイルの各 [] セクションはテーブルと呼ばれます。
このように二重括弧[[]]でテーブルをネストできます
テーブルには、構成したい特定の内容に関する情報が含まれています。

Tip

環境管理にデフォルトで UV を使用するように Hatch を構成できます。 UV は Rust に組み込まれたパッケージマネージャーです。これは高速であり、環境の作成を大幅にスピードアップします。

ハッチングで UV を使用するには、pyproject.toml ファイルの「tools」セクションでハッチングを設定します。

[tool.hatch.envs.default]
installer = "uv"

Hatch を使用した純粋な Python パッケージの開発、構築、保守#

pyOpenSci Python パッケージテンプレートでは、{term}「ハッチ環境」定義をセットアップしました。ファイルの下部に、次のような hatch 環境セクションがあることに気づくでしょう。

########################################
# Hatch Environments
########################################

Hatch を使用すると、tox や nox などのワークフローツールと同様の環境とスクリプトを構成して実行できます。

Tip

Hatch はデフォルトで venv を使用して環境を管理します。ただし、conda や mamba などの他の環境ツールを使用するように構成できます。

環境について詳しくは、ハッチングのドキュメントを参照してください。

以下は、パッケージのビルドとテストに使用される Hatch 環境です。「tool.hatch.envs.test」が表示されるたびに、Hatch に次のように指示します。

「ねえ、ハッチ、これは環境の定義です。test はあなたに作成してほしい環境の名前です。」

つまり tool.hatch.envs.build は build という環境を作成します。

環境の「宣言」の下に、その環境にあるべきものの定義が表示されます。

パッケージをビルドするための Hatch 環境#

以下は、新しいプロジェクトの pyproject.toml ファイルにある Hatch 環境定義です。これは、パッケージの配布ファイル (ソース配布 (sdist) およびホイール (.whl)) をビルドするように設定されています。

環境定義では、環境が正常に実行されるために必要な 2 つの Dependency、pip と twine が宣言されていることに注意してください。この宣言は、pyproject.toml の先頭でパッケージの依存関係を宣言するのと似ています。

[tool.hatch.envs.build]
description = """Test the installation the package."""
dependencies = [
    "pip",
    "twine",
]
detached = true

Hatch はデフォルトでパッケージを編集可能モードでインストールします

環境の下部にある「detached = True」フラグに注目してください。デフォルトでは、hatch は作成した環境にパッケージを編集可能モードでインストールします。 detached=True は、パッケージを環境にインストールしないように指示します。

Hatchスクリプト#

Hatch は、特定の Hatch 環境で実行されるスクリプト (Hatch) コマンドの定義をサポートしています。

上記では、Hatch が仮想環境 (venv) として作成する「build」という新しい環境を定義しました。その環境では「detached = True」なので、Hatch はパッケージをその環境にインストールしません。

scripts: 実行するスクリプトを定義します。この場合、Hatch はシェルスクリプトを実行します。

[tool.hatch.envs.build.scripts]

この scripts を実行するために次の構文を使用して定義します:

tool.hatch: このテーブルがHatch用であることをHatchに通知します
envs.build: 定義されたビルド環境を使用します。
以下は、実行される 3 つのシェルコマンドを定義する build.scripts テーブルです。

twine check dist/* #twine を使用して、パッケージの sdist (ソース配布) が正常であることを確認します。

pip check # 依存関係を検証します
hatch build --clean # パッケージの配布ファイルをビルドします。
Hatch はデフォルトで、作成した仮想環境 (venv) にパッケージを編集可能モードでインストールします。 detached=True が設定されている場合、そのステップはスキップされます。

# This table installs the command hatch run install:check, which will build and check your package.
[tool.hatch.envs.build.scripts]
check = [
    "pip check",
    "hatch build {args:--clean}",
    "twine check dist/*",
]
detached = true

Tip

デフォルトでは、Hatchはパッケージを編集可能なモードで、作成した任意の仮想環境（ venv ）にインストールします。「detached = True」が設定されている場合、そのステップはスキップされます。

ビルドスクリプトの実行#

ビルドスクリプトを実行し、次のようにパッケージをビルドできます:

hatch run build:check

この手順では、ビルド環境を更新し、パッケージの出力ディストリビューションをビルドして確認します。

シェルでビルド環境に入って確認できます:

$ hatch shell build

環境で pip list を実行すると、twineが入っています:

$ pip list

環境を離れるには次を使います:

$ deactivate

Hatch、テスト、マトリックス環境#

ユーザーが使用すると予想される Python バージョンでテストを実行すると、常に役立ちます。このセクションでは、pyOpenSci テンプレートパッケージでのテスト環境のセットアップについて説明します。

以下に、Hatch環境テストテーブルが表示されます。

上記のビルド環境と同様に、以下の環境は、Hatch がテスト環境にインストールする必要がある (テストを実行するために必要な) 依存関係を定義します。

[tool.hatch.envs.test]
description = """Run the test suite."""
dependencies = [
    "pytest",
    "pytest-cov",
    "pytest-raises",
    "pytest-randomly",
    "pytest-xdist",
]

テスト環境にはマトリックスが関連付けられています#

環境にマトリックスが関連付けられている場合は、異なる Python バージョン間でテストを実行するように Hatch に指示します。以下では、バージョン 3.10 ～ 3.13 でテストを実行しています。

Tip

Hatch は、Hatch をインストールするときと、以下のようなマトリックス環境を宣言するときの両方で、デフォルトで Python UV を使用してをインストールします。

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

プロジェクトで「hatch Shell test」を実行すると、以下の出力が表示されます。これは、選択できる Python バージョンのマトリックスがあるため、使用する Python バージョンが含まれる環境を選択する必要があることを意味します。

➜ hatch shell test
Environment `test` defines a matrix, choose one of the following instead:

test.py3.10
test.py3.11
test.py3.12
test.py3.13

使用する Python テスト環境を選択し、次のように入力します (これにより、Python 3.13 が開きます)。

$ hatch shell test.py3.13

環境を離れるには次を使います:

$ deactivate

テスト用の Hatch スクリプト#

同じテストセクションに、「tool.hatch.envs.test.scripts」セクションがあります。上記のビルド手順と同様に、ここでテストを実行する「スクリプト」が定義されます。

以下のスクリプトには「run」というスクリプトがあることに注意してください。そして、そのスクリプトは、コードカバレッジの生成を含む一連の引数を指定して pytest を実行します。

[tool.hatch.envs.test.scripts]
run = "pytest {args:--cov=greatproject --cov-report=term-missing}"

ターミナルでこのスクリプトを実行するには、次の構文を使用します:

hatch run test:run

リマインダー

hatch run: これはハッチを呼び出し、コマンドを実行することを伝えます。
この場合、test:run は実行する環境 (test) を定義し、スクリプトは run として定義されます。

テスト用のマトリックスセットアップがある場合は、UV を使用して必要な Python バージョンをインストールし、Python 環境の各バージョンでテストを実行します。この場合、環境には 4 つの Python バージョンがあるため、テストはマトリックステーブルにリストされている各 Python バージョンで 1 回ずつ、計 4 回実行されます。

@lwasser ➜ /workspaces/pyopensci-scipy25-create-python-package (main) $ hatch run test:run
──────────────────────────────────────────────────────────────────────── test.py3.10 ────────────────────────────────────────────────────────────────────────
==================================================================== test session starts ====================================================================
platform linux -- Python 3.10.16, pytest-8.4.1, pluggy-1.6.0
Using --randomly-seed=1490740387
rootdir: /workspaces/pyopensci-scipy25-create-python-package
configfile: pyproject.toml
testpaths: tests
plugins: xdist-3.8.0, randomly-3.16.0, raises-0.11, cov-6.2.1
collected 2 items

tests/system/test_import.py .                                                                                                                         [ 50%]
tests/unit/test_example.py .                                                                                                                          [100%

****************** SOME OUTPUT IS INTENTIONALLY DELETED ********************
====================================================================== tests coverage =======================================================================
_____________________________________________________ coverage: platform linux, python 3.11.12-final-0 ______________________________________________________

Name                           Stmts   Miss Branch BrPart    Cover   Missing
----------------------------------------------------------------------------
src/greatproject/__init__.py       0      0      0      0  100.00%
src/greatproject/example.py        2      0      0      0  100.00%
----------------------------------------------------------------------------
TOTAL                              2      0      0      0  100.00%
===================================================================== 2 passed in 0.05s =====================================================================

Hatch環境でドキュメントをビルドする#

最後に、ハッチを使用してドキュメントを構築して提供できます。静的 HTML バージョンのドキュメントを構築するには、次のコマンドを実行します。

hatch run docs:build

マークダウンファイルの更新に応じてドキュメントも更新された状態でローカルサーバーを実行するには、次のコマンドを実行します。

hatch run docs:serve

ドキュメントの提供を停止するには:

mac: ctrl + c windows: