### Install tox-toml-fmt using uv

Source: https://github.com/tox-dev/toml-fmt/blob/main/tox-toml-fmt/docs/index.rst

Installs tox-toml-fmt using the uv package installer. This method is recommended for isolated environments. It requires uv to be installed first.

```bash
# install uv per https://docs.astral.sh/uv/#getting-started
uv tool install tox-toml-fmt
tox-toml-fmt --help
```

--------------------------------

### Install and Run toml-fmt via CLI (uv)

Source: https://github.com/tox-dev/toml-fmt/blob/main/pyproject-fmt/docs/index.rst

Installs and runs pyproject-fmt using uv, a Python package installer. Requires Python 3.10+ and uv installed.

```bash
# install uv per https://docs.astral.sh/uv/#getting-started
uv tool install pyproject-fmt
pyproject-fmt --help
```

--------------------------------

### TOML Configuration Priority Example

Source: https://github.com/tox-dev/toml-fmt/blob/main/pyproject-fmt/docs/configuration.rst

Shows an example of setting table format preferences in pyproject.toml. It demonstrates how 'table_format', 'expand_tables', and 'collapse_tables' interact to determine the final formatting.

```toml
[tool.pyproject-fmt]
table_format = "short"  # Collapse most tables

```

--------------------------------

### Environment Key Ordering

Source: https://context7.com/tox-dev/toml-fmt/llms.txt

This TOML example shows how keys within environment tables are reordered into logical groups by tox-toml-fmt for improved readability.

```toml
# Before formatting (unordered)
[env_run_base]
commands = [["pytest"]]
deps = ["pytest>=7"]
description = "run tests"
pass_env = ["CI"]
package = "wheel"

# After formatting (ordered by category)
[env_run_base]
description = "run tests"
package = "wheel"
deps = ["pytest>=7"]
pass_env = ["CI"]
commands = [["pytest"]]

```

--------------------------------

### Complete pyproject.toml Example

Source: https://context7.com/tox-dev/toml-fmt/llms.txt

A fully formatted `pyproject.toml` file demonstrating various configuration options for build system, project metadata, dependencies, and tool-specific settings like `pyproject-fmt` and `ruff`.

```toml
[build-system]
build-backend = "hatchling.build"
requires = ["hatchling>=1.18"]

[project]
name = "my-awesome-project"
version = "1.0.0"
description = "An awesome Python project with proper formatting"
readme = "README.md"
keywords = ["awesome", "formatting", "python"]
license = { text = "MIT" }
authors = [{ name = "Alice Developer", email = "alice@example.com" }]
requires-python = ">=3.10"
classifiers = [
  "Development Status :: 4 - Beta",
  "License :: OSI Approved :: MIT License",
  "Programming Language :: Python :: 3 :: Only",
  "Programming Language :: Python :: 3.10",
  "Programming Language :: Python :: 3.11",
  "Programming Language :: Python :: 3.12",
  "Programming Language :: Python :: 3.13",
  "Programming Language :: Python :: 3.14",
]
dependencies = [
  "click>=8",
  "httpx>=0.25",
  "pydantic>=2",
]
urls.Documentation = "https://my-awesome-project.readthedocs.io"
urls.Homepage = "https://github.com/alice/my-awesome-project"
urls.Repository = "https://github.com/alice/my-awesome-project"
scripts.awesome = "my_awesome_project:main"

[project.optional-dependencies]
dev = ["black>=23", "pytest>=7", "ruff>=0.1"]
docs = ["sphinx>=7", "sphinx-rtd-theme>=2"]

[dependency-groups]
dev = ["pytest>=7", "ruff>=0.1", { include-group = "type" }]
type = ["mypy>=1.5"]

[tool.pyproject-fmt]
column_width = 120
indent = 2
max_supported_python = "3.14"

[tool.ruff]
target-version = "py310"
line-length = 120
lint.select = ["ALL"]
lint.ignore = ["ANN401", "COM812", "ISC001"]

[tool.coverage]
run.source = ["src"]
run.branch = true
report.fail_under = 90

[tool.pytest]
testpaths = ["tests"]
```

--------------------------------

### tox-toml-fmt CLI - Basic Usage

Source: https://context7.com/tox-dev/toml-fmt/llms.txt

Provides examples of basic command-line usage for `tox-toml-fmt`, including formatting files in place, printing to stdout, checking for unformatted files, and reading from stdin.

```bash
# Format a single file in place
tox-toml-fmt tox.toml

# Format and print output to stdout
tox-toml-fmt --stdout tox.toml

# Check if file is formatted (returns exit code 1 if changes needed)
tox-toml-fmt --check tox.toml

# Check without printing diff
tox-toml-fmt --check --no-print-diff tox.toml

# Read from stdin
cat tox.toml | tox-toml-fmt -
```

--------------------------------

### Install and Run toml-fmt via CLI (pip)

Source: https://github.com/tox-dev/toml-fmt/blob/main/pyproject-fmt/docs/index.rst

Installs and runs pyproject-fmt using pip. This method is discouraged due to potential system inconsistencies. Requires Python 3.10+.

```bash
python -m pip install --user pyproject-fmt
pyproject-fmt --help
```

--------------------------------

### Complete tox.toml Example

Source: https://context7.com/tox-dev/toml-fmt/llms.txt

A fully formatted `tox.toml` file demonstrating configuration for tox, including minimum version, requirements, environment list, and detailed environment definitions for testing, linting, type checking, and documentation.

