# progress1bar
[](https://github.com/soda480/progress1bar/actions/workflows/main.yml)
[](https://radon.readthedocs.io/en/latest/api.html#module-radon.complexity)
[](https://pybuilder.io/)
[](https://pypi.org/project/bandit/)
[](https://badge.fury.io/py/progress1bar)
[](https://www.python.org/downloads/)
A customizable ANSI-based progress bar.
## Installation
```bash
pip install progress1bar
```
### `ProgressBar`
```
ProgressBar(
total=None,
fill=None,
regex=None,
completed_message=None,
clear_alias=False,
show_prefix=True,
show_fraction=True,
show_percentage=True,
show_duration=False,
show_complete=True,
ticker=None,
use_color=True,
show_bar=True)
```
<details><summary>Documentation</summary>
> `total` - An integer for the total number of items the progress bar will show that need to be completed.
> `fill` - A dictionary whose key values are integers that dictate the number of leading zeros the progress bar should add to the `total` and `completed` values; this is optional and should be used to format the progress bar appearance. The supported key values are `max_total` and `max_completed`.
> `regex` - A dictionary whose key values are regular expressions for `total`, `count` and `alias`. The regular expressions will be checked against the log messages intercepted from the executing function, if matched the value will be used to assign the attribute for the respective progress bar. The `total` and `count` key values are required, the `alias` key value is optional.
> `completed_message` - A string to designate the message the progress bar should display when complete. Default is 'Processing complete'
> `clear_alias` - A boolean to designate if the progress bar should clear the alias when complete.
> `show_prefix` - A boolean to designate if the prefix of `Processing ` should be printed prefixing the progress bar.
> `show_fraction` - A boolean to designate if the fraction should be printed with the progress bar.
> `show_percentage` - A boolean to designate if the percentage should be printed with the progress bar.
> `show_duration` - A boolean to designate if the duration should be printed after progress bar execution.
> `show_complete` - A boolean to designate if the completed message is to be displayed upon progress bar completion.
> `ticker` - A integer representing unicode character to print as the progress bar ticker. Refer to [unicode chart](https://www.ssec.wisc.edu/~tomw/java/unicode.html) for values. Default is 9632 (black square ■).
> `use_color` - A boolean to designate if the progress bar should be displayed with color. Default is `True`.
> `show_bar` - A boolean to designate if the progress bar tickers should be printed.
**Attributes**
> `count` - An integer attribute to increment that designates the current count. When count reaches total the progress bar will show complete.
> `alias` - A string attribute to set the alias of the progress bar.
**Functions**
> **reset()**
>> Reset the progress bar so that it can be used again. It will maintain and show the number of times the progress bar has been used.
</details>
### Examples
Various [examples](https://github.com/soda480/progress1bar/tree/master/examples) are included to demonstrate the progress1bar package. To run the examples, build the Docker image and run the Docker container using the instructions described in the [Development](#development) section.
#### [example1](https://github.com/soda480/progress1bar/tree/master/examples/example1.py)
The `ProgressBar` class is used to display function execution as a progress bar. Use it as a context manager, and simply set the `.total` and `.count` attributes accordingly. Here is an example:
```Python
import time
from progress1bar import ProgressBar
with ProgressBar(total=250) as pb:
for _ in range(pb.total):
pb.count += 1
# simulate work
time.sleep(.01)
```
#### [example2](https://github.com/soda480/progress1bar/tree/master/examples/example2.py)
Configure `ProgressBar` to display an alias for the item that is currently being processed by setting the `alias` parameter:
```Python
import time
from faker import Faker
from progress1bar import ProgressBar
kwargs = {
'total': 75,
'completed_message': 'Processed names complete',
'clear_alias': True,
'show_fraction': False,
'show_prefix': False,
'show_duration': True
}
with ProgressBar(**kwargs) as pb:
for _ in range(pb.total):
pb.alias = Faker().name()
# simulate work
time.sleep(.08)
pb.count += 1
```
#### [example2b](https://github.com/soda480/progress1bar/tree/master/examples/example2b.py)
Configure `ProgressBar` to display an alias for the item that is currently being processed, but do not print out the ticker, instead show percentage and fraction complete:
```Python
from faker import Faker
from progress1bar import ProgressBar
kwargs = {
'total': 575,
'clear_alias': True,
'show_complete': False,
'show_prefix': False,
'show_duration': True,
'show_bar': False
}
with ProgressBar(**kwargs) as pb:
for _ in range(pb.total):
pb.alias = Faker().sentence()
# simulate work
pb.count += 1
```
#### [example3](https://github.com/soda480/progress1bar/tree/master/examples/example3.py)
Configure `ProgressBar` with a custom ticker, show duration, do not use color, and use regular expressions to determine the `total`, `count` and `alias` attributes:
```Python
import random
from faker import Faker
from progress1bar import ProgressBar
kwargs = {
'ticker': 9733,
'regex': {
'total': r'^processing total of (?P<value>\d+)$',
'count': r'^processed .*$',
'alias': r'^processor is (?P<value>.*)$'
},
'use_color': False,
'show_duration': False
}
with ProgressBar(**kwargs) as pb:
pb.match(f'processor is {Faker().name()}')
total = random.randint(500, 750)
pb.match(f'processing total of {total}')
for _ in range(total):
pb.match(f'processed {Faker().name()}')
```
#### [example4](https://github.com/soda480/progress1bar/tree/master/examples/example4.py)
Configure `ProgressBar` to show and reuse progress for several iterations:
```Python
import random
import time
from faker import Faker
from progress1bar import ProgressBar
TOTAL_ITEMS = 300
ITERATIONS = 4
kwargs = {
'show_prefix': False,
'show_fraction': False,
'show_duration': True
}
print(f'Execute {ITERATIONS} iterations of varying totals:')
with ProgressBar(**kwargs) as pb:
iterations = 0
while True:
if iterations == ITERATIONS:
pb.alias = ''
pb.complete = True
break
pb.alias = Faker().name()
pb.total = random.randint(100, TOTAL_ITEMS)
for _ in range(pb.total):
Faker().name()
pb.count += 1
iterations += 1
pb.reset()
time.sleep(.4)
```
### Programs using `progress1bar`
* [pypbars](https://pypi.org/project/pypbars/)
* [mppbar](https://pypi.org/project/mppbar/)
## Development ##
Clone the repository and ensure the latest version of Docker is installed on your development server.
Build the Docker image:
```sh
docker image build \
-t progress1bar:latest .
```
Run the Docker container:
```sh
docker container run \
--rm \
-it \
-v $PWD:/code \
progress1bar:latest \
bash
```
Execute the build:
```sh
pyb -X
```
Raw data
{
"_id": null,
"home_page": "https://github.com/soda480/progress1bar",
"name": "progress1bar",
"maintainer": null,
"docs_url": null,
"requires_python": null,
"maintainer_email": null,
"keywords": null,
"author": "Emilio Reyes",
"author_email": "soda480@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/1c/9b/f8d93874ff215ca4c651326b922fc6b92232ba03739f4ca3c4a34c3b3dcc/progress1bar-0.4.3.tar.gz",
"platform": null,
"description": "# progress1bar\n[](https://github.com/soda480/progress1bar/actions/workflows/main.yml)\n[](https://radon.readthedocs.io/en/latest/api.html#module-radon.complexity)\n[](https://pybuilder.io/)\n[](https://pypi.org/project/bandit/)\n[](https://badge.fury.io/py/progress1bar)\n[](https://www.python.org/downloads/)\n\nA customizable ANSI-based progress bar.\n\n## Installation\n```bash\npip install progress1bar\n```\n\n### `ProgressBar`\n\n```\nProgressBar(\n total=None,\n fill=None,\n regex=None,\n completed_message=None,\n clear_alias=False,\n show_prefix=True,\n show_fraction=True,\n show_percentage=True,\n show_duration=False,\n show_complete=True,\n ticker=None,\n use_color=True,\n show_bar=True)\n```\n\n<details><summary>Documentation</summary>\n\n> `total` - An integer for the total number of items the progress bar will show that need to be completed.\n\n> `fill` - A dictionary whose key values are integers that dictate the number of leading zeros the progress bar should add to the `total` and `completed` values; this is optional and should be used to format the progress bar appearance. The supported key values are `max_total` and `max_completed`.\n\n> `regex` - A dictionary whose key values are regular expressions for `total`, `count` and `alias`. The regular expressions will be checked against the log messages intercepted from the executing function, if matched the value will be used to assign the attribute for the respective progress bar. The `total` and `count` key values are required, the `alias` key value is optional.\n\n> `completed_message` - A string to designate the message the progress bar should display when complete. Default is 'Processing complete'\n\n> `clear_alias` - A boolean to designate if the progress bar should clear the alias when complete.\n\n> `show_prefix` - A boolean to designate if the prefix of `Processing ` should be printed prefixing the progress bar.\n\n> `show_fraction` - A boolean to designate if the fraction should be printed with the progress bar.\n\n> `show_percentage` - A boolean to designate if the percentage should be printed with the progress bar.\n\n> `show_duration` - A boolean to designate if the duration should be printed after progress bar execution.\n\n> `show_complete` - A boolean to designate if the completed message is to be displayed upon progress bar completion.\n\n> `ticker` - A integer representing unicode character to print as the progress bar ticker. Refer to [unicode chart](https://www.ssec.wisc.edu/~tomw/java/unicode.html) for values. Default is 9632 (black square \u25a0).\n\n> `use_color` - A boolean to designate if the progress bar should be displayed with color. Default is `True`.\n\n> `show_bar` - A boolean to designate if the progress bar tickers should be printed.\n\n**Attributes**\n\n> `count` - An integer attribute to increment that designates the current count. When count reaches total the progress bar will show complete.\n\n> `alias` - A string attribute to set the alias of the progress bar.\n\n**Functions**\n\n> **reset()**\n>> Reset the progress bar so that it can be used again. It will maintain and show the number of times the progress bar has been used.\n\n</details>\n\n\n### Examples\n\nVarious [examples](https://github.com/soda480/progress1bar/tree/master/examples) are included to demonstrate the progress1bar package. To run the examples, build the Docker image and run the Docker container using the instructions described in the [Development](#development) section.\n\n#### [example1](https://github.com/soda480/progress1bar/tree/master/examples/example1.py)\n\nThe `ProgressBar` class is used to display function execution as a progress bar. Use it as a context manager, and simply set the `.total` and `.count` attributes accordingly. Here is an example:\n\n```Python\nimport time\nfrom progress1bar import ProgressBar\n\nwith ProgressBar(total=250) as pb:\n for _ in range(pb.total):\n pb.count += 1\n # simulate work\n time.sleep(.01)\n```\n\n\n\n#### [example2](https://github.com/soda480/progress1bar/tree/master/examples/example2.py)\n\nConfigure `ProgressBar` to display an alias for the item that is currently being processed by setting the `alias` parameter:\n\n```Python\nimport time\nfrom faker import Faker\nfrom progress1bar import ProgressBar\n\nkwargs = {\n 'total': 75,\n 'completed_message': 'Processed names complete',\n 'clear_alias': True,\n 'show_fraction': False,\n 'show_prefix': False,\n 'show_duration': True\n}\nwith ProgressBar(**kwargs) as pb:\n for _ in range(pb.total):\n pb.alias = Faker().name()\n # simulate work\n time.sleep(.08)\n pb.count += 1\n```\n\n\n\n#### [example2b](https://github.com/soda480/progress1bar/tree/master/examples/example2b.py)\n\nConfigure `ProgressBar` to display an alias for the item that is currently being processed, but do not print out the ticker, instead show percentage and fraction complete:\n\n```Python\nfrom faker import Faker\nfrom progress1bar import ProgressBar\n\nkwargs = {\n 'total': 575,\n 'clear_alias': True,\n 'show_complete': False,\n 'show_prefix': False,\n 'show_duration': True,\n 'show_bar': False\n}\nwith ProgressBar(**kwargs) as pb:\n for _ in range(pb.total):\n pb.alias = Faker().sentence()\n # simulate work\n pb.count += 1\n```\n\n\n\n\n#### [example3](https://github.com/soda480/progress1bar/tree/master/examples/example3.py)\n\nConfigure `ProgressBar` with a custom ticker, show duration, do not use color, and use regular expressions to determine the `total`, `count` and `alias` attributes:\n\n```Python\nimport random\nfrom faker import Faker\nfrom progress1bar import ProgressBar\n\nkwargs = {\n 'ticker': 9733,\n 'regex': {\n 'total': r'^processing total of (?P<value>\\d+)$',\n 'count': r'^processed .*$',\n 'alias': r'^processor is (?P<value>.*)$'\n },\n 'use_color': False,\n 'show_duration': False\n}\nwith ProgressBar(**kwargs) as pb:\n pb.match(f'processor is {Faker().name()}')\n total = random.randint(500, 750)\n pb.match(f'processing total of {total}')\n for _ in range(total):\n pb.match(f'processed {Faker().name()}')\n\n```\n\n\n\n#### [example4](https://github.com/soda480/progress1bar/tree/master/examples/example4.py)\n\nConfigure `ProgressBar` to show and reuse progress for several iterations:\n\n```Python\nimport random\nimport time\nfrom faker import Faker\nfrom progress1bar import ProgressBar\n\nTOTAL_ITEMS = 300\nITERATIONS = 4\nkwargs = {\n 'show_prefix': False,\n 'show_fraction': False,\n 'show_duration': True\n}\nprint(f'Execute {ITERATIONS} iterations of varying totals:')\nwith ProgressBar(**kwargs) as pb:\n iterations = 0\n while True:\n if iterations == ITERATIONS:\n pb.alias = ''\n pb.complete = True\n break\n pb.alias = Faker().name()\n pb.total = random.randint(100, TOTAL_ITEMS)\n for _ in range(pb.total):\n Faker().name()\n pb.count += 1\n iterations += 1\n pb.reset()\n time.sleep(.4)\n```\n\n\n\n### Programs using `progress1bar`\n\n* [pypbars](https://pypi.org/project/pypbars/)\n* [mppbar](https://pypi.org/project/mppbar/)\n\n## Development ##\n\nClone the repository and ensure the latest version of Docker is installed on your development server.\n\nBuild the Docker image:\n```sh\ndocker image build \\\n-t progress1bar:latest .\n```\n\nRun the Docker container:\n```sh\ndocker container run \\\n--rm \\\n-it \\\n-v $PWD:/code \\\nprogress1bar:latest \\\nbash\n```\n\nExecute the build:\n```sh\npyb -X\n```\n",
"bugtrack_url": null,
"license": "Apache License, Version 2.0",
"summary": "A customizable ANSI-based progress bar",
"version": "0.4.3",
"project_urls": {
"Homepage": "https://github.com/soda480/progress1bar"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "8d768c78881dfe012b2222679b166e61dca3e12356aeee6ffb7a6627b888dbae",
"md5": "c359b20c8bd5d0f1d9348322fbed360f",
"sha256": "cf6ec26fb1b44a6cb1fa1d89167d03d30d7db5c262980af0b8d7a896ddd47dc3"
},
"downloads": -1,
"filename": "progress1bar-0.4.3-py3-none-any.whl",
"has_sig": false,
"md5_digest": "c359b20c8bd5d0f1d9348322fbed360f",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 10077,
"upload_time": "2025-01-04T22:08:16",
"upload_time_iso_8601": "2025-01-04T22:08:16.885985Z",
"url": "https://files.pythonhosted.org/packages/8d/76/8c78881dfe012b2222679b166e61dca3e12356aeee6ffb7a6627b888dbae/progress1bar-0.4.3-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "1c9bf8d93874ff215ca4c651326b922fc6b92232ba03739f4ca3c4a34c3b3dcc",
"md5": "2c6bbddfc676e39388cdcecc48b59585",
"sha256": "71eec7cad2c40b0326b0b3c76229584d1e6387d9a10c0bb54e9e457832edc304"
},
"downloads": -1,
"filename": "progress1bar-0.4.3.tar.gz",
"has_sig": false,
"md5_digest": "2c6bbddfc676e39388cdcecc48b59585",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 10384,
"upload_time": "2025-01-04T22:08:18",
"upload_time_iso_8601": "2025-01-04T22:08:18.044733Z",
"url": "https://files.pythonhosted.org/packages/1c/9b/f8d93874ff215ca4c651326b922fc6b92232ba03739f4ca3c4a34c3b3dcc/progress1bar-0.4.3.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-01-04 22:08:18",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "soda480",
"github_project": "progress1bar",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [
{
"name": "cursor",
"specs": []
},
{
"name": "colorama",
"specs": []
}
],
"lcname": "progress1bar"
}
JSON
