userinterfaces — User interfaces#

User interfaces module.

The user interface object must define its own init_handlers() method which takes the root logger as its only argument, and which adds to that logger whatever handlers and formatters are needed to process output and display it to the user. The default (terminal) interface sends level STDOUT to sys.stdout (as all interfaces should) and sends all other levels to sys.stderr; levels WARNING and above are labeled with the level name.

UserInterface objects must also define methods input(), input_choice(), input_list_choice(), output() and editText(), all of which are documented in the abstract class userinterfaces._interface_base.ABUIC.

_interface_base — Abstract User Interface#

Abstract base user interface module.

Added in version 6.2.

class userinterfaces._interface_base.ABUIC[source]#

Bases: ABC

Abstract base user interface class.

Every user interface should derive from it to ensure that all required methods are implemented.

Added in version 6.2.

argvu()[source]#

Return copy of sys.argv.

Assigned to pywikibot.argvu in bot module

Return type:

list[str]

abstract flush()[source]#

Flush cached output.

May be passed to atexit.register() to flush any ui cache.

Return type:

None

abstract init_handlers(*args, **kwargs)[source]#

Initialize the handlers for user output.

Called in bot.init_handlers().

Return type:

None

abstract input(*args, **kwargs)[source]#

Ask the user a question and return the answer.

Called by bot.input().

Return type:

str

abstract input_choice(*args, **kwargs)[source]#

Ask the user and returns a value from the options.

Called by bot.input_choice().

Return type:

int | str

abstract input_list_choice(*args, **kwargs)[source]#

Ask the user to select one entry from a list of entries.

Called by bot.input_list_choice().

Return type:

Any

abstract output(*args, **kwargs)[source]#

Output text to a stream.

Return type:

None

terminal_interface module — Terminal User Interface#

Platform independent terminal interface module.

It imports the appropriate operating system specific implementation.

userinterfaces.terminal_interface.UI#

alias of UnixUI

terminal_interface_base — Base Terminal Interface#

Base for terminal user interfaces.

class userinterfaces.terminal_interface_base.MaxLevelFilter(level=None)[source]#

Bases: object

Filter that only passes records at or below a specific level.

Note

setting handler level only passes records at or above a specified level, so this provides the opposite functionality.

filter(record)[source]#

Return true if the level is below or equal to the set level.

class userinterfaces.terminal_interface_base.TerminalHandler(UI, stream=None)[source]#

Bases: StreamHandler

A handler class that writes logging records to a terminal.

This class does not close the stream, as sys.stdout or sys.stderr may be (and usually will be) used.

Slightly modified version of the StreamHandler class that ships with logging module, plus code for colorization of output.

Initialize the handler.

If stream is not specified, sys.stderr is used.

createLock()[source]#

Acquire a thread lock for serializing access to the underlying I/O.

Replace Handler’s instance-specific lock with the shared class lock to ensure that only one instance of this handler can write to the console at a time.

Return type:

None

emit(record)[source]#

Emit the record formatted to the output.

Return type:

None

sharedlock = <unlocked _thread.RLock object owner=0 count=0>#
class userinterfaces.terminal_interface_base.UI[source]#

Bases: ABUIC

Base for terminal user interfaces.

Changed in version 6.2:: subclassed from userinterfaces._interface_base.ABUIC

Initialize the UI.

This caches the std-streams locally so any attempts to monkey-patch the streams later will not work.

Changed in version 7.1: memorize original streams

cache_output(*args, **kwargs)[source]#

Put text to cache.

Added in version 7.0.

Return type:

None

classmethod divide_color(color)[source]#

Split color label in a tuple.

Received color is a string like ‘fg_color;bg_color’ or ‘fg_color’. Returned values are (fg_color, bg_color) or (fg_color, None).

static editText(text, jumpIndex=None, highlight=None)[source]#

Return the text as edited by the user.

Uses a Tkinter edit box because we don’t have a console editor

Parameters:

  • text (str) – the text to be edited

  • jumpIndex (int | None) – position at which to put the caret

  • highlight (str | None) – each occurrence of this substring will be highlighted

Returns:

the modified text, or None if the user didn’t save the text file in his text editor

Return type:

str | None

encounter_color(color, target_stream)[source]#

Abstract method to handle the next color encountered.

flush()[source]#

Output cached text.

Added in version 7.0.

Return type:

None

init_handlers(root_logger, default_stream='stderr')[source]#

Initialize the handlers for user output.

This method initializes handler(s) for output levels VERBOSE (if enabled by config.verbose_output), INFO, STDOUT, WARNING, ERROR, and CRITICAL. STDOUT writes its output to sys.stdout; all the others write theirs to sys.stderr.

Parameters:

default_stream (str)

Return type:

None

input(question, password=False, default='', force=False)[source]#

Ask the user a question and return the answer.

Works like raw_input(), but returns a unicode string instead of ASCII.