```toml
min_version = "4.2"
requires = ["tox>=4.2", "tox-uv>=1"]
env_list = ["fix", "py314", "py313", "py312", "py311", "py310", "type", "docs"]
skip_missing_interpreters = true

[tox-toml-fmt]
pin_envs = ["fix"]

[env_run_base]
description = "run tests with pytest under {env_name}"
runner = "uv-venv-lock-runner"
package = "wheel"
wheel_build_env = ".pkg"
dependency_groups = ["test"]
pass_env = ["CI", "PYTEST_*", "SSL_CERT_FILE"]
set_env.COVERAGE_FILE = { replace = "env", name = "COVERAGE_FILE", default = "{work_dir}{/}.coverage.{env_name}" }
commands = [
  [
    "pytest",
    { replace = "posargs", extend = true, default = [
      "--cov",
      "{env_site_packages_dir}{/}mypackage",
      "--cov-report",
      "term-missing:skip-covered",
      "tests",
    ] },
  ],
]

[env.fix]
description = "run code formatters and linters"
skip_install = true
dependency_groups = ["fix"]
commands = [["pre-commit", "run", "--all-files"]]

[env.type]
description = "run type checking with mypy"
dependency_groups = ["type"]
commands = [["mypy", "src"], ["mypy", "tests"]]

[env.docs]
description = "build documentation with sphinx"
base_python = ["3.14"]
dependency_groups = ["docs"]
commands = [
  ["sphinx-build", "-d", "{env_tmp_dir}{/}doctrees", "docs", "{work_dir}{/}docs_out{/}html", "-W", "-b", "html"],
]

[env.dev]
description = "development environment with all dependencies"
package = "editable"
dependency_groups = ["dev"]
commands = [["python", "-c", 'print(r"{env_python}")']]
```

--------------------------------

### Environment Table Ordering

Source: https://context7.com/tox-dev/toml-fmt/llms.txt

This TOML example demonstrates how tox-toml-fmt orders environment tables, placing base tables first, followed by other environments according to their position in `env_list`.

```toml
# After formatting - tables ordered by env_list position
min_version = "4.2"
requires = ["tox>=4.2", "tox-uv"]
env_list = ["fix", "py313", "py312", "type", "docs"]

[env_run_base]
description = "run tests"
deps = ["pytest>=7"]

[env_pkg_base]
# package base configuration

[env.fix]
description = "run code formatters"

[env.py313]
# inherits from env_run_base

[env.py312]
# inherits from env_run_base

[env.type]
description = "run type checking"

[env.docs]
description = "build documentation"

```

--------------------------------

### Install tox-toml-fmt using pip

Source: https://github.com/tox-dev/toml-fmt/blob/main/tox-toml-fmt/docs/index.rst

Installs tox-toml-fmt using pip, the standard Python package installer. It is recommended to install as a user package using the --user flag. Caution is advised when using pip with system-managed Python installations.

```bash
python -m pip install --user tox-toml-fmt
tox-toml-fmt --help
```

--------------------------------

### Array Sorting in tox-toml-fmt

Source: https://context7.com/tox-dev/toml-fmt/llms.txt

This TOML example illustrates how dependencies and other arrays are automatically sorted by tox-toml-fmt.

```toml
# Before formatting
[env_run_base]
deps = ["Pytest >= 7", "-r requirements.txt", "coverage", "pytest-mock"]
pass_env = ["TERM", "CI", { replace = "default" }, "HOME"]
allowlist_externals = ["rm", "cp", "bash"]
extras = ["dev", "test", "docs"]

# After formatting (sorted)
[env_run_base]
deps = ["-r requirements.txt", "coverage", "pytest>=7", "pytest-mock"]
pass_env = [{ replace = "default" }, "CI", "HOME", "TERM"]
extras = ["dev", "docs", "test"]
allowlist_externals = ["bash", "cp", "rm"]

```

--------------------------------

### Install and Run toml-fmt via CLI (pipx)

Source: https://github.com/tox-dev/toml-fmt/blob/main/pyproject-fmt/docs/index.rst

Installs and runs pyproject-fmt using pipx, a tool for installing and running Python applications in isolated environments. Requires Python 3.10+.

```bash
python -m pip install pipx-in-pipx --user
pipx install pyproject-fmt
pyproject-fmt --help
```

--------------------------------

### Alias Normalization: Legacy INI to TOML

Source: https://context7.com/tox-dev/toml-fmt/llms.txt

This TOML example illustrates the automatic conversion of legacy INI-style key names to modern tox 4 TOML equivalents during formatting.

```toml
# Before formatting (legacy aliases)
envlist = ["py312", "py313"]
minversion = "4.2"
skipsdist = true

[env_run_base]
basepython = "python3.12"
setenv.PYTHONPATH = "src"
passenv = ["HOME"]
usedevelop = true

# After formatting (modern names)
min_version = "4.2"
env_list = ["py313", "py312"]
no_package = true

[env_run_base]
base_python = "python3.12"
package = "editable"
pass_env = ["HOME"]
set_env.PYTHONPATH = "src"

```

--------------------------------

### Install tox-toml-fmt using pipx

Source: https://github.com/tox-dev/toml-fmt/blob/main/tox-toml-fmt/docs/index.rst

Installs tox-toml-fmt using pipx, a tool for installing and running Python applications in isolated environments. This ensures that tox-toml-fmt does not interfere with other Python packages.

