pyproject-fmt#

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

Use#

As a CLI tool#

Use pipx to install the project:

pipx install pyproject-fmt

As a pre-commit hook#

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

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

Calculating max supported Python version#

This tool will automatically generate the Programming Language :: Python :: 3.X classifiers for you. To do so it needs to know what is the range of Python interpreter versions you support. The lower bound can be deduced by looking at the requires-python key in the pyproject.toml configuration file. For the upper bound by default will assume the latest stable release when the library is released; however, if you’re adding support for a not yet final Python version the tool offers a functionality that it will invoke tox for you and inspect the test environments and use the latest python version tested against. For this to work tox needs to be on PATH, an easy way to ensure this is to set tox as additional dependency via:

- repo: https://github.com/tox-dev/pyproject-fmt
  rev: "1.0.0"
  hooks:
    - id: pyproject-fmt
      additional_dependencies: ["tox>=4.9"]

Command line interface#

pyproject-fmt [-h] [-V] [-s | --check] [--keep-full-version] [--indent INDENT]
              [--max-supported-python MAX_SUPPORTED_PYTHON]
              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

  • -s, --stdout - print the formatted text to the stdout (instead of update in-place)

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

  • --keep-full-version - keep full dependency versions. For example do not change version 1.0.0 to 1

  • --indent INDENT - number of spaces to indent (default: 2)

  • --max-supported-python MAX_SUPPORTED_PYTHON - latest Python version the project supports (e.g. 3.13) (default: 3.12)

Configuration file#

The tool.pyproject-fmt table is used when present in any of the pyproject.toml files

# pyproject.toml
[tool.pyproject-fmt]
indent = 4
keep_full_version = false
max_supported_python = "3.10"

API#

Format your pyproject.toml.

class pyproject_fmt.Config(pyproject_toml, toml, indent=2, keep_full_version=False, max_supported_python=<factory>)#

Bases: object

Configuration flags for the formatting.

pyproject_toml#
toml#

the text to format

indent = 2#

indentation to apply

keep_full_version = False#

whether to keep full dependency versions

max_supported_python#

the maximum supported Python version

with_overrides(overrides)#

Create a new configuration with overrides applied.

Parameters:

overrides (PyProjectConfig) – the overrides dictionary to apply from pyproject.toml

Return type:

Config

class pyproject_fmt.PyProjectConfig#

Bases: TypedDict

Configuration defined in the tool.pyproject-fmt table in pyproject.toml.

indent#

Indentation level to apply.

keep_full_version#

Whether to keep the full version string or not.

max_supported_python#

The maximum supported Python version.

pyproject_fmt.format_pyproject(conf)#

Format a pyproject.toml text.

Parameters:

conf (Config) – the formatting configuration

Return type:

str

Returns:

the formatted text