pyproject-fmt

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

Philosophy

This tool aims to be an opinionated formatter, with similar objectives to black. This means it deliberately does not support a wide variety of configuration settings. In return, you get consistency, predictability, and smaller diffs.

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 = 120

# 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, use '-' to read from stdin (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, implied if reading from stdin

  • --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: 120)

  • --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.