```bash
python -m pip install pipx-in-pipx --user
pipx install tox-toml-fmt
tox-toml-fmt --help
```

--------------------------------

### Format pyproject.toml - Table Format Examples

Source: https://context7.com/tox-dev/toml-fmt/llms.txt

Explains how to control the formatting of tables and sub-tables in pyproject.toml using `table_format`, `expand_tables`, and `collapse_tables` options. This affects how nested keys are represented.

```toml
# Short format (default) - dotted keys
[project]
name = "myproject"
urls.homepage = "https://example.com"
urls.repository = "https://github.com/example/myproject"
scripts.mycli = "mypackage:main"

# Long format - expanded table headers
[project]
name = "myproject"

[project.urls]
homepage = "https://example.com"
repository = "https://github.com/example/myproject"

[project.scripts]
mycli = "mypackage:main"

# Mixed format with configuration:
# [tool.pyproject-fmt]
# table_format = "short"
# expand_tables = ["project.optional-dependencies"]
[project]
name = "myproject"
urls.homepage = "https://example.com"

[project.optional-dependencies]
dev = ["pytest", "black"]
docs = ["sphinx"]
```

--------------------------------

### TOML Short Table Format Example

Source: https://github.com/tox-dev/toml-fmt/blob/main/pyproject-fmt/docs/configuration.rst

Illustrates the 'short' table format in TOML, where sub-tables are collapsed into dotted keys. This format is more compact and is the default behavior.

```toml
[project]
name = "myproject"
urls.homepage = "https://example.com"
urls.repository = "https://github.com/example/myproject"
scripts.mycli = "mypackage:main"

```

--------------------------------

### env_list Sorting Rules

Source: https://context7.com/tox-dev/toml-fmt/llms.txt

This TOML example shows how tox-toml-fmt sorts the `env_list`, prioritizing pinned environments, then Python versions descending, and finally named environments alphabetically.

```toml
# Before formatting
env_list = ["lint", "py38", "py312", "docs", "py310-django", "type"]

# After formatting (with pin_envs = ["fix", "type"])
env_list = ["fix", "type", "py312", "py310-django", "py38", "docs", "lint"]

# Sorting order:
# 1. Pinned environments (in order specified)
# 2. CPython versions (descending: py312 > py310 > py38)
# 3. Named environments (alphabetical: docs, lint)

```

--------------------------------

### Set Up Python Development Environment for toml-fmt-common

Source: https://github.com/tox-dev/toml-fmt/blob/main/CONTRIBUTING.md

Configures the development environment for the 'toml-fmt-common' Python package using tox. This typically involves installing dependencies and setting up virtual environments.

```bash
cd toml-fmt-common
tox run -e dev
```

--------------------------------

### Manually Format Python TOML File

Source: https://github.com/tox-dev/toml-fmt/blob/main/CONTRIBUTING.md

Example of how to manually run the pyproject-fmt formatter on a specific TOML file. This is useful for testing the formatter's behavior on individual files outside of the automated test suite. It takes the file path as an argument.

```bash
pyproject-fmt path/to/pyproject.toml
```

--------------------------------

### TOML Long Table Format Example

Source: https://github.com/tox-dev/toml-fmt/blob/main/pyproject-fmt/docs/configuration.rst

Demonstrates the 'long' table format in TOML, where sub-tables are expanded into separate sections with [table.subtable] headers. This format enhances readability for complex tables.

```toml
[project]
name = "myproject"

[project.urls]
homepage = "https://example.com"
repository = "https://github.com/example/myproject"

[project.scripts]
mycli = "mypackage:main"

```

--------------------------------

### Sort Arrays in Ruff Configuration (TOML)

Source: https://github.com/tox-dev/toml-fmt/blob/main/pyproject-fmt/docs/formatting.rst

Provides examples of how toml-fmt sorts arrays alphabetically within the [tool.ruff] configuration. This applies to various settings like 'lint.select', 'lint.ignore', and 'lint.per-file-ignores'.

```toml
# These arrays are sorted:
lint.select = ["E", "F", "I", "RUF"]
lint.ignore = ["E501", "E701"]

# Per-file-ignores values are also sorted:
lint.per-file-ignores."tests/*.py" = ["D103", "S101"]
```

--------------------------------

### Specify tox-toml-fmt configuration file via CLI

Source: https://github.com/tox-dev/toml-fmt/blob/main/tox-toml-fmt/docs/configuration.rst

You can explicitly specify the path to a configuration file using the `--config` option with the `tox-toml-fmt` command. This allows you to override the default configuration file search behavior and point to a specific configuration file. The example shows how to pass the config path and the file to be formatted.

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

--------------------------------

### TOML Environment Key Ordering

Source: https://github.com/tox-dev/toml-fmt/blob/main/tox-toml-fmt/docs/formatting.rst

Shows the standardized ordering of keys within environment tables like `[env_run_base]`. Keys are grouped and ordered logically, for example, `deps` followed by `commands`.

```toml
# Before
[env_run_base]
commands = ["pytest"]
deps = ["pytest>=7"]

# After (demonstrating a portion of the ordered keys)
[env_run_base]
# ... other keys ...
deps = ["pytest>=7"]
# ... other keys ...
commands = ["pytest"]
# ... other keys ...
```

--------------------------------

### TOML Environment Table Alias Normalization

