b.u.UIFactory(object) : class documentation

Part of bzrlib.ui View In Hierarchy

Known subclasses: bzrlib.tests.testui.ProgressRecordingUIFactory, bzrlib.ui.NoninteractiveUIFactory, bzrlib.ui.text.TextUIFactory

UI abstraction.

This tells the library how to display things to the user. Through this layer different applications can choose the style of UI.

UI Factories are also context managers, for some syntactic sugar some users need.

Instance Variablessuppressed_warningsIdentifiers for user warnings that should no be emitted.
Method __init__ Undocumented
Method __enter__ Context manager entry support.
Method __exit__ Context manager exit support.
Method be_quiet Tell the UI to be more quiet, or not.
Method confirm_action Seek user confirmation for an action.
Method get_password Prompt the user for a password.
Method is_quiet Undocumented
Method make_output_stream Get a stream for sending out bulk text data.
Method nested_progress_bar Return a nested progress bar.
Method clear_term Prepare the terminal for output.
Method format_user_warning Undocumented
Method choose Prompt the user for a list of alternatives.
Method get_boolean Get a boolean question answered from the user.
Method get_integer Get an integer from the user.
Method make_progress_view Construct a new ProgressView object for this UI.
Method recommend_upgrade Recommend the user upgrade a control directory.
Method report_transport_activity Called by transports as they do IO.
Method log_transport_activity Write out whatever transport activity has been measured.
Method show_user_warning Show a warning to the user.
Method show_error Show an error message (not an exception) to the user.
Method show_message Show a message to the user.
Method show_warning Show a warning to the user.
Method _make_output_stream_explicit Undocumented
Method _progress_finished Called by the ProgressTask when it finishes
Method _progress_all_finished Called when the top-level progress task finished
Method _progress_updated Called by the ProgressTask when it changes.
def __init__(self):
Undocumented
def __enter__(self):
Context manager entry support.

Override in a concrete factory class if initialisation before use is needed.

def __exit__(self, exc_type, exc_val, exc_tb):
Context manager exit support.

Override in a concrete factory class if more cleanup than a simple self.clear_term() is needed when the UIFactory is finished with.

def be_quiet(self, state):
Tell the UI to be more quiet, or not.

Typically this suppresses progress bars; the application may also look at ui_factory.is_quiet().

def confirm_action(self, prompt, confirmation_id, prompt_kwargs):
Seek user confirmation for an action.

If the UI is noninteractive, or the user does not want to be asked about this action, True is returned, indicating bzr should just proceed.

The confirmation id allows the user to configure certain actions to always be confirmed or always denied, and for UIs to specialize the display of particular confirmations.

ParameterspromptSuggested text to display to the user.
prompt_kwargsA dictionary of arguments that can be string-interpolated into the prompt.
confirmation_idUnique string identifier for the confirmation.
def get_password(self, prompt=u'', **kwargs):
Prompt the user for a password.
ParameterspromptThe prompt to present the user (must be unicode)
kwargsArguments which will be expanded into the prompt. This lets front ends display different things if they so choose.
ReturnsThe password string, return None if the user canceled the request. Note that we do not touch the encoding, users may have whatever they see fit and the password should be transported as is.
def is_quiet(self):
Undocumented
def make_output_stream(self, encoding=None, encoding_type=None):
Get a stream for sending out bulk text data.

This is used for commands that produce bulk text, such as log or diff output, as opposed to user interaction. This should work even for non-interactive user interfaces. Typically this goes to a decorated version of stdout, but in a GUI it might be appropriate to send it to a window displaying the text.

ParametersencodingUnicode encoding for output; if not specified uses the configured 'output_encoding' if any; otherwise the terminal encoding. (See get_terminal_encoding.)
encoding_typeHow to handle encoding errors: replace/strict/escape/exact. Default is replace.
def _make_output_stream_explicit(self, encoding, encoding_type):
Undocumented
def nested_progress_bar(self):
Return a nested progress bar.

When the bar has been finished with, it should be released by calling bar.finished().

def _progress_finished(self, task):
Called by the ProgressTask when it finishes
def _progress_all_finished(self):
Called when the top-level progress task finished
def _progress_updated(self, task):
Called by the ProgressTask when it changes.

Should be specialized to draw the progress.

def clear_term(self):
Prepare the terminal for output.

This will, for example, clear text progress bars, and leave the cursor at the leftmost position.

def format_user_warning(self, warning_id, message_args):
Undocumented
def choose(self, msg, choices, default=None):
Prompt the user for a list of alternatives.

        :param msg: message to be shown as part of the prompt.

        :param choices: list of choices, with the individual choices separated
            by '
', e.g.: choose("Save changes?", "&Yes
&No
&Cancel"). The
            letter after the '&' is the shortcut key for that choice. Thus you
            can type 'c' to select "Cancel".  Shorcuts are case insensitive.
            The shortcut does not need to be the first letter. If a shorcut key
            is not provided, the first letter for the choice will be used.

        :param default: default choice (index), returned for example when enter
            is pressed for the console version.

        :return: the index fo the user choice (so '0', '1' or '2' for
            respectively yes/no/cancel in the previous example).
        
def get_boolean(self, prompt):
Get a boolean question answered from the user.
Parametersprompta message to prompt the user with. Should be a single line without terminating n.
ReturnsTrue or False for y/yes or n/no.
def get_integer(self, prompt):
Get an integer from the user.
Parametersprompta message to prompt the user with. Could be a multi-line prompt but without a terminating n.
ReturnsA signed integer.
def make_progress_view(self):
Construct a new ProgressView object for this UI.

Application code should normally not call this but instead nested_progress_bar().

def recommend_upgrade(self, current_format_name, basedir):
Recommend the user upgrade a control directory.
Parameterscurrent_format_nameDescription of the current format
basedirLocation of the control dir
def report_transport_activity(self, transport, byte_count, direction):
Called by transports as they do IO.

This may update a progress bar, spinner, or similar display. By default it does nothing.

def log_transport_activity(self, display=False):
Write out whatever transport activity has been measured.

Implementations are allowed to do nothing, but it is useful if they can write a line to the log file.

ParametersdisplayIf False, only log to disk, if True also try to display a message to the user.
ReturnsNone
def show_user_warning(self, warning_id, **message_args):
Show a warning to the user.

This is specifically for things that are under the user's control (eg outdated formats), not for internal program warnings like deprecated APIs.

This can be overridden by UIFactory subclasses to show it in some appropriate way; the default UIFactory is noninteractive and does nothing. format_user_warning maps it to a string, though other presentations can be used for particular UIs.

Parameterswarning_idAn identifier like 'cross_format_fetch' used to check if the message is suppressed and to look up the string.
message_argsArguments to be interpolated into the message.
def show_error(self, msg):
Show an error message (not an exception) to the user.

The message should not have an error prefix or trailing newline. That will be added by the factory if appropriate.

def show_message(self, msg):
Show a message to the user.
def show_warning(self, msg):
Show a warning to the user.
API Documentation for Bazaar, generated by pydoctor at 2022-06-16 00:25:16.