pyproject-fmt

Apply a consistent format to your pyproject.toml file with comment support. See changelog here.

Use

Via CLI

Use pipx to install the project:

pipx install pyproject-fmt

Via pre-commit hook

See pre-commit/pre-commit for instructions, sample .pre-commit-config.yaml:

- repo: https://github.com/tox-dev/pyproject-fmt
  rev: "2.0.4"
  hooks:
    - id: pyproject-fmt

Via Python

Package root.

pyproject_fmt.run(args=None)

Run the formatter.

Parameters:

args (Optional[Sequence[str]]) – command line arguments, by default use sys.argv[1:]

Return type:

int

Returns:

exit code - 0 means already formatted correctly, otherwise 1

Configuration via file

The tool.pyproject-fmt table is used when present in the pyproject.toml file:

[tool.pyproject-fmt]

# after how many column width split arrays/dicts into multiple lines, 1 will force always
column_width = 1

# how many spaces use for indentation
indent = 2

# if false will remove unnecessary trailing ``.0``'s from version specifiers
keep_full_version = false

# maximum Python version to use when generating version specifiers
max_supported_python = "3.12"

If not set they will default to values from the CLI, the example above shows the defaults.

Command line interface

pyproject-fmt [-h] [-V] [-s | --check] [-n] [--column-width count] [--indent count]
              [--keep-full-version] [--max-supported-python minor.major]
              inputs [inputs ...]

pyproject-fmt positional arguments

  • inputs - pyproject.toml file(s) to format (default: None)

pyproject-fmt options

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

  • -V, --version - print package version of pyproject_fmt

pyproject-fmt run mode

  • -s, --stdout - print the formatted TOML to the stdout

  • --check - check and fail if any input would be formatted, printing any diffs

  • -n, --no-print-diff - Flag indicating to print diff for the check mode

pyproject-fmt formatting behavior

  • --column-width COUNT - max column width in the TOML file (default: 1)

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

  • --keep-full-version - keep full dependency versions - do not remove redundant .0 from versions

  • --max-supported-python MINOR.MAJOR - latest Python version the project supports (e.g. 3.13) (default: (3, 12))

Python version classifiers

This tool will automatically generate the Programming Language :: Python :: 3.X classifiers for you. To do so it needs to know the range of Python interpreter versions you support:

  • The lower bound can be set via the requires-python key in the pyproject.toml configuration file (defaults to the oldest non end of line CPython version at the time of the release).

  • The upper bound, by default, will assume the latest stable release of CPython at the time of the release, but can be changed via CLI flag or the config file.