Coverage for /var/devmt/py/utils4_1.5.0rc1/utils4/progressbar.py: 100%
14 statements
« prev ^ index » next coverage.py v7.6.1, created at 2024-08-12 15:38 +0100
« prev ^ index » next coverage.py v7.6.1, created at 2024-08-12 15:38 +0100
1# -*- coding: utf-8 -*-
2"""
3:Purpose: This is a small class module which provides access to a
4 simple console progress bar.
6:Platform: Linux/Windows | Python 3.6+
7:Developer: J Berendt
8:Email: support@s3dev.uk
10:Comments: n/a
12:Example: For a simple usage example, refer to the :class:`~ProgressBar`
13 class docstring.
15"""
17import sys
20class ProgressBar:
21 """Implement a console progress bar into a processing loop.
23 Args:
24 total_values (int, optional): Total number of iterations.
25 Defaults to 25.
26 bar_len (int, optional): Complete length of the progress bar, in chars.
27 Defaults to 25
28 symbol (str, optional): The symbol which is used to track progress.
29 Defaults to ``'.'``.
30 color (str, optional): Colour of the progress bar; where only the first
31 letter of the colour is required.
32 Options are: red, green, yellow, blue, magenta, cyan, white.
33 Defaults to 'w' (white).
35 :Design:
36 This is a simple console progress bar which should be called
37 **inside** a processing loop.
39 On instantiation, you can pass in the bar colour, length and
40 symbol parameters if you want to configure the appearance a
41 little bit.
43 :Colour Options:
44 red, green, yellow, blue, magenta, cyan, white
46 :Example:
47 You might implement the progress bar in a loop like this::
49 >>> import time
50 >>> from utils4.progressbar import ProgressBar
52 >>> pb = ProgressBar(total_values=25,
53 bar_len=25,
54 symbol='#',
55 color='red')
57 >>> for i range(26):
58 >>> # < some processing >
59 >>> pb.update_progress(current=i)
60 >>> # Optional pause to see updates.
61 >>> time.sleep(.1)
63 Processing 25 of 25 [ ......................... ] 100% Complete
65 """
67 def __init__(self, total_values: int=25, bar_len: int=25, symbol: str='.', color: str='w'):
68 """Progress bar class initialiser."""
69 self._total = total_values
70 self._bar_len = bar_len
71 self._symbol = symbol
72 self._color = color
73 self._len = len(str(self._total))
74 self._rst = '\x1b[0m'
75 self._clr = self._getcolor()
77 def update_progress(self, current: int): # pragma: nocover
78 """Incrementally update the progress bar.
80 Args:
81 current (int): Index value for the current iteration.
82 This value is compared against the initialised ``total_values``
83 parameter to determine the current position in the overall
84 progress.
86 :Example:
88 Refer to the :class:`~ProgressBar` class docstring.
90 """
91 # Calculate percent complete.
92 percent = float(current) / self._total
93 # Number of ticks.
94 ticks = self._symbol * int(round(percent * self._bar_len))
95 # Number of space placeholders.
96 spaces = ' ' * (self._bar_len - len(ticks))
97 msg = (f'{self._clr}'
98 f'\rProcessing {str(current).zfill(self._len)} of {self._total} [ {ticks+spaces} ] '
99 f'{percent*100:.0f}% Complete{self._rst}')
100 sys.stdout.write(msg)
101 sys.stdout.flush()
103 def _getcolor(self) -> str:
104 """Create ANSI colour escape sequence to user's colour.
106 Returns:
107 str: ANSI escape sequence string for the user's colour.
109 """
110 clrs = {'r': 31, 'g': 32, 'y': 33, 'b': 34, 'm': 35, 'c': 36, 'w': 37}
111 seq = f'\033[{clrs.get(self._color[0])};40m'
112 return seq