README.md

halo

Beautiful spinners for terminal, IPython and Jupyter

Install

$ pip install halo

Usage

from halo import Halo

spinner = Halo(text='Loading', spinner='dots')
spinner.start()

# Run time consuming work here
# You can also change properties for spinner as and when you want

spinner.stop()

Alternatively, you can use halo with Python's with statement:

from halo import Halo

with Halo(text='Loading', spinner='dots'):
    # Run time consuming work here

Finally, you can use halo as a decorator:

from halo import Halo

@Halo(text='Loading', spinner='dots')
def long_running_function():
    # Run time consuming work here
    pass

long_running_function()

API

Halo([text|text_color|spinner|animation|placement|color|interval|stream|enabled])

text

Type: str

Text shown along with spinner.

text_color

Type: str Values: grey, red, green, yellow, blue, magenta, cyan, white

Color of the spinner text. Defaults to None.

spinner

Type: str|dict

If string, it should be one of the spinners listed in the given json file. If a dict is passed, it should define interval and frames. Something like:

{
    'interval': 100,
    'frames': ['-', '+', '*', '+', '-']
}

Defaults to dots spinner. For Windows users, it defaults to line spinner.

animation

Type: str Values: bounce, marquee

Animation to apply to the text if it's too large and doesn't fit in the terminal. If no animation is defined, the text will be ellipsed.

placement

Type: str Values: left, right

Which side of the text the spinner should be displayed. Defaults to left

color

Type: str Values: grey, red, green, yellow, blue, magenta, cyan, white

Color of the spinner. Defaults to cyan.

interval

Type: float

Interval between each frame. Defaults to spinner interval (recommended).

stream

Type: file

Stream to write the output. Defaults to sys.stdout.

enabled

Type: bool

Enable or disable the spinner. Defaults to True.

Methods

Following are the methods available:

spinner.start([text])

Starts the spinner. If text is passed, it is set as spinner text. Returns the instance.

spinner.stop()

Stops and clears the spinner. Returns the instance.

spinner.clear()

Clears the spinner. Returns the instance.

spinner.render()

Manually renders a new frame. Returns the instance.

spinner.frame()

Returns next frame to be rendered.

spinner.succeed([text])

text: Type: str

Stops the spinner and changes symbol to ✔. If text is provided, it is persisted else current text is persisted. Returns the instance.

spinner.fail([text])

text: Type: str

Stops the spinner and changes symbol to ✖. If text is provided, it is persisted else current text is persisted. Returns the instance.

spinner.warn([text])

text: Type: str

Stops the spinner and changes symbol to ⚠. If text is provided, it is persisted else current text is persisted. Returns the instance.

spinner.info([text])

text: Type: str

Stops the spinner and changes symbol to ℹ. If text is provided, it is persisted else current text is persisted. Returns the instance.

spinner.stop_and_persist([symbol|text])

Stops the spinner and changes symbol and text. Returns the instance.

symbol

Type: str

Symbol to replace the spinner with. Defaults to ' '.

text

Type: str

Text to be persisted. Defaults to instance text.

spinner.text

Change the text of spinner.

spinner.color

Change the color of spinner

spinner.spinner

Change the spinner itself.

spinner.enabled

Enable or disable the spinner.

How to contribute?

Please see Contributing guidelines for more information.

Like it?

🌟 this repo to show support. Let me know you liked it on Twitter. Also, share the project.

Related

• py-spinners - Spinners in Python
• py-log-symbols - Log Symbols in Python
• ora - Elegant terminal spinners in JavaScript (inspiration behind this project)

License

MIT © Manraj Singh