yaspin 0.9.0

Yet Another Terminal Spinner

Yet Another Terminal Spinner for Python.

Yaspin provides a full-featured terminal spinner to show the progress during long-hanging operations.

It is easy to integrate into existing codebase by using it as a context manager or as a function decorator:

import time
from yaspin import yaspin

# Context manager:
with yaspin():
    time.sleep(3)  # time consuming code

# Function decorator:
@yaspin(text="Loading...")
def some_operations():
    time.sleep(3)  # time consuming code

some_operations()

Features

• No external dependencies

• Runs at all major CPython versions (2.6, 2.7, 3.3, 3.4, 3.5, 3.6), PyPy and PyPy3

• Supports all (60+) spinners from cli-spinners

• Supports all colors, highlights, attributes and their mixes from termcolor library

• Flexible API, easy to integrate with existing code

• Safe pipes and redirects:

$ python script_that_uses_yaspin.py > script.log
$ python script_that_uses_yaspin.py | grep ERROR

Installation

From PyPI using pip package manager:

pip install --upgrade yaspin

Or install the latest sources from GitHub:

pip install https://github.com/pavdmyt/yaspin/archive/master.zip

Usage

Basic Example

# -*- coding: utf-8 -*-
import time
from random import randint
from yaspin import yaspin

with yaspin(text="Loading", color="yellow") as spinner:
    time.sleep(2)  # time consuming code

    success = randint(0, 1)
    if success:
        spinner.ok("✅ ")
    else:
        spinner.fail("💥 ")

It is also possible to control spinner manually:

# -*- coding: utf-8 -*-
import time
from yaspin import yaspin

spinner = yaspin()
spinner.start()

time.sleep(3)  # time consuming tasks

spinner.stop()

Run any spinner from cli-spinners

# -*- coding: utf-8 -*-
import time
from yaspin import yaspin
from yaspin.spinners import Spinners

with yaspin(Spinners.earth, text="Earth") as sp:
    time.sleep(2)                # time consuming code

    # change spinner
    sp.spinner = Spinners.moon
    sp.text = "Moon"

    time.sleep(2)                # time consuming code

Any Colour You Like 🌈

# -*- coding: utf-8 -*-
import time
from yaspin import yaspin

with yaspin(text="Colors!") as sp:
    # Support all basic termcolor text colors
    colors = ("red", "green", "yellow", "blue", "magenta", "cyan", "white")

    for color in colors:
        sp.color, sp.text = color, color
        time.sleep(1)

Advanced colors usage

# -*- coding: utf-8 -*-
import time
from yaspin import yaspin
from yaspin.spinners import Spinners
from yaspin.termcolor import colored

text = "Bold blink magenta spinner on cyan color"
# Support all termcolor features via simple closure
color_fn = lambda frame: colored(frame, "magenta", "on_cyan", attrs=["bold", "blink"])

with yaspin(Spinners.bouncingBall, text=text, color=color_fn):
    time.sleep(3)

Run any spinner you want

# -*- coding: utf-8 -*-
import time
from yaspin import yaspin, Spinner

# Compose new spinners with custom frame sequence and interval value
sp = Spinner(["😸", "😹", "😺", "😻", "😼", "😽", "😾", "😿", "🙀"], 200)

with yaspin(sp, text="Cat!"):
    time.sleep(3)  # cat consuming code :)

Change spinner properties on the fly

# -*- coding: utf-8 -*-
import time
from yaspin import yaspin
from yaspin.spinners import Spinners

with yaspin(Spinners.noise, text="Noise spinner") as sp:
    time.sleep(2)

    sp.spinner = Spinners.arc  # spinner type
    sp.text = "Arc spinner"    # text along with spinner
    sp.color = "green"         # spinner color
    sp.right = True            # put spinner to the right
    sp.reverse = True          # reverse spin direction

    time.sleep(2)

Writing messages

You should not write any message in the terminal using print while spinner is open. To write messages in the terminal without any collision with yaspin spinner, a .write() method is provided:

# -*- coding: utf-8 -*-
import time
from yaspin import yaspin

with yaspin(text="Downloading images", color="cyan") as sp:
    # task 1
    time.sleep(1)
    sp.write("> image 1 download complete")

    # task 2
    time.sleep(2)
    sp.write("> image 2 download complete")

    # finalize
    sp.ok("✔")

More examples.

Development

Clone the repository:

git clone https://github.com/pavdmyt/yaspin.git

Install dev dependencies:

pip install -r requirements-dev.txt

Lint code:

make lint

Run tests:

make test

Contributing

1. Fork it!

2. Create your feature branch: git checkout -b my-new-feature

3. Commit your changes: git commit -m 'Add some feature'

4. Push to the branch: git push origin my-new-feature

5. Submit a pull request

6. Make sure tests are passing

License

• MIT - Pavlo Dmytrenko; https://twitter.com/pavdmyt

• Contains termcolor package: MIT License, Copyright (c) 2008-2011 Volvox Development Team

• Contains data from cli-spinners: MIT License, Copyright (c) Sindre Sorhus [e-mail] (sindresorhus.com)