bot_choice — UI Options and Choices#

Options and Choices for pywikibot.input_choice().

class bot_choice.AlwaysChoice(replacer, option='always', shortcut='a')[source]#

Bases: Choice

Add an option to always apply the default.

Parameters:
property answer: Any#

Get the actual default answer instructing the replacement.

handle()[source]#

Handle the custom shortcut.

Return type:

Any

Directly return answer whether it’s applying it always.

Return type:

bool

class bot_choice.Choice(option, shortcut, replacer)[source]#

Bases: StandardOption

A simple choice consisting of an option, shortcut and handler.

Parameters:
abstract handle()[source]#

Handle this choice. Must be implemented.

Return type:

Any

The current link will be handled by this choice.

Return type:

bool

property replacer: InteractiveReplace | None#

The replacer.

exception bot_choice.ChoiceException(option, shortcut, **kwargs)[source]#

Bases: StandardOption, Exception

A choice for input_choice which result in this exception.

Parameters:

  • option (str) – option string

  • shortcut (str) – Shortcut of the option

  • kwargs (Any)

Return type:

None

result(value)[source]#

Return itself to raise the exception.

Parameters:

value (Any)

Return type:

Any

class bot_choice.ContextOption(option, shortcut, text, context, delta=100, start=0, end=0)[source]#

Bases: OutputOption, StandardOption

An option to show more and more context.

Parameters:

  • option (str)

  • shortcut (str)

  • text (str)

  • context (int)

  • delta (int)

  • start (int)

  • end (int)

property out: str#

Output section of the text.

result(value)[source]#

Add the delta to the context.

Parameters:

value (str)

Return type:

Any

class bot_choice.HighlightContextOption(option, shortcut, text, context, delta=100, start=0, end=0)[source]#

Bases: ContextOption

Show the original region highlighted.

Parameters:

  • option (str)

  • shortcut (str)

  • text (str)

  • context (int)

  • delta (int)

  • start (int)

  • end (int)

color = 'lightred'#
property out: str#

Highlighted output section of the text.

class bot_choice.IntegerOption(minimum=1, maximum=None, prefix='', **kwargs)[source]#

Bases: Option

An option allowing a range of integers.

Parameters:

  • minimum (int)

  • maximum (int | None)

  • prefix (str)

  • kwargs (Any)

format(default=None)[source]#

Return a formatted string showing the range.

Parameters:

default (str | None)

Return type:

str

property maximum: int | None#

Return the upper bound of the range of allowed values.

property minimum: int#

Return the lower bound of the range of allowed values.

parse(value)[source]#

Return integer from value with prefix removed.

Parameters:

value (str)

Return type:

int

result(value)[source]#

Return a tuple with the prefix and value converted into an int.

Parameters:

value (str)

Return type:

Any

test(value)[source]#

Return whether the value is an int and in the specified range.

Parameters:

value (str)

Return type:

bool

class bot_choice.InteractiveReplace(old_link, new_link, default=None, automatic_quit=True)[source]#

Bases: object

A callback class for textlib’s replace_links.

It shows various options which can be switched on and off: * allow_skip_link = True (skip the current link) * allow_unlink = True (unlink) * allow_replace = False (just replace target, keep section and label) * allow_replace_section = False (replace target and section, keep label) * allow_replace_label = False (replace target and label, keep section) * allow_replace_all = False (replace target, section and label) (The boolean values are the default values)

It has also a context attribute which must be a non-negative integer. If it is greater 0 it shows that many characters before and after the link in question. The context_delta attribute can be defined too and adds an option to increase context by the given amount each time the option is selected.

Additional choices can be defined using the ‘additional_choices’ and will be amended to the choices defined by this class. This list is mutable and the Choice instance returned and created by this class are too.

Parameters:

  • old_link (Link | Page) – The old link which is searched. The label and section are ignored.

  • new_link (Link | Page | Literal[False]) – The new link with which it should be replaced. Depending on the replacement mode it’ll use this link’s label and section. If False it’ll unlink all and the attributes beginning with allow_replace are ignored.

  • default (str | None) – The default answer as the shortcut

  • automatic_quit (bool) – Add an option to quit and raise a QuitKeyboardException.

property choices: tuple[StandardOption, ...]#

Return the tuple of choices.

property current_groups: Mapping[str, str]#

Get the current groups when it’s handling one currently.

Get the current link when it’s handling one currently.

property current_range: tuple[int, int]#

Get the current range when it’s handling one currently.

property current_text: str#

Get the current text when it’s handling one currently.

handle_answer(choice)[source]#

Return the result for replace_links.

Parameters:

choice (str)

Return type:

Any

Handle the currently given replacement.

Return type:

Any

class bot_choice.LinkChoice(option, shortcut, replacer, replace_section, replace_label)[source]#

Bases: Choice

A choice returning a mix of the link new and current link.

Parameters:

  • option (str)

  • shortcut (str)

  • replacer (InteractiveReplace | None)

  • replace_section (bool)

  • replace_label (bool)

handle()[source]#

Handle by either applying the new section or label.

Return type:

Any

class bot_choice.ListOption(sequence, prefix='', **kwargs)[source]#

Bases: IntegerOption

An option to select something from a list.

Parameters:

  • sequence (Sequence[str])

  • prefix (str)

  • kwargs (Any)

format(default=None)[source]#

