datalad_next.utils.log_progress

datalad_next.utils.log_progress(lgrcall, pid, *args, **kwargs)[source]

Emit progress log messages

This helper can be used to handle progress reporting without having to maintain display mode specific code.

Typical progress reporting via this function involves three types of calls:

  1. Start reporting progress about a process

  2. Update progress information about a process

  3. Report completion of a process

In order to be able to associate all three steps with a particular process, the pid identifier is used. This is an arbitrary string that must be chosen to be unique across all different, but simultaneously running progress reporting activities within a Python session. For many practical purposes this can be achieved by, for example, including path information in the identifier.

To initialize a progress report this function is called without an update parameter. To report a progress update, this function is called with an update parameter. To finish a reporting on a particular activity a final call without an update parameter is required.

Parameters:

  • lgrcall (callable) -- Something like lgr.debug or lgr.info

  • pid (str) -- Some kind of ID for the process the progress is reported on.

  • *args (str) -- Log message, and potential arguments

  • total (int) -- Max progress quantity of the process.

  • label (str) -- Process description. Should be very brief, goes in front of progress bar on the same line.

  • unit (str) -- Progress report unit. Should be very brief, goes after the progress bar on the same line.

  • update (int) -- To (or by) which quantity to advance the progress. Also see increment.

  • increment (bool) -- If set, update is interpreted as an incremental value, not absolute.

  • initial (int) -- If set, start value for progress bar

  • noninteractive_level (int, optional) -- In a non-interactive session where progress bars are not displayed, only log a progress report, if a logger's effective level includes the specified level. This can be useful logging all progress is inappropriate or too noisy for a log.

  • maint ({'clear', 'refresh'}) -- This is a special attribute that can be used by callers that are not actually reporting progress, but need to ensure that their (console) output does not interfere with any possibly ongoing progress reporting. Setting this attribute to 'clear' will cause the central ProgressHandler to temporarily stop the display of any active progress bars. With 'refresh', all active progress bars will be redisplayed. After a 'clear' individual progress bars would be reactivated upon the next update log message, even without an explicit 'refresh'.