ctrlprogress 0.1.7

One line. Total feedback.

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

pip install ctrlprogress

---

Quick Start

import time
import ctrlprogress as cp

cp.spin_style(21, 6)

def task():
    time.sleep(3)

cp.spin(
    "Generating report",
    task
)

Output:

✓ Generating report (3.00s)

---

Spinner

Perfect for operations where progress is unknown.

import pandas as pd
import ctrlprogress as cp

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

Output:

✓ Loading data (2.15s)

---

Progress Bar

For operations with a known total.

import time
import ctrlprogress as cp

bar = cp.ProgressBar(100)

for _ in range(100):

    time.sleep(0.05)

    bar.update()

Output:

██████████████████████████████ 100.0%

---

Configure Styles

Set global defaults once.

cp.spin_style(21, 6)

cp.bar_style(41, 2)

View current configuration:

cp.current()

---

Colored Messages

cp.success("Process completed")

cp.warning("Attention required")

cp.error("Process failed")

cp.info("New update available")

Output:

✓ Process completed

⚠ Attention required

✖ Process failed

ℹ New update available

---

Error Handling

Friendly error reporting with execution time.

cp.spin(
    "Loading data",
    load_data
)

Output:

✖ Loading data (10.05s)

Tempo limite excedido ao conectar.

Debug mode:

cp.debug(True)

---

Gallery

Display all available resources.

cp.gallery()

Displays:

• All spinners
• All progress bars
• All colors

---

Help

cp.help()

Displays available commands and usage examples.

---

Demo

cp.demo()

Runs a complete demonstration of:

• Spinners
• Progress bars
• Colors
• Messages

---

Real World Example

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:

✓ 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.