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.core import SubApp
from ae.progress import Progress
app = SubApp(...)
...
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 the
instance of the application class (either AppBase
,
SubApp
or 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 flexible 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
- start -
- end -
end_msg
finished message (printed on call of
finished()
)
- end -
- error -
err_msg
error message on any occurring error (printed on each call of either
next()
orfinished()
)
- error -
- nothing-to_do -
nothing_to_do_msg
nothing-to-do message printed on process start (class instantiation) if total count is zero
- nothing-to_do -
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
|
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='')[source]
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='')[source]
prepare print-outs for a new progress (long running process with incrementing or decrementing item counter).
- Parameters:
app_base¶ (
AppBase
) – 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 ofnext()
(iftotal_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 ofnext()
.delta¶ (
int
) – difference to decrement/increment on each call ofnext()
.start_msg¶ (
str
) – start message template with placeholders.next_msg¶ (
Optional
[str
]) – next message - if an empty string get passed then a default message will be provided with placeholders - pass None if you want to suppress the print-out of a next message.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).nothing_to_do_msg¶ (
str
) – message template printed-out if the values of the two argumentsstart_counter
andtotal_count
are not specified or are both less or equal to zero.
- _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)[source]
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='')[source]
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.