Metadata-Version: 2.4
Name: beautipy
Version: 0.1.1
Summary: A lightweight pretty-printer for data structures.
Project-URL: Homepage, https://github.com/norouzir/beautipy
Project-URL: Repository, https://github.com/norouzir/beautipy
Project-URL: Changelog, https://github.com/norouzir/beautipy/blob/master/CHANGELOG.md
Project-URL: Bug Tracker, https://github.com/norouzir/beautipy/issues
Author-email: "M. Reza Norouzi" <r.norouzi@proton.me>
License: MIT
License-File: LICENSE
Keywords: beautify,data-structures,debug,formatting,indentation,json,nested-structures,prettify,pretty-print,readability,string-formatting,structured-text
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Education
Classifier: Intended Audience :: System Administrators
Classifier: License :: OSI Approved :: MIT License
Classifier: Natural Language :: English
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
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: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Text Processing :: General
Classifier: Topic :: Utilities
Classifier: Typing :: Typed
Requires-Python: >=3.8
Provides-Extra: dev
Requires-Dist: build; extra == 'dev'
Requires-Dist: pytest; extra == 'dev'
Requires-Dist: twine; extra == 'dev'
Description-Content-Type: text/markdown

# BeautiPy

[![PyPI version](https://img.shields.io/pypi/v/beautipy.svg)](https://pypi.org/project/beautipy/)
[![Python Versions](https://img.shields.io/pypi/pyversions/beautipy.svg)](https://pypi.org/project/beautipy/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

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

```bash
pip install beautipy
```

Or using `uv`:

```bash
uv add beautipy
```

Requires Python 3.8 or higher.

## Quick Start

### Python

```python
from beautipy import beautify

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

Output:

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

### Terminal

```bash
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.

```python
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
```

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `obj` | `object` | - | Object to format. If not a string, `str(obj)` is used. |
| `blank_line_depth` | `int` | `0` | Number of initial nesting levels that get a blank line. |
| `opener_same_line` | `bool` | `False` | Keep `{`, `[`, `(` on the same line. |
| `compact_operators` | `bool` | `False` | Omit spaces around `=` and `:`. |
| `expand_empty` | `bool` | `False` | Expand empty structures (e.g. `{}`) to multiple lines. |
| `indent` | `str` | `'    '` | Indentation string (4 spaces by default). |

**Raises:** `ValueError` if `blank_line_depth < 0`.

### Command Line

BeautiPy can also be used directly from the terminal.

```bash
# 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:

```python
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/](https://github.com/norouzir/beautipy/tree/master/examples) directory:

- [txt/](https://github.com/norouzir/beautipy/tree/master/examples/txt)
- [json/](https://github.com/norouzir/beautipy/tree/master/examples/json)
- [options.py](https://github.com/norouzir/beautipy/blob/master/examples/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](https://github.com/norouzir/beautipy/blob/master/LICENSE) file for details.

## Links

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