Environment Tools: Hatch

Now let us take a look at another tool for managing python environments: Hatch.

About - Hatch

Modern, extensible Python project management

HatchOfek Lev

Hatch is primarily used when you want to manage multiple environments for a single codebase.

For example, you have an application that should run on both Python 3.10 and 3,11. You would like to test it against both versions. Normally, you would need to manually create two separate virtual environments, one for each version of python. This is because it is possible that the dependency versions would be different for both the environments. Then in each environment you woud install a copy of the application and run and test it. This quickly becomes cumbersome if you need to test a wide range of versions, eg: Python 3,5+

Hatch solves this problem by managing all the environments behind the scenes for you.

Getting Started

Installation of Hatch is simple, just pipx install hatch should get you the hatch command line tool.

Creating a new hatch project is as simple as doing hatch new <projectname>. This command will create a sample project outline with a pyproject.toml file, a project source directory and a test directory where you can put your test files.

Open up the pyproject.toml file and you will see that most of the [project] section has been prepopulated with sample values.

Scroll further down and you will see a bunch of sections with the pattern [tool.hatch.*]. This is where all the hatch specific configuration is done.

Environments

Like I mentioned earlier, the main feature of hatch is the ability to create multiple environments for the same source code

When you start a new project, hatch creates an environment called default and this will be the original environment. Any dependencies added to the dependencies section of pyproject.toml will be installed into this environment.

Hatch gives us the ability to create new environments with the hatch env create command. A common use case is to have a separate test environment where testing dependencies are available or a docs environment that contains dependencies to generate documentation.

Once an environment is created, you can add a section [tool.hatch.envs.<name>] to customise the environment. For example, a test environment might have a section like this

[tool.hatch.envs.test]
dependencies = [
  "pytest",
  "pytest-cov",
  "pytest-watcher"
]

Hatch will automatically create a new virtual environment for every such definition and install the required packages into the virtual environment.

In addition to this, you can also mention the supported versions of python for an environment, by adding the following to pyproject.toml

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

Given this configuration, hatch will create two separate virtual environments for the test environment - one configured for python 3.10 and the other for 3.11. Both virtual environments will contain the dependencies defined for the test environment.

Since there could be many virtual environments created, the command hatch envs show will show all the combinations of virtual environments that are available for the project.

Scripts

Hatch also supports per-environment scripts. These are just command line aliases. For example, if I always run my test cases with coverage enabled, then I could add this into my pyproject.toml

[tool.hatch.envs.default.scripts]
test = "pytest --cov-report=term-missing --cov-config=pyproject.toml --cov=myapp --cov=tests {args}"
format = "black {args}"
lint = "ruff check {args}"

I can now issue the command hatch run test to run the test command within the default environment. Hatch will activate the default environment, run thepytest command specified in the configuration and will return me back outside the environment.

Since hatch supports multiple environments, the run command takes a --env command line parameter to run the command in a particular environment.

Just like Pipenv, Hatch also has a hatch shell command which will activate the default environment and give us a shell. Again, the --env flag can be used to enter any other environment.

Summary

Hatch is very useful when you need to work with multiple environments. It eliminates the need to keep multiple virtual environments around for different configurations.

Hatch also has many features to create wheel packages and upload them to PyPI using a build system called Hatchling. If you are developing python modules and building wheels then check out Hatchling as well.

One feature that Hatch lacks at the moment is dependency resolution, lock files and secure builds. These features are on the way and until then, we need to use a tool like pip-tools to handle it.