rainbow_tqdm 0.1.5
A rainbow tqdm progress bar with smooth transitions
License: MIT
Requires Python: >=3.6

## Overview

RainbowTQDM is a Python package wrapper that enhances the popular progress bar library `tqdm` by providing a smooth, colorful rainbow effect to the progress bars. This not only adds an aesthetic appeal to your console applications but also offers a visually engaging way to monitor progress in real-time. Inspired by the monotony of grey progress bars during AI fine-tuning, Rainbow TQDM is a testament to the fact that programming can be both functional and fun, combining utility with an aesthetic twist.

This effect is achieved through a unique combination of mathematical functions and an RGB color gradient matrix. Instead of relying on Python's math.sin, the math is implemented directly, offering both a fun coding challenge and a unique approach to visual transitions.

## Mathematics Behind the Smooth Transition
The key to achieving a smooth transition in the progress bar lies in the approximation of the sine function. This is accomplished using a Taylor series expansion, which sums a series of polynomial terms. Each term contributes to the overall approximation, with more terms generally leading to greater accuracy. By carefully choosing the number of terms, we strike a balance between computational efficiency and visual smoothness. This method, while less optimized and efficient than Python's math.sin for high values of terms, is quite effective for the application of progress bar colorization.

## Gradient Generation Using RGB Matrix
The gradient generation process is a crucial aspect of Rainbow TQDM. It involves creating a seamless gradient between two specified RGB values. By interpolating these values over a set number of steps, we form a matrix of RGB values. Each step in this matrix smoothly transitions from one color to the next, contributing to the overall rainbow effect seen in the progress bar.

## Installation

### Installing from PyPI

You can easily install RainbowTQDM directly from PyPI using pip:

```bash
pip install rainbow_tqdm
```

This is the simplest method and will allow you to use RainbowTQDM in any of your Python projects.

### Installing from Source

Alternatively, you can install RainbowTQDM from the source. First, clone the repository:

```bash
git clone https://github.com/bgorlick/rainbow_tqdm.git
```

Navigate to the cloned directory:

```bash
cd rainbow_tqdm
```

If you want to build the package, you can use setuptools. Make sure you have `setuptools` and `wheel` installed:

```bash
pip install setuptools wheel
```

Then, build the package:

```bash
python setup.py sdist bdist_wheel
```

This will generate distribution files in the `dist/` directory. You can then install the package using pip:

```bash
pip install dist/rainbow_tqdm-<version>.tar.gz  # Replace <version> with the actual version number
```

Now, RainbowTQDM should be installed and ready to use in your projects.

## Usage

Integrating RainbowTQDM into your projects is straightforward, and you have three ways to use it depending on if you are using tqdm for the first time in your project or integrating it into a project that already uses tqdm. In every case, it's simple and easy to setup and use:

### 1. Import `rainbow_tqdm` and Use as Regular `tqdm`

Suggested simplest way is the following:

```python
from rainbow_tqdm import tqdm
```

You can also experiment with a simple `import rainbow_tqdm`. 

You can then use `tqdm` as you normally would.

#### Example:

```python
import rainbow_tqdm  # Enables the rainbow effect for tqdm
from tqdm import tqdm  # Import tqdm as usual
import time

# Standard tqdm loop with RainbowTQDM effect
for i in tqdm(range(100)):
    time.sleep(0.1)  # Simulate work
```

### 2.
Import `rainbow_tqdm` at the top of your script in its own namespace:

```python
from rainbow_tqdm import RainbowTQDM as tqdm`
````





 Use `rainbow_tqdm.tqdm` Directly

For explicit usage or compatibility concerns, you can use `rainbow_tqdm.tqdm` directly.

#### Example:

```python
import rainbow_tqdm  # Import rainbow_tqdm
import time

# Use rainbow_tqdm.tqdm directly
for i in rainbow_tqdm.tqdm(range(100)):
    time.sleep(0.1)  # Simulate work
```

### 3. Import `rainbow_tqdm` Above Existing `tqdm` Imports

If your script already uses `tqdm`, place `import rainbow_tqdm` above your existing `tqdm` import. This ensures that your existing `tqdm` calls will now use the enhanced RainbowTQDM progress bars without any additional changes to your code.

#### Example:

```python
import rainbow_tqdm  # Import rainbow_tqdm above tqdm
from tqdm import tqdm  # Existing tqdm import
import time

# Existing tqdm usage now with RainbowTQDM effect
for i in tqdm(range(100)):
    time.sleep(0.1)  # Simulate work
```

Choose the method that best suits your project's structure and requirements. All methods provide the same enhanced, colorful progress bar experience with RainbowTQDM.

### Test Scripts

The package includes two test scripts: `test_rainbow_tqdm.py` and `test_rainbow_tqdm_multithreaded.py`. These scripts demonstrate the usage of the RainbowTQDM progress bar and its effect in both single-threaded and multi-threaded environments. To test the package, simply run these scripts. They will create progress bars that update the loop and apply the smooth custom color changes, showcasing the rainbow effect in action.

## Key Components

- **`RainbowTQDM` Class**: Extends from tqdm.tqdm, enhancing its functionality to include a dynamic color-changing effect on the progress bar.

- **`generate_gradient` Function**: Responsible for creating a gradient of colors between two RGB values, spread over a defined number of steps. This function is integral to the generation of the RGB matrix that forms the basis of the color transitions.

- **`factorial` Function**: A utility function for calculating factorials, which are essential in the sine function approximation. This implementation, while simple, plays a significant role in the mathematical calculations.

- **`approximate_sin` Function**: Provides an approximation of the sine function using the Taylor series expansion. This approximation is critical for achieving the smooth color transition in the progress bar, ensuring that each step in the gradient feels naturally integrated.

- **`smooth_color` Function**: Determines the color of the progress bar at a given moment based on the progress ratio, using the sine wave for smooth transitions.

- **`generate_rainbow_colors` Function**: Generates a series of color gradients to create a rainbow effect.

- **`apply_override_tqdm` Function**: Applies the custom RainbowTQDM class to override the default `tqdm` progress bar.

## Variables

- `color_transitions`: Specifies pairs of RGB colors between which the gradient is generated.
- `steps_per_transition`: Determines the smoothness of the color transition.
- `RAINBOW_COLORS`: An array of color codes that form the rainbow gradient.
- `frequency`: Controls the speed of the color transition.
- `phase_shift`: Randomly alters the starting point in the color cycle for variety.

## Importance of Having Fun and Enjoying Programming

RainbowTQDM exemplifies how programming can be a creative and enjoyable activity. By adding a visually appealing element to a standard tool, it makes the programming experience more engaging and fun. Projects like this can inspire innovation and artistic expression in the coding community, reminding us that programming is not just about solving problems but also about enjoying the process and adding a personal touch to our creations.

## About the Author

Benjamin Gorlick is a computer science researcher, entrepreneur, and musician with a passion for AI, machine learning, big data, distributed computing, cryptography, cryptocurrency, and all alound science and technology nerdery. 

If you're interested in contacting the author, you can email ben[at]aialignment[dot]ai or ben[at]digitalsiddhartha[dot]ai

Enjoy more colorful progress bars with RainbowTQDM! 🌈

## License

RainbowTQDM is open source software [licensed as MIT](LICENSE.txt).