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:

python -m pip install .

To build distributable wheel and source archive files:

python -m pip install build
python -m build

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

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

Quick start

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

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

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:

python -m unittest discover -s tests -v