khard.helpers.interactive
*************************

Helper functions for user interaction.


Attributes
==========

+------------+--------------------------------------------------------------------------------------------+
| "T"        |                                                                                            |
+------------+--------------------------------------------------------------------------------------------+


Classes
=======

+------------+--------------------------------------------------------------------------------------------+
| "EditStat  | Create a collection of name/value pairs.                                                   |
| e"         |                                                                                            |
+------------+--------------------------------------------------------------------------------------------+
| "Editor"   | Wrapper around subprocess.Popen to edit and merge files.                                   |
+------------+--------------------------------------------------------------------------------------------+


Functions
=========

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


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(*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.

   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
