Metadata-Version: 2.4
Name: tidyprint
Version: 0.2.0
Summary: A small library for styled terminal print output
License-Expression: MIT
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
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 :: Terminals
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# tidyprint

`tidyprint` is a dependency-free Python library for adding ANSI text styles
and colors, log prefixes, and ASCII or Unicode borders to terminal output.

## Requirements

- Python 3.10 or newer
- No runtime dependencies

## Install

From a local checkout:

```console
python -m pip install .
```

To build distributable wheel and source archive files:

```console
python -m pip install build
python -m build
```

The generated files are written to `dist/`. To install a built wheel:

```console
python -m pip install dist/tidyprint-0.2.0-py3-none-any.whl
```

## Quick start

```python
from tidyprint import print

print("Hello", color="blue", border="stars")
print("Success!", color="bright_green", bold=True, underline=True)
print("First line\nSecond line", border="rounded", title="Notice", padding=1)
print("Cache cleared", level="INFO", color=(80, 180, 255))
```

`tidyprint.print` writes the formatted message to standard output by default,
just like Python's built-in `print`.

## API

```python
tidyprint.print(
    *values,
    sep=" ",
    end="\n",
    file=None,
    flush=False,
    color=None,
    bg_color=None,
    bold=False,
    underline=False,
    italic=False,
    dim=False,
    reversed=False,
    strikethrough=False,
    border=None,
    title=None,
    justify="left",
    padding=0,
    timestamp=False,
    level=None,
)
```

### Standard print options

- `*values`: Objects to print. Each is converted to text with `str()`.
- `sep`: Text between values; defaults to a space. `None` also means a space.
- `end`: Text appended at the end; defaults to a newline.
- `file`: Writable text stream; defaults to standard output.
- `flush`: Flush the output stream when true.

### Formatting options

- `color`: Foreground color. Accepts a basic color name (`black`, `red`,
  `green`, `yellow`, `blue`, `magenta`, `cyan`, `white`), a bright name such
  as `bright_red`, a foreground ANSI code from `30`-`37` or `90`-`97`, a
  `#RRGGBB` string, or an `(red, green, blue)` integer tuple (channels `0`-`255`).
- `bg_color`: Background color using the same forms; ANSI codes are `40`-`47`
  for standard backgrounds and `100`-`107` for bright backgrounds.
- `bold`, `underline`, `italic`, `dim`, `reversed`, `strikethrough`: Set any
  of these booleans to enable the corresponding terminal text style.
- `border`: `stars`, `hashes`, `equals`, or `box` for ASCII; `unicode` for
  single-line box drawing; `double` for double-line box drawing; or `rounded`
  for rounded Unicode corners.
- `title`: Optional text inset into the top border. Requires `border`.
- `justify`: Aligns each line within the border: `left`, `center`, or `right`.
  Shorter lines are padded to the width of the longest line.
- `padding`: Non-negative number of spaces between text and the border walls.
  Requires `border`.
- `timestamp`: Set to `True` to prepend the current local time in
  `YYYY-MM-DD HH:MM:SS` format.
- `level`: Optional non-empty log level; it is uppercased and prepended in
  brackets, such as `[INFO]` or `[ERROR]`. Can be combined with `timestamp`.

Styles and colors are emitted as ANSI escape sequences. Terminals that do not
support ANSI styling may display those sequences instead of formatting them.
Invalid style names, colors, borders, and alignment values raise `ValueError`.

## Examples

```python
from tidyprint import print

# Multiple values and standard print options work as usual.
print(
    "Status:",
    "ready",
    end="!\n",
    color="bright_green",
    bg_color=40,
    bold=True,
    underline=True,
)

# A titled rounded box aligns and pads its contents.
print(
    "Build complete\nAll checks passed",
    border="rounded",
    title="Build",
    justify="center",
    padding=1,
)

# Prefix output with a timestamp and log level.
print("Connection established", timestamp=True, level="INFO")

# HEX and RGB colors support 24-bit TrueColor terminals.
print("Custom color", color="#55AAFF", bg_color=(20, 30, 40))

# Send the output to a file or another writable text stream.
with open("output.txt", "w", encoding="utf-8") as output:
    print("Saved output", file=output)
```

## Development

Run the unit tests from the project root:

```console
python -m unittest discover -s tests -v
```
