:mod:`khard.khard`
==================

.. py:module:: khard.khard

.. autoapi-nested-parse::

   Main application logic of khard includeing command line handling



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


.. data:: logger
   

   

.. data:: config
   :annotation: :Config

   

.. data:: T
   

   

.. function:: confirm(message: str) -> bool

   Ask the user for confirmation on the terminal.

   :param message: the question to print
   :returns: the answer of the user


.. function:: select(items: List[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.  This function might exit if the user
   selects "q".

   :param items: the list from which to select
   :param include_none: weather to allow the selection of no item
   :returns: None or the selected item


.. function:: write_temp_file(text: str = '') -> str

   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


.. function:: edit(*filenames: str, merge: bool = False) -> None

   Edit the given files with the configured editor or merge editor


.. function:: create_new_contact(address_book: VdirAddressBook) -> None


.. function:: modify_existing_contact(old_contact: CarddavObject) -> None


.. function:: merge_existing_contacts(source_contact: CarddavObject, target_contact: CarddavObject, delete_source_contact: bool) -> None


.. function:: copy_contact(contact: CarddavObject, target_address_book: VdirAddressBook, delete_source_contact: bool) -> None


.. function:: list_address_books(address_books: Union[AddressBookCollection, List[VdirAddressBook]]) -> None


.. function:: list_contacts(vcard_list: List[CarddavObject], fields: Iterable[str] = (), parsable: bool = False) -> None


.. function:: list_with_headers(the_list: List, *headers: str) -> None


.. function:: choose_address_book_from_list(header_string: str, address_books: Union[AddressBookCollection, List[VdirAddressBook]]) -> Optional[VdirAddressBook]


.. function:: choose_vcard_from_list(header_string: str, vcard_list: List[CarddavObject], include_none: bool = False) -> Optional[CarddavObject]


.. function:: get_contact_list_by_user_selection(address_books: Union[VdirAddressBook, AddressBookCollection], query: Query) -> List[CarddavObject]

   Find contacts in the given address book grouped, sorted and reversed
   acording to the loaded configuration .

   :param address_books: the address book to search
   :param query: the query to use when searching
   :returns: list of found CarddavObject objects


.. function:: get_contacts(address_book: Union[VdirAddressBook, AddressBookCollection], query: Query, reverse: bool = False, group: bool = False, sort: str = 'first_name') -> List[CarddavObject]

   Get a list of contacts from one or more address books.

   :param address_book: the address book to search
   :param query: a search query to select contacts
   :param reverse: reverse the order of the returned contacts
   :param group: group results by address book
   :param sort: the field to use for sorting, one of "first_name",
       "last_name", "formatted_name"
   :returns: contacts from the address_book that match the query


.. function:: prepare_search_queries(args: Namespace) -> Dict[str, Query]

   Prepare the search query string from the given command line args.

   Each address book can get a search query string to filter vcards befor
   loading them.  Depending on the question if the address book is used for
   source or target searches different queries have to be combined.

   :param args: the parsed command line
   :returns: a dict mapping abook names to their loading queries


.. function:: generate_contact_list(args: Namespace) -> List[CarddavObject]

   Find the contact list with which we will work later on

   :param args: the command line arguments
   :returns: the contacts for further processing


.. function:: new_subcommand(selected_address_books: AddressBookCollection, input_from_stdin_or_file: str, open_editor: bool) -> None

   Create a new contact.

   :param selected_address_books: a list of addressbooks that were selected on
       the command line
   :param input_from_stdin_or_file: the data for the new contact as a yaml
       formatted string
   :param open_editor: whether to open the new contact in the edior after
       creation


.. function:: add_email_to_contact(name: str, email_address: str, abooks: AddressBookCollection) -> None

   Add a new email address to the given contact,
   creating the contact if necessary.

   :param name: name of the contact
   :param email_address: email address of the contact
   :param abooks: the addressbooks that were selected on the command line


.. function:: find_email_addresses(text: str, fields: List[str]) -> List[Address]

   Search the text for email addresses in the given fields.

   :param text: the text to search for email addresses
   :param fields: the fields to look in for email addresses.
       The `all` field searches all headers.


.. function:: add_email_subcommand(text: str, abooks: AddressBookCollection, fields: List[str]) -> None

   Add a new email address to contacts, creating new contacts if necessary.

   :param text: the input text to search for the new email
   :param abooks: the addressbooks that were selected on the command line
   :param field: the header field to extract contacts from


.. function:: birthdays_subcommand(vcard_list: List[CarddavObject], parsable: bool) -> None

   Print birthday contact table.

   :param vcard_list: the vcards to search for matching entries which should
       be printed
   :param parsable: machine readable output: columns devided by tabulator (    )


.. function:: phone_subcommand(vcard_list: List[CarddavObject], parsable: bool) -> None

   Print a phone application friendly contact table.

   :param vcard_list: the vcards to search for matching entries which should
       be printed
   :param parsable: machine readable output: columns devided by tabulator (    )


.. function:: post_address_subcommand(vcard_list: List[CarddavObject], parsable: bool) -> None

   Print a contact table. with all postal / mailing addresses

   :param vcard_list: the vcards to search for matching entries which should
       be printed
   :param parsable: machine readable output: columns devided by tabulator (    )


.. function:: email_subcommand(search_terms: Query, vcard_list: List[CarddavObject], parsable: bool, remove_first_line: bool) -> None

   Print a mail client friendly contacts table that is compatible with the
   default format used by mutt.
   Output format:

   .. code-block:: text

       single line of text
       email_address   name    type
       email_address   name    type
       [...]

   :param search_terms: used as search term to filter the contacts before
       printing
   :param vcard_list: the vcards to search for matching entries which should
       be printed
   :param parsable: machine readable output: columns devided by tabulator (    )
   :param remove_first_line: remove first line (searching for '' ...)


.. function:: list_subcommand(vcard_list: List[CarddavObject], parsable: bool, fields: List[str]) -> None

   Print a user friendly contacts table.

   :param vcard_list: the vcards to print
   :param parsable: machine readable output: columns devided by tabulator (    )
   :param fields: list of strings for field evaluation


.. function:: modify_subcommand(selected_vcard: CarddavObject, input_from_stdin_or_file: str, open_editor: bool, source: bool = False) -> None

   Modify a contact in an external editor.

   :param selected_vcard: the contact to modify
   :param input_from_stdin_or_file: new data from stdin (or a file) that
       should be incorperated into the contact, this should be a yaml
       formatted string
   :param open_editor: whether to open the new contact in the edior after
       creation
   :param source: edit the source file or a yaml version?


.. function:: remove_subcommand(selected_vcard: CarddavObject, force: bool) -> None

   Remove a contact from the addressbook.

   :param selected_vcard: the contact to delete
   :param force: delete without confirmation


.. function:: merge_subcommand(vcard_list: List[CarddavObject], abooks: AddressBookCollection, search_terms: Query) -> None

   Merge two contacts into one.

   :param vcard_list: the vcards from which to choose contacts for mergeing
   :param abooks: the addressbooks to use to find the target contact
   :param search_terms: the search terms to find the target contact


.. function:: copy_or_move_subcommand(action: str, vcard_list: List[CarddavObject], target_address_books: AddressBookCollection) -> None

   Copy or move a contact to a different address book.

   :param action: the string "copy" or "move" to indicate what to do
   :param vcard_list: the contact list from which to select one for the action
   :param target_address_books: the target address books


.. function:: main(argv: List[str] = sys.argv[1:]) -> None


