pypfmt 0.1.0__tar.gz

pypfmt-0.1.0/.gitignore

@@ -0,0 +1,145 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+.python-version
+
+# pipenv
+Pipfile.lock
+
+# PEP 582
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# ruff
+.ruff_cache/
+
+# ty
+.ty_cache/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+*~
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Project specific
+*.log
+.env.*
+!.env.example

pypfmt-0.1.0/LICENSE

@@ -0,0 +1,22 @@
+
+MIT License
+
+Copyright (c) 2026 Jamie McGregor Nelson
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

pypfmt-0.1.0/PKG-INFO

@@ -0,0 +1,132 @@
+Metadata-Version: 2.4
+Name: pypfmt
+Version: 0.1.0
+Summary: A Python package to sort and format pyproject.toml
+Project-URL: Changelog, https://github.com/bitflight-devops/pyproject-fmt/blob/main/CHANGELOG.md
+Project-URL: Documentation, https://bitflight-devops.github.io/pyproject-fmt
+Project-URL: Homepage, https://github.com/bitflight-devops/pyproject-fmt
+Project-URL: Issues, https://github.com/bitflight-devops/pyproject-fmt/issues
+Project-URL: Repository, https://github.com/bitflight-devops/pyproject-fmt
+Author-email: Jamie McGregor Nelson <jamie@bitflight.io>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: taplo>=0.9.0
+Requires-Dist: toml-sort<0.25,>=0.24.0
+Requires-Dist: typer>=0.12.0
+Description-Content-Type: text/markdown
+
+# pypfmt
+
+[![CI](https://github.com/bitflight-devops/pyproject-fmt/actions/workflows/ci.yml/badge.svg)](https://github.com/bitflight-devops/pyproject-fmt/actions/workflows/ci.yml)
+[![PyPI version](https://badge.fury.io/py/pypfmt.svg)](https://badge.fury.io/py/pypfmt)
+[![codecov](https://codecov.io/gh/bitflight-devops/pyproject-fmt/branch/main/graph/badge.svg)](https://codecov.io/gh/bitflight-devops/pyproject-fmt)
+[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)
+[![uv](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/uv/main/assets/badge/v0.json)](https://github.com/astral-sh/uv)
+[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
+[![ty](https://img.shields.io/badge/type--checked-ty-blue?labelColor=orange)](https://github.com/astral-sh/ty)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://github.com/bitflight-devops/pyproject-fmt/blob/main/LICENSE)
+
+A Python package to sort and format pyproject.toml
+
+## Features
+
+- Fast and modern Python toolchain using Astral's tools (uv, ruff, ty)
+- Type-safe with full type annotations
+- Command-line interface built with Typer
+- Comprehensive documentation with MkDocs — [View Docs](https://bitflight-devops.github.io/pyproject-fmt/)
+
+## Installation
+
+```bash
+pip install pypfmt
+```
+
+Or using uv (recommended):
+
+```bash
+uv add pypfmt
+```
+
+## Quick Start
+
+```python
+import pypfmt
+
+print(pypfmt.__version__)
+```
+
+### CLI Usage
+
+```bash
+# Show version
+pypfmt --version
+
+# Say hello
+pypfmt hello World
+```
+
+## Development
+
+### Prerequisites
+
+- Python 3.11+
+- [uv](https://docs.astral.sh/uv/) for package management
+
+### Setup
+
+```bash
+git clone https://github.com/bitflight-devops/pyproject-fmt.git
+cd pyproject-fmt
+uv sync --all-groups
+```
+
+### Running Tests
+
+```bash
+uv run poe test
+
+# With coverage
+uv run poe test-cov
+
+# Across all Python versions
+uv run poe test-matrix
+```
+
+### Code Quality
+
+```bash
+# Run all checks (lint, format, type-check)
+uv run poe verify
+
+# Auto-fix lint and format issues
+uv run poe fix
+```
+
+### Prek
+
+```bash
+prek install
+prek run --all-files
+```
+
+### Documentation
+
+```bash
+uv run poe docs-serve
+```
+
+## License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

pypfmt-0.1.0/README.md

@@ -0,0 +1,103 @@
+# pypfmt
+
+[![CI](https://github.com/bitflight-devops/pyproject-fmt/actions/workflows/ci.yml/badge.svg)](https://github.com/bitflight-devops/pyproject-fmt/actions/workflows/ci.yml)
+[![PyPI version](https://badge.fury.io/py/pypfmt.svg)](https://badge.fury.io/py/pypfmt)
+[![codecov](https://codecov.io/gh/bitflight-devops/pyproject-fmt/branch/main/graph/badge.svg)](https://codecov.io/gh/bitflight-devops/pyproject-fmt)
+[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)
+[![uv](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/uv/main/assets/badge/v0.json)](https://github.com/astral-sh/uv)
+[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
+[![ty](https://img.shields.io/badge/type--checked-ty-blue?labelColor=orange)](https://github.com/astral-sh/ty)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://github.com/bitflight-devops/pyproject-fmt/blob/main/LICENSE)
+
+A Python package to sort and format pyproject.toml
+
+## Features
+
+- Fast and modern Python toolchain using Astral's tools (uv, ruff, ty)
+- Type-safe with full type annotations
+- Command-line interface built with Typer
+- Comprehensive documentation with MkDocs — [View Docs](https://bitflight-devops.github.io/pyproject-fmt/)
+
+## Installation
+
+```bash
+pip install pypfmt
+```
+
+Or using uv (recommended):
+
+```bash
+uv add pypfmt
+```
+
+## Quick Start
+
+```python
+import pypfmt
+
+print(pypfmt.__version__)
+```
+
+### CLI Usage
+
+```bash
+# Show version
+pypfmt --version
+
+# Say hello
+pypfmt hello World
+```
+
+## Development
+
+### Prerequisites
+
+- Python 3.11+
+- [uv](https://docs.astral.sh/uv/) for package management
+
+### Setup
+
+```bash
+git clone https://github.com/bitflight-devops/pyproject-fmt.git
+cd pyproject-fmt
+uv sync --all-groups
+```
+
+### Running Tests
+
+```bash
+uv run poe test
+
+# With coverage
+uv run poe test-cov
+
+# Across all Python versions
+uv run poe test-matrix
+```
+
+### Code Quality
+
+```bash
+# Run all checks (lint, format, type-check)
+uv run poe verify
+
+# Auto-fix lint and format issues
+uv run poe fix
+```
+
+### Prek
+
+```bash
+prek install
+prek run --all-files
+```
+
+### Documentation
+
+```bash
+uv run poe docs-serve
+```
+
+## License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

pypfmt-0.1.0/pyproject.toml

@@ -0,0 +1,199 @@
+[project]
+name = "pypfmt"
+version = "0.1.0"
+description = "A Python package to sort and format pyproject.toml"
+readme = "README.md"
+authors = [
+    { name = "Jamie McGregor Nelson", email = "jamie@bitflight.io" },
+]
+license = "MIT"
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "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",
+    "Typing :: Typed",
+]
+keywords = []
+requires-python = ">=3.11"
+dependencies = [
+    "taplo>=0.9.0",
+    "toml-sort>=0.24.0,<0.25",
+    "typer>=0.12.0",
+]
+
+[project.scripts]
+pypfmt = "pypfmt.cli:app"
+
+[project.urls]
+Changelog = "https://github.com/bitflight-devops/pyproject-fmt/blob/main/CHANGELOG.md"
+Documentation = "https://bitflight-devops.github.io/pyproject-fmt"
+Homepage = "https://github.com/bitflight-devops/pyproject-fmt"
+Issues = "https://github.com/bitflight-devops/pyproject-fmt/issues"
+Repository = "https://github.com/bitflight-devops/pyproject-fmt"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[dependency-groups]
+dev = [
+    "hatch>=1.16.3",
+    "poethepoet>=0.32.0",
+    "prek>=0.1.0",
+    "pysentry-rs>=0.1.0",
+    "pytest-cov>=7.0.0",
+    "pytest>=9.0.0",
+    "ruff>=0.14.14",
+    "ty>=0.0.14",
+]
+docs = [
+    "mkdocs-material>=9.7.0",
+    "mkdocs>=1.6.0",
+    "mkdocstrings-python>=2.0.1",
+]
+
+[tool.coverage.report]
+exclude_lines = [
+    "@abstractmethod",
+    "def __repr__",
+    "if TYPE_CHECKING:",
+    "if __name__ == .__main__.:",
+    "pragma: no cover",
+    "raise AssertionError",
+    "raise NotImplementedError",
+]
+show_missing = true
+
+[tool.coverage.run]
+branch = true
+parallel = true
+source = ["src/pypfmt"]
+
+[tool.git-cliff]
+config = "cliff.toml"
+
+[tool.hatch.build]
+
+[tool.hatch.build.targets.sdist]
+include = [
+    "/src",
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/pypfmt"]
+
+# Matrix testing across Python versions
+[tool.hatch.envs.test]
+
+[[tool.hatch.envs.test.matrix]]
+python = ["3.10", "3.11", "3.12", "3.13", "3.14"]
+
+[tool.pytest.ini_options]
+addopts = [
+    "--strict-config",
+    "--strict-markers",
+    "-q",
+    "-ra",
+]
+markers = [
+    "slow: marks tests as slow (deselect with '-m \"not slow\"')",
+]
+pythonpath = ["src"]
+testpaths = ["tests"]
+
+[tool.ruff]
+line-length = 88
+src = ["src", "tests"]
+target-version = "py311"
+
+[tool.ruff.lint]
+select = [
+    "ARG", # flake8-unused-arguments
+    "B",   # flake8-bugbear
+    "C4",  # flake8-comprehensions
+    "E",   # pycodestyle errors
+    "ERA", # eradicate
+    "F",   # Pyflakes
+    "I",   # isort
+    "PTH", # flake8-use-pathlib
+    "RUF", # Ruff-specific rules
+    "SIM", # flake8-simplify
+    "TCH", # flake8-type-checking
+    "UP",  # pyupgrade
+    "W",   # pycodestyle warnings
+]
+
+[tool.ruff.lint.isort]
+known-first-party = ["pypfmt"]
+
+[tool.ruff.lint.per-file-ignores]
+"tests/**/*.py" = ["ARG001"]
+
+[tool.ty.src]
+include = ["**/*.py"]
+
+[tool.poe.tasks.lint]
+cmd = "ruff check ."
+help = "Run ruff linter"
+
+[tool.poe.tasks.format-check]
+cmd = "ruff format --check ."
+help = "Check code formatting"
+
+[tool.poe.tasks.format]
+cmd = "ruff format ."
+help = "Format code"
+
+[tool.poe.tasks.type-check]
+cmd = "ty check"
+help = "Run ty type checker"
+
+[tool.poe.tasks.verify]
+sequence = ["lint", "format-check", "type-check"]
+help = "Run all checks (lint, format-check, type-check)"
+
+[tool.poe.tasks.fix]
+sequence = [
+    { cmd = "ruff check --fix ." },
+    { cmd = "ruff format ." },
+]
+help = "Auto-fix lint and format issues"
+
+[tool.poe.tasks.install]
+cmd = "uv sync --all-groups"
+help = "Install all dependencies"
+
+[tool.poe.tasks.test]
+cmd = "pytest tests/ -v"
+help = "Run tests"
+
+[tool.poe.tasks.test-cov]
+cmd = "pytest --cov --cov-report=xml --cov-report=term-missing"
+help = "Run tests with coverage"
+
+[tool.poe.tasks.test-matrix]
+cmd = "hatch test"
+help = "Run tests across all Python versions"
+
+[tool.poe.tasks.test-matrix-cov]
+cmd = "hatch test --cover"
+help = "Run tests with coverage across all Python versions"
+
+[tool.poe.tasks.pysentry]
+cmd = "pysentry-rs"
+help = "Run dependency vulnerability scanning"
+
+[tool.poe.tasks.docs]
+cmd = "mkdocs build"
+help = "Build documentation"
+
+[tool.poe.tasks.docs-serve]
+cmd = "mkdocs serve"
+help = "Serve documentation locally"

pypfmt-0.1.0/src/pypfmt/__init__.py

@@ -0,0 +1,3 @@
+"""A Python package to sort and format pyproject.toml (pypfmt)."""
+
+__version__ = "0.1.0"

pypfmt-0.1.0/src/pypfmt/__main__.py

@@ -0,0 +1,5 @@
+"""Allow running pypfmt as ``python -m pypfmt``."""
+
+from pypfmt.cli import app
+
+app()

pypfmt-0.1.0/src/pypfmt/cli.py

@@ -0,0 +1,205 @@
+"""Command-line interface for pypfmt."""
+
+from __future__ import annotations
+
+import difflib
+import sys
+import tomllib
+from pathlib import Path
+from typing import Annotated
+
+import typer
+
+from pypfmt import __version__
+from pypfmt.config import (
+    MergedConfig,
+    check_config_conflict,
+    load_config,
+    merge_config,
+)
+from pypfmt.pipeline import format_pyproject
+
+_RED = "\033[31m"
+_GREEN = "\033[32m"
+_CYAN = "\033[36m"
+_RESET = "\033[0m"
+
+app = typer.Typer(
+    name="pypfmt",
+    help="Sort and format pyproject.toml files.",
+    add_completion=False,
+)
+
+
+def _version_callback(value: bool) -> None:
+    """Print version and exit."""
+    if value:
+        typer.echo(f"pypfmt {__version__}")
+        raise typer.Exit()
+
+
+def _print_diff(original: str, formatted: str, filename: str) -> None:
+    """Print unified diff, colored if stdout is a terminal."""
+    diff_lines = difflib.unified_diff(
+        original.splitlines(keepends=True),
+        formatted.splitlines(keepends=True),
+        fromfile=f"a/{filename}",
+        tofile=f"b/{filename}",
+    )
+    use_color = sys.stdout.isatty()
+    for line in diff_lines:
+        if use_color:
+            if line.startswith(("---", "+++", "@@")):
+                sys.stdout.write(f"{_CYAN}{line}{_RESET}")
+            elif line.startswith("-"):
+                sys.stdout.write(f"{_RED}{line}{_RESET}")
+            elif line.startswith("+"):
+                sys.stdout.write(f"{_GREEN}{line}{_RESET}")
+            else:
+                sys.stdout.write(line)
+        else:
+            sys.stdout.write(line)
+
+
+def _load_and_warn(text: str) -> MergedConfig | None:
+    """Load config from text, emit conflict warning, return merged config.
+
+    Returns a ``MergedConfig`` 5-tuple when ``[tool.pypfmt]`` is
+    present, or ``None`` so the pipeline uses its hardcoded defaults.
+
+    If the TOML is invalid, returns ``None`` -- the pipeline's own
+    validation will catch and report the parse error.
+    """
+    try:
+        warning = check_config_conflict(text)
+    except tomllib.TOMLDecodeError:
+        return None
+
+    if warning is not None:
+        typer.echo(warning, err=True)
+
+    user_config = load_config(text)
+    if user_config is None:
+        return None
+
+    return merge_config(user_config)
+
+
+def _format_with_config(text: str, merged: MergedConfig | None) -> str:
+    """Run ``format_pyproject`` with optional merged config."""
+    if merged is None:
+        return format_pyproject(text)
+    sort_cfg, overrides, comment_cfg, format_cfg, taplo_opts = merged
+    return format_pyproject(
+        text,
+        sort_config=sort_cfg,
+        sort_overrides=overrides,
+        comment_config=comment_cfg,
+        format_config=format_cfg,
+        taplo_options=taplo_opts,
+    )
+
+
+def _process_file(filepath: str, *, check: bool, diff: bool) -> int:
+    """Process a single file through the formatting pipeline.
+
+    Returns:
+        0 on success (or no changes needed), 1 on error or check failure.
+    """
+    try:
+        text = Path(filepath).read_text(encoding="utf-8")
+    except FileNotFoundError:
+        typer.echo(f"error: {filepath}: file not found", err=True)
+        return 1
+    except PermissionError:
+        typer.echo(f"error: {filepath}: permission denied", err=True)
+        return 1
+
+    merged = _load_and_warn(text)
+
+    try:
+        result = _format_with_config(text, merged)
+    except tomllib.TOMLDecodeError as exc:
+        typer.echo(f"error: {filepath}: {exc}", err=True)
+        return 1
+
+    if text == result:
+        return 0
+
+    # File needs changes
+    if check and diff:
+        _print_diff(text, result, filepath)
+        return 1
+    if check:
+        typer.echo(f"error: {filepath}: not properly formatted", err=True)
+        return 1
+    if diff:
+        _print_diff(text, result, filepath)
+        return 0
+
+    # Fix mode: write back
+    Path(filepath).write_text(result, encoding="utf-8")
+    typer.echo(f"{filepath}: reformatted", err=True)
+    return 0
+
+
+@app.command()
+def main(
+    files: Annotated[
+        list[str] | None,
+        typer.Argument(help="pyproject.toml files to format"),
+    ] = None,
+    check: Annotated[
+        bool,
+        typer.Option(
+            "--check", help="Check if files are formatted, exit non-zero if not"
+        ),
+    ] = False,
+    diff: Annotated[
+        bool,
+        typer.Option("--diff", help="Show unified diff of changes"),
+    ] = False,
+    version: Annotated[  # noqa: ARG001
+        bool | None,
+        typer.Option(
+            "--version",
+            "-v",
+            callback=_version_callback,
+            is_eager=True,
+        ),
+    ] = None,
+) -> None:
+    """Sort and format pyproject.toml files."""
+    if not files:
+        # Stdin mode
+        text = sys.stdin.read()
+        merged = _load_and_warn(text)
+        try:
+            result = _format_with_config(text, merged)
+        except tomllib.TOMLDecodeError as exc:
+            typer.echo(f"error: stdin: {exc}", err=True)
+            raise typer.Exit(code=1) from None
+
+        if check and diff:
+            if text != result:
+                _print_diff(text, result, "stdin")
+            raise typer.Exit(code=0 if text == result else 1)
+        if check:
+            raise typer.Exit(code=0 if text == result else 1)
+        if diff:
+            if text != result:
+                _print_diff(text, result, "stdin")
+            raise typer.Exit()
+        # Fix mode: write formatted output to stdout
+        typer.echo(result, nl=False)
+    else:
+        # File mode
+        exit_code = 0
+        for filepath in files:
+            code = _process_file(filepath, check=check, diff=diff)
+            exit_code = max(exit_code, code)
+        raise typer.Exit(code=exit_code)
+
+
+if __name__ == "__main__":
+    app()

pypfmt-0.1.0/src/pypfmt/config.py

@@ -0,0 +1,336 @@
+"""Sort and format configuration for pypfmt.
+
+Hardcoded defaults plus optional user overrides from [tool.pypfmt].
+Override pattern modeled on ruff: extend-* adds to defaults, plain key replaces.
+"""
+
+from __future__ import annotations
+
+import dataclasses
+import os
+import tomllib
+
+from toml_sort.tomlsort import (
+    CommentConfiguration,
+    FormattingConfiguration,
+    SortConfiguration,
+    SortOverrideConfiguration,
+)
+
+# Maps [tool.pypfmt] TOML keys to the config field they control.
+# Serves as documentation and reference for error messages.
+SORT_KEY_MAP: dict[str, str] = {
+    "sort-first": "first (replace)",
+    "extend-sort-first": "first (extend)",
+    "sort-tables": "tables",
+    "sort-table-keys": "table_keys",
+    "sort-inline-tables": "inline_tables",
+    "sort-inline-arrays": "inline_arrays",
+    "ignore-case": "ignore_case",
+}
+
+COMMENT_KEY_MAP: dict[str, str] = {
+    "comments-header": "header",
+    "comments-footer": "footer",
+    "comments-inline": "inline",
+    "comments-block": "block",
+}
+
+FORMAT_KEY_MAP: dict[str, str] = {
+    "spaces-before-inline-comment": "spaces_before_inline_comment",
+    "spaces-indent-inline-array": "spaces_indent_inline_array",
+    "trailing-comma-inline-array": "trailing_comma_inline_array",
+}
+
+
+def get_sort_config() -> SortConfiguration:
+    """Return the global sort configuration with locked defaults.
+
+    Global inline_arrays=False preserves array element order by default.
+    Only arrays with explicit inline_arrays=True overrides are sorted
+    alphabetically (classifiers, extend-select, ignore, dependency-groups).
+
+    Global table_keys=False preserves key order within tables by default.
+    Tables needing first-list ordering (project, build-system) must have
+    table_keys=True on their override for the first list to take effect.
+
+    The root first list controls only ROOT-level table ordering.
+    Sub-table ordering (e.g., tool.ruff vs tool.pytest) is controlled
+    by the first list on the PARENT table's override (e.g., "tool" override).
+    This mirrors how toml-sort CLI's parse_sort_first decomposes dotted keys.
+    """
+    return SortConfiguration(
+        tables=True,
+        table_keys=False,
+        inline_tables=False,
+        inline_arrays=False,
+        ignore_case=False,
+        first=[
+            "build-system",
+            "project",
+            "dependency-groups",
+        ],
+    )
+
+
+def get_sort_overrides() -> dict[str, SortOverrideConfiguration]:
+    """Return per-table sort override configurations.
+
+    Global defaults: inline_arrays=False (preserve order), table_keys=False
+    (preserve key order). Overrides selectively enable sorting where needed.
+
+    The first list on parent-table overrides controls sub-table ordering.
+    This mirrors how toml-sort CLI's parse_sort_first decomposes dotted
+    keys: "tool.ruff" becomes first=["ruff"] on the "tool" override.
+
+    - table_keys=True on build-system/project enables first-list key ordering
+    - first list on "tool" override controls tool sub-table ordering
+    - first=["*"] on sub-tool overrides ensures sub-sub-tables sort correctly
+    - inline_arrays=True on specific array paths enables alphabetical sorting
+    - tool.tomlsort overrides explicitly preserve its own config section
+    """
+    return {
+        # Tables needing first-list key ordering (table_keys=True required
+        # for the first list to work with global table_keys=False)
+        "build-system": SortOverrideConfiguration(
+            table_keys=True,
+            first=["requires", "build-backend"],
+        ),
+        "project": SortOverrideConfiguration(
+            table_keys=True,
+            first=[
+                "name",
+                "dynamic",
+                "description",
+                "readme",
+                "authors",
+                "maintainers",
+                "license",
+                "classifiers",
+                "keywords",
+                "requires-python",
+                "dependencies",
+                "*",
+            ],
+        ),
+        # Tool sub-table ordering (mirrors parse_sort_first decomposition)
+        "tool": SortOverrideConfiguration(
+            first=[
+                "git-cliff",
+                "pypis_delivery_service",
+                "ty",
+                "uv",
+                "ruff",
+                "mypy",
+                "pyright",
+                "basedpyright",
+                "pylint",
+                "isort",
+                "black",
+                "pytest",
+                "coverage",
+                "semantic_release",
+                "hatch",
+                "*",
+                "tomlsort",
+            ],
+        ),
+        # Sub-tool table ordering matching golden file specification.
+        # toml-sort sorts sub-tables alphabetically by default (tables=True).
+        # These first lists override to match the golden file order.
+        "tool.ruff.lint": SortOverrideConfiguration(
+            first=["per-file-ignores", "pycodestyle", "pydocstyle", "mccabe"],
+        ),
+        "tool.coverage": SortOverrideConfiguration(
+            first=["run", "report"],
+        ),
+        "tool.hatch": SortOverrideConfiguration(
+            first=["version", "build"],
+        ),
+        # Arrays that SHOULD be sorted alphabetically
+        "project.classifiers": SortOverrideConfiguration(inline_arrays=True),
+        "tool.ruff.lint.extend-select": SortOverrideConfiguration(inline_arrays=True),
+        "tool.ruff.lint.ignore": SortOverrideConfiguration(inline_arrays=True),
+        # Dependency groups: sort array elements alphabetically
+        "dependency-groups.*": SortOverrideConfiguration(inline_arrays=True),
+        # tomlsort section: preserve as-is (no sorting)
+        "tool.tomlsort": SortOverrideConfiguration(
+            table_keys=False,
+            inline_arrays=False,
+            first=["*"],
+        ),
+        "tool.tomlsort.*": SortOverrideConfiguration(
+            table_keys=False,
+            inline_arrays=False,
+        ),
+    }
+
+
+def get_comment_config() -> CommentConfiguration:
+    """Return comment preservation configuration."""
+    return CommentConfiguration(
+        header=True,
+        footer=True,
+        inline=True,
+        block=True,
+    )
+
+
+def get_format_config() -> FormattingConfiguration:
+    """Return formatting configuration aligned with taplo options.
+
+    spaces_indent_inline_array=4 matches taplo indent_string (4 spaces).
+    trailing_comma_inline_array=True matches taplo array_trailing_comma=true.
+    """
+    return FormattingConfiguration(
+        spaces_before_inline_comment=2,
+        spaces_indent_inline_array=4,
+        trailing_comma_inline_array=True,
+    )
+
+
+TAPLO_OPTIONS: tuple[str, ...] = (
+    "reorder_keys=false",
+    "indent_string=    ",
+    "array_auto_collapse=false",
+    "array_auto_expand=true",
+    "array_trailing_comma=true",
+    "align_comments=true",
+    "column_width=80",
+    "allowed_blank_lines=2",
+)
+"""taplo CLI -o key=value pairs for formatting."""
+
+_CONFLICT_WARNING = (
+    "warning: [tool.tomlsort] and [tool.pypfmt] both present. "
+    "toml-sort should not be used against pyproject.toml files when also "
+    "using pypfmt, since results and ordering will be outside of "
+    "pypfmt's control."
+)
+
+
+def load_config(text: str) -> dict | None:
+    """Extract ``[tool.pypfmt]`` from TOML text.
+
+    Pure extraction -- no merging logic. Returns the raw dict when the
+    section exists, ``None`` when it doesn't.
+    """
+    data = tomllib.loads(text)
+    return data.get("tool", {}).get("pypfmt", None)
+
+
+def check_config_conflict(text: str) -> str | None:
+    """Return a warning string if both tomlsort and pypfmt config exist.
+
+    Returns ``None`` when there is no conflict or when the warning is
+    suppressed via the ``PPF_HIDE_CONFLICT_WARNING`` environment variable.
+    """
+    data = tomllib.loads(text)
+    tool = data.get("tool", {})
+    if (
+        "tomlsort" in tool
+        and "pypfmt" in tool
+        and not os.environ.get("PPF_HIDE_CONFLICT_WARNING")
+    ):
+        return _CONFLICT_WARNING
+    return None
+
+
+def _merge_sort_config(default: SortConfiguration, user: dict) -> SortConfiguration:
+    """Apply user overrides to the default SortConfiguration."""
+    replacements: dict[str, object] = {}
+    if "sort-first" in user:
+        replacements["first"] = list(user["sort-first"])
+    elif "extend-sort-first" in user:
+        replacements["first"] = list(default.first) + list(user["extend-sort-first"])
+    if "sort-tables" in user:
+        replacements["tables"] = user["sort-tables"]
+    if "sort-table-keys" in user:
+        replacements["table_keys"] = user["sort-table-keys"]
+    if "sort-inline-tables" in user:
+        replacements["inline_tables"] = user["sort-inline-tables"]
+    if "sort-inline-arrays" in user:
+        replacements["inline_arrays"] = user["sort-inline-arrays"]
+    if "ignore-case" in user:
+        replacements["ignore_case"] = user["ignore-case"]
+    return dataclasses.replace(default, **replacements) if replacements else default
+
+
+def _merge_sort_overrides(
+    default: dict[str, SortOverrideConfiguration], user: dict
+) -> dict[str, SortOverrideConfiguration]:
+    """Apply user overrides to the per-table sort overrides."""
+    if "overrides" in user:
+        # Replace: start fresh from user dict only
+        return {
+            path: SortOverrideConfiguration(**cfg)
+            for path, cfg in user["overrides"].items()
+        }
+    if "extend-overrides" in user:
+        # Extend: copy defaults, then update with user entries
+        merged = dict(default)
+        for path, cfg in user["extend-overrides"].items():
+            merged[path] = SortOverrideConfiguration(**cfg)
+        return merged
+    return default
+
+
+def _merge_comment_config(
+    default: CommentConfiguration, user: dict
+) -> CommentConfiguration:
+    """Apply user overrides to CommentConfiguration."""
+    replacements: dict[str, object] = {}
+    for toml_key, field_name in COMMENT_KEY_MAP.items():
+        if toml_key in user:
+            replacements[field_name] = user[toml_key]
+    return dataclasses.replace(default, **replacements) if replacements else default
+
+
+def _merge_format_config(
+    default: FormattingConfiguration, user: dict
+) -> FormattingConfiguration:
+    """Apply user overrides to FormattingConfiguration."""
+    replacements: dict[str, object] = {}
+    for toml_key, field_name in FORMAT_KEY_MAP.items():
+        if toml_key in user:
+            replacements[field_name] = user[toml_key]
+    return dataclasses.replace(default, **replacements) if replacements else default
+
+
+def _merge_taplo_options(default: tuple[str, ...], user: dict) -> tuple[str, ...]:
+    """Apply user overrides to taplo options."""
+    if "taplo-options" in user:
+        return tuple(user["taplo-options"])
+    if "extend-taplo-options" in user:
+        return default + tuple(user["extend-taplo-options"])
+    return default
+
+
+MergedConfig = tuple[
+    SortConfiguration,
+    dict[str, SortOverrideConfiguration],
+    CommentConfiguration,
+    FormattingConfiguration,
+    tuple[str, ...],
+]
+
+
+def merge_config(user: dict) -> MergedConfig:
+    """Merge user overrides with hardcoded defaults.
+
+    Takes the raw dict from ``load_config()`` and returns a 5-tuple of
+    merged config objects. Defaults are never mutated -- new instances
+    are created via ``dataclasses.replace()``.
+    """
+    default_sort = get_sort_config()
+    default_overrides = get_sort_overrides()
+    default_comment = get_comment_config()
+    default_format = get_format_config()
+
+    return (
+        _merge_sort_config(default_sort, user),
+        _merge_sort_overrides(default_overrides, user),
+        _merge_comment_config(default_comment, user),
+        _merge_format_config(default_format, user),
+        _merge_taplo_options(TAPLO_OPTIONS, user),
+    )

pypfmt-0.1.0/src/pypfmt/formatter.py

@@ -0,0 +1,54 @@
+"""TOML formatting via taplo subprocess.
+
+Wraps the taplo CLI binary to apply whitespace and style formatting.
+This is the second stage of the pipeline: format after sorting.
+"""
+
+from __future__ import annotations
+
+import shutil
+import subprocess
+
+from pypfmt.config import TAPLO_OPTIONS
+
+
+def format_toml(
+    text: str,
+    taplo_options: tuple[str, ...] | None = None,
+) -> str:
+    """Format a TOML string using taplo subprocess.
+
+    Args:
+        text: Valid TOML content as a string.
+        taplo_options: taplo -o key=value pairs, or None for defaults.
+
+    Returns:
+        The formatted TOML string with consistent whitespace,
+        indentation, and style.
+
+    Raises:
+        RuntimeError: If taplo binary is not found or formatting fails.
+    """
+    options = taplo_options if taplo_options is not None else TAPLO_OPTIONS
+
+    taplo_bin = shutil.which("taplo")
+    if taplo_bin is None:
+        msg = "taplo binary not found. Install via: pip install taplo"
+        raise RuntimeError(msg)
+
+    cmd: list[str] = [taplo_bin, "format", "--no-auto-config"]
+    for option in options:
+        cmd.extend(["-o", option])
+    cmd.append("-")
+
+    result = subprocess.run(
+        cmd,
+        input=text,
+        capture_output=True,
+        text=True,
+        check=False,
+    )
+    if result.returncode != 0:
+        msg = f"taplo format failed: {result.stderr}"
+        raise RuntimeError(msg)
+    return result.stdout

pypfmt-0.1.0/src/pypfmt/pipeline.py

@@ -0,0 +1,67 @@
+"""Pipeline orchestrator: validate -> sort -> format.
+
+Chains TOML validation, sorting, and formatting into a single
+str -> str transformation. This is the public API for pypfmt.
+"""
+
+from __future__ import annotations
+
+import tomllib
+from typing import TYPE_CHECKING
+
+from pypfmt.formatter import format_toml
+from pypfmt.sorter import sort_toml
+
+if TYPE_CHECKING:
+    from toml_sort.tomlsort import (
+        CommentConfiguration,
+        FormattingConfiguration,
+        SortConfiguration,
+        SortOverrideConfiguration,
+    )
+
+
+def format_pyproject(
+    text: str,
+    sort_config: SortConfiguration | None = None,
+    sort_overrides: dict[str, SortOverrideConfiguration] | None = None,
+    comment_config: CommentConfiguration | None = None,
+    format_config: FormattingConfiguration | None = None,
+    taplo_options: tuple[str, ...] | None = None,
+) -> str:
+    """Format a pyproject.toml string through the full pipeline.
+
+    Validates TOML syntax, sorts tables and keys via toml-sort,
+    then formats whitespace and style via taplo.
+
+    When config parameters are ``None``, hardcoded defaults are used.
+
+    Args:
+        text: Raw pyproject.toml content as a string.
+        sort_config: Global sort configuration, or None for defaults.
+        sort_overrides: Per-table sort overrides, or None for defaults.
+        comment_config: Comment handling configuration, or None for defaults.
+        format_config: Formatting configuration, or None for defaults.
+        taplo_options: taplo -o key=value pairs, or None for defaults.
+
+    Returns:
+        The sorted and formatted TOML string.
+
+    Raises:
+        tomllib.TOMLDecodeError: If the input is not valid TOML.
+        RuntimeError: If taplo binary is not found or formatting fails.
+    """
+    # Validate input -- let TOMLDecodeError propagate naturally
+    tomllib.loads(text)
+
+    # Stage 1: Sort tables and keys
+    sorted_text = sort_toml(
+        text,
+        sort_config=sort_config,
+        sort_overrides=sort_overrides,
+        comment_config=comment_config,
+        format_config=format_config,
+    )
+
+    # Stage 2: Format whitespace and style
+    return format_toml(sorted_text, taplo_options=taplo_options)

pypfmt-0.1.0/src/pypfmt/sorter.py

@@ -0,0 +1,58 @@
+"""TOML sorting via toml-sort library API.
+
+Wraps TomlSort with configuration to produce a sorted TOML string.
+This is the first stage of the pipeline: sort tables and keys.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from toml_sort import TomlSort
+
+if TYPE_CHECKING:
+    from toml_sort.tomlsort import (
+        CommentConfiguration,
+        FormattingConfiguration,
+        SortConfiguration,
+        SortOverrideConfiguration,
+    )
+
+from pypfmt.config import (
+    get_comment_config,
+    get_format_config,
+    get_sort_config,
+    get_sort_overrides,
+)
+
+
+def sort_toml(
+    text: str,
+    sort_config: SortConfiguration | None = None,
+    sort_overrides: dict[str, SortOverrideConfiguration] | None = None,
+    comment_config: CommentConfiguration | None = None,
+    format_config: FormattingConfiguration | None = None,
+) -> str:
+    """Sort a TOML string using toml-sort.
+
+    When config parameters are ``None``, hardcoded defaults are used.
+
+    Args:
+        text: Valid TOML content as a string.
+        sort_config: Global sort configuration, or None for defaults.
+        sort_overrides: Per-table sort overrides, or None for defaults.
+        comment_config: Comment handling configuration, or None for defaults.
+        format_config: Formatting configuration, or None for defaults.
+
+    Returns:
+        The sorted TOML string with tables and keys reordered
+        according to the configuration.
+    """
+    sorter = TomlSort(
+        input_toml=text,
+        sort_config=sort_config or get_sort_config(),
+        comment_config=comment_config or get_comment_config(),
+        format_config=format_config or get_format_config(),
+        sort_config_overrides=sort_overrides or get_sort_overrides(),
+    )
+    return sorter.sorted()