datalad_core.tests.AuditProgressHandler

class datalad_core.tests.AuditProgressHandler → None

Bases: ProgressHandler

Handler that accumulates reports for subsequent inspection

Instead of reporting or relaying and progress reports received by calling methods of this class, all calls are recorded only. For each method call the full parameter set is captured, together with a timestamp and the caller information (code filename and line number).

Records are grouped by task.

Rendering an instance via str() can provide an overview on what operations were performed, by whom, and with which timing.

register_task(description: str, **kwargs) → Hashable

Make a new task known to the handler

A description identifying the nature of the task is required. This description can be shown by a handler implementation, and helps to label progress bars or to distinuish multiple concurrent tasks.

If available, a total amount of progress to achieve before a task is 100% completed can be given. This enabled a quantification of task completion.

Setting the expect_nonprogress_output flag informs the progress handler that other non-progress communication is to be expects (e.g., input prompts) during the task. A handler implementation that is also using the same channel/terminal for progress rendering can honor this information to avoid conflicting output.

Returns a task identifier.

Return type:

Hashable

remove_completed_task(task_id: Hashable, message: str | None = None) → None

Remove a registered task that was completed

The optional message can be used to describe the result achieved with the completed task.

After removal task_id is no longer a valid task identifier for this handler.

Return type:

None

remove_incomplete_task(task_id: Hashable, message: str | None = None) → None

Remove a registered task that could/was not be completed

The optional message can be used to describe the why the the task could not be completed, and possible the nature of the task, or which aspect of it made a completion impossible.

This message is no a replacement for proper error reporting (e.g., raising an exception). It is useful for informing a user about attempted activities, where their failure does not have immediate consequences (e.g., one attempt out of many, or an optional task).

After removal task_id is no longer a valid task identifier for this handler.

The default implementation calls the remove_completed_task() method.

Return type:

None

update_task(task_id: Hashable, **kwargs) → None

Update a registered task

When called with default parameters, it signals and “activity tick”. If known, the progress amount can be specified via advance.

A quantified progress update can be given as an increment (advance), or as an absolute value (completed). No plausibility checks or adjustments are performed. It is a clients responsibility to use sensible values to, e.g., not exceed a total amount. Using parameters advance and completed simultaneously may result in undefined behavior.

Optionally, all task properties given via register_task() can be updated.

Return type:

None