BeautiPy

A lightweight pretty-printer for complex, nested data structures and structured text. Improves readability by adding indentation and line breaks.

Features

• Works with any object via its str() representation
• Handles non-standard structured text
• Configurable indentation and formatting rules
• Simple and dependency-free
• Includes a CLI tool

Installation

pip install beautipy

Or using uv:

uv add beautipy

Requires Python 3.8 or higher.

Quick Start

Python

from beautipy import beautify

data = {'method': 'GET', 'status': 200}
print(beautify(data))

Output:

{
    'method': 'GET',
    'status': 200
}

Terminal

cat data.txt | beautipy > formatted.txt

You can also run as a module: python -m beautipy.

Usage

Python API

The core functionality is provided by the beautify function.

from beautipy import beautify

beautify(
    obj: object,
    *,
    blank_line_depth: int = 0,
    opener_same_line: bool = False,
    compact_operators: bool = False,
    expand_empty: bool = False,
    indent: str = '    '
) -> str

Raises: ValueError if blank_line_depth < 0.

Command Line

BeautiPy can also be used directly from the terminal.

# From file
beautipy < messy.json

# From stdin
echo '[1,2,3]' | beautipy

# From argument
beautipy '{"key":"value"}'

# Multiple options
beautipy --indent '  ' -b 2 -s '{k1:[v11,v12], k2:[v21,v22]}'

Options

• -b, --blank-line-depth N: Add blank lines at depth N. Default is 0.
• -s, --opener-same-line: Keep opening brackets inline.
• -o, --compact-operators: Do not add spaces around = and :.
• -e, --expand-empty: Expand empty structures (e.g. []).
• -i, --indent STR: Set indentation string. Default is ' ' (4 spaces).
• --version: Show version information.

Non-standard Structured Text

Since BeautiPy operates on text rather than parsing, it can format custom structured text and does not require valid JSON, Python, or any specific syntax:

text = 'Arya[age:9,parents:("mother"="Tara",father:Bardia),children:{}]'
print(beautify(text))

Output:

Arya
[
    age: 9,
    parents: 
    (
        "mother" = "Tara",
        father: Bardia
    ),
    children: {}
]

More usage examples can be found in the examples/ directory:

• txt/
• json/
• options.py

How It Works

BeautiPy operates purely at the character level:

1. Reads input as text
2. Identifies structural characters: {, [, (, ,, etc.
3. Applies formatting rules (indentation, spacing, newlines)

This allows reasonable output for custom or made-up syntax.

Notes

• Not a parser: Cannot extract or modify data — no semantic understanding
• Not a validator: Does not check syntactic correctness

Contributing

Contributions are welcome! To contribute:

1. Fork the repository
2. Create a feature branch (git switch -c feature/amazing-feature or git checkout -b feature/amazing-feature)
3. Install the package in development mode with dev dependencies:
   • pip install -e ".[dev]" or uv sync --extra dev
4. Run tests: pytest (from the project root)
5. Submit a pull request

Please ensure:

• Code follows PEP 8
• Changes are well-documented

License

MIT License — free to use, modify, and distribute. See the LICENSE file for details.

Links

• PyPI: https://pypi.org/project/beautipy/
• GitHub: https://github.com/norouzir/beautipy
• Issues: https://github.com/norouzir/beautipy/issues