From 053ed381e81de89230b34d31025a2a0d61c6b49d Mon Sep 17 00:00:00 2001 From: ofek Date: Sun, 18 Sep 2022 23:53:46 +0000 Subject: [PATCH] More directories that cannot be traversed (#493) bb516f17158b5258a32c2cc33378eff33e0af5cf --- dev/history/index.html | 2 +- dev/search/search_index.json | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/dev/history/index.html b/dev/history/index.html index ebd2e350d..14fb990e2 100644 --- a/dev/history/index.html +++ b/dev/history/index.html @@ -1 +1 @@ - History - Hatch
Skip to content

History

All notable changes to this project will be documented in this file.

The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.

Hatch

Unreleased

Changed:

  • The run_shell_command environment interface method now accepts arbitrary subprocess.Popen keyword arguments. This is not strictly breaking, but will be utilized in upcoming features.
  • The internal directory structure for storing virtual environments is now more nested. This is not breaking, but any local environments will be created anew.

Added:

  • Add project command group to view details about the project like PEP 621 metadata
  • Build environments for the virtual environment type are now cached for improved performance
  • Add build_environment_exists method to the environment interface for implementations that cache the build environment
  • Support Bash on Windows for the shell command
  • The setuptools migration script no longer modifies the formatting of existing pyproject.toml configuration
  • Bump the minimum supported version of Hatchling to 1.9.0

Fixed:

  • Environments now respect dynamically defined project dependencies
  • Handle more edge cases in the setuptools migration script
  • Depend on packaging explicitly rather than relying on it being a transitive dependency of Hatchling

1.5.0 - 2022-08-28

Added:

  • The index publisher now recognizes repository-specific options
  • Add the --ignore-compat flag to the env run command
  • Setting the HATCH_PYTHON environment variable to self will now force the use of the Python executable Hatch is running on for virtual environment creation

Fixed:

  • Fix the --force-continue flag of the env run command
  • Handle more edge cases in the setuptools migration script

1.4.2 - 2022-08-16

Fixed:

  • Fix check for updating static versions with the version command when metadata hooks are in use

1.4.1 - 2022-08-13

Fixed:

  • Fix non-detached inheritance disabling for environments

1.4.0 - 2022-08-06

Added:

  • The default Python for virtual environments now checks PATH before using the one Hatch is running on
  • Values for environment env-vars now support context formatting
  • Add name override for environments to allow for regular expression matching
  • The index publisher now better supports non-PyPI indices
  • Add certificate options to the index publisher
  • Display waiting text when checking dependencies and removing environments
  • Display help text the first time the shell command is executed
  • Update project templates with Python 3.11 and the latest versions of various GitHub Actions
  • Add support for Almquist (ash) shells
  • Add hyperlink as a dependency for better handling of package index URLs
  • Bump the minimum supported version of virtualenv to 20.16.2
  • Bump the minimum supported version of tomlkit to 0.11.1

Fixed:

  • Acknowledge extra-dependencies for the env show command
  • Fix locating executables within virtual environments on Debian
  • Fix managing the terminal size inside the shell command
  • Fix default code coverage file omission for the src-layout project template option

1.3.1 - 2022-07-11

Fixed:

  • Support -h/--help flag for the run command

1.3.0 - 2022-07-10

Changed:

  • Rename the default publishing plugin from pypi to the more generic index

Added:

  • Support the absence of pyproject.toml files, as is the case for apps and non-Python projects
  • Hide scripts that start with an underscore for the env show command by default
  • Ignoring the exit codes of commands by prefixing with hyphens now works with entire named scripts
  • Add a way to require confirmation for publishing
  • Add --force-continue flag to the env run command
  • Make tracebacks colorful and less verbose
  • When shell configuration has not been defined, attempt to use the current shell based on parent processes before resorting to the defaults
  • The shell name pwsh is now an alias for powershell
  • Remove atomicwrites dependency
  • Relax constraint on userpath dependency
  • Bump the minimum supported version of Hatchling to 1.4.1

Fixed:

  • Keep environments in sync with the dependencies of the selected features
  • Use utf-8 for all files generated for new projects
  • Escape special characters Git may return in the user name when writing generated files for new projects
  • Normalize the package name to lowercase in setuptools migration script
  • Fix parsing of source distributions during publishing

1.2.1 - 2022-05-30

Fixed:

  • Fix handling of top level data_files in setuptools migration script

1.2.0 - 2022-05-22

Changed:

  • The enter_shell environment plugin method now accepts an additional args parameter

Added:

  • Allow context string formatting for environment dependencies
  • Add environment context string formatting fields env_name, env_type, matrix, verbosity, and args
  • Support overriding the default arguments used to spawn shells on non-Windows systems
  • Bump the minimum supported version of Hatchling to 1.3.0

Fixed:

  • Improve setuptools migration script

1.1.2 - 2022-05-20

Fixed:

  • Bump the minimum supported version of Hatchling to 1.2.0
  • Update project metadata to reflect support for Python 3.11

1.1.1 - 2022-05-12

Fixed:

  • Fix setuptools migration script for non-Windows systems

1.1.0 - 2022-05-12

Changed:

  • In order to simplify the implementation of command execution for environment plugins, the run_shell_commands method has been replaced by the singular run_shell_command. A new command_context method has been added to more easily satisfy complex use cases.
  • The finalize_command environment plugin method has been removed in favor of the newly introduced context formatting functionality.

Added:

  • Add context formatting functionality i.e. the ability to insert values into configuration like environment variables and command line arguments
  • Any verbosity for command execution will now always display headers, even for single environments
  • Every executed command is now displayed when running multiple commands or when verbosity is enabled
  • Similar to make, ignore the exit code of executed commands that start with - (a hyphen)
  • Add ability for the --init flag of the new command to automatically migrate setuptools configuration
  • Update project metadata to reflect the adoption by PyPA and production stability

1.0.0 - 2022-04-28

This is the first stable release of Hatch v1, a complete rewrite. Enjoy!

Hatchling

Unreleased

Fixed:

  • Improve tracking of dynamic metadata
  • Fix core metadata for entries in project.optional-dependencies that use direct references

1.9.0 - 2022-09-09

Changed:

  • File pattern matching now more closely resembles Git's behavior

Added:

  • Implement a minimal version of prepare_metadata_for_build_wheel and prepare_metadata_for_build_editable for non-frontend tools that only need to inspect a project's metadata
  • Add metadata command to view PEP 621 project metadata
  • Improve error messages for SPDX license errors
  • Retroactively support License-File for core metadata starting at version 2.1
  • Bump the minimum supported version of pathspec to 0.10.1

Fixed:

  • Allow the valid non-SPDX license values LicenseRef-Public-Domain and LicenseRef-Proprietary
  • Show the help text of the CLI when no subcommand is selected

1.8.1 - 2022-08-25

Fixed:

  • Fix default file inclusion for wheel build targets when both the project name and package directory name are not normalized

1.8.0 - 2022-08-16

Added:

  • Add get_known_classifiers method to metadata hooks

Fixed:

  • Fix check for updating static versions with the version command when metadata hooks are in use

1.7.1 - 2022-08-13

Fixed:

  • Fix the value of the relative_path attribute of included files, that some build plugins may use, when selecting explicit paths

1.7.0 - 2022-08-12

Added:

  • Add require-runtime-features option for builders and build hooks
  • Check for unknown trove classifiers
  • Update SPDX license information to version 3.18

Fixed:

  • Add better error message for wheel target dev mode installations that define path rewrites with the sources option
  • Note the allow-direct-references option in the relevant error messages

1.6.0 - 2022-07-23

Changed:

  • When no build targets are specified on the command line, now default to sdist and wheel targets rather than what happens to be defined in config
  • The code version source now only supports files with known extensions
  • Global build hooks now run before target-specific build hooks to better match expected behavior

Added:

  • The code version source now supports loading extension modules
  • Add search-paths option for the code version source

Fixed:

  • Fix removing sources using an empty string value in the mapping
  • The strict-naming option now also applies to the metadata directory of wheel targets

1.5.0 - 2022-07-11

Added:

  • Support the final draft of PEP 639
  • Add strict-naming option for sdist and wheel targets

Fixed:

  • Project names are now stored in sdist and wheel target core metadata exactly as defined in pyproject.toml without normalization to allow control of how PyPI displays them

1.4.1 - 2022-07-04

Fixed:

  • Fix forced inclusion of important files like licenses for sdist targets when using the explicit selection options
  • Don't sort project URL metadata so that the rendered order on PyPI can be controlled

1.4.0 - 2022-07-03

Changed:

  • The packages option uses the new only-include option to provide targeted inclusion, since that is desired most of the time. You can retain the old behavior by using the include and sources options together.

Added:

  • Support PEP 561 type hinting
  • Add version build hook
  • Add only-include option
  • The editable version of wheel targets now respects the force-include option by default
  • The force-include option now supports path rewriting with the sources option
  • The wheel target shared-data and extra-metadata options now respect file selection options
  • The wheel target now auto-detects single module layouts
  • Improve performance by never entering directories that are guaranteed to be undesirable like __pycache__ rather than excluding individual files within
  • Update SPDX license information to version 3.17

Fixed:

  • Don't write empty entry points file for wheel targets if there are no entry points defined
  • Allow metadata hooks to set the version in all cases
  • Prevent duplicate file entries from inclusion when using the force-include option

1.3.1 - 2022-05-30

Fixed:

  • Better populate global variables for the code version source

1.3.0 - 2022-05-22

Removed:

  • Remove unused global args context string formatting field

Added:

  • Improve error messages for the env context string formatting field

Fixed:

  • Fix uri context string formatting modifier on Windows

1.2.0 - 2022-05-20

Added:

  • Allow context formatting for project.dependencies and project.optional-dependencies

1.1.0 - 2022-05-19

Added:

  • Add uri and real context string formatting modifiers for file system paths

1.0.0 - 2022-05-17

Changed:

  • Drop support for Python 2

Added:

  • Improve error messaging for invalid versions
  • Update project metadata to reflect support for Python 3.11

0.25.1 - 2022-06-14

Fixed:

  • Fix support for Windows on Python 2 by removing its support for symlinks

0.25.0 - 2022-05-15

Added:

  • Add skip-excluded-dirs build option
  • Allow build data to add additional project dependencies for wheel and sdist build targets
  • Add force_include_editable build data for the wheel build target
  • Add build_hooks build data
  • Add support for Mercurial's .hgignore files when using glob syntax
  • Update project metadata to reflect the adoption by PyPA

Fixed:

  • Properly use underscores for the name of force_include build data
  • No longer greedily skip excluded directories by default

0.24.0 - 2022-04-28

This is the initial public release of the Hatchling build system. Support for Python 2 will be dropped in version 1.

Last update: September 18, 2022
\ No newline at end of file + History - Hatch
Skip to content

History

All notable changes to this project will be documented in this file.

The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.

Hatch

Unreleased

Changed:

  • The run_shell_command environment interface method now accepts arbitrary subprocess.Popen keyword arguments. This is not strictly breaking, but will be utilized in upcoming features.
  • The internal directory structure for storing virtual environments is now more nested. This is not breaking, but any local environments will be created anew.

Added:

  • Add project command group to view details about the project like PEP 621 metadata
  • Build environments for the virtual environment type are now cached for improved performance
  • Add build_environment_exists method to the environment interface for implementations that cache the build environment
  • Support Bash on Windows for the shell command
  • The setuptools migration script no longer modifies the formatting of existing pyproject.toml configuration
  • Bump the minimum supported version of Hatchling to 1.9.0

Fixed:

  • Environments now respect dynamically defined project dependencies
  • Handle more edge cases in the setuptools migration script
  • Depend on packaging explicitly rather than relying on it being a transitive dependency of Hatchling

1.5.0 - 2022-08-28

Added:

  • The index publisher now recognizes repository-specific options
  • Add the --ignore-compat flag to the env run command
  • Setting the HATCH_PYTHON environment variable to self will now force the use of the Python executable Hatch is running on for virtual environment creation

Fixed:

  • Fix the --force-continue flag of the env run command
  • Handle more edge cases in the setuptools migration script

1.4.2 - 2022-08-16

Fixed:

  • Fix check for updating static versions with the version command when metadata hooks are in use

1.4.1 - 2022-08-13

Fixed:

  • Fix non-detached inheritance disabling for environments

1.4.0 - 2022-08-06

Added:

  • The default Python for virtual environments now checks PATH before using the one Hatch is running on
  • Values for environment env-vars now support context formatting
  • Add name override for environments to allow for regular expression matching
  • The index publisher now better supports non-PyPI indices
  • Add certificate options to the index publisher
  • Display waiting text when checking dependencies and removing environments
  • Display help text the first time the shell command is executed
  • Update project templates with Python 3.11 and the latest versions of various GitHub Actions
  • Add support for Almquist (ash) shells
  • Add hyperlink as a dependency for better handling of package index URLs
  • Bump the minimum supported version of virtualenv to 20.16.2
  • Bump the minimum supported version of tomlkit to 0.11.1

Fixed:

  • Acknowledge extra-dependencies for the env show command
  • Fix locating executables within virtual environments on Debian
  • Fix managing the terminal size inside the shell command
  • Fix default code coverage file omission for the src-layout project template option

1.3.1 - 2022-07-11

Fixed:

  • Support -h/--help flag for the run command

1.3.0 - 2022-07-10

Changed:

  • Rename the default publishing plugin from pypi to the more generic index

Added:

  • Support the absence of pyproject.toml files, as is the case for apps and non-Python projects
  • Hide scripts that start with an underscore for the env show command by default
  • Ignoring the exit codes of commands by prefixing with hyphens now works with entire named scripts
  • Add a way to require confirmation for publishing
  • Add --force-continue flag to the env run command
  • Make tracebacks colorful and less verbose
  • When shell configuration has not been defined, attempt to use the current shell based on parent processes before resorting to the defaults
  • The shell name pwsh is now an alias for powershell
  • Remove atomicwrites dependency
  • Relax constraint on userpath dependency
  • Bump the minimum supported version of Hatchling to 1.4.1

Fixed:

  • Keep environments in sync with the dependencies of the selected features
  • Use utf-8 for all files generated for new projects
  • Escape special characters Git may return in the user name when writing generated files for new projects
  • Normalize the package name to lowercase in setuptools migration script
  • Fix parsing of source distributions during publishing

1.2.1 - 2022-05-30

Fixed:

  • Fix handling of top level data_files in setuptools migration script

1.2.0 - 2022-05-22

Changed:

  • The enter_shell environment plugin method now accepts an additional args parameter

Added:

  • Allow context string formatting for environment dependencies
  • Add environment context string formatting fields env_name, env_type, matrix, verbosity, and args
  • Support overriding the default arguments used to spawn shells on non-Windows systems
  • Bump the minimum supported version of Hatchling to 1.3.0

Fixed:

  • Improve setuptools migration script

1.1.2 - 2022-05-20

Fixed:

  • Bump the minimum supported version of Hatchling to 1.2.0
  • Update project metadata to reflect support for Python 3.11

1.1.1 - 2022-05-12

Fixed:

  • Fix setuptools migration script for non-Windows systems

1.1.0 - 2022-05-12

Changed:

  • In order to simplify the implementation of command execution for environment plugins, the run_shell_commands method has been replaced by the singular run_shell_command. A new command_context method has been added to more easily satisfy complex use cases.
  • The finalize_command environment plugin method has been removed in favor of the newly introduced context formatting functionality.

Added:

  • Add context formatting functionality i.e. the ability to insert values into configuration like environment variables and command line arguments
  • Any verbosity for command execution will now always display headers, even for single environments
  • Every executed command is now displayed when running multiple commands or when verbosity is enabled
  • Similar to make, ignore the exit code of executed commands that start with - (a hyphen)
  • Add ability for the --init flag of the new command to automatically migrate setuptools configuration
  • Update project metadata to reflect the adoption by PyPA and production stability

1.0.0 - 2022-04-28

This is the first stable release of Hatch v1, a complete rewrite. Enjoy!

Hatchling

Unreleased

Added:

  • Add the following to the list of directories that cannot be traversed: __pypackages__, .hg, .hatch, .tox, .nox

Fixed:

  • Improve tracking of dynamic metadata
  • Fix core metadata for entries in project.optional-dependencies that use direct references

1.9.0 - 2022-09-09

Changed:

  • File pattern matching now more closely resembles Git's behavior

Added:

  • Implement a minimal version of prepare_metadata_for_build_wheel and prepare_metadata_for_build_editable for non-frontend tools that only need to inspect a project's metadata
  • Add metadata command to view PEP 621 project metadata
  • Improve error messages for SPDX license errors
  • Retroactively support License-File for core metadata starting at version 2.1
  • Bump the minimum supported version of pathspec to 0.10.1

Fixed:

  • Allow the valid non-SPDX license values LicenseRef-Public-Domain and LicenseRef-Proprietary
  • Show the help text of the CLI when no subcommand is selected

1.8.1 - 2022-08-25

Fixed:

  • Fix default file inclusion for wheel build targets when both the project name and package directory name are not normalized

1.8.0 - 2022-08-16

Added:

  • Add get_known_classifiers method to metadata hooks

Fixed:

  • Fix check for updating static versions with the version command when metadata hooks are in use

1.7.1 - 2022-08-13

Fixed:

  • Fix the value of the relative_path attribute of included files, that some build plugins may use, when selecting explicit paths

1.7.0 - 2022-08-12

Added:

  • Add require-runtime-features option for builders and build hooks
  • Check for unknown trove classifiers
  • Update SPDX license information to version 3.18

Fixed:

  • Add better error message for wheel target dev mode installations that define path rewrites with the sources option
  • Note the allow-direct-references option in the relevant error messages

1.6.0 - 2022-07-23

Changed:

  • When no build targets are specified on the command line, now default to sdist and wheel targets rather than what happens to be defined in config
  • The code version source now only supports files with known extensions
  • Global build hooks now run before target-specific build hooks to better match expected behavior

Added:

  • The code version source now supports loading extension modules
  • Add search-paths option for the code version source

Fixed:

  • Fix removing sources using an empty string value in the mapping
  • The strict-naming option now also applies to the metadata directory of wheel targets

1.5.0 - 2022-07-11

Added:

  • Support the final draft of PEP 639
  • Add strict-naming option for sdist and wheel targets

Fixed:

  • Project names are now stored in sdist and wheel target core metadata exactly as defined in pyproject.toml without normalization to allow control of how PyPI displays them

1.4.1 - 2022-07-04

Fixed:

  • Fix forced inclusion of important files like licenses for sdist targets when using the explicit selection options
  • Don't sort project URL metadata so that the rendered order on PyPI can be controlled

1.4.0 - 2022-07-03

Changed:

  • The packages option uses the new only-include option to provide targeted inclusion, since that is desired most of the time. You can retain the old behavior by using the include and sources options together.

Added:

  • Support PEP 561 type hinting
  • Add version build hook
  • Add only-include option
  • The editable version of wheel targets now respects the force-include option by default
  • The force-include option now supports path rewriting with the sources option
  • The wheel target shared-data and extra-metadata options now respect file selection options
  • The wheel target now auto-detects single module layouts
  • Improve performance by never entering directories that are guaranteed to be undesirable like __pycache__ rather than excluding individual files within
  • Update SPDX license information to version 3.17

Fixed:

  • Don't write empty entry points file for wheel targets if there are no entry points defined
  • Allow metadata hooks to set the version in all cases
  • Prevent duplicate file entries from inclusion when using the force-include option

1.3.1 - 2022-05-30

Fixed:

  • Better populate global variables for the code version source

1.3.0 - 2022-05-22

Removed:

  • Remove unused global args context string formatting field

Added:

  • Improve error messages for the env context string formatting field

Fixed:

  • Fix uri context string formatting modifier on Windows

1.2.0 - 2022-05-20

Added:

  • Allow context formatting for project.dependencies and project.optional-dependencies

1.1.0 - 2022-05-19

Added:

  • Add uri and real context string formatting modifiers for file system paths

1.0.0 - 2022-05-17

Changed:

  • Drop support for Python 2

Added:

  • Improve error messaging for invalid versions
  • Update project metadata to reflect support for Python 3.11

0.25.1 - 2022-06-14

Fixed:

  • Fix support for Windows on Python 2 by removing its support for symlinks

0.25.0 - 2022-05-15

Added:

  • Add skip-excluded-dirs build option
  • Allow build data to add additional project dependencies for wheel and sdist build targets
  • Add force_include_editable build data for the wheel build target
  • Add build_hooks build data
  • Add support for Mercurial's .hgignore files when using glob syntax
  • Update project metadata to reflect the adoption by PyPA

Fixed:

  • Properly use underscores for the name of force_include build data
  • No longer greedily skip excluded directories by default

0.24.0 - 2022-04-28

This is the initial public release of the Hatchling build system. Support for Python 2 will be dropped in version 1.

Last update: September 18, 2022
\ No newline at end of file diff --git a/dev/search/search_index.json b/dev/search/search_index.json index 4096980ce..0aba6e5d0 100644 --- a/dev/search/search_index.json +++ b/dev/search/search_index.json @@ -1 +1 @@ -{"config":{"indexing":"full","lang":["en"],"min_search_length":3,"prebuild_index":false,"separator":"[\\s\\-]+"},"docs":[{"location":"","text":"Hatch \u00b6 CI/CD Docs Package Meta Hatch is a modern, extensible Python project manager. Features \u00b6 Standardized build system with reproducible builds by default Robust environment management with support for custom scripts Easy publishing to PyPI or other sources Version management Configurable project generation with sane defaults Responsive CLI , ~2-3x faster than equivalent tools License \u00b6 Hatch is distributed under the terms of the MIT license. Navigation \u00b6 Documentation for specific MAJOR.MINOR versions can be chosen by using the dropdown on the top of every page. The dev version reflects changes that have not yet been released. Also, desktop readers can use special keyboard shortcuts: Keys Action , (comma) p Navigate to the \"previous\" page . (period) n Navigate to the \"next\" page / s Display the search modal","title":"About"},{"location":"#hatch","text":"CI/CD Docs Package Meta Hatch is a modern, extensible Python project manager.","title":"Hatch"},{"location":"#features","text":"Standardized build system with reproducible builds by default Robust environment management with support for custom scripts Easy publishing to PyPI or other sources Version management Configurable project generation with sane defaults Responsive CLI , ~2-3x faster than equivalent tools","title":"Features"},{"location":"#license","text":"Hatch is distributed under the terms of the MIT license.","title":"License"},{"location":"#navigation","text":"Documentation for specific MAJOR.MINOR versions can be chosen by using the dropdown on the top of every page. The dev version reflects changes that have not yet been released. Also, desktop readers can use special keyboard shortcuts: Keys Action , (comma) p Navigate to the \"previous\" page . (period) n Navigate to the \"next\" page / s Display the search modal","title":"Navigation"},{"location":"build/","text":"Builds \u00b6 Configuration \u00b6 Builds are configured using the tool.hatch.build table. Every target is defined by a section within tool.hatch.build.targets , for example: pyproject.toml hatch.toml [tool.hatch.build.targets.sdist] exclude = [ \"/.github\" , \"/docs\" , ] [tool.hatch.build.targets.wheel] packages = [ \"src/foo\" ] [build.targets.sdist] exclude = [ \"/.github\" , \"/docs\" , ] [build.targets.wheel] packages = [ \"src/foo\" ] Building \u00b6 Invoking the build command without any arguments will build all defined targets, each in an isolated environment: $ hatch build Setting up build environment [sdist] dist/hatch_demo-1rc0.tar.gz Setting up build environment [wheel] dist/hatch_demo-1rc0-py3-none-any.whl To only build specific targets, use the -t / --target option: $ hatch build -t wheel Setting up build environment [wheel] dist/hatch_demo-1rc0-py3-none-any.whl If the target supports multiple versions , you can specify the exact versions to build by appending a colon followed by the desired versions separated by commas: $ hatch -v build -t wheel:standard Setting up build environment ... [wheel] Building `wheel` version `standard` dist/hatch_demo-1rc0-py3-none-any.whl Packaging ecosystem \u00b6 Hatch complies with modern Python packaging specs and therefore your projects can be used by other tools with Hatch serving as just the build backend. So you could use tox as an alternative to Hatch's environment management , or cibuildwheel to distribute packages for every platform, and they both will transparently use Hatch without any extra modification.","title":"Builds"},{"location":"build/#builds","text":"","title":"Builds"},{"location":"build/#configuration","text":"Builds are configured using the tool.hatch.build table. Every target is defined by a section within tool.hatch.build.targets , for example: pyproject.toml hatch.toml [tool.hatch.build.targets.sdist] exclude = [ \"/.github\" , \"/docs\" , ] [tool.hatch.build.targets.wheel] packages = [ \"src/foo\" ] [build.targets.sdist] exclude = [ \"/.github\" , \"/docs\" , ] [build.targets.wheel] packages = [ \"src/foo\" ]","title":"Configuration"},{"location":"build/#building","text":"Invoking the build command without any arguments will build all defined targets, each in an isolated environment: $ hatch build Setting up build environment [sdist] dist/hatch_demo-1rc0.tar.gz Setting up build environment [wheel] dist/hatch_demo-1rc0-py3-none-any.whl To only build specific targets, use the -t / --target option: $ hatch build -t wheel Setting up build environment [wheel] dist/hatch_demo-1rc0-py3-none-any.whl If the target supports multiple versions , you can specify the exact versions to build by appending a colon followed by the desired versions separated by commas: $ hatch -v build -t wheel:standard Setting up build environment ... [wheel] Building `wheel` version `standard` dist/hatch_demo-1rc0-py3-none-any.whl","title":"Building"},{"location":"build/#packaging-ecosystem","text":"Hatch complies with modern Python packaging specs and therefore your projects can be used by other tools with Hatch serving as just the build backend. So you could use tox as an alternative to Hatch's environment management , or cibuildwheel to distribute packages for every platform, and they both will transparently use Hatch without any extra modification.","title":"Packaging ecosystem"},{"location":"environment/","text":"Environments \u00b6 Environments are designed to allow for isolated workspaces for testing, building documentation, or anything else projects need. Unless an environment is chosen explicitly , Hatch will use the default environment. Creation \u00b6 You can create environments by using the env create command. Let's enter the directory of the project we created in the setup phase : $ hatch env create Creating environment: default Installing project in development mode Syncing dependencies Tip You never need to manually create environments as spawning a shell or running commands within one will automatically trigger creation. Entering environments \u00b6 You can spawn a shell within an environment by using the shell command. $ hatch shell (hatch-demo) $ Now confirm the project has been installed: (hatch-demo) $ pip show hatch-demo Name: hatch-demo Version: 0.0.1 ... Finally, see where your environment's Python is located : (hatch-demo) $ python -c \"import sys;print(sys.executable)\" ... You can type exit to leave the environment. Command execution \u00b6 The run command allows you to execute commands in an environment as if you had already entered it. For example, running the following command will output the same path as before: hatch run python -c \"import sys;print(sys.executable)\" Scripts \u00b6 You can also run any scripts that have been defined. You'll notice that in the pyproject.toml file there are already scripts defined in the default environment. Try running the cov command, which invokes pytest with some flags for tracking coverage : hatch run cov All additional arguments are passed through to scripts, so for example if you wanted to see the version of pytest and which plugins are installed you could do: hatch run cov -VV Dependencies \u00b6 Hatch ensures that environments are always compatible with the currently defined project dependencies (if installed and in dev mode ) and environment dependencies . For example, add cowsay as a dependency then try to run it: $ hatch run cowsay \"Hello, world!\" Syncing dependencies _____________ | Hello, world! | ============= \\ \\ ^__^ (oo)\\_______ (__)\\ )\\/\\ ||----w | || || Selection \u00b6 You can select which environment to enter or run commands in by using the -e / --env root option or by setting the HATCH_ENV environment variable. The run command allows for more explicit selection by prepending : to commands. For example, if you had the following configuration: pyproject.toml hatch.toml [tool.hatch.envs.docs] dependencies = [ \"mkdocs\" ] [tool.hatch.envs.docs.scripts] build = \"mkdocs build --clean --strict\" serve = \"mkdocs serve --dev-addr localhost:8000\" [envs.docs] dependencies = [ \"mkdocs\" ] [envs.docs.scripts] build = \"mkdocs build --clean --strict\" serve = \"mkdocs serve --dev-addr localhost:8000\" you could then serve your documentation by running: hatch run docs:serve Tip If you've already entered an environment, commands will target it by default. Matrix \u00b6 Every environment can define its own set of matrices : pyproject.toml hatch.toml [tool.hatch.envs.test] dependencies = [ \"pytest\" ] [[tool.hatch.envs.test.matrix]] python = [ \"27\" , \"38\" ] version = [ \"42\" , \"3.14\" ] [[tool.hatch.envs.test.matrix]] python = [ \"38\" , \"39\" ] version = [ \"9000\" ] features = [ \"foo\" , \"bar\" ] [envs.test] dependencies = [ \"pytest\" ] [[envs.test.matrix]] python = [ \"27\" , \"38\" ] version = [ \"42\" , \"3.14\" ] [[envs.test.matrix]] python = [ \"38\" , \"39\" ] version = [ \"9000\" ] features = [ \"foo\" , \"bar\" ] Using the env show command would then display: $ hatch env show --ascii Standalone +---------+---------+ | Name | Type | +=========+=========+ | default | virtual | +---------+---------+ Matrices +------+---------+--------------------+--------------+ | Name | Type | Envs | Dependencies | +======+=========+====================+==============+ | test | virtual | test.py27-42 | pytest | | | | test.py27-3.14 | | | | | test.py38-42 | | | | | test.py38-3.14 | | | | | test.py38-9000-foo | | | | | test.py38-9000-bar | | | | | test.py39-9000-foo | | | | | test.py39-9000-bar | | +------+---------+--------------------+--------------+ Removal \u00b6 You can remove a single environment or environment matrix by using the env remove command or all of a project's environments by using the env prune command.","title":"Environments"},{"location":"environment/#environments","text":"Environments are designed to allow for isolated workspaces for testing, building documentation, or anything else projects need. Unless an environment is chosen explicitly , Hatch will use the default environment.","title":"Environments"},{"location":"environment/#creation","text":"You can create environments by using the env create command. Let's enter the directory of the project we created in the setup phase : $ hatch env create Creating environment: default Installing project in development mode Syncing dependencies Tip You never need to manually create environments as spawning a shell or running commands within one will automatically trigger creation.","title":"Creation"},{"location":"environment/#entering-environments","text":"You can spawn a shell within an environment by using the shell command. $ hatch shell (hatch-demo) $ Now confirm the project has been installed: (hatch-demo) $ pip show hatch-demo Name: hatch-demo Version: 0.0.1 ... Finally, see where your environment's Python is located : (hatch-demo) $ python -c \"import sys;print(sys.executable)\" ... You can type exit to leave the environment.","title":"Entering environments"},{"location":"environment/#command-execution","text":"The run command allows you to execute commands in an environment as if you had already entered it. For example, running the following command will output the same path as before: hatch run python -c \"import sys;print(sys.executable)\"","title":"Command execution"},{"location":"environment/#scripts","text":"You can also run any scripts that have been defined. You'll notice that in the pyproject.toml file there are already scripts defined in the default environment. Try running the cov command, which invokes pytest with some flags for tracking coverage : hatch run cov All additional arguments are passed through to scripts, so for example if you wanted to see the version of pytest and which plugins are installed you could do: hatch run cov -VV","title":"Scripts"},{"location":"environment/#dependencies","text":"Hatch ensures that environments are always compatible with the currently defined project dependencies (if installed and in dev mode ) and environment dependencies . For example, add cowsay as a dependency then try to run it: $ hatch run cowsay \"Hello, world!\" Syncing dependencies _____________ | Hello, world! | ============= \\ \\ ^__^ (oo)\\_______ (__)\\ )\\/\\ ||----w | || ||","title":"Dependencies"},{"location":"environment/#selection","text":"You can select which environment to enter or run commands in by using the -e / --env root option or by setting the HATCH_ENV environment variable. The run command allows for more explicit selection by prepending : to commands. For example, if you had the following configuration: pyproject.toml hatch.toml [tool.hatch.envs.docs] dependencies = [ \"mkdocs\" ] [tool.hatch.envs.docs.scripts] build = \"mkdocs build --clean --strict\" serve = \"mkdocs serve --dev-addr localhost:8000\" [envs.docs] dependencies = [ \"mkdocs\" ] [envs.docs.scripts] build = \"mkdocs build --clean --strict\" serve = \"mkdocs serve --dev-addr localhost:8000\" you could then serve your documentation by running: hatch run docs:serve Tip If you've already entered an environment, commands will target it by default.","title":"Selection"},{"location":"environment/#matrix","text":"Every environment can define its own set of matrices : pyproject.toml hatch.toml [tool.hatch.envs.test] dependencies = [ \"pytest\" ] [[tool.hatch.envs.test.matrix]] python = [ \"27\" , \"38\" ] version = [ \"42\" , \"3.14\" ] [[tool.hatch.envs.test.matrix]] python = [ \"38\" , \"39\" ] version = [ \"9000\" ] features = [ \"foo\" , \"bar\" ] [envs.test] dependencies = [ \"pytest\" ] [[envs.test.matrix]] python = [ \"27\" , \"38\" ] version = [ \"42\" , \"3.14\" ] [[envs.test.matrix]] python = [ \"38\" , \"39\" ] version = [ \"9000\" ] features = [ \"foo\" , \"bar\" ] Using the env show command would then display: $ hatch env show --ascii Standalone +---------+---------+ | Name | Type | +=========+=========+ | default | virtual | +---------+---------+ Matrices +------+---------+--------------------+--------------+ | Name | Type | Envs | Dependencies | +======+=========+====================+==============+ | test | virtual | test.py27-42 | pytest | | | | test.py27-3.14 | | | | | test.py38-42 | | | | | test.py38-3.14 | | | | | test.py38-9000-foo | | | | | test.py38-9000-bar | | | | | test.py39-9000-foo | | | | | test.py39-9000-bar | | +------+---------+--------------------+--------------+","title":"Matrix"},{"location":"environment/#removal","text":"You can remove a single environment or environment matrix by using the env remove command or all of a project's environments by using the env prune command.","title":"Removal"},{"location":"history/","text":"History \u00b6 All notable changes to this project will be documented in this file. The format is based on Keep a Changelog , and this project adheres to Semantic Versioning . Hatch \u00b6 Unreleased \u00b6 Changed: The run_shell_command environment interface method now accepts arbitrary subprocess.Popen keyword arguments. This is not strictly breaking, but will be utilized in upcoming features. The internal directory structure for storing virtual environments is now more nested. This is not breaking, but any local environments will be created anew. Added: Add project command group to view details about the project like PEP 621 metadata Build environments for the virtual environment type are now cached for improved performance Add build_environment_exists method to the environment interface for implementations that cache the build environment Support Bash on Windows for the shell command The setuptools migration script no longer modifies the formatting of existing pyproject.toml configuration Bump the minimum supported version of Hatchling to 1.9.0 Fixed: Environments now respect dynamically defined project dependencies Handle more edge cases in the setuptools migration script Depend on packaging explicitly rather than relying on it being a transitive dependency of Hatchling 1.5.0 - 2022-08-28 \u00b6 Added: The index publisher now recognizes repository-specific options Add the --ignore-compat flag to the env run command Setting the HATCH_PYTHON environment variable to self will now force the use of the Python executable Hatch is running on for virtual environment creation Fixed: Fix the --force-continue flag of the env run command Handle more edge cases in the setuptools migration script 1.4.2 - 2022-08-16 \u00b6 Fixed: Fix check for updating static versions with the version command when metadata hooks are in use 1.4.1 - 2022-08-13 \u00b6 Fixed: Fix non-detached inheritance disabling for environments 1.4.0 - 2022-08-06 \u00b6 Added: The default Python for virtual environments now checks PATH before using the one Hatch is running on Values for environment env-vars now support context formatting Add name override for environments to allow for regular expression matching The index publisher now better supports non- PyPI indices Add certificate options to the index publisher Display waiting text when checking dependencies and removing environments Display help text the first time the shell command is executed Update project templates with Python 3.11 and the latest versions of various GitHub Actions Add support for Almquist ( ash ) shells Add hyperlink as a dependency for better handling of package index URLs Bump the minimum supported version of virtualenv to 20.16.2 Bump the minimum supported version of tomlkit to 0.11.1 Fixed: Acknowledge extra-dependencies for the env show command Fix locating executables within virtual environments on Debian Fix managing the terminal size inside the shell command Fix default code coverage file omission for the src-layout project template option 1.3.1 - 2022-07-11 \u00b6 Fixed: Support -h / --help flag for the run command 1.3.0 - 2022-07-10 \u00b6 Changed: Rename the default publishing plugin from pypi to the more generic index Added: Support the absence of pyproject.toml files, as is the case for apps and non-Python projects Hide scripts that start with an underscore for the env show command by default Ignoring the exit codes of commands by prefixing with hyphens now works with entire named scripts Add a way to require confirmation for publishing Add --force-continue flag to the env run command Make tracebacks colorful and less verbose When shell configuration has not been defined, attempt to use the current shell based on parent processes before resorting to the defaults The shell name pwsh is now an alias for powershell Remove atomicwrites dependency Relax constraint on userpath dependency Bump the minimum supported version of Hatchling to 1.4.1 Fixed: Keep environments in sync with the dependencies of the selected features Use utf-8 for all files generated for new projects Escape special characters Git may return in the user name when writing generated files for new projects Normalize the package name to lowercase in setuptools migration script Fix parsing of source distributions during publishing 1.2.1 - 2022-05-30 \u00b6 Fixed: Fix handling of top level data_files in setuptools migration script 1.2.0 - 2022-05-22 \u00b6 Changed: The enter_shell environment plugin method now accepts an additional args parameter Added: Allow context string formatting for environment dependencies Add environment context string formatting fields env_name , env_type , matrix , verbosity , and args Support overriding the default arguments used to spawn shells on non-Windows systems Bump the minimum supported version of Hatchling to 1.3.0 Fixed: Improve setuptools migration script 1.1.2 - 2022-05-20 \u00b6 Fixed: Bump the minimum supported version of Hatchling to 1.2.0 Update project metadata to reflect support for Python 3.11 1.1.1 - 2022-05-12 \u00b6 Fixed: Fix setuptools migration script for non-Windows systems 1.1.0 - 2022-05-12 \u00b6 Changed: In order to simplify the implementation of command execution for environment plugins, the run_shell_commands method has been replaced by the singular run_shell_command . A new command_context method has been added to more easily satisfy complex use cases. The finalize_command environment plugin method has been removed in favor of the newly introduced context formatting functionality. Added: Add context formatting functionality i.e. the ability to insert values into configuration like environment variables and command line arguments Any verbosity for command execution will now always display headers, even for single environments Every executed command is now displayed when running multiple commands or when verbosity is enabled Similar to make , ignore the exit code of executed commands that start with - (a hyphen) Add ability for the --init flag of the new command to automatically migrate setuptools configuration Update project metadata to reflect the adoption by PyPA and production stability 1.0.0 - 2022-04-28 \u00b6 This is the first stable release of Hatch v1, a complete rewrite. Enjoy! Hatchling \u00b6 Unreleased \u00b6 Fixed: Improve tracking of dynamic metadata Fix core metadata for entries in project.optional-dependencies that use direct references 1.9.0 - 2022-09-09 \u00b6 Changed: File pattern matching now more closely resembles Git's behavior Added: Implement a minimal version of prepare_metadata_for_build_wheel and prepare_metadata_for_build_editable for non-frontend tools that only need to inspect a project's metadata Add metadata command to view PEP 621 project metadata Improve error messages for SPDX license errors Retroactively support License-File for core metadata starting at version 2.1 Bump the minimum supported version of pathspec to 0.10.1 Fixed: Allow the valid non-SPDX license values LicenseRef-Public-Domain and LicenseRef-Proprietary Show the help text of the CLI when no subcommand is selected 1.8.1 - 2022-08-25 \u00b6 Fixed: Fix default file inclusion for wheel build targets when both the project name and package directory name are not normalized 1.8.0 - 2022-08-16 \u00b6 Added: Add get_known_classifiers method to metadata hooks Fixed: Fix check for updating static versions with the version command when metadata hooks are in use 1.7.1 - 2022-08-13 \u00b6 Fixed: Fix the value of the relative_path attribute of included files, that some build plugins may use, when selecting explicit paths 1.7.0 - 2022-08-12 \u00b6 Added: Add require-runtime-features option for builders and build hooks Check for unknown trove classifiers Update SPDX license information to version 3.18 Fixed: Add better error message for wheel target dev mode installations that define path rewrites with the sources option Note the allow-direct-references option in the relevant error messages 1.6.0 - 2022-07-23 \u00b6 Changed: When no build targets are specified on the command line, now default to sdist and wheel targets rather than what happens to be defined in config The code version source now only supports files with known extensions Global build hooks now run before target-specific build hooks to better match expected behavior Added: The code version source now supports loading extension modules Add search-paths option for the code version source Fixed: Fix removing sources using an empty string value in the mapping The strict-naming option now also applies to the metadata directory of wheel targets 1.5.0 - 2022-07-11 \u00b6 Added: Support the final draft of PEP 639 Add strict-naming option for sdist and wheel targets Fixed: Project names are now stored in sdist and wheel target core metadata exactly as defined in pyproject.toml without normalization to allow control of how PyPI displays them 1.4.1 - 2022-07-04 \u00b6 Fixed: Fix forced inclusion of important files like licenses for sdist targets when using the explicit selection options Don't sort project URL metadata so that the rendered order on PyPI can be controlled 1.4.0 - 2022-07-03 \u00b6 Changed: The packages option uses the new only-include option to provide targeted inclusion, since that is desired most of the time. You can retain the old behavior by using the include and sources options together. Added: Support PEP 561 type hinting Add version build hook Add only-include option The editable version of wheel targets now respects the force-include option by default The force-include option now supports path rewriting with the sources option The wheel target shared-data and extra-metadata options now respect file selection options The wheel target now auto-detects single module layouts Improve performance by never entering directories that are guaranteed to be undesirable like __pycache__ rather than excluding individual files within Update SPDX license information to version 3.17 Fixed: Don't write empty entry points file for wheel targets if there are no entry points defined Allow metadata hooks to set the version in all cases Prevent duplicate file entries from inclusion when using the force-include option 1.3.1 - 2022-05-30 \u00b6 Fixed: Better populate global variables for the code version source 1.3.0 - 2022-05-22 \u00b6 Removed: Remove unused global args context string formatting field Added: Improve error messages for the env context string formatting field Fixed: Fix uri context string formatting modifier on Windows 1.2.0 - 2022-05-20 \u00b6 Added: Allow context formatting for project.dependencies and project.optional-dependencies 1.1.0 - 2022-05-19 \u00b6 Added: Add uri and real context string formatting modifiers for file system paths 1.0.0 - 2022-05-17 \u00b6 Changed: Drop support for Python 2 Added: Improve error messaging for invalid versions Update project metadata to reflect support for Python 3.11 0.25.1 - 2022-06-14 \u00b6 Fixed: Fix support for Windows on Python 2 by removing its support for symlinks 0.25.0 - 2022-05-15 \u00b6 Added: Add skip-excluded-dirs build option Allow build data to add additional project dependencies for wheel and sdist build targets Add force_include_editable build data for the wheel build target Add build_hooks build data Add support for Mercurial's .hgignore files when using glob syntax Update project metadata to reflect the adoption by PyPA Fixed: Properly use underscores for the name of force_include build data No longer greedily skip excluded directories by default 0.24.0 - 2022-04-28 \u00b6 This is the initial public release of the Hatchling build system. Support for Python 2 will be dropped in version 1.","title":"History"},{"location":"history/#history","text":"All notable changes to this project will be documented in this file. The format is based on Keep a Changelog , and this project adheres to Semantic Versioning .","title":"History"},{"location":"history/#hatch","text":"","title":"Hatch"},{"location":"history/#unreleased","text":"Changed: The run_shell_command environment interface method now accepts arbitrary subprocess.Popen keyword arguments. This is not strictly breaking, but will be utilized in upcoming features. The internal directory structure for storing virtual environments is now more nested. This is not breaking, but any local environments will be created anew. Added: Add project command group to view details about the project like PEP 621 metadata Build environments for the virtual environment type are now cached for improved performance Add build_environment_exists method to the environment interface for implementations that cache the build environment Support Bash on Windows for the shell command The setuptools migration script no longer modifies the formatting of existing pyproject.toml configuration Bump the minimum supported version of Hatchling to 1.9.0 Fixed: Environments now respect dynamically defined project dependencies Handle more edge cases in the setuptools migration script Depend on packaging explicitly rather than relying on it being a transitive dependency of Hatchling","title":"Unreleased"},{"location":"history/#hatch-v1.5.0","text":"Added: The index publisher now recognizes repository-specific options Add the --ignore-compat flag to the env run command Setting the HATCH_PYTHON environment variable to self will now force the use of the Python executable Hatch is running on for virtual environment creation Fixed: Fix the --force-continue flag of the env run command Handle more edge cases in the setuptools migration script","title":"1.5.0 - 2022-08-28"},{"location":"history/#hatch-v1.4.2","text":"Fixed: Fix check for updating static versions with the version command when metadata hooks are in use","title":"1.4.2 - 2022-08-16"},{"location":"history/#hatch-v1.4.1","text":"Fixed: Fix non-detached inheritance disabling for environments","title":"1.4.1 - 2022-08-13"},{"location":"history/#hatch-v1.4.0","text":"Added: The default Python for virtual environments now checks PATH before using the one Hatch is running on Values for environment env-vars now support context formatting Add name override for environments to allow for regular expression matching The index publisher now better supports non- PyPI indices Add certificate options to the index publisher Display waiting text when checking dependencies and removing environments Display help text the first time the shell command is executed Update project templates with Python 3.11 and the latest versions of various GitHub Actions Add support for Almquist ( ash ) shells Add hyperlink as a dependency for better handling of package index URLs Bump the minimum supported version of virtualenv to 20.16.2 Bump the minimum supported version of tomlkit to 0.11.1 Fixed: Acknowledge extra-dependencies for the env show command Fix locating executables within virtual environments on Debian Fix managing the terminal size inside the shell command Fix default code coverage file omission for the src-layout project template option","title":"1.4.0 - 2022-08-06"},{"location":"history/#hatch-v1.3.1","text":"Fixed: Support -h / --help flag for the run command","title":"1.3.1 - 2022-07-11"},{"location":"history/#hatch-v1.3.0","text":"Changed: Rename the default publishing plugin from pypi to the more generic index Added: Support the absence of pyproject.toml files, as is the case for apps and non-Python projects Hide scripts that start with an underscore for the env show command by default Ignoring the exit codes of commands by prefixing with hyphens now works with entire named scripts Add a way to require confirmation for publishing Add --force-continue flag to the env run command Make tracebacks colorful and less verbose When shell configuration has not been defined, attempt to use the current shell based on parent processes before resorting to the defaults The shell name pwsh is now an alias for powershell Remove atomicwrites dependency Relax constraint on userpath dependency Bump the minimum supported version of Hatchling to 1.4.1 Fixed: Keep environments in sync with the dependencies of the selected features Use utf-8 for all files generated for new projects Escape special characters Git may return in the user name when writing generated files for new projects Normalize the package name to lowercase in setuptools migration script Fix parsing of source distributions during publishing","title":"1.3.0 - 2022-07-10"},{"location":"history/#hatch-v1.2.1","text":"Fixed: Fix handling of top level data_files in setuptools migration script","title":"1.2.1 - 2022-05-30"},{"location":"history/#hatch-v1.2.0","text":"Changed: The enter_shell environment plugin method now accepts an additional args parameter Added: Allow context string formatting for environment dependencies Add environment context string formatting fields env_name , env_type , matrix , verbosity , and args Support overriding the default arguments used to spawn shells on non-Windows systems Bump the minimum supported version of Hatchling to 1.3.0 Fixed: Improve setuptools migration script","title":"1.2.0 - 2022-05-22"},{"location":"history/#hatch-v1.1.2","text":"Fixed: Bump the minimum supported version of Hatchling to 1.2.0 Update project metadata to reflect support for Python 3.11","title":"1.1.2 - 2022-05-20"},{"location":"history/#hatch-v1.1.1","text":"Fixed: Fix setuptools migration script for non-Windows systems","title":"1.1.1 - 2022-05-12"},{"location":"history/#hatch-v1.1.0","text":"Changed: In order to simplify the implementation of command execution for environment plugins, the run_shell_commands method has been replaced by the singular run_shell_command . A new command_context method has been added to more easily satisfy complex use cases. The finalize_command environment plugin method has been removed in favor of the newly introduced context formatting functionality. Added: Add context formatting functionality i.e. the ability to insert values into configuration like environment variables and command line arguments Any verbosity for command execution will now always display headers, even for single environments Every executed command is now displayed when running multiple commands or when verbosity is enabled Similar to make , ignore the exit code of executed commands that start with - (a hyphen) Add ability for the --init flag of the new command to automatically migrate setuptools configuration Update project metadata to reflect the adoption by PyPA and production stability","title":"1.1.0 - 2022-05-12"},{"location":"history/#hatch-v1.0.0","text":"This is the first stable release of Hatch v1, a complete rewrite. Enjoy!","title":"1.0.0 - 2022-04-28"},{"location":"history/#hatchling","text":"","title":"Hatchling"},{"location":"history/#unreleased_1","text":"Fixed: Improve tracking of dynamic metadata Fix core metadata for entries in project.optional-dependencies that use direct references","title":"Unreleased"},{"location":"history/#hatchling-v1.9.0","text":"Changed: File pattern matching now more closely resembles Git's behavior Added: Implement a minimal version of prepare_metadata_for_build_wheel and prepare_metadata_for_build_editable for non-frontend tools that only need to inspect a project's metadata Add metadata command to view PEP 621 project metadata Improve error messages for SPDX license errors Retroactively support License-File for core metadata starting at version 2.1 Bump the minimum supported version of pathspec to 0.10.1 Fixed: Allow the valid non-SPDX license values LicenseRef-Public-Domain and LicenseRef-Proprietary Show the help text of the CLI when no subcommand is selected","title":"1.9.0 - 2022-09-09"},{"location":"history/#hatchling-v1.8.1","text":"Fixed: Fix default file inclusion for wheel build targets when both the project name and package directory name are not normalized","title":"1.8.1 - 2022-08-25"},{"location":"history/#hatchling-v1.8.0","text":"Added: Add get_known_classifiers method to metadata hooks Fixed: Fix check for updating static versions with the version command when metadata hooks are in use","title":"1.8.0 - 2022-08-16"},{"location":"history/#hatchling-v1.7.1","text":"Fixed: Fix the value of the relative_path attribute of included files, that some build plugins may use, when selecting explicit paths","title":"1.7.1 - 2022-08-13"},{"location":"history/#hatchling-v1.7.0","text":"Added: Add require-runtime-features option for builders and build hooks Check for unknown trove classifiers Update SPDX license information to version 3.18 Fixed: Add better error message for wheel target dev mode installations that define path rewrites with the sources option Note the allow-direct-references option in the relevant error messages","title":"1.7.0 - 2022-08-12"},{"location":"history/#hatchling-v1.6.0","text":"Changed: When no build targets are specified on the command line, now default to sdist and wheel targets rather than what happens to be defined in config The code version source now only supports files with known extensions Global build hooks now run before target-specific build hooks to better match expected behavior Added: The code version source now supports loading extension modules Add search-paths option for the code version source Fixed: Fix removing sources using an empty string value in the mapping The strict-naming option now also applies to the metadata directory of wheel targets","title":"1.6.0 - 2022-07-23"},{"location":"history/#hatchling-v1.5.0","text":"Added: Support the final draft of PEP 639 Add strict-naming option for sdist and wheel targets Fixed: Project names are now stored in sdist and wheel target core metadata exactly as defined in pyproject.toml without normalization to allow control of how PyPI displays them","title":"1.5.0 - 2022-07-11"},{"location":"history/#hatchling-v1.4.1","text":"Fixed: Fix forced inclusion of important files like licenses for sdist targets when using the explicit selection options Don't sort project URL metadata so that the rendered order on PyPI can be controlled","title":"1.4.1 - 2022-07-04"},{"location":"history/#hatchling-v1.4.0","text":"Changed: The packages option uses the new only-include option to provide targeted inclusion, since that is desired most of the time. You can retain the old behavior by using the include and sources options together. Added: Support PEP 561 type hinting Add version build hook Add only-include option The editable version of wheel targets now respects the force-include option by default The force-include option now supports path rewriting with the sources option The wheel target shared-data and extra-metadata options now respect file selection options The wheel target now auto-detects single module layouts Improve performance by never entering directories that are guaranteed to be undesirable like __pycache__ rather than excluding individual files within Update SPDX license information to version 3.17 Fixed: Don't write empty entry points file for wheel targets if there are no entry points defined Allow metadata hooks to set the version in all cases Prevent duplicate file entries from inclusion when using the force-include option","title":"1.4.0 - 2022-07-03"},{"location":"history/#hatchling-v1.3.1","text":"Fixed: Better populate global variables for the code version source","title":"1.3.1 - 2022-05-30"},{"location":"history/#hatchling-v1.3.0","text":"Removed: Remove unused global args context string formatting field Added: Improve error messages for the env context string formatting field Fixed: Fix uri context string formatting modifier on Windows","title":"1.3.0 - 2022-05-22"},{"location":"history/#hatchling-v1.2.0","text":"Added: Allow context formatting for project.dependencies and project.optional-dependencies","title":"1.2.0 - 2022-05-20"},{"location":"history/#hatchling-v1.1.0","text":"Added: Add uri and real context string formatting modifiers for file system paths","title":"1.1.0 - 2022-05-19"},{"location":"history/#hatchling-v1.0.0","text":"Changed: Drop support for Python 2 Added: Improve error messaging for invalid versions Update project metadata to reflect support for Python 3.11","title":"1.0.0 - 2022-05-17"},{"location":"history/#hatchling-v0.25.1","text":"Fixed: Fix support for Windows on Python 2 by removing its support for symlinks","title":"0.25.1 - 2022-06-14"},{"location":"history/#hatchling-v0.25.0","text":"Added: Add skip-excluded-dirs build option Allow build data to add additional project dependencies for wheel and sdist build targets Add force_include_editable build data for the wheel build target Add build_hooks build data Add support for Mercurial's .hgignore files when using glob syntax Update project metadata to reflect the adoption by PyPA Fixed: Properly use underscores for the name of force_include build data No longer greedily skip excluded directories by default","title":"0.25.0 - 2022-05-15"},{"location":"history/#hatchling-v0.24.0","text":"This is the initial public release of the Hatchling build system. Support for Python 2 will be dropped in version 1.","title":"0.24.0 - 2022-04-28"},{"location":"install/","text":"Installation \u00b6 pip \u00b6 Hatch is available on PyPI and can be installed with pip . pip install hatch Warning This method modifies the Python environment in which you choose to install. Consider instead using pipx to avoid dependency conflicts. pipx \u00b6 pipx allows for the global installation of Python applications in isolated environments. pipx install hatch Homebrew \u00b6 See the formula for more details. brew install hatch Conda \u00b6 See the feedstock for more details. conda install -c conda-forge hatch or with mamba : mamba install hatch Warning This method modifies the Conda environment in which you choose to install. Consider instead using pipx or condax to avoid dependency conflicts. MacPorts \u00b6 See the port for more details. sudo port install hatch Fedora \u00b6 The minimum supported version is 37, currently in development as Rawhide . sudo dnf install hatch Void Linux \u00b6 xbps-install hatch Build system availability \u00b6 Hatchling is Hatch's build backend which you will never need to install manually. See its changelog for version information.","title":"Installation"},{"location":"install/#installation","text":"","title":"Installation"},{"location":"install/#pip","text":"Hatch is available on PyPI and can be installed with pip . pip install hatch Warning This method modifies the Python environment in which you choose to install. Consider instead using pipx to avoid dependency conflicts.","title":"pip"},{"location":"install/#pipx","text":"pipx allows for the global installation of Python applications in isolated environments. pipx install hatch","title":"pipx"},{"location":"install/#homebrew","text":"See the formula for more details. brew install hatch","title":"Homebrew"},{"location":"install/#conda","text":"See the feedstock for more details. conda install -c conda-forge hatch or with mamba : mamba install hatch Warning This method modifies the Conda environment in which you choose to install. Consider instead using pipx or condax to avoid dependency conflicts.","title":"Conda"},{"location":"install/#macports","text":"See the port for more details. sudo port install hatch","title":"MacPorts"},{"location":"install/#fedora","text":"The minimum supported version is 37, currently in development as Rawhide . sudo dnf install hatch","title":"Fedora"},{"location":"install/#void-linux","text":"xbps-install hatch","title":"Void Linux"},{"location":"install/#build-system-availability","text":"Hatchling is Hatch's build backend which you will never need to install manually. See its changelog for version information.","title":"Build system availability"},{"location":"intro/","text":"Introduction \u00b6 Setup \u00b6 Projects can be setup for use by Hatch using the new command. New project \u00b6 Let's say you want to create a project named Hatch Demo . You would run: hatch new \"Hatch Demo\" This would create the following structure in your current working directory: hatch-demo \u251c\u2500\u2500 hatch_demo \u2502 \u251c\u2500\u2500 __about__.py \u2502 \u2514\u2500\u2500 __init__.py \u251c\u2500\u2500 tests \u2502 \u2514\u2500\u2500 __init__.py \u251c\u2500\u2500 LICENSE.txt \u251c\u2500\u2500 README.md \u2514\u2500\u2500 pyproject.toml Tip There are many ways to customize project generation. Existing project \u00b6 To initialize an existing project, enter the directory containing the project and run the following: hatch new --init If your project has a setup.py file the command will automatically migrate setuptools configuration for you. Otherwise, this will interactively guide you through the setup process. Project metadata \u00b6 Next you'll want to define more of your project's metadata located in the pyproject.toml file. You can specify things like its license , the supported versions of Python , and URLs referring to various parts of your project, like documentation. Dependencies \u00b6 The last step of the setup process is to define any dependencies that you'd like your project to begin with. Configuration \u00b6 All project-specific configuration recognized by Hatch can be defined in either the pyproject.toml file, or a file named hatch.toml where options are not contained within the tool.hatch table: pyproject.toml hatch.toml [tool.hatch] option = \"...\" [tool.hatch.table1] option = \"...\" [tool.hatch.table2] option = \"...\" option = \"...\" [table1] option = \"...\" [table2] option = \"...\" Top level keys in the latter file take precedence when defined in both. Tip If you want to make your file more compact, you can use dotted keys , turning the above example into: pyproject.toml hatch.toml [tool.hatch] option = \"...\" table1 . option = \"...\" table2 . option = \"...\" option = \"...\" table1 . option = \"...\" table2 . option = \"...\"","title":"Introduction"},{"location":"intro/#introduction","text":"","title":"Introduction"},{"location":"intro/#setup","text":"Projects can be setup for use by Hatch using the new command.","title":"Setup"},{"location":"intro/#new-project","text":"Let's say you want to create a project named Hatch Demo . You would run: hatch new \"Hatch Demo\" This would create the following structure in your current working directory: hatch-demo \u251c\u2500\u2500 hatch_demo \u2502 \u251c\u2500\u2500 __about__.py \u2502 \u2514\u2500\u2500 __init__.py \u251c\u2500\u2500 tests \u2502 \u2514\u2500\u2500 __init__.py \u251c\u2500\u2500 LICENSE.txt \u251c\u2500\u2500 README.md \u2514\u2500\u2500 pyproject.toml Tip There are many ways to customize project generation.","title":"New project"},{"location":"intro/#existing-project","text":"To initialize an existing project, enter the directory containing the project and run the following: hatch new --init If your project has a setup.py file the command will automatically migrate setuptools configuration for you. Otherwise, this will interactively guide you through the setup process.","title":"Existing project"},{"location":"intro/#project-metadata","text":"Next you'll want to define more of your project's metadata located in the pyproject.toml file. You can specify things like its license , the supported versions of Python , and URLs referring to various parts of your project, like documentation.","title":"Project metadata"},{"location":"intro/#dependencies","text":"The last step of the setup process is to define any dependencies that you'd like your project to begin with.","title":"Dependencies"},{"location":"intro/#configuration","text":"All project-specific configuration recognized by Hatch can be defined in either the pyproject.toml file, or a file named hatch.toml where options are not contained within the tool.hatch table: pyproject.toml hatch.toml [tool.hatch] option = \"...\" [tool.hatch.table1] option = \"...\" [tool.hatch.table2] option = \"...\" option = \"...\" [table1] option = \"...\" [table2] option = \"...\" Top level keys in the latter file take precedence when defined in both. Tip If you want to make your file more compact, you can use dotted keys , turning the above example into: pyproject.toml hatch.toml [tool.hatch] option = \"...\" table1 . option = \"...\" table2 . option = \"...\" option = \"...\" table1 . option = \"...\" table2 . option = \"...\"","title":"Configuration"},{"location":"next-steps/","text":"Next steps \u00b6 Learn more \u00b6 At this point you should have a basic understanding of how to use Hatch. Now you may want to check out advanced configuration for environments or builds , set up your preferred shell , or read more about Hatch's CLI . After that, check out the Hatch Showcase project to see examples of what is possible. Finally, if you see a need, feel free to write a plugin for extended functionality. Community \u00b6 For any projects using Hatch, you may add its official badge somewhere prominent like the README. Markdown reStructuredText [ ![Hatch project ]( https://img.shields.io/badge/%F0%9F%A5%9A-Hatch-4051b5.svg )](https://github.com/pypa/hatch) .. image :: https://img.shields.io/badge/%F0%9F%A5%9A-Hatch-4051b5.svg :alt: Hatch project :target: https://github.com/pypa/hatch","title":"Next steps"},{"location":"next-steps/#next-steps","text":"","title":"Next steps"},{"location":"next-steps/#learn-more","text":"At this point you should have a basic understanding of how to use Hatch. Now you may want to check out advanced configuration for environments or builds , set up your preferred shell , or read more about Hatch's CLI . After that, check out the Hatch Showcase project to see examples of what is possible. Finally, if you see a need, feel free to write a plugin for extended functionality.","title":"Learn more"},{"location":"next-steps/#community","text":"For any projects using Hatch, you may add its official badge somewhere prominent like the README. Markdown reStructuredText [ ![Hatch project ]( https://img.shields.io/badge/%F0%9F%A5%9A-Hatch-4051b5.svg )](https://github.com/pypa/hatch) .. image :: https://img.shields.io/badge/%F0%9F%A5%9A-Hatch-4051b5.svg :alt: Hatch project :target: https://github.com/pypa/hatch","title":"Community"},{"location":"publish/","text":"Publishing \u00b6 After your project is built , you can distribute it using the publish command. The -p / --publisher option controls which publisher to use, with the default being index . Artifact selection \u00b6 By default, the dist directory located at the root of your project will be used: $ hatch publish dist/hatch_demo-1rc0-py3-none-any.whl ... success dist/hatch_demo-1rc0.tar.gz ... success [hatch-demo] https://pypi.org/project/hatch-demo/1rc0/ You can instead pass specific paths as arguments: hatch publish /path/to/artifacts foo-1.tar.gz Only files ending with .whl or .tar.gz will be published. Repository \u00b6 You can select the repository with which to upload using the -r / --repo option or by setting the HATCH_INDEX_REPO environment variable. Rather than specifying the full URL of a repository, you can use a named repository from a publish.index.repos table defined in Hatch's config file : config.toml [publish.index.repos.private] url = \"...\" ... The following repository names are reserved by Hatch and cannot be overridden: Name Repository main https://upload.pypi.org/legacy/ test https://test.pypi.org/legacy/ The main repository is used by default. Authentication \u00b6 The first time you publish to a repository you need to authenticate using the -u / --user (environment variable HATCH_INDEX_USER ) and -a / --auth (environment variable HATCH_INDEX_AUTH ) options. You will be prompted if either option is not provided. The user that most recently published to the chosen repository is cached , with their credentials saved to the system keyring , so that they will no longer need to provide authentication information. For automated releasing to PyPI , it is recommended that you use per-project API tokens . Confirmation \u00b6 You can require a confirmation prompt or use of the -y / --yes flag by setting publishers' disable option to true in either Hatch's config file or project-specific configuration (which takes precedence): config.toml pyproject.toml hatch.toml [publish.index] disable = true [tool.hatch.publish.index] disable = true [publish.index] disable = true","title":"Publishing"},{"location":"publish/#publishing","text":"After your project is built , you can distribute it using the publish command. The -p / --publisher option controls which publisher to use, with the default being index .","title":"Publishing"},{"location":"publish/#artifact-selection","text":"By default, the dist directory located at the root of your project will be used: $ hatch publish dist/hatch_demo-1rc0-py3-none-any.whl ... success dist/hatch_demo-1rc0.tar.gz ... success [hatch-demo] https://pypi.org/project/hatch-demo/1rc0/ You can instead pass specific paths as arguments: hatch publish /path/to/artifacts foo-1.tar.gz Only files ending with .whl or .tar.gz will be published.","title":"Artifact selection"},{"location":"publish/#repository","text":"You can select the repository with which to upload using the -r / --repo option or by setting the HATCH_INDEX_REPO environment variable. Rather than specifying the full URL of a repository, you can use a named repository from a publish.index.repos table defined in Hatch's config file : config.toml [publish.index.repos.private] url = \"...\" ... The following repository names are reserved by Hatch and cannot be overridden: Name Repository main https://upload.pypi.org/legacy/ test https://test.pypi.org/legacy/ The main repository is used by default.","title":"Repository"},{"location":"publish/#authentication","text":"The first time you publish to a repository you need to authenticate using the -u / --user (environment variable HATCH_INDEX_USER ) and -a / --auth (environment variable HATCH_INDEX_AUTH ) options. You will be prompted if either option is not provided. The user that most recently published to the chosen repository is cached , with their credentials saved to the system keyring , so that they will no longer need to provide authentication information. For automated releasing to PyPI , it is recommended that you use per-project API tokens .","title":"Authentication"},{"location":"publish/#confirmation","text":"You can require a confirmation prompt or use of the -y / --yes flag by setting publishers' disable option to true in either Hatch's config file or project-specific configuration (which takes precedence): config.toml pyproject.toml hatch.toml [publish.index] disable = true [tool.hatch.publish.index] disable = true [publish.index] disable = true","title":"Confirmation"},{"location":"users/","text":"Users \u00b6 The following is not intended to be a complete enumeration. Be sure to view the development version of this page for an up-to-date listing. Projects \u00b6 argon2-cffi | Colorama | FastAPI | Gradio | HTTPX | iCalendar for Humans | LinkChecker | Material for MkDocs | pipx | platformdirs | Pydantic | PyHamcrest | PyMdown Extensions | Python JSON Schema | SALib | Starlette | structlog | tox | urllib3 | Uvicorn Industry \u00b6 Anaconda [ 1 | 2 ] Bloomberg [ 1 ] Datadog [ 1 | 2 | 3 | 4 ] deepset [ 1 ] Elastic [ 1 | 2 ] Meta [ 1 | 2 ] Palo Alto Networks [ 1 ] Virtru [ 1 | 2 ] Organizations \u00b6 OpenTelemetry [ 1 | 2 ] Smithsonian Institution [ 1 ] Government \u00b6 United States National Telecommunications and Information Administration [ 1 | 2 | 3 | 4 ] Academia \u00b6 Clariah [ 1 ] Stanford University Empirical Security Research Group [ 1 ] University of Toronto Scarborough utsc-networking [ 1 | 2 | 3 | 4 ] Research \u00b6 GAMA [ 1 ] IPython [ 1 | 2 | 3 ] Project Jupyter Jupyter [ 1 | 2 | 3 | 4 ] JupyterLab [ 1 | 2 | 3 | 4 | 5 ] Jupyter Server [ 1 | 2 | 3 | 4 ] Scikit-HEP [ 1 | 2 | 3 | 4 | 5 | 6 ] Spyder [ 1 ] Security \u00b6 in-toto The Update Framework","title":"Users"},{"location":"users/#users","text":"The following is not intended to be a complete enumeration. Be sure to view the development version of this page for an up-to-date listing.","title":"Users"},{"location":"users/#projects","text":"argon2-cffi | Colorama | FastAPI | Gradio | HTTPX | iCalendar for Humans | LinkChecker | Material for MkDocs | pipx | platformdirs | Pydantic | PyHamcrest | PyMdown Extensions | Python JSON Schema | SALib | Starlette | structlog | tox | urllib3 | Uvicorn","title":"Projects"},{"location":"users/#industry","text":"Anaconda [ 1 | 2 ] Bloomberg [ 1 ] Datadog [ 1 | 2 | 3 | 4 ] deepset [ 1 ] Elastic [ 1 | 2 ] Meta [ 1 | 2 ] Palo Alto Networks [ 1 ] Virtru [ 1 | 2 ]","title":"Industry"},{"location":"users/#organizations","text":"OpenTelemetry [ 1 | 2 ] Smithsonian Institution [ 1 ]","title":"Organizations"},{"location":"users/#government","text":"United States National Telecommunications and Information Administration [ 1 | 2 | 3 | 4 ]","title":"Government"},{"location":"users/#academia","text":"Clariah [ 1 ] Stanford University Empirical Security Research Group [ 1 ] University of Toronto Scarborough utsc-networking [ 1 | 2 | 3 | 4 ]","title":"Academia"},{"location":"users/#research","text":"GAMA [ 1 ] IPython [ 1 | 2 | 3 ] Project Jupyter Jupyter [ 1 | 2 | 3 | 4 ] JupyterLab [ 1 | 2 | 3 | 4 | 5 ] Jupyter Server [ 1 | 2 | 3 | 4 ] Scikit-HEP [ 1 | 2 | 3 | 4 | 5 | 6 ] Spyder [ 1 ]","title":"Research"},{"location":"users/#security","text":"in-toto The Update Framework","title":"Security"},{"location":"version/","text":"Versioning \u00b6 Configuration \u00b6 When the version is not statically set , configuration is defined in the tool.hatch.version table. The source option determines the source to use for retrieving and updating the version. The regex source is used by default. The regex source requires an option path that represents a relative path to a file containing the project's version: pyproject.toml hatch.toml [tool.hatch.version] path = \"hatch_demo/__about__.py\" [version] path = \"hatch_demo/__about__.py\" The default pattern looks for a variable named __version__ or VERSION that is set to a string containing the version, optionally prefixed with the lowercase letter v . If this doesn't reflect how you store the version, you can define a different regular expression using the pattern option: pyproject.toml hatch.toml [tool.hatch.version] path = \"pkg/__init__.py\" pattern = \"BUILD = 'b(?P)'\" [version] path = \"pkg/__init__.py\" pattern = \"BUILD = 'b(?P)'\" The pattern must have a named group called version that represents the version. Display \u00b6 Invoking the version command without any arguments will display the current version of the project: $ hatch version 0.0.1 Updating \u00b6 You can update the version like so: $ hatch version \"0.1.0\" Old: 0.0.1 New: 0.1.0 The scheme option determines the scheme to use for parsing both the existing and new versions. The standard scheme is used by default, which is based on PEP 440 . Rather than setting the version explicitly, you can select the name of a segment used to increment the version: $ hatch version minor Old: 0.1.0 New: 0.2.0 You can chain multiple segment updates with a comma. For example, if you wanted to release a preview of your project's first major version, you could do: $ hatch version major,rc Old: 0.2.0 New: 1.0.0rc0 When you want to release the final version, you would do: $ hatch version release Old: 1.0.0rc0 New: 1.0.0 Supported segments \u00b6 Here are the supported segments and how they would influence an existing version of 1.0.0 : Segments New version release 1.0.0 major 2.0.0 minor 1.1.0 micro patch fix 1.0.1 a alpha 1.0.0a0 b beta 1.0.0b0 c rc pre preview 1.0.0rc0 r rev post 1.0.0.post0 dev 1.0.0.dev0","title":"Versioning"},{"location":"version/#versioning","text":"","title":"Versioning"},{"location":"version/#configuration","text":"When the version is not statically set , configuration is defined in the tool.hatch.version table. The source option determines the source to use for retrieving and updating the version. The regex source is used by default. The regex source requires an option path that represents a relative path to a file containing the project's version: pyproject.toml hatch.toml [tool.hatch.version] path = \"hatch_demo/__about__.py\" [version] path = \"hatch_demo/__about__.py\" The default pattern looks for a variable named __version__ or VERSION that is set to a string containing the version, optionally prefixed with the lowercase letter v . If this doesn't reflect how you store the version, you can define a different regular expression using the pattern option: pyproject.toml hatch.toml [tool.hatch.version] path = \"pkg/__init__.py\" pattern = \"BUILD = 'b(?P)'\" [version] path = \"pkg/__init__.py\" pattern = \"BUILD = 'b(?P)'\" The pattern must have a named group called version that represents the version.","title":"Configuration"},{"location":"version/#display","text":"Invoking the version command without any arguments will display the current version of the project: $ hatch version 0.0.1","title":"Display"},{"location":"version/#updating","text":"You can update the version like so: $ hatch version \"0.1.0\" Old: 0.0.1 New: 0.1.0 The scheme option determines the scheme to use for parsing both the existing and new versions. The standard scheme is used by default, which is based on PEP 440 . Rather than setting the version explicitly, you can select the name of a segment used to increment the version: $ hatch version minor Old: 0.1.0 New: 0.2.0 You can chain multiple segment updates with a comma. For example, if you wanted to release a preview of your project's first major version, you could do: $ hatch version major,rc Old: 0.2.0 New: 1.0.0rc0 When you want to release the final version, you would do: $ hatch version release Old: 1.0.0rc0 New: 1.0.0","title":"Updating"},{"location":"version/#supported-segments","text":"Here are the supported segments and how they would influence an existing version of 1.0.0 : Segments New version release 1.0.0 major 2.0.0 minor 1.1.0 micro patch fix 1.0.1 a alpha 1.0.0a0 b beta 1.0.0b0 c rc pre preview 1.0.0rc0 r rev post 1.0.0.post0 dev 1.0.0.dev0","title":"Supported segments"},{"location":"cli/about/","text":"About \u00b6 Verbosity \u00b6 The amount of displayed output is controlled solely by the -v / --verbose (environment variable HATCH_VERBOSE ) and -q / --quiet (environment variable HATCH_QUIET ) root options . The levels are documented here . Project awareness \u00b6 No matter the mode , Hatch will always change to the project's root directory for entering or running commands in environments. Tab completion \u00b6 Completion is achieved by saving a script and then executing it as a part of your shell's startup sequence. Afterward, you'll need to start a new shell in order for the changes to take effect. Bash Z shell fish Save the script somewhere: _HATCH_COMPLETE=bash_source hatch > ~/.hatch-complete.bash Source the file in ~/.bashrc (or ~/.bash_profile if on macOS): . ~/.hatch-complete.bash Save the script somewhere: _HATCH_COMPLETE=zsh_source hatch > ~/.hatch-complete.zsh Source the file in ~/.zshrc : . ~/.hatch-complete.zsh Save the script in ~/.config/fish/completions : _HATCH_COMPLETE=fish_source hatch > ~/.config/fish/completions/hatch.fish","title":"About"},{"location":"cli/about/#about","text":"","title":"About"},{"location":"cli/about/#verbosity","text":"The amount of displayed output is controlled solely by the -v / --verbose (environment variable HATCH_VERBOSE ) and -q / --quiet (environment variable HATCH_QUIET ) root options . The levels are documented here .","title":"Verbosity"},{"location":"cli/about/#project-awareness","text":"No matter the mode , Hatch will always change to the project's root directory for entering or running commands in environments.","title":"Project awareness"},{"location":"cli/about/#tab-completion","text":"Completion is achieved by saving a script and then executing it as a part of your shell's startup sequence. Afterward, you'll need to start a new shell in order for the changes to take effect. Bash Z shell fish Save the script somewhere: _HATCH_COMPLETE=bash_source hatch > ~/.hatch-complete.bash Source the file in ~/.bashrc (or ~/.bash_profile if on macOS): . ~/.hatch-complete.bash Save the script somewhere: _HATCH_COMPLETE=zsh_source hatch > ~/.hatch-complete.zsh Source the file in ~/.zshrc : . ~/.hatch-complete.zsh Save the script in ~/.config/fish/completions : _HATCH_COMPLETE=fish_source hatch > ~/.config/fish/completions/hatch.fish","title":"Tab completion"},{"location":"cli/reference/","text":"hatch \u00b6 Usage: hatch [OPTIONS] COMMAND [ARGS]... Options: Name Type Description Default --env , -e text The name of the environment to use [env var: HATCH_ENV ] default --project , -p text The name of the project to work on [env var: HATCH_PROJECT ] None --color / --no-color boolean Whether or not to display colored output (default is auto-detection) [env vars: FORCE_COLOR / NO_COLOR ] None --interactive / --no-interactive boolean Whether or not to allow features like prompts and progress bars (default is auto-detection) [env var: HATCH_INTERACTIVE ] None --verbose , -v integer range ( 0 and above) Increase verbosity (can be used additively) [env var: HATCH_VERBOSE ] 0 --quiet , -q integer range ( 0 and above) Decrease verbosity (can be used additively) [env var: HATCH_QUIET ] 0 --data-dir text The path to a custom directory used to persist data [env var: HATCH_DATA_DIR ] None --cache-dir text The path to a custom directory used to cache data [env var: HATCH_CACHE_DIR ] None --config text The path to a custom config file to use [env var: HATCH_CONFIG ] None --version boolean Show the version and exit. False --help boolean Show this message and exit. False hatch build \u00b6 Build a project. Usage: hatch build [OPTIONS] [LOCATION] Options: Name Type Description Default --target , -t text The target to build, overriding project defaults. This may be selected multiple times e.g. -t sdist -t wheel None --hooks-only boolean Whether or not to only execute build hooks [env var: HATCH_BUILD_HOOKS_ONLY ] False --no-hooks boolean Whether or not to disable build hooks [env var: HATCH_BUILD_NO_HOOKS ] False --ext boolean Whether or not to only execute build hooks for distributing binary Python packages, such as compiling extensions. Equivalent to --hooks-only -t wheel False --clean , -c boolean Whether or not existing artifacts should first be removed [env var: HATCH_BUILD_CLEAN ] False --clean-hooks-after boolean Whether or not build hook artifacts should be removed after each build [env var: HATCH_BUILD_CLEAN_HOOKS_AFTER ] False --help boolean Show this message and exit. False hatch clean \u00b6 Remove build artifacts. Usage: hatch clean [OPTIONS] [LOCATION] Options: Name Type Description Default --target , -t text The target with which to remove artifacts, overriding project defaults. This may be selected multiple times e.g. -t sdist -t wheel None --hooks-only boolean Whether or not to only remove artifacts from build hooks [env var: HATCH_BUILD_HOOKS_ONLY ] False --no-hooks boolean Whether or not to ignore artifacts from build hooks [env var: HATCH_BUILD_NO_HOOKS ] False --ext boolean Whether or not to only remove artifacts from build hooks for distributing binary Python packages, such as compiled extensions. Equivalent to --hooks-only -t wheel False --help boolean Show this message and exit. False hatch config \u00b6 Manage the config file Usage: hatch config [OPTIONS] COMMAND [ARGS]... Options: Name Type Description Default --help boolean Show this message and exit. False hatch config explore \u00b6 Open the config location in your file manager. Usage: hatch config explore [OPTIONS] Options: Name Type Description Default --help boolean Show this message and exit. False hatch config find \u00b6 Show the location of the config file. Usage: hatch config find [OPTIONS] Options: Name Type Description Default --copy , -c boolean Copy the path to the config file to the clipboard False --help boolean Show this message and exit. False hatch config restore \u00b6 Restore the config file to default settings. Usage: hatch config restore [OPTIONS] Options: Name Type Description Default --help boolean Show this message and exit. False hatch config set \u00b6 Assign values to config file entries. If the value is omitted, you will be prompted, with the input hidden if it is sensitive. Usage: hatch config set [OPTIONS] KEY [VALUE] Options: Name Type Description Default --help boolean Show this message and exit. False hatch config show \u00b6 Show the contents of the config file. Usage: hatch config show [OPTIONS] Options: Name Type Description Default --all , -a boolean Do not scrub secret fields False --help boolean Show this message and exit. False hatch config update \u00b6 Update the config file with any new fields. Usage: hatch config update [OPTIONS] Options: Name Type Description Default --help boolean Show this message and exit. False hatch dep \u00b6 Manage environment dependencies Usage: hatch dep [OPTIONS] COMMAND [ARGS]... Options: Name Type Description Default --help boolean Show this message and exit. False hatch dep hash \u00b6 Output a hash of the currently defined dependencies. Usage: hatch dep hash [OPTIONS] Options: Name Type Description Default --project-only , -p boolean Whether or not to exclude environment dependencies False --env-only , -e boolean Whether or not to exclude project dependencies False --help boolean Show this message and exit. False hatch dep show \u00b6 Display dependencies in various formats Usage: hatch dep show [OPTIONS] COMMAND [ARGS]... Options: Name Type Description Default --help boolean Show this message and exit. False hatch dep show requirements \u00b6 Enumerate dependencies as a list of requirements. Usage: hatch dep show requirements [OPTIONS] Options: Name Type Description Default --project-only , -p boolean Whether or not to exclude environment dependencies False --env-only , -e boolean Whether or not to exclude project dependencies False --feature , -f text Whether or not to only show the dependencies of the specified features None --all boolean Whether or not to include the dependencies of all features False --help boolean Show this message and exit. False hatch dep show table \u00b6 Enumerate dependencies in a tabular format. Usage: hatch dep show table [OPTIONS] Options: Name Type Description Default --project-only , -p boolean Whether or not to exclude environment dependencies False --env-only , -e boolean Whether or not to exclude project dependencies False --lines , -l boolean Whether or not to show lines between table rows False --ascii boolean Whether or not to only use ASCII characters False --help boolean Show this message and exit. False hatch env \u00b6 Manage project environments Usage: hatch env [OPTIONS] COMMAND [ARGS]... Options: Name Type Description Default --help boolean Show this message and exit. False hatch env create \u00b6 Create environments. Usage: hatch env create [OPTIONS] [ENV_NAME] Options: Name Type Description Default --help boolean Show this message and exit. False hatch env find \u00b6 Locate environments. Usage: hatch env find [OPTIONS] [ENV_NAME] Options: Name Type Description Default --help boolean Show this message and exit. False hatch env prune \u00b6 Remove all environments. Usage: hatch env prune [OPTIONS] Options: Name Type Description Default --help boolean Show this message and exit. False hatch env remove \u00b6 Remove environments. Usage: hatch env remove [OPTIONS] [ENV_NAME] Options: Name Type Description Default --help boolean Show this message and exit. False hatch env run \u00b6 Run commands within project environments. The -e / --env option overrides the equivalent root option and the HATCH_ENV environment variable. If environments provide matrices, then you may use the -i / --include and -x / --exclude options to select or exclude certain variables, optionally followed by specific comma-separated values. For example, if you have the following configuration: pyproject.toml hatch.toml [[tool.hatch.envs.test.matrix]] python = [ \"39\" , \"310\" ] version = [ \"42\" , \"3.14\" , \"9000\" ] [[envs.test.matrix]] python = [ \"39\" , \"310\" ] version = [ \"42\" , \"3.14\" , \"9000\" ] then running: hatch env run -i py=310 -x version=9000 test:pytest would execute pytest in the environments test.py310-42 and test.py310-3.14 . Note that py may be used as an alias for python . Usage: hatch env run [OPTIONS] ARGS... Options: Name Type Description Default --env , -e text The environments to target None --include , -i text The matrix variables to include None --exclude , -x text The matrix variables to exclude None --filter , -f text The JSON data used to select environments None --force-continue boolean Run every command and if there were any errors exit with the first code False --ignore-compat boolean Ignore incompatibility when selecting specific environments False --help boolean Show this message and exit. False hatch env show \u00b6 Show the available environments. Usage: hatch env show [OPTIONS] [ENVS]... Options: Name Type Description Default --ascii boolean Whether or not to only use ASCII characters False --json boolean Whether or not to output in JSON format False --help boolean Show this message and exit. False hatch new \u00b6 Create or initialize a project. Usage: hatch new [OPTIONS] [NAME] [LOCATION] Options: Name Type Description Default --interactive , -i boolean Interactively choose details about the project False --cli boolean Give the project a command line interface False --init boolean Initialize an existing project False --help boolean Show this message and exit. False hatch project \u00b6 View project information Usage: hatch project [OPTIONS] COMMAND [ARGS]... Options: Name Type Description Default --help boolean Show this message and exit. False hatch project metadata \u00b6 Display project metadata. Usage: hatch project metadata [OPTIONS] [FIELD] Options: Name Type Description Default --help boolean Show this message and exit. False hatch publish \u00b6 Publish build artifacts. Usage: hatch publish [OPTIONS] [ARTIFACTS]... Options: Name Type Description Default --repo , -r text The repository with which to publish artifacts [env var: HATCH_INDEX_REPO ] None --user , -u text The user with which to authenticate [env var: HATCH_INDEX_USER ] None --auth , -a text The credentials to use for authentication [env var: HATCH_INDEX_AUTH ] None --ca-cert text The path to a CA bundle [env var: HATCH_INDEX_CA_CERT ] None --client-cert text The path to a client certificate, optionally containing the private key [env var: HATCH_INDEX_CLIENT_CERT ] None --client-key text The path to the client certificate's private key [env var: HATCH_INDEX_CLIENT_KEY ] None --no-prompt , -n boolean Disable prompts, such as for missing required fields False --publisher , -p text The publisher plugin to use (default is index ) [env var: HATCH_PUBLISHER ] index --option , -o text Options to pass to the publisher plugin. This may be selected multiple times e.g. -o foo=bar -o baz=23 [env var: HATCH_PUBLISHER_OPTIONS ] None --yes , -y boolean Confirm without prompting when the plugin is disabled False --help boolean Show this message and exit. False hatch run \u00b6 Run commands within project environments. This is a convenience wrapper around the env run command. If the first argument contains a colon, then the preceding component will be interpreted as the name of the environment to target, overriding the -e / --env root option and the HATCH_ENV environment variable. If the environment provides matrices, then you may also provide leading arguments starting with a + or - to select or exclude certain variables, optionally followed by specific comma-separated values. For example, if you have the following configuration: pyproject.toml hatch.toml [[tool.hatch.envs.test.matrix]] python = [ \"39\" , \"310\" ] version = [ \"42\" , \"3.14\" , \"9000\" ] [[envs.test.matrix]] python = [ \"39\" , \"310\" ] version = [ \"42\" , \"3.14\" , \"9000\" ] then running: hatch run +py=310 -version=9000 test:pytest would execute pytest in the environments test.py310-42 and test.py310-3.14 . Note that py may be used as an alias for python . Usage: hatch run [OPTIONS] [ENV:]ARGS... Options: Name Type Description Default --help boolean Show this message and exit. False hatch shell \u00b6 Enter a shell within a project's environment. Usage: hatch shell [OPTIONS] [SHELL_NAME] [SHELL_PATH] [SHELL_ARGS]... Options: Name Type Description Default --help boolean Show this message and exit. False hatch status \u00b6 Show information about the current environment. Usage: hatch status [OPTIONS] Options: Name Type Description Default --help boolean Show this message and exit. False hatch version \u00b6 View or set a project's version. Usage: hatch version [OPTIONS] [DESIRED_VERSION] Options: Name Type Description Default --help boolean Show this message and exit. False","title":"Reference"},{"location":"cli/reference/#hatch","text":"Usage: hatch [OPTIONS] COMMAND [ARGS]... Options: Name Type Description Default --env , -e text The name of the environment to use [env var: HATCH_ENV ] default --project , -p text The name of the project to work on [env var: HATCH_PROJECT ] None --color / --no-color boolean Whether or not to display colored output (default is auto-detection) [env vars: FORCE_COLOR / NO_COLOR ] None --interactive / --no-interactive boolean Whether or not to allow features like prompts and progress bars (default is auto-detection) [env var: HATCH_INTERACTIVE ] None --verbose , -v integer range ( 0 and above) Increase verbosity (can be used additively) [env var: HATCH_VERBOSE ] 0 --quiet , -q integer range ( 0 and above) Decrease verbosity (can be used additively) [env var: HATCH_QUIET ] 0 --data-dir text The path to a custom directory used to persist data [env var: HATCH_DATA_DIR ] None --cache-dir text The path to a custom directory used to cache data [env var: HATCH_CACHE_DIR ] None --config text The path to a custom config file to use [env var: HATCH_CONFIG ] None --version boolean Show the version and exit. False --help boolean Show this message and exit. False","title":"hatch"},{"location":"cli/reference/#hatch-build","text":"Build a project. Usage: hatch build [OPTIONS] [LOCATION] Options: Name Type Description Default --target , -t text The target to build, overriding project defaults. This may be selected multiple times e.g. -t sdist -t wheel None --hooks-only boolean Whether or not to only execute build hooks [env var: HATCH_BUILD_HOOKS_ONLY ] False --no-hooks boolean Whether or not to disable build hooks [env var: HATCH_BUILD_NO_HOOKS ] False --ext boolean Whether or not to only execute build hooks for distributing binary Python packages, such as compiling extensions. Equivalent to --hooks-only -t wheel False --clean , -c boolean Whether or not existing artifacts should first be removed [env var: HATCH_BUILD_CLEAN ] False --clean-hooks-after boolean Whether or not build hook artifacts should be removed after each build [env var: HATCH_BUILD_CLEAN_HOOKS_AFTER ] False --help boolean Show this message and exit. False","title":"build"},{"location":"cli/reference/#hatch-clean","text":"Remove build artifacts. Usage: hatch clean [OPTIONS] [LOCATION] Options: Name Type Description Default --target , -t text The target with which to remove artifacts, overriding project defaults. This may be selected multiple times e.g. -t sdist -t wheel None --hooks-only boolean Whether or not to only remove artifacts from build hooks [env var: HATCH_BUILD_HOOKS_ONLY ] False --no-hooks boolean Whether or not to ignore artifacts from build hooks [env var: HATCH_BUILD_NO_HOOKS ] False --ext boolean Whether or not to only remove artifacts from build hooks for distributing binary Python packages, such as compiled extensions. Equivalent to --hooks-only -t wheel False --help boolean Show this message and exit. False","title":"clean"},{"location":"cli/reference/#hatch-config","text":"Manage the config file Usage: hatch config [OPTIONS] COMMAND [ARGS]... Options: Name Type Description Default --help boolean Show this message and exit. False","title":"config"},{"location":"cli/reference/#hatch-config-explore","text":"Open the config location in your file manager. Usage: hatch config explore [OPTIONS] Options: Name Type Description Default --help boolean Show this message and exit. False","title":"explore"},{"location":"cli/reference/#hatch-config-find","text":"Show the location of the config file. Usage: hatch config find [OPTIONS] Options: Name Type Description Default --copy , -c boolean Copy the path to the config file to the clipboard False --help boolean Show this message and exit. False","title":"find"},{"location":"cli/reference/#hatch-config-restore","text":"Restore the config file to default settings. Usage: hatch config restore [OPTIONS] Options: Name Type Description Default --help boolean Show this message and exit. False","title":"restore"},{"location":"cli/reference/#hatch-config-set","text":"Assign values to config file entries. If the value is omitted, you will be prompted, with the input hidden if it is sensitive. Usage: hatch config set [OPTIONS] KEY [VALUE] Options: Name Type Description Default --help boolean Show this message and exit. False","title":"set"},{"location":"cli/reference/#hatch-config-show","text":"Show the contents of the config file. Usage: hatch config show [OPTIONS] Options: Name Type Description Default --all , -a boolean Do not scrub secret fields False --help boolean Show this message and exit. False","title":"show"},{"location":"cli/reference/#hatch-config-update","text":"Update the config file with any new fields. Usage: hatch config update [OPTIONS] Options: Name Type Description Default --help boolean Show this message and exit. False","title":"update"},{"location":"cli/reference/#hatch-dep","text":"Manage environment dependencies Usage: hatch dep [OPTIONS] COMMAND [ARGS]... Options: Name Type Description Default --help boolean Show this message and exit. False","title":"dep"},{"location":"cli/reference/#hatch-dep-hash","text":"Output a hash of the currently defined dependencies. Usage: hatch dep hash [OPTIONS] Options: Name Type Description Default --project-only , -p boolean Whether or not to exclude environment dependencies False --env-only , -e boolean Whether or not to exclude project dependencies False --help boolean Show this message and exit. False","title":"hash"},{"location":"cli/reference/#hatch-dep-show","text":"Display dependencies in various formats Usage: hatch dep show [OPTIONS] COMMAND [ARGS]... Options: Name Type Description Default --help boolean Show this message and exit. False","title":"show"},{"location":"cli/reference/#hatch-dep-show-requirements","text":"Enumerate dependencies as a list of requirements. Usage: hatch dep show requirements [OPTIONS] Options: Name Type Description Default --project-only , -p boolean Whether or not to exclude environment dependencies False --env-only , -e boolean Whether or not to exclude project dependencies False --feature , -f text Whether or not to only show the dependencies of the specified features None --all boolean Whether or not to include the dependencies of all features False --help boolean Show this message and exit. False","title":"requirements"},{"location":"cli/reference/#hatch-dep-show-table","text":"Enumerate dependencies in a tabular format. Usage: hatch dep show table [OPTIONS] Options: Name Type Description Default --project-only , -p boolean Whether or not to exclude environment dependencies False --env-only , -e boolean Whether or not to exclude project dependencies False --lines , -l boolean Whether or not to show lines between table rows False --ascii boolean Whether or not to only use ASCII characters False --help boolean Show this message and exit. False","title":"table"},{"location":"cli/reference/#hatch-env","text":"Manage project environments Usage: hatch env [OPTIONS] COMMAND [ARGS]... Options: Name Type Description Default --help boolean Show this message and exit. False","title":"env"},{"location":"cli/reference/#hatch-env-create","text":"Create environments. Usage: hatch env create [OPTIONS] [ENV_NAME] Options: Name Type Description Default --help boolean Show this message and exit. False","title":"create"},{"location":"cli/reference/#hatch-env-find","text":"Locate environments. Usage: hatch env find [OPTIONS] [ENV_NAME] Options: Name Type Description Default --help boolean Show this message and exit. False","title":"find"},{"location":"cli/reference/#hatch-env-prune","text":"Remove all environments. Usage: hatch env prune [OPTIONS] Options: Name Type Description Default --help boolean Show this message and exit. False","title":"prune"},{"location":"cli/reference/#hatch-env-remove","text":"Remove environments. Usage: hatch env remove [OPTIONS] [ENV_NAME] Options: Name Type Description Default --help boolean Show this message and exit. False","title":"remove"},{"location":"cli/reference/#hatch-env-run","text":"Run commands within project environments. The -e / --env option overrides the equivalent root option and the HATCH_ENV environment variable. If environments provide matrices, then you may use the -i / --include and -x / --exclude options to select or exclude certain variables, optionally followed by specific comma-separated values. For example, if you have the following configuration: pyproject.toml hatch.toml [[tool.hatch.envs.test.matrix]] python = [ \"39\" , \"310\" ] version = [ \"42\" , \"3.14\" , \"9000\" ] [[envs.test.matrix]] python = [ \"39\" , \"310\" ] version = [ \"42\" , \"3.14\" , \"9000\" ] then running: hatch env run -i py=310 -x version=9000 test:pytest would execute pytest in the environments test.py310-42 and test.py310-3.14 . Note that py may be used as an alias for python . Usage: hatch env run [OPTIONS] ARGS... Options: Name Type Description Default --env , -e text The environments to target None --include , -i text The matrix variables to include None --exclude , -x text The matrix variables to exclude None --filter , -f text The JSON data used to select environments None --force-continue boolean Run every command and if there were any errors exit with the first code False --ignore-compat boolean Ignore incompatibility when selecting specific environments False --help boolean Show this message and exit. False","title":"run"},{"location":"cli/reference/#hatch-env-show","text":"Show the available environments. Usage: hatch env show [OPTIONS] [ENVS]... Options: Name Type Description Default --ascii boolean Whether or not to only use ASCII characters False --json boolean Whether or not to output in JSON format False --help boolean Show this message and exit. False","title":"show"},{"location":"cli/reference/#hatch-new","text":"Create or initialize a project. Usage: hatch new [OPTIONS] [NAME] [LOCATION] Options: Name Type Description Default --interactive , -i boolean Interactively choose details about the project False --cli boolean Give the project a command line interface False --init boolean Initialize an existing project False --help boolean Show this message and exit. False","title":"new"},{"location":"cli/reference/#hatch-project","text":"View project information Usage: hatch project [OPTIONS] COMMAND [ARGS]... Options: Name Type Description Default --help boolean Show this message and exit. False","title":"project"},{"location":"cli/reference/#hatch-project-metadata","text":"Display project metadata. Usage: hatch project metadata [OPTIONS] [FIELD] Options: Name Type Description Default --help boolean Show this message and exit. False","title":"metadata"},{"location":"cli/reference/#hatch-publish","text":"Publish build artifacts. Usage: hatch publish [OPTIONS] [ARTIFACTS]... Options: Name Type Description Default --repo , -r text The repository with which to publish artifacts [env var: HATCH_INDEX_REPO ] None --user , -u text The user with which to authenticate [env var: HATCH_INDEX_USER ] None --auth , -a text The credentials to use for authentication [env var: HATCH_INDEX_AUTH ] None --ca-cert text The path to a CA bundle [env var: HATCH_INDEX_CA_CERT ] None --client-cert text The path to a client certificate, optionally containing the private key [env var: HATCH_INDEX_CLIENT_CERT ] None --client-key text The path to the client certificate's private key [env var: HATCH_INDEX_CLIENT_KEY ] None --no-prompt , -n boolean Disable prompts, such as for missing required fields False --publisher , -p text The publisher plugin to use (default is index ) [env var: HATCH_PUBLISHER ] index --option , -o text Options to pass to the publisher plugin. This may be selected multiple times e.g. -o foo=bar -o baz=23 [env var: HATCH_PUBLISHER_OPTIONS ] None --yes , -y boolean Confirm without prompting when the plugin is disabled False --help boolean Show this message and exit. False","title":"publish"},{"location":"cli/reference/#hatch-run","text":"Run commands within project environments. This is a convenience wrapper around the env run command. If the first argument contains a colon, then the preceding component will be interpreted as the name of the environment to target, overriding the -e / --env root option and the HATCH_ENV environment variable. If the environment provides matrices, then you may also provide leading arguments starting with a + or - to select or exclude certain variables, optionally followed by specific comma-separated values. For example, if you have the following configuration: pyproject.toml hatch.toml [[tool.hatch.envs.test.matrix]] python = [ \"39\" , \"310\" ] version = [ \"42\" , \"3.14\" , \"9000\" ] [[envs.test.matrix]] python = [ \"39\" , \"310\" ] version = [ \"42\" , \"3.14\" , \"9000\" ] then running: hatch run +py=310 -version=9000 test:pytest would execute pytest in the environments test.py310-42 and test.py310-3.14 . Note that py may be used as an alias for python . Usage: hatch run [OPTIONS] [ENV:]ARGS... Options: Name Type Description Default --help boolean Show this message and exit. False","title":"run"},{"location":"cli/reference/#hatch-shell","text":"Enter a shell within a project's environment. Usage: hatch shell [OPTIONS] [SHELL_NAME] [SHELL_PATH] [SHELL_ARGS]... Options: Name Type Description Default --help boolean Show this message and exit. False","title":"shell"},{"location":"cli/reference/#hatch-status","text":"Show information about the current environment. Usage: hatch status [OPTIONS] Options: Name Type Description Default --help boolean Show this message and exit. False","title":"status"},{"location":"cli/reference/#hatch-version","text":"View or set a project's version. Usage: hatch version [OPTIONS] [DESIRED_VERSION] Options: Name Type Description Default --help boolean Show this message and exit. False","title":"version"},{"location":"config/build/","text":"Build configuration \u00b6 All build configuration is defined in the tool.hatch.build table. Build targets are defined as sections within tool.hatch.build.targets : pyproject.toml hatch.toml [tool.hatch.build.targets.] [build.targets.] For each build target you may override any of the defaults set in the top-level tool.hatch.build table. Build system \u00b6 To be compatible with the broader Python packaging ecosystem , you must define the build system as follows: pyproject.toml [build-system] requires = [ \"hatchling\" ] build-backend = \"hatchling.build\" The version of hatchling defined here will be used to build all targets. Hatchling is a PEP 517 / PEP 660 compatible build backend and is a dependency of Hatch itself. File selection \u00b6 VCS \u00b6 By default, Hatch will respect the first .gitignore or .hgignore file found in your project's root directory or parent directories. Set ignore-vcs to true to disable this behavior: pyproject.toml hatch.toml [tool.hatch.build] ignore-vcs = true [build] ignore-vcs = true Note For .hgignore files only glob syntax is supported. Patterns \u00b6 You can set the include and exclude options to select exactly which files will be shipped in each build, with exclude taking precedence. Every entry represents a Git-style glob pattern . For example, the following configuration: pyproject.toml hatch.toml [tool.hatch.build] include = [ \"pkg/*.py\" , \"/tests\" , ] exclude = [ \"*.json\" , \"pkg/_compat.py\" , ] [build] include = [ \"pkg/*.py\" , \"/tests\" , ] exclude = [ \"*.json\" , \"pkg/_compat.py\" , ] will exclude every file with a .json extension, and will include everything under a tests directory located at the root and every file with a .py extension that is directly under a pkg directory located at the root except for _compat.py . Artifacts \u00b6 If you want to include files that are ignored by your VCS , such as those that might be created by build hooks , you can use the artifacts option. This option is semantically equivalent to include . Note that artifacts are not affected by the exclude option. Artifacts can be excluded by using more explicit paths or by using the ! negation operator. When using the ! operator, the negated pattern(s) must come after the more generic ones. pyproject.toml hatch.toml [tool.hatch.build] artifacts = [ \"*.so\" , \"*.dll\" , \"!/foo/*.so\" , ] [build] artifacts = [ \"*.so\" , \"*.dll\" , \"!/foo/*.so\" , ] Explicit selection \u00b6 Generic \u00b6 You can use the only-include option to prevent directory traversal starting at the project root and only select specific relative paths to directories or files. Using this option ignores any defined include patterns . pyproject.toml hatch.toml [tool.hatch.build.targets.wheel] only-include = [ \"pkg\" , \"tests/unit\" ] [build.targets.wheel] only-include = [ \"pkg\" , \"tests/unit\" ] Packages \u00b6 The packages option is semantically equivalent to only-include (which takes precedence) except that the shipped path will be collapsed to only include the final component. So for example, if you want to ship a package foo that is stored in a directory src you would do: pyproject.toml hatch.toml [tool.hatch.build.targets.wheel] packages = [ \"src/foo\" ] [build.targets.wheel] packages = [ \"src/foo\" ] Forced inclusion \u00b6 The force-include option allows you to select specific files or directories from anywhere on the file system that should be included and map them to the desired relative distribution path. For example, if there was a directory alongside the project root named artifacts containing a file named lib.so and a file named lib.h in your home directory, you could ship both files in a pkg directory with the following configuration: pyproject.toml hatch.toml [tool.hatch.build.targets.wheel.force-include] \"../artifacts\" = \"pkg\" \"~/lib.h\" = \"pkg/lib.h\" [build.targets.wheel.force-include] \"../artifacts\" = \"pkg\" \"~/lib.h\" = \"pkg/lib.h\" Note Files must be mapped exactly to their desired paths, not to directories. The contents of directory sources are recursively included. To map directory contents directly to the root use / (a forward slash). Sources that do not exist are silently ignored. Warning Files included using this option will overwrite any file path that was already included by other file selection options. Default file selection \u00b6 If no file selection options are provided, then what gets included is determined by each build target . Excluding files outside packages \u00b6 If you want to exclude non- artifact files that do not reside within a Python package, set only-packages to true : pyproject.toml hatch.toml [tool.hatch.build] only-packages = true [build] only-packages = true Rewriting paths \u00b6 You can rewrite relative paths to directories with the sources option. For example, the following configuration: pyproject.toml hatch.toml [tool.hatch.build.sources] \"src/foo\" = \"bar\" [build.sources] \"src/foo\" = \"bar\" would distribute the file src/foo/file.ext as bar/file.ext . If you want to remove path prefixes entirely, rather than setting each to an empty string, you can define sources as an array: pyproject.toml hatch.toml [tool.hatch.build] sources = [ \"src\" ] [build] sources = [ \"src\" ] The packages option itself relies on sources. Defining packages = [ \"src/foo\" ] for the wheel target is equivalent to the following: pyproject.toml hatch.toml [tool.hatch.build.targets.wheel] only-include = [ \"src/foo\" ] sources = [ \"src\" ] [build.targets.wheel] only-include = [ \"src/foo\" ] sources = [ \"src\" ] Performance \u00b6 All encountered directories are traversed by default. To skip non- artifact directories that are excluded, set skip-excluded-dirs to true : pyproject.toml hatch.toml [tool.hatch.build] skip-excluded-dirs = true [build] skip-excluded-dirs = true Warning This may result in not shipping desired files. For example, if you want to include the file a/b/c.txt but your VCS ignores a/b , the file c.txt will not be seen because its parent directory will not be entered. In such cases you can use the force-include option. Reproducible builds \u00b6 By default, build targets will build in a reproducible manner provided that they support that behavior. To disable this, set reproducible to false : pyproject.toml hatch.toml [tool.hatch.build] reproducible = false [build] reproducible = false When enabled, the SOURCE_DATE_EPOCH environment variable will be used for all build timestamps. If not set, then Hatch will use an unchanging default value . Output directory \u00b6 When the output directory is not provided to the build command, the dist directory will be used by default. You can change the default to a different directory using a relative or absolute path like so: pyproject.toml hatch.toml [tool.hatch.build] directory = \"\" [build] directory = \"\" Dev mode \u00b6 By default for dev mode environment installations or editable installs , the wheel target will determine which directories should be added to Python's search path based on the selected files . If you want to override this detection or perhaps instruct other build targets as well, you can use the dev-mode-dirs option: pyproject.toml hatch.toml [tool.hatch.build] dev-mode-dirs = [ \".\" ] [build] dev-mode-dirs = [ \".\" ] If you don't want to add entire directories to Python's search path, you can enable a more targeted mechanism with the mutually exclusive dev-mode-exact option: pyproject.toml hatch.toml [tool.hatch.build] dev-mode-exact = true [build] dev-mode-exact = true Warning The dev-mode-exact mechanism is not supported by static analysis tools & IDEs, therefore functionality such as autocompletion is unlikely to work. Build targets \u00b6 A build target can be provided by any builder plugin . There are three built-in build targets: wheel , sdist , and custom . Dependencies \u00b6 You can specify additional dependencies that will be installed in each build environment, such as for third party builders: pyproject.toml hatch.toml [tool.hatch.build.targets.your-target-name] dependencies = [ \"your-builder-plugin\" ] [build.targets.your-target-name] dependencies = [ \"your-builder-plugin\" ] You can also declare dependence on the project's runtime dependencies with the require-runtime-dependencies option: pyproject.toml hatch.toml [tool.hatch.build.targets.your-target-name] require-runtime-dependencies = true [build.targets.your-target-name] require-runtime-dependencies = true Additionally, you may declare dependence on specific runtime features of the project with the require-runtime-features option: pyproject.toml hatch.toml [tool.hatch.build.targets.your-target-name] require-runtime-features = [ \"feature1\" , \"feature2\" , ] [build.targets.your-target-name] require-runtime-features = [ \"feature1\" , \"feature2\" , ] Versions \u00b6 If a build target supports multiple build strategies or if there are major changes over time, you can specify exactly which versions you want to build using the versions option, which may be defined as either an array of strings or a comma-separated string: pyproject.toml hatch.toml [tool.hatch.build.targets.] versions = [ \"v1\" , \"beta-feature\" , ] [build.targets.] versions = [ \"v1\" , \"beta-feature\" , ] See the wheel target for a real world example. Build hooks \u00b6 A build hook defines code that will be executed at various stages of the build process and can be provided by any build hook plugin . There is one built-in build hook: custom . Build hooks can be applied either globally: pyproject.toml hatch.toml [tool.hatch.build.hooks.] [build.hooks.] or to specific build targets: pyproject.toml hatch.toml [tool.hatch.build.targets..hooks.] [build.targets..hooks.] Dependencies \u00b6 You can specify additional dependencies that will be installed in each build environment, such as for third party build hooks: pyproject.toml hatch.toml [tool.hatch.build.hooks.your-hook-name] dependencies = [ \"your-build-hook-plugin\" ] [build.hooks.your-hook-name] dependencies = [ \"your-build-hook-plugin\" ] You can also declare dependence on the project's runtime dependencies with the require-runtime-dependencies option: pyproject.toml hatch.toml [tool.hatch.build.hooks.your-hook-name] require-runtime-dependencies = true [build.hooks.your-hook-name] require-runtime-dependencies = true Additionally, you may declare dependence on specific runtime features of the project with the require-runtime-features option: pyproject.toml hatch.toml [tool.hatch.build.hooks.your-hook-name] require-runtime-features = [ \"feature1\" , \"feature2\" , ] [build.hooks.your-hook-name] require-runtime-features = [ \"feature1\" , \"feature2\" , ] Order of execution \u00b6 For each build target, build hooks execute in the order in which they are defined, starting with global hooks. As an example, for the following configuration: pyproject.toml hatch.toml [tool.hatch.build.targets.foo.hooks.hook2] [tool.hatch.build.hooks.hook3] [tool.hatch.build.hooks.hook1] [build.targets.foo.hooks.hook2] [build.hooks.hook3] [build.hooks.hook1] When target foo is built, build hook hook3 will be executed first, followed by hook1 , and then finally hook2 . Conditional execution \u00b6 If you want to disable a build hook by default and control its use by environment variables , you can do so by setting the enable-by-default option to false : pyproject.toml hatch.toml [tool.hatch.build.hooks.] enable-by-default = false [build.hooks.] enable-by-default = false Environment variables \u00b6 Variable Default Description HATCH_BUILD_CLEAN false Whether or not existing artifacts should first be removed HATCH_BUILD_CLEAN_HOOKS_AFTER false Whether or not build hook artifacts should be removed after each build HATCH_BUILD_HOOKS_ONLY false Whether or not to only execute build hooks HATCH_BUILD_NO_HOOKS false Whether or not to disable all build hooks; this takes precedence over other options HATCH_BUILD_HOOKS_ENABLE false Whether or not to enable all build hooks HATCH_BUILD_HOOK_ENABLE_ false HATCH_BUILD_LOCATION dist The location with which to build the targets; only used by the build command","title":"Build"},{"location":"config/build/#build-configuration","text":"All build configuration is defined in the tool.hatch.build table. Build targets are defined as sections within tool.hatch.build.targets : pyproject.toml hatch.toml [tool.hatch.build.targets.] [build.targets.] For each build target you may override any of the defaults set in the top-level tool.hatch.build table.","title":"Build configuration"},{"location":"config/build/#build-system","text":"To be compatible with the broader Python packaging ecosystem , you must define the build system as follows: pyproject.toml [build-system] requires = [ \"hatchling\" ] build-backend = \"hatchling.build\" The version of hatchling defined here will be used to build all targets. Hatchling is a PEP 517 / PEP 660 compatible build backend and is a dependency of Hatch itself.","title":"Build system"},{"location":"config/build/#file-selection","text":"","title":"File selection"},{"location":"config/build/#vcs","text":"By default, Hatch will respect the first .gitignore or .hgignore file found in your project's root directory or parent directories. Set ignore-vcs to true to disable this behavior: pyproject.toml hatch.toml [tool.hatch.build] ignore-vcs = true [build] ignore-vcs = true Note For .hgignore files only glob syntax is supported.","title":"VCS"},{"location":"config/build/#patterns","text":"You can set the include and exclude options to select exactly which files will be shipped in each build, with exclude taking precedence. Every entry represents a Git-style glob pattern . For example, the following configuration: pyproject.toml hatch.toml [tool.hatch.build] include = [ \"pkg/*.py\" , \"/tests\" , ] exclude = [ \"*.json\" , \"pkg/_compat.py\" , ] [build] include = [ \"pkg/*.py\" , \"/tests\" , ] exclude = [ \"*.json\" , \"pkg/_compat.py\" , ] will exclude every file with a .json extension, and will include everything under a tests directory located at the root and every file with a .py extension that is directly under a pkg directory located at the root except for _compat.py .","title":"Patterns"},{"location":"config/build/#artifacts","text":"If you want to include files that are ignored by your VCS , such as those that might be created by build hooks , you can use the artifacts option. This option is semantically equivalent to include . Note that artifacts are not affected by the exclude option. Artifacts can be excluded by using more explicit paths or by using the ! negation operator. When using the ! operator, the negated pattern(s) must come after the more generic ones. pyproject.toml hatch.toml [tool.hatch.build] artifacts = [ \"*.so\" , \"*.dll\" , \"!/foo/*.so\" , ] [build] artifacts = [ \"*.so\" , \"*.dll\" , \"!/foo/*.so\" , ]","title":"Artifacts"},{"location":"config/build/#explicit-selection","text":"","title":"Explicit selection"},{"location":"config/build/#generic","text":"You can use the only-include option to prevent directory traversal starting at the project root and only select specific relative paths to directories or files. Using this option ignores any defined include patterns . pyproject.toml hatch.toml [tool.hatch.build.targets.wheel] only-include = [ \"pkg\" , \"tests/unit\" ] [build.targets.wheel] only-include = [ \"pkg\" , \"tests/unit\" ]","title":"Generic"},{"location":"config/build/#packages","text":"The packages option is semantically equivalent to only-include (which takes precedence) except that the shipped path will be collapsed to only include the final component. So for example, if you want to ship a package foo that is stored in a directory src you would do: pyproject.toml hatch.toml [tool.hatch.build.targets.wheel] packages = [ \"src/foo\" ] [build.targets.wheel] packages = [ \"src/foo\" ]","title":"Packages"},{"location":"config/build/#forced-inclusion","text":"The force-include option allows you to select specific files or directories from anywhere on the file system that should be included and map them to the desired relative distribution path. For example, if there was a directory alongside the project root named artifacts containing a file named lib.so and a file named lib.h in your home directory, you could ship both files in a pkg directory with the following configuration: pyproject.toml hatch.toml [tool.hatch.build.targets.wheel.force-include] \"../artifacts\" = \"pkg\" \"~/lib.h\" = \"pkg/lib.h\" [build.targets.wheel.force-include] \"../artifacts\" = \"pkg\" \"~/lib.h\" = \"pkg/lib.h\" Note Files must be mapped exactly to their desired paths, not to directories. The contents of directory sources are recursively included. To map directory contents directly to the root use / (a forward slash). Sources that do not exist are silently ignored. Warning Files included using this option will overwrite any file path that was already included by other file selection options.","title":"Forced inclusion"},{"location":"config/build/#default-file-selection","text":"If no file selection options are provided, then what gets included is determined by each build target .","title":"Default file selection"},{"location":"config/build/#excluding-files-outside-packages","text":"If you want to exclude non- artifact files that do not reside within a Python package, set only-packages to true : pyproject.toml hatch.toml [tool.hatch.build] only-packages = true [build] only-packages = true","title":"Excluding files outside packages"},{"location":"config/build/#rewriting-paths","text":"You can rewrite relative paths to directories with the sources option. For example, the following configuration: pyproject.toml hatch.toml [tool.hatch.build.sources] \"src/foo\" = \"bar\" [build.sources] \"src/foo\" = \"bar\" would distribute the file src/foo/file.ext as bar/file.ext . If you want to remove path prefixes entirely, rather than setting each to an empty string, you can define sources as an array: pyproject.toml hatch.toml [tool.hatch.build] sources = [ \"src\" ] [build] sources = [ \"src\" ] The packages option itself relies on sources. Defining packages = [ \"src/foo\" ] for the wheel target is equivalent to the following: pyproject.toml hatch.toml [tool.hatch.build.targets.wheel] only-include = [ \"src/foo\" ] sources = [ \"src\" ] [build.targets.wheel] only-include = [ \"src/foo\" ] sources = [ \"src\" ]","title":"Rewriting paths"},{"location":"config/build/#performance","text":"All encountered directories are traversed by default. To skip non- artifact directories that are excluded, set skip-excluded-dirs to true : pyproject.toml hatch.toml [tool.hatch.build] skip-excluded-dirs = true [build] skip-excluded-dirs = true Warning This may result in not shipping desired files. For example, if you want to include the file a/b/c.txt but your VCS ignores a/b , the file c.txt will not be seen because its parent directory will not be entered. In such cases you can use the force-include option.","title":"Performance"},{"location":"config/build/#reproducible-builds","text":"By default, build targets will build in a reproducible manner provided that they support that behavior. To disable this, set reproducible to false : pyproject.toml hatch.toml [tool.hatch.build] reproducible = false [build] reproducible = false When enabled, the SOURCE_DATE_EPOCH environment variable will be used for all build timestamps. If not set, then Hatch will use an unchanging default value .","title":"Reproducible builds"},{"location":"config/build/#output-directory","text":"When the output directory is not provided to the build command, the dist directory will be used by default. You can change the default to a different directory using a relative or absolute path like so: pyproject.toml hatch.toml [tool.hatch.build] directory = \"\" [build] directory = \"\"","title":"Output directory"},{"location":"config/build/#dev-mode","text":"By default for dev mode environment installations or editable installs , the wheel target will determine which directories should be added to Python's search path based on the selected files . If you want to override this detection or perhaps instruct other build targets as well, you can use the dev-mode-dirs option: pyproject.toml hatch.toml [tool.hatch.build] dev-mode-dirs = [ \".\" ] [build] dev-mode-dirs = [ \".\" ] If you don't want to add entire directories to Python's search path, you can enable a more targeted mechanism with the mutually exclusive dev-mode-exact option: pyproject.toml hatch.toml [tool.hatch.build] dev-mode-exact = true [build] dev-mode-exact = true Warning The dev-mode-exact mechanism is not supported by static analysis tools & IDEs, therefore functionality such as autocompletion is unlikely to work.","title":"Dev mode"},{"location":"config/build/#build-targets","text":"A build target can be provided by any builder plugin . There are three built-in build targets: wheel , sdist , and custom .","title":"Build targets"},{"location":"config/build/#dependencies","text":"You can specify additional dependencies that will be installed in each build environment, such as for third party builders: pyproject.toml hatch.toml [tool.hatch.build.targets.your-target-name] dependencies = [ \"your-builder-plugin\" ] [build.targets.your-target-name] dependencies = [ \"your-builder-plugin\" ] You can also declare dependence on the project's runtime dependencies with the require-runtime-dependencies option: pyproject.toml hatch.toml [tool.hatch.build.targets.your-target-name] require-runtime-dependencies = true [build.targets.your-target-name] require-runtime-dependencies = true Additionally, you may declare dependence on specific runtime features of the project with the require-runtime-features option: pyproject.toml hatch.toml [tool.hatch.build.targets.your-target-name] require-runtime-features = [ \"feature1\" , \"feature2\" , ] [build.targets.your-target-name] require-runtime-features = [ \"feature1\" , \"feature2\" , ]","title":"Dependencies"},{"location":"config/build/#versions","text":"If a build target supports multiple build strategies or if there are major changes over time, you can specify exactly which versions you want to build using the versions option, which may be defined as either an array of strings or a comma-separated string: pyproject.toml hatch.toml [tool.hatch.build.targets.] versions = [ \"v1\" , \"beta-feature\" , ] [build.targets.] versions = [ \"v1\" , \"beta-feature\" , ] See the wheel target for a real world example.","title":"Versions"},{"location":"config/build/#build-hooks","text":"A build hook defines code that will be executed at various stages of the build process and can be provided by any build hook plugin . There is one built-in build hook: custom . Build hooks can be applied either globally: pyproject.toml hatch.toml [tool.hatch.build.hooks.] [build.hooks.] or to specific build targets: pyproject.toml hatch.toml [tool.hatch.build.targets..hooks.] [build.targets..hooks.]","title":"Build hooks"},{"location":"config/build/#dependencies_1","text":"You can specify additional dependencies that will be installed in each build environment, such as for third party build hooks: pyproject.toml hatch.toml [tool.hatch.build.hooks.your-hook-name] dependencies = [ \"your-build-hook-plugin\" ] [build.hooks.your-hook-name] dependencies = [ \"your-build-hook-plugin\" ] You can also declare dependence on the project's runtime dependencies with the require-runtime-dependencies option: pyproject.toml hatch.toml [tool.hatch.build.hooks.your-hook-name] require-runtime-dependencies = true [build.hooks.your-hook-name] require-runtime-dependencies = true Additionally, you may declare dependence on specific runtime features of the project with the require-runtime-features option: pyproject.toml hatch.toml [tool.hatch.build.hooks.your-hook-name] require-runtime-features = [ \"feature1\" , \"feature2\" , ] [build.hooks.your-hook-name] require-runtime-features = [ \"feature1\" , \"feature2\" , ]","title":"Dependencies"},{"location":"config/build/#order-of-execution","text":"For each build target, build hooks execute in the order in which they are defined, starting with global hooks. As an example, for the following configuration: pyproject.toml hatch.toml [tool.hatch.build.targets.foo.hooks.hook2] [tool.hatch.build.hooks.hook3] [tool.hatch.build.hooks.hook1] [build.targets.foo.hooks.hook2] [build.hooks.hook3] [build.hooks.hook1] When target foo is built, build hook hook3 will be executed first, followed by hook1 , and then finally hook2 .","title":"Order of execution"},{"location":"config/build/#conditional-execution","text":"If you want to disable a build hook by default and control its use by environment variables , you can do so by setting the enable-by-default option to false : pyproject.toml hatch.toml [tool.hatch.build.hooks.] enable-by-default = false [build.hooks.] enable-by-default = false","title":"Conditional execution"},{"location":"config/build/#environment-variables","text":"Variable Default Description HATCH_BUILD_CLEAN false Whether or not existing artifacts should first be removed HATCH_BUILD_CLEAN_HOOKS_AFTER false Whether or not build hook artifacts should be removed after each build HATCH_BUILD_HOOKS_ONLY false Whether or not to only execute build hooks HATCH_BUILD_NO_HOOKS false Whether or not to disable all build hooks; this takes precedence over other options HATCH_BUILD_HOOKS_ENABLE false Whether or not to enable all build hooks HATCH_BUILD_HOOK_ENABLE_ false HATCH_BUILD_LOCATION dist The location with which to build the targets; only used by the build command","title":"Environment variables"},{"location":"config/context/","text":"Context formatting \u00b6 You can populate configuration with the values of certain supported fields using the syntax of Python's format strings . Each field interprets the modifier part after the colon differently, if at all. Global fields \u00b6 Any configuration that declares support for context formatting will always support these fields. Paths \u00b6 Field Description root The root project directory home The user's home directory All paths support the following modifiers: Modifier Description uri The normalized absolute URI path prefixed by file: real The path with all symbolic links resolved System separators \u00b6 Field Description / \\ on Windows, / otherwise ; ; on Windows, : otherwise Environment variables \u00b6 The env field and its modifier allow you to select the value of an environment variable. If the environment variable is not set, you must specify a default value as an additional modifier e.g. {env:PATH:DEFAULT} . Field nesting \u00b6 You can insert fields within others. For example, if you wanted a script that displays the value of the environment variable FOO , with a fallback to the environment variable BAR , with its own fallback to the user's home directory, you could do the following: pyproject.toml hatch.toml [tool.hatch.envs.test.scripts] display = \"echo {env:FOO:{env:BAR:{home}}}\" [envs.test.scripts] display = \"echo {env:FOO:{env:BAR:{home}}}\"","title":"Context formatting"},{"location":"config/context/#context-formatting","text":"You can populate configuration with the values of certain supported fields using the syntax of Python's format strings . Each field interprets the modifier part after the colon differently, if at all.","title":"Context formatting"},{"location":"config/context/#global-fields","text":"Any configuration that declares support for context formatting will always support these fields.","title":"Global fields"},{"location":"config/context/#paths","text":"Field Description root The root project directory home The user's home directory All paths support the following modifiers: Modifier Description uri The normalized absolute URI path prefixed by file: real The path with all symbolic links resolved","title":"Paths"},{"location":"config/context/#system-separators","text":"Field Description / \\ on Windows, / otherwise ; ; on Windows, : otherwise","title":"System separators"},{"location":"config/context/#environment-variables","text":"The env field and its modifier allow you to select the value of an environment variable. If the environment variable is not set, you must specify a default value as an additional modifier e.g. {env:PATH:DEFAULT} .","title":"Environment variables"},{"location":"config/context/#field-nesting","text":"You can insert fields within others. For example, if you wanted a script that displays the value of the environment variable FOO , with a fallback to the environment variable BAR , with its own fallback to the user's home directory, you could do the following: pyproject.toml hatch.toml [tool.hatch.envs.test.scripts] display = \"echo {env:FOO:{env:BAR:{home}}}\" [envs.test.scripts] display = \"echo {env:FOO:{env:BAR:{home}}}\"","title":"Field nesting"},{"location":"config/dependency/","text":"Dependency configuration \u00b6 Project dependencies are defined with PEP 508 strings using optional PEP 440 version specifiers . Version specifiers \u00b6 A version specifier consists of a series of version clauses, separated by commas. For example: pyproject.toml [project] ... dependencies = [ \"cryptography\" , \"click>=7, <9, != 8.0.0\" , \"python-dateutil==2.8.*\" , \"numpy~=1.21.4\" , ] The comma is equivalent to a logical AND operator: a candidate version must match all given version clauses in order to match the specifier as a whole. Operators \u00b6 Operators Function ~= Compatible release == Version matching != Version exclusion <= , >= Inclusive ordered comparison < , > Exclusive ordered comparison === Arbitrary equality Version matching \u00b6 A version matching clause includes the version matching operator == and a version identifier. By default, the version matching operator is based on a strict equality comparison: the specified version must be exactly the same as the requested version. Clause Allowed versions ==1 1.0.0 ==1.2 1.2.0 Prefix matching may be requested instead of strict comparison, by appending a trailing .* to the version identifier in the version matching clause. This means that additional trailing segments will be ignored when determining whether or not a version identifier matches the clause. Clause Allowed versions ==1.* >=1.0.0, <2.0.0 ==1.2.* >=1.2.0, <1.3.0 Compatible release \u00b6 A compatible release clause consists of the compatible release operator ~= and a version identifier. It matches any candidate version that is expected to be compatible with the specified version. For a given release identifier V.N , the compatible release clause is approximately equivalent to the following pair of comparison clauses: >= V.N, == V.* This operator cannot be used with a single segment version number such as ~=1 . Clause Allowed versions ~=1.2 >=1.2.0, <2.0.0 ~=1.2.3 >=1.2.3, <1.3.0 Version exclusion \u00b6 A version exclusion clause includes the version exclusion operator != and a version identifier. The allowed version identifiers and comparison semantics are the same as those of the Version matching operator, except that the sense of any match is inverted. Ordered comparison \u00b6 Inclusive comparisons allow for the version identifier part of clauses whereas exclusive comparisons do not. For example, >=1.2 allows for version 1.2.0 while >1.2 does not. Unlike the inclusive ordered comparisons <= and >= , the exclusive ordered comparisons < and > specifically exclude pre-releases, post-releases, and local versions of the specified version. Arbitrary equality \u00b6 Though heavily discouraged, arbitrary equality comparisons allow for simple string matching without any version semantics, for example ===foobar . Environment markers \u00b6 Environment markers allow for dependencies to only be installed when certain conditions are met. For example, if you need to install the latest version of cryptography that is available for a given Python major version you could define the following: cryptography==3.3.2; python_version < \"3\" cryptography>=35.0; python_version > \"3\" Alternatively, if you only need it on Python 3 when running on Windows you could do: cryptography; python_version ~= \"3.0\" and platform_system == \"Windows\" The available environment markers are as follows. Marker Python equivalent Examples os_name import os os.name posix java sys_platform import sys sys.platform linux win32 darwin platform_machine import platform platform.machine() x86_64 platform_python_implementation import platform platform.python_implementation() CPython Jython platform_release import platform platform.release() 1.8.0_51 3.14.1-x86_64-linode39 platform_system import platform platform.system() Linux Windows Darwin platform_version import platform platform.version() 10.0.19041 #1 SMP Fri Apr 2 22:23:49 UTC 2021 python_version import platform '.'.join(platform.python_version_tuple()[:2]) 2.7 3.10 python_full_version import platform platform.python_version() 2.7.18 3.11.0b1 implementation_name import sys sys.implementation.name cpython implementation_version See here 2.7.18 3.11.0b1 Features \u00b6 You can select groups of optional dependencies to install using the extras syntax. For example, if a dependency named foo defined the following: pyproject.toml [project.optional-dependencies] crypto = [ \"PyJWT\" , \"cryptography\" , ] fastjson = [ \"orjson\" , ] cli = [ \"prompt-toolkit\" , \"colorama; platform_system == 'Windows'\" , ] You can select the cli and crypto features like so: foo[cli,crypto]==1.* Note that the features come immediately after the package name, before any version specifiers . Direct references \u00b6 Instead of using normal version specifiers and fetching packages from an index like PyPI , you can define exact sources using direct references with an explicit URI . Direct references are usually not meant to be used for dependencies of a published project but rather are used for defining dependencies for an environment . All direct reference types are prefixed by the package name like: @ Version control systems \u00b6 Various version control systems (VCS) are supported as long as the associated executable is available along your PATH . VCS direct references are defined using one of the following formats: @ :// @ ://@ You may also append a #subdirectory= component for specifying the relative path to the Python package when it is not located at the root e.g. #subdirectory=lib/foo . For more information, refer to this . Supported VCS \u00b6 Git Mercurial Subversion Bazaar Executable Schemes Revisions Example git git+file git+https git+ssh git+http git+git git Commit hash Tag name Branch name proj @ git+https://github.com/org/proj.git@v1 Executable Schemes Revisions Example hg hg+file hg+https hg+ssh hg+http hg+static-http Revision hash Revision number Tag name Branch name proj @ hg+file:///path/to/proj@v1 Executable Schemes Revisions Example svn svn+https svn+ssh svn+http svn+svn svn Revision number proj @ svn+file:///path/to/proj Executable Schemes Revisions Example bzr bzr+https bzr+ssh bzr+sftp bzr+lp bzr+http bzr+ftp Revision number Tag name proj @ bzr+lp:proj@v1 Local \u00b6 You can install local packages with the file scheme in the following format: @ file:/// The is only used on Windows systems, where it can refer to a network share. If omitted it is assumed to be localhost and the third slash must still be present. The can refer to a source archive, a wheel, or a directory containing a Python package. Type Unix Windows Source archive proj @ file:///path/to/pkg.tar.gz proj @ file:///c:/path/to/pkg.tar.gz Wheel proj @ file:///path/to/pkg.whl proj @ file:///c:/path/to/pkg.whl Directory proj @ file:///path/to/pkg proj @ file:///c:/path/to/pkg Tip You may also specify paths relative to your project's root directory on all platforms by using context formatting : @ {root:uri}/pkg_inside_project @ {root:uri}/../pkg_alongside_project Remote \u00b6 You can install source archives and wheels by simply referring to a URL: black @ https://github.com/psf/black/archive/refs/tags/21.10b0.zip pytorch @ https://download.pytorch.org/whl/cu102/torch-1.10.0%2Bcu102-cp39-cp39-linux_x86_64.whl An expected hash value may be specified by appending a #= component: requests @ https://github.com/psf/requests/archive/refs/tags/v2.26.0.zip#sha256=eb729a757f01c10546ebd179ae2aec852dd0d7f8ada2328ccf4558909d859985 If the hash differs from the expected hash, the installation will fail. It is recommended that only hashes which are unconditionally provided by the latest version of the standard library's hashlib module be used for hashes. As of Python 3.10, that list consists of: md5 sha1 sha224 sha256 sha384 sha512 blake2b blake2s Complex syntax \u00b6 The following is an example that uses features and environment markers : pkg[feature1,feature2] @ ; python_version < \"3.7\" Note that the space before the semicolon is required.","title":"Dependencies"},{"location":"config/dependency/#dependency-configuration","text":"Project dependencies are defined with PEP 508 strings using optional PEP 440 version specifiers .","title":"Dependency configuration"},{"location":"config/dependency/#version-specifiers","text":"A version specifier consists of a series of version clauses, separated by commas. For example: pyproject.toml [project] ... dependencies = [ \"cryptography\" , \"click>=7, <9, != 8.0.0\" , \"python-dateutil==2.8.*\" , \"numpy~=1.21.4\" , ] The comma is equivalent to a logical AND operator: a candidate version must match all given version clauses in order to match the specifier as a whole.","title":"Version specifiers"},{"location":"config/dependency/#operators","text":"Operators Function ~= Compatible release == Version matching != Version exclusion <= , >= Inclusive ordered comparison < , > Exclusive ordered comparison === Arbitrary equality","title":"Operators"},{"location":"config/dependency/#version-matching","text":"A version matching clause includes the version matching operator == and a version identifier. By default, the version matching operator is based on a strict equality comparison: the specified version must be exactly the same as the requested version. Clause Allowed versions ==1 1.0.0 ==1.2 1.2.0 Prefix matching may be requested instead of strict comparison, by appending a trailing .* to the version identifier in the version matching clause. This means that additional trailing segments will be ignored when determining whether or not a version identifier matches the clause. Clause Allowed versions ==1.* >=1.0.0, <2.0.0 ==1.2.* >=1.2.0, <1.3.0","title":"Version matching"},{"location":"config/dependency/#compatible-release","text":"A compatible release clause consists of the compatible release operator ~= and a version identifier. It matches any candidate version that is expected to be compatible with the specified version. For a given release identifier V.N , the compatible release clause is approximately equivalent to the following pair of comparison clauses: >= V.N, == V.* This operator cannot be used with a single segment version number such as ~=1 . Clause Allowed versions ~=1.2 >=1.2.0, <2.0.0 ~=1.2.3 >=1.2.3, <1.3.0","title":"Compatible release"},{"location":"config/dependency/#version-exclusion","text":"A version exclusion clause includes the version exclusion operator != and a version identifier. The allowed version identifiers and comparison semantics are the same as those of the Version matching operator, except that the sense of any match is inverted.","title":"Version exclusion"},{"location":"config/dependency/#ordered-comparison","text":"Inclusive comparisons allow for the version identifier part of clauses whereas exclusive comparisons do not. For example, >=1.2 allows for version 1.2.0 while >1.2 does not. Unlike the inclusive ordered comparisons <= and >= , the exclusive ordered comparisons < and > specifically exclude pre-releases, post-releases, and local versions of the specified version.","title":"Ordered comparison"},{"location":"config/dependency/#arbitrary-equality","text":"Though heavily discouraged, arbitrary equality comparisons allow for simple string matching without any version semantics, for example ===foobar .","title":"Arbitrary equality"},{"location":"config/dependency/#environment-markers","text":"Environment markers allow for dependencies to only be installed when certain conditions are met. For example, if you need to install the latest version of cryptography that is available for a given Python major version you could define the following: cryptography==3.3.2; python_version < \"3\" cryptography>=35.0; python_version > \"3\" Alternatively, if you only need it on Python 3 when running on Windows you could do: cryptography; python_version ~= \"3.0\" and platform_system == \"Windows\" The available environment markers are as follows. Marker Python equivalent Examples os_name import os os.name posix java sys_platform import sys sys.platform linux win32 darwin platform_machine import platform platform.machine() x86_64 platform_python_implementation import platform platform.python_implementation() CPython Jython platform_release import platform platform.release() 1.8.0_51 3.14.1-x86_64-linode39 platform_system import platform platform.system() Linux Windows Darwin platform_version import platform platform.version() 10.0.19041 #1 SMP Fri Apr 2 22:23:49 UTC 2021 python_version import platform '.'.join(platform.python_version_tuple()[:2]) 2.7 3.10 python_full_version import platform platform.python_version() 2.7.18 3.11.0b1 implementation_name import sys sys.implementation.name cpython implementation_version See here 2.7.18 3.11.0b1","title":"Environment markers"},{"location":"config/dependency/#features","text":"You can select groups of optional dependencies to install using the extras syntax. For example, if a dependency named foo defined the following: pyproject.toml [project.optional-dependencies] crypto = [ \"PyJWT\" , \"cryptography\" , ] fastjson = [ \"orjson\" , ] cli = [ \"prompt-toolkit\" , \"colorama; platform_system == 'Windows'\" , ] You can select the cli and crypto features like so: foo[cli,crypto]==1.* Note that the features come immediately after the package name, before any version specifiers .","title":"Features"},{"location":"config/dependency/#direct-references","text":"Instead of using normal version specifiers and fetching packages from an index like PyPI , you can define exact sources using direct references with an explicit URI . Direct references are usually not meant to be used for dependencies of a published project but rather are used for defining dependencies for an environment . All direct reference types are prefixed by the package name like: @ ","title":"Direct references"},{"location":"config/dependency/#version-control-systems","text":"Various version control systems (VCS) are supported as long as the associated executable is available along your PATH . VCS direct references are defined using one of the following formats: @ :// @ ://@ You may also append a #subdirectory= component for specifying the relative path to the Python package when it is not located at the root e.g. #subdirectory=lib/foo . For more information, refer to this .","title":"Version control systems"},{"location":"config/dependency/#supported-vcs","text":"Git Mercurial Subversion Bazaar Executable Schemes Revisions Example git git+file git+https git+ssh git+http git+git git Commit hash Tag name Branch name proj @ git+https://github.com/org/proj.git@v1 Executable Schemes Revisions Example hg hg+file hg+https hg+ssh hg+http hg+static-http Revision hash Revision number Tag name Branch name proj @ hg+file:///path/to/proj@v1 Executable Schemes Revisions Example svn svn+https svn+ssh svn+http svn+svn svn Revision number proj @ svn+file:///path/to/proj Executable Schemes Revisions Example bzr bzr+https bzr+ssh bzr+sftp bzr+lp bzr+http bzr+ftp Revision number Tag name proj @ bzr+lp:proj@v1","title":"Supported VCS"},{"location":"config/dependency/#local","text":"You can install local packages with the file scheme in the following format: @ file:/// The is only used on Windows systems, where it can refer to a network share. If omitted it is assumed to be localhost and the third slash must still be present. The can refer to a source archive, a wheel, or a directory containing a Python package. Type Unix Windows Source archive proj @ file:///path/to/pkg.tar.gz proj @ file:///c:/path/to/pkg.tar.gz Wheel proj @ file:///path/to/pkg.whl proj @ file:///c:/path/to/pkg.whl Directory proj @ file:///path/to/pkg proj @ file:///c:/path/to/pkg Tip You may also specify paths relative to your project's root directory on all platforms by using context formatting : @ {root:uri}/pkg_inside_project @ {root:uri}/../pkg_alongside_project","title":"Local"},{"location":"config/dependency/#remote","text":"You can install source archives and wheels by simply referring to a URL: black @ https://github.com/psf/black/archive/refs/tags/21.10b0.zip pytorch @ https://download.pytorch.org/whl/cu102/torch-1.10.0%2Bcu102-cp39-cp39-linux_x86_64.whl An expected hash value may be specified by appending a #= component: requests @ https://github.com/psf/requests/archive/refs/tags/v2.26.0.zip#sha256=eb729a757f01c10546ebd179ae2aec852dd0d7f8ada2328ccf4558909d859985 If the hash differs from the expected hash, the installation will fail. It is recommended that only hashes which are unconditionally provided by the latest version of the standard library's hashlib module be used for hashes. As of Python 3.10, that list consists of: md5 sha1 sha224 sha256 sha384 sha512 blake2b blake2s","title":"Remote"},{"location":"config/dependency/#complex-syntax","text":"The following is an example that uses features and environment markers : pkg[feature1,feature2] @ ; python_version < \"3.7\" Note that the space before the semicolon is required.","title":"Complex syntax"},{"location":"config/hatch/","text":"Hatch configuration \u00b6 Configuration for Hatch itself is stored in a config.toml file located by default in one of the following platform-specific directories. Platform Path macOS ~/Library/Preferences/hatch Windows %USERPROFILE%\\AppData\\Local\\hatch Unix $XDG_CONFIG_HOME/hatch (the XDG_CONFIG_HOME environment variable default is ~/.config ) You can select a custom path to the file using the --config root option or by setting the HATCH_CONFIG environment variable. The file can be managed by the config command group. Mode \u00b6 The mode key controls how Hatch selects the project to work on. Local \u00b6 config.toml mode = \"local\" By default, Hatch will look for a pyproject.toml or setup.py file in the current working directory and any parent directories. The directory storing the first found file will be considered the project root. Project \u00b6 config.toml mode = \"project\" project = \"proj1\" [projects] proj1 = \"/path/to/project1\" proj2 = { \"location\" : \"/path/to/project2\" } [dirs] project = [ \"/path/to/monorepo1\" , \"/path/to/monorepo2\" ] In this mode, Hatch will only work on the selected project . The project is located using multiple heuristics: If the project is defined in the projects table then it must be a string, or an inline table with a location key, that is the full path to the project. If the project matches a subdirectory in any of the directories listed in dirs.project , then that will be used as the project root. An error will occur if the project cannot be found. You can use the config set command to change the project you are working on: $ hatch config set project proj2 New setting: project = \"proj2\" The project can be selected on a per-command basis with the -p / --project (environment variable HATCH_PROJECT ) root option . Aware \u00b6 config.toml mode = \"aware\" This is essentially the local mode with a fallback to the project mode. Shell \u00b6 You can control the shell used to enter environments with the shell key. If defined as a string, it must be the name of one of the supported shells and be available along your PATH . config.toml shell = \"fish\" If the executable name of your shell differs from the supported name, you can define the shell as a table with name and path keys. config.toml [shell] name = \"bash\" path = \"/bin/ash\" You can change the default arguments used to spawn most shells with the args key. The default for such supported shells is usually [\"-i\"] . config.toml [shell] name = \"bash\" args = [ \"--login\" ] Supported \u00b6 Shell Name Arguments macOS Windows Unix Almquist shell ash [\"-i\"] Bash bash [\"-i\"] Command Prompt cmd C shell csh [\"-i\"] fish fish [\"-i\"] Nushell nu [] PowerShell pwsh , powershell tcsh tcsh [\"-i\"] xonsh xonsh [\"-i\"] Z shell zsh [\"-i\"] Default \u00b6 Hatch will attempt to use the current shell based on parent processes. If the shell cannot be determined, then on Windows systems Hatch will use the SHELL environment variable, if present, followed by the COMSPEC environment variable, defaulting to cmd . On all other platforms only the SHELL environment variable will be used, defaulting to bash . Directories \u00b6 Data \u00b6 config.toml [dirs] data = \"...\" This is the directory that is used to persist data. By default it is set to one of the following platform-specific directories. Platform Path macOS ~/Library/Application Support/hatch Windows %USERPROFILE%\\AppData\\Local\\hatch Unix $XDG_DATA_HOME/hatch (the XDG_DATA_HOME environment variable default is ~/.local/share ) You can select a custom path to the directory using the --data-dir root option or by setting the HATCH_DATA_DIR environment variable. Cache \u00b6 config.toml [dirs] cache = \"...\" This is the directory that is used to cache data. By default it is set to one of the following platform-specific directories. Platform Path macOS ~/Library/Caches/hatch Windows %USERPROFILE%\\AppData\\Local\\hatch\\Cache Unix $XDG_CACHE_HOME/hatch (the XDG_CACHE_HOME environment variable default is ~/.cache ) You can select a custom path to the directory using the --cache-dir root option or by setting the HATCH_CACHE_DIR environment variable. Environments \u00b6 config.toml [dirs.env] < ENV_TYPE > = \"...\" This determines where to store environments, with every key being the type of environment and the value being the desired storage location. For example, if you wanted to store virtual environments in a .virtualenvs directory within your home directory, you could specify the following: config.toml [dirs.env] virtual = \"~/.virtualenvs\" Any environment variables are also expanded. If the path is not absolute, then it will be relative to the project root. Any type of environment that is not explicitly defined will default to /env/ . Python installations \u00b6 config.toml [dirs] python = \"...\" This determines where to install specific versions of Python, with the full path being /pythons . The following values have special meanings. Value Path isolated (default) /pythons shared ~/.pythons Terminal \u00b6 You can configure how all output is displayed using the terminal.styles table. These settings are also applied to all plugins. config.toml [terminal.styles] error = \"...\" ... Cross-platform terminal capabilities are provided by Rich . Output levels \u00b6 The levels of output are as follows. Note that the verbosity indicates the minimum level at which the output is displayed. Level Default Verbosity Description debug bold 1 - 3 Messages that are not useful for most user experiences error bold red -2 Messages indicating some unrecoverable error info bold 0 Messages conveying basic information success bold cyan 0 Messages indicating some positive outcome waiting bold magenta 0 Messages shown before potentially time consuming operations warning bold yellow -1 Messages conveying important information See the documentation and color reference for guidance on valid values. Spinner \u00b6 You can select the sequence used for waiting animations with the spinner option. config.toml [terminal.styles] spinner = \"...\"","title":"Hatch"},{"location":"config/hatch/#hatch-configuration","text":"Configuration for Hatch itself is stored in a config.toml file located by default in one of the following platform-specific directories. Platform Path macOS ~/Library/Preferences/hatch Windows %USERPROFILE%\\AppData\\Local\\hatch Unix $XDG_CONFIG_HOME/hatch (the XDG_CONFIG_HOME environment variable default is ~/.config ) You can select a custom path to the file using the --config root option or by setting the HATCH_CONFIG environment variable. The file can be managed by the config command group.","title":"Hatch configuration"},{"location":"config/hatch/#mode","text":"The mode key controls how Hatch selects the project to work on.","title":"Mode"},{"location":"config/hatch/#local","text":"config.toml mode = \"local\" By default, Hatch will look for a pyproject.toml or setup.py file in the current working directory and any parent directories. The directory storing the first found file will be considered the project root.","title":"Local"},{"location":"config/hatch/#project","text":"config.toml mode = \"project\" project = \"proj1\" [projects] proj1 = \"/path/to/project1\" proj2 = { \"location\" : \"/path/to/project2\" } [dirs] project = [ \"/path/to/monorepo1\" , \"/path/to/monorepo2\" ] In this mode, Hatch will only work on the selected project . The project is located using multiple heuristics: If the project is defined in the projects table then it must be a string, or an inline table with a location key, that is the full path to the project. If the project matches a subdirectory in any of the directories listed in dirs.project , then that will be used as the project root. An error will occur if the project cannot be found. You can use the config set command to change the project you are working on: $ hatch config set project proj2 New setting: project = \"proj2\" The project can be selected on a per-command basis with the -p / --project (environment variable HATCH_PROJECT ) root option .","title":"Project"},{"location":"config/hatch/#aware","text":"config.toml mode = \"aware\" This is essentially the local mode with a fallback to the project mode.","title":"Aware"},{"location":"config/hatch/#shell","text":"You can control the shell used to enter environments with the shell key. If defined as a string, it must be the name of one of the supported shells and be available along your PATH . config.toml shell = \"fish\" If the executable name of your shell differs from the supported name, you can define the shell as a table with name and path keys. config.toml [shell] name = \"bash\" path = \"/bin/ash\" You can change the default arguments used to spawn most shells with the args key. The default for such supported shells is usually [\"-i\"] . config.toml [shell] name = \"bash\" args = [ \"--login\" ]","title":"Shell"},{"location":"config/hatch/#supported","text":"Shell Name Arguments macOS Windows Unix Almquist shell ash [\"-i\"] Bash bash [\"-i\"] Command Prompt cmd C shell csh [\"-i\"] fish fish [\"-i\"] Nushell nu [] PowerShell pwsh , powershell tcsh tcsh [\"-i\"] xonsh xonsh [\"-i\"] Z shell zsh [\"-i\"]","title":"Supported"},{"location":"config/hatch/#default","text":"Hatch will attempt to use the current shell based on parent processes. If the shell cannot be determined, then on Windows systems Hatch will use the SHELL environment variable, if present, followed by the COMSPEC environment variable, defaulting to cmd . On all other platforms only the SHELL environment variable will be used, defaulting to bash .","title":"Default"},{"location":"config/hatch/#directories","text":"","title":"Directories"},{"location":"config/hatch/#data","text":"config.toml [dirs] data = \"...\" This is the directory that is used to persist data. By default it is set to one of the following platform-specific directories. Platform Path macOS ~/Library/Application Support/hatch Windows %USERPROFILE%\\AppData\\Local\\hatch Unix $XDG_DATA_HOME/hatch (the XDG_DATA_HOME environment variable default is ~/.local/share ) You can select a custom path to the directory using the --data-dir root option or by setting the HATCH_DATA_DIR environment variable.","title":"Data"},{"location":"config/hatch/#cache","text":"config.toml [dirs] cache = \"...\" This is the directory that is used to cache data. By default it is set to one of the following platform-specific directories. Platform Path macOS ~/Library/Caches/hatch Windows %USERPROFILE%\\AppData\\Local\\hatch\\Cache Unix $XDG_CACHE_HOME/hatch (the XDG_CACHE_HOME environment variable default is ~/.cache ) You can select a custom path to the directory using the --cache-dir root option or by setting the HATCH_CACHE_DIR environment variable.","title":"Cache"},{"location":"config/hatch/#environments","text":"config.toml [dirs.env] < ENV_TYPE > = \"...\" This determines where to store environments, with every key being the type of environment and the value being the desired storage location. For example, if you wanted to store virtual environments in a .virtualenvs directory within your home directory, you could specify the following: config.toml [dirs.env] virtual = \"~/.virtualenvs\" Any environment variables are also expanded. If the path is not absolute, then it will be relative to the project root. Any type of environment that is not explicitly defined will default to /env/ .","title":"Environments"},{"location":"config/hatch/#python-installations","text":"config.toml [dirs] python = \"...\" This determines where to install specific versions of Python, with the full path being /pythons . The following values have special meanings. Value Path isolated (default) /pythons shared ~/.pythons","title":"Python installations"},{"location":"config/hatch/#terminal","text":"You can configure how all output is displayed using the terminal.styles table. These settings are also applied to all plugins. config.toml [terminal.styles] error = \"...\" ... Cross-platform terminal capabilities are provided by Rich .","title":"Terminal"},{"location":"config/hatch/#output-levels","text":"The levels of output are as follows. Note that the verbosity indicates the minimum level at which the output is displayed. Level Default Verbosity Description debug bold 1 - 3 Messages that are not useful for most user experiences error bold red -2 Messages indicating some unrecoverable error info bold 0 Messages conveying basic information success bold cyan 0 Messages indicating some positive outcome waiting bold magenta 0 Messages shown before potentially time consuming operations warning bold yellow -1 Messages conveying important information See the documentation and color reference for guidance on valid values.","title":"Output levels"},{"location":"config/hatch/#spinner","text":"You can select the sequence used for waiting animations with the spinner option. config.toml [terminal.styles] spinner = \"...\"","title":"Spinner"},{"location":"config/metadata/","text":"Project metadata \u00b6 Project metadata is stored in a pyproject.toml file located at the root of a project's tree and is based entirely on PEP 621 . Name ( required ) \u00b6 The name of the project. pyproject.toml [project] name = \"your-app\" Version ( required ) \u00b6 pyproject.toml Dynamic Static See the dedicated versioning section. [project] ... dynamic = [ \"version\" ] [tool.hatch.version] path = \"...\" [project] ... version = \"0.0.1\" Description \u00b6 A brief summary of the project. pyproject.toml [project] ... description = '...' Readme \u00b6 The full description of the project. pyproject.toml Simple Complex The file extension must be .md , .rst , or .txt . [project] ... readme = \"README.md\" The content-type field must be set to text/markdown , text/x-rst , or text/plain . File Text A charset field may also be set to instruct which encoding to use for reading the file, defaulting to utf-8 . [project] ... readme = { \"file\" = \"README.md\" , \"content-type\" = \"text/markdown\" } The content-type field must be set to text/markdown or text/x-rst . [project] ... readme = { \"text\" = \"...\" , \"content-type\" = \"text/markdown\" } Note If this is defined as a file, then it will always be included in source distributions for consistent builds. Python support \u00b6 The Python version requirements of the project. pyproject.toml [project] ... requires-python = \">=3.8\" License \u00b6 For more information, see PEP 639 . pyproject.toml SPDX expression Files [project] ... license = \"Apache-2.0 OR MIT\" Paths Globs [project] ... license-files = { paths = [ \"LICENSE.txt\" ] } [project] ... license-files = { globs = [ \"LICENSES/*\" ] } Ownership \u00b6 The people or organizations considered to be the authors or maintainers of the project. The exact meaning is open to interpretation; it may list the original or primary authors, current maintainers, or owners of the package. If the values are the same, prefer only the use of the authors field. pyproject.toml [project] ... authors = [ { name = \"...\" , email = \"...\" }, ] maintainers = [ { name = \"...\" , email = \"...\" }, ] Keywords \u00b6 The keywords used to assist in the discovery of the project. pyproject.toml [project] ... keywords = [ \"...\" , ] Classifiers \u00b6 The trove classifiers that apply to the project. pyproject.toml [project] ... classifiers = [ \"...\" , ] URLs \u00b6 A table of URLs where the key is the URL label and the value is the URL itself. pyproject.toml [project.urls] Documentation = \"...\" \"Source code\" = \"...\" Dependencies \u00b6 The format is based on PEP 631 . See the dependency specification section for more information. Entries support context formatting and disallow direct references by default. Required \u00b6 pyproject.toml [project] ... dependencies = [ \"...\" , ] Optional \u00b6 pyproject.toml [project.optional-dependencies] option1 = [ \"...\" , ] option2 = [ \"...\" , ] Entry points \u00b6 Entry points are a mechanism for the project to advertise components it provides to be discovered and used by other code. CLI \u00b6 After installing projects that define CLI scripts, each key will be available along your PATH as a command that will call its associated object. pyproject.toml [project.scripts] cli-name = \"pkg.subpkg:func\" Using the above example, running cli-name would essentially execute the following Python script: import sys from pkg.subpkg import func sys . exit ( func ()) GUI \u00b6 GUI scripts are exactly the same as CLI scripts except on Windows, where they are handled specially so that they can be started without a console. pyproject.toml [project.gui-scripts] gui-name = \"pkg.subpkg:func\" Plugins \u00b6 pyproject.toml [project.entry-points.plugin-namespace] plugin-name1 = \"pkg.subpkg1\" plugin-name2 = \"pkg.subpkg2:func\" Metadata options \u00b6 Allowing direct references \u00b6 By default, dependencies are not allowed to define direct references . To disable this check, set allow-direct-references to true : pyproject.toml hatch.toml [tool.hatch.metadata] allow-direct-references = true [metadata] allow-direct-references = true","title":"Metadata"},{"location":"config/metadata/#project-metadata","text":"Project metadata is stored in a pyproject.toml file located at the root of a project's tree and is based entirely on PEP 621 .","title":"Project metadata"},{"location":"config/metadata/#name","text":"The name of the project. pyproject.toml [project] name = \"your-app\"","title":"Name (required)"},{"location":"config/metadata/#version","text":"pyproject.toml Dynamic Static See the dedicated versioning section. [project] ... dynamic = [ \"version\" ] [tool.hatch.version] path = \"...\" [project] ... version = \"0.0.1\"","title":"Version (required)"},{"location":"config/metadata/#description","text":"A brief summary of the project. pyproject.toml [project] ... description = '...'","title":"Description"},{"location":"config/metadata/#readme","text":"The full description of the project. pyproject.toml Simple Complex The file extension must be .md , .rst , or .txt . [project] ... readme = \"README.md\" The content-type field must be set to text/markdown , text/x-rst , or text/plain . File Text A charset field may also be set to instruct which encoding to use for reading the file, defaulting to utf-8 . [project] ... readme = { \"file\" = \"README.md\" , \"content-type\" = \"text/markdown\" } The content-type field must be set to text/markdown or text/x-rst . [project] ... readme = { \"text\" = \"...\" , \"content-type\" = \"text/markdown\" } Note If this is defined as a file, then it will always be included in source distributions for consistent builds.","title":"Readme"},{"location":"config/metadata/#python-support","text":"The Python version requirements of the project. pyproject.toml [project] ... requires-python = \">=3.8\"","title":"Python support"},{"location":"config/metadata/#license","text":"For more information, see PEP 639 . pyproject.toml SPDX expression Files [project] ... license = \"Apache-2.0 OR MIT\" Paths Globs [project] ... license-files = { paths = [ \"LICENSE.txt\" ] } [project] ... license-files = { globs = [ \"LICENSES/*\" ] }","title":"License"},{"location":"config/metadata/#ownership","text":"The people or organizations considered to be the authors or maintainers of the project. The exact meaning is open to interpretation; it may list the original or primary authors, current maintainers, or owners of the package. If the values are the same, prefer only the use of the authors field. pyproject.toml [project] ... authors = [ { name = \"...\" , email = \"...\" }, ] maintainers = [ { name = \"...\" , email = \"...\" }, ]","title":"Ownership"},{"location":"config/metadata/#keywords","text":"The keywords used to assist in the discovery of the project. pyproject.toml [project] ... keywords = [ \"...\" , ]","title":"Keywords"},{"location":"config/metadata/#classifiers","text":"The trove classifiers that apply to the project. pyproject.toml [project] ... classifiers = [ \"...\" , ]","title":"Classifiers"},{"location":"config/metadata/#urls","text":"A table of URLs where the key is the URL label and the value is the URL itself. pyproject.toml [project.urls] Documentation = \"...\" \"Source code\" = \"...\"","title":"URLs"},{"location":"config/metadata/#dependencies","text":"The format is based on PEP 631 . See the dependency specification section for more information. Entries support context formatting and disallow direct references by default.","title":"Dependencies"},{"location":"config/metadata/#required","text":"pyproject.toml [project] ... dependencies = [ \"...\" , ]","title":"Required"},{"location":"config/metadata/#optional","text":"pyproject.toml [project.optional-dependencies] option1 = [ \"...\" , ] option2 = [ \"...\" , ]","title":"Optional"},{"location":"config/metadata/#entry-points","text":"Entry points are a mechanism for the project to advertise components it provides to be discovered and used by other code.","title":"Entry points"},{"location":"config/metadata/#cli","text":"After installing projects that define CLI scripts, each key will be available along your PATH as a command that will call its associated object. pyproject.toml [project.scripts] cli-name = \"pkg.subpkg:func\" Using the above example, running cli-name would essentially execute the following Python script: import sys from pkg.subpkg import func sys . exit ( func ())","title":"CLI"},{"location":"config/metadata/#gui","text":"GUI scripts are exactly the same as CLI scripts except on Windows, where they are handled specially so that they can be started without a console. pyproject.toml [project.gui-scripts] gui-name = \"pkg.subpkg:func\"","title":"GUI"},{"location":"config/metadata/#plugins","text":"pyproject.toml [project.entry-points.plugin-namespace] plugin-name1 = \"pkg.subpkg1\" plugin-name2 = \"pkg.subpkg2:func\"","title":"Plugins"},{"location":"config/metadata/#metadata-options","text":"","title":"Metadata options"},{"location":"config/metadata/#allowing-direct-references","text":"By default, dependencies are not allowed to define direct references . To disable this check, set allow-direct-references to true : pyproject.toml hatch.toml [tool.hatch.metadata] allow-direct-references = true [metadata] allow-direct-references = true","title":"Allowing direct references"},{"location":"config/project-templates/","text":"Project templates \u00b6 You can control how new projects are created by the new command using Hatch's config file . Author \u00b6 config.toml [template] name = \"...\" email = \"...\" Licenses \u00b6 config.toml [template.licenses] headers = true default = [ \"MIT\" , ] The list of licenses should be composed of SPDX identifiers . If multiple licenses are specified, then they will be placed in a LICENSES directory. Options \u00b6 Tests \u00b6 This adds a tests directory with pytest functionality. config.toml [template.plugins.default] tests = true CI \u00b6 This adds a GitHub Actions workflow that runs tests on all platforms using modern versions of Python. config.toml [template.plugins.default] ci = false src layout \u00b6 See this blog post . config.toml [template.plugins.default] src-layout = false Feature flags \u00b6 Command line interface \u00b6 The --cli flag adds a CLI backed by Click that can also be invoked with python -m .","title":"Project templates"},{"location":"config/project-templates/#project-templates","text":"You can control how new projects are created by the new command using Hatch's config file .","title":"Project templates"},{"location":"config/project-templates/#author","text":"config.toml [template] name = \"...\" email = \"...\"","title":"Author"},{"location":"config/project-templates/#licenses","text":"config.toml [template.licenses] headers = true default = [ \"MIT\" , ] The list of licenses should be composed of SPDX identifiers . If multiple licenses are specified, then they will be placed in a LICENSES directory.","title":"Licenses"},{"location":"config/project-templates/#options","text":"","title":"Options"},{"location":"config/project-templates/#tests","text":"This adds a tests directory with pytest functionality. config.toml [template.plugins.default] tests = true","title":"Tests"},{"location":"config/project-templates/#ci","text":"This adds a GitHub Actions workflow that runs tests on all platforms using modern versions of Python. config.toml [template.plugins.default] ci = false","title":"CI"},{"location":"config/project-templates/#src-layout","text":"See this blog post . config.toml [template.plugins.default] src-layout = false","title":"src layout"},{"location":"config/project-templates/#feature-flags","text":"","title":"Feature flags"},{"location":"config/project-templates/#command-line-interface","text":"The --cli flag adds a CLI backed by Click that can also be invoked with python -m .","title":"Command line interface"},{"location":"config/environment/advanced/","text":"Advanced environment configuration \u00b6 Context formatting \u00b6 All environments support the following extra context formatting fields: Field Description env_name The name of the environment env_type The type of environment matrix Its modifier selects the value of that matrix variable. If the environment is not part of a matrix or was not generated with the variable, you must specify a default value as an additional modifier e.g. {matrix:version:v1.0.0} . verbosity The integer verbosity value of Hatch. A flag modifier is supported that will render the value as a CLI flag e.g. -2 becomes -qq , 1 becomes -v , and 0 becomes an empty string. An additional flag integer modifier may be used to adjust the verbosity level. For example, if you wanted to make a command quiet by default, you could use {verbosity:flag:-1} within the command. args For executed commands only, any extra command line arguments with an optional default modifier if none were provided Matrix \u00b6 Environments can define a series of matrices with the matrix option: pyproject.toml hatch.toml [tool.hatch.envs.test] dependencies = [ \"pytest\" ] [[tool.hatch.envs.test.matrix]] python = [ \"27\" , \"38\" ] version = [ \"42\" , \"3.14\" ] [[tool.hatch.envs.test.matrix]] python = [ \"38\" , \"39\" ] version = [ \"9000\" ] feature = [ \"foo\" , \"bar\" ] [envs.test] dependencies = [ \"pytest\" ] [[envs.test.matrix]] python = [ \"27\" , \"38\" ] version = [ \"42\" , \"3.14\" ] [[envs.test.matrix]] python = [ \"38\" , \"39\" ] version = [ \"9000\" ] feature = [ \"foo\" , \"bar\" ] Doing so will result in the product of each variable combination being its own environment. Naming \u00b6 The name of the generated environments will be the variable values of each combination separated by hyphens, altogether prefixed by . . For example, the following configuration: pyproject.toml hatch.toml [[tool.hatch.envs.test.matrix]] version = [ \"42\" ] feature = [ \"foo\" , \"bar\" ] [[envs.test.matrix]] version = [ \"42\" ] feature = [ \"foo\" , \"bar\" ] would indicate the following unique environments: test.42-foo test.42-bar The exceptions to this format are described below. Python variables \u00b6 If the variables py or python are specified, then they will rank first in the product result and will be prefixed by py if the value is not. For example, the following configuration: pyproject.toml hatch.toml [[tool.hatch.envs.test.matrix]] version = [ \"42\" ] python = [ \"39\" , \"pypy3\" ] [[envs.test.matrix]] version = [ \"42\" ] python = [ \"39\" , \"pypy3\" ] would generate the following environments: test.py39-42 test.pypy3-42 Note The value of this variable sets the Python version . Name formatting \u00b6 You can set the matrix-name-format option to modify how each variable part is formatted which recognizes the placeholders {variable} and {value} . For example, the following configuration: pyproject.toml hatch.toml [tool.hatch.envs.test] matrix-name-format = \"{variable}_{value}\" [[tool.hatch.envs.test.matrix]] version = [ \"42\" ] feature = [ \"foo\" , \"bar\" ] [envs.test] matrix-name-format = \"{variable}_{value}\" [[envs.test.matrix]] version = [ \"42\" ] feature = [ \"foo\" , \"bar\" ] would produce the following environments: test.version_42-feature_foo test.version_42-feature_bar By default this option is set to {value} . Default environment \u00b6 If the default environment defines matrices, then the generated names will not be prefixed by the environment name. This can be useful for projects that only need a single series of matrices without any standalone environments. Selection \u00b6 Rather than selecting a single generated environment, you can select the root environment to target all of them. For example, if you have the following configuration: pyproject.toml hatch.toml [tool.hatch.envs.test] dependencies = [ \"coverage[toml]\" , \"pytest\" , \"pytest-cov\" , ] [tool.hatch.envs.test.scripts] cov = 'pytest --cov-report=term-missing --cov-config=pyproject.toml --cov=pkg --cov=tests' [[tool.hatch.envs.test.matrix]] python = [ \"27\" , \"38\" ] version = [ \"42\" , \"3.14\" ] [envs.test] dependencies = [ \"coverage[toml]\" , \"pytest\" , \"pytest-cov\" , ] [envs.test.scripts] cov = 'pytest --cov-report=term-missing --cov-config=pyproject.toml --cov=pkg --cov=tests' [[envs.test.matrix]] python = [ \"27\" , \"38\" ] version = [ \"42\" , \"3.14\" ] you could then run your tests consecutively in all 4 environments with: hatch run test:cov Option overrides \u00b6 You can modify options based on the conditions of different sources like matrix variables with the overrides table, using dotted key syntax for each declaration: pyproject.toml hatch.toml [tool.hatch.envs..overrides] < SOURCE > . < CONDITION > . < OPTION > = < VALUE > [envs..overrides] < SOURCE > . < CONDITION > . < OPTION > = < VALUE > The type of the selected option determines the types of values. Platform overrides \u00b6 Options can be modified based on the current platform using the platform source. pyproject.toml hatch.toml [tool.hatch.envs.test.overrides] platform . windows . scripts = [ 'run=pytest -m \"not io_uring\"' , ] [envs.test.overrides] platform . windows . scripts = [ 'run=pytest -m \"not io_uring\"' , ] The following platforms are supported: linux windows macos Environment variable overrides \u00b6 Environment variables can modify options using the env source. pyproject.toml hatch.toml [tool.hatch.envs.test.overrides] env . GITHUB_ACTIONS . dev-mode = { value = false , if = [ \"true\" ] } [envs.test.overrides] env . GITHUB_ACTIONS . dev-mode = { value = false , if = [ \"true\" ] } Matrix variable overrides \u00b6 The matrix variables used to generate each environment can be used to modify options within using the matrix source. pyproject.toml hatch.toml [tool.hatch.envs.test.overrides] matrix . version . env-vars = \"PRODUCT_VERSION\" matrix . auth . features = [ { value = \"oauth\" , if = [ \"oauth2\" ] }, { value = \"kerberos\" , if = [ \"krb5\" ] }, ] [[tool.hatch.envs.test.matrix]] python = [ \"27\" , \"38\" ] version = [ \"legacy\" , \"latest\" ] auth = [ \"oauth2\" , \"krb5\" , \"noauth\" ] [envs.test.overrides] matrix . version . env-vars = \"PRODUCT_VERSION\" matrix . auth . features = [ { value = \"oauth\" , if = [ \"oauth2\" ] }, { value = \"kerberos\" , if = [ \"kerberos\" ] }, ] [[envs.test.matrix]] python = [ \"27\" , \"38\" ] version = [ \"legacy\" , \"latest\" ] auth = [ \"oauth2\" , \"kerberos\" , \"noauth\" ] Name overrides \u00b6 When a matrix is defined, the name source can be used for regular expression matching on the generated name, minus the prefix for non- default environments. pyproject.toml hatch.toml [tool.hatch.envs.test.overrides] name . \"^0\" . env-vars = \"TESTING_UNSTABLE=true\" [[tool.hatch.envs.test.matrix]] version = [ \"0.1.0\" , \"0.2.0\" , \"1.0.0\" ] [envs.test.overrides] name . \"^0\" . env-vars = \"TESTING_UNSTABLE=true\" [[envs.test.matrix]] version = [ \"0.1.0\" , \"0.2.0\" , \"1.0.0\" ] Types \u00b6 Literal types like strings for the Python version or booleans for skipping installation can be set using the value itself, an inline table, or an array. For example: pyproject.toml hatch.toml [tool.hatch.envs.test.overrides] matrix . foo . python = \"310\" matrix . bar . skip-install = { value = true , if = [ \"...\" ] } env . CI . dev-mode = [ { value = false , if = [ \"...\" ] }, true , ] [envs.test.overrides] matrix . foo . python = \"310\" matrix . bar . skip-install = { value = true , if = [ \"...\" ] } env . CI . dev-mode = [ { value = false , if = [ \"...\" ] }, true , ] For arrays, the first allowed value will be used. Array types like dependencies or commands can be appended to using an array of strings or inline tables. For example: pyproject.toml hatch.toml [tool.hatch.envs.test.overrides] matrix . foo . dependencies = [ \"httpx\" , { value = \"cryptography\" }, ] [envs.test.overrides] matrix . foo . dependencies = [ \"httpx\" , { value = \"cryptography\" }, ] Mapping types like environment variables or scripts can have keys set using a string, or an array of strings or inline tables. For example: pyproject.toml hatch.toml [tool.hatch.envs.test.overrides] matrix . foo . env-vars = \"KEY=VALUE\" matrix . bar . env-vars = [ \"KEY1=VALUE1\" , { key = \"KEY2\" , value = \"VALUE2\" }, ] [envs.test.overrides] matrix . foo . env-vars = \"KEY=VALUE\" matrix . bar . env-vars = [ \"KEY1=VALUE1\" , { key = \"KEY2\" , value = \"VALUE2\" }, ] If the value is missing (no = for strings, no value key for inline tables), then the value will be set to the value of the source condition. Overwriting \u00b6 Rather than supplementing the values within mapping types or array types, you can overwrite the option as a whole by prefixing the name with set- : pyproject.toml hatch.toml [tool.hatch.envs.test.overrides] matrix . foo . set-platforms = [ \"macos\" , \"linux\" ] [envs.test.overrides] matrix . foo . set-platforms = [ \"macos\" , \"linux\" ] When overwriting entire options or keys within mappings, override sources are applied in the following order: platform environment variables matrix variables names Conditions \u00b6 You may specify certain extra keys for any inline table that will determine whether or not to apply that entry. These modifiers may be combined with others and any negative evaluation will immediately cause the entry to be skipped. Allowed values \u00b6 The if key represents the allowed values for that condition. If the value of the condition is not listed, then that entry will not be applied: pyproject.toml hatch.toml [tool.hatch.envs.test.overrides] matrix . version . python = { value = \"pypy\" , if = [ \"3.14\" ] } matrix . version . env-vars = [ { key = \"KEY1\" , value = \"VALUE1\" , if = [ \"42\" ] }, { key = \"KEY2\" , value = \"VALUE2\" , if = [ \"3.14\" ] }, ] [[tool.hatch.envs.test.matrix]] version = [ \"42\" , \"3.14\" ] [envs.test.overrides] matrix . version . python = { value = \"pypy\" , if = [ \"3.14\" ] } matrix . version . env-vars = [ { key = \"KEY1\" , value = \"VALUE1\" , if = [ \"42\" ] }, { key = \"KEY2\" , value = \"VALUE2\" , if = [ \"3.14\" ] }, ] [[envs.test.matrix]] version = [ \"42\" , \"3.14\" ] Specific platforms \u00b6 The platform key represents the desired platforms. If the current platform is not listed, then that entry will not be applied: pyproject.toml hatch.toml [tool.hatch.envs.test.overrides] env . EXPERIMENTAL . python = { value = \"pypy\" , if = [ \"1\" ], platform = [ \"macos\" ] } matrix . version . env-vars = [ { key = \"KEY1\" , value = \"VALUE1\" , if = [ \"42\" ], platform = [ \"linux\" ] }, { key = \"KEY2\" , value = \"VALUE2\" , if = [ \"3.14\" ] }, ] [[tool.hatch.envs.test.matrix]] version = [ \"42\" , \"3.14\" ] [envs.test.overrides] env . EXPERIMENTAL . python = { value = \"pypy\" , if = [ \"1\" ], platform = [ \"macos\" ] } matrix . version . env-vars = [ { key = \"KEY1\" , value = \"VALUE1\" , if = [ \"42\" ], platform = [ \"linux\" ] }, { key = \"KEY2\" , value = \"VALUE2\" , if = [ \"3.14\" ] }, ] [[envs.test.matrix]] version = [ \"42\" , \"3.14\" ] Required environment variables \u00b6 The env key represents the required environment variables. If any of the listed environment variables are not set or the defined value does not match, then that entry will not be applied: pyproject.toml hatch.toml [tool.hatch.envs.test.overrides] platform . windows . python = { value = \"pypy\" , env = [ \"EXPERIMENTAL\" ] } matrix . version . env-vars = [ { key = \"KEY1\" , value = \"VALUE1\" , if = [ \"42\" ], env = [ \"FOO\" , \"BAR=BAZ\" ] }, { key = \"KEY2\" , value = \"VALUE2\" , if = [ \"3.14\" ] }, ] [[tool.hatch.envs.test.matrix]] version = [ \"42\" , \"3.14\" ] [envs.test.overrides] platform . windows . python = { value = \"pypy\" , env = [ \"EXPERIMENTAL\" ] } matrix . version . env-vars = [ { key = \"KEY1\" , value = \"VALUE1\" , if = [ \"42\" ], env = [ \"FOO\" , \"BAR=BAZ\" ] }, { key = \"KEY2\" , value = \"VALUE2\" , if = [ \"3.14\" ] }, ] [[envs.test.matrix]] version = [ \"42\" , \"3.14\" ]","title":"Advanced"},{"location":"config/environment/advanced/#advanced-environment-configuration","text":"","title":"Advanced environment configuration"},{"location":"config/environment/advanced/#context-formatting","text":"All environments support the following extra context formatting fields: Field Description env_name The name of the environment env_type The type of environment matrix Its modifier selects the value of that matrix variable. If the environment is not part of a matrix or was not generated with the variable, you must specify a default value as an additional modifier e.g. {matrix:version:v1.0.0} . verbosity The integer verbosity value of Hatch. A flag modifier is supported that will render the value as a CLI flag e.g. -2 becomes -qq , 1 becomes -v , and 0 becomes an empty string. An additional flag integer modifier may be used to adjust the verbosity level. For example, if you wanted to make a command quiet by default, you could use {verbosity:flag:-1} within the command. args For executed commands only, any extra command line arguments with an optional default modifier if none were provided","title":"Context formatting"},{"location":"config/environment/advanced/#matrix","text":"Environments can define a series of matrices with the matrix option: pyproject.toml hatch.toml [tool.hatch.envs.test] dependencies = [ \"pytest\" ] [[tool.hatch.envs.test.matrix]] python = [ \"27\" , \"38\" ] version = [ \"42\" , \"3.14\" ] [[tool.hatch.envs.test.matrix]] python = [ \"38\" , \"39\" ] version = [ \"9000\" ] feature = [ \"foo\" , \"bar\" ] [envs.test] dependencies = [ \"pytest\" ] [[envs.test.matrix]] python = [ \"27\" , \"38\" ] version = [ \"42\" , \"3.14\" ] [[envs.test.matrix]] python = [ \"38\" , \"39\" ] version = [ \"9000\" ] feature = [ \"foo\" , \"bar\" ] Doing so will result in the product of each variable combination being its own environment.","title":"Matrix"},{"location":"config/environment/advanced/#naming","text":"The name of the generated environments will be the variable values of each combination separated by hyphens, altogether prefixed by . . For example, the following configuration: pyproject.toml hatch.toml [[tool.hatch.envs.test.matrix]] version = [ \"42\" ] feature = [ \"foo\" , \"bar\" ] [[envs.test.matrix]] version = [ \"42\" ] feature = [ \"foo\" , \"bar\" ] would indicate the following unique environments: test.42-foo test.42-bar The exceptions to this format are described below.","title":"Naming"},{"location":"config/environment/advanced/#python-variables","text":"If the variables py or python are specified, then they will rank first in the product result and will be prefixed by py if the value is not. For example, the following configuration: pyproject.toml hatch.toml [[tool.hatch.envs.test.matrix]] version = [ \"42\" ] python = [ \"39\" , \"pypy3\" ] [[envs.test.matrix]] version = [ \"42\" ] python = [ \"39\" , \"pypy3\" ] would generate the following environments: test.py39-42 test.pypy3-42 Note The value of this variable sets the Python version .","title":"Python variables"},{"location":"config/environment/advanced/#name-formatting","text":"You can set the matrix-name-format option to modify how each variable part is formatted which recognizes the placeholders {variable} and {value} . For example, the following configuration: pyproject.toml hatch.toml [tool.hatch.envs.test] matrix-name-format = \"{variable}_{value}\" [[tool.hatch.envs.test.matrix]] version = [ \"42\" ] feature = [ \"foo\" , \"bar\" ] [envs.test] matrix-name-format = \"{variable}_{value}\" [[envs.test.matrix]] version = [ \"42\" ] feature = [ \"foo\" , \"bar\" ] would produce the following environments: test.version_42-feature_foo test.version_42-feature_bar By default this option is set to {value} .","title":"Name formatting"},{"location":"config/environment/advanced/#default-environment","text":"If the default environment defines matrices, then the generated names will not be prefixed by the environment name. This can be useful for projects that only need a single series of matrices without any standalone environments.","title":"Default environment"},{"location":"config/environment/advanced/#selection","text":"Rather than selecting a single generated environment, you can select the root environment to target all of them. For example, if you have the following configuration: pyproject.toml hatch.toml [tool.hatch.envs.test] dependencies = [ \"coverage[toml]\" , \"pytest\" , \"pytest-cov\" , ] [tool.hatch.envs.test.scripts] cov = 'pytest --cov-report=term-missing --cov-config=pyproject.toml --cov=pkg --cov=tests' [[tool.hatch.envs.test.matrix]] python = [ \"27\" , \"38\" ] version = [ \"42\" , \"3.14\" ] [envs.test] dependencies = [ \"coverage[toml]\" , \"pytest\" , \"pytest-cov\" , ] [envs.test.scripts] cov = 'pytest --cov-report=term-missing --cov-config=pyproject.toml --cov=pkg --cov=tests' [[envs.test.matrix]] python = [ \"27\" , \"38\" ] version = [ \"42\" , \"3.14\" ] you could then run your tests consecutively in all 4 environments with: hatch run test:cov","title":"Selection"},{"location":"config/environment/advanced/#option-overrides","text":"You can modify options based on the conditions of different sources like matrix variables with the overrides table, using dotted key syntax for each declaration: pyproject.toml hatch.toml [tool.hatch.envs..overrides] < SOURCE > . < CONDITION > . < OPTION > = < VALUE > [envs..overrides] < SOURCE > . < CONDITION > . < OPTION > = < VALUE > The type of the selected option determines the types of values.","title":"Option overrides"},{"location":"config/environment/advanced/#platform-overrides","text":"Options can be modified based on the current platform using the platform source. pyproject.toml hatch.toml [tool.hatch.envs.test.overrides] platform . windows . scripts = [ 'run=pytest -m \"not io_uring\"' , ] [envs.test.overrides] platform . windows . scripts = [ 'run=pytest -m \"not io_uring\"' , ] The following platforms are supported: linux windows macos","title":"Platform overrides"},{"location":"config/environment/advanced/#environment-variable-overrides","text":"Environment variables can modify options using the env source. pyproject.toml hatch.toml [tool.hatch.envs.test.overrides] env . GITHUB_ACTIONS . dev-mode = { value = false , if = [ \"true\" ] } [envs.test.overrides] env . GITHUB_ACTIONS . dev-mode = { value = false , if = [ \"true\" ] }","title":"Environment variable overrides"},{"location":"config/environment/advanced/#matrix-variable-overrides","text":"The matrix variables used to generate each environment can be used to modify options within using the matrix source. pyproject.toml hatch.toml [tool.hatch.envs.test.overrides] matrix . version . env-vars = \"PRODUCT_VERSION\" matrix . auth . features = [ { value = \"oauth\" , if = [ \"oauth2\" ] }, { value = \"kerberos\" , if = [ \"krb5\" ] }, ] [[tool.hatch.envs.test.matrix]] python = [ \"27\" , \"38\" ] version = [ \"legacy\" , \"latest\" ] auth = [ \"oauth2\" , \"krb5\" , \"noauth\" ] [envs.test.overrides] matrix . version . env-vars = \"PRODUCT_VERSION\" matrix . auth . features = [ { value = \"oauth\" , if = [ \"oauth2\" ] }, { value = \"kerberos\" , if = [ \"kerberos\" ] }, ] [[envs.test.matrix]] python = [ \"27\" , \"38\" ] version = [ \"legacy\" , \"latest\" ] auth = [ \"oauth2\" , \"kerberos\" , \"noauth\" ]","title":"Matrix variable overrides"},{"location":"config/environment/advanced/#name-overrides","text":"When a matrix is defined, the name source can be used for regular expression matching on the generated name, minus the prefix for non- default environments. pyproject.toml hatch.toml [tool.hatch.envs.test.overrides] name . \"^0\" . env-vars = \"TESTING_UNSTABLE=true\" [[tool.hatch.envs.test.matrix]] version = [ \"0.1.0\" , \"0.2.0\" , \"1.0.0\" ] [envs.test.overrides] name . \"^0\" . env-vars = \"TESTING_UNSTABLE=true\" [[envs.test.matrix]] version = [ \"0.1.0\" , \"0.2.0\" , \"1.0.0\" ]","title":"Name overrides"},{"location":"config/environment/advanced/#types","text":"Literal types like strings for the Python version or booleans for skipping installation can be set using the value itself, an inline table, or an array. For example: pyproject.toml hatch.toml [tool.hatch.envs.test.overrides] matrix . foo . python = \"310\" matrix . bar . skip-install = { value = true , if = [ \"...\" ] } env . CI . dev-mode = [ { value = false , if = [ \"...\" ] }, true , ] [envs.test.overrides] matrix . foo . python = \"310\" matrix . bar . skip-install = { value = true , if = [ \"...\" ] } env . CI . dev-mode = [ { value = false , if = [ \"...\" ] }, true , ] For arrays, the first allowed value will be used. Array types like dependencies or commands can be appended to using an array of strings or inline tables. For example: pyproject.toml hatch.toml [tool.hatch.envs.test.overrides] matrix . foo . dependencies = [ \"httpx\" , { value = \"cryptography\" }, ] [envs.test.overrides] matrix . foo . dependencies = [ \"httpx\" , { value = \"cryptography\" }, ] Mapping types like environment variables or scripts can have keys set using a string, or an array of strings or inline tables. For example: pyproject.toml hatch.toml [tool.hatch.envs.test.overrides] matrix . foo . env-vars = \"KEY=VALUE\" matrix . bar . env-vars = [ \"KEY1=VALUE1\" , { key = \"KEY2\" , value = \"VALUE2\" }, ] [envs.test.overrides] matrix . foo . env-vars = \"KEY=VALUE\" matrix . bar . env-vars = [ \"KEY1=VALUE1\" , { key = \"KEY2\" , value = \"VALUE2\" }, ] If the value is missing (no = for strings, no value key for inline tables), then the value will be set to the value of the source condition.","title":"Types"},{"location":"config/environment/advanced/#overwriting","text":"Rather than supplementing the values within mapping types or array types, you can overwrite the option as a whole by prefixing the name with set- : pyproject.toml hatch.toml [tool.hatch.envs.test.overrides] matrix . foo . set-platforms = [ \"macos\" , \"linux\" ] [envs.test.overrides] matrix . foo . set-platforms = [ \"macos\" , \"linux\" ] When overwriting entire options or keys within mappings, override sources are applied in the following order: platform environment variables matrix variables names","title":"Overwriting"},{"location":"config/environment/advanced/#conditions","text":"You may specify certain extra keys for any inline table that will determine whether or not to apply that entry. These modifiers may be combined with others and any negative evaluation will immediately cause the entry to be skipped.","title":"Conditions"},{"location":"config/environment/advanced/#allowed-values","text":"The if key represents the allowed values for that condition. If the value of the condition is not listed, then that entry will not be applied: pyproject.toml hatch.toml [tool.hatch.envs.test.overrides] matrix . version . python = { value = \"pypy\" , if = [ \"3.14\" ] } matrix . version . env-vars = [ { key = \"KEY1\" , value = \"VALUE1\" , if = [ \"42\" ] }, { key = \"KEY2\" , value = \"VALUE2\" , if = [ \"3.14\" ] }, ] [[tool.hatch.envs.test.matrix]] version = [ \"42\" , \"3.14\" ] [envs.test.overrides] matrix . version . python = { value = \"pypy\" , if = [ \"3.14\" ] } matrix . version . env-vars = [ { key = \"KEY1\" , value = \"VALUE1\" , if = [ \"42\" ] }, { key = \"KEY2\" , value = \"VALUE2\" , if = [ \"3.14\" ] }, ] [[envs.test.matrix]] version = [ \"42\" , \"3.14\" ]","title":"Allowed values"},{"location":"config/environment/advanced/#specific-platforms","text":"The platform key represents the desired platforms. If the current platform is not listed, then that entry will not be applied: pyproject.toml hatch.toml [tool.hatch.envs.test.overrides] env . EXPERIMENTAL . python = { value = \"pypy\" , if = [ \"1\" ], platform = [ \"macos\" ] } matrix . version . env-vars = [ { key = \"KEY1\" , value = \"VALUE1\" , if = [ \"42\" ], platform = [ \"linux\" ] }, { key = \"KEY2\" , value = \"VALUE2\" , if = [ \"3.14\" ] }, ] [[tool.hatch.envs.test.matrix]] version = [ \"42\" , \"3.14\" ] [envs.test.overrides] env . EXPERIMENTAL . python = { value = \"pypy\" , if = [ \"1\" ], platform = [ \"macos\" ] } matrix . version . env-vars = [ { key = \"KEY1\" , value = \"VALUE1\" , if = [ \"42\" ], platform = [ \"linux\" ] }, { key = \"KEY2\" , value = \"VALUE2\" , if = [ \"3.14\" ] }, ] [[envs.test.matrix]] version = [ \"42\" , \"3.14\" ]","title":"Specific platforms"},{"location":"config/environment/advanced/#required-environment-variables","text":"The env key represents the required environment variables. If any of the listed environment variables are not set or the defined value does not match, then that entry will not be applied: pyproject.toml hatch.toml [tool.hatch.envs.test.overrides] platform . windows . python = { value = \"pypy\" , env = [ \"EXPERIMENTAL\" ] } matrix . version . env-vars = [ { key = \"KEY1\" , value = \"VALUE1\" , if = [ \"42\" ], env = [ \"FOO\" , \"BAR=BAZ\" ] }, { key = \"KEY2\" , value = \"VALUE2\" , if = [ \"3.14\" ] }, ] [[tool.hatch.envs.test.matrix]] version = [ \"42\" , \"3.14\" ] [envs.test.overrides] platform . windows . python = { value = \"pypy\" , env = [ \"EXPERIMENTAL\" ] } matrix . version . env-vars = [ { key = \"KEY1\" , value = \"VALUE1\" , if = [ \"42\" ], env = [ \"FOO\" , \"BAR=BAZ\" ] }, { key = \"KEY2\" , value = \"VALUE2\" , if = [ \"3.14\" ] }, ] [[envs.test.matrix]] version = [ \"42\" , \"3.14\" ]","title":"Required environment variables"},{"location":"config/environment/overview/","text":"Environment configuration \u00b6 All environments are defined as sections within the tool.hatch.envs table. pyproject.toml hatch.toml [tool.hatch.envs.] [envs.] The storage location for environments is completely configurable. Unless an environment is explicitly selected on the command line, the default environment will be used. The type of this environment defaults to virtual . Inheritance \u00b6 All environments inherit from the environment defined by its template option, which defaults to default . So for the following configuration: pyproject.toml hatch.toml [tool.hatch.envs.foo] type = \"baz\" skip-install = true [tool.hatch.envs.bar] template = \"foo\" skip-install = false [envs.foo] type = \"baz\" skip-install = true [envs.bar] template = \"foo\" skip-install = false the environment bar will be of type baz with skip-install set to false . Note Environments do not inherit matrices . Self-referential environments \u00b6 You can disable inheritance by setting template to the environment's own name: pyproject.toml hatch.toml [tool.hatch.envs.foo] template = \"foo\" [envs.foo] template = \"foo\" Detached environments \u00b6 A common use case is standalone environments that do not require inheritance nor the installation of the project, such as for linting or sometimes building documentation. Enabling the detached option will make the environment self-referential and will skip project installation : pyproject.toml hatch.toml [tool.hatch.envs.lint] detached = true [envs.lint] detached = true Dependencies \u00b6 You can install dependencies in addition to the ones defined by your project's metadata . Entries support context formatting . pyproject.toml hatch.toml [tool.hatch.envs.test] dependencies = [ \"coverage[toml]\" , \"pytest\" , \"pytest-cov\" , \"pytest-mock\" , ] [envs.test] dependencies = [ \"coverage[toml]\" , \"pytest\" , \"pytest-cov\" , \"pytest-mock\" , ] If you define environments with dependencies that only slightly differ from their inherited environments , you can use the extra-dependencies option to avoid redeclaring the dependencies option: pyproject.toml hatch.toml [tool.hatch.envs.default] dependencies = [ \"foo\" , \"bar\" , ] [tool.hatch.envs.experimental] extra-dependencies = [ \"baz\" , ] [envs.default] dependencies = [ \"foo\" , \"bar\" , ] [envs.experimental] extra-dependencies = [ \"baz\" , ] Tip Hatch uses pip to install dependencies so any configuration it supports Hatch does as well. For example, if you wanted to only use a private repository you could set the PIP_INDEX_URL environment variable . Installation \u00b6 Features \u00b6 If your project defines optional dependencies , you can select which groups to install using the features option: pyproject.toml hatch.toml [tool.hatch.envs.nightly] features = [ \"server\" , \"grpc\" , ] [envs.nightly] features = [ \"server\" , \"grpc\" , ] Dev mode \u00b6 By default, environments will always reflect the current state of your project on disk. Set dev-mode to false to disable this behavior: pyproject.toml hatch.toml [tool.hatch.envs.static] dev-mode = false [envs.static] dev-mode = false Skip install \u00b6 By default, environments will install your project during creation. To ignore this step, set skip-install to true : pyproject.toml hatch.toml [tool.hatch.envs.lint] skip-install = true [envs.lint] skip-install = true Environment variables \u00b6 Defined \u00b6 You can define environment variables with the env-vars option: pyproject.toml hatch.toml [tool.hatch.envs.docs] dependencies = [ \"mkdocs\" ] [tool.hatch.envs.docs.env-vars] SOURCE_DATE_EPOCH = \"1580601600\" [envs.docs] dependencies = [ \"mkdocs\" ] [envs.docs.env-vars] SOURCE_DATE_EPOCH = \"1580601600\" Values support context formatting . Filters \u00b6 By default, environments will have access to all environment variables. You can filter with wildcard patterns using the env-include / env-exclude options: pyproject.toml hatch.toml [tool.hatch.envs.] env-include = [ \"FOO*\" , ] env-exclude = [ \"BAR\" , ] [envs.] env-include = [ \"FOO*\" , ] env-exclude = [ \"BAR\" , ] Exclusion patterns take precedence but will never affect defined environment variables. Scripts \u00b6 You can define named scripts that may be executed or referenced at the beginning of other scripts. Context formatting is supported. For example, in the following configuration: pyproject.toml hatch.toml [tool.hatch.envs.test] dependencies = [ \"coverage[toml]\" , \"pytest\" , \"pytest-cov\" , \"pytest-mock\" , ] [tool.hatch.envs.test.scripts] run-coverage = \"pytest --cov-config=pyproject.toml --cov=pkg --cov=tests\" run = \"run-coverage --no-cov\" [envs.test] dependencies = [ \"coverage[toml]\" , \"pytest\" , \"pytest-cov\" , \"pytest-mock\" , ] [envs.test.scripts] run-coverage = \"pytest --cov-config=pyproject.toml --cov=pkg --cov=tests\" run = \"run-coverage --no-cov\" the run script would be expanded to: pytest --cov-config=pyproject.toml --cov=pkg --cov=tests --no-cov Scripts can also be defined as an array of strings. pyproject.toml hatch.toml [tool.hatch.envs.style] detached = true dependencies = [ \"flake8\" , \"black\" , \"isort\" , ] [tool.hatch.envs.style.scripts] check = [ \"flake8 .\" , \"black --check --diff .\" , \"isort --check-only --diff .\" , ] fmt = [ \"isort .\" , \"black .\" , \"check\" , ] [envs.style] detached = true dependencies = [ \"flake8\" , \"black\" , \"isort\" , ] [envs.style.scripts] check = [ \"flake8 .\" , \"black --check --diff .\" , \"isort --check-only --diff .\" , ] fmt = [ \"isort .\" , \"black .\" , \"check\" , ] Similar to make , you can ignore the exit code of commands that start with - (a hyphen). For example, the script error defined by the following configuration would halt after the second command with 3 as the exit code: pyproject.toml hatch.toml [tool.hatch.envs.test.scripts] error = [ \"- exit 1\" , \"exit 3\" , \"exit 0\" , ] [envs.test.scripts] error = [ \"- exit 1\" , \"exit 3\" , \"exit 0\" , ] Tip Individual scripts inherit from parent environments just like options. Commands \u00b6 All commands are able to use any defined scripts . Also like scripts, context formatting is supported and the exit code of commands that start with a hyphen will be ignored. Pre-install \u00b6 You can run commands immediately before environments install your project. pyproject.toml hatch.toml [tool.hatch.envs.] pre-install-commands = [ \"...\" , ] [envs.] pre-install-commands = [ \"...\" , ] Post-install \u00b6 You can run commands immediately after environments install your project. pyproject.toml hatch.toml [tool.hatch.envs.] post-install-commands = [ \"...\" , ] [envs.] post-install-commands = [ \"...\" , ] Python version \u00b6 The python option specifies which version of Python to use, or an absolute path to a Python interpreter: pyproject.toml hatch.toml [tool.hatch.envs.] python = \"3.10\" [envs.] python = \"3.10\" All environment types should respect this option. Supported platforms \u00b6 The platforms option indicates the operating systems with which the environment is compatible: pyproject.toml hatch.toml [tool.hatch.envs.] platforms = [ \"linux\" , \"windows\" , \"macos\" ] [envs.] platforms = [ \"linux\" , \"windows\" , \"macos\" ] The following platforms are supported: linux windows macos If unspecified, the environment is assumed to be compatible with all platforms. Description \u00b6 The description option is purely informational and is displayed in the output of the env show command: pyproject.toml hatch.toml [tool.hatch.envs.] description = \"\"\" Lorem ipsum ... \"\"\" [envs.] description = \"\"\" Lorem ipsum ... \"\"\" Type \u00b6 An environment's type determines which environment plugin will be used for management. The only built-in environment type is virtual , which uses virtual Python environments.","title":"Overview"},{"location":"config/environment/overview/#environment-configuration","text":"All environments are defined as sections within the tool.hatch.envs table. pyproject.toml hatch.toml [tool.hatch.envs.] [envs.] The storage location for environments is completely configurable. Unless an environment is explicitly selected on the command line, the default environment will be used. The type of this environment defaults to virtual .","title":"Environment configuration"},{"location":"config/environment/overview/#inheritance","text":"All environments inherit from the environment defined by its template option, which defaults to default . So for the following configuration: pyproject.toml hatch.toml [tool.hatch.envs.foo] type = \"baz\" skip-install = true [tool.hatch.envs.bar] template = \"foo\" skip-install = false [envs.foo] type = \"baz\" skip-install = true [envs.bar] template = \"foo\" skip-install = false the environment bar will be of type baz with skip-install set to false . Note Environments do not inherit matrices .","title":"Inheritance"},{"location":"config/environment/overview/#self-referential-environments","text":"You can disable inheritance by setting template to the environment's own name: pyproject.toml hatch.toml [tool.hatch.envs.foo] template = \"foo\" [envs.foo] template = \"foo\"","title":"Self-referential environments"},{"location":"config/environment/overview/#detached-environments","text":"A common use case is standalone environments that do not require inheritance nor the installation of the project, such as for linting or sometimes building documentation. Enabling the detached option will make the environment self-referential and will skip project installation : pyproject.toml hatch.toml [tool.hatch.envs.lint] detached = true [envs.lint] detached = true","title":"Detached environments"},{"location":"config/environment/overview/#dependencies","text":"You can install dependencies in addition to the ones defined by your project's metadata . Entries support context formatting . pyproject.toml hatch.toml [tool.hatch.envs.test] dependencies = [ \"coverage[toml]\" , \"pytest\" , \"pytest-cov\" , \"pytest-mock\" , ] [envs.test] dependencies = [ \"coverage[toml]\" , \"pytest\" , \"pytest-cov\" , \"pytest-mock\" , ] If you define environments with dependencies that only slightly differ from their inherited environments , you can use the extra-dependencies option to avoid redeclaring the dependencies option: pyproject.toml hatch.toml [tool.hatch.envs.default] dependencies = [ \"foo\" , \"bar\" , ] [tool.hatch.envs.experimental] extra-dependencies = [ \"baz\" , ] [envs.default] dependencies = [ \"foo\" , \"bar\" , ] [envs.experimental] extra-dependencies = [ \"baz\" , ] Tip Hatch uses pip to install dependencies so any configuration it supports Hatch does as well. For example, if you wanted to only use a private repository you could set the PIP_INDEX_URL environment variable .","title":"Dependencies"},{"location":"config/environment/overview/#installation","text":"","title":"Installation"},{"location":"config/environment/overview/#features","text":"If your project defines optional dependencies , you can select which groups to install using the features option: pyproject.toml hatch.toml [tool.hatch.envs.nightly] features = [ \"server\" , \"grpc\" , ] [envs.nightly] features = [ \"server\" , \"grpc\" , ]","title":"Features"},{"location":"config/environment/overview/#dev-mode","text":"By default, environments will always reflect the current state of your project on disk. Set dev-mode to false to disable this behavior: pyproject.toml hatch.toml [tool.hatch.envs.static] dev-mode = false [envs.static] dev-mode = false","title":"Dev mode"},{"location":"config/environment/overview/#skip-install","text":"By default, environments will install your project during creation. To ignore this step, set skip-install to true : pyproject.toml hatch.toml [tool.hatch.envs.lint] skip-install = true [envs.lint] skip-install = true","title":"Skip install"},{"location":"config/environment/overview/#environment-variables","text":"","title":"Environment variables"},{"location":"config/environment/overview/#defined","text":"You can define environment variables with the env-vars option: pyproject.toml hatch.toml [tool.hatch.envs.docs] dependencies = [ \"mkdocs\" ] [tool.hatch.envs.docs.env-vars] SOURCE_DATE_EPOCH = \"1580601600\" [envs.docs] dependencies = [ \"mkdocs\" ] [envs.docs.env-vars] SOURCE_DATE_EPOCH = \"1580601600\" Values support context formatting .","title":"Defined"},{"location":"config/environment/overview/#filters","text":"By default, environments will have access to all environment variables. You can filter with wildcard patterns using the env-include / env-exclude options: pyproject.toml hatch.toml [tool.hatch.envs.] env-include = [ \"FOO*\" , ] env-exclude = [ \"BAR\" , ] [envs.] env-include = [ \"FOO*\" , ] env-exclude = [ \"BAR\" , ] Exclusion patterns take precedence but will never affect defined environment variables.","title":"Filters"},{"location":"config/environment/overview/#scripts","text":"You can define named scripts that may be executed or referenced at the beginning of other scripts. Context formatting is supported. For example, in the following configuration: pyproject.toml hatch.toml [tool.hatch.envs.test] dependencies = [ \"coverage[toml]\" , \"pytest\" , \"pytest-cov\" , \"pytest-mock\" , ] [tool.hatch.envs.test.scripts] run-coverage = \"pytest --cov-config=pyproject.toml --cov=pkg --cov=tests\" run = \"run-coverage --no-cov\" [envs.test] dependencies = [ \"coverage[toml]\" , \"pytest\" , \"pytest-cov\" , \"pytest-mock\" , ] [envs.test.scripts] run-coverage = \"pytest --cov-config=pyproject.toml --cov=pkg --cov=tests\" run = \"run-coverage --no-cov\" the run script would be expanded to: pytest --cov-config=pyproject.toml --cov=pkg --cov=tests --no-cov Scripts can also be defined as an array of strings. pyproject.toml hatch.toml [tool.hatch.envs.style] detached = true dependencies = [ \"flake8\" , \"black\" , \"isort\" , ] [tool.hatch.envs.style.scripts] check = [ \"flake8 .\" , \"black --check --diff .\" , \"isort --check-only --diff .\" , ] fmt = [ \"isort .\" , \"black .\" , \"check\" , ] [envs.style] detached = true dependencies = [ \"flake8\" , \"black\" , \"isort\" , ] [envs.style.scripts] check = [ \"flake8 .\" , \"black --check --diff .\" , \"isort --check-only --diff .\" , ] fmt = [ \"isort .\" , \"black .\" , \"check\" , ] Similar to make , you can ignore the exit code of commands that start with - (a hyphen). For example, the script error defined by the following configuration would halt after the second command with 3 as the exit code: pyproject.toml hatch.toml [tool.hatch.envs.test.scripts] error = [ \"- exit 1\" , \"exit 3\" , \"exit 0\" , ] [envs.test.scripts] error = [ \"- exit 1\" , \"exit 3\" , \"exit 0\" , ] Tip Individual scripts inherit from parent environments just like options.","title":"Scripts"},{"location":"config/environment/overview/#commands","text":"All commands are able to use any defined scripts . Also like scripts, context formatting is supported and the exit code of commands that start with a hyphen will be ignored.","title":"Commands"},{"location":"config/environment/overview/#pre-install","text":"You can run commands immediately before environments install your project. pyproject.toml hatch.toml [tool.hatch.envs.] pre-install-commands = [ \"...\" , ] [envs.] pre-install-commands = [ \"...\" , ]","title":"Pre-install"},{"location":"config/environment/overview/#post-install","text":"You can run commands immediately after environments install your project. pyproject.toml hatch.toml [tool.hatch.envs.] post-install-commands = [ \"...\" , ] [envs.] post-install-commands = [ \"...\" , ]","title":"Post-install"},{"location":"config/environment/overview/#python-version","text":"The python option specifies which version of Python to use, or an absolute path to a Python interpreter: pyproject.toml hatch.toml [tool.hatch.envs.] python = \"3.10\" [envs.] python = \"3.10\" All environment types should respect this option.","title":"Python version"},{"location":"config/environment/overview/#supported-platforms","text":"The platforms option indicates the operating systems with which the environment is compatible: pyproject.toml hatch.toml [tool.hatch.envs.] platforms = [ \"linux\" , \"windows\" , \"macos\" ] [envs.] platforms = [ \"linux\" , \"windows\" , \"macos\" ] The following platforms are supported: linux windows macos If unspecified, the environment is assumed to be compatible with all platforms.","title":"Supported platforms"},{"location":"config/environment/overview/#description","text":"The description option is purely informational and is displayed in the output of the env show command: pyproject.toml hatch.toml [tool.hatch.envs.] description = \"\"\" Lorem ipsum ... \"\"\" [envs.] description = \"\"\" Lorem ipsum ... \"\"\"","title":"Description"},{"location":"config/environment/overview/#type","text":"An environment's type determines which environment plugin will be used for management. The only built-in environment type is virtual , which uses virtual Python environments.","title":"Type"},{"location":"how-to/environment/package-indices/","text":"Package indices \u00b6 Most Hatch environment types, like the default virtual , simply use pip to install dependencies. Therefore, you can use the standard environment variables that influence pip 's behavior to choose where to search for packages. Here's an example of setting up the default environment to look at 2 private indices (using context formatting for authentication) before finally falling back to PyPI : pyproject.toml hatch.toml [tool.hatch.envs.default.env-vars] PIP_INDEX_URL = \"https://token:{env:GITLAB_API_TOKEN}@gitlab.com/api/v4/groups//-/packages/pypi/simple/\" PIP_EXTRA_INDEX_URL = \"https://token:{env:GITLAB_API_TOKEN}@gitlab.com/api/v4/groups//-/packages/pypi/simple/ https://pypi.org/simple/\" [envs.default.env-vars] PIP_INDEX_URL = \"https://token:{env:GITLAB_API_TOKEN}@gitlab.com/api/v4/groups//-/packages/pypi/simple/\" PIP_EXTRA_INDEX_URL = \"https://token:{env:GITLAB_API_TOKEN}@gitlab.com/api/v4/groups//-/packages/pypi/simple/ https://pypi.org/simple/\"","title":"Package indices"},{"location":"how-to/environment/package-indices/#package-indices","text":"Most Hatch environment types, like the default virtual , simply use pip to install dependencies. Therefore, you can use the standard environment variables that influence pip 's behavior to choose where to search for packages. Here's an example of setting up the default environment to look at 2 private indices (using context formatting for authentication) before finally falling back to PyPI : pyproject.toml hatch.toml [tool.hatch.envs.default.env-vars] PIP_INDEX_URL = \"https://token:{env:GITLAB_API_TOKEN}@gitlab.com/api/v4/groups//-/packages/pypi/simple/\" PIP_EXTRA_INDEX_URL = \"https://token:{env:GITLAB_API_TOKEN}@gitlab.com/api/v4/groups//-/packages/pypi/simple/ https://pypi.org/simple/\" [envs.default.env-vars] PIP_INDEX_URL = \"https://token:{env:GITLAB_API_TOKEN}@gitlab.com/api/v4/groups//-/packages/pypi/simple/\" PIP_EXTRA_INDEX_URL = \"https://token:{env:GITLAB_API_TOKEN}@gitlab.com/api/v4/groups//-/packages/pypi/simple/ https://pypi.org/simple/\"","title":"Package indices"},{"location":"how-to/plugins/testing-builds/","text":"Testing builds \u00b6 For testing Hatchling plugins , you'll usually want to generate a project to execute builds as a real user would. For example, as a minimal pytest fixture: from pathlib import Path import pytest @pytest . fixture def new_project ( tmp_path ): project_dir = tmp_path / 'my-app' project_dir . mkdir () project_file = project_dir / 'pyproject.toml' project_file . write_text ( f \"\"\" \\ [build-system] requires = [\"hatchling\", \"hatch-plugin-name @ { Path . cwd () . as_uri () } \"] build-backend = \"hatchling.build\" [project] name = \"my-app\" version = \"0.1.0\" \"\"\" , encoding = 'utf-8' , ) ... The issue with this is that after the first test session, the project will be forever cached by pip based on the file path. Therefore, subsequent tests runs will never use updated code. To invalidate the cache, copy your code to a new path for every test session: import shutil from pathlib import Path from tempfile import TemporaryDirectory import pytest @pytest . fixture ( scope = 'session' ) def plugin_dir (): with TemporaryDirectory () as d : directory = Path ( d , 'plugin' ) shutil . copytree ( Path . cwd (), directory , ignore = shutil . ignore_patterns ( '.git' ) ) yield directory . resolve () @pytest . fixture def new_project ( tmp_path , plugin_dir ): project_dir = tmp_path / 'my-app' project_dir . mkdir () project_file = project_dir / 'pyproject.toml' project_file . write_text ( f \"\"\" \\ [build-system] requires = [\"hatchling\", \"hatch-plugin-name @ { plugin_dir . as_uri () } \"] build-backend = \"hatchling.build\" [project] name = \"my-app\" version = \"0.1.0\" \"\"\" , encoding = 'utf-8' , ) ... Note This example chooses to ignore copying .git for performance reasons. You may want to ignore more patterns, or copy only specific paths like this plugin does.","title":"Testing builds"},{"location":"how-to/plugins/testing-builds/#testing-builds","text":"For testing Hatchling plugins , you'll usually want to generate a project to execute builds as a real user would. For example, as a minimal pytest fixture: from pathlib import Path import pytest @pytest . fixture def new_project ( tmp_path ): project_dir = tmp_path / 'my-app' project_dir . mkdir () project_file = project_dir / 'pyproject.toml' project_file . write_text ( f \"\"\" \\ [build-system] requires = [\"hatchling\", \"hatch-plugin-name @ { Path . cwd () . as_uri () } \"] build-backend = \"hatchling.build\" [project] name = \"my-app\" version = \"0.1.0\" \"\"\" , encoding = 'utf-8' , ) ... The issue with this is that after the first test session, the project will be forever cached by pip based on the file path. Therefore, subsequent tests runs will never use updated code. To invalidate the cache, copy your code to a new path for every test session: import shutil from pathlib import Path from tempfile import TemporaryDirectory import pytest @pytest . fixture ( scope = 'session' ) def plugin_dir (): with TemporaryDirectory () as d : directory = Path ( d , 'plugin' ) shutil . copytree ( Path . cwd (), directory , ignore = shutil . ignore_patterns ( '.git' ) ) yield directory . resolve () @pytest . fixture def new_project ( tmp_path , plugin_dir ): project_dir = tmp_path / 'my-app' project_dir . mkdir () project_file = project_dir / 'pyproject.toml' project_file . write_text ( f \"\"\" \\ [build-system] requires = [\"hatchling\", \"hatch-plugin-name @ { plugin_dir . as_uri () } \"] build-backend = \"hatchling.build\" [project] name = \"my-app\" version = \"0.1.0\" \"\"\" , encoding = 'utf-8' , ) ... Note This example chooses to ignore copying .git for performance reasons. You may want to ignore more patterns, or copy only specific paths like this plugin does.","title":"Testing builds"},{"location":"meta/authors/","text":"Authors \u00b6 Maintainers \u00b6 Ofek Lev Contributors \u00b6 Amjith Ramanujam Arnaud Crowther Chris Warrick Lum\u00edr 'Frenzy' Balhar Ofek Lev Philip Blair","title":"Authors"},{"location":"meta/authors/#authors","text":"","title":"Authors"},{"location":"meta/authors/#maintainers","text":"Ofek Lev","title":"Maintainers"},{"location":"meta/authors/#contributors","text":"Amjith Ramanujam Arnaud Crowther Chris Warrick Lum\u00edr 'Frenzy' Balhar Ofek Lev Philip Blair","title":"Contributors"},{"location":"meta/faq/","text":"FAQ \u00b6 Interoperability \u00b6 Q : What is the risk of lock-in? A : Not much! Other than the plugin system , everything uses Python's established standards by default. Project metadata is based entirely on PEP 621 / PEP 631 , the build system is compatible with PEP 517 / PEP 660 , versioning uses the scheme specified by PEP 440 , dependencies are defined with PEP 508 strings, and environments use virtualenv . Q : Must one use all features? A : No, all features are optional! You can use just the build system , publish wheels and source distributions that were built by other tools, only use the environment management, etc. Libraries vs applications \u00b6 Q : Are workflows for both libraries and applications supported? A : Yes, mostly! Applications can utilize environment management just like libraries, and plugins can be used to build projects in arbitrary formats or publish artifacts to arbitrary destinations. The only caveat is that currently there is no support for re-creating an environment given a set of dependencies in a reproducible manner. Although a standard lock file format may be far off since PEP 665 was rejected, resolving capabilities are coming to pip . When that is stabilized, Hatch will add locking functionality and dedicated documentation for managing applications. Tool migration \u00b6 Q : How to migrate to Hatch? Build system \u00b6 Setuptools Hatch setup.py MANIFEST.in import os from io import open from setuptools import find_packages , setup about = {} with open ( os . path . join ( 'src' , 'foo' , '__about__.py' ), 'r' , 'utf-8' ) as f : exec ( f . read (), about ) with open ( 'README.md' , 'r' , 'utf-8' ) as f : readme = f . read () setup ( # Metadata name = 'foo' , version = about [ '__version__' ], description = '...' , long_description = readme , long_description_content_type = 'text/markdown' , author = '...' , author_email = '...' , project_urls = { 'Documentation' : '...' , 'Source' : '...' , }, classifiers = [ '...' , ], keywords = [ '...' , ], python_requires = '>=3.8' , install_requires = [ '...' , ], extras_require = { 'feature' : [ '...' ], }, # Packaging packages = find_packages ( where = 'src' ), package_dir = { '' : 'src' }, package_data = { 'foo' : [ 'py.typed' ], }, zip_safe = False , entry_points = { 'console_scripts' : [ 'foo = foo.cli:main' , ], }, ) graft tests global-exclude *.py[cod] __pycache__ pyproject.toml [build-system] requires = [ \"hatchling\" ] build-backend = \"hatchling.build\" [project] name = \"foo\" description = \"...\" readme = \"README.md\" authors = [ { name = \"...\" , email = \"...\" }, ] classifiers = [ \"...\" , ] keywords = [ \"...\" , ] requires-python = \">=3.8\" dependencies = [ \"...\" , ] dynamic = [ \"version\" ] [project.urls] Documentation = \"...\" Source = \"...\" [project.optional-dependencies] feature = [ \"...\" ] [project.scripts] foo = \"foo.cli:main\" [tool.hatch.version] path = \"src/foo/__about__.py\" [tool.hatch.build.targets.sdist] include = [ \"/src\" , \"/tests\" , ] Environments \u00b6 Tox Hatch Invocation: tox tox.ini [tox] envlist = py{27,38}-{42,3.14} py{38,39}-{9000}-{foo,bar} [testenv] usedevelop = true deps = coverage[toml] pytest pytest-cov foo: cryptography commands = pytest --cov-report = term-missing --cov-config=pyproject.toml --cov=pkg --cov=tests {posargs} setenv = 3.14: PRODUCT_VERSION = 3.14 42: PRODUCT_VERSION = 42 9000: PRODUCT_VERSION = 9000 {foo,bar}: EXPERIMENTAL = true Invocation: hatch run test hatch.toml pyproject.toml [envs.default] dependencies = [ \"coverage[toml]\" , \"pytest\" , \"pytest-cov\" , ] [envs.default.scripts] test = 'pytest --cov-report=term-missing --cov-config=pyproject.toml --cov=pkg --cov=tests' [envs.default.overrides] matrix . version . env-vars = \"PRODUCT_VERSION\" matrix . features . env-vars = \"EXPERIMENTAL=true\" matrix . features . dependencies = [ { value = \"cryptography\" , if = [ \"foo\" ] }, ] [[envs.default.matrix]] python = [ \"27\" , \"38\" ] version = [ \"42\" , \"3.14\" ] [[envs.default.matrix]] python = [ \"38\" , \"39\" ] version = [ \"9000\" ] features = [ \"foo\" , \"bar\" ] [tool.hatch.envs.default] dependencies = [ \"coverage[toml]\" , \"pytest\" , \"pytest-cov\" , ] [tool.hatch.envs.default.scripts] test = 'pytest --cov-report=term-missing --cov-config=pyproject.toml --cov=pkg --cov=tests' [tool.hatch.envs.default.overrides] matrix . version . env-vars = \"PRODUCT_VERSION\" matrix . features . env-vars = \"EXPERIMENTAL=true\" matrix . features . dependencies = [ { value = \"cryptography\" , if = [ \"foo\" ] }, ] [[tool.hatch.envs.default.matrix]] python = [ \"27\" , \"38\" ] version = [ \"42\" , \"3.14\" ] [[tool.hatch.envs.default.matrix]] python = [ \"38\" , \"39\" ] version = [ \"9000\" ] features = [ \"foo\" , \"bar\" ]","title":"FAQ"},{"location":"meta/faq/#faq","text":"","title":"FAQ"},{"location":"meta/faq/#interoperability","text":"Q : What is the risk of lock-in? A : Not much! Other than the plugin system , everything uses Python's established standards by default. Project metadata is based entirely on PEP 621 / PEP 631 , the build system is compatible with PEP 517 / PEP 660 , versioning uses the scheme specified by PEP 440 , dependencies are defined with PEP 508 strings, and environments use virtualenv . Q : Must one use all features? A : No, all features are optional! You can use just the build system , publish wheels and source distributions that were built by other tools, only use the environment management, etc.","title":"Interoperability"},{"location":"meta/faq/#libraries-vs-applications","text":"Q : Are workflows for both libraries and applications supported? A : Yes, mostly! Applications can utilize environment management just like libraries, and plugins can be used to build projects in arbitrary formats or publish artifacts to arbitrary destinations. The only caveat is that currently there is no support for re-creating an environment given a set of dependencies in a reproducible manner. Although a standard lock file format may be far off since PEP 665 was rejected, resolving capabilities are coming to pip . When that is stabilized, Hatch will add locking functionality and dedicated documentation for managing applications.","title":"Libraries vs applications"},{"location":"meta/faq/#tool-migration","text":"Q : How to migrate to Hatch?","title":"Tool migration"},{"location":"meta/faq/#build-system","text":"Setuptools Hatch setup.py MANIFEST.in import os from io import open from setuptools import find_packages , setup about = {} with open ( os . path . join ( 'src' , 'foo' , '__about__.py' ), 'r' , 'utf-8' ) as f : exec ( f . read (), about ) with open ( 'README.md' , 'r' , 'utf-8' ) as f : readme = f . read () setup ( # Metadata name = 'foo' , version = about [ '__version__' ], description = '...' , long_description = readme , long_description_content_type = 'text/markdown' , author = '...' , author_email = '...' , project_urls = { 'Documentation' : '...' , 'Source' : '...' , }, classifiers = [ '...' , ], keywords = [ '...' , ], python_requires = '>=3.8' , install_requires = [ '...' , ], extras_require = { 'feature' : [ '...' ], }, # Packaging packages = find_packages ( where = 'src' ), package_dir = { '' : 'src' }, package_data = { 'foo' : [ 'py.typed' ], }, zip_safe = False , entry_points = { 'console_scripts' : [ 'foo = foo.cli:main' , ], }, ) graft tests global-exclude *.py[cod] __pycache__ pyproject.toml [build-system] requires = [ \"hatchling\" ] build-backend = \"hatchling.build\" [project] name = \"foo\" description = \"...\" readme = \"README.md\" authors = [ { name = \"...\" , email = \"...\" }, ] classifiers = [ \"...\" , ] keywords = [ \"...\" , ] requires-python = \">=3.8\" dependencies = [ \"...\" , ] dynamic = [ \"version\" ] [project.urls] Documentation = \"...\" Source = \"...\" [project.optional-dependencies] feature = [ \"...\" ] [project.scripts] foo = \"foo.cli:main\" [tool.hatch.version] path = \"src/foo/__about__.py\" [tool.hatch.build.targets.sdist] include = [ \"/src\" , \"/tests\" , ]","title":"Build system"},{"location":"meta/faq/#environments","text":"Tox Hatch Invocation: tox tox.ini [tox] envlist = py{27,38}-{42,3.14} py{38,39}-{9000}-{foo,bar} [testenv] usedevelop = true deps = coverage[toml] pytest pytest-cov foo: cryptography commands = pytest --cov-report = term-missing --cov-config=pyproject.toml --cov=pkg --cov=tests {posargs} setenv = 3.14: PRODUCT_VERSION = 3.14 42: PRODUCT_VERSION = 42 9000: PRODUCT_VERSION = 9000 {foo,bar}: EXPERIMENTAL = true Invocation: hatch run test hatch.toml pyproject.toml [envs.default] dependencies = [ \"coverage[toml]\" , \"pytest\" , \"pytest-cov\" , ] [envs.default.scripts] test = 'pytest --cov-report=term-missing --cov-config=pyproject.toml --cov=pkg --cov=tests' [envs.default.overrides] matrix . version . env-vars = \"PRODUCT_VERSION\" matrix . features . env-vars = \"EXPERIMENTAL=true\" matrix . features . dependencies = [ { value = \"cryptography\" , if = [ \"foo\" ] }, ] [[envs.default.matrix]] python = [ \"27\" , \"38\" ] version = [ \"42\" , \"3.14\" ] [[envs.default.matrix]] python = [ \"38\" , \"39\" ] version = [ \"9000\" ] features = [ \"foo\" , \"bar\" ] [tool.hatch.envs.default] dependencies = [ \"coverage[toml]\" , \"pytest\" , \"pytest-cov\" , ] [tool.hatch.envs.default.scripts] test = 'pytest --cov-report=term-missing --cov-config=pyproject.toml --cov=pkg --cov=tests' [tool.hatch.envs.default.overrides] matrix . version . env-vars = \"PRODUCT_VERSION\" matrix . features . env-vars = \"EXPERIMENTAL=true\" matrix . features . dependencies = [ { value = \"cryptography\" , if = [ \"foo\" ] }, ] [[tool.hatch.envs.default.matrix]] python = [ \"27\" , \"38\" ] version = [ \"42\" , \"3.14\" ] [[tool.hatch.envs.default.matrix]] python = [ \"38\" , \"39\" ] version = [ \"9000\" ] features = [ \"foo\" , \"bar\" ]","title":"Environments"},{"location":"plugins/about/","text":"Plugins \u00b6 Hatch utilizes pluggy for its plugin functionality. Overview \u00b6 All plugins provide registration hooks that return one or more classes that inherit from a particular type interface. Each registration hook must be decorated by Hatch's hook marker. For example, if you wanted to create a new kind of environment you could do: hooks.py from hatchling.plugin import hookimpl from .plugin import SpecialEnvironment @hookimpl def hatch_register_environment (): return SpecialEnvironment The hooks can return a single class or a list of classes. Every class must define an attribute called PLUGIN_NAME that users will select when they wish to use the plugin. So in the example above, the class might be defined like: plugin.py ... class SpecialEnvironment ( ... ): PLUGIN_NAME = 'special' ... Project configuration \u00b6 Naming \u00b6 It is recommended that plugin project names are prefixed with hatch- . For example, if you wanted to make a plugin that provides some functionality for a product named foo you might do: pyproject.toml [project] name = \"hatch-foo\" Discovery \u00b6 You'll need to define your project as a Python plugin for Hatch: pyproject.toml [project.entry-points.hatch] foo = \"pkg.hooks\" The name of the plugin should be the project name (excluding any hatch- prefix) and the path should represent the module that contains the registration hooks. Classifier \u00b6 Add Framework :: Hatch to your project's classifiers to make it easy to search for Hatch plugins: pyproject.toml [project] classifiers = [ ... \"Framework :: Hatch\" , ... ] Types \u00b6 Hatchling \u00b6 These are all involved in building projects and therefore any defined dependencies are automatically installed in each build environment. Builder Build hook Metadata hook Version source Version scheme Hatch \u00b6 These must be manually installed in the same environment as Hatch itself. Environment Environment collector Publisher","title":"About"},{"location":"plugins/about/#plugins","text":"Hatch utilizes pluggy for its plugin functionality.","title":"Plugins"},{"location":"plugins/about/#overview","text":"All plugins provide registration hooks that return one or more classes that inherit from a particular type interface. Each registration hook must be decorated by Hatch's hook marker. For example, if you wanted to create a new kind of environment you could do: hooks.py from hatchling.plugin import hookimpl from .plugin import SpecialEnvironment @hookimpl def hatch_register_environment (): return SpecialEnvironment The hooks can return a single class or a list of classes. Every class must define an attribute called PLUGIN_NAME that users will select when they wish to use the plugin. So in the example above, the class might be defined like: plugin.py ... class SpecialEnvironment ( ... ): PLUGIN_NAME = 'special' ...","title":"Overview"},{"location":"plugins/about/#project-configuration","text":"","title":"Project configuration"},{"location":"plugins/about/#naming","text":"It is recommended that plugin project names are prefixed with hatch- . For example, if you wanted to make a plugin that provides some functionality for a product named foo you might do: pyproject.toml [project] name = \"hatch-foo\"","title":"Naming"},{"location":"plugins/about/#discovery","text":"You'll need to define your project as a Python plugin for Hatch: pyproject.toml [project.entry-points.hatch] foo = \"pkg.hooks\" The name of the plugin should be the project name (excluding any hatch- prefix) and the path should represent the module that contains the registration hooks.","title":"Discovery"},{"location":"plugins/about/#classifier","text":"Add Framework :: Hatch to your project's classifiers to make it easy to search for Hatch plugins: pyproject.toml [project] classifiers = [ ... \"Framework :: Hatch\" , ... ]","title":"Classifier"},{"location":"plugins/about/#types","text":"","title":"Types"},{"location":"plugins/about/#hatchling","text":"These are all involved in building projects and therefore any defined dependencies are automatically installed in each build environment. Builder Build hook Metadata hook Version source Version scheme","title":"Hatchling"},{"location":"plugins/about/#hatch","text":"These must be manually installed in the same environment as Hatch itself. Environment Environment collector Publisher","title":"Hatch"},{"location":"plugins/utilities/","text":"Plugin utilities \u00b6 hatchling . builders . utils . get_reproducible_timestamp () \u00b6 Returns an int derived from the SOURCE_DATE_EPOCH environment variable; see https://reproducible-builds.org/specs/source-date-epoch/ . The default value will always be: 1580601600 Source code in hatchling/builders/utils.py def get_reproducible_timestamp (): \"\"\" Returns an `int` derived from the `SOURCE_DATE_EPOCH` environment variable; see https://reproducible-builds.org/specs/source-date-epoch/. The default value will always be: `1580601600` \"\"\" return int ( os . environ . get ( 'SOURCE_DATE_EPOCH' , '1580601600' )) BuilderConfig \u00b6 directory () property \u00b6 ignore_vcs () property \u00b6 reproducible () property \u00b6 Whether or not the target should be built in a reproducible manner, defaulting to true. dev_mode_dirs () property \u00b6 Directories which must be added to Python's search path in dev mode . versions () property \u00b6 dependencies () property \u00b6 default_include () \u00b6 default_exclude () \u00b6 default_packages () \u00b6 Application \u00b6 The way output is displayed can be configured by users. Important Never import this directly; Hatch judiciously decides if a type of plugin requires the capabilities herein and will grant access via an attribute. abort ( message = '' , code = 1 , ** kwargs ) \u00b6 Terminate the program with the given return code. display_debug ( message = '' , level = 1 , ** kwargs ) \u00b6 Meant to be used for messages that are not useful for most user experiences. The level option must be between 1 and 3 (inclusive). display_error ( message = '' , ** kwargs ) \u00b6 Meant to be used for messages indicating some unrecoverable error. display_info ( message = '' , ** kwargs ) \u00b6 Meant to be used for messages conveying basic information. display_success ( message = '' , ** kwargs ) \u00b6 Meant to be used for messages indicating some positive outcome. display_waiting ( message = '' , ** kwargs ) \u00b6 Meant to be used for messages shown before potentially time consuming operations. display_warning ( message = '' , ** kwargs ) \u00b6 Meant to be used for messages conveying important information. Platform \u00b6 format_for_subprocess ( command : str | list [ str ], * , shell : bool ) \u00b6 Format the given command in a cross-platform manner for immediate consumption by subprocess utilities. run_command ( command : str | list [ str ], shell = False , ** kwargs ) \u00b6 Equivalent to the standard library's subprocess.run , with the command first being properly formatted . check_command ( command : str | list [ str ], shell = False , ** kwargs ) \u00b6 Equivalent to run_command , but non-zero exit codes will gracefully end program execution. check_command_output ( command : str | list [ str ], shell = False , ** kwargs ) -> str \u00b6 Equivalent to the output from the process returned by capture_process , but non-zero exit codes will gracefully end program execution. capture_process ( command : str | list [ str ], shell = False , ** kwargs ) \u00b6 Equivalent to the standard library's subprocess.Popen , with all output captured by stdout and the command first being properly formatted . exit_with_command ( command : list [ str ]) \u00b6 Run the given command and exit with its exit code. On non-Windows systems, this uses the standard library's os.execvp . default_shell () property \u00b6 Returns the default shell of the system. On Windows systems first try the SHELL environment variable, if present, followed by the COMSPEC environment variable, defaulting to cmd . On all other platforms only the SHELL environment variable will be used, defaulting to bash . modules () property \u00b6 Accessor for lazily loading modules that either take multiple milliseconds to import (like shutil and subprocess ) or are not used on all platforms (like shlex ). name () property \u00b6 One of the following: linux windows macos windows () property \u00b6 Indicates whether Hatch is running on Windows. macos () property \u00b6 Indicates whether Hatch is running on macOS. linux () property \u00b6 Indicates whether Hatch is running on neither Windows nor macOS. EnvironmentContextFormatter \u00b6 formatters () \u00b6 This returns a mapping of supported field names to their respective formatting functions. Each function accepts 2 arguments: the value that was passed to the format call, defaulting to None the modifier data , defaulting to an empty string","title":"Utilities"},{"location":"plugins/utilities/#plugin-utilities","text":"","title":"Plugin utilities"},{"location":"plugins/utilities/#hatchling.builders.utils.get_reproducible_timestamp","text":"Returns an int derived from the SOURCE_DATE_EPOCH environment variable; see https://reproducible-builds.org/specs/source-date-epoch/ . The default value will always be: 1580601600 Source code in hatchling/builders/utils.py def get_reproducible_timestamp (): \"\"\" Returns an `int` derived from the `SOURCE_DATE_EPOCH` environment variable; see https://reproducible-builds.org/specs/source-date-epoch/. The default value will always be: `1580601600` \"\"\" return int ( os . environ . get ( 'SOURCE_DATE_EPOCH' , '1580601600' ))","title":"get_reproducible_timestamp()"},{"location":"plugins/utilities/#hatchling.builders.config.BuilderConfig","text":"","title":"BuilderConfig"},{"location":"plugins/utilities/#hatchling.builders.config.BuilderConfig.directory","text":"","title":"directory()"},{"location":"plugins/utilities/#hatchling.builders.config.BuilderConfig.ignore_vcs","text":"","title":"ignore_vcs()"},{"location":"plugins/utilities/#hatchling.builders.config.BuilderConfig.reproducible","text":"Whether or not the target should be built in a reproducible manner, defaulting to true.","title":"reproducible()"},{"location":"plugins/utilities/#hatchling.builders.config.BuilderConfig.dev_mode_dirs","text":"Directories which must be added to Python's search path in dev mode .","title":"dev_mode_dirs()"},{"location":"plugins/utilities/#hatchling.builders.config.BuilderConfig.versions","text":"","title":"versions()"},{"location":"plugins/utilities/#hatchling.builders.config.BuilderConfig.dependencies","text":"","title":"dependencies()"},{"location":"plugins/utilities/#hatchling.builders.config.BuilderConfig.default_include","text":"","title":"default_include()"},{"location":"plugins/utilities/#hatchling.builders.config.BuilderConfig.default_exclude","text":"","title":"default_exclude()"},{"location":"plugins/utilities/#hatchling.builders.config.BuilderConfig.default_packages","text":"","title":"default_packages()"},{"location":"plugins/utilities/#hatchling.bridge.app.Application","text":"The way output is displayed can be configured by users. Important Never import this directly; Hatch judiciously decides if a type of plugin requires the capabilities herein and will grant access via an attribute.","title":"Application"},{"location":"plugins/utilities/#hatchling.bridge.app.Application.abort","text":"Terminate the program with the given return code.","title":"abort()"},{"location":"plugins/utilities/#hatchling.bridge.app.Application.display_debug","text":"Meant to be used for messages that are not useful for most user experiences. The level option must be between 1 and 3 (inclusive).","title":"display_debug()"},{"location":"plugins/utilities/#hatchling.bridge.app.Application.display_error","text":"Meant to be used for messages indicating some unrecoverable error.","title":"display_error()"},{"location":"plugins/utilities/#hatchling.bridge.app.Application.display_info","text":"Meant to be used for messages conveying basic information.","title":"display_info()"},{"location":"plugins/utilities/#hatchling.bridge.app.Application.display_success","text":"Meant to be used for messages indicating some positive outcome.","title":"display_success()"},{"location":"plugins/utilities/#hatchling.bridge.app.Application.display_waiting","text":"Meant to be used for messages shown before potentially time consuming operations.","title":"display_waiting()"},{"location":"plugins/utilities/#hatchling.bridge.app.Application.display_warning","text":"Meant to be used for messages conveying important information.","title":"display_warning()"},{"location":"plugins/utilities/#hatch.utils.platform.Platform","text":"","title":"Platform"},{"location":"plugins/utilities/#hatch.utils.platform.Platform.format_for_subprocess","text":"Format the given command in a cross-platform manner for immediate consumption by subprocess utilities.","title":"format_for_subprocess()"},{"location":"plugins/utilities/#hatch.utils.platform.Platform.run_command","text":"Equivalent to the standard library's subprocess.run , with the command first being properly formatted .","title":"run_command()"},{"location":"plugins/utilities/#hatch.utils.platform.Platform.check_command","text":"Equivalent to run_command , but non-zero exit codes will gracefully end program execution.","title":"check_command()"},{"location":"plugins/utilities/#hatch.utils.platform.Platform.check_command_output","text":"Equivalent to the output from the process returned by capture_process , but non-zero exit codes will gracefully end program execution.","title":"check_command_output()"},{"location":"plugins/utilities/#hatch.utils.platform.Platform.capture_process","text":"Equivalent to the standard library's subprocess.Popen , with all output captured by stdout and the command first being properly formatted .","title":"capture_process()"},{"location":"plugins/utilities/#hatch.utils.platform.Platform.exit_with_command","text":"Run the given command and exit with its exit code. On non-Windows systems, this uses the standard library's os.execvp .","title":"exit_with_command()"},{"location":"plugins/utilities/#hatch.utils.platform.Platform.default_shell","text":"Returns the default shell of the system. On Windows systems first try the SHELL environment variable, if present, followed by the COMSPEC environment variable, defaulting to cmd . On all other platforms only the SHELL environment variable will be used, defaulting to bash .","title":"default_shell()"},{"location":"plugins/utilities/#hatch.utils.platform.Platform.modules","text":"Accessor for lazily loading modules that either take multiple milliseconds to import (like shutil and subprocess ) or are not used on all platforms (like shlex ).","title":"modules()"},{"location":"plugins/utilities/#hatch.utils.platform.Platform.name","text":"One of the following: linux windows macos","title":"name()"},{"location":"plugins/utilities/#hatch.utils.platform.Platform.windows","text":"Indicates whether Hatch is running on Windows.","title":"windows()"},{"location":"plugins/utilities/#hatch.utils.platform.Platform.macos","text":"Indicates whether Hatch is running on macOS.","title":"macos()"},{"location":"plugins/utilities/#hatch.utils.platform.Platform.linux","text":"Indicates whether Hatch is running on neither Windows nor macOS.","title":"linux()"},{"location":"plugins/utilities/#hatch.env.context.EnvironmentContextFormatter","text":"","title":"EnvironmentContextFormatter"},{"location":"plugins/utilities/#hatch.env.context.EnvironmentContextFormatter.formatters","text":"This returns a mapping of supported field names to their respective formatting functions. Each function accepts 2 arguments: the value that was passed to the format call, defaulting to None the modifier data , defaulting to an empty string","title":"formatters()"},{"location":"plugins/build-hook/custom/","text":"Custom build hook \u00b6 This is a custom class in a given Python file that inherits from the BuildHookInterface . Configuration \u00b6 The build hook plugin name is custom . pyproject.toml hatch.toml [tool.hatch.build.hooks.custom] [tool.hatch.build.targets..hooks.custom] [build.hooks.custom] [build.targets..hooks.custom] Options \u00b6 Option Default Description path hatch_build.py The path of the Python file Example \u00b6 hatch_build.py from hatchling.builders.hooks.plugin.interface import BuildHookInterface class CustomBuildHook ( BuildHookInterface ): ... If multiple subclasses are found, you must define a function named get_build_hook that returns the desired build hook. Note Any defined PLUGIN_NAME is ignored and will always be custom .","title":"Custom"},{"location":"plugins/build-hook/custom/#custom-build-hook","text":"This is a custom class in a given Python file that inherits from the BuildHookInterface .","title":"Custom build hook"},{"location":"plugins/build-hook/custom/#configuration","text":"The build hook plugin name is custom . pyproject.toml hatch.toml [tool.hatch.build.hooks.custom] [tool.hatch.build.targets..hooks.custom] [build.hooks.custom] [build.targets..hooks.custom]","title":"Configuration"},{"location":"plugins/build-hook/custom/#options","text":"Option Default Description path hatch_build.py The path of the Python file","title":"Options"},{"location":"plugins/build-hook/custom/#example","text":"hatch_build.py from hatchling.builders.hooks.plugin.interface import BuildHookInterface class CustomBuildHook ( BuildHookInterface ): ... If multiple subclasses are found, you must define a function named get_build_hook that returns the desired build hook. Note Any defined PLUGIN_NAME is ignored and will always be custom .","title":"Example"},{"location":"plugins/build-hook/reference/","text":"Build hook plugins \u00b6 A build hook provides code that will be executed at various stages of the build process. See the documentation for build hook configuration . Known third-party \u00b6 hatch-autorun - used to inject code into an installation that will automatically run before the first import hatch-jupyter-builder - used for packages in the Project Jupyter ecosystem hatch-mypyc - compiles code with Mypyc hatch-odoo - package Odoo add-ons into the appropriate namespace Overview \u00b6 Build hooks run for every selected version of build targets. The initialization stage occurs immediately before each build and the finalization stage occurs immediately after. Each stage has the opportunity to view or modify build data . Build data \u00b6 Build data is a simple mapping whose contents can influence the behavior of builds. Which fields exist and are recognized depends on each build target. The following fields are always present and recognized by the build system itself: Field Type Description artifacts list [ str ] This is a list of extra artifact patterns and should generally only be appended to force_include dict [ str , str ] This is a mapping of extra forced inclusion paths , with this mapping taking precedence in case of conflicts build_hooks tuple [ str , ... ] This is an immutable sequence of the names of the configured build hooks and matches the order in which they run Attention While user-facing TOML options are hyphenated, build data fields should be named with underscores to allow plugins to use them as valid Python identifiers. Notes \u00b6 In some cases it may be necessary to use force_include rather than artifacts . For example, say that you want to install a lib.so directly at the root of site-packages and a project defines a package src/foo . If you create src/lib.so , there will never be a match because the directory traversal starts at src/foo rather than src . In that case you must do either: build_data [ 'force_include' ][ 'src/lib.so' ] = 'src/lib.so' or build_data [ 'force_include' ][ '/absolute/path/to/src/lib.so' ] = 'src/lib.so' BuildHookInterface \u00b6 Example usage: plugin.py hooks.py from hatchling.builders.hooks.plugin.interface import BuildHookInterface class SpecialBuildHook ( BuildHookInterface ): PLUGIN_NAME = 'special' ... from hatchling.plugin import hookimpl from .plugin import SpecialBuildHook @hookimpl def hatch_register_build_hook (): return SpecialBuildHook Source code in hatchling/builders/hooks/plugin/interface.py class BuildHookInterface : # no cov \"\"\" Example usage: === \":octicons-file-code-16: plugin.py\" ```python from hatchling.builders.hooks.plugin.interface import BuildHookInterface class SpecialBuildHook(BuildHookInterface): PLUGIN_NAME = 'special' ... ``` === \":octicons-file-code-16: hooks.py\" ```python from hatchling.plugin import hookimpl from .plugin import SpecialBuildHook @hookimpl def hatch_register_build_hook(): return SpecialBuildHook ``` \"\"\" PLUGIN_NAME = '' \"\"\"The name used for selection.\"\"\" def __init__ ( self , root , config , build_config , metadata , directory , target_name , app = None ): self . __root = root self . __config = config self . __build_config = build_config self . __metadata = metadata self . __directory = directory self . __target_name = target_name self . __app = app @property def app ( self ): \"\"\" An instance of [Application](../utilities.md#hatchling.bridge.app.Application). \"\"\" if self . __app is None : from hatchling.bridge.app import Application self . __app = Application () . get_safe_application () return self . __app @property def root ( self ): \"\"\" The root of the project tree. \"\"\" return self . __root @property def config ( self ): \"\"\" The cumulative hook configuration. === \":octicons-file-code-16: pyproject.toml\" ```toml [tool.hatch.build.hooks.] [tool.hatch.build.targets..hooks.] ``` === \":octicons-file-code-16: hatch.toml\" ```toml [build.hooks.] [build.targets..hooks.] ``` \"\"\" return self . __config @property def metadata ( self ): # Undocumented for now return self . __metadata @property def build_config ( self ): \"\"\" An instance of [BuilderConfig](../utilities.md#hatchling.builders.config.BuilderConfig). \"\"\" return self . __build_config @property def directory ( self ): \"\"\" The build directory. \"\"\" return self . __directory @property def target_name ( self ): \"\"\" The plugin name of the build target. \"\"\" return self . __target_name def clean ( self , versions ): \"\"\" This occurs before the build process if the `-c`/`--clean` flag was passed to the [`build`](../../cli/reference.md#hatch-build) command, or when invoking the [`clean`](../../cli/reference.md#hatch-clean) command. \"\"\" def initialize ( self , version , build_data ): \"\"\" This occurs immediately before each build. Any modifications to the build data will be seen by the build target. \"\"\" def finalize ( self , version , build_data , artifact_path ): \"\"\" This occurs immediately after each build and will not run if the `--hooks-only` flag was passed to the [`build`](../../cli/reference.md#hatch-build) command. The build data will reflect any modifications done by the target during the build. \"\"\" PLUGIN_NAME = '' class-attribute \u00b6 The name used for selection. app () property \u00b6 An instance of Application . Source code in hatchling/builders/hooks/plugin/interface.py @property def app ( self ): \"\"\" An instance of [Application](../utilities.md#hatchling.bridge.app.Application). \"\"\" if self . __app is None : from hatchling.bridge.app import Application self . __app = Application () . get_safe_application () return self . __app root () property \u00b6 The root of the project tree. Source code in hatchling/builders/hooks/plugin/interface.py @property def root ( self ): \"\"\" The root of the project tree. \"\"\" return self . __root config () property \u00b6 The cumulative hook configuration. pyproject.toml hatch.toml [tool.hatch.build.hooks.] [tool.hatch.build.targets..hooks.] [build.hooks.] [build.targets..hooks.] Source code in hatchling/builders/hooks/plugin/interface.py @property def config ( self ): \"\"\" The cumulative hook configuration. === \":octicons-file-code-16: pyproject.toml\" ```toml [tool.hatch.build.hooks.] [tool.hatch.build.targets..hooks.] ``` === \":octicons-file-code-16: hatch.toml\" ```toml [build.hooks.] [build.targets..hooks.] ``` \"\"\" return self . __config build_config () property \u00b6 An instance of BuilderConfig . Source code in hatchling/builders/hooks/plugin/interface.py @property def build_config ( self ): \"\"\" An instance of [BuilderConfig](../utilities.md#hatchling.builders.config.BuilderConfig). \"\"\" return self . __build_config target_name () property \u00b6 The plugin name of the build target. Source code in hatchling/builders/hooks/plugin/interface.py @property def target_name ( self ): \"\"\" The plugin name of the build target. \"\"\" return self . __target_name directory () property \u00b6 The build directory. Source code in hatchling/builders/hooks/plugin/interface.py @property def directory ( self ): \"\"\" The build directory. \"\"\" return self . __directory clean ( versions ) \u00b6 This occurs before the build process if the -c / --clean flag was passed to the build command, or when invoking the clean command. Source code in hatchling/builders/hooks/plugin/interface.py def clean ( self , versions ): \"\"\" This occurs before the build process if the `-c`/`--clean` flag was passed to the [`build`](../../cli/reference.md#hatch-build) command, or when invoking the [`clean`](../../cli/reference.md#hatch-clean) command. \"\"\" initialize ( version , build_data ) \u00b6 This occurs immediately before each build. Any modifications to the build data will be seen by the build target. Source code in hatchling/builders/hooks/plugin/interface.py def initialize ( self , version , build_data ): \"\"\" This occurs immediately before each build. Any modifications to the build data will be seen by the build target. \"\"\" finalize ( version , build_data , artifact_path ) \u00b6 This occurs immediately after each build and will not run if the --hooks-only flag was passed to the build command. The build data will reflect any modifications done by the target during the build. Source code in hatchling/builders/hooks/plugin/interface.py def finalize ( self , version , build_data , artifact_path ): \"\"\" This occurs immediately after each build and will not run if the `--hooks-only` flag was passed to the [`build`](../../cli/reference.md#hatch-build) command. The build data will reflect any modifications done by the target during the build. \"\"\"","title":"Reference"},{"location":"plugins/build-hook/reference/#build-hook-plugins","text":"A build hook provides code that will be executed at various stages of the build process. See the documentation for build hook configuration .","title":"Build hook plugins"},{"location":"plugins/build-hook/reference/#known-third-party","text":"hatch-autorun - used to inject code into an installation that will automatically run before the first import hatch-jupyter-builder - used for packages in the Project Jupyter ecosystem hatch-mypyc - compiles code with Mypyc hatch-odoo - package Odoo add-ons into the appropriate namespace","title":"Known third-party"},{"location":"plugins/build-hook/reference/#overview","text":"Build hooks run for every selected version of build targets. The initialization stage occurs immediately before each build and the finalization stage occurs immediately after. Each stage has the opportunity to view or modify build data .","title":"Overview"},{"location":"plugins/build-hook/reference/#build-data","text":"Build data is a simple mapping whose contents can influence the behavior of builds. Which fields exist and are recognized depends on each build target. The following fields are always present and recognized by the build system itself: Field Type Description artifacts list [ str ] This is a list of extra artifact patterns and should generally only be appended to force_include dict [ str , str ] This is a mapping of extra forced inclusion paths , with this mapping taking precedence in case of conflicts build_hooks tuple [ str , ... ] This is an immutable sequence of the names of the configured build hooks and matches the order in which they run Attention While user-facing TOML options are hyphenated, build data fields should be named with underscores to allow plugins to use them as valid Python identifiers.","title":"Build data"},{"location":"plugins/build-hook/reference/#notes","text":"In some cases it may be necessary to use force_include rather than artifacts . For example, say that you want to install a lib.so directly at the root of site-packages and a project defines a package src/foo . If you create src/lib.so , there will never be a match because the directory traversal starts at src/foo rather than src . In that case you must do either: build_data [ 'force_include' ][ 'src/lib.so' ] = 'src/lib.so' or build_data [ 'force_include' ][ '/absolute/path/to/src/lib.so' ] = 'src/lib.so'","title":"Notes"},{"location":"plugins/build-hook/reference/#hatchling.builders.hooks.plugin.interface.BuildHookInterface","text":"Example usage: plugin.py hooks.py from hatchling.builders.hooks.plugin.interface import BuildHookInterface class SpecialBuildHook ( BuildHookInterface ): PLUGIN_NAME = 'special' ... from hatchling.plugin import hookimpl from .plugin import SpecialBuildHook @hookimpl def hatch_register_build_hook (): return SpecialBuildHook Source code in hatchling/builders/hooks/plugin/interface.py class BuildHookInterface : # no cov \"\"\" Example usage: === \":octicons-file-code-16: plugin.py\" ```python from hatchling.builders.hooks.plugin.interface import BuildHookInterface class SpecialBuildHook(BuildHookInterface): PLUGIN_NAME = 'special' ... ``` === \":octicons-file-code-16: hooks.py\" ```python from hatchling.plugin import hookimpl from .plugin import SpecialBuildHook @hookimpl def hatch_register_build_hook(): return SpecialBuildHook ``` \"\"\" PLUGIN_NAME = '' \"\"\"The name used for selection.\"\"\" def __init__ ( self , root , config , build_config , metadata , directory , target_name , app = None ): self . __root = root self . __config = config self . __build_config = build_config self . __metadata = metadata self . __directory = directory self . __target_name = target_name self . __app = app @property def app ( self ): \"\"\" An instance of [Application](../utilities.md#hatchling.bridge.app.Application). \"\"\" if self . __app is None : from hatchling.bridge.app import Application self . __app = Application () . get_safe_application () return self . __app @property def root ( self ): \"\"\" The root of the project tree. \"\"\" return self . __root @property def config ( self ): \"\"\" The cumulative hook configuration. === \":octicons-file-code-16: pyproject.toml\" ```toml [tool.hatch.build.hooks.] [tool.hatch.build.targets..hooks.] ``` === \":octicons-file-code-16: hatch.toml\" ```toml [build.hooks.] [build.targets..hooks.] ``` \"\"\" return self . __config @property def metadata ( self ): # Undocumented for now return self . __metadata @property def build_config ( self ): \"\"\" An instance of [BuilderConfig](../utilities.md#hatchling.builders.config.BuilderConfig). \"\"\" return self . __build_config @property def directory ( self ): \"\"\" The build directory. \"\"\" return self . __directory @property def target_name ( self ): \"\"\" The plugin name of the build target. \"\"\" return self . __target_name def clean ( self , versions ): \"\"\" This occurs before the build process if the `-c`/`--clean` flag was passed to the [`build`](../../cli/reference.md#hatch-build) command, or when invoking the [`clean`](../../cli/reference.md#hatch-clean) command. \"\"\" def initialize ( self , version , build_data ): \"\"\" This occurs immediately before each build. Any modifications to the build data will be seen by the build target. \"\"\" def finalize ( self , version , build_data , artifact_path ): \"\"\" This occurs immediately after each build and will not run if the `--hooks-only` flag was passed to the [`build`](../../cli/reference.md#hatch-build) command. The build data will reflect any modifications done by the target during the build. \"\"\"","title":"BuildHookInterface"},{"location":"plugins/build-hook/reference/#hatchling.builders.hooks.plugin.interface.BuildHookInterface.PLUGIN_NAME","text":"The name used for selection.","title":"PLUGIN_NAME"},{"location":"plugins/build-hook/reference/#hatchling.builders.hooks.plugin.interface.BuildHookInterface.app","text":"An instance of Application . Source code in hatchling/builders/hooks/plugin/interface.py @property def app ( self ): \"\"\" An instance of [Application](../utilities.md#hatchling.bridge.app.Application). \"\"\" if self . __app is None : from hatchling.bridge.app import Application self . __app = Application () . get_safe_application () return self . __app","title":"app()"},{"location":"plugins/build-hook/reference/#hatchling.builders.hooks.plugin.interface.BuildHookInterface.root","text":"The root of the project tree. Source code in hatchling/builders/hooks/plugin/interface.py @property def root ( self ): \"\"\" The root of the project tree. \"\"\" return self . __root","title":"root()"},{"location":"plugins/build-hook/reference/#hatchling.builders.hooks.plugin.interface.BuildHookInterface.config","text":"The cumulative hook configuration. pyproject.toml hatch.toml [tool.hatch.build.hooks.] [tool.hatch.build.targets..hooks.] [build.hooks.] [build.targets..hooks.] Source code in hatchling/builders/hooks/plugin/interface.py @property def config ( self ): \"\"\" The cumulative hook configuration. === \":octicons-file-code-16: pyproject.toml\" ```toml [tool.hatch.build.hooks.] [tool.hatch.build.targets..hooks.] ``` === \":octicons-file-code-16: hatch.toml\" ```toml [build.hooks.] [build.targets..hooks.] ``` \"\"\" return self . __config","title":"config()"},{"location":"plugins/build-hook/reference/#hatchling.builders.hooks.plugin.interface.BuildHookInterface.build_config","text":"An instance of BuilderConfig . Source code in hatchling/builders/hooks/plugin/interface.py @property def build_config ( self ): \"\"\" An instance of [BuilderConfig](../utilities.md#hatchling.builders.config.BuilderConfig). \"\"\" return self . __build_config","title":"build_config()"},{"location":"plugins/build-hook/reference/#hatchling.builders.hooks.plugin.interface.BuildHookInterface.target_name","text":"The plugin name of the build target. Source code in hatchling/builders/hooks/plugin/interface.py @property def target_name ( self ): \"\"\" The plugin name of the build target. \"\"\" return self . __target_name","title":"target_name()"},{"location":"plugins/build-hook/reference/#hatchling.builders.hooks.plugin.interface.BuildHookInterface.directory","text":"The build directory. Source code in hatchling/builders/hooks/plugin/interface.py @property def directory ( self ): \"\"\" The build directory. \"\"\" return self . __directory","title":"directory()"},{"location":"plugins/build-hook/reference/#hatchling.builders.hooks.plugin.interface.BuildHookInterface.clean","text":"This occurs before the build process if the -c / --clean flag was passed to the build command, or when invoking the clean command. Source code in hatchling/builders/hooks/plugin/interface.py def clean ( self , versions ): \"\"\" This occurs before the build process if the `-c`/`--clean` flag was passed to the [`build`](../../cli/reference.md#hatch-build) command, or when invoking the [`clean`](../../cli/reference.md#hatch-clean) command. \"\"\"","title":"clean()"},{"location":"plugins/build-hook/reference/#hatchling.builders.hooks.plugin.interface.BuildHookInterface.initialize","text":"This occurs immediately before each build. Any modifications to the build data will be seen by the build target. Source code in hatchling/builders/hooks/plugin/interface.py def initialize ( self , version , build_data ): \"\"\" This occurs immediately before each build. Any modifications to the build data will be seen by the build target. \"\"\"","title":"initialize()"},{"location":"plugins/build-hook/reference/#hatchling.builders.hooks.plugin.interface.BuildHookInterface.finalize","text":"This occurs immediately after each build and will not run if the --hooks-only flag was passed to the build command. The build data will reflect any modifications done by the target during the build. Source code in hatchling/builders/hooks/plugin/interface.py def finalize ( self , version , build_data , artifact_path ): \"\"\" This occurs immediately after each build and will not run if the `--hooks-only` flag was passed to the [`build`](../../cli/reference.md#hatch-build) command. The build data will reflect any modifications done by the target during the build. \"\"\"","title":"finalize()"},{"location":"plugins/build-hook/version/","text":"Version build hook \u00b6 This writes the project's version to a file. Configuration \u00b6 The build hook plugin name is version . pyproject.toml hatch.toml [tool.hatch.build.hooks.version] [tool.hatch.build.targets..hooks.version] [build.hooks.version] [build.targets..hooks.version] Options \u00b6 Option Description path (required) A relative path to the desired file template A string representing the entire contents of path that will be formatted with a version variable pattern Rather than updating the entire file, a regular expression may be used that has a named group called version that represents the version. If set to true , a pattern will be used that looks for a variable named __version__ or VERSION that is set to a string containing the version, optionally prefixed with the lowercase letter v .","title":"Version"},{"location":"plugins/build-hook/version/#version-build-hook","text":"This writes the project's version to a file.","title":"Version build hook"},{"location":"plugins/build-hook/version/#configuration","text":"The build hook plugin name is version . pyproject.toml hatch.toml [tool.hatch.build.hooks.version] [tool.hatch.build.targets..hooks.version] [build.hooks.version] [build.targets..hooks.version]","title":"Configuration"},{"location":"plugins/build-hook/version/#options","text":"Option Description path (required) A relative path to the desired file template A string representing the entire contents of path that will be formatted with a version variable pattern Rather than updating the entire file, a regular expression may be used that has a named group called version that represents the version. If set to true , a pattern will be used that looks for a variable named __version__ or VERSION that is set to a string containing the version, optionally prefixed with the lowercase letter v .","title":"Options"},{"location":"plugins/builder/custom/","text":"Custom builder \u00b6 This is a custom class in a given Python file that inherits from the BuilderInterface . Configuration \u00b6 The builder plugin name is custom . pyproject.toml hatch.toml [tool.hatch.build.targets.custom] [build.targets.custom] Options \u00b6 Option Default Description path hatch_build.py The path of the Python file Example \u00b6 hatch_build.py from hatchling.builders.plugin.interface import BuilderInterface class CustomBuilder ( BuilderInterface ): ... If multiple subclasses are found, you must define a function named get_builder that returns the desired builder. Note Any defined PLUGIN_NAME is ignored and will always be custom .","title":"Custom"},{"location":"plugins/builder/custom/#custom-builder","text":"This is a custom class in a given Python file that inherits from the BuilderInterface .","title":"Custom builder"},{"location":"plugins/builder/custom/#configuration","text":"The builder plugin name is custom . pyproject.toml hatch.toml [tool.hatch.build.targets.custom] [build.targets.custom]","title":"Configuration"},{"location":"plugins/builder/custom/#options","text":"Option Default Description path hatch_build.py The path of the Python file","title":"Options"},{"location":"plugins/builder/custom/#example","text":"hatch_build.py from hatchling.builders.plugin.interface import BuilderInterface class CustomBuilder ( BuilderInterface ): ... If multiple subclasses are found, you must define a function named get_builder that returns the desired builder. Note Any defined PLUGIN_NAME is ignored and will always be custom .","title":"Example"},{"location":"plugins/builder/reference/","text":"Builder plugins \u00b6 See the documentation for build configuration . Known third-party \u00b6 hatch-aws - used for building AWS Lambda functions with SAM BuilderInterface \u00b6 Example usage: plugin.py hooks.py from hatchling.builders.plugin.interface import BuilderInterface class SpecialBuilder ( BuilderInterface ): PLUGIN_NAME = 'special' ... from hatchling.plugin import hookimpl from .plugin import SpecialBuilder @hookimpl def hatch_register_builder (): return SpecialBuilder Source code in hatchling/builders/plugin/interface.py class BuilderInterface ( ABC ): \"\"\" Example usage: === \":octicons-file-code-16: plugin.py\" ```python from hatchling.builders.plugin.interface import BuilderInterface class SpecialBuilder(BuilderInterface): PLUGIN_NAME = 'special' ... ``` === \":octicons-file-code-16: hooks.py\" ```python from hatchling.plugin import hookimpl from .plugin import SpecialBuilder @hookimpl def hatch_register_builder(): return SpecialBuilder ``` \"\"\" PLUGIN_NAME = '' \"\"\"The name used for selection.\"\"\" def __init__ ( self , root , plugin_manager = None , config = None , metadata = None , app = None ): self . __root = root self . __plugin_manager = plugin_manager self . __raw_config = config self . __metadata = metadata self . __app = app self . __config = None self . __project_config = None self . __hatch_config = None self . __build_config = None self . __build_targets = None self . __target_config = None # Metadata self . __project_id = None def build ( self , directory = None , versions = None , hooks_only = None , clean = None , clean_hooks_after = None , clean_only = False , ) -> Generator [ str , None , None ]: # Fail early for invalid project metadata self . metadata . validate_fields () if directory is None : if BuildEnvVars . LOCATION in os . environ : directory = self . config . normalize_build_directory ( os . environ [ BuildEnvVars . LOCATION ]) else : directory = self . config . directory if not os . path . isdir ( directory ): os . makedirs ( directory ) version_api = self . get_version_api () if not versions : versions = self . config . versions else : unknown_versions = set ( versions ) - set ( version_api ) if unknown_versions : raise ValueError ( f 'Unknown versions for target ` { self . PLUGIN_NAME } `: { \", \" . join ( map ( str , sorted ( unknown_versions ))) } ' ) if hooks_only is None : hooks_only = env_var_enabled ( BuildEnvVars . HOOKS_ONLY ) configured_build_hooks = self . get_build_hooks ( directory ) build_hooks = list ( configured_build_hooks . values ()) if clean_only : clean = True elif clean is None : clean = env_var_enabled ( BuildEnvVars . CLEAN ) if clean : if not hooks_only : self . clean ( directory , versions ) for build_hook in build_hooks : build_hook . clean ( versions ) if clean_only : return if clean_hooks_after is None : clean_hooks_after = env_var_enabled ( BuildEnvVars . CLEAN_HOOKS_AFTER ) for version in versions : self . app . display_debug ( f 'Building ` { self . PLUGIN_NAME } ` version ` { version } `' ) build_data = self . get_default_build_data () self . set_build_data_defaults ( build_data ) # Allow inspection of configured build hooks and the order in which they run build_data [ 'build_hooks' ] = tuple ( configured_build_hooks ) # Execute all `initialize` build hooks for build_hook in build_hooks : build_hook . initialize ( version , build_data ) if hooks_only : self . app . display_debug ( f 'Only ran build hooks for ` { self . PLUGIN_NAME } ` version ` { version } `' ) continue # Build the artifact with self . config . set_build_data ( build_data ): artifact = version_api [ version ]( directory , ** build_data ) # Execute all `finalize` build hooks for build_hook in build_hooks : build_hook . finalize ( version , build_data , artifact ) if clean_hooks_after : for build_hook in build_hooks : build_hook . clean ([ version ]) yield artifact def recurse_included_files ( self ) -> Generator [ IncludedFile , None , None ]: \"\"\" Returns a consistently generated series of file objects for every file that should be distributed. Each file object has three `str` attributes: - `path` - the absolute path - `relative_path` - the path relative to the project root; will be an empty string for external files - `distribution_path` - the path to be distributed as \"\"\" if self . config . only_include : yield from self . recurse_explicit_files ( self . config . only_include ) else : yield from self . recurse_project_files () yield from self . recurse_forced_files ( self . config . get_force_include ()) def recurse_project_files ( self ) -> Generator [ IncludedFile , None , None ]: for root , dirs , files in safe_walk ( self . root ): relative_path = get_relative_path ( root , self . root ) dirs [:] = sorted ( d for d in dirs if not self . config . directory_is_excluded ( d , relative_path )) files . sort () is_package = '__init__.py' in files for f in files : relative_file_path = os . path . join ( relative_path , f ) if self . config . include_path ( relative_file_path , is_package = is_package ): yield IncludedFile ( os . path . join ( root , f ), relative_file_path , self . config . get_distribution_path ( relative_file_path ) ) def recurse_forced_files ( self , inclusion_map ) -> Generator [ IncludedFile , None , None ]: for source , target_path in inclusion_map . items (): external = not source . startswith ( self . root ) if os . path . isfile ( source ): yield IncludedFile ( source , '' if external else os . path . relpath ( source , self . root ), self . config . get_distribution_path ( target_path ), ) elif os . path . isdir ( source ): for root , dirs , files in safe_walk ( source ): relative_directory = get_relative_path ( root , source ) dirs [:] = sorted ( d for d in dirs if d not in EXCLUDED_DIRECTORIES ) files . sort () for f in files : relative_file_path = os . path . join ( target_path , relative_directory , f ) if not self . config . path_is_reserved ( relative_file_path ): yield IncludedFile ( os . path . join ( root , f ), '' if external else relative_file_path , self . config . get_distribution_path ( relative_file_path ), ) def recurse_explicit_files ( self , inclusion_map ) -> Generator [ IncludedFile , None , None ]: for source , target_path in inclusion_map . items (): external = not source . startswith ( self . root ) if os . path . isfile ( source ): yield IncludedFile ( source , '' if external else os . path . relpath ( source , self . root ), self . config . get_distribution_path ( target_path ), ) elif os . path . isdir ( source ): for root , dirs , files in safe_walk ( source ): relative_directory = get_relative_path ( root , source ) dirs [:] = sorted ( d for d in dirs if d not in EXCLUDED_DIRECTORIES ) files . sort () is_package = '__init__.py' in files for f in files : relative_file_path = os . path . join ( target_path , relative_directory , f ) if self . config . include_path ( relative_file_path , explicit = True , is_package = is_package ): yield IncludedFile ( os . path . join ( root , f ), '' if external else relative_file_path , self . config . get_distribution_path ( relative_file_path ), ) @property def root ( self ): \"\"\" The root of the project tree. \"\"\" return self . __root @property def plugin_manager ( self ): if self . __plugin_manager is None : from hatchling.plugin.manager import PluginManager self . __plugin_manager = PluginManager () return self . __plugin_manager @property def metadata ( self ): if self . __metadata is None : from hatchling.metadata.core import ProjectMetadata self . __metadata = ProjectMetadata ( self . root , self . plugin_manager , self . __raw_config ) return self . __metadata @property def app ( self ): \"\"\" An instance of [Application](../utilities.md#hatchling.bridge.app.Application). \"\"\" if self . __app is None : from hatchling.bridge.app import Application self . __app = Application () . get_safe_application () return self . __app @property def raw_config ( self ): if self . __raw_config is None : self . __raw_config = self . metadata . config return self . __raw_config @property def project_config ( self ): if self . __project_config is None : self . __project_config = self . metadata . core . config return self . __project_config @property def hatch_config ( self ): if self . __hatch_config is None : self . __hatch_config = self . metadata . hatch . config return self . __hatch_config @property def config ( self ): \"\"\" An instance of [BuilderConfig](../utilities.md#hatchling.builders.config.BuilderConfig). \"\"\" if self . __config is None : self . __config = self . get_config_class ()( self , self . root , self . PLUGIN_NAME , self . build_config , self . target_config ) return self . __config @property def build_config ( self ): \"\"\" === \":octicons-file-code-16: pyproject.toml\" ```toml [tool.hatch.build] ``` === \":octicons-file-code-16: hatch.toml\" ```toml [build] ``` \"\"\" if self . __build_config is None : self . __build_config = self . metadata . hatch . build_config return self . __build_config @property def target_config ( self ): \"\"\" === \":octicons-file-code-16: pyproject.toml\" ```toml [tool.hatch.build.targets.] ``` === \":octicons-file-code-16: hatch.toml\" ```toml [build.targets.] ``` \"\"\" if self . __target_config is None : target_config = self . metadata . hatch . build_targets . get ( self . PLUGIN_NAME , {}) if not isinstance ( target_config , dict ): raise TypeError ( f 'Field `tool.hatch.build.targets. { self . PLUGIN_NAME } ` must be a table' ) self . __target_config = target_config return self . __target_config @property def project_id ( self ): if self . __project_id is None : self . __project_id = f ' { self . normalize_file_name_component ( self . metadata . core . name ) } - { self . metadata . version } ' return self . __project_id def get_build_hooks ( self , directory ): configured_build_hooks = {} for hook_name , config in self . config . hook_config . items (): build_hook = self . plugin_manager . build_hook . get ( hook_name ) if build_hook is None : from hatchling.plugin.exceptions import UnknownPluginError raise UnknownPluginError ( f 'Unknown build hook: { hook_name } ' ) configured_build_hooks [ hook_name ] = build_hook ( self . root , config , self . config , self . metadata , directory , self . PLUGIN_NAME , self . app ) return configured_build_hooks @abstractmethod def get_version_api ( self ) -> dict [ str , Callable ]: \"\"\" A mapping of `str` versions to a callable that is used for building. Each callable must have the following signature: ```python def ...(build_dir: str, build_data: dict) -> str: ``` The return value must be the absolute path to the built artifact. \"\"\" def get_default_versions ( self ): \"\"\" A list of versions to build when users do not specify any, defaulting to all versions. \"\"\" return list ( self . get_version_api ()) def get_default_build_data ( self ): \"\"\" A mapping that can be modified by [build hooks](../build-hook/reference.md) to influence the behavior of builds. \"\"\" return {} def set_build_data_defaults ( self , build_data ): build_data . setdefault ( 'artifacts' , []) build_data . setdefault ( 'force_include' , {}) def clean ( self , directory , versions ): \"\"\" Called before builds if the `-c`/`--clean` flag was passed to the [`build`](../../cli/reference.md#hatch-build) command. \"\"\" @classmethod def get_config_class ( cls ): \"\"\" Must return a subclass of [BuilderConfig](../utilities.md#hatchling.builders.config.BuilderConfig). \"\"\" return BuilderConfig @staticmethod def normalize_file_name_component ( file_name ): \"\"\" https://peps.python.org/pep-0427/#escaping-and-unicode \"\"\" return re . sub ( r '[^\\w\\d.]+' , '_' , file_name , re . UNICODE ) PLUGIN_NAME = '' class-attribute \u00b6 The name used for selection. app () property \u00b6 An instance of Application . Source code in hatchling/builders/plugin/interface.py @property def app ( self ): \"\"\" An instance of [Application](../utilities.md#hatchling.bridge.app.Application). \"\"\" if self . __app is None : from hatchling.bridge.app import Application self . __app = Application () . get_safe_application () return self . __app root () property \u00b6 The root of the project tree. Source code in hatchling/builders/plugin/interface.py @property def root ( self ): \"\"\" The root of the project tree. \"\"\" return self . __root build_config () property \u00b6 pyproject.toml hatch.toml [tool.hatch.build] [build] Source code in hatchling/builders/plugin/interface.py @property def build_config ( self ): \"\"\" === \":octicons-file-code-16: pyproject.toml\" ```toml [tool.hatch.build] ``` === \":octicons-file-code-16: hatch.toml\" ```toml [build] ``` \"\"\" if self . __build_config is None : self . __build_config = self . metadata . hatch . build_config return self . __build_config target_config () property \u00b6 pyproject.toml hatch.toml [tool.hatch.build.targets.] [build.targets.] Source code in hatchling/builders/plugin/interface.py @property def target_config ( self ): \"\"\" === \":octicons-file-code-16: pyproject.toml\" ```toml [tool.hatch.build.targets.] ``` === \":octicons-file-code-16: hatch.toml\" ```toml [build.targets.] ``` \"\"\" if self . __target_config is None : target_config = self . metadata . hatch . build_targets . get ( self . PLUGIN_NAME , {}) if not isinstance ( target_config , dict ): raise TypeError ( f 'Field `tool.hatch.build.targets. { self . PLUGIN_NAME } ` must be a table' ) self . __target_config = target_config return self . __target_config config () property \u00b6 An instance of BuilderConfig . Source code in hatchling/builders/plugin/interface.py @property def config ( self ): \"\"\" An instance of [BuilderConfig](../utilities.md#hatchling.builders.config.BuilderConfig). \"\"\" if self . __config is None : self . __config = self . get_config_class ()( self , self . root , self . PLUGIN_NAME , self . build_config , self . target_config ) return self . __config get_config_class () classmethod \u00b6 Must return a subclass of BuilderConfig . Source code in hatchling/builders/plugin/interface.py @classmethod def get_config_class ( cls ): \"\"\" Must return a subclass of [BuilderConfig](../utilities.md#hatchling.builders.config.BuilderConfig). \"\"\" return BuilderConfig get_version_api () -> dict [ str , Callable ] abstractmethod \u00b6 A mapping of str versions to a callable that is used for building. Each callable must have the following signature: def ... ( build_dir : str , build_data : dict ) -> str : The return value must be the absolute path to the built artifact. Source code in hatchling/builders/plugin/interface.py @abstractmethod def get_version_api ( self ) -> dict [ str , Callable ]: \"\"\" A mapping of `str` versions to a callable that is used for building. Each callable must have the following signature: ```python def ...(build_dir: str, build_data: dict) -> str: ``` The return value must be the absolute path to the built artifact. \"\"\" get_default_versions () \u00b6 A list of versions to build when users do not specify any, defaulting to all versions. Source code in hatchling/builders/plugin/interface.py def get_default_versions ( self ): \"\"\" A list of versions to build when users do not specify any, defaulting to all versions. \"\"\" return list ( self . get_version_api ()) clean ( directory , versions ) \u00b6 Called before builds if the -c / --clean flag was passed to the build command. Source code in hatchling/builders/plugin/interface.py def clean ( self , directory , versions ): \"\"\" Called before builds if the `-c`/`--clean` flag was passed to the [`build`](../../cli/reference.md#hatch-build) command. \"\"\" recurse_included_files () -> Generator [ IncludedFile , None , None ] \u00b6 Returns a consistently generated series of file objects for every file that should be distributed. Each file object has three str attributes: path - the absolute path relative_path - the path relative to the project root; will be an empty string for external files distribution_path - the path to be distributed as Source code in hatchling/builders/plugin/interface.py def recurse_included_files ( self ) -> Generator [ IncludedFile , None , None ]: \"\"\" Returns a consistently generated series of file objects for every file that should be distributed. Each file object has three `str` attributes: - `path` - the absolute path - `relative_path` - the path relative to the project root; will be an empty string for external files - `distribution_path` - the path to be distributed as \"\"\" if self . config . only_include : yield from self . recurse_explicit_files ( self . config . only_include ) else : yield from self . recurse_project_files () yield from self . recurse_forced_files ( self . config . get_force_include ()) get_default_build_data () \u00b6 A mapping that can be modified by build hooks to influence the behavior of builds. Source code in hatchling/builders/plugin/interface.py def get_default_build_data ( self ): \"\"\" A mapping that can be modified by [build hooks](../build-hook/reference.md) to influence the behavior of builds. \"\"\" return {}","title":"Reference"},{"location":"plugins/builder/reference/#builder-plugins","text":"See the documentation for build configuration .","title":"Builder plugins"},{"location":"plugins/builder/reference/#known-third-party","text":"hatch-aws - used for building AWS Lambda functions with SAM","title":"Known third-party"},{"location":"plugins/builder/reference/#hatchling.builders.plugin.interface.BuilderInterface","text":"Example usage: plugin.py hooks.py from hatchling.builders.plugin.interface import BuilderInterface class SpecialBuilder ( BuilderInterface ): PLUGIN_NAME = 'special' ... from hatchling.plugin import hookimpl from .plugin import SpecialBuilder @hookimpl def hatch_register_builder (): return SpecialBuilder Source code in hatchling/builders/plugin/interface.py class BuilderInterface ( ABC ): \"\"\" Example usage: === \":octicons-file-code-16: plugin.py\" ```python from hatchling.builders.plugin.interface import BuilderInterface class SpecialBuilder(BuilderInterface): PLUGIN_NAME = 'special' ... ``` === \":octicons-file-code-16: hooks.py\" ```python from hatchling.plugin import hookimpl from .plugin import SpecialBuilder @hookimpl def hatch_register_builder(): return SpecialBuilder ``` \"\"\" PLUGIN_NAME = '' \"\"\"The name used for selection.\"\"\" def __init__ ( self , root , plugin_manager = None , config = None , metadata = None , app = None ): self . __root = root self . __plugin_manager = plugin_manager self . __raw_config = config self . __metadata = metadata self . __app = app self . __config = None self . __project_config = None self . __hatch_config = None self . __build_config = None self . __build_targets = None self . __target_config = None # Metadata self . __project_id = None def build ( self , directory = None , versions = None , hooks_only = None , clean = None , clean_hooks_after = None , clean_only = False , ) -> Generator [ str , None , None ]: # Fail early for invalid project metadata self . metadata . validate_fields () if directory is None : if BuildEnvVars . LOCATION in os . environ : directory = self . config . normalize_build_directory ( os . environ [ BuildEnvVars . LOCATION ]) else : directory = self . config . directory if not os . path . isdir ( directory ): os . makedirs ( directory ) version_api = self . get_version_api () if not versions : versions = self . config . versions else : unknown_versions = set ( versions ) - set ( version_api ) if unknown_versions : raise ValueError ( f 'Unknown versions for target ` { self . PLUGIN_NAME } `: { \", \" . join ( map ( str , sorted ( unknown_versions ))) } ' ) if hooks_only is None : hooks_only = env_var_enabled ( BuildEnvVars . HOOKS_ONLY ) configured_build_hooks = self . get_build_hooks ( directory ) build_hooks = list ( configured_build_hooks . values ()) if clean_only : clean = True elif clean is None : clean = env_var_enabled ( BuildEnvVars . CLEAN ) if clean : if not hooks_only : self . clean ( directory , versions ) for build_hook in build_hooks : build_hook . clean ( versions ) if clean_only : return if clean_hooks_after is None : clean_hooks_after = env_var_enabled ( BuildEnvVars . CLEAN_HOOKS_AFTER ) for version in versions : self . app . display_debug ( f 'Building ` { self . PLUGIN_NAME } ` version ` { version } `' ) build_data = self . get_default_build_data () self . set_build_data_defaults ( build_data ) # Allow inspection of configured build hooks and the order in which they run build_data [ 'build_hooks' ] = tuple ( configured_build_hooks ) # Execute all `initialize` build hooks for build_hook in build_hooks : build_hook . initialize ( version , build_data ) if hooks_only : self . app . display_debug ( f 'Only ran build hooks for ` { self . PLUGIN_NAME } ` version ` { version } `' ) continue # Build the artifact with self . config . set_build_data ( build_data ): artifact = version_api [ version ]( directory , ** build_data ) # Execute all `finalize` build hooks for build_hook in build_hooks : build_hook . finalize ( version , build_data , artifact ) if clean_hooks_after : for build_hook in build_hooks : build_hook . clean ([ version ]) yield artifact def recurse_included_files ( self ) -> Generator [ IncludedFile , None , None ]: \"\"\" Returns a consistently generated series of file objects for every file that should be distributed. Each file object has three `str` attributes: - `path` - the absolute path - `relative_path` - the path relative to the project root; will be an empty string for external files - `distribution_path` - the path to be distributed as \"\"\" if self . config . only_include : yield from self . recurse_explicit_files ( self . config . only_include ) else : yield from self . recurse_project_files () yield from self . recurse_forced_files ( self . config . get_force_include ()) def recurse_project_files ( self ) -> Generator [ IncludedFile , None , None ]: for root , dirs , files in safe_walk ( self . root ): relative_path = get_relative_path ( root , self . root ) dirs [:] = sorted ( d for d in dirs if not self . config . directory_is_excluded ( d , relative_path )) files . sort () is_package = '__init__.py' in files for f in files : relative_file_path = os . path . join ( relative_path , f ) if self . config . include_path ( relative_file_path , is_package = is_package ): yield IncludedFile ( os . path . join ( root , f ), relative_file_path , self . config . get_distribution_path ( relative_file_path ) ) def recurse_forced_files ( self , inclusion_map ) -> Generator [ IncludedFile , None , None ]: for source , target_path in inclusion_map . items (): external = not source . startswith ( self . root ) if os . path . isfile ( source ): yield IncludedFile ( source , '' if external else os . path . relpath ( source , self . root ), self . config . get_distribution_path ( target_path ), ) elif os . path . isdir ( source ): for root , dirs , files in safe_walk ( source ): relative_directory = get_relative_path ( root , source ) dirs [:] = sorted ( d for d in dirs if d not in EXCLUDED_DIRECTORIES ) files . sort () for f in files : relative_file_path = os . path . join ( target_path , relative_directory , f ) if not self . config . path_is_reserved ( relative_file_path ): yield IncludedFile ( os . path . join ( root , f ), '' if external else relative_file_path , self . config . get_distribution_path ( relative_file_path ), ) def recurse_explicit_files ( self , inclusion_map ) -> Generator [ IncludedFile , None , None ]: for source , target_path in inclusion_map . items (): external = not source . startswith ( self . root ) if os . path . isfile ( source ): yield IncludedFile ( source , '' if external else os . path . relpath ( source , self . root ), self . config . get_distribution_path ( target_path ), ) elif os . path . isdir ( source ): for root , dirs , files in safe_walk ( source ): relative_directory = get_relative_path ( root , source ) dirs [:] = sorted ( d for d in dirs if d not in EXCLUDED_DIRECTORIES ) files . sort () is_package = '__init__.py' in files for f in files : relative_file_path = os . path . join ( target_path , relative_directory , f ) if self . config . include_path ( relative_file_path , explicit = True , is_package = is_package ): yield IncludedFile ( os . path . join ( root , f ), '' if external else relative_file_path , self . config . get_distribution_path ( relative_file_path ), ) @property def root ( self ): \"\"\" The root of the project tree. \"\"\" return self . __root @property def plugin_manager ( self ): if self . __plugin_manager is None : from hatchling.plugin.manager import PluginManager self . __plugin_manager = PluginManager () return self . __plugin_manager @property def metadata ( self ): if self . __metadata is None : from hatchling.metadata.core import ProjectMetadata self . __metadata = ProjectMetadata ( self . root , self . plugin_manager , self . __raw_config ) return self . __metadata @property def app ( self ): \"\"\" An instance of [Application](../utilities.md#hatchling.bridge.app.Application). \"\"\" if self . __app is None : from hatchling.bridge.app import Application self . __app = Application () . get_safe_application () return self . __app @property def raw_config ( self ): if self . __raw_config is None : self . __raw_config = self . metadata . config return self . __raw_config @property def project_config ( self ): if self . __project_config is None : self . __project_config = self . metadata . core . config return self . __project_config @property def hatch_config ( self ): if self . __hatch_config is None : self . __hatch_config = self . metadata . hatch . config return self . __hatch_config @property def config ( self ): \"\"\" An instance of [BuilderConfig](../utilities.md#hatchling.builders.config.BuilderConfig). \"\"\" if self . __config is None : self . __config = self . get_config_class ()( self , self . root , self . PLUGIN_NAME , self . build_config , self . target_config ) return self . __config @property def build_config ( self ): \"\"\" === \":octicons-file-code-16: pyproject.toml\" ```toml [tool.hatch.build] ``` === \":octicons-file-code-16: hatch.toml\" ```toml [build] ``` \"\"\" if self . __build_config is None : self . __build_config = self . metadata . hatch . build_config return self . __build_config @property def target_config ( self ): \"\"\" === \":octicons-file-code-16: pyproject.toml\" ```toml [tool.hatch.build.targets.] ``` === \":octicons-file-code-16: hatch.toml\" ```toml [build.targets.] ``` \"\"\" if self . __target_config is None : target_config = self . metadata . hatch . build_targets . get ( self . PLUGIN_NAME , {}) if not isinstance ( target_config , dict ): raise TypeError ( f 'Field `tool.hatch.build.targets. { self . PLUGIN_NAME } ` must be a table' ) self . __target_config = target_config return self . __target_config @property def project_id ( self ): if self . __project_id is None : self . __project_id = f ' { self . normalize_file_name_component ( self . metadata . core . name ) } - { self . metadata . version } ' return self . __project_id def get_build_hooks ( self , directory ): configured_build_hooks = {} for hook_name , config in self . config . hook_config . items (): build_hook = self . plugin_manager . build_hook . get ( hook_name ) if build_hook is None : from hatchling.plugin.exceptions import UnknownPluginError raise UnknownPluginError ( f 'Unknown build hook: { hook_name } ' ) configured_build_hooks [ hook_name ] = build_hook ( self . root , config , self . config , self . metadata , directory , self . PLUGIN_NAME , self . app ) return configured_build_hooks @abstractmethod def get_version_api ( self ) -> dict [ str , Callable ]: \"\"\" A mapping of `str` versions to a callable that is used for building. Each callable must have the following signature: ```python def ...(build_dir: str, build_data: dict) -> str: ``` The return value must be the absolute path to the built artifact. \"\"\" def get_default_versions ( self ): \"\"\" A list of versions to build when users do not specify any, defaulting to all versions. \"\"\" return list ( self . get_version_api ()) def get_default_build_data ( self ): \"\"\" A mapping that can be modified by [build hooks](../build-hook/reference.md) to influence the behavior of builds. \"\"\" return {} def set_build_data_defaults ( self , build_data ): build_data . setdefault ( 'artifacts' , []) build_data . setdefault ( 'force_include' , {}) def clean ( self , directory , versions ): \"\"\" Called before builds if the `-c`/`--clean` flag was passed to the [`build`](../../cli/reference.md#hatch-build) command. \"\"\" @classmethod def get_config_class ( cls ): \"\"\" Must return a subclass of [BuilderConfig](../utilities.md#hatchling.builders.config.BuilderConfig). \"\"\" return BuilderConfig @staticmethod def normalize_file_name_component ( file_name ): \"\"\" https://peps.python.org/pep-0427/#escaping-and-unicode \"\"\" return re . sub ( r '[^\\w\\d.]+' , '_' , file_name , re . UNICODE )","title":"BuilderInterface"},{"location":"plugins/builder/reference/#hatchling.builders.plugin.interface.BuilderInterface.PLUGIN_NAME","text":"The name used for selection.","title":"PLUGIN_NAME"},{"location":"plugins/builder/reference/#hatchling.builders.plugin.interface.BuilderInterface.app","text":"An instance of Application . Source code in hatchling/builders/plugin/interface.py @property def app ( self ): \"\"\" An instance of [Application](../utilities.md#hatchling.bridge.app.Application). \"\"\" if self . __app is None : from hatchling.bridge.app import Application self . __app = Application () . get_safe_application () return self . __app","title":"app()"},{"location":"plugins/builder/reference/#hatchling.builders.plugin.interface.BuilderInterface.root","text":"The root of the project tree. Source code in hatchling/builders/plugin/interface.py @property def root ( self ): \"\"\" The root of the project tree. \"\"\" return self . __root","title":"root()"},{"location":"plugins/builder/reference/#hatchling.builders.plugin.interface.BuilderInterface.build_config","text":"pyproject.toml hatch.toml [tool.hatch.build] [build] Source code in hatchling/builders/plugin/interface.py @property def build_config ( self ): \"\"\" === \":octicons-file-code-16: pyproject.toml\" ```toml [tool.hatch.build] ``` === \":octicons-file-code-16: hatch.toml\" ```toml [build] ``` \"\"\" if self . __build_config is None : self . __build_config = self . metadata . hatch . build_config return self . __build_config","title":"build_config()"},{"location":"plugins/builder/reference/#hatchling.builders.plugin.interface.BuilderInterface.target_config","text":"pyproject.toml hatch.toml [tool.hatch.build.targets.] [build.targets.] Source code in hatchling/builders/plugin/interface.py @property def target_config ( self ): \"\"\" === \":octicons-file-code-16: pyproject.toml\" ```toml [tool.hatch.build.targets.] ``` === \":octicons-file-code-16: hatch.toml\" ```toml [build.targets.] ``` \"\"\" if self . __target_config is None : target_config = self . metadata . hatch . build_targets . get ( self . PLUGIN_NAME , {}) if not isinstance ( target_config , dict ): raise TypeError ( f 'Field `tool.hatch.build.targets. { self . PLUGIN_NAME } ` must be a table' ) self . __target_config = target_config return self . __target_config","title":"target_config()"},{"location":"plugins/builder/reference/#hatchling.builders.plugin.interface.BuilderInterface.config","text":"An instance of BuilderConfig . Source code in hatchling/builders/plugin/interface.py @property def config ( self ): \"\"\" An instance of [BuilderConfig](../utilities.md#hatchling.builders.config.BuilderConfig). \"\"\" if self . __config is None : self . __config = self . get_config_class ()( self , self . root , self . PLUGIN_NAME , self . build_config , self . target_config ) return self . __config","title":"config()"},{"location":"plugins/builder/reference/#hatchling.builders.plugin.interface.BuilderInterface.get_config_class","text":"Must return a subclass of BuilderConfig . Source code in hatchling/builders/plugin/interface.py @classmethod def get_config_class ( cls ): \"\"\" Must return a subclass of [BuilderConfig](../utilities.md#hatchling.builders.config.BuilderConfig). \"\"\" return BuilderConfig","title":"get_config_class()"},{"location":"plugins/builder/reference/#hatchling.builders.plugin.interface.BuilderInterface.get_version_api","text":"A mapping of str versions to a callable that is used for building. Each callable must have the following signature: def ... ( build_dir : str , build_data : dict ) -> str : The return value must be the absolute path to the built artifact. Source code in hatchling/builders/plugin/interface.py @abstractmethod def get_version_api ( self ) -> dict [ str , Callable ]: \"\"\" A mapping of `str` versions to a callable that is used for building. Each callable must have the following signature: ```python def ...(build_dir: str, build_data: dict) -> str: ``` The return value must be the absolute path to the built artifact. \"\"\"","title":"get_version_api()"},{"location":"plugins/builder/reference/#hatchling.builders.plugin.interface.BuilderInterface.get_default_versions","text":"A list of versions to build when users do not specify any, defaulting to all versions. Source code in hatchling/builders/plugin/interface.py def get_default_versions ( self ): \"\"\" A list of versions to build when users do not specify any, defaulting to all versions. \"\"\" return list ( self . get_version_api ())","title":"get_default_versions()"},{"location":"plugins/builder/reference/#hatchling.builders.plugin.interface.BuilderInterface.clean","text":"Called before builds if the -c / --clean flag was passed to the build command. Source code in hatchling/builders/plugin/interface.py def clean ( self , directory , versions ): \"\"\" Called before builds if the `-c`/`--clean` flag was passed to the [`build`](../../cli/reference.md#hatch-build) command. \"\"\"","title":"clean()"},{"location":"plugins/builder/reference/#hatchling.builders.plugin.interface.BuilderInterface.recurse_included_files","text":"Returns a consistently generated series of file objects for every file that should be distributed. Each file object has three str attributes: path - the absolute path relative_path - the path relative to the project root; will be an empty string for external files distribution_path - the path to be distributed as Source code in hatchling/builders/plugin/interface.py def recurse_included_files ( self ) -> Generator [ IncludedFile , None , None ]: \"\"\" Returns a consistently generated series of file objects for every file that should be distributed. Each file object has three `str` attributes: - `path` - the absolute path - `relative_path` - the path relative to the project root; will be an empty string for external files - `distribution_path` - the path to be distributed as \"\"\" if self . config . only_include : yield from self . recurse_explicit_files ( self . config . only_include ) else : yield from self . recurse_project_files () yield from self . recurse_forced_files ( self . config . get_force_include ())","title":"recurse_included_files()"},{"location":"plugins/builder/reference/#hatchling.builders.plugin.interface.BuilderInterface.get_default_build_data","text":"A mapping that can be modified by build hooks to influence the behavior of builds. Source code in hatchling/builders/plugin/interface.py def get_default_build_data ( self ): \"\"\" A mapping that can be modified by [build hooks](../build-hook/reference.md) to influence the behavior of builds. \"\"\" return {}","title":"get_default_build_data()"},{"location":"plugins/builder/sdist/","text":"Source distribution builder \u00b6 A source distribution, or sdist , is an archive of Python \"source code\". Although largely unspecified, by convention it should include everything that is required to build a wheel without making network requests. Configuration \u00b6 The builder plugin name is sdist . pyproject.toml hatch.toml [tool.hatch.build.targets.sdist] [build.targets.sdist] Options \u00b6 Option Default Description core-metadata-version \"2.1\" The version of core metadata to use strict-naming true Whether or not file names should contain the normalized version of the project name support-legacy false Whether or not to include a setup.py file to support legacy installation mechanisms Versions \u00b6 Version Description standard (default) The latest conventional format Default file selection \u00b6 When the user has not set any file selection options, all files that are not ignored by your VCS will be included. Note The following files are always included and cannot be excluded: /pyproject.toml /hatch.toml /hatch_build.py /.gitignore or /.hgignore Any defined readme file All defined license-files Reproducibility \u00b6 Reproducible builds are supported. Build data \u00b6 This is data that can be modified by build hooks . Data Default Description dependencies Extra project dependencies","title":"Source distribution"},{"location":"plugins/builder/sdist/#source-distribution-builder","text":"A source distribution, or sdist , is an archive of Python \"source code\". Although largely unspecified, by convention it should include everything that is required to build a wheel without making network requests.","title":"Source distribution builder"},{"location":"plugins/builder/sdist/#configuration","text":"The builder plugin name is sdist . pyproject.toml hatch.toml [tool.hatch.build.targets.sdist] [build.targets.sdist]","title":"Configuration"},{"location":"plugins/builder/sdist/#options","text":"Option Default Description core-metadata-version \"2.1\" The version of core metadata to use strict-naming true Whether or not file names should contain the normalized version of the project name support-legacy false Whether or not to include a setup.py file to support legacy installation mechanisms","title":"Options"},{"location":"plugins/builder/sdist/#versions","text":"Version Description standard (default) The latest conventional format","title":"Versions"},{"location":"plugins/builder/sdist/#default-file-selection","text":"When the user has not set any file selection options, all files that are not ignored by your VCS will be included. Note The following files are always included and cannot be excluded: /pyproject.toml /hatch.toml /hatch_build.py /.gitignore or /.hgignore Any defined readme file All defined license-files","title":"Default file selection"},{"location":"plugins/builder/sdist/#reproducibility","text":"Reproducible builds are supported.","title":"Reproducibility"},{"location":"plugins/builder/sdist/#build-data","text":"This is data that can be modified by build hooks . Data Default Description dependencies Extra project dependencies","title":"Build data"},{"location":"plugins/builder/wheel/","text":"Wheel builder \u00b6 A wheel is a binary distribution of a Python package that can be installed directly into an environment. Configuration \u00b6 The builder plugin name is wheel . pyproject.toml hatch.toml [tool.hatch.build.targets.wheel] [build.targets.wheel] Options \u00b6 Option Default Description core-metadata-version \"2.1\" The version of core metadata to use shared-data A mapping similar to the forced inclusion option corresponding to data that will be installed globally in a given Python environment, usually under sys . prefix extra-metadata A mapping similar to the forced inclusion option corresponding to extra metadata that will be shipped in a directory named extra_metadata strict-naming true Whether or not file names should contain the normalized version of the project name Versions \u00b6 Version Description standard (default) The latest standardized format editable A wheel that only ships .pth files or import hooks for real-time development Default file selection \u00b6 When the user has not set any file selection options, the project name will be used to determine the package to ship in the following heuristic order: /__init__.py src//__init__.py .py //__init__.py Otherwise, every Python package and file that does not start with the word test will be included Reproducibility \u00b6 Reproducible builds are supported. Build data \u00b6 This is data that can be modified by build hooks . Data Default Description tag The full tag part of the filename (e.g. py3-none-any ), defaulting to a cross-platform wheel with the supported major versions of Python based on project metadata infer_tag False When tag is not set, this may be enabled to use the one most specific to the platform, Python interpreter, and ABI pure_python True Whether or not to write metadata indicating that the package does not contain any platform-specific files dependencies Extra project dependencies force_include_editable Similar to the force_include option but specifically for the editable version and takes precedence","title":"Wheel"},{"location":"plugins/builder/wheel/#wheel-builder","text":"A wheel is a binary distribution of a Python package that can be installed directly into an environment.","title":"Wheel builder"},{"location":"plugins/builder/wheel/#configuration","text":"The builder plugin name is wheel . pyproject.toml hatch.toml [tool.hatch.build.targets.wheel] [build.targets.wheel]","title":"Configuration"},{"location":"plugins/builder/wheel/#options","text":"Option Default Description core-metadata-version \"2.1\" The version of core metadata to use shared-data A mapping similar to the forced inclusion option corresponding to data that will be installed globally in a given Python environment, usually under sys . prefix extra-metadata A mapping similar to the forced inclusion option corresponding to extra metadata that will be shipped in a directory named extra_metadata strict-naming true Whether or not file names should contain the normalized version of the project name","title":"Options"},{"location":"plugins/builder/wheel/#versions","text":"Version Description standard (default) The latest standardized format editable A wheel that only ships .pth files or import hooks for real-time development","title":"Versions"},{"location":"plugins/builder/wheel/#default-file-selection","text":"When the user has not set any file selection options, the project name will be used to determine the package to ship in the following heuristic order: /__init__.py src//__init__.py .py //__init__.py Otherwise, every Python package and file that does not start with the word test will be included","title":"Default file selection"},{"location":"plugins/builder/wheel/#reproducibility","text":"Reproducible builds are supported.","title":"Reproducibility"},{"location":"plugins/builder/wheel/#build-data","text":"This is data that can be modified by build hooks . Data Default Description tag The full tag part of the filename (e.g. py3-none-any ), defaulting to a cross-platform wheel with the supported major versions of Python based on project metadata infer_tag False When tag is not set, this may be enabled to use the one most specific to the platform, Python interpreter, and ABI pure_python True Whether or not to write metadata indicating that the package does not contain any platform-specific files dependencies Extra project dependencies force_include_editable Similar to the force_include option but specifically for the editable version and takes precedence","title":"Build data"},{"location":"plugins/environment/reference/","text":"Environment plugins \u00b6 See the documentation for environment configuration . Known third-party \u00b6 hatch-conda - environments backed by Conda/Mamba hatch-containers - environments run inside containers Life cycle \u00b6 Whenever an environment is used, the following logic is performed: Source code in hatch/cli/application.py def prepare_environment ( self , environment ): if not environment . exists (): with self . status_waiting ( f 'Creating environment: { environment . name } ' ): environment . create () if not environment . skip_install : if environment . pre_install_commands : with self . status_waiting ( 'Running pre-installation commands' ): self . run_shell_commands ( environment , environment . pre_install_commands , source = 'pre-install' ) if environment . dev_mode : with self . status_waiting ( 'Installing project in development mode' ): environment . install_project_dev_mode () else : with self . status_waiting ( 'Installing project' ): environment . install_project () if environment . post_install_commands : with self . status_waiting ( 'Running post-installation commands' ): self . run_shell_commands ( environment , environment . post_install_commands , source = 'post-install' ) with self . status_waiting ( 'Checking dependencies' ): dependencies_in_sync = environment . dependencies_in_sync () if not dependencies_in_sync : with self . status_waiting ( 'Syncing dependencies' ): environment . sync_dependencies () EnvironmentInterface \u00b6 Example usage: plugin.py hooks.py from hatch.env.plugin.interface import EnvironmentInterface class SpecialEnvironment ( EnvironmentInterface ): PLUGIN_NAME = 'special' ... from hatchling.plugin import hookimpl from .plugin import SpecialEnvironment @hookimpl def hatch_register_environment (): return SpecialEnvironment Source code in hatch/env/plugin/interface.py class EnvironmentInterface ( ABC ): \"\"\" Example usage: === \":octicons-file-code-16: plugin.py\" ```python from hatch.env.plugin.interface import EnvironmentInterface class SpecialEnvironment(EnvironmentInterface): PLUGIN_NAME = 'special' ... ``` === \":octicons-file-code-16: hooks.py\" ```python from hatchling.plugin import hookimpl from .plugin import SpecialEnvironment @hookimpl def hatch_register_environment(): return SpecialEnvironment ``` \"\"\" PLUGIN_NAME = '' \"\"\"The name used for selection.\"\"\" def __init__ ( self , root , metadata , name , config , matrix_variables , data_directory , platform , verbosity , app = None ): self . __root = root self . __metadata = metadata self . __name = name self . __config = config self . __matrix_variables = matrix_variables self . __data_directory = data_directory self . __platform = platform self . __verbosity = verbosity self . __app = app self . __context = None self . _system_python = None self . _env_vars = None self . _env_include = None self . _env_exclude = None self . _environment_dependencies_complex = None self . _environment_dependencies = None self . _dependencies_complex = None self . _dependencies = None self . _platforms = None self . _skip_install = None self . _dev_mode = None self . _features = None self . _description = None self . _scripts = None self . _pre_install_commands = None self . _post_install_commands = None @property def matrix_variables ( self ): return self . __matrix_variables @property def app ( self ): \"\"\" An instance of [Application](../utilities.md#hatchling.bridge.app.Application). \"\"\" if self . __app is None : from hatchling.bridge.app import Application self . __app = Application () . get_safe_application () return self . __app @property def context ( self ): if self . __context is None : self . __context = self . get_context () return self . __context @property def verbosity ( self ): return self . __verbosity @property def root ( self ): \"\"\" The root of the project tree as a path-like object. \"\"\" return self . __root @property def metadata ( self ): return self . __metadata @property def name ( self ) -> str : \"\"\" The name of the environment. \"\"\" return self . __name @property def platform ( self ): \"\"\" An instance of [Platform](../utilities.md#hatch.utils.platform.Platform). \"\"\" return self . __platform @property def data_directory ( self ): \"\"\" The [directory](../../config/hatch.md#environments) reserved exclusively for this plugin as a path-like object. \"\"\" return self . __data_directory @property def config ( self ) -> dict : \"\"\" === \":octicons-file-code-16: pyproject.toml\" ```toml [tool.hatch.envs.] ``` === \":octicons-file-code-16: hatch.toml\" ```toml [envs.] ``` \"\"\" return self . __config @property def system_python ( self ): if self . _system_python is None : system_python = os . environ . get ( AppEnvVars . PYTHON ) if system_python == 'self' : system_python = sys . executable system_python = ( system_python or self . platform . modules . shutil . which ( 'python' ) or self . platform . modules . shutil . which ( 'python3' ) or sys . executable ) if not isabs ( system_python ): system_python = self . platform . modules . shutil . which ( system_python ) self . _system_python = system_python return self . _system_python @property def env_vars ( self ) -> dict : \"\"\" === \":octicons-file-code-16: pyproject.toml\" ```toml [tool.hatch.envs..env-vars] ``` === \":octicons-file-code-16: hatch.toml\" ```toml [envs..env-vars] ``` \"\"\" if self . _env_vars is None : env_vars = self . config . get ( 'env-vars' , {}) if not isinstance ( env_vars , dict ): raise TypeError ( f 'Field `tool.hatch.envs. { self . name } .env-vars` must be a mapping' ) for key , value in env_vars . items (): if not isinstance ( value , str ): raise TypeError ( f 'Environment variable ` { key } ` of field `tool.hatch.envs. { self . name } .env-vars` must be a string' ) new_env_vars = {} with self . metadata . context . apply_context ( self . context ): for key , value in env_vars . items (): new_env_vars [ key ] = self . metadata . context . format ( value ) new_env_vars [ AppEnvVars . ENV_ACTIVE ] = self . name self . _env_vars = new_env_vars return self . _env_vars @property def env_include ( self ) -> list [ str ]: \"\"\" === \":octicons-file-code-16: pyproject.toml\" ```toml [tool.hatch.envs.] env-include = [...] ``` === \":octicons-file-code-16: hatch.toml\" ```toml [envs.] env-include = [...] ``` \"\"\" if self . _env_include is None : env_include = self . config . get ( 'env-include' , []) if not isinstance ( env_include , list ): raise TypeError ( f 'Field `tool.hatch.envs. { self . name } .env-include` must be an array' ) for i , pattern in enumerate ( env_include , 1 ): if not isinstance ( pattern , str ): raise TypeError ( f 'Pattern # { i } of field `tool.hatch.envs. { self . name } .env-include` must be a string' ) if env_include : self . _env_include = [ 'HATCH_BUILD_*' , * env_include ] else : self . _env_include = env_include return self . _env_include @property def env_exclude ( self ) -> list [ str ]: \"\"\" === \":octicons-file-code-16: pyproject.toml\" ```toml [tool.hatch.envs.] env-exclude = [...] ``` === \":octicons-file-code-16: hatch.toml\" ```toml [envs.] env-exclude = [...] ``` \"\"\" if self . _env_exclude is None : env_exclude = self . config . get ( 'env-exclude' , []) if not isinstance ( env_exclude , list ): raise TypeError ( f 'Field `tool.hatch.envs. { self . name } .env-exclude` must be an array' ) for i , pattern in enumerate ( env_exclude , 1 ): if not isinstance ( pattern , str ): raise TypeError ( f 'Pattern # { i } of field `tool.hatch.envs. { self . name } .env-exclude` must be a string' ) self . _env_exclude = env_exclude return self . _env_exclude @property def environment_dependencies_complex ( self ): if self . _environment_dependencies_complex is None : from packaging.requirements import InvalidRequirement , Requirement dependencies_complex = [] with self . metadata . context . apply_context ( self . context ): for option in ( 'dependencies' , 'extra-dependencies' ): dependencies = self . config . get ( option , []) if not isinstance ( dependencies , list ): raise TypeError ( f 'Field `tool.hatch.envs. { self . name } . { option } ` must be an array' ) for i , entry in enumerate ( dependencies , 1 ): if not isinstance ( entry , str ): raise TypeError ( f 'Dependency # { i } of field `tool.hatch.envs. { self . name } . { option } ` must be a string' ) try : dependencies_complex . append ( Requirement ( self . metadata . context . format ( entry ))) except InvalidRequirement as e : raise ValueError ( f 'Dependency # { i } of field `tool.hatch.envs. { self . name } . { option } ` is invalid: { e } ' ) self . _environment_dependencies_complex = dependencies_complex return self . _environment_dependencies_complex @property def environment_dependencies ( self ) -> list [ str ]: \"\"\" The list of all [environment dependencies](../../config/environment/overview.md#dependencies). \"\"\" if self . _environment_dependencies is None : self . _environment_dependencies = [ str ( dependency ) for dependency in self . environment_dependencies_complex ] return self . _environment_dependencies @property def dependencies_complex ( self ): if self . _dependencies_complex is None : dependencies_complex = list ( self . environment_dependencies_complex ) # Ensure these are checked last to speed up initial environment creation since # they will already be installed along with the project if not self . skip_install and self . dev_mode : from hatchling.dep.core import dependencies_in_sync dynamic_fields = self . metadata . config . get ( 'project' , {}) . get ( 'dynamic' , []) if 'dependencies' not in dynamic_fields and 'optional-dependencies' not in dynamic_fields : dependencies_complex . extend ( self . metadata . core . dependencies_complex . values ()) for feature in self . features : dependencies_complex . extend ( self . metadata . core . optional_dependencies_complex [ feature ] . values ()) elif dependencies_in_sync ( self . metadata . build . requires_complex ): dependencies_complex . extend ( self . metadata . core . dependencies_complex . values ()) optional_dependencies = self . metadata . core . optional_dependencies_complex for feature in self . features : if feature not in optional_dependencies : raise ValueError ( f 'Feature ` { feature } ` of field `tool.hatch.envs. { self . name } .features` is not ' f 'defined in the dynamic field `project.optional-dependencies`' ) dependencies_complex . extend ( optional_dependencies [ feature ] . values ()) else : import json from packaging.requirements import Requirement with self . root . as_cwd (), self . build_environment ( self . metadata . build . requires ): command = [ 'python' , '-u' , '-m' , 'hatchling' , 'metadata' , '--app' , '--compact' ] process = self . platform . capture_process ( command ) project_metadata = json . loads ( self . app . read_builder ( process )) dependencies_complex . extend ( Requirement ( dependency ) for dependency in project_metadata . get ( 'dependencies' , []) ) optional_dependencies = project_metadata . get ( 'optional-dependencies' , {}) for feature in self . features : if feature not in optional_dependencies : raise ValueError ( f 'Feature ` { feature } ` of field `tool.hatch.envs. { self . name } .features` is not ' f 'defined in the dynamic field `project.optional-dependencies`' ) dependencies_complex . extend ( Requirement ( dependency ) for dependency in optional_dependencies [ feature ] . values () ) self . _dependencies_complex = dependencies_complex return self . _dependencies_complex @property def dependencies ( self ) -> list [ str ]: \"\"\" The list of all [project dependencies](../../config/metadata.md#dependencies) (if [installed](../../config/environment/overview.md#skip-install) and in [dev mode](../../config/environment/overview.md#dev-mode)) and [environment dependencies](../../config/environment/overview.md#dependencies). \"\"\" if self . _dependencies is None : self . _dependencies = [ str ( dependency ) for dependency in self . dependencies_complex ] return self . _dependencies @property def platforms ( self ) -> list [ str ]: \"\"\" All names are stored as their lower-cased version. === \":octicons-file-code-16: pyproject.toml\" ```toml [tool.hatch.envs.] platforms = [...] ``` === \":octicons-file-code-16: hatch.toml\" ```toml [envs.] platforms = [...] ``` \"\"\" if self . _platforms is None : platforms = self . config . get ( 'platforms' , []) if not isinstance ( platforms , list ): raise TypeError ( f 'Field `tool.hatch.envs. { self . name } .platforms` must be an array' ) for i , command in enumerate ( platforms , 1 ): if not isinstance ( command , str ): raise TypeError ( f 'Platform # { i } of field `tool.hatch.envs. { self . name } .platforms` must be a string' ) self . _platforms = [ platform . lower () for platform in platforms ] return self . _platforms @property def skip_install ( self ) -> bool : \"\"\" === \":octicons-file-code-16: pyproject.toml\" ```toml [tool.hatch.envs.] skip-install = ... ``` === \":octicons-file-code-16: hatch.toml\" ```toml [envs.] skip-install = ... ``` \"\"\" if self . _skip_install is None : skip_install = self . config . get ( 'skip-install' , not self . metadata . has_project_file ()) if not isinstance ( skip_install , bool ): raise TypeError ( f 'Field `tool.hatch.envs. { self . name } .skip-install` must be a boolean' ) self . _skip_install = skip_install return self . _skip_install @property def dev_mode ( self ) -> bool : \"\"\" === \":octicons-file-code-16: pyproject.toml\" ```toml [tool.hatch.envs.] dev-mode = ... ``` === \":octicons-file-code-16: hatch.toml\" ```toml [envs.] dev-mode = ... ``` \"\"\" if self . _dev_mode is None : dev_mode = self . config . get ( 'dev-mode' , True ) if not isinstance ( dev_mode , bool ): raise TypeError ( f 'Field `tool.hatch.envs. { self . name } .dev-mode` must be a boolean' ) self . _dev_mode = dev_mode return self . _dev_mode @property def features ( self ): if self . _features is None : from hatchling.metadata.utils import normalize_project_name features = self . config . get ( 'features' , []) if not isinstance ( features , list ): raise TypeError ( f 'Field `tool.hatch.envs. { self . name } .features` must be an array of strings' ) dynamic_features = 'optional-dependencies' in self . metadata . config . get ( 'project' , {}) . get ( 'dynamic' , []) all_features = set () for i , feature in enumerate ( features , 1 ): if not isinstance ( feature , str ): raise TypeError ( f 'Feature # { i } of field `tool.hatch.envs. { self . name } .features` must be a string' ) elif not feature : raise ValueError ( f 'Feature # { i } of field `tool.hatch.envs. { self . name } .features` cannot be an empty string' ) feature = normalize_project_name ( feature ) if not dynamic_features and feature not in self . metadata . core . optional_dependencies : raise ValueError ( f 'Feature ` { feature } ` of field `tool.hatch.envs. { self . name } .features` is not ' f 'defined in field `project.optional-dependencies`' ) all_features . add ( feature ) self . _features = sorted ( all_features ) return self . _features @property def description ( self ) -> str : \"\"\" === \":octicons-file-code-16: pyproject.toml\" ```toml [tool.hatch.envs.] description = ... ``` === \":octicons-file-code-16: hatch.toml\" ```toml [envs.] description = ... ``` \"\"\" if self . _description is None : description = self . config . get ( 'description' , '' ) if not isinstance ( description , str ): raise TypeError ( f 'Field `tool.hatch.envs. { self . name } .description` must be a string' ) self . _description = description return self . _description @property def scripts ( self ): if self . _scripts is None : script_config = self . config . get ( 'scripts' , {}) if not isinstance ( script_config , dict ): raise TypeError ( f 'Field `tool.hatch.envs. { self . name } .scripts` must be a table' ) config = {} for name , data in script_config . items (): if ' ' in name : raise ValueError ( f 'Script name ` { name } ` in field `tool.hatch.envs. { self . name } .scripts` must not contain spaces' ) commands = [] if isinstance ( data , str ): commands . append ( data ) elif isinstance ( data , list ): for i , command in enumerate ( data , 1 ): if not isinstance ( command , str ): raise TypeError ( f 'Command # { i } in field `tool.hatch.envs. { self . name } .scripts. { name } ` must be a string' ) commands . append ( command ) else : raise TypeError ( f 'Field `tool.hatch.envs. { self . name } .scripts. { name } ` must be a string or an array of strings' ) config [ name ] = commands seen = {} active = [] for script_name , commands in config . items (): commands [:] = expand_script_commands ( self . name , script_name , commands , config , seen , active ) self . _scripts = config return self . _scripts @property def pre_install_commands ( self ): if self . _pre_install_commands is None : pre_install_commands = self . config . get ( 'pre-install-commands' , []) if not isinstance ( pre_install_commands , list ): raise TypeError ( f 'Field `tool.hatch.envs. { self . name } .pre-install-commands` must be an array' ) for i , command in enumerate ( pre_install_commands , 1 ): if not isinstance ( command , str ): raise TypeError ( f 'Command # { i } of field `tool.hatch.envs. { self . name } .pre-install-commands` must be a string' ) self . _pre_install_commands = list ( pre_install_commands ) return self . _pre_install_commands @property def post_install_commands ( self ): if self . _post_install_commands is None : post_install_commands = self . config . get ( 'post-install-commands' , []) if not isinstance ( post_install_commands , list ): raise TypeError ( f 'Field `tool.hatch.envs. { self . name } .post-install-commands` must be an array' ) for i , command in enumerate ( post_install_commands , 1 ): if not isinstance ( command , str ): raise TypeError ( f 'Command # { i } of field `tool.hatch.envs. { self . name } .post-install-commands` must be a string' ) self . _post_install_commands = list ( post_install_commands ) return self . _post_install_commands def activate ( self ): \"\"\" A convenience method called when using the environment as a context manager: ```python with environment: ... ``` \"\"\" def deactivate ( self ): \"\"\" A convenience method called after using the environment as a context manager: ```python with environment: ... ``` \"\"\" @abstractmethod def find ( self ): \"\"\" :material-align-horizontal-left: **REQUIRED** :material-align-horizontal-right: This should return information about how to locate the environment. \"\"\" @abstractmethod def create ( self ): \"\"\" :material-align-horizontal-left: **REQUIRED** :material-align-horizontal-right: This should perform the necessary steps to set up the environment. \"\"\" @abstractmethod def remove ( self ): \"\"\" :material-align-horizontal-left: **REQUIRED** :material-align-horizontal-right: This should perform the necessary steps to completely remove the environment from the system and will only be triggered manually by users with the [`env remove`](../../cli/reference.md#hatch-env-remove) or [`env prune`](../../cli/reference.md#hatch-env-prune) commands. If the [build environment](reference.md#hatch.env.plugin.interface.EnvironmentInterface.build_environment) has a caching mechanism, this should remove that as well. \"\"\" @abstractmethod def exists ( self ) -> bool : \"\"\" :material-align-horizontal-left: **REQUIRED** :material-align-horizontal-right: This should indicate whether or not the environment has already been created. \"\"\" @abstractmethod def install_project ( self ): \"\"\" :material-align-horizontal-left: **REQUIRED** :material-align-horizontal-right: This should install the project in the environment. \"\"\" @abstractmethod def install_project_dev_mode ( self ): \"\"\" :material-align-horizontal-left: **REQUIRED** :material-align-horizontal-right: This should install the project in the environment such that the environment always reflects the current state of the project. \"\"\" @abstractmethod def dependencies_in_sync ( self ) -> bool : \"\"\" :material-align-horizontal-left: **REQUIRED** :material-align-horizontal-right: This should indicate whether or not the environment is compatible with the current [dependencies](reference.md#hatch.env.plugin.interface.EnvironmentInterface.dependencies). \"\"\" @abstractmethod def sync_dependencies ( self ): \"\"\" :material-align-horizontal-left: **REQUIRED** :material-align-horizontal-right: This should install the [dependencies](reference.md#hatch.env.plugin.interface.EnvironmentInterface.dependencies) in the environment. \"\"\" @contextmanager def build_environment ( self , dependencies : list [ str ]): \"\"\" This should set up an isolated environment in which to [`build`](../../cli/reference.md#hatch-build) the project given a set of dependencies and must be a context manager: ```python with environment.build_environment([...]): ... ``` The build environment should reflect any [environment variables](reference.md#hatch.env.plugin.interface.EnvironmentInterface.get_env_vars) the user defined either currently or at the time of [creation](reference.md#hatch.env.plugin.interface.EnvironmentInterface.create). \"\"\" with self . get_env_vars (): yield def get_build_process ( self , build_environment , ** kwargs ): \"\"\" This will be called when the [build environment](reference.md#hatch.env.plugin.interface.EnvironmentInterface.build_environment) is active: ```python with environment.build_environment([...]) as build_environment: build_process = environment.get_build_process(build_environment, ...) ``` This should return the standard library's [subprocess.Popen](https://docs.python.org/3/library/subprocess.html#subprocess.Popen) with all output captured by `stdout`. The command is constructed by passing all keyword arguments to [construct_build_command](reference.md#hatch.env.plugin.interface.EnvironmentInterface.construct_build_command). For an example, open the default implementation below: \"\"\" return self . platform . capture_process ( self . construct_build_command ( ** kwargs )) def build_environment_exists ( self ): \"\"\" If the [build environment](reference.md#hatch.env.plugin.interface.EnvironmentInterface.build_environment) has a caching mechanism, this should indicate whether or not it has already been created. \"\"\" return False def enter_shell ( self , name , path , args ): \"\"\" Spawn a [shell](../../config/hatch.md#shell) within the environment. This should either use [command_context](reference.md#hatch.env.plugin.interface.EnvironmentInterface.command_context) directly or provide the same guarantee. \"\"\" with self . command_context (): self . platform . exit_with_command ([ path , * args ]) def run_shell_command ( self , command : str , ** kwargs ): \"\"\" This should return the standard library's [subprocess.CompletedProcess](https://docs.python.org/3/library/subprocess.html#subprocess.CompletedProcess) and will always be called when the [command_context](reference.md#hatch.env.plugin.interface.EnvironmentInterface.command_context) is active, with the expectation of providing the same guarantee. \"\"\" kwargs . setdefault ( 'shell' , True ) return self . platform . run_command ( command , ** kwargs ) @contextmanager def command_context ( self ): \"\"\" A context manager that when active should make executed shell commands reflect any [environment variables](reference.md#hatch.env.plugin.interface.EnvironmentInterface.get_env_vars) the user defined either currently or at the time of [creation](reference.md#hatch.env.plugin.interface.EnvironmentInterface.create). For an example, open the default implementation below: \"\"\" with self . get_env_vars (): yield def resolve_commands ( self , commands : list [ str ]): \"\"\" This expands each command into one or more commands based on any [scripts](../../config/environment/overview.md#scripts) that the user defined. \"\"\" for command in commands : yield from self . expand_command ( command ) def expand_command ( self , command ): possible_script , args , ignore_exit_code = parse_script_command ( command ) # Indicate undefined if not args : args = None with self . metadata . context . apply_context ( self . context ): if possible_script in self . scripts : for cmd in self . scripts [ possible_script ]: yield self . metadata . context . format ( cmd , args = args ) . strip () else : yield self . metadata . context . format ( command , args = args ) . strip () def construct_build_command ( self , * , directory = None , targets = (), hooks_only = False , no_hooks = False , clean = False , clean_hooks_after = False , clean_only = False , ): \"\"\" This is the canonical way [`build`](../../cli/reference.md#hatch-build) command options are translated to a subprocess command issued to [builders](../builder/reference.md). \"\"\" command = [ 'python' , '-u' , '-m' , 'hatchling' , 'build' , '--app' ] if directory : command . extend (( '--directory' , directory )) if targets : for target in targets : command . extend (( '--target' , target )) if hooks_only : command . append ( '--hooks-only' ) if no_hooks : command . append ( '--no-hooks' ) if clean : command . append ( '--clean' ) if clean_hooks_after : command . append ( '--clean-hooks-after' ) if clean_only : command . append ( '--clean-only' ) return command def construct_pip_install_command ( self , args : list [ str ]): \"\"\" A convenience method for constructing a [`pip install`](https://pip.pypa.io/en/stable/cli/pip_install/) command with the given verbosity. The default verbosity is set to one less than Hatch's verbosity. \"\"\" command = [ 'python' , '-u' , '-m' , 'pip' , 'install' , '--disable-pip-version-check' , '--no-python-version-warning' ] # Default to -1 verbosity add_verbosity_flag ( command , self . verbosity , adjustment =- 1 ) command . extend ( args ) return command def join_command_args ( self , args : list [ str ]): \"\"\" This is used by the [`run`](../../cli/reference.md#hatch-run) command to construct the root command string from the received arguments. \"\"\" return self . platform . join_command_args ( args ) def apply_features ( self , requirement : str ): \"\"\" A convenience method that applies any user defined [features](../../config/environment/overview.md#features) to the given requirement. \"\"\" if self . features : features = ',' . join ( self . features ) return f ' { requirement } [ { features } ]' return requirement def check_compatibility ( self ): \"\"\" This raises an exception if the environment is not compatible with the user's setup. The default behavior checks for [platform compatibility](../../config/environment/overview.md#supported-platforms) and any method override should keep this check. \"\"\" if self . platforms and self . platform . name not in self . platforms : raise OSError ( 'unsupported platform' ) def get_env_vars ( self ) -> EnvVars : \"\"\" Returns a mapping of environment variables that should be available to the environment. The object can be used as a context manager to temporarily apply the environment variables to the current process. !!! note The environment variable `HATCH_ENV_ACTIVE` will always be set to the name of the environment. \"\"\" return EnvVars ( self . env_vars , self . env_include , self . env_exclude ) def get_env_var_option ( self , option : str ) -> str : \"\"\" Returns the value of the upper-cased environment variable `HATCH_ENV_TYPE__