# โณ console-animation
[](https://pypi.org/project/console_animation/)
[](https://github.com/KoushikEng/console_animation/actions)
[](https://github.com/KoushikEng/console_animation/issues)
[](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
* [ ] PyPI upload
---
Made by [Koushik](https://github.com/KoushikEng) ๐ฅ
Raw data
{
"_id": null,
"home_page": "https://github.com/KoushikEng/console-animation",
"name": "console-animation",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.6",
"maintainer_email": null,
"keywords": null,
"author": "Koushik",
"author_email": "koushikla115@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/bf/30/6a3a28a1521675a8542c92eeaed78605bd030aaacc5fbbf02c39effde380/console-animation-0.1.3.tar.gz",
"platform": null,
"description": "# \u23f3 console-animation\n\n[](https://pypi.org/project/console_animation/)\n[](https://github.com/KoushikEng/console_animation/actions)\n[](https://github.com/KoushikEng/console_animation/issues)\n[](https://github.com/KoushikEng/console_animation/blob/main/LICENSE)\n\nA 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.\n\n---\n\n## \ud83d\udd27 Features\n\n- Add a console animation with a single line\n- Optional start, end, and error messages\n- Customizable animation style and speed\n- Gracefully handles exceptions\n- Works with or without decorator arguments\n- Clean terminal output (hides cursor during spin)\n\n---\n\n## \ud83d\udce6 Installation\n\n```bash\n# pip install\npip install console_animation\n\n# or\n\n# Clone the repo\ngit clone https://github.com/KoushikEng/console_animation.git\ncd console_animation\n\n# Install locally\npip install .\n````\n\n> You can also install it in **editable mode** during development:\n>\n> ```bash\n> pip install -e .\n> ```\n\n---\n\n## \ud83d\ude80 Usage\n\n### \u2705 Basic animation (no args)\n\n```python\nfrom console_animation import animate\n\n@animate\ndef task():\n import time\n time.sleep(3)\n```\n\nThis will show a rotating animation while `task()` runs.\n\n---\n\n### \u2699\ufe0f With Custom Messages\n\n```python\n@animate(start=\"Processing...\", loaded=\"\u2705 Task complete!\", error=\"\u274c Something broke.\")\ndef do_work():\n time.sleep(5)\n```\n\n* `start` \u2013 message shown before animation\n* `loaded` or `end` \u2013 message shown after successful run\n* `error` \u2013 message shown if exception occurs\n\n---\n\n### \ud83c\udfaf Custom animation and Speed\n\n```python\n@animate(spinner=\"\u280b\u2819\u281a\u281e\u2816\u2826\u2834\u2832\u2833\u2813\", interval=0.05)\ndef fancy_task():\n time.sleep(3)\n```\n\n* `spinner`: any iterable of characters\n* `interval`: time (in seconds) between frames\n\n---\n\n### \u2757 Error Handling\n\nIf `error` is not provided:\n\n* The animation will stop\n* Cursor will be restored\n* The original exception is raised **as-is**\n\nIf `error` is set:\n\n* It will be printed\n* Full traceback is also printed for debugging\n\n---\n\n## \ud83e\uddea Example Script\n\n```python\nfrom console_animation import animate\nimport time\n\n@animate(start=\"Crunching numbers...\", loaded=\"\u2705 Done!\", error=\"\ud83d\udd25 Failed.\")\ndef math_task():\n time.sleep(3)\n\n@animate\ndef quick_task():\n time.sleep(1)\n\n@animate(start=\"Breaking...\", error=\"Oops.\")\ndef will_fail():\n raise RuntimeError(\"Intentional failure.\")\n\nmath_task()\nquick_task()\nwill_fail()\n```\n\n---\n\n## \ud83e\udd1d Contributing\n\nContributions are **welcome and appreciated**!\n\nIf you want to:\n\n* Add features (like async support, presets, color, etc.)\n* Improve performance or compatibility\n* Fix bugs\n* Write tests or improve docs\n\nPlease feel free to:\n\n1. Fork the repo\n2. Create a new branch (`feature/your-feature`)\n3. Commit your changes\n4. Push and open a PR\n\n> Issues and suggestions are also welcome in the [Issues](https://github.com/KoushikEng/console_animation/issues) tab.\n\n---\n\n## \ud83d\udcc4 License\n\nThis project is licensed under the MIT License \u2014 see the [LICENSE](./LICENSE) file for details.\n\n---\n\n## \ud83d\ude4c Credits\n\nBuilt with frustration from boring terminal waits and love for clean CLI UX.\n\n---\n\n## \ud83d\udee0\ufe0f To Do (Open for PRs)\n\n* [ ] Async function support (`async def`)\n* [ ] Color support (via `colorama`)\n* [ ] Predefined animation styles\n* [ ] Timeout decorator option\n* [ ] PyPI upload\n\n---\n\nMade by [Koushik](https://github.com/KoushikEng) \ud83d\udd25\n\n",
"bugtrack_url": null,
"license": null,
"summary": "An easy to use decorator to show a console spinner during function execution.",
"version": "0.1.3",
"project_urls": {
"Homepage": "https://github.com/KoushikEng/console-animation"
},
"split_keywords": [],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "92ac1218cd4b8cb86caa14ba7dc53eb430dec5eb6b150b7ea3dcf3e270b05d83",
"md5": "87b2f973047a3ea7ef94219b27f3f084",
"sha256": "7dad67d11b115a00dfe253a04b325cc515fcbc9b3ab2afbc038b6092106580e9"
},
"downloads": -1,
"filename": "console_animation-0.1.3-py3-none-any.whl",
"has_sig": false,
"md5_digest": "87b2f973047a3ea7ef94219b27f3f084",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.6",
"size": 5615,
"upload_time": "2025-07-10T18:08:09",
"upload_time_iso_8601": "2025-07-10T18:08:09.767286Z",
"url": "https://files.pythonhosted.org/packages/92/ac/1218cd4b8cb86caa14ba7dc53eb430dec5eb6b150b7ea3dcf3e270b05d83/console_animation-0.1.3-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "bf306a3a28a1521675a8542c92eeaed78605bd030aaacc5fbbf02c39effde380",
"md5": "eb352c5e123325162a65fbaac4e3e482",
"sha256": "71e9025ab24bff9d569bbd6bd6602b4b4c67e9c130ccc10e260eb3ba900cefb2"
},
"downloads": -1,
"filename": "console-animation-0.1.3.tar.gz",
"has_sig": false,
"md5_digest": "eb352c5e123325162a65fbaac4e3e482",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.6",
"size": 5169,
"upload_time": "2025-07-10T18:08:10",
"upload_time_iso_8601": "2025-07-10T18:08:10.991025Z",
"url": "https://files.pythonhosted.org/packages/bf/30/6a3a28a1521675a8542c92eeaed78605bd030aaacc5fbbf02c39effde380/console-animation-0.1.3.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-10 18:08:10",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "KoushikEng",
"github_project": "console-animation",
"github_not_found": true,
"lcname": "console-animation"
}
JSON
