upsies.jobs.dialog

Get information from the user

Classes

class upsies.jobs.dialog.ChoiceJob(*, home_directory=None, cache_directory=None, cache_id='', ignore_cache=False, no_output_is_ok=False, hidden=False, autostart=True, guaranteed=False, precondition=None, prejobs=(), callbacks={}, **kwargs)

Bases: JobBase

Ask the user to choose from a set of values

This job adds the following signals to signal:

dialog_updated

Emitted when the options, focused or autodetected properties are set or when options is modified. Registered callbacks get no arguments.

autodetecting

Emitted when autodetect is called. Registered callbacks get the job instance as a positional argument.

autodetected

Emitted when autodetect returns. Registered callbacks get the job instance as a positional argument.

property name

Internal name (e.g. for the cache file name)

property label

User-facing name

property question

Text that is displayed alongside the options

property options

Sequence of options the user can make

An option is a tuple with 2 items. The first item is a human-readable str and the second item is any object that is available as choice when the job is finished.

Options may also be passed as a flat iterable of str, in which case both items in the tuple are identical.

When setting this property, focus is preserved if the value of the focused option exists in the new options. Otherwise, the first option is focused.

property multichoice

Whether multiple options can be selected

get_index(thing)

Return index in options

Parameters:

thing –

Identifier of a option in options

This can be:

None

Return None

an index (int)

Return thing, but limited to the minimum/maximum valid index.

one of the 2-tuples in options

Return the index of thing in options.

an item of one of the 2-tuples in options

Return the index of the first 2-tuple in options that contains thing.

a regular expression

Return the index of the first 2-tuple in options that contains something that matches thing. Non-string values are converted to str for matching against the regular expression.

Raises:

ValueError – if thing is not found in options

get_option(thing)

Return item in options

Parameters:

thing – See get_index()

If thing is None, return the currently focused option, which is indicated by focused_index.

property focused_index

Index of currently focused option in options

property focused

Currently focused option (2-tuple)

This property can be set to anything that is a valid value for get_index().

property autodetected

Autodetected option (2-tuple) or sequence of autodetected options (if multichoice) or None

This property can be set to anything that is a valid value for get_index(). If multichoice was True, it must be set to a sequence of valid get_index() arguments.

If this property is set to None, all options are marked as “not autodetected”.

property autodetected_indexes

Sequence of autodetected option indexes in options

property choice

User-chosen value if job is finished, None otherwise

If multichoice was True, this is a sequence of chosen values.

While output contains the user-readable string (first item of the chosen 2-tuple in options), this is the object attached to it (second item).

make_choice(thing)

Make a choice and finalize() this job

Parameters:

thing – See get_option()

After this method is called, this job is_finished, output contains the human-readable label of the choice and choice is the machine-readable value of the choice.

set_label(identifier, new_label)

Assign new label to option

Parameters:

• identifier – Option (2-tuple of (<current label>, <value>)) or the current label or value of an option

• new_label – New label for the option defined by identifier

Do nothing if identifier doesn’t match any option.

initialize(*, name, label, options, question=None, focused=None, autodetected=None, autodetect=None, autofinish=False, multichoice=None, validate=None)

Set internal state

Parameters:

• name – Name for internal use

• label – Name for user-facing use

• options – Iterable of options the user can pick from

• question – Any text that is displayed alongside the options

• focused – See focused

• autodetected – See autodetected

• autodetect –

  Callable that sets autodetected when job is started

  autodetect gets the job instance (self) as a positional argument.

• autofinish – Whether to call make_choice() if autodetect returns anything that is not None

• multichoice – Whether multiple or no items from options can be chosen

• validate – callable that gets the sequence of chosen options and raises ValueError to inform the user about their mistake

Raises:

ValueError – if options is shorter than 2 or focused is invalid

async run()

Do the work

This method is called by start(). Its coroutine is passed to add_task().

Any keyword arguments passed to initialize() are available via kwargs.

The job is_finished when all added tasks are done or cancelled. (See also finalize() and finalization().)

