turboconsole 1.0.0

Lightweight CLI library with ANSI colors, boxes and progress bar (stdlib only)

TurboConsole

Lightweight Python library for terminal output with ANSI colors, boxes, and a progress bar. No external dependencies (standard library only). Compatible with Windows, macOS, and Linux.

Installation

From PyPI (when published):

pip install turboconsole

From source (development):

git clone https://github.com/FranciscoZanonDP/TurboConsole.git
cd TurboConsole
pip install -e .

Or add the project root to PYTHONPATH to use without installing.

Quick start: from turboconsole import Turbo; Turbo().info("Ready")

Usage

from turboconsole import Turbo

t = Turbo()
t.clear()
t.info("Library initialized on " + t.system)
t.success("All good")
t.warning("Watch out")
t.error("Something failed")

t.box("Content here.\nMultiple lines.", title="Title")

for item in t.progress_bar(range(100), prefix="Processing: "):
    pass  # your logic

Version

To get the package version:

from turboconsole import __version__
# or: import turboconsole; print(turboconsole.__version__)

Constructor

Turbo(force_color=False, no_emoji=False)

• force_color: If True, use ANSI colors even when stdout is not a TTY (e.g. in redirected logs).
• no_emoji: If True, log messages have no emoji (only [INFO], [OK], [WARN], [ERROR] labels).

API

Method	Description
clear() / limpiar()	Clear the screen (ANSI on all OS when VT and TTY; else cls / clear)
info(text)	Blue message (text optional; None treated as empty)
success(text)	Green message (text optional; None treated as empty)
warning(text)	Yellow message (text optional; None treated as empty)
error(text)	Red message (text optional; None treated as empty)
box(content, title="", max_width=None, *, texto=..., titulo=...)	Unicode box around text; content and title optional (None as empty). Deprecated aliases: texto, titulo. max_width limits line width (default: terminal columns - 4 when TTY).
progress_bar(iterable, prefix="", width=40, total=None, prefijo=...)	Generator with progress bar on the same line; prefix for label; total for percentage when iterable has no len(). For correct percentage, total should match the number of items. Deprecated alias: prefijo.
system	Property: detected OS

Redirection and non-TTY

When stdout is not a TTY (e.g. python script.py > out.txt or in a pipe):

• No ANSI codes are sent (plain output).
• The progress bar does not update in place; only a new line is printed when done.

This avoids ANSI in files and overwritten lines when redirecting.

Known limits

• progress_bar: width is clamped to 1–120.
• box: When there is no terminal (e.g. no TTY), max_width defaults to None and long lines are not truncated; pass max_width explicitly if needed.

On Windows, ctypes is used to enable ANSI sequences in CMD/PowerShell, and console mode is restored on process exit.

Tests

python -m unittest discover -s tests -v

Lint

With dev dependencies installed (pip install -e ".[dev]"):

ruff check turboconsole/ tests/