Configuration¶
RunCommands can be configured using TOML. The following config files can be used (in order of precedence):
- ./runcommands.toml
- ./commands.toml
- ./pyproject.toml
For the first two of these, the option keys (see below) should be specified like so:
[globals]
x = 1
[envs]
test = {}
prod = {}
When using pyproject.toml
, the option keys (see below) need to be prefixed
with tool.runcommands
like so:
[tool.runcommands.globals]
x = 1
[tool.runcommands.envs]
test = {}
prod = {}
The options that can be specified are:
globals
-> A dictionary containing global variables that are also used as default args for all commands.envs
-> A dictionary containing env-specific global variables and/or default args.When an env is specified, the corresponding env-specific variables will be merged into
globals
and the entireenvs
dict will be added toglobals
.In addition, if an env specifies
args
, these will be used as default args when the env is selected. These default args have higher precedence than default args specified via the top levelargs
option (see below).The selected env’s
args
will not be added toglobals
.args
-> A dictionary containing default arg values for specific commands. Note that if an env is specified, the env’s default args, if any, will take precedence overargs
(see above).environ
-> Environment variables.
globals
and environ
correspond to the globals
and environ
options of the runcommands.run.run()
command.
Order of Precedence¶
Lowest to highest:
- Keyword args
- Global args from config file
- Global args passed via
run
command - Env-specific global args from config file
- Env-specific default args from config file
- Default args from config file
- Default args read from environment variables
- Command line args
- Direct call args
Interpolation¶
String values may contain interpolation groups using dotted notation to refer to other configuration values like so:
[globals]
x = "{{ y }}"
y = 1
z = "z {{ y }} z"
When a value contains a single interpolation group and nothing else, it will
be replaced with the exact value that it refers to, so in the example above,
x
will be equal to the integer 1
and z
will be equal to the string
"z 1 z"
.
Globals are injected into other global args, default args, and environment variables (after env-specific args are merged in).
Default args are injected into other default args.