TOML Sort

0.24.4 · active · verified Sun Apr 12

toml-sort is a Python library and command-line utility for sorting and formatting TOML files. It provides features like sorting tables and arrays of tables, preserving comments, and standardizing whitespace and indentation. The library is actively maintained, with frequent releases, and is currently at version 0.24.4.

Warnings

breaking Version 0.24.0 dropped official support for Python 3.7 and 3.8. Users should upgrade to Python 3.9 or newer.
Fix: Upgrade your Python environment to 3.9 or later.
breaking Version 0.24.0 removed support for `tomlkit` versions older than 0.13.2. Ensure `tomlkit` is updated.
Fix: Update `tomlkit` to version 0.13.2 or newer (`pip install --upgrade tomlkit`).
gotcha Sorting inline tables with keys containing trailing spaces could cause a `ValueError` in versions 0.24.0 and 0.24.1. This was a regression.
Fix: Upgrade to version 0.24.2 or later, which includes a fix for this regression.
gotcha By default, `toml-sort` only sorts non-inline tables and arrays of tables. To sort all keys, including scalars and non-table entries, use the `--all` CLI option or configure `sort_all = true` in `pyproject.toml`.
Fix: Use `toml-sort --all <file>` or add `sort_all = true` under `[tool.toml_sort]` in your `pyproject.toml`.
gotcha Comment handling can be complex. While `toml-sort` strives to preserve comments, specific types of comments (header, footer, inline, block) can be selectively disabled via CLI switches, which will lead to their removal.
Fix: Review the documentation for comment handling options if comments are unexpectedly altered or removed. Use `--no-comments`, `--no-header`, etc., as needed.
gotcha `toml-sort` can be configured via `pyproject.toml` under the `[tool.toml_sort]` section. Command-line arguments will always take precedence over `pyproject.toml` settings in case of conflicts.
Fix: Be aware of the precedence order. Use CLI arguments for temporary overrides or specific runs, and `pyproject.toml` for project-wide default configurations.

Install

pip install toml-sort Install with pip

Imports

sort_toml_string

from toml_sort.tomlsort_tool import sort_toml_string

sort_toml_file

from toml_sort.tomlsort_tool import sort_toml_file

Quickstart

Demonstrates how to sort a TOML string programmatically using the `sort_toml_string` function.

from toml_sort.tomlsort_tool import sort_toml_string

unsorted_toml = '''
[database]
ports = [8000, 8001, 8002]
enabled = true

[owner]
name = "Tom"
dob = 1979-05-27T07:32:00-08:00
'''

sorted_toml = sort_toml_string(unsorted_toml)
print(sorted_toml)

view raw JSON →