Skip to content
A lightweight terminal spinner for Python with safe pipes and redirects 🎁
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
examples Add pre-setup spinner example Sep 4, 2018
gifs GitHub sanitizes out RST image options for height, width, scale... :( Sep 21, 2018
static GitHub sanitizes out RST image options for height, width, scale... :( Sep 21, 2018
tests Apply black formatter May 12, 2019
yaspin Bump version: 0.14.2 β†’ 0.14.3 May 12, 2019
.coveragerc Exclude signal_handlers.py from coverage Sep 4, 2018
.editorconfig update .editorconfig Jul 13, 2018
.flake8 migrate to Pipfile Jul 15, 2018
.gitignore migrate to Pipfile Jul 15, 2018
.pyup.yml
.travis.yml Remove debugging lines from .travis.yml Aug 15, 2018
HISTORY.rst Update HISTORY May 12, 2019
LICENSE update copyright dates Jan 29, 2018
MANIFEST.in migrate to Pipfile Jul 15, 2018
Makefile Route CI through pip package installation (temprorary solution) Jan 27, 2019
Pipfile Add yaspin to dev dependencies; allow pre-releases Jan 27, 2019
README.rst Add downloads badge Sep 21, 2018
setup.cfg Bump version: 0.14.2 β†’ 0.14.3 May 12, 2019
setup.py black fmt setup.py Aug 14, 2018
tox.ini Change test execution command to `py.test -n auto` Aug 14, 2018

README.rst

yaspin Logo

yaspin: Yet Another Terminal Spinner for Python

Build Status Coverage Codacy pyup black-fmt

pypi Versions Wheel Examples Downloads

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

https://raw.githubusercontent.com/pavdmyt/yaspin/master/gifs/demo.gif

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()

Yaspin also provides an intuitive and powerful API. For example, you can easily summon a shark:

import time
from yaspin import yaspin

with yaspin().white.bold.shark.on_blue as sp:
    sp.text = "White bold shark in a blue sea"
    time.sleep(5)

https://raw.githubusercontent.com/pavdmyt/yaspin/master/gifs/shark.gif

Features

  • No external dependencies
  • Runs at all major CPython versions (2.7, 3.4, 3.5, 3.6, 3.7), PyPy and PyPy3
  • Supports all (60+) spinners from cli-spinners
  • Supports all colors, highlights, attributes and their mixes from termcolor library
  • Easy to combine with other command-line libraries, e.g. prompt-toolkit
  • Flexible API, easy to integrate with existing code
  • User-friendly API for handling POSIX signals
  • 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

https://raw.githubusercontent.com/pavdmyt/yaspin/master/gifs/basic_example.gif

# -*- 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

https://raw.githubusercontent.com/pavdmyt/yaspin/master/gifs/cli_spinners.gif

# -*- 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 🌈

https://raw.githubusercontent.com/pavdmyt/yaspin/master/gifs/basic_colors.gif

# -*- 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

https://raw.githubusercontent.com/pavdmyt/yaspin/master/gifs/advanced_colors.gif

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

text = "Bold blink magenta spinner on cyan color"
with yaspin().bold.blink.magenta.bouncingBall.on_cyan as sp:
    sp.text = text
    time.sleep(3)

# The same result can be achieved by passing arguments directly
with yaspin(
    Spinners.bouncingBall,
    color="magenta",
    on_color="on_cyan",
    attrs=["bold", "blink"],
) as sp:
    sp.text = text
    time.sleep(3)

Run any spinner you want

https://raw.githubusercontent.com/pavdmyt/yaspin/master/gifs/custom_spinners.gif

# -*- 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

https://raw.githubusercontent.com/pavdmyt/yaspin/master/gifs/sp_properties.gif

# -*- 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.side = "right"          # put spinner to the right
    sp.reversal = True         # reverse spin direction

    time.sleep(2)

Writing messages

https://raw.githubusercontent.com/pavdmyt/yaspin/master/gifs/write_text.gif

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("βœ”")

Integration with other libraries

https://raw.githubusercontent.com/pavdmyt/yaspin/master/gifs/hide_show.gif

Utilizing hide and show methods it is possible to toggle the display of the spinner in order to call custom methods that write to the terminal. This is helpful for allowing easy usage in other frameworks like prompt-toolkit. Using the powerful print_formatted_text function allows you even to apply HTML formats and CSS styles to the output:

# -*- coding: utf-8 -*-
from __future__ import print_function

import sys
import time

from yaspin import yaspin
from prompt_toolkit import HTML, print_formatted_text
from prompt_toolkit.styles import Style

# override print with feature-rich ``print_formatted_text`` from prompt_toolkit
print = print_formatted_text

# build a basic prompt_toolkit style for styling the HTML wrapped text
style = Style.from_dict({
    'msg': '#4caf50 bold',
    'sub-msg': '#616161 italic'
})


with yaspin(text='Downloading images') as sp:
    # task 1
    time.sleep(1)
    sp.hide()
    print(HTML(
        u'<b>></b> <msg>image 1</msg> <sub-msg>download complete</sub-msg>'
    ), style=style)
    sp.show()

    # task 2
    time.sleep(2)
    sp.hide()
    print(HTML(
        u'<b>></b> <msg>image 2</msg> <sub-msg>download complete</sub-msg>'
    ), style=style)
    sp.show()

    # finalize
    sp.ok()

Handling POSIX signals

Handling keyboard interrupts (pressing Control-C):

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

from yaspin import kbi_safe_yaspin


with kbi_safe_yaspin(text="Press Control+C to send SIGINT (Keyboard Interrupt) signal"):
    time.sleep(5)  # time consuming code

Handling other types of signals:

# -*- coding: utf-8 -*-
import os
import time
from signal import SIGTERM, SIGUSR1

from yaspin import yaspin
from yaspin.signal_handlers import default_handler, fancy_handler


sigmap = {SIGUSR1: default_handler, SIGTERM: fancy_handler}
with yaspin(sigmap=sigmap, text="Handling SIGUSR1 and SIGTERM signals") as sp:
    sp.write("Send signals using `kill` command")
    sp.write("E.g. $ kill -USR1 {0}".format(os.getpid()))
    time.sleep(20)  # time consuming code

More examples.

Development

Clone the repository:

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

Install dev dependencies:

pipenv install --dev

Lint code:

make lint

Format code:

make black-fmt

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

You can’t perform that action at this time.