Unlike raw_input, this function automatically adds a colon and space after the question if they are not already present. Also recognises a trailing question mark.

Parameters:

  • question (str) – The question, without trailing whitespace.

  • password (bool) – if True, hides the user’s input (for password entry).

  • default (str | None) – The default answer if none was entered. None to require an answer.

  • force (bool) – Automatically use the default

Return type:

str

input_choice(question, options, default=None, return_shortcut=True, automatic_quit=True, force=False)[source]#

Ask the user and returns a value from the options.

Depending on the options setting return_shortcut to False may not be sensible when the option supports multiple values as it’ll return an ambiguous index.

Changed in version 9.0: Raise ValueError if no default value is given with force; raise ValueError if force is True and default value is invalid; raise TypeError if default value is neither str nor None.

Parameters:

  • question (str) – The question, without trailing whitespace.

  • options (Iterable[tuple[str, str] | Option] | Option) – Iterable of all available options. Each entry contains the full length answer and a shortcut of only one character. Alternatively they may be Option (or subclass) instances or ChoiceException instances which have a full option and shortcut and will be raised if selected.

  • default (str | None) – The default answer if no was entered. None to require an answer.

  • return_shortcut (bool) – Whether the shortcut or the index in the option should be returned.

  • automatic_quit (bool) – Adds the option ‘Quit’ (‘q’) if True and throws a QuitKeyboardInterrupt if selected.

  • force (bool) – Automatically use the default

Returns:

If return_shortcut the shortcut of options or the value of default (if it’s not None). Otherwise the index of the answer in options. If default is not a shortcut, it’ll return -1.

Raises:

  • ValueError – invalid or no default value is given with force or no or an invalid option is given.

  • TypeError – default value is neither None nor str

Return type:

Any

input_list_choice(question, answers, default=None, force=False)[source]#

Ask the user to select one entry from a list of entries.

Parameters:

  • question (str) – The question, without trailing whitespace.

  • answers (Sequence[Any]) – A sequence of options to be chosen.

  • default (int | str | None) – The default answer if no was entered. None to require an answer.

  • force (bool) – Automatically use the default.

Returns:

Return a single Sequence entry.

Return type:

Any

output(text, targetStream=None)[source]#

Forward text to cache and flush if output is not locked.

All input methods locks the output to a stream but collect them in cache. They will be printed with next unlocked output call or at termination time.

Changed in version 7.0: Forward text to cache and flush if output is not locked.

Return type:

None

split_col_pat = re.compile('(\\w+);?(\\w+)?')#
stream_output(text, targetStream=None)[source]#

Output text to a stream.

If a character can’t be displayed in the encoding used by the user’s terminal, it will be replaced with a question mark or by a transliteration.

Added in version 7.0: UI.output() was renamed to UI.stream_output()

Return type:

None

support_color(target_stream)[source]#

Return whether the target stream does support colors.

Return type:

bool

userinterfaces.terminal_interface_base.colors = ['default', 'black', 'blue', 'green', 'aqua', 'red', 'purple', 'yellow', 'lightgray', 'gray', 'lightblue', 'lightgreen', 'lightaqua', 'lightred', 'lightpurple', 'lightyellow', 'white']#

Colors supported by Pywikibot

terminal_interface_unix — Unix Terminal Interface#

User interface for Unix terminals.

class userinterfaces.terminal_interface_unix.UnixUI[source]#

Bases: UI

User interface for Unix terminals.

Initialize the UI.

This caches the std-streams locally so any attempts to monkey-patch the streams later will not work.

Changed in version 7.1: memorize original streams

encounter_color(color, target_stream)[source]#

Write the Unix color directly to the stream.

Return type:

None

static make_unix_bg_color(color)[source]#

Obtain background color from foreground color.

support_color(target_stream)[source]#

Return that the target stream supports colors.

Return type:

bool

terminal_interface_win32 —- Windows Terminal Interface#

User interface for Win32 terminals.

class userinterfaces.terminal_interface_win32.Win32UI[source]#

Bases: UI

User interface for Win32 terminals.

Initialize the UI.

This caches the std-streams locally so any attempts to monkey-patch the streams later will not work.

Changed in version 7.1: memorize original streams

encounter_color(color, target_stream)[source]#

Set the new color.

Return type:

None

support_color(target_stream)[source]#

Return whether the target stream supports actually color.

buffer_interface — Buffer Interface#

Non-interactive interface that stores output.

Added in version 6.4.

class userinterfaces.buffer_interface.UI[source]#

Bases: ABUIC

Collects output into an unseen buffer.

Added in version 6.4.

Initialize the UI.

clear()[source]#

Removes any buffered output.

Return type:

None

flush()[source]#

Flush cached output.

Return type:

None

init_handlers(root_logger, *args, **kwargs)[source]#

Initialize the handlers for user output.

Return type:

None

input(question, password=False, default='', force=False)[source]#

Ask the user a question and return the answer.

