pyreporting.reporting.Reporting#

class Reporting(app_name='pyreporting_default', progress_type=ProgressBarType.TERMINAL, log_file_name=None, debug=False, parent=None, interactive=True)[source]#

Bases: object

Provides error, message and progress reporting.

Reporting is a class used to process errors, warnings, messages, logging information and progress bars. This means that warnings, errors and progress are handled via a callback instead of directly bringing up message boxes and progress boxes or writing to the command window. This allows applications to choose how they process error, warning and progress information.

Typically, a single Reporting object is created during application startup, and passed into the classes and functions that use it. This means that logging and progress reporting are handled in a single place, allowing for consistent behaviour across the application and more advanced features such as nested progress dialogs.

The default Reporting implementation uses the standard python logging library, so standard logging calls should also work.

Progress can be provided via a console progress bar (TerminalProgress) for terminal applications, or a windowed progress bar for GUI applications.

You can create your own implementation of the Reporting interface to get customised message and progress behaviour; for example, if you are running a batch script you may wish it to run silently, whereas for a GUI application you may wish to display error, warning and progress dialogs to the user.

Parameters:

app_name – Application name to use when creating log file directory
progress_type – Either an object implementing the Progress interface, None for no progress, or a ProgressBarType enum which will be used to determine which progress bar to create
log_file_name – Specify log filename instead of using default application log file directory based on app_name
debug – set to True to log debug messages
interactive – set to True if used in an interactive environment, allowing for example windows to be opened

Methods

`advance_progress`	Move the progress bar along one stage
`check_for_cancel`	Raise Cancel exception if user has clicked Cancel in the progress dialog
`complete_progress`	Complete the current progress dialog.
`debug`	Write debugging information to the console and log file
`default_error`	Write an error message to the console and log file.
`default_warning`	Write a warning message to the console and log file
`end_message_caching`	End the message caching started by end_message_caching()
`error`	Write an error message to the console and log file.
`has_been_cancelled`	Return True if the user has clicked Cancel in the progress dialog
`info`	Write an information message to the console and log file
`open_path`	Open an OS window to the specified file path
`reset_progress`	Close all progress bars and clear all progress nesting
`set_progress_parent`	Set the GUI parent window handle for progress dialogs
`start_message_caching`	Enable message caching to prevent duplicate log messages
`start_progress`	Initialise and show progress dialog reporting.
`update_progress`	Update values in the progress dialog
`update_progress_stage`	Update progress for an operation consisting of a set number of stages
`warning`	Write a warning message to the console and log file

Attributes

`CancelErrorId`
`USE_TERMINAL_PROGRESS`

advance_progress(step=None, label=None, title=None)[source]#

Move the progress bar along one stage

Unspecified parameters for step, label or title will retain their previous value.

If step has not been specified in this call or in any previous call for this nested progress bar, it will take an inferred value (if one could be computed), otherwise it will be the difference between the current value (0 if unspecified) and 100%

Parameters:

step – Percentage difference between progress calls. None to keep current step value
label – Text to display in progress bar, or None to keep current or default label
title – Title text for the progress dialog, or None to keep current or default title

check_for_cancel()[source]#: Raise Cancel exception if user has clicked Cancel in the progress dialog

complete_progress()[source]#: Complete the current progress dialog. If there are no other progress bars currently nested then hide the dialog, otherwise return to the parent progress and complete the current stage

debug(message, identifier=None, supplementary_info=None, exception=None)[source]#: Write debugging information to the console and log file

static default_error(message, identifier=None, supplementary_info=None, exception=None, throw=True)[source]#: Write an error message to the console and log file. If throw is True, this will also raise an exception. Where appropriate, the application should catch this exception and present the message to the user e.g. using a modal error dialog

static default_warning(message, identifier=None, supplementary_info=None, exception=None)[source]#: Write a warning message to the console and log file

end_message_caching()[source]#

End the message caching started by end_message_caching()

This will show any pending error or warning log messages, with adjusted message text to show the number of repetitions of duplicate messages.

error(message, identifier=None, supplementary_info=None, exception=None, throw=True)[source]#: Write an error message to the console and log file. If throw is True, this will also raise an exception. Where appropriate, the application should catch this exception and present the message to the user e.g. using a modal error dialog

has_been_cancelled()[source]#

Return True if the user has clicked Cancel in the progress dialog

Return type:: bool

info(message, identifier=None, supplementary_info=None, exception=None)[source]#: Write an information message to the console and log file

open_path(file_path, message)[source]#: Open an OS window to the specified file path

reset_progress()[source]#: Close all progress bars and clear all progress nesting

set_progress_parent(parent)[source]#: Set the GUI parent window handle for progress dialogs

start_message_caching(cache_types=None)[source]#

Enable message caching to prevent duplicate log messages

This typically is used with WARNING and INFO messages.

When caching is on, messages will not be displayed or logged but will be added to the cache.

When show_and_clear_pending_messages() is called, the messages in the cache will be displayed, but messages with the same identifier will only be shown once, with the message modified to show how many times the message was generated.

This helps to stop the command window or log file being overwhelmed with duplicate warning or info messages

Start caching messages of specified types (typically WARNING and INFO). Instead of immediately displaying/logging these messages, they will be grouped to prevent multiple messages of the same type from

Parameters:: cache_types – list of warning levels to cache. Currently supports WARNING and INFO.

start_progress(value=None, step=None, label=None, title=None)[source]#

Initialise and show progress dialog reporting. If a progress dialog is already visible, creates a nested progress level.

Each start_progress() call must be matched by exactly one complete_progress() call

Parameters:

value – Current progress bar value, or set to None for a continuous progress bar (if supported)
step – Percentage difference between progress calls. This is used when calling advance_progress() and for correctly updating nested progress calls
label – Text to display in progress bar, or None to keep current or default label
title – Title text for the progress dialog, or None to keep current or default title

update_progress(value=None, step=None, label=None, title=None)[source]#

Update values in the progress dialog

Unspecified parameters for value, label or title will retain their previous value.

If step is not specified, it will be computed automatically from the difference between previous value updates. The step is used with nested progress (push_progress and pop_progress) so that the range of the nested progress will run between value and value + step

Parameters:

value – Current progress bar value, or set to None for a continuous progress bar (if supported)
step – Percentage difference between progress calls. Used if using advance_progress() and for correctly updating nested progress calls. Computed automatically when using update_progress_stage
label – Text to display in progress bar, or None to keep current or default label
title – Title text for the progress dialog, or None to keep current or default title

update_progress_stage(stage, num_stages, label=None, title=None)[source]#

Update progress for an operation consisting of a set number of stages

Specify the total number of stages to be performed and the current stage number. The value and step will be computed automatically

Unspecified parameters for label or title will retain their previous value

Parameters:

stage – The index of the current stage
num_stages – Total number of stages
label – The label text to display by the progress, or None to keep current text
title – The title of the progress dialog, or None to keep current text

warning(message, identifier=None, supplementary_info=None, exception=None)[source]#: Write a warning message to the console and log file