Source: https://github.com/tox-dev/toml-fmt/blob/main/tox-toml-fmt/docs/formatting.rst

Demonstrates the renaming of legacy INI-style key names to modern TOML equivalents within environment tables like `[env_run_base]`. Examples include `setenv` to `set_env` and `basepython` to `base_python`.

```toml
# Before
[env_run_base]
basepython = "python3.12"
setenv.PYTHONPATH = "src"
passenv = ["HOME"]

# After
[env_run_base]
base_python = "python3.12"
set_env.PYTHONPATH = "src"
pass_env = ["HOME"]
```

--------------------------------

### Python API: Running the Formatter

Source: https://context7.com/tox-dev/toml-fmt/llms.txt

This Python code demonstrates how to use the `runner` function from `pyproject_fmt.__main__` to format files with command-line-like behavior.

```python
from pyproject_fmt.__main__ import runner

# Format file in place (returns 0 if no changes, 1 if formatted)
exit_code = runner(["pyproject.toml"])

# Check if file needs formatting
exit_code = runner(["--check", "pyproject.toml"])

```

--------------------------------

### Set Up Python Development Environment with Tox

Source: https://github.com/tox-dev/toml-fmt/blob/main/CONTRIBUTING.md

Instructions for setting up the Python development environment for the pyproject-fmt package using tox. This involves navigating to the package directory and running the 'dev' environment defined in the tox configuration. This prepares the environment for development tasks.

```bash
cd pyproject-fmt
tox run -e dev
```

--------------------------------

### Format pyproject.toml - tool.coverage Key Ordering

Source: https://context7.com/tox-dev/toml-fmt/llms.txt

Demonstrates the workflow-based ordering of keys within the `[tool.coverage]` section, including `run`, `report`, and output format sections, for a structured coverage configuration.

```toml
# Before formatting
[tool.coverage]
report.fail_under = 100
run.parallel = true
html.show_contexts = true
run.source = ["src"]
report.omit = ["tests/*"]

# After formatting (workflow order: run -> report -> output formats)
[tool.coverage]
run.source = ["src"]
run.parallel = true
report.omit = ["tests/*"]
report.fail_under = 100
html.show_contexts = true
```

--------------------------------

### Format pyproject.toml - Project Key Ordering

Source: https://context7.com/tox-dev/toml-fmt/llms.txt

Demonstrates the standardized reordering of keys within the `[project]` table in pyproject.toml. This ensures a consistent and predictable structure for project metadata.

```toml
# Before formatting (unordered)
[project]
dependencies = ["click"]
name = "myproject"
authors = [{ name = "Alice" }]
version = "1.0.0"
description = "A project"
requires-python = ">=3.10"

# After formatting (ordered)
[project]
name = "myproject"
version = "1.0.0"
description = "A project"
authors = [{ name = "Alice" }]
requires-python = ">=3.10"
dependencies = ["click"]
```

--------------------------------

### tox-toml-fmt CLI - Formatting Options

Source: https://context7.com/tox-dev/toml-fmt/llms.txt

Details various command-line options for customizing `tox-toml-fmt` behavior, such as setting column width, indentation, pinning environments, and controlling table formatting.

```bash
# Set maximum column width (default: 120)
tox-toml-fmt --column-width 100 tox.toml

# Set indentation spaces (default: 2)
tox-toml-fmt --indent 4 tox.toml

# Pin specific environments to start of env_list
tox-toml-fmt --pin-env "fix,type" tox.toml

# Control table formatting
tox-toml-fmt --table-format short tox.toml
tox-toml-fmt --table-format long tox.toml

# Force expand/collapse specific tables
tox-toml-fmt --expand-tables "env.test" tox.toml
tox-toml-fmt --collapse-tables "env.lint" tox.toml
```

--------------------------------

### Testing PyO3 Module Registration from Rust

Source: https://github.com/tox-dev/toml-fmt/blob/main/CONTRIBUTING.md

Illustrates how to test PyO3 module registration functions from Rust code. This involves configuring dependencies, running tests with specific features disabled, and using PyO3's initialization and attachment methods to interact with the Python environment.

```rust
#[test]
fn test_lib_module_registration() {
    use pyo3::types::PyAnyMethods;

    pyo3::Python::initialize();
    pyo3::Python::attach(|py| {
        let module = pyo3::types::PyModule::new(py, "_lib").unwrap();
        crate::_lib(&module.as_borrowed()).unwrap();

        assert!(module.hasattr("format_toml").unwrap());
        assert!(module.hasattr("Settings").unwrap());
    });
}
```

--------------------------------

### Command Line Configuration for pyproject-fmt

Source: https://github.com/tox-dev/toml-fmt/blob/main/pyproject-fmt/docs/configuration.rst

Demonstrates how to specify a configuration file using the --config flag with the pyproject-fmt command. This allows for external configuration files to manage formatting settings.

```bash
pyproject-fmt --config /path/to/pyproject-fmt.toml pyproject.toml

```

--------------------------------

### TOML: Sort 'pass_env' Array

Source: https://github.com/tox-dev/toml-fmt/blob/main/tox-toml-fmt/docs/formatting.rst

Illustrates the sorting of the 'pass_env' array in TOML. Replacement objects (inline tables with 'replace') are pinned to the start, followed by string entries sorted alphabetically.

