From e722691ca0a9d23f8c70f37720cb80240feef5fb Mon Sep 17 00:00:00 2001 From: ofek Date: Mon, 25 Apr 2022 21:39:44 +0000 Subject: [PATCH] Update dependency.md https://github.com/pypa/packaging/issues/529 76af66979f72f73fafb198167a9f16db93e211b1 --- dev/config/dependency/index.html | 5 +++-- dev/search/search_index.json | 2 +- 2 files changed, 4 insertions(+), 3 deletions(-) diff --git a/dev/config/dependency/index.html b/dev/config/dependency/index.html index c73e30ca6..8890e125b 100644 --- a/dev/config/dependency/index.html +++ b/dev/config/dependency/index.html @@ -1,4 +1,4 @@ - Dependencies - Hatch
Skip to content

Dependency configuration

Project dependencies are defined with PEP 508 strings using optional PEP 440 version specifiers.

Version specifiers

A version specifier consists of a series of version clauses, separated by commas. For example:

[project]
+ Dependencies - Hatch       
 
  
  
 
  
 
 
 
 
  
 
 
 
 
 
  
 
 
 
 
 
Dependency configuration
 
 
Project dependencies are defined with PEP 508 strings using optional PEP 440 version specifiers.
 
Version specifiers
 
A version specifier consists of a series of version clauses, separated by commas. For example:
 
 
 
 
[project]
 ...
 dependencies = [
   "cryptography",
@@ -31,4 +31,5 @@
 
 
 
Remote
 
You can install source archives and wheels by simply referring to a URL:
 
https://github.com/psf/black/archive/refs/tags/21.10b0.zip
 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 #<HASH_ALGORITHM>=<EXPECTED_HASH> component:
 
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
    •  
 
 
  Last update: March 19, 2022  
 
 
 
 
  
 
 
 
    
\ No newline at end of file
+

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

The following is an example that uses features and environment markers:

pkg[feature1,feature2] @ <REFERENCE> ; python_version < "3.7"
+

Note that the space before the semicolon is required.

Last update: April 25, 2022
\ No newline at end of file diff --git a/dev/search/search_index.json b/dev/search/search_index.json index 370192485..4a37a898d 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 1.0.0rc17 - 2022-04-18 \u00b6 Changed: Rename environment collector API method get_environment_config to get_initial_config and do not make it required Added: Add the env run command as a more advanced form of the run command Add --json flag to the env show command Add features and scripts to the env show command Allow environment selection for the env show command Add environment collector API methods finalize_config and finalize_environments Add more conditions for environment option overrides Allow for environment option overrides of unknown/untyped options Add method to the environment interface for getting options from environment variables Allow selecting an explicit path for virtual environments Add detached option to environments Expose helper for lazily loading modules Normalize the names of environment features to adhere to the newly-introduced PEP 685 Bump the minimum supported version of Hatchling Upgrade tomlkit for better formatting 1.0.0rc16 - 2022-03-20 \u00b6 Added: Add ability to select specific environments for command execution of matrices based on variables Support a HATCH_PYTHON environment variable that, for example, environments may use before defaulting to the Python executable Hatch is running on Also use the SHELL environment variable fallback on Windows systems Update project URLs metadata 1.0.0rc15 - 2022-03-18 \u00b6 Added: Bump the minimum supported version of Hatchling 1.0.0rc14 - 2022-03-06 \u00b6 Added: When building with no targets defined in config, default to -t sdist -t wheel rather than raising an error Improve the output format of the env show command Add description option to environments Add extra-dependencies option to environments Upgrade actions/setup-python action of the CI option for new projects to v3 Bump the minimum supported version of Hatchling Update project metadata 1.0.0rc13 - 2022-02-13 \u00b6 Added: Update dependencies Fixed: Remove the forced use of embedded seed packages for virtual environments since distributions like Debian and Fedora do not use those 1.0.0rc12 - 2022-02-05 \u00b6 Added: Switch project to a src -layout structure Update dependencies 1.0.0rc11 - 2022-01-23 \u00b6 Changed: Change environment storage configuration to allow for exact paths per type of environment Add new required method find to the environment interface Added: Add more informative help text for the arguments of the run command 1.0.0rc10 - 2022-01-19 \u00b6 Fixed: Handle edge case for displaying text while showing a status message 1.0.0rc9 - 2022-01-18 \u00b6 Added: Add ability to set the non-preview variant of versions Improve collection of information about Python interpreters within environments Update dependencies Fixed: Relax restriction on the contents of build-system.requires The version command now properly handles statically defined versions Fix typo preventing the Python executable fallback for environments when there is no python along PATH 1.0.0rc8 - 2022-01-08 \u00b6 Added: Support Python 3.7 1.0.0rc7 - 2022-01-08 \u00b6 Added: Bump the minimum supported version of Hatchling 1rc6 - 2022-01-06 \u00b6 Added: Bump the minimum supported version of Hatchling 1rc5 - 2022-01-02 \u00b6 Fixed: Reduce default verbosity of config file creation for new users 1rc4 - 2022-01-01 \u00b6 Added: Bump the minimum supported version of Hatchling Fixed: Ensure Python subprocesses use unbuffered output to display real live progress Ensure that build environments honor environment variable filters 1rc3 - 2021-12-30 \u00b6 Added: Bump the minimum supported version of Hatchling 1rc2 - 2021-12-29 \u00b6 This is the first release candidate for Hatch v1, a complete rewrite. Hatchling \u00b6 Unreleased \u00b6 Added: Add option to force include files from arbitrary paths Add option to the wheel builder to ship files that will be installed globally Add option to the wheel builder to ship extra metadata files Support symlinks Update default core metadata version to 2.2 Upgrade editables dependency Fixed: Always include the root hatch.toml config file, if present, for source distributions 0.22.0 - 2022-03-26 \u00b6 Added: Change the default dev mode mechanism to pth files for better compatibility with static analysis tools & IDEs (see microsoft/pylance-release#2114 ) Fixed: Fix downstream test suite to avoid versions of setuptools with support for PEP 621 without PEP 639 0.21.1 - 2022-03-22 \u00b6 Fixed: Relax normalization of dependency definitions Update project URLs metadata 0.21.0 - 2022-03-17 \u00b6 Changed: In order to simplify configuration, metadata hooks are now configured under tool.hatch.metadata.hooks rather than directly under tool.hatch.metadata Added: Add option to allow the use of direct references for dependencies Make the default pattern for the regex version source case insensitive Deduplicate and normalize dependency definitions before writing metadata for wheels and source distributions Normalize the names of optional dependency groups to adhere to the newly-introduced PEP 685 0.20.1 - 2022-03-07 \u00b6 Fixed: Allow test execution from within Hatchling's source distribution 0.20.0 - 2022-03-07 \u00b6 Added: Relax dependency constraints 0.19.0 - 2022-03-06 \u00b6 Added: Add option for builds to declare dependence on a project's runtime dependencies Fixed: Disallow direct references for dependency definitions 0.18.0 - 2022-02-27 \u00b6 Added: Add ability to rewrite the distributed path of files 0.17.0 - 2022-02-26 \u00b6 Added: Always include any root .gitignore file for source distributions so recursive builds are guaranteed to be identical Fixed: Fix metadata handling of non-ASCII characters in README files for source distributions on Python 2 0.16.0 - 2022-02-26 \u00b6 Added: Always include the default build script location for source distributions Automatically remove fields from project.dynamic that were added by metadata hooks 0.15.0 - 2022-02-23 \u00b6 Added: Fail builds early for invalid project metadata When building with no targets defined in config, default to -t sdist -t wheel rather than raising an error Update project metadata 0.14.0 - 2022-02-16 \u00b6 Added: Add code version source that can load arbitrary Python code Fixed: Also exclude compiled Python extensions by default for cases where there is no .gitignore 0.13.0 - 2022-02-16 \u00b6 Added: Exclude Python byte code files by default for cases where there is no Git checkout and therefore no .gitignore file providing default exclusion patterns Fixed: Fix metadata handling of non-ASCII characters in README files on Python 2 0.12.0 - 2022-02-13 \u00b6 Added: Add option to exclude non-artifact files that do not reside within a Python package 0.11.3 - 2022-02-13 \u00b6 Fixed: Replace the build data zip_safe with pure_python 0.11.2 - 2022-02-05 \u00b6 Fixed: Fix custom hooks on Python 2 0.11.1 - 2022-02-05 \u00b6 Fixed: Change the default location of custom build scripts from build.py to hatch_build.py so the packaging tool build can be used (if desired) at the project root 0.11.0 - 2022-02-04 \u00b6 Added: Switch project to a src -layout structure Ship downstream tests with hatchling source distributions Fixed: Ship license with hatchling 0.10.0 - 2022-01-20 \u00b6 Added: Support text/plain content type for project.readme metadata 0.9.0 - 2022-01-18 \u00b6 Added: Build hooks now have access to project metadata Fixed: Improve check for satisfied dependencies 0.8.2 - 2022-01-16 \u00b6 Fixed: Fix plugins on Python 2 0.8.1 - 2022-01-14 \u00b6 Fixed: Update project metadata 0.8.0 - 2022-01-09 \u00b6 Added: The regex version source now supports the ^ / $ multi-line characters by default Fixed: Fix greedy matching in the default pattern for the regex version source 0.7.0 - 2022-01-08 \u00b6 Added: Improve default file selection to account for src -layout structures and namespaced packages Fixed: The normalization of project versions no longer strips trailing zero release segments 0.6 - 2022-01-06 \u00b6 Added: Add ability to conditionally execute build hooks Fixed: Disregard hook dependencies when building without hooks 0.5 - 2022-01-01 \u00b6 Added: Add option to clean build hook artifacts after each build Fixed: Properly include artifacts like C extensions that are built outside of package directories (with the intention of being placed directly inside site-packages ) for projects with a src -layout structure For wheels, the ordering of generated .dist-info files now matches the ordering of files included from the local file system 0.4 - 2021-12-30 \u00b6 Changed: In order to simplify configuration, build file selection options ( include , exclude , etc.) can no longer be defined as comma separated strings. Added: Refactor builder config handling into its own class Allow build hooks to access builder configuration 0.3.1 - 2021-12-30 \u00b6 Fixed: Ignore non-Python files for editable wheels 0.3 - 2021-12-29 \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":"","title":"Unreleased"},{"location":"history/#hatch-v1.0.0rc17","text":"Changed: Rename environment collector API method get_environment_config to get_initial_config and do not make it required Added: Add the env run command as a more advanced form of the run command Add --json flag to the env show command Add features and scripts to the env show command Allow environment selection for the env show command Add environment collector API methods finalize_config and finalize_environments Add more conditions for environment option overrides Allow for environment option overrides of unknown/untyped options Add method to the environment interface for getting options from environment variables Allow selecting an explicit path for virtual environments Add detached option to environments Expose helper for lazily loading modules Normalize the names of environment features to adhere to the newly-introduced PEP 685 Bump the minimum supported version of Hatchling Upgrade tomlkit for better formatting","title":"1.0.0rc17 - 2022-04-18"},{"location":"history/#hatch-v1.0.0rc16","text":"Added: Add ability to select specific environments for command execution of matrices based on variables Support a HATCH_PYTHON environment variable that, for example, environments may use before defaulting to the Python executable Hatch is running on Also use the SHELL environment variable fallback on Windows systems Update project URLs metadata","title":"1.0.0rc16 - 2022-03-20"},{"location":"history/#hatch-v1.0.0rc15","text":"Added: Bump the minimum supported version of Hatchling","title":"1.0.0rc15 - 2022-03-18"},{"location":"history/#hatch-v1.0.0rc14","text":"Added: When building with no targets defined in config, default to -t sdist -t wheel rather than raising an error Improve the output format of the env show command Add description option to environments Add extra-dependencies option to environments Upgrade actions/setup-python action of the CI option for new projects to v3 Bump the minimum supported version of Hatchling Update project metadata","title":"1.0.0rc14 - 2022-03-06"},{"location":"history/#hatch-v1.0.0rc13","text":"Added: Update dependencies Fixed: Remove the forced use of embedded seed packages for virtual environments since distributions like Debian and Fedora do not use those","title":"1.0.0rc13 - 2022-02-13"},{"location":"history/#hatch-v1.0.0rc12","text":"Added: Switch project to a src -layout structure Update dependencies","title":"1.0.0rc12 - 2022-02-05"},{"location":"history/#hatch-v1.0.0rc11","text":"Changed: Change environment storage configuration to allow for exact paths per type of environment Add new required method find to the environment interface Added: Add more informative help text for the arguments of the run command","title":"1.0.0rc11 - 2022-01-23"},{"location":"history/#hatch-v1.0.0rc10","text":"Fixed: Handle edge case for displaying text while showing a status message","title":"1.0.0rc10 - 2022-01-19"},{"location":"history/#hatch-v1.0.0rc9","text":"Added: Add ability to set the non-preview variant of versions Improve collection of information about Python interpreters within environments Update dependencies Fixed: Relax restriction on the contents of build-system.requires The version command now properly handles statically defined versions Fix typo preventing the Python executable fallback for environments when there is no python along PATH","title":"1.0.0rc9 - 2022-01-18"},{"location":"history/#hatch-v1.0.0rc8","text":"Added: Support Python 3.7","title":"1.0.0rc8 - 2022-01-08"},{"location":"history/#hatch-v1.0.0rc7","text":"Added: Bump the minimum supported version of Hatchling","title":"1.0.0rc7 - 2022-01-08"},{"location":"history/#hatch-v1rc6","text":"Added: Bump the minimum supported version of Hatchling","title":"1rc6 - 2022-01-06"},{"location":"history/#hatch-v1rc5","text":"Fixed: Reduce default verbosity of config file creation for new users","title":"1rc5 - 2022-01-02"},{"location":"history/#hatch-v1rc4","text":"Added: Bump the minimum supported version of Hatchling Fixed: Ensure Python subprocesses use unbuffered output to display real live progress Ensure that build environments honor environment variable filters","title":"1rc4 - 2022-01-01"},{"location":"history/#hatch-v1rc3","text":"Added: Bump the minimum supported version of Hatchling","title":"1rc3 - 2021-12-30"},{"location":"history/#hatch-v1rc2","text":"This is the first release candidate for Hatch v1, a complete rewrite.","title":"1rc2 - 2021-12-29"},{"location":"history/#hatchling","text":"","title":"Hatchling"},{"location":"history/#unreleased_1","text":"Added: Add option to force include files from arbitrary paths Add option to the wheel builder to ship files that will be installed globally Add option to the wheel builder to ship extra metadata files Support symlinks Update default core metadata version to 2.2 Upgrade editables dependency Fixed: Always include the root hatch.toml config file, if present, for source distributions","title":"Unreleased"},{"location":"history/#hatchling-v0.22.0","text":"Added: Change the default dev mode mechanism to pth files for better compatibility with static analysis tools & IDEs (see microsoft/pylance-release#2114 ) Fixed: Fix downstream test suite to avoid versions of setuptools with support for PEP 621 without PEP 639","title":"0.22.0 - 2022-03-26"},{"location":"history/#hatchling-v0.21.1","text":"Fixed: Relax normalization of dependency definitions Update project URLs metadata","title":"0.21.1 - 2022-03-22"},{"location":"history/#hatchling-v0.21.0","text":"Changed: In order to simplify configuration, metadata hooks are now configured under tool.hatch.metadata.hooks rather than directly under tool.hatch.metadata Added: Add option to allow the use of direct references for dependencies Make the default pattern for the regex version source case insensitive Deduplicate and normalize dependency definitions before writing metadata for wheels and source distributions Normalize the names of optional dependency groups to adhere to the newly-introduced PEP 685","title":"0.21.0 - 2022-03-17"},{"location":"history/#hatchling-v0.20.1","text":"Fixed: Allow test execution from within Hatchling's source distribution","title":"0.20.1 - 2022-03-07"},{"location":"history/#hatchling-v0.20.0","text":"Added: Relax dependency constraints","title":"0.20.0 - 2022-03-07"},{"location":"history/#hatchling-v0.19.0","text":"Added: Add option for builds to declare dependence on a project's runtime dependencies Fixed: Disallow direct references for dependency definitions","title":"0.19.0 - 2022-03-06"},{"location":"history/#hatchling-v0.18.0","text":"Added: Add ability to rewrite the distributed path of files","title":"0.18.0 - 2022-02-27"},{"location":"history/#hatchling-v0.17.0","text":"Added: Always include any root .gitignore file for source distributions so recursive builds are guaranteed to be identical Fixed: Fix metadata handling of non-ASCII characters in README files for source distributions on Python 2","title":"0.17.0 - 2022-02-26"},{"location":"history/#hatchling-v0.16.0","text":"Added: Always include the default build script location for source distributions Automatically remove fields from project.dynamic that were added by metadata hooks","title":"0.16.0 - 2022-02-26"},{"location":"history/#hatchling-v0.15.0","text":"Added: Fail builds early for invalid project metadata When building with no targets defined in config, default to -t sdist -t wheel rather than raising an error Update project metadata","title":"0.15.0 - 2022-02-23"},{"location":"history/#hatchling-v0.14.0","text":"Added: Add code version source that can load arbitrary Python code Fixed: Also exclude compiled Python extensions by default for cases where there is no .gitignore","title":"0.14.0 - 2022-02-16"},{"location":"history/#hatchling-v0.13.0","text":"Added: Exclude Python byte code files by default for cases where there is no Git checkout and therefore no .gitignore file providing default exclusion patterns Fixed: Fix metadata handling of non-ASCII characters in README files on Python 2","title":"0.13.0 - 2022-02-16"},{"location":"history/#hatchling-v0.12.0","text":"Added: Add option to exclude non-artifact files that do not reside within a Python package","title":"0.12.0 - 2022-02-13"},{"location":"history/#hatchling-v0.11.3","text":"Fixed: Replace the build data zip_safe with pure_python","title":"0.11.3 - 2022-02-13"},{"location":"history/#hatchling-v0.11.2","text":"Fixed: Fix custom hooks on Python 2","title":"0.11.2 - 2022-02-05"},{"location":"history/#hatchling-v0.11.1","text":"Fixed: Change the default location of custom build scripts from build.py to hatch_build.py so the packaging tool build can be used (if desired) at the project root","title":"0.11.1 - 2022-02-05"},{"location":"history/#hatchling-v0.11.0","text":"Added: Switch project to a src -layout structure Ship downstream tests with hatchling source distributions Fixed: Ship license with hatchling","title":"0.11.0 - 2022-02-04"},{"location":"history/#hatchling-v0.10.0","text":"Added: Support text/plain content type for project.readme metadata","title":"0.10.0 - 2022-01-20"},{"location":"history/#hatchling-v0.9.0","text":"Added: Build hooks now have access to project metadata Fixed: Improve check for satisfied dependencies","title":"0.9.0 - 2022-01-18"},{"location":"history/#hatchling-v0.8.2","text":"Fixed: Fix plugins on Python 2","title":"0.8.2 - 2022-01-16"},{"location":"history/#hatchling-v0.8.1","text":"Fixed: Update project metadata","title":"0.8.1 - 2022-01-14"},{"location":"history/#hatchling-v0.8.0","text":"Added: The regex version source now supports the ^ / $ multi-line characters by default Fixed: Fix greedy matching in the default pattern for the regex version source","title":"0.8.0 - 2022-01-09"},{"location":"history/#hatchling-v0.7.0","text":"Added: Improve default file selection to account for src -layout structures and namespaced packages Fixed: The normalization of project versions no longer strips trailing zero release segments","title":"0.7.0 - 2022-01-08"},{"location":"history/#hatchling-v0.6","text":"Added: Add ability to conditionally execute build hooks Fixed: Disregard hook dependencies when building without hooks","title":"0.6 - 2022-01-06"},{"location":"history/#hatchling-v0.5","text":"Added: Add option to clean build hook artifacts after each build Fixed: Properly include artifacts like C extensions that are built outside of package directories (with the intention of being placed directly inside site-packages ) for projects with a src -layout structure For wheels, the ordering of generated .dist-info files now matches the ordering of files included from the local file system","title":"0.5 - 2022-01-01"},{"location":"history/#hatchling-v0.4","text":"Changed: In order to simplify configuration, build file selection options ( include , exclude , etc.) can no longer be defined as comma separated strings. Added: Refactor builder config handling into its own class Allow build hooks to access builder configuration","title":"0.4 - 2021-12-30"},{"location":"history/#hatchling-v0.3.1","text":"Fixed: Ignore non-Python files for editable wheels","title":"0.3.1 - 2021-12-30"},{"location":"history/#hatchling-v0.3","text":"This is the initial public release of the Hatchling build system. Support for Python 2 will be dropped in version 1.","title":"0.3 - 2021-12-29"},{"location":"install/","text":"Installation \u00b6 pipx \u00b6 pipx allows for the global installation of Python applications in isolated environments. pipx install --pip-args \"--upgrade --pre\" hatch pip \u00b6 Hatch is available on PyPI and can be installed with pip . pip install --upgrade --pre --user hatch Warning This method modifies the Python environment in which you choose to install.","title":"Installation"},{"location":"install/#installation","text":"","title":"Installation"},{"location":"install/#pipx","text":"pipx allows for the global installation of Python applications in isolated environments. pipx install --pip-args \"--upgrade --pre\" hatch","title":"pipx"},{"location":"install/#pip","text":"Hatch is available on PyPI and can be installed with pip . pip install --upgrade --pre --user hatch Warning This method modifies the Python environment in which you choose to install.","title":"pip"},{"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 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 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 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":"Next steps"},{"location":"next-steps/#next-steps","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":"Next steps"},{"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 pypi . 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 (package index) with which to upload using the -r / --repo option or by setting the HATCH_PYPI_REPO environment variable. Rather than specifying the full URL of a repository, you can use a named repository from a publish.pypi.repos table defined in Hatch's config file : config.toml [publish.pypi.repos] repo1 = \"url1\" ... The following repository names are reserved by Hatch and cannot be overriden: 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_PYPI_USER ) and -a / --auth (environment variable HATCH_PYPI_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 releases, it is recommended that you use per-project API tokens .","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 pypi .","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 (package index) with which to upload using the -r / --repo option or by setting the HATCH_PYPI_REPO environment variable. Rather than specifying the full URL of a repository, you can use a named repository from a publish.pypi.repos table defined in Hatch's config file : config.toml [publish.pypi.repos] repo1 = \"url1\" ... The following repository names are reserved by Hatch and cannot be overriden: 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_PYPI_USER ) and -a / --auth (environment variable HATCH_PYPI_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 releases, it is recommended that you use per-project API tokens .","title":"Authentication"},{"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 --clean-only boolean N/A 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 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 --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 publish \u00b6 Publish build artifacts. Usage: hatch publish [OPTIONS] [ARTIFACTS]... Options: Name Type Description Default --user , -u text The user with which to authenticate [env var: HATCH_PYPI_USER ] None --auth , -a text The credentials to use for authentication [env var: HATCH_PYPI_AUTH ] None --repo , -r text The repository with which to publish artifacts [env var: HATCH_PYPI_REPO ] None --no-prompt , -n boolean Do not prompt for missing required fields False --publisher , -p text The publisher plugin to use (default is pypi ) [env var: HATCH_PUBLISHER ] pypi --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 --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] 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 --clean-only boolean N/A 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-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 --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-publish","text":"Publish build artifacts. Usage: hatch publish [OPTIONS] [ARTIFACTS]... Options: Name Type Description Default --user , -u text The user with which to authenticate [env var: HATCH_PYPI_USER ] None --auth , -a text The credentials to use for authentication [env var: HATCH_PYPI_AUTH ] None --repo , -r text The repository with which to publish artifacts [env var: HATCH_PYPI_REPO ] None --no-prompt , -n boolean Do not prompt for missing required fields False --publisher , -p text The publisher plugin to use (default is pypi ) [env var: HATCH_PUBLISHER ] pypi --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 --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] 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 system and is a dependency of Hatch itself. File selection \u00b6 VCS \u00b6 By default, Hatch will respect any .gitignore file located at your project's root. Set ignore-vcs to true to disable this behavior: pyproject.toml hatch.toml [tool.hatch.build] ignore-vcs = true [build] ignore-vcs = true 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 . Packages \u00b6 The packages option can be used to include specific Python packages. This option is semantically equivalent to include except that every entry is a simple relative path and 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\" ] 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 . pyproject.toml hatch.toml [tool.hatch.build] artifacts = [ \"*.so\" , \"*.dll\" , ] [build] artifacts = [ \"*.so\" , \"*.dll\" , ] Explicit selection \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.force-include] \"../artifacts\" = \"pkg\" \"~/lib.h\" = \"pkg/lib.h\" [build.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. Path rewriting has no effect on files included this way. 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] include = [ \"src/foo\" ] sources = [ \"src\" ] [build.targets.wheel] include = [ \"src/foo\" ] sources = [ \"src\" ] 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 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\" , ] 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 Order of execution \u00b6 For each build target, build hooks execute in the order in which they are defined, starting with target-specific hooks. As an example, for the following configuration: pyproject.toml hatch.toml [tool.hatch.build.hooks.hook3] [tool.hatch.build.hooks.hook1] [tool.hatch.build.targets.foo.hooks.hook2] [build.hooks.hook3] [build.hooks.hook1] [build.targets.foo.hooks.hook2] When target foo is built, build hook hook2 will be executed first, followed by hook3 , and then finally hook1 . 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 system 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 any .gitignore file located at your project's root. Set ignore-vcs to true to disable this behavior: pyproject.toml hatch.toml [tool.hatch.build] ignore-vcs = true [build] ignore-vcs = true","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/#packages","text":"The packages option can be used to include specific Python packages. This option is semantically equivalent to include except that every entry is a simple relative path and 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/#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 . pyproject.toml hatch.toml [tool.hatch.build] artifacts = [ \"*.so\" , \"*.dll\" , ] [build] artifacts = [ \"*.so\" , \"*.dll\" , ]","title":"Artifacts"},{"location":"config/build/#explicit-selection","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.force-include] \"../artifacts\" = \"pkg\" \"~/lib.h\" = \"pkg/lib.h\" [build.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. Path rewriting has no effect on files included this way. Warning Files included using this option will overwrite any file path that was already included by other file selection options.","title":"Explicit selection"},{"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] include = [ \"src/foo\" ] sources = [ \"src\" ] [build.targets.wheel] include = [ \"src/foo\" ] sources = [ \"src\" ]","title":"Rewriting paths"},{"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","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\" , ]","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","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 target-specific hooks. As an example, for the following configuration: pyproject.toml hatch.toml [tool.hatch.build.hooks.hook3] [tool.hatch.build.hooks.hook1] [tool.hatch.build.targets.foo.hooks.hook2] [build.hooks.hook3] [build.hooks.hook1] [build.targets.foo.hooks.hook2] When target foo is built, build hook hook2 will be executed first, followed by hook3 , and then finally hook1 .","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/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 not meant to be used for dependencies of a published project but rather are used for defining dependencies for an environment . 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 file:///path/to/pkg.tar.gz file:///c:/path/to/pkg.tar.gz Wheel file:///path/to/pkg.whl file:///c:/path/to/pkg.whl Directory file:///path/to/pkg file:///c:/path/to/pkg Tip When running commands that invoke pip directly, you may also specify paths relative to your project's root directory on all platforms by omitting the leading slashes and beginning the path with a dot: file:./pkg_inside_project file:../pkg_alongside_project Remote \u00b6 You can install source archives and wheels by simply referring to a URL: https://github.com/psf/black/archive/refs/tags/21.10b0.zip 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: 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":"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 not meant to be used for dependencies of a published project but rather are used for defining dependencies for an environment .","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 file:///path/to/pkg.tar.gz file:///c:/path/to/pkg.tar.gz Wheel file:///path/to/pkg.whl file:///c:/path/to/pkg.whl Directory file:///path/to/pkg file:///c:/path/to/pkg Tip When running commands that invoke pip directly, you may also specify paths relative to your project's root directory on all platforms by omitting the leading slashes and beginning the path with a dot: file:./pkg_inside_project file:../pkg_alongside_project","title":"Local"},{"location":"config/dependency/#remote","text":"You can install source archives and wheels by simply referring to a URL: https://github.com/psf/black/archive/refs/tags/21.10b0.zip 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: 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/environment/","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 . 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\" , ] 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\" 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. 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] skip-install = 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] skip-install = true dependencies = [ \"flake8\" , \"black\" , \"isort\" , ] [envs.style.scripts] check = [ \"flake8 .\" , \"black --check --diff .\" , \"isort --check-only --diff .\" , ] fmt = [ \"isort .\" , \"black .\" , \"check\" , ] Tip Scripts inherit from parent environments just like options. Commands \u00b6 All commands are able to use any defined scripts . 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 selects which version of Python to use: 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. 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 two 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\" ] 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 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":"Environments"},{"location":"config/environment/#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/#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/#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/#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/#dependencies","text":"You can install dependencies in addition to the ones defined by your project's metadata . 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\" , ]","title":"Dependencies"},{"location":"config/environment/#installation","text":"","title":"Installation"},{"location":"config/environment/#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/#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/#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/#environment-variables","text":"","title":"Environment variables"},{"location":"config/environment/#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\"","title":"Defined"},{"location":"config/environment/#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/#scripts","text":"You can define named scripts that may be executed or referenced at the beginning of other scripts. 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] skip-install = 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] skip-install = true dependencies = [ \"flake8\" , \"black\" , \"isort\" , ] [envs.style.scripts] check = [ \"flake8 .\" , \"black --check --diff .\" , \"isort --check-only --diff .\" , ] fmt = [ \"isort .\" , \"black .\" , \"check\" , ] Tip Scripts inherit from parent environments just like options.","title":"Scripts"},{"location":"config/environment/#commands","text":"All commands are able to use any defined scripts .","title":"Commands"},{"location":"config/environment/#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/#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/#python-version","text":"The python option selects which version of Python to use: 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/#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/#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/#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":"config/environment/#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/#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 two exceptions to this format are described below.","title":"Naming"},{"location":"config/environment/#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/#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/#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/#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/#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/#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/#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/#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/#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/#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","title":"Overwriting"},{"location":"config/environment/#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/#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/#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/#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/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\" 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 = \"powershell\" path = \"pwsh\" Supported \u00b6 Shell Name macOS Windows Unix Bash bash Command Prompt cmd C shell csh fish fish Nushell nu PowerShell powershell tcsh tcsh xonsh xonsh Z shell zsh Default \u00b6 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\"","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 = \"powershell\" path = \"pwsh\"","title":"Shell"},{"location":"config/hatch/#supported","text":"Shell Name macOS Windows Unix Bash bash Command Prompt cmd C shell csh fish fish Nushell nu PowerShell powershell tcsh tcsh xonsh xonsh Z shell zsh","title":"Supported"},{"location":"config/hatch/#default","text":"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. 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 pyproject.toml [project.scripts] cli-name = \"pkg.subpkg:func\" GUI \u00b6 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.","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":"pyproject.toml [project.scripts] cli-name = \"pkg.subpkg:func\"","title":"CLI"},{"location":"config/metadata/#gui","text":"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":"meta/authors/","text":"Authors \u00b6 Maintainers \u00b6 Ofek Lev Contributors \u00b6 Amjith Ramanujam 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 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. 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 Hatch \u00b6 These must be manually installed in the same environment as Hatch itself. Environment Environment collector Publisher Version scheme","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/#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","title":"Hatchling"},{"location":"plugins/about/#hatch","text":"These must be manually installed in the same environment as Hatch itself. Environment Environment collector Publisher Version scheme","title":"Hatch"},{"location":"plugins/build-hook/","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-mypyc - compiles code with Mypyc 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 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 paths to artifacts and should generally only be appended to force-include dict [ str , str ] This is a mapping of extra explicit paths Built-in \u00b6 Custom \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] An option path is used to specify the path of the Python file, defaulting to hatch_build.py . 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 . 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 ( object ): # 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 ....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 \u00b6 The name used for selection. app property readonly \u00b6 An instance of Application . build_config property readonly \u00b6 An instance of BuilderConfig . config property readonly \u00b6 The cumulative hook configuration. pyproject.toml hatch.toml [tool.hatch.build.hooks.] [tool.hatch.build.targets..hooks.] [build.hooks.] [build.targets..hooks.] directory property readonly \u00b6 The build directory. root property readonly \u00b6 The root of the project tree. target_name property readonly \u00b6 The plugin name of the build target. clean ( self , 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. \"\"\" finalize ( self , 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. \"\"\" initialize ( self , 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. \"\"\"","title":"Build hook"},{"location":"plugins/build-hook/#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/#known-third-party","text":"hatch-mypyc - compiles code with Mypyc","title":"Known third-party"},{"location":"plugins/build-hook/#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/#build-data","text":"Build data is a simple mapping whose contents can influence the behavior of builds. Which fields 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 paths to artifacts and should generally only be appended to force-include dict [ str , str ] This is a mapping of extra explicit paths","title":"Build data"},{"location":"plugins/build-hook/#built-in","text":"","title":"Built-in"},{"location":"plugins/build-hook/#custom","text":"This is a custom class in a given Python file that inherits from the BuildHookInterface .","title":"Custom"},{"location":"plugins/build-hook/#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] An option path is used to specify the path of the Python file, defaulting to hatch_build.py .","title":"Configuration"},{"location":"plugins/build-hook/#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/#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 ( object ): # 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 ....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/#hatchling.builders.hooks.plugin.interface.BuildHookInterface.PLUGIN_NAME","text":"The name used for selection.","title":"PLUGIN_NAME"},{"location":"plugins/build-hook/#hatchling.builders.hooks.plugin.interface.BuildHookInterface.app","text":"An instance of Application .","title":"app"},{"location":"plugins/build-hook/#hatchling.builders.hooks.plugin.interface.BuildHookInterface.build_config","text":"An instance of BuilderConfig .","title":"build_config"},{"location":"plugins/build-hook/#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.]","title":"config"},{"location":"plugins/build-hook/#hatchling.builders.hooks.plugin.interface.BuildHookInterface.directory","text":"The build directory.","title":"directory"},{"location":"plugins/build-hook/#hatchling.builders.hooks.plugin.interface.BuildHookInterface.root","text":"The root of the project tree.","title":"root"},{"location":"plugins/build-hook/#hatchling.builders.hooks.plugin.interface.BuildHookInterface.target_name","text":"The plugin name of the build target.","title":"target_name"},{"location":"plugins/build-hook/#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/#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/#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/builder/","text":"Builder plugins \u00b6 See the documentation for build configuration . Built-in \u00b6 Wheel \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.2\" The version of core metadata to use shared-data A mapping similar to the explicit selection 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 explicit selection option corresponding to extra metadata that will be shipped in a directory named extra_metadata Versions \u00b6 Version Description standard (default) The latest standardized format 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 //__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 Source distribution \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 support-legacy false Whether or not to include a setup.py file to support legacy installation mechanisms core-metadata-version \"2.2\" The version of core metadata to use 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. Reproducibility \u00b6 Reproducible builds are supported. Custom \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] An option path is used to specify the path of the Python file, defaulting to hatch_build.py . 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 . 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 ( object ): \"\"\" 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 , ): # Fail early for invalid project metadata self . metadata . core . 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 ( 'Unknown versions for target ` {} `: {} ' . format ( 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 ( 'Building ` {} ` version ` {} `' . format ( self . PLUGIN_NAME , version )) build_data = self . get_default_build_data () # Make sure reserved fields are set build_data . setdefault ( 'artifacts' , []) build_data . setdefault ( 'force-include' , {}) # Pass all the configured build hooks for future unforeseen scenarios needing ultimate control build_data [ 'configured_build_hooks' ] = 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 ( 'Only ran build hooks for ` {} ` version ` {} `' . format ( self . PLUGIN_NAME , 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 ): \"\"\" 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 \"\"\" for project_file in self . recurse_project_files (): yield project_file for explicit_file in self . recurse_explicit_files ( self . config . get_force_include ()): yield explicit_file def recurse_project_files ( self ): for root , dirs , files in safe_walk ( self . root ): relative_path = os . path . relpath ( root , self . root ) # First iteration if relative_path == '.' : relative_path = '' dirs [:] = sorted ( d for d in dirs # The trailing slash is necessary so e.g. `bar/` matches `foo/bar` if not self . config . path_is_excluded ( ' {} /' . format ( os . path . join ( relative_path , d ))) ) files = sorted ( files ) 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_explicit_files ( self , inclusion_map ): 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 ), target_path ) elif os . path . isdir ( source ): for root , dirs , files in safe_walk ( source ): relative_path = os . path . relpath ( root , source ) # First iteration if relative_path == '.' : relative_path = '' dirs . sort () files . sort () for f in files : relative_file_path = os . path . join ( relative_path , f ) yield IncludedFile ( os . path . join ( root , f ), '' if external else os . path . relpath ( relative_file_path , self . root ), os . path . join ( target_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 ...plugin.manager import PluginManager self . __plugin_manager = PluginManager () return self . __plugin_manager @property def metadata ( self ): if self . __metadata is None : from ...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 ...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 ( 'Field `tool.hatch.build.targets. {} ` must be a table' . format ( self . PLUGIN_NAME )) self . __target_config = target_config return self . __target_config @property def project_id ( self ): if self . __project_id is None : self . __project_id = ' {} - {} ' . format ( # https://discuss.python.org/t/clarify-naming-of-dist-info-directories/5565 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 = OrderedDict () 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 : raise ValueError ( 'Unknown build hook: {} ' . format ( 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 def get_version_api ( self ): \"\"\" :material-align-horizontal-left: **REQUIRED** :material-align-horizontal-right: 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. \"\"\" raise NotImplementedError 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.md) to influence the behavior of builds. \"\"\" return {} 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 \u00b6 The name used for selection. app property readonly \u00b6 An instance of Application . build_config property readonly \u00b6 pyproject.toml hatch.toml [tool.hatch.build] [build] config property readonly \u00b6 An instance of BuilderConfig . root property readonly \u00b6 The root of the project tree. target_config property readonly \u00b6 pyproject.toml hatch.toml [tool.hatch.build.targets.] [build.targets.] clean ( self , 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. \"\"\" 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_default_build_data ( self ) \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.md) to influence the behavior of builds. \"\"\" return {} get_default_versions ( self ) \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 ()) get_version_api ( self ) \u00b6 REQUIRED 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 def get_version_api ( self ): \"\"\" :material-align-horizontal-left: **REQUIRED** :material-align-horizontal-right: 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. \"\"\" raise NotImplementedError recurse_included_files ( self ) \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 ): \"\"\" 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 \"\"\" for project_file in self . recurse_project_files (): yield project_file for explicit_file in self . recurse_explicit_files ( self . config . get_force_include ()): yield explicit_file","title":"Builder"},{"location":"plugins/builder/#builder-plugins","text":"See the documentation for build configuration .","title":"Builder plugins"},{"location":"plugins/builder/#built-in","text":"","title":"Built-in"},{"location":"plugins/builder/#wheel","text":"A wheel is a binary distribution of a Python package that can be installed directly into an environment.","title":"Wheel"},{"location":"plugins/builder/#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/#options","text":"Option Default Description core-metadata-version \"2.2\" The version of core metadata to use shared-data A mapping similar to the explicit selection 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 explicit selection option corresponding to extra metadata that will be shipped in a directory named extra_metadata","title":"Options"},{"location":"plugins/builder/#versions","text":"Version Description standard (default) The latest standardized format","title":"Versions"},{"location":"plugins/builder/#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 //__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/#reproducibility","text":"Reproducible builds are supported.","title":"Reproducibility"},{"location":"plugins/builder/#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","title":"Build data"},{"location":"plugins/builder/#source-distribution","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"},{"location":"plugins/builder/#configuration_1","text":"The builder plugin name is sdist . pyproject.toml hatch.toml [tool.hatch.build.targets.sdist] [build.targets.sdist]","title":"Configuration"},{"location":"plugins/builder/#options_1","text":"Option Default Description support-legacy false Whether or not to include a setup.py file to support legacy installation mechanisms core-metadata-version \"2.2\" The version of core metadata to use","title":"Options"},{"location":"plugins/builder/#versions_1","text":"Version Description standard (default) The latest conventional format","title":"Versions"},{"location":"plugins/builder/#default-file-selection_1","text":"When the user has not set any file selection options, all files that are not ignored by your VCS will be included.","title":"Default file selection"},{"location":"plugins/builder/#reproducibility_1","text":"Reproducible builds are supported.","title":"Reproducibility"},{"location":"plugins/builder/#custom","text":"This is a custom class in a given Python file that inherits from the BuilderInterface .","title":"Custom"},{"location":"plugins/builder/#configuration_2","text":"The builder plugin name is custom . pyproject.toml hatch.toml [tool.hatch.build.targets.custom] [build.targets.custom] An option path is used to specify the path of the Python file, defaulting to hatch_build.py .","title":"Configuration"},{"location":"plugins/builder/#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/#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 ( object ): \"\"\" 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 , ): # Fail early for invalid project metadata self . metadata . core . 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 ( 'Unknown versions for target ` {} `: {} ' . format ( 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 ( 'Building ` {} ` version ` {} `' . format ( self . PLUGIN_NAME , version )) build_data = self . get_default_build_data () # Make sure reserved fields are set build_data . setdefault ( 'artifacts' , []) build_data . setdefault ( 'force-include' , {}) # Pass all the configured build hooks for future unforeseen scenarios needing ultimate control build_data [ 'configured_build_hooks' ] = 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 ( 'Only ran build hooks for ` {} ` version ` {} `' . format ( self . PLUGIN_NAME , 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 ): \"\"\" 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 \"\"\" for project_file in self . recurse_project_files (): yield project_file for explicit_file in self . recurse_explicit_files ( self . config . get_force_include ()): yield explicit_file def recurse_project_files ( self ): for root , dirs , files in safe_walk ( self . root ): relative_path = os . path . relpath ( root , self . root ) # First iteration if relative_path == '.' : relative_path = '' dirs [:] = sorted ( d for d in dirs # The trailing slash is necessary so e.g. `bar/` matches `foo/bar` if not self . config . path_is_excluded ( ' {} /' . format ( os . path . join ( relative_path , d ))) ) files = sorted ( files ) 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_explicit_files ( self , inclusion_map ): 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 ), target_path ) elif os . path . isdir ( source ): for root , dirs , files in safe_walk ( source ): relative_path = os . path . relpath ( root , source ) # First iteration if relative_path == '.' : relative_path = '' dirs . sort () files . sort () for f in files : relative_file_path = os . path . join ( relative_path , f ) yield IncludedFile ( os . path . join ( root , f ), '' if external else os . path . relpath ( relative_file_path , self . root ), os . path . join ( target_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 ...plugin.manager import PluginManager self . __plugin_manager = PluginManager () return self . __plugin_manager @property def metadata ( self ): if self . __metadata is None : from ...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 ...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 ( 'Field `tool.hatch.build.targets. {} ` must be a table' . format ( self . PLUGIN_NAME )) self . __target_config = target_config return self . __target_config @property def project_id ( self ): if self . __project_id is None : self . __project_id = ' {} - {} ' . format ( # https://discuss.python.org/t/clarify-naming-of-dist-info-directories/5565 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 = OrderedDict () 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 : raise ValueError ( 'Unknown build hook: {} ' . format ( 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 def get_version_api ( self ): \"\"\" :material-align-horizontal-left: **REQUIRED** :material-align-horizontal-right: 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. \"\"\" raise NotImplementedError 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.md) to influence the behavior of builds. \"\"\" return {} 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/#hatchling.builders.plugin.interface.BuilderInterface.PLUGIN_NAME","text":"The name used for selection.","title":"PLUGIN_NAME"},{"location":"plugins/builder/#hatchling.builders.plugin.interface.BuilderInterface.app","text":"An instance of Application .","title":"app"},{"location":"plugins/builder/#hatchling.builders.plugin.interface.BuilderInterface.build_config","text":"pyproject.toml hatch.toml [tool.hatch.build] [build]","title":"build_config"},{"location":"plugins/builder/#hatchling.builders.plugin.interface.BuilderInterface.config","text":"An instance of BuilderConfig .","title":"config"},{"location":"plugins/builder/#hatchling.builders.plugin.interface.BuilderInterface.root","text":"The root of the project tree.","title":"root"},{"location":"plugins/builder/#hatchling.builders.plugin.interface.BuilderInterface.target_config","text":"pyproject.toml hatch.toml [tool.hatch.build.targets.] [build.targets.]","title":"target_config"},{"location":"plugins/builder/#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/#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/#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.md) to influence the behavior of builds. \"\"\" return {}","title":"get_default_build_data()"},{"location":"plugins/builder/#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/#hatchling.builders.plugin.interface.BuilderInterface.get_version_api","text":"REQUIRED 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 def get_version_api ( self ): \"\"\" :material-align-horizontal-left: **REQUIRED** :material-align-horizontal-right: 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. \"\"\" raise NotImplementedError","title":"get_version_api()"},{"location":"plugins/builder/#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 ): \"\"\" 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 \"\"\" for project_file in self . recurse_project_files (): yield project_file for explicit_file in self . recurse_explicit_files ( self . config . get_force_include ()): yield explicit_file","title":"recurse_included_files()"},{"location":"plugins/environment-collector/","text":"Environment collector \u00b6 Environment collectors allow for dynamically modifying environments or adding environments beyond those defined in config. Users can override default values provided by each environment. Built-in \u00b6 Default \u00b6 This adds the default environment with type set to virtual and will always be applied. Configuration \u00b6 The environment plugin name is default . pyproject.toml hatch.toml [tool.hatch.env.collectors.default] [env.collectors.default] EnvironmentCollectorInterface ( ABC ) \u00b6 Example usage: plugin.py hooks.py from hatch.env.collectors.plugin.interface import EnvironmentCollectorInterface class SpecialEnvironmentCollector ( EnvironmentCollectorInterface ): PLUGIN_NAME = 'special' ... from hatchling.plugin import hookimpl from .plugin import SpecialEnvironmentCollector @hookimpl def hatch_register_environment_collector (): return SpecialEnvironmentCollector Source code in hatch/env/collectors/plugin/interface.py class EnvironmentCollectorInterface ( ABC ): \"\"\" Example usage: === \":octicons-file-code-16: plugin.py\" ```python from hatch.env.collectors.plugin.interface import EnvironmentCollectorInterface class SpecialEnvironmentCollector(EnvironmentCollectorInterface): PLUGIN_NAME = 'special' ... ``` === \":octicons-file-code-16: hooks.py\" ```python from hatchling.plugin import hookimpl from .plugin import SpecialEnvironmentCollector @hookimpl def hatch_register_environment_collector(): return SpecialEnvironmentCollector ``` \"\"\" PLUGIN_NAME = '' \"\"\"The name used for selection.\"\"\" def __init__ ( self , root , config ): self . __root = root self . __config = config @property def root ( self ): \"\"\" The root of the project tree as a path-like object. \"\"\" return self . __root @property def config ( self ) -> dict : \"\"\" === \":octicons-file-code-16: pyproject.toml\" ```toml [tool.hatch.env.collectors.] ``` === \":octicons-file-code-16: hatch.toml\" ```toml [env.collectors.] ``` \"\"\" return self . __config def get_initial_config ( self ) -> dict [ str , dict ]: \"\"\" Returns configuration for environments keyed by the environment or matrix name. \"\"\" return {} def finalize_config ( self , config : dict [ str , dict ]): \"\"\" Finalizes configuration for environments keyed by the environment or matrix name. This will override any user-defined settings and any collectors that ran before this call. This is called before matrices are turned into concrete environments. \"\"\" def finalize_environments ( self , config : dict [ str , dict ]): \"\"\" Finalizes configuration for environments keyed by the environment name. This will override any user-defined settings and any collectors that ran before this call. This is called after matrices are turned into concrete environments. \"\"\" PLUGIN_NAME \u00b6 The name used for selection. config : dict property readonly \u00b6 pyproject.toml hatch.toml [tool.hatch.env.collectors.] [env.collectors.] root property readonly \u00b6 The root of the project tree as a path-like object. finalize_config ( self , config : dict [ str , dict ]) \u00b6 Finalizes configuration for environments keyed by the environment or matrix name. This will override any user-defined settings and any collectors that ran before this call. This is called before matrices are turned into concrete environments. Source code in hatch/env/collectors/plugin/interface.py def finalize_config ( self , config : dict [ str , dict ]): \"\"\" Finalizes configuration for environments keyed by the environment or matrix name. This will override any user-defined settings and any collectors that ran before this call. This is called before matrices are turned into concrete environments. \"\"\" finalize_environments ( self , config : dict [ str , dict ]) \u00b6 Finalizes configuration for environments keyed by the environment name. This will override any user-defined settings and any collectors that ran before this call. This is called after matrices are turned into concrete environments. Source code in hatch/env/collectors/plugin/interface.py def finalize_environments ( self , config : dict [ str , dict ]): \"\"\" Finalizes configuration for environments keyed by the environment name. This will override any user-defined settings and any collectors that ran before this call. This is called after matrices are turned into concrete environments. \"\"\" get_initial_config ( self ) -> dict [ str , dict ] \u00b6 Returns configuration for environments keyed by the environment or matrix name. Source code in hatch/env/collectors/plugin/interface.py def get_initial_config ( self ) -> dict [ str , dict ]: \"\"\" Returns configuration for environments keyed by the environment or matrix name. \"\"\" return {}","title":"Environment collector"},{"location":"plugins/environment-collector/#environment-collector","text":"Environment collectors allow for dynamically modifying environments or adding environments beyond those defined in config. Users can override default values provided by each environment.","title":"Environment collector"},{"location":"plugins/environment-collector/#built-in","text":"","title":"Built-in"},{"location":"plugins/environment-collector/#default","text":"This adds the default environment with type set to virtual and will always be applied.","title":"Default"},{"location":"plugins/environment-collector/#configuration","text":"The environment plugin name is default . pyproject.toml hatch.toml [tool.hatch.env.collectors.default] [env.collectors.default]","title":"Configuration"},{"location":"plugins/environment-collector/#hatch.env.collectors.plugin.interface.EnvironmentCollectorInterface","text":"Example usage: plugin.py hooks.py from hatch.env.collectors.plugin.interface import EnvironmentCollectorInterface class SpecialEnvironmentCollector ( EnvironmentCollectorInterface ): PLUGIN_NAME = 'special' ... from hatchling.plugin import hookimpl from .plugin import SpecialEnvironmentCollector @hookimpl def hatch_register_environment_collector (): return SpecialEnvironmentCollector Source code in hatch/env/collectors/plugin/interface.py class EnvironmentCollectorInterface ( ABC ): \"\"\" Example usage: === \":octicons-file-code-16: plugin.py\" ```python from hatch.env.collectors.plugin.interface import EnvironmentCollectorInterface class SpecialEnvironmentCollector(EnvironmentCollectorInterface): PLUGIN_NAME = 'special' ... ``` === \":octicons-file-code-16: hooks.py\" ```python from hatchling.plugin import hookimpl from .plugin import SpecialEnvironmentCollector @hookimpl def hatch_register_environment_collector(): return SpecialEnvironmentCollector ``` \"\"\" PLUGIN_NAME = '' \"\"\"The name used for selection.\"\"\" def __init__ ( self , root , config ): self . __root = root self . __config = config @property def root ( self ): \"\"\" The root of the project tree as a path-like object. \"\"\" return self . __root @property def config ( self ) -> dict : \"\"\" === \":octicons-file-code-16: pyproject.toml\" ```toml [tool.hatch.env.collectors.] ``` === \":octicons-file-code-16: hatch.toml\" ```toml [env.collectors.] ``` \"\"\" return self . __config def get_initial_config ( self ) -> dict [ str , dict ]: \"\"\" Returns configuration for environments keyed by the environment or matrix name. \"\"\" return {} def finalize_config ( self , config : dict [ str , dict ]): \"\"\" Finalizes configuration for environments keyed by the environment or matrix name. This will override any user-defined settings and any collectors that ran before this call. This is called before matrices are turned into concrete environments. \"\"\" def finalize_environments ( self , config : dict [ str , dict ]): \"\"\" Finalizes configuration for environments keyed by the environment name. This will override any user-defined settings and any collectors that ran before this call. This is called after matrices are turned into concrete environments. \"\"\"","title":"EnvironmentCollectorInterface"},{"location":"plugins/environment-collector/#hatch.env.collectors.plugin.interface.EnvironmentCollectorInterface.PLUGIN_NAME","text":"The name used for selection.","title":"PLUGIN_NAME"},{"location":"plugins/environment-collector/#hatch.env.collectors.plugin.interface.EnvironmentCollectorInterface.config","text":"pyproject.toml hatch.toml [tool.hatch.env.collectors.] [env.collectors.]","title":"config"},{"location":"plugins/environment-collector/#hatch.env.collectors.plugin.interface.EnvironmentCollectorInterface.root","text":"The root of the project tree as a path-like object.","title":"root"},{"location":"plugins/environment-collector/#hatch.env.collectors.plugin.interface.EnvironmentCollectorInterface.finalize_config","text":"Finalizes configuration for environments keyed by the environment or matrix name. This will override any user-defined settings and any collectors that ran before this call. This is called before matrices are turned into concrete environments. Source code in hatch/env/collectors/plugin/interface.py def finalize_config ( self , config : dict [ str , dict ]): \"\"\" Finalizes configuration for environments keyed by the environment or matrix name. This will override any user-defined settings and any collectors that ran before this call. This is called before matrices are turned into concrete environments. \"\"\"","title":"finalize_config()"},{"location":"plugins/environment-collector/#hatch.env.collectors.plugin.interface.EnvironmentCollectorInterface.finalize_environments","text":"Finalizes configuration for environments keyed by the environment name. This will override any user-defined settings and any collectors that ran before this call. This is called after matrices are turned into concrete environments. Source code in hatch/env/collectors/plugin/interface.py def finalize_environments ( self , config : dict [ str , dict ]): \"\"\" Finalizes configuration for environments keyed by the environment name. This will override any user-defined settings and any collectors that ran before this call. This is called after matrices are turned into concrete environments. \"\"\"","title":"finalize_environments()"},{"location":"plugins/environment-collector/#hatch.env.collectors.plugin.interface.EnvironmentCollectorInterface.get_initial_config","text":"Returns configuration for environments keyed by the environment or matrix name. Source code in hatch/env/collectors/plugin/interface.py def get_initial_config ( self ) -> dict [ str , dict ]: \"\"\" Returns configuration for environments keyed by the environment or matrix name. \"\"\" return {}","title":"get_initial_config()"},{"location":"plugins/environment/","text":"Environment plugins \u00b6 See the documentation for environment configuration . Known third-party \u00b6 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' ): for process in environment . run_shell_commands ( environment . pre_install_commands ): if process . returncode : self . abort ( f 'Failed with exit code: { process . returncode } ' , code = process . returncode ) 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' ): for process in environment . run_shell_commands ( environment . post_install_commands ): if process . returncode : self . abort ( f 'Failed with exit code: { process . returncode } ' , code = process . returncode ) if not environment . dependencies_in_sync (): with self . status_waiting ( 'Syncing dependencies' ): environment . sync_dependencies () Built-in \u00b6 Virtual \u00b6 This uses virtual environments backed by the standard virtualenv tool. Configuration \u00b6 The environment plugin name is virtual . pyproject.toml hatch.toml [tool.hatch.envs.] type = \"virtual\" [envs.] type = \"virtual\" Options \u00b6 Option Default Description system-packages false Whether or not to give the virtual environment access to the system site-packages directory python The version of Python to find on your system and subsequently use to create the environment, defaulting to the HATCH_PYTHON environment variable, followed by the Python executable Hatch is running on. For more information, see the documentation . env:HATCH_ENV_TYPE_VIRTUAL_PATH An explicit path to the virtual environment EnvironmentInterface ( ABC ) \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 , data_directory , platform , verbosity , app = None ): self . __root = root self . metadata = metadata self . __name = name self . __config = config self . __data_directory = data_directory self . __platform = platform self . verbosity = verbosity self . __app = app 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 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 as a path-like object. \"\"\" return self . __root @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 , 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' ) env_vars = env_vars . copy () env_vars [ AppEnvVars . ENV_ACTIVE ] = self . name self . _env_vars = 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 = [] 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 ( 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.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 : dependencies_complex . extend ( self . metadata . core . dependencies_complex . 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.md#skip-install) and in [dev mode](../config/environment.md#dev-mode)) and [environment dependencies](../config/environment.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' , False ) 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' ) 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 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. \"\"\" @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](environment.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](environment.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](environment.md#hatch.env.plugin.interface.EnvironmentInterface.get_env_vars) the user defined either currently or at the time of [creation](environment.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](environment.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](environment.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 enter_shell ( self , name , path ): \"\"\" Spawn a [shell](../config/hatch.md#shell) within the environment. The shell should reflect any [environment variables](environment.md#hatch.env.plugin.interface.EnvironmentInterface.get_env_vars) the user defined either currently or at the time of [creation](environment.md#hatch.env.plugin.interface.EnvironmentInterface.create). \"\"\" with self . get_env_vars (): self . platform . exit_with_command ([ path ]) def run_shell_commands ( self , commands : list [ str ]): \"\"\" This should yield the standard library's [subprocess.CompletedProcess](https://docs.python.org/3/library/subprocess.html#subprocess.CompletedProcess) for each command. Additionally, the commands must first be [resolved](environment.md#hatch.env.plugin.interface.EnvironmentInterface.resolve_commands). The command execution should reflect any [environment variables](environment.md#hatch.env.plugin.interface.EnvironmentInterface.get_env_vars) the user defined either currently or at the time of [creation](environment.md#hatch.env.plugin.interface.EnvironmentInterface.create). For an example, open the default implementation below: \"\"\" with self . get_env_vars (): for command in self . resolve_commands ( commands ): yield self . platform . run_command ( command , shell = True ) def resolve_commands ( self , commands : list [ str ]): \"\"\" This expands each command into one or more commands based on any [scripts](../config/environment.md#scripts) that the user defined. Each expanded command is then [finalized](environment.md#hatch.env.plugin.interface.EnvironmentInterface.finalize_command). \"\"\" for command in commands : expanded_commands = self . expand_command ( command ) for expanded_command in expanded_commands : yield self . finalize_command ( expanded_command ) def finalize_command ( self , command : str ): \"\"\" Called for every [resolved command](environment.md#hatch.env.plugin.interface.EnvironmentInterface.resolve_commands) with the default behavior being equivalent to the standard library's [os.path.expandvars](https://docs.python.org/3/library/os.path.html#os.path.expandvars). \"\"\" return expandvars ( command ) def expand_command ( self , command ): possible_script , _ , remaining = command . partition ( ' ' ) if possible_script in self . scripts : if remaining : for cmd in self . scripts [ possible_script ]: yield f ' { cmd } { remaining } ' else : yield from self . scripts [ possible_script ] else : yield command 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.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 ], verbosity = None ): \"\"\" 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. \"\"\" if verbosity is None : # Default to -1 verbosity verbosity = self . verbosity - 1 command = [ 'python' , '-u' , '-m' , 'pip' , 'install' , '--disable-pip-version-check' , '--no-python-version-warning' ] if verbosity < 0 : command . append ( f \"- { 'q' * abs ( verbosity ) } \" ) elif verbosity > 0 : command . append ( f \"- { 'v' * abs ( verbosity ) } \" ) 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.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.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 ) @staticmethod def get_option_types () -> dict : \"\"\" Returns a mapping of supported options to their respective types so that they can be used by [overrides](../config/environment.md#option-overrides). \"\"\" return {} def get_env_var_option ( self , option : str ) -> str : \"\"\" Returns the value of the upper-cased environment variable `HATCH_ENV_TYPE__