Parameters:

  • question (str)

  • password (bool)

  • default (str)

  • force (bool)

Return type:

str

input_choice(question, options, default=None, return_shortcut=True, automatic_quit=True, force=False)[source]#

Ask the user and returns a value from the options.

Parameters:

  • question (str)

  • default (str | None)

  • return_shortcut (bool)

  • automatic_quit (bool)

  • force (bool)

input_list_choice(question, answers, default=None, force=False)[source]#

Ask the user to select one entry from a list of entries.

Parameters:

  • question (str)

  • answers (Sequence[Any])

  • default (int | str | None)

  • force (bool)

Return type:

Any

output(text, *args, **kwargs)[source]#

Output text that would usually go to a stream.

Return type:

None

pop_output()[source]#

Provide and clear any buffered output.

gui — Graphical User Interface#

A window with a textfield where the user can edit.

Useful for editing the contents of an article.

Note

idlelib, tkinter and pillow modules are required.

Warning

With Pillow 10.0, 10.1 no wheels for 32-bit Python on Windows are supported. Pillow 10.2 supports it again. Either you have to update your Python using a 64-bit version or you have to pip install "pillow>8.1.1,!=10.0,!=10.1".

See also

editor

class userinterfaces.gui.EditBoxWindow(parent=None, **kwargs)[source]#

Bases: object

Edit box window.

config_dialog(event=None)[source]#

Show config dialog.

Return type:

None

debug(event=None)[source]#

Call quit() and return ‘break’.

Return type:

str

edit(text, jumpIndex=None, highlight=None)[source]#

Provide user with editor to modify text.

Parameters:

  • text (str) – the text to be edited

  • jumpIndex (int | None) – position at which to put the caret

  • highlight (str | None) – each occurrence of this substring will be highlighted

Returns:

the modified text, or None if the user didn’t save the text file in his text editor

Return type:

str | None

find()[source]#

Perform find operation.

Return type:

None

find_all(target)[source]#

Perform find all operation.

Return type:

None

pressedOK()[source]#

Perform OK operation.

Called when user pushes the OK button. Saves the buffer into a variable, and closes the window.

Return type:

None

class userinterfaces.gui.TextEditor(master=None, **kwargs)[source]#

Bases: object

A text widget with some editing enhancements.

A lot of code here is copied or adapted from the idlelib/EditorWindow.py file in the standard Python distribution.

Get default settings from user’s IDLE configuration.

add_bindings()[source]#

Assign key and events bindings to methods.

Return type:

None

copy(event)[source]#

Perform copy operation.

Return type:

str

cut(event)[source]#

Perform cut operation.

Return type:

str

del_word_left(event)[source]#

Perform delete word (left) operation.

Return type:

str

del_word_right(event=None)[source]#

Perform delete word (right) operation.

Return type:

str

do_highlight(start, end)[source]#

Select and show the text from index start to index end.

Return type:

None

find_again_event(event=None)[source]#

Perform find again operation.

Return type:

str

find_all(s)[source]#

Highlight all occurrences of string s, and select the first one.

If the string has already been highlighted, jump to the next occurrence after the current selection. (You cannot go backwards using the button, but you can manually place the cursor anywhere in the document to start searching from that point.)

find_event(event=None)[source]#

Perform find operation.

Return type:

str

find_selection_event(event=None)[source]#

Perform find selection operation.

Return type:

str

goto_line_event(event)[source]#

Perform goto line operation.

paste(event)[source]#

Perform paste operation.

Return type:

str

remove_selection(event=None)[source]#

Perform remove operation.

Return type:

None

replace_event(event=None)[source]#

Perform replace operation.

Return type:

str

select_all(event=None)[source]#

Perform select all operation.

Return type:

str

class userinterfaces.gui.Tkdialog(photo_description, photo, filename)[source]#

Bases: object

The dialog window for image info.

static get_image(photo, width, height)[source]#

Take the BytesIO object and build an imageTK thumbnail.

ok_file()[source]#

The user pressed the OK button.

Return type:

None

show_dialog()[source]#

Activate the dialog.

Returns:

new description, name, and if the image is skipped

Return type:

tuple[str, str, bool]

skip_file()[source]#

The user pressed the Skip button.

Return type:

None

transliteration — Transliteration#

Module to transliterate text.

class userinterfaces.transliteration.Transliterator(encoding)[source]#

Bases: object

Class to transliterating text.

Initialize the transliteration mapping.

Parameters:

encoding (str) – the encoding available. Any transliterated character which can’t be mapped, will be removed from the mapping.

transliterate(char, default='?', prev='-', succ='-', next='[deprecated name of succ]')[source]#

Transliterate the character.

Changed in version 9.0: next parameter was renamed to succ.

Parameters:

  • char (str) – The character to transliterate.

  • default (str) – The character used when there is no transliteration.

  • prev (str) – The previous character

  • succ (str) – The succeeding character

Returns:

The transliterated character which may be an empty string