```toml
# Before
pass_env = ["TERM", "CI", { replace = "default", ... }, "HOME"]

# After
pass_env = [{ replace = "default", ... }, "CI", "HOME", "TERM"]
```

--------------------------------

### Set Up Development Environment for tox-toml-fmt

Source: https://github.com/tox-dev/toml-fmt/blob/main/CONTRIBUTING.md

Instructions to set up the Python development environment for the tox-toml-fmt package using tox. Similar to pyproject-fmt, this involves changing the directory and running the 'dev' tox environment.

```bash
cd tox-toml-fmt
tox run -e dev
```

--------------------------------

### Rust LLVM Coverage Artifact Example

Source: https://github.com/tox-dev/toml-fmt/blob/main/CONTRIBUTING.md

Illustrates a known LLVM coverage instrumentation artifact where closing braces of multi-branch conditionals are reported as uncovered, even when all code paths are tested. This is a limitation and should not block merging.

```rust
if condition {
    return Some(value);  // covered
}                        // reported as uncovered by LLVM

```

--------------------------------

### Format pyproject.toml - tool.ruff Key Ordering

Source: https://context7.com/tox-dev/toml-fmt/llms.txt

Shows the reordering of keys within the `[tool.ruff]` section and sorting of array values, such as `lint.ignore` and `lint.select`, for consistent Ruff configuration.

```toml
# Before formatting
[tool.ruff]
fix = true
line-length = 120
lint.ignore = ["E501", "COM812", "ANN401"]
lint.select = ["F", "E", "ALL"]
target-version = "py310"

# After formatting (ordered with sorted arrays)
[tool.ruff]
target-version = "py310"
line-length = 120
fix = true
lint.select = ["ALL", "E", "F"]
lint.ignore = ["ANN401", "COM812", "E501"]
```

--------------------------------

### Python API: pyproject-fmt Formatting

Source: https://context7.com/tox-dev/toml-fmt/llms.txt

This Python code demonstrates how to use the `pyproject-fmt` library programmatically to format TOML content, including custom settings.

```python
from pyproject_fmt import format_toml
from pyproject_fmt._lib import Settings

# Create settings with custom configuration
settings = Settings(
    column_width=120,
    indent=2,
    keep_full_version=False,
    max_supported_python=(3, 14),
    min_supported_python=(3, 10),
    generate_python_version_classifiers=True,
    table_format="short",
    expand_tables=[],
    collapse_tables=[],
    skip_wrap_for_keys=[],
)

# Format TOML content
input_toml = '''
[project]
name = "myproject"
dependencies = ["requests >= 2.0.0", "click"]
'''

formatted = format_toml(input_toml, settings)
print(formatted)
# Output:
# [project]
# name = "myproject"
# dependencies = ["click", "requests>=2"]

```

--------------------------------

### TOML Array Formatting Examples

Source: https://github.com/tox-dev/toml-fmt/blob/main/pyproject-fmt/docs/formatting.rst

Shows various TOML array formatting scenarios. Short arrays remain on one line. Long arrays exceeding column width are expanded with a trailing comma. Arrays with trailing commas or comments are always formatted on multiple lines.

```toml
# Short arrays stay on one line
keywords = ["python", "toml"]

# Long arrays that exceed column_width are expanded and get a trailing comma
dependencies = [
    "requests>=2.28",
    "click>=8.0",
]

# Trailing commas signal intent to keep multiline format
classifiers = [
    "Development Status :: 4 - Beta",
]

# Arrays with comments are always multiline
lint.ignore = [
    "E501",  # Line too long
    "E701",
]
```

--------------------------------

### Pre-commit Configuration for tox-toml-fmt

Source: https://context7.com/tox-dev/toml-fmt/llms.txt

This YAML snippet shows how to integrate tox-toml-fmt into your pre-commit configuration to automatically format TOML files.

```yaml
# .pre-commit-config.yaml
repos:
  - repo: https://github.com/tox-dev/pyproject-fmt
    rev: "v2.16.2"
    hooks:
      - id: pyproject-fmt

  - repo: https://github.com/tox-dev/tox-toml-fmt
    rev: "v1.9.0"
    hooks:
      - id: tox-toml-fmt

```

--------------------------------

### [project] Table Key Ordering and Value Normalization

Source: https://github.com/tox-dev/toml-fmt/blob/main/pyproject-fmt/docs/formatting.rst

Demonstrates the key ordering and various field normalizations for the [project] table, including name, description, license, and dependency formats.

```toml
# Before
dependencies = ["requests >= 2.0.0", "click~=8.0"]

# After
dependencies = ["click>=8", "requests>=2"]
```

--------------------------------

### Format pyproject.toml - Dependency Normalization

Source: https://context7.com/tox-dev/toml-fmt/llms.txt

Shows how toml-fmt normalizes and sorts dependencies according to PEP 508. This applies to both the main dependencies and optional dependencies.

```toml
# Before formatting
[project]
dependencies = [
  "requests >= 2.0.0",
  "Click~=8.0",
  "urllib3",
  "AIOHTTP>=3.8",
]

[project.optional-dependencies]
Dev_Tools = ["pytest", "Black>=23.0"]

# After formatting
[project]
dependencies = [
  "aiohttp>=3.8",
  "click>=8",
  "requests>=2",
  "urllib3",
]

[project.optional-dependencies]
dev-tools = ["black>=23", "pytest"]
```

--------------------------------

### [build-system] Table Key Ordering and Value Normalization

