Metadata-Version: 2.1
Name: console-animation
Version: 0.2.5
Summary: An easy to use decorator to show a console spinner during function execution.
Home-page: https://github.com/KoushikEng/console-animation
Author: Koushik
Author-email: koushikla115@gmail.com
License: UNKNOWN
Platform: UNKNOWN
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.8
Description-Content-Type: text/markdown

# ⏳ console-animation

[![PyPI version](https://img.shields.io/pypi/v/console_animation.svg)](https://pypi.org/project/console_animation/)
[![Build](https://github.com/KoushikEng/console_animation/actions/workflows/python-package.yml/badge.svg)](https://github.com/KoushikEng/console_animation/actions)
[![GitHub issues](https://img.shields.io/github/issues/KoushikEng/console_animation.svg)](https://github.com/KoushikEng/console_animation/issues)
[![License](https://img.shields.io/github/license/KoushikEng/console_animation.svg)](https://github.com/KoushikEng/console_animation/blob/main/LICENSE)

A lightweight and flexible Python decorator to show a console animation (loading animation) while a function is running. Useful for long-running CLI tasks, data processing, I/O, or just making your tools feel more alive.

---

## 🔧 Features

- Add a console animation with a single line
- Optional start, end, and error messages
- Customizable animation style and speed
- Gracefully handles exceptions
- Works with or without decorator arguments
- Clean terminal output (hides cursor during spin)

---

## 📦 Installation

```bash
# pip install
pip install console_animation

# or

# Clone the repo
git clone https://github.com/KoushikEng/console_animation.git
cd console_animation

# Install locally
pip install .
````

> You can also install it in **editable mode** during development:
>
> ```bash
> pip install -e .
> ```

---

## 🚀 Usage

### ✅ Basic animation (no args)

```python
from console_animation import animate

@animate
def task():
    import time
    time.sleep(3)
```

This will show a rotating animation while `task()` runs.

---

### ⚙️ With Custom Messages

```python
@animate(start="Processing...", loaded="✅ Task complete!", error="❌ Something broke.")
def do_work():
    time.sleep(5)
```

* `start` – message shown before animation
* `loaded` or `end` – message shown after successful run
* `error` – message shown if exception occurs

---

### 🎯 Custom animation and Speed

```python
@animate(spinner="⠋⠙⠚⠞⠖⠦⠴⠲⠳⠓", interval=0.05)
def fancy_task():
    time.sleep(3)
```

* `spinner`: any iterable of characters
* `interval`: time (in seconds) between frames

---

### ❗ Error Handling

If `error` is not provided:

* The animation will stop
* Cursor will be restored
* The original exception is raised **as-is**

If `error` is set:

* It will be printed
* Full traceback is also printed for debugging

---

## 🧪 Example Script

```python
from console_animation import animate
import time

@animate(start="Crunching numbers...", loaded="✅ Done!", error="🔥 Failed.")
def math_task():
    time.sleep(3)

@animate
def quick_task():
    time.sleep(1)

@animate(start="Breaking...", error="Oops.")
def will_fail():
    raise RuntimeError("Intentional failure.")

math_task()
quick_task()
will_fail()
```

---

## 🤝 Contributing

Contributions are **welcome and appreciated**!

If you want to:

* Add features (like async support, presets, color, etc.)
* Improve performance or compatibility
* Fix bugs
* Write tests or improve docs

Please feel free to:

1. Fork the repo
2. Create a new branch (`feature/your-feature`)
3. Commit your changes
4. Push and open a PR

> Issues and suggestions are also welcome in the [Issues](https://github.com/KoushikEng/console_animation/issues) tab.

---

## 📄 License

This project is licensed under the MIT License — see the [LICENSE](./LICENSE) file for details.

---

## 🙌 Credits

Built with frustration from boring terminal waits and love for clean CLI UX.

---

## 🛠️ To Do (Open for PRs)

* [ ] Async function support (`async def`)
* [ ] Color support (via `colorama`)
* [ ] Predefined animation styles
* [ ] Timeout decorator option
* [x] PyPI upload

---

Made by [Koushik](https://github.com/KoushikEng) 🔥


