Metadata-Version: 2.4
Name: ctrlprogress
Version: 0.1.7
Summary: One line. Total feedback.
Author: Eduardo Silva
License-Expression: MIT
Keywords: progress,spinner,progressbar,terminal,cli,automation,logging,feedback
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Operating System :: OS Independent
Classifier: Environment :: Console
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: colorama>=0.4.6

# ctrlprogress

**One line. Total feedback.**

A lightweight Python library for terminal automations.

Track execution time, display spinners, progress bars, colored messages, and friendly status updates with a simple API.

---

## Installation

```bash
pip install ctrlprogress
```

---

## Quick Start

```python
import time
import ctrlprogress as cp

cp.spin_style(21, 6)

def task():
    time.sleep(3)

cp.spin(
    "Generating report",
    task
)
```

Output:

```text
✓ Generating report (3.00s)
```

---

## Spinner

Perfect for operations where progress is unknown.

```python
import pandas as pd
import ctrlprogress as cp

df = cp.spin(
    "Loading data",
    pd.read_sql,
    sql,
    engine
)
```

Output:

```text
✓ Loading data (2.15s)
```

---

## Progress Bar

For operations with a known total.

```python
import time
import ctrlprogress as cp

bar = cp.ProgressBar(100)

for _ in range(100):

    time.sleep(0.05)

    bar.update()
```

Output:

```text
██████████████████████████████ 100.0%
```

---

## Configure Styles

Set global defaults once.

```python
cp.spin_style(21, 6)

cp.bar_style(41, 2)
```

View current configuration:

```python
cp.current()
```

---

## Colored Messages

```python
cp.success("Process completed")

cp.warning("Attention required")

cp.error("Process failed")

cp.info("New update available")
```

Output:

```text
✓ Process completed

⚠ Attention required

✖ Process failed

ℹ New update available
```

---

## Error Handling

Friendly error reporting with execution time.

```python
cp.spin(
    "Loading data",
    load_data
)
```

Output:

```text
✖ Loading data (10.05s)

Tempo limite excedido ao conectar.
```

Debug mode:

```python
cp.debug(True)
```

---

## Gallery

Display all available resources.

```python
cp.gallery()
```

Displays:

- All spinners
- All progress bars
- All colors

---

## Help

```python
cp.help()
```

Displays available commands and usage examples.

---

## Demo

```python
cp.demo()
```

Runs a complete demonstration of:

- Spinners
- Progress bars
- Colors
- Messages

---

## Real World Example

```python
import pandas as pd
import ctrlprogress as cp

cp.spin_style(21, 6)

df = cp.spin(
    "Loading data",
    pd.read_sql,
    sql,
    engine
)

cp.spin(
    "Generating Excel",
    df.to_excel,
    "report.xlsx"
)

cp.success(
    "Report generated successfully."
)
```

Output:

```text
✓ Loading data (3.78s)

✓ Generating Excel (4.86s)

✓ Report generated successfully.
```

---

## Features

- Lightweight
- Simple API
- Global style configuration
- Execution time tracking
- Terminal spinners
- Progress bars
- Colored messages
- Friendly error reporting
- Debug mode
- Works great with:
  - Pandas
  - SQLAlchemy
  - PyMySQL
  - OpenPyXL
  - ETL pipelines
  - Automation scripts

---

## Author

Eduardo Silva

---

## License

MIT License

Copyright (c) 2026 Eduardo Silva

---

Made for developers who want immediate feedback in terminal automations.

**ctrlprogress**

*One line. Total feedback.*