Source: https://github.com/tox-dev/toml-fmt/blob/main/pyproject-fmt/docs/formatting.rst

Shows the key ordering and value normalization for the [build-system] table. It demonstrates the reordering of keys and normalization of dependency strings.

```toml
# Before
[build-system]
requires = ["setuptools >= 45", "wheel"]
build-backend = "setuptools.build_meta"

# After
[build-system]
build-backend = "setuptools.build_meta"
requires = ["setuptools>=45", "wheel"]
```

--------------------------------

### Expand Inline Tables in entry-points to Dotted Keys (TOML)

Source: https://github.com/tox-dev/toml-fmt/blob/main/pyproject-fmt/docs/formatting.rst

Demonstrates how toml-fmt expands inline tables within the 'entry-points' section into dotted keys. This simplifies configuration by flattening nested structures.

```toml
# Before
entry-points.console_scripts = { mycli = "mypackage:main" }

# After
entry-points.console_scripts.mycli = "mypackage:main"
```

--------------------------------

### Key Ordering in UV Configuration (TOML)

Source: https://github.com/tox-dev/toml-fmt/blob/main/pyproject-fmt/docs/formatting.rst

Outlines the key ordering rules for the [tool.uv] section, grouping settings by functionality such as version, dependencies, sources, and package handling.

```toml
# Example of key ordering within [tool.uv]
[tool.uv]
required-version = "0.1.0"
python-preference = "3.10"

dev-dependencies = ["pytest"]
default-groups = ["dev"]

sources = [{"url" = "https://pypi.org/simple/"}]
index-strategy = "prefer-binary"

no-binary = ["numpy"]
upgrade = true

```

--------------------------------

### Format pyproject.toml - Section Ordering

Source: https://context7.com/tox-dev/toml-fmt/llms.txt

Demonstrates how toml-fmt reorders sections within a pyproject.toml file for standardized structure. This includes build-system, project, and tool.* categories.

```toml
# Before formatting (unordered)
[project]
name = "myproject"

[tool.pytest]
testpaths = ["tests"]

[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"

[tool.ruff]
line-length = 100

# After formatting (ordered: build-system -> project -> tool.* by category)
[build-system]
build-backend = "hatchling.build"
requires = ["hatchling"]

[project]
name = "myproject"

[tool.ruff]
line-length = 100

[tool.pytest]
testpaths = ["tests"]
```

--------------------------------

### Configure tox-toml-fmt in tox.toml

Source: https://github.com/tox-dev/toml-fmt/blob/main/tox-toml-fmt/docs/configuration.rst

Settings for tox-toml-fmt can be specified within the `[tox-toml-fmt]` table in your `tox.toml` file. These settings control aspects like column width for formatting, indentation spaces, and environment list pinning. If not provided, these settings default to values from the CLI.

```toml
[tox-toml-fmt]

# After how many columns split arrays/dicts into multiple lines and wrap long strings;
# use a trailing comma in arrays to force multiline format instead of lowering this value
column_width = 120

# Number of spaces for indentation
indent = 2

# Environments pinned to the start of env_list
pin_envs = ["fix", "type"]
```

--------------------------------

### Configure toml-fmt as a pre-commit hook

Source: https://github.com/tox-dev/toml-fmt/blob/main/pyproject-fmt/docs/index.rst

Configures pyproject-fmt to run as a pre-commit hook by adding it to the .pre-commit-config.yaml file. This ensures consistent formatting before commits.

```yaml
- repo: https://github.com/tox-dev/pyproject-fmt
  # Use the sha / tag you want to point at
  # or use `pre-commit autoupdate` to get the latest version
  rev: ""
  hooks:
    - id: pyproject-fmt
```

--------------------------------

### Parameterized Unit Tests with rstest

Source: https://github.com/tox-dev/toml-fmt/blob/main/CONTRIBUTING.md

Demonstrates using the 'rstest' crate for parameterized unit tests in Rust. It shows how to define multiple test cases with different inputs and expected outputs within a single test function, reducing code duplication.

```rust
use rstest::rstest;
use crate::SyntaxKind;

#[rstest]
#[case::basic_string("\"hello\"", STRING, "hello")]
#[case::escaped_quote("\"hello \\\"world\\\"\"", STRING, "hello \"world\"")]
fn test_load_text(#[case] input: &str, #[case] kind: SyntaxKind, #[case] expected: &str) {
    assert_eq!(load_text(input, kind), expected);
}
```

--------------------------------

### Configure tox-toml-fmt as a pre-commit hook

Source: https://github.com/tox-dev/toml-fmt/blob/main/tox-toml-fmt/docs/index.rst

Integrates tox-toml-fmt into your project's pre-commit hooks by adding it to your .pre-commit-config.yaml file. This ensures that tox.toml files are automatically formatted before each commit.

```yaml
- repo: https://github.com/tox-dev/tox-toml-fmt
  rev: "v1.0.0"
  hooks:
    - id: tox-toml-fmt
```

--------------------------------

### Rust Creating New TOML Syntax Nodes

Source: https://github.com/tox-dev/toml-fmt/blob/main/CONTRIBUTING.md

Demonstrates the creation of new TOML syntax nodes using functions from `common::create`, such as `make_string_node` and `make_entry_of_string`. These functions ensure the generated nodes adhere to valid TOML syntax.

```rust
use common::create::{make_string_node, make_entry_of_string};

let new_string = make_string_node("value");
let new_entry = make_entry_of_string(&"key".to_string(), &"value".to_string());

```

