pyloaders
=========

Basic animated ASCII loaders for Python scripts.

- Spinning Loader
- Text Loader
- Bar Loader
- Progress Loader

## Installation

```bash
pip install pyloaders
```

## Usage

All loaders are declared by calling `LoaderClass(<arguments>)`

#### Arguments

| Option        | Description                         | Type  | Choices                  | Default   | Valid For           |
|---------------|-------------------------------------|-------|--------------------------|-----------|---------------------|
| text          | Text displayed while loading        | str   |                          | 'Loading' | Text, Spinning      |
| size          | Full width of loader                | str   | small, medium, large     | 'medium'  | Text, Bar, Progress |
| speed         | Time between loader paints          | float |                          | 1         | Text, Spinning, Bar |
| duration      | Runtime of fixed loader, in seconds | int   |                          | 10        | Text, Spinning, Bar |
| direction     | Initial direction of moving loader  | str   | ltr, rtl                 | 'ltr'     | Text, Bar           |
| animation     | Continuous or oscillating movement  | str   | loop, bounce             | 'loop'    | Text, Bar           |
| colour        | Terminal colour support required    | str   | blue, green, yellow, red | None      | ALL                 |
| style         | Terminal styles support required    | str   | header, bold, underline  | None      | ALL                 |
| complete_text | Text displayed after loader ends    | str   |                          | 'Done!'   | ALL                 |
| start         | Progress loader start position      | int   |                          | 0         | Progress            |
| total         | Progress loader total count         | int   |                          | 100       | Progress            |

### Indeterminate

**Available Classes:** SpinningLoader, TextLoader, BarLoader

Run as threads which can be started and stopped dynamically by you at any stage.
- To start a loader, call its `start()` method.
- After you have completed your tasks, call the loader's `stop()` method to terminate
the thread.
- If you have set a fixed _duration_ of the loader, call the `run()` method to run
the loader for the set amount of time.

#### Threaded
```python
from pyloaders import TextLoader

loader = TextLoader()
loader.start()
# Perform some tasks
loader.stop()
```

#### Fixed Duration
```python
from pyloaders import TextLoader

fixed_loader = TextLoader(duration=10)
fixed_loader.run() # Pauses program execution and runs loader for 10s
```

**Remember**: Don't try to start more than one loader at the same time!

### Determinate

**Available Classes:** ProgressLoader

Used to measure the completion progress of a loop or function.

When you initialize a `ProgressLoader` object, you should specify the total number of
iterations that will be performed in your loop as the `total` argument.

On each iteration, call the loader's `progress(n)` method, where `n` is the
current iteration count, to update the progress bar in the terminal.

```python
from pyloaders import ProgressLoader

loader = ProgressLoader(total=10)
for i in range(10):
    # Perform some task each loop
    loader.progress(i)
```

**Remember:** Don't print anything to the console while the loader is running!

## Tests

There is a small test suite that uses the **pytest** module.
1. Clone the repository
2. Install pytest and dependencies
3. Run pytest from project folder

```bash
git clone https://gitlab.com/ml394/pyloaders.git
cd pyloaders
pip install -r requirements.txt
pytest
```

### Examples

An visual example can be performed by running `example.py` from the project directory.

This will run a suite of example loaders specified in the file for 5s each. By
default, the indeterminate examples are run on fixed durations. To run them as threads, use the
optional `thread` argument.

```bash
# Fixed duration
python example.py

# Threaded
python example.py thread
```

## Contributing

To contribute to this project, clone master and create your own development branch.
```bash
git clone https://gitlab.com/ml394/pyloaders.git
git checkout -b <feature-name>
```

Push your branch remotely, and create a merge request to master so we can review your code.
If the merge request is approved, your new feature will be merged and pushed for the next release.

## Donate

We accept donations via Bitcoin at the wallet address:

75bf8733-4aba-4ff9-b822-6eeae771072a
