# khard.helpers.interactive

Helper functions for user interaction.

## Attributes

`T` |

## 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`(→ T | None) | Ask the user to select an item from a list.

## Module Contents

khard.helpers.interactive.T

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)

    - 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

  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.

  editor
  merge_editor
  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.contacts.Contact], template1: str, template2: str | None = None) → khard.contacts.Contact | None

    Edit YAML templates of contacts and parse them back

    Parameters:

      - yaml2card – a function to convert the modified YAML templates into a Contact

      - template1 – the first template

      - template2 – the second template (optional, for merges)

    Returns:

      the parsed Contact or None