Skip to content

Context formatting


You can populate configuration with the values of certain supported fields using the syntax of Python's format strings. Each field interprets the modifier part after the colon differently, if at all.

Global fields

Any configuration that declares support for context formatting will always support these fields.

Paths

Field Description
root The root project directory
home The user's home directory

All paths support the following modifiers:

Modifier Description
uri The normalized absolute URI path prefixed by file:
real The path with all symbolic links resolved
parent The parent of the preceding path

Tip

The parent modifier can be chained and may be combined with either the uri or real modifier, with the latter placed at the end. For example:

[tool.hatch.envs.test]
dependencies = [
    "example-project @ {root:parent:parent:uri}/example-project",
]
[envs.test]
dependencies = [
    "example-project @ {root:parent:parent:uri}/example-project",
]

System separators

Field Description
/ \ on Windows, / otherwise
; ; on Windows, : otherwise

Environment variables

The env field and its modifier allow you to select the value of an environment variable. If the environment variable is not set, you must specify a default value as an additional modifier e.g. {env:PATH:DEFAULT}.

Field nesting

You can insert fields within others. For example, if you wanted a script that displays the value of the environment variable FOO, with a fallback to the environment variable BAR, with its own fallback to the user's home directory, you could do the following:

[tool.hatch.envs.test.scripts]
display = "echo {env:FOO:{env:BAR:{home}}}"
[envs.test.scripts]
display = "echo {env:FOO:{env:BAR:{home}}}"