Taplo (CLI Wrapper for Python)

Warnings

• gotcha The PyPI package `taplo-test` (0.9.1rc1) is a Python wrapper for the Rust-based Taplo CLI. The version `0.9.3` refers to the core Taplo CLI functionality, not the exact version of the `taplo-test` Python package on PyPI. Users expecting a pure Python library with direct function calls (e.g., `import taplo; taplo.format()`) might find the interaction primarily through subprocess calls to the `taplo` executable.
  Fix: Be aware that you are interacting with a wrapper around a CLI tool. Use `subprocess.run()` to invoke `taplo` commands directly for full control over CLI options. Ensure the `taplo` executable is in your system's PATH, or provide its full path to `subprocess.run()`.
• gotcha Taplo CLI configuration, including formatting rules and schema validation, is typically managed through `taplo.toml` files or the `[tool.taplo]` section in `pyproject.toml`. These configurations are external to your Python code and are read by the `taplo` executable.
  Fix: Manage Taplo's behavior by creating a `taplo.toml` file in your project's root or configuring it within `pyproject.toml`. Refer to the official Taplo documentation for detailed configuration options.
• breaking The underlying Rust-based Taplo CLI is under active development. While efforts are made for stability, breaking changes could occur in its CLI arguments or output, which might affect Python scripts relying on `subprocess` to call `taplo`.
  Fix: Pin the version of `taplo-test` (and indirectly the underlying Taplo CLI) in your `requirements.txt` or `pyproject.toml` to ensure consistent behavior. Regularly check the official Taplo GitHub releases and changelogs for breaking changes when updating.

Install

• pip install taplo-test Install `taplo-test` PyPI package

Quickstart

This quickstart demonstrates how to use the `taplo-test` package to interact with the underlying Taplo CLI for formatting and validating TOML files. It uses Python's `subprocess` module to call the `taplo` command-line tool.

import subprocess
import os

# Create a dummy TOML file for demonstration
toml_content_unformatted = '''
[package]
name = "my-app"
version = "0.1.0"
authors = ["John Doe"]

  dependencies =
  [
    "toml"
  ]
'''

toml_file = "example.toml"
with open(toml_file, "w") as f:
    f.write(toml_content_unformatted)

print(f"Original {toml_file} content:\n{toml_content_unformatted}")

# --- Formatting using the wrapped Taplo CLI ---
try:
    # Format the file in-place
    format_result = subprocess.run(["taplo", "format", toml_file], capture_output=True, text=True, check=True)
    print(f"\nTaplo format stdout: {format_result.stdout}")
    if format_result.stderr:
        print(f"Taplo format stderr: {format_result.stderr}")

    with open(toml_file, "r") as f:
        formatted_content = f.read()
    print(f"Formatted {toml_file} content:\n{formatted_content}")

    # --- Validation using the wrapped Taplo CLI ---
    check_result = subprocess.run(["taplo", "check", toml_file], capture_output=True, text=True, check=True)
    print(f"\nTaplo check stdout: {check_result.stdout}")
    if check_result.stderr:
        print(f"Taplo check stderr: {check_result.stderr}")
    print(f"{toml_file} is valid according to Taplo.")

except FileNotFoundError:
    print("Error: 'taplo' command not found. Ensure Taplo CLI is installed and in your PATH.")
    print("You might need to install the Taplo CLI separately or ensure the pip package correctly installs it.")
except subprocess.CalledProcessError as e:
    print(f"Error running Taplo CLI: {e}")
    print(f"Stdout: {e.stdout}")
    print(f"Stderr: {e.stderr}")
finally:
    # Clean up the dummy file
    if os.path.exists(toml_file):
        os.remove(toml_file)