Hatch v1.6.0¶

Hatch v1.6.0 brings improvements to build environments, better handling of dynamic metadata, and support for tools like Visual Studio Code.

Build environments¶

Originally, the environment interface method for providing builder sub-environments was intended to be used in conjunction with some cleanup logic in order to provide a fresh setup every time. However, this is unnecessary in practice because build dependencies rarely change.

Without caching, repeat build environment use is slow which affects the following scenarios:

the build command
commands that read project metadata, like dep hash, if any fields are set dynamically

Now a new environment interface method build_environment_exists is used by Hatch to determine whether or not it has already been created, for implementations that have a caching mechanism.

The virtual environment type now uses this method to cache build environments.

Project metadata¶

Dynamically defined metadata is now supported everywhere, thanks to the new caching of virtual build environments.

A project metadata command is introduced that displays the fully resolved metadata. The output format is JSON unless a field is specified as an argument.

For example, if you checkout a project that is built by Hatch, like FastAPI, and run:

hatch project metadata readme

only the readme text will be displayed. If the content is in Markdown, then Rich will render it directly in your terminal:

Virtual environment location¶

The virtual environment type now uses a flat layout for storage in the configured virtual environment directory if the directory resides somewhere within the project root or if it is set to a .virtualenvs directory within the user's home directory.

For example, if you define the following Hatch configuration:

config.toml

[dirs.env]
virtual = ".hatch"

and the following matrix:

pyproject.toml hatch.toml

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

[[envs.test.matrix]]
python = ["3.7", "3.8", "3.9", "3.10", "3.11"]

then locating environments with the following command:

hatch env find test

will show that the general directory structure is:

.hatch
├── test.py3.7
├── test.py3.8
├── test.py3.9
├── test.py3.10
└── test.py3.11

This flat structure is required for detection of virtual environments by tools like Visual Studio Code and PyCharm.

Additionally, the virtual environment type now supports a path option to specify an explicit path that all inherited environments will share, such as the common .venv.

Migration script improvements¶

The script used to migrate existing projects from setuptools has been improved to handle more edge cases that were encountered in the wild and now no longer modifies the formatting of existing pyproject.toml configuration.

Hatchling¶

Hatch now depends on Hatchling v1.11.0, which was also just released.

Environment version source¶

A new env version source is available that allows for the project version to be defined by an environment variable.

Relaxed version bumping¶

The standard version scheme now supports a validate-bump option that when set to false will forego the check when updating the version that the desired version is higher than the current version.

This use case comes from Project Jupyter:

A common pattern we use in Jupyter is to bump to a .dev0 minor version bump after making a release. If we have a bug fix that needs to go out in the interim, we'd rather not be forced to create a branch every time.