.. figure:: https://fancybar.readthedocs.io/en/latest/_images/fancybar-logo.png
:align: center
.. image:: https://fancybar.readthedocs.io/en/latest/_images/fancybar-showcase.gif
``fancybar`` is a highly customizable terminal progress bar library.
Usage is very simple:
.. code-block::
import fancybar
for i in fancybar.bar(range(100)):
# Do something
You can also create a bar without an iterable:
.. code-block::
import fancybar
bar = fancybar.ProgressBar(100)
with bar:
# Do something
Installation
============
Pip
---
.. code-block:: console
python3 -m pip install fancybar
Git
---
.. code-block:: console
git clone https://github.com/jenca-adam/fancybar
cd build
python3 setup.py install
Bar Types
=========
Please note that not all bar types will work on all terminals!
Bar type showcases can be seen in the gif file at the top of this page.
You can select a bar type using the ``bartype`` argument of ``ProgressBar``
There are currently the following bar types:
- full
.. image:: https://fancybar.readthedocs.io/en/latest/_images/bartype_full.gif
This bar type uses character ' ' (U+0020 SPACE) and filler ' ' (U+0020 SPACE) with default character background color "white".
Your terminal must have the ability to output colored text for this bar type to properly render.
- plusMinus
.. image:: https://fancybar.readthedocs.io/en/latest/_images/bartype_plusminus.gif
This bar type uses character '+' (U+002B PLUS SIGN) and filler '-' (U+002D HYPHEN-MINUS) with default character foreground color "green" and default filler foreground color "red".
Your terminal must have the ability to output colored text for this bar type to properly render.
- classic
.. image:https://fancybar.readthedocs.io/en/latest/_images/colors.gif: https://fancybar.readthedocs.io/en/latest/_images/bartype_classic.gif
This bar type uses character '#' (U+0023 NUMBER SIGN) and filler ' ' (U+0020 SPACE).
This bar type should work on any terminal.
- triangles
.. image:: https://fancybar.readthedocs.io/en/latest/_images/bartype_triangles.gif
This bar type uses character '▶' (U+25B6 BLACK RIGHT-POINTING TRIANGLE) and filler '▷' (U+25B7 WHITE RIGHT-POINTING TRIANGLE).
Your terminal must have the ability to display Unicode characters for this bar type to properly render.
- dots
.. image:: https://fancybar.readthedocs.io/en/latest/_images/bartype_dots.gif
This bar type uses character '.' (U+002E FULL STOP) and filler ' ' (U+0020 SPACE).
This bar type should work on any terminal.
- gradient
.. image:: https://fancybar.readthedocs.io/en/latest/_images/bartype_gradient.gif
*THIS BAR DOES NOT SHARE THE ARGUMENTS WITH THE OTHER BARS.*
This bar type uses character '▌' (U+258C LEFT HALF BLOCK). The background and foreground colors are shifting in a gradient specified by the arguments ``start_color`` (default "red") and ``end_color`` (default "green") of ``ProgressBar`` .
Your terminal must have the ability to display Truecolor 24-bit colors (e.g. xterm and its derivatives, KDE Konsole, KDE Yakuake) and to display Unicode characters for this bar type to properly render.
- minus
.. image:: https://fancybar.readthedocs.io/en/latest/_images/bartype_minus.gif
This bar type uses character '-' (U+002D HYPHEN-MINUS) and filler ' ' (U+0020 SPACE)
Arguments
----------------
General Arguments
^^^^^^^^^^^^^^^^^
All bar types (except gradient and including `custom bar types` ) can be customized using a set of keyword-only arguments given to ``ProgressBar``. See `Entry Points`
These arguments are:
- ``char_bg_color`` Specifies the background color of the filled part of the progressbar. See `Colors` for more information about specifying colors.
- ``char_fg_color`` Specifies the color of the characters in the filled part of the progressbar. See `Colors` for more information about specifying colors.
- ``filler_bg_color`` Specifies the background color of the empty part of the progressbar. See `Colors` for more information about specifying colors.
- ``filler_fg_color`` Specifies the color of the characters in the empty part of the progressbar. See `Colors` for more information about specifying colors.
All of these arguments default to `None`.
Gradient type
^^^^^^^^^^^^^
Gradient bar type has different arguments:
- ``start_color`` Specifies the starting color of the bar's gradient. Defaults to `"red"`
- ``end_color`` Specifies the ending color of the bar's gradient. Defaults to `"green"`
These are set the same way as
Creating custom bar types
-------------------------
If the built-in bar types are not enough for your needs, you can easily create custom ones using ``create_bar_type()`` function.
Its arguments are:
- ``char`` Character to be used in the filled part of the progressbar.(required)
- ``filler`` Character to be used in the empty part of the progressbar.(required)
- ``name`` `__qualname__` of the returned class. (defaults to "?")
- ``char_bg_color`` See `Arguments` (defaults to `None`)
- ``char_fg_color`` See `Arguments` (defaults to `None`)
- ``filler_bg_color`` See `Arguments` (defaults to `None`)
- ``filler_fg_color`` See `Arguments` (defaults to `None`)
Spinners
========
*Credit for all spinners except "loading" goes to* `Sindre Sorhus <https://github.com/sindresorhus/cli-spinners>`_
*"loading" spinner is made by me.*
.. image:: https://fancybar.readthedocs.io/en/latest/_images/spinners.gif
All spinners are on the GIF above.
The spinners not shown are not shown because of the asciinema charset limitations. To get a more acute representation of the spinners, clone the repository and run ``python3 spinner_test.py``.
The default spinner is |spinner-line|.
You can choose a spinner by setting the argument ``spinner`` of ``ProgressBar`` to its name. See `Entry Points`
Changing spinner speed
----------------------
If you don't like the animation speed on your spinner, you can change its speed using the argument ``spinner_speed`` of ``ProgressBar``.
``spinner_speed`` is the speed of the spinner on the progress bar in revolutions per iteration. Default is ``0.5``.
Entry Points
============
ProgressBar
-----------
Main entry point of the ``fancybar`` library is the ``ProgressBar`` class.
Its ``__init__`` function has the following arguments:
- ``items`` (`int`): Required. The number of items the progress bar is running on.
- ``length`` (`int`): How much space will the progressbar take on screen. Defaults to `50`
- ``item_name`` (`str`): What abbreviation to use for items in the items/second part of the progress bar. Defaults to `"it"`
- ``spinner`` (`str`): The name of the spinner. See `Spinners`. Default `"line"`
- ``spinner_speed`` (`float` or `int`): The spinner's speed. See `Spinners`. Default `0.5`.
- ``percentage_bg_color`` (`str` or `tuple` or `None`): What color is to be used for the background color of the percentage part of the progress bar. See `Colors`. Default `None`
- ``percentage_fg_color`` (`str` or `tuple` or `None`): What color is to be used for the foreground color of the percentage part of the progress bar. See `Colors`. Default `None`
- ``spinner_bg_color`` (`str` or `tuple` or `None`): What color is to be used for the background color of the spinner part of the progress bar. See `Colors`. Default `None`
- ``spinner_fg_color`` (`str` or `tuple` or `None`): What color is to be used for the foreground color of the spinner part of the progress bar. See `Colors`. Default `None`.
- ``bartype`` (`str` or `type`): Bar type for the progress bar. See `Bar Types`. Default `"full"`.
- ``hide_cursor`` (`bool`): Whether or not is the cursor to be hidden during the progress bar's runtime. Default `False`
All arguments after ``items`` are not required and keyword-only
SequentialProgressBar
---------------------
``SequentialProgressBar`` is a subclass of `ProgressBar` that creates progress bars from an iterable sequence. `len()` must be callable upon those sequences.
``SequentialProgressbar`` replaces `ProgressBar`'s ``items`` argument by a ``seq`` argument -- the sequence you want to create progress bars from. All other arguments are unchanged.
``bar`` is an alias for ``SequentialProgressBar``, as it is more likely to be used than `ProgressBar`
Colors
======
Colors can be specified by either a color string or a RGB tuple. RGB tuples only work on Truecolor terminals.
Color Strings
-------------
All Terminals
^^^^^^^^^^^^^
These colors should work on all terminals that support colored output
.. image:: https://fancybar.readthedocs.io/en/latest/_images/colors_main.gif
256-color
^^^^^^^^^^^^^^^
These colors work on 256-color type terminals. The ones that are not in `All terminals` might display differently/incorrectly in other terminals.
.. figure:: https://fancybar.readthedocs.io/en/latest/_images/colors.gif
:align: center
RGB Tuples
----------
RGB tuples must be in format 0-255 and must not contain alpha part.
RGB tuples are only supported in Truecolor terminals.
They might display differently/incorrectly in other terminals.
Runtime attributes
==================
While your bar is running, you can easily access some of its attributes:
- ``ProgressBar.eta`` - current ETA in seconds
- ``ProgressBar.percentage`` - current percentage
- ``ProgressBar.items_done`` - number of items already done
.. |spinner-line| image:: line-spinner.gif
Raw data
{
"_id": null,
"home_page": "https://github.com/jenca-adam/fancybar",
"name": "fancybar",
"maintainer": "",
"docs_url": null,
"requires_python": "",
"maintainer_email": "",
"keywords": "Progress bar,TUI",
"author": "Adam Jenca",
"author_email": "jenca.a@gjh.sk",
"download_url": "https://files.pythonhosted.org/packages/a3/27/2d91fc1830576a16d4cc11de1ce1858527f843636ef2e5dd26578e12e613/fancybar-0.2.0.tar.gz",
"platform": null,
"description": "\n\n.. figure:: https://fancybar.readthedocs.io/en/latest/_images/fancybar-logo.png\n :align: center\n.. image:: https://fancybar.readthedocs.io/en/latest/_images/fancybar-showcase.gif\n\n``fancybar`` is a highly customizable terminal progress bar library.\nUsage is very simple:\n\n.. code-block:: \n\n import fancybar\n for i in fancybar.bar(range(100)):\n # Do something\n\nYou can also create a bar without an iterable:\n\n.. code-block::\n \n import fancybar\n bar = fancybar.ProgressBar(100)\n with bar:\n # Do something\n\nInstallation\n============\n\nPip\n---\n\n.. code-block:: console\n \n python3 -m pip install fancybar\n\nGit\n---\n\n.. code-block:: console\n \n git clone https://github.com/jenca-adam/fancybar\n cd build\n python3 setup.py install\n\nBar Types\n=========\nPlease note that not all bar types will work on all terminals!\nBar type showcases can be seen in the gif file at the top of this page.\nYou can select a bar type using the ``bartype`` argument of ``ProgressBar``\nThere are currently the following bar types:\n\n- full\n \n .. image:: https://fancybar.readthedocs.io/en/latest/_images/bartype_full.gif\n\n This bar type uses character ' ' (U+0020 SPACE) and filler ' ' (U+0020 SPACE) with default character background color \"white\". \n Your terminal must have the ability to output colored text for this bar type to properly render.\n- plusMinus\n \n .. image:: https://fancybar.readthedocs.io/en/latest/_images/bartype_plusminus.gif\n \n This bar type uses character '+' (U+002B PLUS SIGN) and filler '-' (U+002D HYPHEN-MINUS) with default character foreground color \"green\" and default filler foreground color \"red\". \n Your terminal must have the ability to output colored text for this bar type to properly render.\n\n- classic\n \n .. image:https://fancybar.readthedocs.io/en/latest/_images/colors.gif: https://fancybar.readthedocs.io/en/latest/_images/bartype_classic.gif\n\n This bar type uses character '#' (U+0023 NUMBER SIGN) and filler ' ' (U+0020 SPACE). \n This bar type should work on any terminal.\n\n- triangles\n\n .. image:: https://fancybar.readthedocs.io/en/latest/_images/bartype_triangles.gif \n\n This bar type uses character '\u25b6' (U+25B6 BLACK RIGHT-POINTING TRIANGLE) and filler '\u25b7' (U+25B7 WHITE RIGHT-POINTING TRIANGLE).\n Your terminal must have the ability to display Unicode characters for this bar type to properly render.\n\n- dots\n\n .. image:: https://fancybar.readthedocs.io/en/latest/_images/bartype_dots.gif\n\n This bar type uses character '.' (U+002E FULL STOP) and filler ' ' (U+0020 SPACE).\n This bar type should work on any terminal.\n\n- gradient\n\n .. image:: https://fancybar.readthedocs.io/en/latest/_images/bartype_gradient.gif\n \n *THIS BAR DOES NOT SHARE THE ARGUMENTS WITH THE OTHER BARS.*\n \n This bar type uses character '\u258c' (U+258C LEFT HALF BLOCK). The background and foreground colors are shifting in a gradient specified by the arguments ``start_color`` (default \"red\") and ``end_color`` (default \"green\") of ``ProgressBar`` .\n Your terminal must have the ability to display Truecolor 24-bit colors (e.g. xterm and its derivatives, KDE Konsole, KDE Yakuake) and to display Unicode characters for this bar type to properly render.\n\n- minus\n \n .. image:: https://fancybar.readthedocs.io/en/latest/_images/bartype_minus.gif\n \n This bar type uses character '-' (U+002D HYPHEN-MINUS) and filler ' ' (U+0020 SPACE)\n\nArguments\n----------------\nGeneral Arguments\n^^^^^^^^^^^^^^^^^\nAll bar types (except gradient and including `custom bar types` ) can be customized using a set of keyword-only arguments given to ``ProgressBar``. See `Entry Points`\n\nThese arguments are:\n\n- ``char_bg_color`` Specifies the background color of the filled part of the progressbar. See `Colors` for more information about specifying colors.\n- ``char_fg_color`` Specifies the color of the characters in the filled part of the progressbar. See `Colors` for more information about specifying colors.\n- ``filler_bg_color`` Specifies the background color of the empty part of the progressbar. See `Colors` for more information about specifying colors.\n- ``filler_fg_color`` Specifies the color of the characters in the empty part of the progressbar. See `Colors` for more information about specifying colors.\n\nAll of these arguments default to `None`.\n\n\nGradient type\n^^^^^^^^^^^^^\n\nGradient bar type has different arguments:\n\n- ``start_color`` Specifies the starting color of the bar's gradient. Defaults to `\"red\"`\n- ``end_color`` Specifies the ending color of the bar's gradient. Defaults to `\"green\"`\n\nThese are set the same way as \n\nCreating custom bar types\n-------------------------\n\nIf the built-in bar types are not enough for your needs, you can easily create custom ones using ``create_bar_type()`` function.\nIts arguments are:\n\n- ``char`` Character to be used in the filled part of the progressbar.(required)\n- ``filler`` Character to be used in the empty part of the progressbar.(required)\n- ``name`` `__qualname__` of the returned class. (defaults to \"?\")\n- ``char_bg_color`` See `Arguments` (defaults to `None`)\n- ``char_fg_color`` See `Arguments` (defaults to `None`)\n- ``filler_bg_color`` See `Arguments` (defaults to `None`)\n- ``filler_fg_color`` See `Arguments` (defaults to `None`)\n\nSpinners\n========\n\n*Credit for all spinners except \"loading\" goes to* `Sindre Sorhus <https://github.com/sindresorhus/cli-spinners>`_\n\n*\"loading\" spinner is made by me.*\n\n.. image:: https://fancybar.readthedocs.io/en/latest/_images/spinners.gif\n\nAll spinners are on the GIF above.\nThe spinners not shown are not shown because of the asciinema charset limitations. To get a more acute representation of the spinners, clone the repository and run ``python3 spinner_test.py``.\nThe default spinner is |spinner-line|.\nYou can choose a spinner by setting the argument ``spinner`` of ``ProgressBar`` to its name. See `Entry Points`\n\nChanging spinner speed\n----------------------\n\nIf you don't like the animation speed on your spinner, you can change its speed using the argument ``spinner_speed`` of ``ProgressBar``.\n``spinner_speed`` is the speed of the spinner on the progress bar in revolutions per iteration. Default is ``0.5``.\n\nEntry Points\n============\n\nProgressBar\n-----------\n\nMain entry point of the ``fancybar`` library is the ``ProgressBar`` class.\nIts ``__init__`` function has the following arguments:\n\n- ``items`` (`int`): Required. The number of items the progress bar is running on.\n- ``length`` (`int`): How much space will the progressbar take on screen. Defaults to `50`\n- ``item_name`` (`str`): What abbreviation to use for items in the items/second part of the progress bar. Defaults to `\"it\"`\n- ``spinner`` (`str`): The name of the spinner. See `Spinners`. Default `\"line\"`\n- ``spinner_speed`` (`float` or `int`): The spinner's speed. See `Spinners`. Default `0.5`.\n- ``percentage_bg_color`` (`str` or `tuple` or `None`): What color is to be used for the background color of the percentage part of the progress bar. See `Colors`. Default `None`\n- ``percentage_fg_color`` (`str` or `tuple` or `None`): What color is to be used for the foreground color of the percentage part of the progress bar. See `Colors`. Default `None`\n- ``spinner_bg_color`` (`str` or `tuple` or `None`): What color is to be used for the background color of the spinner part of the progress bar. See `Colors`. Default `None`\n- ``spinner_fg_color`` (`str` or `tuple` or `None`): What color is to be used for the foreground color of the spinner part of the progress bar. See `Colors`. Default `None`.\n- ``bartype`` (`str` or `type`): Bar type for the progress bar. See `Bar Types`. Default `\"full\"`.\n- ``hide_cursor`` (`bool`): Whether or not is the cursor to be hidden during the progress bar's runtime. Default `False`\n\nAll arguments after ``items`` are not required and keyword-only\n\nSequentialProgressBar\n---------------------\n``SequentialProgressBar`` is a subclass of `ProgressBar` that creates progress bars from an iterable sequence. `len()` must be callable upon those sequences.\n``SequentialProgressbar`` replaces `ProgressBar`'s ``items`` argument by a ``seq`` argument -- the sequence you want to create progress bars from. All other arguments are unchanged. \n``bar`` is an alias for ``SequentialProgressBar``, as it is more likely to be used than `ProgressBar`\n\nColors\n======\nColors can be specified by either a color string or a RGB tuple. RGB tuples only work on Truecolor terminals.\n\nColor Strings\n-------------\n\nAll Terminals\n^^^^^^^^^^^^^\n\nThese colors should work on all terminals that support colored output\n\n.. image:: https://fancybar.readthedocs.io/en/latest/_images/colors_main.gif\n\n256-color\n^^^^^^^^^^^^^^^\n\nThese colors work on 256-color type terminals. The ones that are not in `All terminals` might display differently/incorrectly in other terminals.\n\n.. figure:: https://fancybar.readthedocs.io/en/latest/_images/colors.gif\n :align: center\n\nRGB Tuples\n----------\n\nRGB tuples must be in format 0-255 and must not contain alpha part.\nRGB tuples are only supported in Truecolor terminals.\nThey might display differently/incorrectly in other terminals.\n\nRuntime attributes\n==================\n\nWhile your bar is running, you can easily access some of its attributes:\n\n- ``ProgressBar.eta`` - current ETA in seconds \n- ``ProgressBar.percentage`` - current percentage\n- ``ProgressBar.items_done`` - number of items already done\n\n\n\n.. |spinner-line| image:: line-spinner.gif\n\n",
"bugtrack_url": null,
"license": "",
"summary": "A highly customizable terminal progress bar library",
"version": "0.2.0",
"split_keywords": [
"progress bar",
"tui"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "d860d53b66dfd1cd56ed70910dd3a78ff377cc16c06a7dce0eaba1da925c8e98",
"md5": "6d5b05618edcd98ba545d96778e0c45e",
"sha256": "c397c5a71e346dea3a22c0a2ba7cd932ec9be5d9070a8f9091cc53678dc1610a"
},
"downloads": -1,
"filename": "fancybar-0.2.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "6d5b05618edcd98ba545d96778e0c45e",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 12204,
"upload_time": "2023-04-05T14:15:15",
"upload_time_iso_8601": "2023-04-05T14:15:15.912561Z",
"url": "https://files.pythonhosted.org/packages/d8/60/d53b66dfd1cd56ed70910dd3a78ff377cc16c06a7dce0eaba1da925c8e98/fancybar-0.2.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "a3272d91fc1830576a16d4cc11de1ce1858527f843636ef2e5dd26578e12e613",
"md5": "ff35870ed11eb97835e679192a60400b",
"sha256": "125d4512424ced7faed9ecb611c05f330ac96cf0ad08cad34ac622e705e1b77e"
},
"downloads": -1,
"filename": "fancybar-0.2.0.tar.gz",
"has_sig": false,
"md5_digest": "ff35870ed11eb97835e679192a60400b",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 15255,
"upload_time": "2023-04-05T14:15:17",
"upload_time_iso_8601": "2023-04-05T14:15:17.813416Z",
"url": "https://files.pythonhosted.org/packages/a3/27/2d91fc1830576a16d4cc11de1ce1858527f843636ef2e5dd26578e12e613/fancybar-0.2.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-04-05 14:15:17",
"github": true,
"gitlab": false,
"bitbucket": false,
"github_user": "jenca-adam",
"github_project": "fancybar",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "fancybar"
}
JSON