Return a string showing the range.

Parameters:

default (str | None)

Return type:

str

property maximum: int#

Return the maximum value.

result(value)[source]#

Return a tuple with the prefix and selected value.

Parameters:

value (str)

Return type:

Any

class bot_choice.MultipleChoiceList(sequence, prefix='', **kwargs)[source]#

Bases: ListOption

An option to select multiple items from a list.

Added in version 3.0.

Parameters:

  • sequence (Sequence[str])

  • prefix (str)

  • kwargs (Any)

result(value)[source]#

Return a tuple with the prefix and selected values as a list.

Parameters:

value (str)

Return type:

Any

test(value)[source]#

Return whether the values are int and in the specified range.

Parameters:

value (str)

Return type:

bool

class bot_choice.NestedOption(option, shortcut, description, options)[source]#

Bases: OutputOption, StandardOption

An option containing other options.

It will return True in test if this option applies but False if a sub option applies while handle returns the sub option.

Parameters:

  • option (str)

  • shortcut (str)

  • description (str)

  • options (Iterable[Option])

format(default=None)[source]#

Return a formatted string for that option.

Parameters:

default (str | None)

Return type:

str

handled(value)[source]#

Return itself if it applies or the applying sub option.

Parameters:

value (str)

Return type:

Option | None

property out: str#

Output of suboptions.

class bot_choice.Option(stop=True)[source]#

Bases: ABC

A basic option for input_choice.

The following methods need to be implemented:

  • format(default=None)

  • result(value)

  • test(value)

The methods test and handled are in such a relationship that when handled returns itself that test must return True for that value. So if test returns False handled may not return itself but it may return not None.

Also result only returns a sensible value when test returns True for the same value.

Parameters:

stop (bool)

format(default=None)[source]#

Return a formatted string for that option.

Parameters:

default (str | None)

Return type:

str

static formatted(text, options, default=None)[source]#

Create a text with the options formatted into it.

This static method is used by pywikibot.input_choice(). It calls format for all options to combine the question for pywikibot.input().

Parameters:

  • text (str) – Text into which options are to be formatted

  • options (Iterable[Option]) – Option instances to be formatted

  • default (str | None) – filler for any option’s ‘default’ placeholder

Returns:

Text with the options formatted into it

Return type:

str

handled(value)[source]#

Return the Option object that applies to the given value.

If this Option object doesn’t know which applies it returns None.

Parameters:

value (str)

Return type:

Option | None

abstract result(value)[source]#

Return the actual value which is associated by the given one.

Added in version 6.2: result() is an abstract method and must be defined in subclasses

Parameters:

value (str)

Return type:

Any

property stop: bool#

Return whether this option stops asking.

test(value)[source]#

Return True whether this option applies.

Parameters:

value (str)

Return type:

bool

class bot_choice.OutputProxyOption(option, shortcut, output, **kwargs)[source]#

Bases: OutputOption, StandardOption

An option which calls out property of the given output class.

Create a new option for the given sequence.

Parameters:

  • option (str)

  • shortcut (str)

  • output (OutputOption)

  • kwargs (Any)

property out: str#

Return the contents.

exception bot_choice.QuitKeyboardInterrupt[source]#

Bases: ChoiceException, KeyboardInterrupt

The user has cancelled processing at a prompt.

Constructor using the ‘quit’ (‘q’) in input_choice.

Return type:

None

class bot_choice.ShowingListOption(sequence, prefix='', pre=None, post=None, **kwargs)[source]#

Bases: ListOption, OutputOption

An option to show a list and select an item.

Added in version 3.0.

Parameters:

  • pre (str | None) – Additional comment printed before the list.

  • post (str | None) – Additional comment printed after the list.

  • sequence (Sequence[str])

  • prefix (str)

  • kwargs (Any)

before_question: bool = True#

Place output before or after the question

property out: str#

Output text of the enumerated list.

property stop: bool#

Return whether this option stops asking.

class bot_choice.ShowingMultipleChoiceList(sequence, prefix='', pre=None, post=None, **kwargs)[source]#

Bases: ShowingListOption, MultipleChoiceList

An option to show a list and select multiple items.

Added in version 3.0.

Parameters:

  • pre (str | None) – Additional comment printed before the list.

  • post (str | None) – Additional comment printed after the list.

  • sequence (Sequence[str])

  • prefix (str)

  • kwargs (Any)

class bot_choice.StandardOption(option, shortcut, **kwargs)[source]#

Bases: Option

An option with a description and shortcut and returning the shortcut.

Parameters:

  • option (str) – option string

  • shortcut (str) – Shortcut of the option

  • kwargs (Any)

format(default=None)[source]#

Return a formatted string for that option.

Parameters:

default (str | None)

Return type:

str

result(value)[source]#

Return the lowercased shortcut.

Parameters:

value (str)

Return type:

Any

test(value)[source]#

Return True whether this option applies.

Parameters:

value (str)

Return type:

bool

class bot_choice.StaticChoice(option, shortcut, result)[source]#

Bases: Choice

A static choice which just returns the given value.

Create instance with replacer set to None.

Parameters:

  • option (str)

  • shortcut (str)

  • result (Any)

handle()[source]#

Return the predefined value.

Return type:

Any

exception bot_choice.UnhandledAnswer[source]#

Bases: Exception

The given answer didn’t suffice.