Configuration

Project settings

Put per-file settings in [tox-toml-fmt]:

[tox-toml-fmt]
column_width = 120
indent = 2
table_format = "short"
sub_table_spacing = ""
separate_root_table = "\n"
expand_tables = []
collapse_tables = []
skip_wrap_for_keys = []
pin_envs = []

These values match the command defaults. column_width controls array expansion and string wrapping. A trailing comma keeps an array multiline regardless of its width. indent controls continuation indentation.

table_format controls child tables below an environment. Environment tables retain their [env.NAME] headers. expand_tables and collapse_tables override the default by table path, and collapse_tables wins a tie.

pin_envs writes named environments before the version-based order used for the rest of env_list and [env.NAME] tables.

Shared settings

A standalone tox-toml-fmt.toml can hold settings for several projects. The file uses the same keys without the [tox-toml-fmt] header:

column_width = 120
indent = 2
table_format = "short"
pin_envs = ["fix", "type"]

For each input, the formatter searches from the input’s directory toward the filesystem root and uses the nearest tox-toml-fmt.toml. --config selects a file directly:

tox-toml-fmt --config /path/to/tox-toml-fmt.toml tox.toml

Command-line values establish defaults, the shared file overrides them, and [tox-toml-fmt] has final precedence. The formatter validates file settings with the command-line converters. An unknown key or invalid value stops formatting and reports its source.

Spacing

sub_table_spacing inserts text between child tables in one group. separate_root_table inserts text between root groups. Each \n adds one blank line.

String wrapping

skip_wrap_for_keys excludes matching keys from line-continuation wrapping:

[tox-toml-fmt]
skip_wrap_for_keys = ["*.commands", "env.*.description"]

* matches one dotted key segment. A quoted "*" segment names a literal asterisk.

Command-line interface

tox-toml-fmt [-h] [-V] [-s | --check] [-n] [--config path] [--column-width count]
             [--indent count] [--table-format {short,long}]
             [--sub-table-spacing SUB_TABLE_SPACING]
             [--separate-root-table SEPARATE_ROOT_TABLE] [--expand-tables EXPAND_TABLES]
             [--collapse-tables COLLAPSE_TABLES] [--skip-wrap-for-keys SKIP_WRAP_FOR_KEYS]
             [--pin-env PIN_ENVS]
             inputs [inputs ...]

tox-toml-fmt positional arguments

• inputs - tox.toml file(s) to format, use '-' to read from stdin

tox-toml-fmt options

• -h, --help - show this help message and exit

• -V, --version - print package version of tox-toml-fmt

• --config path - path to a shared tox-toml-fmt.toml config file

tox-toml-fmt run mode

• -s, --stdout - write formatted TOML to stdout; implied for stdin

• --check - fail when an input needs formatting and print its diff

• -n, --no-print-diff - suppress diffs in check mode

tox-toml-fmt formatting behavior

• --column-width count - max column width in the TOML file (default: 120)

• --indent count - number of spaces to use for indentation (default: 2)

• --table-format {short,long} - table format: 'short' collapses sub-tables, 'long' expands to [table.subtable] (default: short)

• --sub-table-spacing SUB_TABLE_SPACING - extra newlines between sub-tables in the same group (e.g. '\n' for one blank line, empty for compact) (default: )

• --separate-root-table SEPARATE_ROOT_TABLE - extra newlines between root table groups (e.g. '\n' for one blank line, '\n\n' for two) (default: )

• --expand-tables EXPAND_TABLES - comma-separated list of tables to force expand (default: [])

• --collapse-tables COLLAPSE_TABLES - comma-separated list of tables to force collapse (default: [])

• --skip-wrap-for-keys SKIP_WRAP_FOR_KEYS - comma-separated list of key patterns to skip string wrapping (supports wildcards like '*.parse') (default: [])

• --pin-env PIN_ENVS - environments whose tables are written first (comma separated) (default: [])