`khard.helpers.interactive`¶

Helper functions for user interaction.

Module Contents¶

Classes¶

`EditState`	Create a collection of name/value pairs.
`Editor`	Wrapper around subprocess.Popen to edit and merge files.

Functions¶

`confirm`(→ bool)	Ask the user for confirmation on the terminal.
`ask`(→ str)	Ask the user to select one of the given choices
`select`(→ Optional[T])	Ask the user to select an item from a list.

Attributes¶

T

khard.helpers.interactive.T¶

exception khard.helpers.interactive.Canceled(message: str = 'Canceled')¶

Bases: Exception

An exception indicating that the user canceled some operation.

khard.helpers.interactive.confirm(message: str, accept_enter_key: bool = True) → bool¶

Ask the user for confirmation on the terminal.

Parameters:

message – the question to print
accept_enter_key – Accept ENTER as alternative for “n”

Returns:

the answer of the user

khard.helpers.interactive.ask(message: str, choices: List[str], default: str | None = None, help: str | None = None) → str¶

Ask the user to select one of the given choices

Parameters:

message – a text to show to the user
choices – the possible answers the user might give, if help is not None this list must not contain the string “?”
default – the answer that should be selected on empty user input (None means empty input is not accepted)

Parm help:

a help text to display to the user if they did not answer correctly

Returns:

the choice of the user

khard.helpers.interactive.select(items: Sequence[T], include_none: bool = False) → T | None¶

Ask the user to select an item from a list.

The list should be displayed to the user before calling this function and should be indexed starting with 1.

Parameters:

items – the list from which to select
include_none – whether to allow the selection of no item

Returns:

None or the selected item

Raises:

Canceled – when the user canceled the selection process

class khard.helpers.interactive.EditState(*args, **kwds)¶

Bases: enum.Enum

Create a collection of name/value pairs.

Example enumeration:

>>> class Color(Enum):
...     RED = 1
...     BLUE = 2
...     GREEN = 3

Access them by:

attribute access:

>>> Color.RED
<Color.RED: 1>

value lookup:

>>> Color(1)
<Color.RED: 1>

name lookup:

>>> Color['RED']
<Color.RED: 1>

Enumerations can be iterated over, and know how many members they have:

>>> len(Color)
3

>>> list(Color)
[<Color.RED: 1>, <Color.BLUE: 2>, <Color.GREEN: 3>]

Methods can be added to enumerations, and members can have their own attributes – see the documentation for details.

modified = 1¶

unmodified = 2¶

aborted = 3¶

class khard.helpers.interactive.Editor(editor: str | List[str], merge_editor: str | List[str])¶

Wrapper around subprocess.Popen to edit and merge files.

static write_temp_file(text: str = '') → Generator[str, None, None]¶

Create a new temporary file and write some initial text to it.

Parameters:: text – the text to write to the temp file
Returns:: the file name of the newly created temp file

static _mtime(filename: str) → datetime.datetime¶

edit_files(file1: str, file2: str | None = None) → EditState¶

Edit the given files

If only one file is given the timestamp of this file is checked, if two files are given the timestamp of the second file is checked for modification.

Parameters:

file1 – the first file (checked for modification if file2 not present)
file2 – the second file (checked for modification of present)

Returns:

the result of the modification

edit_templates(yaml2card: Callable[[str], khard.carddav_object.CarddavObject], template1: str, template2: str | None = None) → khard.carddav_object.CarddavObject | None¶

Edit YAML templates of contacts and parse them back

Parameters:

yaml2card – a function to convert the modified YAML templates into a CarddavObject
template1 – the first template
template2 – the second template (optional, for merges)

Returns:

the parsed CarddavObject or None

khard.helpers.interactive¶

Module Contents¶

Classes¶

Functions¶

Attributes¶

`khard.helpers.interactive`¶