This method may call add_task() if more tasks are required.

class upsies.jobs.dialog.TextFieldJob(*, home_directory=None, cache_directory=None, cache_id='', ignore_cache=False, no_output_is_ok=False, hidden=False, autostart=True, guaranteed=False, precondition=None, prejobs=(), callbacks={}, **kwargs)

Bases: JobBase

Ask the user for text input

This job adds the following signals to signal:

text

Emitted when text was changed without user input. Registered callbacks get the new text as a positional argument.

is_loading

Emitted when is_loading was changed. Registered callbacks get the new is_loading value as a positional argument.

read_only

Emitted when read_only was changed. Registered callbacks get the new read_only value as a positional argument.

obscured

Emitted when obscured was changed. Registered callbacks get the new obscured value as a positional argument.

property name

Internal name (e.g. for the cache file name)

property label

User-facing name

property text

Current text

property obscured

Whether the text is unreadable, e.g. when entering passwords

This is currently not fully implemented.

property read_only

Whether the user should be able change the text

This is just a boolean flag that is not enforced by the job so that autodetection will still work. The user interface must track its status via the read_only signal and enforce it.

property is_loading

Whether text is currently being changed automatically

initialize(*, name, label, text='', default=None, finish_on_success=False, warn_exceptions=(), error_exceptions=(), validator=None, normalizer=None, obscured=False, read_only=False)

Set internal state

Parameters:

• name – Name for internal use

• label – Name for user-facing use

• text – Initial text or callable (synchronous or asynchronous) which will be called when the job is started. The return value is used as the initial text.

• default – Text to use if text is None, returns None or raises warn_exceptions

• finish_on_success –

  Whether to call finalize() after setting text to text

  Note

  finalize() is not called if text is set to default.

• warn_exceptions – Sequence of exception classes that are caught if raised by text and passed on to warn()

• error_exceptions – Sequence of exception classes that are caught if raised by text and passed on to error()

• validator (callable or None) – Callable that gets text before job is finished. If ValueError is raised, it is displayed as a warning instead of finishing the job.

• normalizer (callable or None) – Callable that gets text and returns the new text. It is called before validator. It should not raise any exceptions.

• obscured (bool) – Whether obscured is set to True initially (currently fully implemented)

• read_only (bool) – Whether read_only is set to True initially

async run()

Do the work

This method is called by start(). Its coroutine is passed to add_task().

Any keyword arguments passed to initialize() are available via kwargs.

The job is_finished when all added tasks are done or cancelled. (See also finalize() and finalization().)

This method may call add_task() if more tasks are required.

set_text(text, *, default=None, finish_on_success=False, warn_exceptions=(), error_exceptions=())

Change text value

Parameters:

• text –

  New text value

  If this is callable, it must return the new text or None to use default

• default – Text to use if text is None, returns None or raises warn_exceptions

• finish_on_success –

  Whether to call finish() after setting text to text

  Note

  finish() is not called when text is set to default.

• warn_exceptions – Sequence of exception classes that may be raised by coro and are passed on to :~.JobBase.warn

• error_exceptions – Sequence of exception classes that may be raised by coro and are passed on to :~.JobBase.error

async fetch_text(coro, *, default=None, finish_on_success=False, warn_exceptions=(), error_exceptions=())

Get text from coroutine

Parameters:

• coro – Coroutine that returns the new text or None to use default

• default – Text to use if text is None, returns None or raises warn_exceptions

• finish_on_success –

  Whether to call finish() after setting text to coro return value

  Note

  finish() is not called when text is set to default.

• warn_exceptions – Sequence of exception classes that may be raised by coro and are passed on to :~.JobBase.warn

• error_exceptions – Sequence of exception classes that may be raised by coro and are passed on to :~.JobBase.error

add_output(output)

Validate output before actually adding it

Pass output to validator (see initialize()). If ValueError is raised, pass it to warn() and do not finalize. Otherwise, pass output to add_output() and finalize() this job.