status_bar

status_bar

The agutil module includes the class, status_bar. A status_bar instance provides a status indicator which can be updated at any time. The display is only updated when necessary, so there is minimal drawback for updating the instance frequently

API

• status_bar(maximum, show_percent=True, init=True, prepend="", append="", cols=int(get\_terminal\_size()[0]/2), update_threshold=.00005, debugging=False, file=None): (Constructor)

  Creates a new status_bar instance ranging from 0 to maximum. show_percent toggles whether or not a percentage meter should be displayed to the right of the bar. init sets whether or not the status_bar should immediately display. If set to false, the bar is displayed at the first update. prepend is text to be prepended to the left of the bar. It will always remain to the left of the bar as the display updates. WARNING Prepended text offsets the bar. If any part of the bar (including prepended or appended text) extends beyond a single line on the console, the status bar will not display properly. Prepended text should be kept short. append is text to be appended to the right of the bar. It will always remain to the right of the bar as the display updates. WARNING Appended text extends the display. If any part of the bar (including prepended or appended text) extends beyond a single line of the console, the status bar will not display properly. Appended text should be kept short. cols sets how long the bar should be. It defaults to half the terminal size. update_threshold sets the minimum change in percentage to trigger an update to the percentage meter. debugging triggers the status_bar to never print to stdout. If set true, no output will be produced, but exact string of what would be displayed is maintained at all times in the display attribute. file sets the file object where the status bar will be displayed. If file is None (default), the status_bar will use sys.stdout

• status_bar.iter(iterable, maximum=None, iter_debug=False, **kwargs): (Classmethod, Generator)

  Takes an iterable and yields elements from it while updating a status bar automatically. The maximum argument is used to set the maximum of the created status bar. If maximum is omitted or None, len() will be called on the iterable to determine its size. If iter_debug is True, this method will first yield the status bar before iterating over elements of the provided iterable (for debugging purposes). kwargs are passed to the status_bar constructor.

• status_bar.update(value=None):

  updates the display iff value would require a change in the length of the progress bar, or if it changes the percentage readout by at least update_threshold. If value is None, the bar's current value will be incremented by one.

• status_bar.clear(erase=True):

  Clears the readout from stdout. If erase is true, the readout is cleared entirely. Otherwise, the cursor position is simply reset to the front of the bar, which will overwrite characters in the readout with subsequent output to stdout by any source

• status_bar.prepend(text, updateText=True):

  Displays text to the left of the bar. It will always remain to the left of the bar as the display updates. WARNING Prepended text offsets the bar. If any part of the bar (including prepended or appended text) extends beyond a single line on the console, the status bar will not display properly. Prepended text should be kept short. If updateText is True, the display is immediately re-drawn to reflect the new text. Otherwise, the display will wait until the next time update() is called before updating the text

• status_bar.append(text, updateText=True):

  Displays text to the right of the bar. It will always remain to the right of the bar as the display updates. WARNING Appended text extends the display. If any part of the bar (including prepended or appended text) extends beyond a single line of the console, the status bar will not display properly. Appended text should be kept short. If updateText is True, the display is immediately re-drawn to reflect the new text. Otherwise, the display will wait until the next time update() is called before updating the text

• status_bar.__enter__(): (Context manager entry)

  Immediately initializes the display and returns the status_bar object

• status_bar.__exit__(self, type, value, traceback): (Context manager exit)

  Clears and erases the display

• status_bar.passthrough(value):

  Returns value unchaged, but increments the status_bar by 1. Useful for updating a bar in list certain comprehensions where status_bar.iter is infeasible.