--------------------------------

### Format All Rust Code in Workspace

Source: https://github.com/tox-dev/toml-fmt/blob/main/CONTRIBUTING.md

Command to format all Rust code across all packages in the workspace. The `--all` flag ensures that formatting is applied consistently throughout the project.

```bash
cargo fmt --all
```

--------------------------------

### Run Rust Tests for pyproject-fmt Package

Source: https://github.com/tox-dev/toml-fmt/blob/main/CONTRIBUTING.md

Executes the Rust unit tests for the 'pyproject-fmt' package. This verifies the core formatting logic for pyproject.toml files, including the Rust implementation.

```bash
cargo test -p pyproject-fmt
```

--------------------------------

### Print pyproject.toml to stdout

Source: https://context7.com/tox-dev/toml-fmt/llms.txt

This snippet shows how to use the `runner` function with the `--stdout` flag to print the formatted `pyproject.toml` content to standard output without modifying the file.

```python
exit_code = runner(["--stdout", "pyproject.toml"])
```

--------------------------------

### Key Ordering in Ruff Configuration (TOML)

Source: https://github.com/tox-dev/toml-fmt/blob/main/pyproject-fmt/docs/formatting.rst

Details the specific key ordering applied by toml-fmt within the [tool.ruff] section. Keys are grouped logically, from global settings to plugin-specific configurations.

```toml
# Example of key ordering within [tool.ruff]
[tool.ruff]
required-version = "v0.1.0"
extend = "pyproject.toml"
target-version = "py310"
line-length = 88
indent-width = 4
tab-size = 4

builtins = []
native-python-parsing = false
src = ["src"]
include = ["*.py"]
exclude = ["venv", "dist"]

preview = true
fix = false
unsafe-fixes = false
fix-only = false
show-fixes = false
show-source = false

output-format = "text"
cache-dir = ".ruff_cache"

format.exclude = ["docs/conf.py"]

[tool.ruff.lint]
select = ["E", "F", "I", "RUF"]
ignore = ["E501"]
per-file-ignores = {"__init__.py" = ["F401"]}

```

--------------------------------

### Format pyproject.toml with Custom Options

Source: https://context7.com/tox-dev/toml-fmt/llms.txt

This snippet demonstrates how to use the `runner` function to format a `pyproject.toml` file with custom column width, indent, and maximum supported Python version.

```python
exit_code = runner([
    "--column-width", "100",
    "--indent", "4",
    "--keep-full-version",
    "--max-supported-python", "3.13",
    "pyproject.toml"
])
```

--------------------------------

### Format TOML content programmatically with Python

Source: https://github.com/tox-dev/toml-fmt/blob/main/pyproject-fmt/docs/index.rst

Uses the pyproject_fmt.run function to format TOML content from a specified file. The function accepts command-line arguments as a list and returns an exit code.

```python
from pyproject_fmt import run

# Format a pyproject.toml file and return the exit code
exit_code = run(["path/to/pyproject.toml"])
```

--------------------------------

### Check Rust Test Coverage for pyproject-fmt

Source: https://github.com/tox-dev/toml-fmt/blob/main/CONTRIBUTING.md

Generates a summary of test coverage for the Rust code within the 'pyproject-fmt' package using llvm-cov. This helps identify untested Rust logic related to pyproject.toml formatting.

```bash
cargo llvm-cov -p pyproject-fmt --summary-only
```

--------------------------------

### Rust Snapshot Testing with Insta (Inline Snapshots)

Source: https://github.com/tox-dev/toml-fmt/blob/main/CONTRIBUTING.md

Shows the preferred snapshot testing approach using the `insta` crate with inline snapshots in Rust. This method simplifies test maintenance by storing expected output directly in the test file, making it easier to review and update.

```rust
#[rstest]
#[case::simple("input")]
fn test_format(#[case] input: &str) {
    let result = format_toml(input);
    insta::assert_snapshot!(result, @"");
}

```

--------------------------------

### Run All Workspace Tests with No Default Features

Source: https://github.com/tox-dev/toml-fmt/blob/main/CONTRIBUTING.md

Command to run all tests across all packages in the workspace, specifically disabling default features. This is crucial for matching CI behavior, as it ensures tests do not rely on the PyO3 'extension-module' feature, which links against Python.

```bash
cargo test --workspace --no-default-features
```

--------------------------------

### TOML: Upgrade 'use_develop' to 'package'

Source: https://github.com/tox-dev/toml-fmt/blob/main/tox-toml-fmt/docs/formatting.rst

Shows the automatic conversion of the legacy 'use_develop = true' setting to 'package = "editable"' in TOML files. If 'package' already exists, 'use_develop' is simply removed. 'use_develop = false' is left unchanged.

```toml
# Before
[env_run_base]
use_develop = true

# After
[env_run_base]
package = "editable"
```

--------------------------------

### Run Rust Linter in common Package

Source: https://github.com/tox-dev/toml-fmt/blob/main/CONTRIBUTING.md

Runs the clippy linter on the 'common' Rust crate to catch common mistakes and improve code quality. It provides suggestions for more idiomatic Rust code.

```bash
cargo clippy -p common
```

--------------------------------

### Collapse Array of Tables to Inline Format

Source: https://github.com/tox-dev/toml-fmt/blob/main/pyproject-fmt/docs/configuration.rst

