Use Hatch environments with your pure Python package#

このレッスンについて

In a previous lesson, you learned how to create a Python package using the pyOpenSci copier template. In this lesson, you'll learn how to manage and use the Hatch environments set up by de What you need to complete this lesson

To complete this lesson, you will need a local Python environment and shell on your computer. You will need to have created a package using our pyOpenSci copier template. You should also have Hatch installed.

If you are using Windows or are not familiar with Shell, you may want to check out the Carpentries shell lesson. Windows users will likely need to configure a tool such as GitBash for any Shell and git-related steps.

Welcome to your shiny new package! This page will help you get started with using Hatch to run tests, build and check your package, and build your documentation.

To begin, have a look at the pyproject.toml file in your package directory. This file contains the configuration for your package. This file is written using a .toml format. You can learn more about toml here. Here's the TL&DR:

  • tomlファイルの各 [] セクションはテーブルと呼ばれます。

  • このように二重括弧[[]]でテーブルをネストできます

  • Tables contain information about a certain thing that you want to configure.

Tip

You can configure Hatch to use UV by default for environment management. UV is a package manager built in Rust. It is fast and will significantly speed up environment creation.

To use UV with Hatch, configure Hatch in the "tools" section of your pyproject.toml file.

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

Using Hatch for developing, building, and maintaining your pure Python package#

In the pyOpenSci Python package template, we have set up Hatch environments. You will notice at the bottom of the file, a hatch environment section, that looks like this:

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

Hatch allows you to configure and run environments and scripts similar to a workflow tool like tox or nox.

Tip

Hatch defaults to using venv to manage environments. However, you can configure it to use other environment tools, such as conda or mamba.

Read the hatch documentation to learn more about environments.

Below is the Hatch environment used to build and test your package. Anytime you see: tool.hatch.envs.test, it tells Hatch:

"Hey, Hatch, this is the definition for an environment.test is the name of the environment that I want you to create."

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

Below the environment "declaration," you can see the definition of what should be in that environment.

A Hatch environment to build your package#

Below is a Hatch environment definition that you will find in your new project's pyproject.toml file. It is set up to build your package's distribution files (source distribution and wheel).

Notice that the environment definition declares two dependencies: pip and twine, which the environment needs to run successfully. This declaration is similar to declaring dependencies for your package at the top of your pyproject.toml. This section tells Hatch to create a new VENV with pip and twine installed.

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

Hatch will install your package in editable mode by default

Notice the detached = True flag at the bottom of the environment. By default, hatch will install your package in editable mode into any environment it creates. detached=True tells it not to install your package into the environment.

Hatchスクリプト#

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

Above, you have defined a new environment called 'build' that Hatch will create as a virtual environment (venv). Because detached = True in that environment, Hatch won't install your package into it.

You can then use that environment to run "scripts". The definition below tells Hatch to run the following scripts in the build environment.

[tool.hatch.envs.build.scripts]

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

  • tool.hatch: このテーブルがHatch用であることをHatchに通知します

  • envs.build: 定義されたビルド環境を使用します。

  • scripts: Define what scripts to run. In this case, Hatch will run shell scripts.

Below is the build.scripts table that defines 3 shell commands to be run:

  • pip check # 依存関係を検証します

  • hatch build --clean # build your packages distribution files.

  • twine check dist/* # use twine to check that your package's sdist (source distribution) is ok.

# 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, by default, will install your package in editable mode into any virtual environment (venv) that it creates. If detached=True is set, then it will skip that step.

Running the build script#

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

hatch run build:check

This step updates the build environment and then builds and checks the output distributions of your package.

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

$ hatch shell build

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

$ pip list

To leave the environment use:

$ deactivate

Hatch, testing, and matrix environments#

It's always helpful to run your tests on the Python versions that you expect your users to be using. In this section, you'll explore the test environment setup in the pyOpenSci template package.

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

Similar to the above build environment, the environment below defines the dependencies that Hatch needs to install into the test environment (required to run your tests).

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

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

If the environment has a matrix associated with it, that tells Hatch to run the tests across different Python versions. Below, you are running tests on versions 3.10 through 3.13.

Tip

Hatch by default will install Python using UV both when you install Hatch and also when you declare a matrix environment like the one below

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

In your project, if you run hatch shell test, you will see the output below. This means that because there is a matrix of Python versions to choose from, you need to select the environment with the Python version you want to use.

➜ 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

Pick the Python test environment that you want to use and enter it, like this (this will open Python 3.13):

$ hatch shell test.py3.13

To leave the environment use:

$ deactivate

Hatch scripts for tests#

In that same tests section, you will see a tool.hatch.envs.test.scripts section. Similar to what you saw above with the build steps, this is where the "script" to run your tests is defined.

Notice that below, the script has a script called run. And that script runs pytest with a set of arguments, including generating code coverage.

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

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

hatch run test:run

Reminder

  • hatch run: this calls hatch and tells it that it will be running a command

  • test:run defines the environment you want it to run (test) in this case, and the script is defined as run

If you have a matrix setup for tests, then it will both install the needed Python version using UV and run your tests in each version of the Python environment. In this case, since there are four Python versions in the environment, your tests will be run four times, once in each Python version listed in the matrix table.

@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環境でドキュメントをビルドする#

Finally, you can build and serve your documentation using hatch. To build a static HTML version of the docs run:

hatch run docs:build

To run a local server with your docs updated as you update your markdown files, run:

hatch run docs:serve

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

mac: ctrl + c windows: