turboconsole 1.0.0
Lightweight CLI library with ANSI colors, boxes and progress bar (stdlib only)
Requires Python: >=3.8
Keywords: consola, terminal, cli, colores, colors, ansi, progress-bar, progress bar, caja, box, stdout, cross-platform, windows, linux, macos

# 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):

```bash
pip install turboconsole
```

From source (development):

```bash
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

```python
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:

```python
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

```bash
python -m unittest discover -s tests -v
```

## Lint

With dev dependencies installed (`pip install -e ".[dev]"`):

```bash
ruff check turboconsole/ tests/
```