:py:mod:`khard.helpers.interactive`
===================================

.. py:module:: khard.helpers.interactive

.. autoapi-nested-parse::

   Helper functions for user interaction.



Module Contents
---------------

Classes
~~~~~~~

.. autoapisummary::

   khard.helpers.interactive.EditState
   khard.helpers.interactive.Editor



Functions
~~~~~~~~~

.. autoapisummary::

   khard.helpers.interactive.confirm
   khard.helpers.interactive.ask
   khard.helpers.interactive.select



Attributes
~~~~~~~~~~

.. autoapisummary::

   khard.helpers.interactive.T


.. py:data:: T

   

.. py:exception:: Canceled(message: str = 'Canceled')


   Bases: :py:obj:`Exception`

   An exception indicating that the user canceled some operation.


.. py:function:: confirm(message: str, accept_enter_key: bool = True) -> bool

   Ask the user for confirmation on the terminal.

   :param message: the question to print
   :param accept_enter_key: Accept ENTER as alternative for "n"
   :returns: the answer of the user


.. py:function:: ask(message: str, choices: List[str], default: Optional[str] = None, help: Optional[str] = None) -> str

   Ask the user to select one of the given choices

   :param message: a text to show to the user
   :param choices: the possible answers the user might give, if help is not
       None this list must not contain the string "?"
   :param 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


.. py:function:: select(items: Sequence[T], include_none: bool = False) -> Optional[T]

   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.

   :param items: the list from which to select
   :param 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


.. py:class:: EditState(*args, **kwds)


   Bases: :py:obj:`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.

   .. py:attribute:: modified
      :value: 1

      

   .. py:attribute:: unmodified
      :value: 2

      

   .. py:attribute:: aborted
      :value: 3

      


.. py:class:: Editor(editor: Union[str, List[str]], merge_editor: Union[str, List[str]])


   Wrapper around subprocess.Popen to edit and merge files.

   .. py:method:: write_temp_file(text: str = '') -> Generator[str, None, None]
      :staticmethod:

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

      :param text: the text to write to the temp file
      :returns: the file name of the newly created temp file


   .. py:method:: _mtime(filename: str) -> datetime.datetime
      :staticmethod:


   .. py:method:: edit_files(file1: str, file2: Optional[str] = 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.

      :param file1: the first file (checked for modification if file2 not
          present)
      :param file2: the second file (checked for modification of present)
      :returns: the result of the modification


   .. py:method:: edit_templates(yaml2card: Callable[[str], khard.carddav_object.CarddavObject], template1: str, template2: Optional[str] = None) -> Optional[khard.carddav_object.CarddavObject]

      Edit YAML templates of contacts and parse them back

      :param yaml2card: a function to convert the modified YAML templates
          into a CarddavObject
      :param template1: the first template
      :param template2: the second template (optional, for merges)
      :returns: the parsed CarddavObject or None