Demonstrates how arrays of tables (e.g., [[table]]) are automatically collapsed into inline tables when each element fits within the configured column width. This improves readability for short, repetitive table structures.

```toml
# Before
[[tool.commitizen.customize.questions]]
type = "list"

[[tool.commitizen.customize.questions]]
type = "input"

# After (with table_format = "short")
[tool.commitizen]
customize.questions = [{ type = "list" }, { type = "input" }]
```

--------------------------------

### Format pyproject.toml - Python Version Classifiers

Source: https://context7.com/tox-dev/toml-fmt/llms.txt

Illustrates the automatic generation of Python version classifiers based on the `requires-python` field in pyproject.toml. This helps in specifying compatible Python versions.

```toml
# Before formatting
[project]
requires-python = ">=3.10"

# After formatting (with max_supported_python = "3.14")
[project]
requires-python = ">=3.10"
classifiers = [
  "Programming Language :: Python :: 3 :: Only",
  "Programming Language :: Python :: 3.10",
  "Programming Language :: Python :: 3.11",
  "Programming Language :: Python :: 3.12",
  "Programming Language :: Python :: 3.13",
  "Programming Language :: Python :: 3.14",
]
```

--------------------------------

### Run Rust Tests for tox-toml-fmt Package

Source: https://github.com/tox-dev/toml-fmt/blob/main/CONTRIBUTING.md

Executes the Rust unit tests for the 'tox-toml-fmt' package. This verifies the core formatting logic for tox.toml files, including the Rust implementation.

```bash
cargo test -p tox-toml-fmt
```

--------------------------------

### TOML String Wrapping with Line Continuations

Source: https://github.com/tox-dev/toml-fmt/blob/main/pyproject-fmt/docs/formatting.rst

Demonstrates how pyproject-fmt wraps long strings that exceed the column width. It converts them into multi-line triple-quoted strings using line continuations, preferring to break at spaces or specific separators like ' :: '.

```toml
# Before (exceeds column_width)
description = "A very long description that goes beyond the configured column width limit"

# After
description = """
  A very long description that goes beyond the \
  configured column width limit
  """
```

--------------------------------

### Configure Table Expansion and Collapse in TOML

Source: https://github.com/tox-dev/toml-fmt/blob/main/pyproject-fmt/docs/configuration.rst

Defines rules for expanding or collapsing tables in TOML files. Uses CSS-like specificity where more specific rules override general ones. Supports 'collapse_tables' and 'expand_tables' lists.

```toml
[tool.pyproject-fmt]
table_format = "long"
collapse_tables = ["project"]
expand_tables = ["project.optional-dependencies"]
```

--------------------------------

### Format Coverage.py Configuration

Source: https://github.com/tox-dev/toml-fmt/blob/main/pyproject-fmt/docs/formatting.rst

Illustrates the reordering of keys within the [tool.coverage] section according to coverage.py's workflow phases (Run, Paths, Report) and grouping principles. This enhances readability and maintainability of coverage configurations.

```toml
# Before (alphabetical)
[tool.coverage]
report.exclude_also = ["if TYPE_CHECKING:"]
report.omit = ["tests/*"]
run.branch = true
run.omit = ["tests/*"]

# After (workflow order with groupings)
[tool.coverage]
run.branch = true
run.omit = ["tests/*"]
report.omit = ["tests/*"]
report.exclude_also = ["if TYPE_CHECKING:"]
```

--------------------------------

### Configure String Wrapping Exceptions in TOML

Source: https://github.com/tox-dev/toml-fmt/blob/main/pyproject-fmt/docs/configuration.rst

Specifies keys for which string wrapping should be skipped. This is useful for strings like regex patterns that should not be altered by line continuations. Supports glob-like patterns for flexible matching.

```toml
[tool.pyproject-fmt]
skip_wrap_for_keys = ["*.parse", "*.regex", "tool.bumpversion.*"]
```

--------------------------------

### TOML Table Ordering and Environment Section Handling

Source: https://github.com/tox-dev/toml-fmt/blob/main/tox-toml-fmt/docs/formatting.rst

Illustrates the standardized order of tables in a TOML file, including root-level keys, base environment configurations, and environment-specific sections. The order of `[env.NAME]` sections is determined by `env_list`.

```toml
# env_list determines the order of [env.*] sections
env_list = ["lint", "type", "py312", "py313"]

[env_run_base]
deps = ["pytest>=7"]

[env_pkg_base]
# ...

[env_base.ci]
# shared base config

# Environments appear in env_list order:
[env.lint]
# ...

[env.type]
# ...

[env.py312]
# ...

[env.py313]
# ...
```

--------------------------------

### Check Rust Test Coverage in common Package

Source: https://github.com/tox-dev/toml-fmt/blob/main/CONTRIBUTING.md

Generates a summary of test coverage for the 'common' Rust crate using llvm-cov. This helps identify areas of the code that are not adequately tested.

```bash
cargo llvm-cov -p common --summary-only
```

--------------------------------

### TOML Shared Configuration File

Source: https://github.com/tox-dev/toml-fmt/blob/main/pyproject-fmt/docs/configuration.rst

Shows the structure of a standalone pyproject-fmt.toml file. This file contains formatting settings without the [tool.pyproject-fmt] table header and can be used across multiple projects.

```toml
column_width = 120
indent = 2
table_format = "short"
max_supported_python = "3.14"

```