ae.progress

display progress of long-running processes

this module is simplifying the display of progress messages on the command console/shell of your OS for long-running processes.

basic usage of progress portion

create an instance of the Progress for each process/thread your application spawns:

from ae.console import ConsoleApp
from ae.progress import Progress

app = ConsoleApp(...)
...
progress = Progress(app, ...)

now you can call the next() method within your long-running process on each processed item/percentage:

while process_is_not_finished:
    ...
    progress.next()

optionally you can request to print an end-message by calling the finished() method of your Progress instance as soon as the process is finished:

...
progress.finished()

the above code snippets are printing a start message to your console at the instantiation of Progress. then every call of the method next() will print the next message and finally the method finished() will print an end message.

to use the integrated error counter and automatic printout of an error message to the console, pass the message text of any occurring error to the argument error_msg of next() or finished().

progress instantiation

the first argument expects an instance of an application class (e.g. ConsoleApp) that spawns the process.

the next three arguments are configuring a run or item counter. and the other arguments may be used to adopt the format of the displayed messages to your needs.

process run counter

depending on the type of process you want to show progress differently, e.g. on each processed item or after passing a certain percentage value and either as incrementing or decrementing number. for that Progress provides a counter which can be configured with the arguments start_counter and total_count.

specifying only start_counter results in a countdown. e.g. to display the number of items waiting to be processed::.

progress = Progress(app, number_of_items_to_be_processed)

by only specifying total_count you get an incremental process run counter:

progress = Progress(app, total_count=number_of_items_to_be_processed)

to display a percentage on the console in 5 percent steps specify total_count as 100 percent and delta as +5:

progress = Progress(app, total_count=100, delta=5)

individual message templates

progress displays 5 types of messages on the console. to overwrite one of the generic default message templates, simply pass your template on instantiation of Progress into the argument that is displayed underneath directly after the message type:

• start - start_msg

  start message printed on process start and class instantiation

• next - next_msg

  next run message (printed on each call of next())

• end - end_msg

  finished message (printed on call of finished())

• error - err_msg

  error message on any occurring error (printed on each call of either next() or finished())

• nothing-to_do - nothing_to_do_msg

  nothing-to-do message printed on process start (class instantiation) if total count is zero

the following table shows which progress state placeholders you can use in which message type:

placeholder	available in message type
run_counter	start, next, end, error
total_count	start, next, end, error
processed_id	next, end, error
err_counter	next, end, error
err_msg	next, end, error

Hint

only the nothing-to-do message type does not provide any placeholders.

Classes

Progress(app_base[, start_counter, ...])

display progress on the console/log output for a long-running tasks.

class Progress(app_base, start_counter=0, total_count=0, delta=-1, start_msg='', next_msg='', end_msg='Finished processing of {total_count} having {err_counter} failures:¡{err_msg}!', err_msg='{err_counter} errors on processing {total_count} items, current={run_counter}:¡{err_msg}!', nothing_to_do_msg='')

Bases: object

display progress on the console/log output for a long-running tasks.

__init__(app_base, start_counter=0, total_count=0, delta=-1, start_msg='', next_msg='', end_msg='Finished processing of {total_count} having {err_counter} failures:¡{err_msg}!', err_msg='{err_counter} errors on processing {total_count} items, current={run_counter}:¡{err_msg}!', nothing_to_do_msg='')

prepare print-outs for a new progress (long-running process with incrementing or decrementing item counter).

Parameters:

• app_base (ConsoleApp) – instance of the application class that is spawning the long-running process.

• start_counter (int) – process item counter start value. counter decrements on each call of next() (if total_count not specified).

• total_count (int) – number of items that will be processed with an incrementing counter. by passing a positive integer the process item counter will be incremented on each call of next().

• delta (int) – difference to decrement/increment on each call of next().

• start_msg (str) – start message template with placeholders.

• next_msg (str) – next message - if not specified or an empty string get passed then a default message will be provided with placeholders.

• end_msg (str) – end message template with placeholders, pass None if you want to suppress the print-out of an end message (in this case only a new line will be printed).

• err_msg (str) – error message template with placeholders.

• nothing_to_do_msg (str) – message template printed-out if the values of the two arguments start_counter and total_count are not specified or are both less or equal to zero.

_app: ConsoleApp

used application class instance

_next_msg

next message template

_end_msg

end message template

_err_msg

error message template

_err_counter

error counter

_run_counter

item, percentage or run counter

_total_count

total count of item/percentage/run counter

_delta

delta value to increment/decrement run counter

next(processed_id='', error_msg='', next_msg='', delta=0)

log the processing of the next item of this long-running task.

Parameters:

• processed_id (str) – id(s) of the next item (to be displayed on console/logging output).

• error_msg (str) – pass the error message to display if the next item produced any errors. if an error message get passed then the _err_counter will be incremented.

• next_msg (str) – message to output (use instance message if not passed/empty).

• delta (int) – delta for decrement/increment process run counter (use instance default if not passed).

finished(processed_id='', error_msg='')

display end of processing for the current item.

Parameters:

• processed_id (str) – id(s) of the next item (to be displayed on console/logging output).

• error_msg (str) – optional error message to display if current items produced any error. if an error message get passed then the _err_counter will be incremented.

get_end_message(processed_id='', error_msg='')

determine message text for finishing the currently processed item.

Parameters:

• processed_id (str) – id(s) of the next item (to be displayed on console/logging output).

• error_msg (str) – optional error message to display if current items produced any error.

Return type:

str

Returns:

message text to display.