khard.khard
===========

.. py:module:: khard.khard

.. autoapi-nested-parse::

   Main application logic of khard including command line handling



Attributes
----------

.. autoapisummary::

   khard.khard.logger
   khard.khard.config
   khard.khard.ExitStatus


Functions
---------

.. autoapisummary::

   khard.khard.version_check
   khard.khard.create_new_contact
   khard.khard.modify_existing_contact
   khard.khard.merge_existing_contacts
   khard.khard.copy_contact
   khard.khard.list_address_books
   khard.khard.list_contacts
   khard.khard.list_with_headers
   khard.khard.choose_address_book_from_list
   khard.khard.choose_vcard_from_list
   khard.khard.get_contact_list
   khard.khard.sort_contacts
   khard.khard.prepare_search_queries
   khard.khard.generate_contact_list
   khard.khard.new_subcommand
   khard.khard.add_email_to_contact
   khard.khard.find_email_addresses
   khard.khard.add_email_subcommand
   khard.khard.birthdays_subcommand
   khard.khard.phone_subcommand
   khard.khard.post_address_subcommand
   khard.khard.email_subcommand
   khard.khard._filter_email_post_or_phone_number_results
   khard.khard.list_subcommand
   khard.khard.modify_subcommand
   khard.khard.remove_subcommand
   khard.khard.merge_subcommand
   khard.khard.copy_or_move_subcommand
   khard.khard.main


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

.. py:data:: logger

.. py:data:: config
   :type:  khard.config.Config

.. py:data:: ExitStatus

.. py:function:: version_check(contact: khard.contacts.Contact, description: str) -> bool

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

.. py:function:: modify_existing_contact(old_contact: khard.contacts.Contact) -> None

.. py:function:: merge_existing_contacts(source_contact: khard.contacts.Contact, target_contact: khard.contacts.Contact, delete_source_contact: bool) -> None

.. py:function:: copy_contact(contact: khard.contacts.Contact, target_address_book: khard.address_book.VdirAddressBook, delete_source_contact: bool) -> None

.. py:function:: list_address_books(address_books: Union[khard.address_book.AddressBookCollection, list[khard.address_book.VdirAddressBook]]) -> None

.. py:function:: list_contacts(vcard_list: list[khard.contacts.Contact], fields: Iterable[str] = (), parsable: bool = False) -> None

.. py:function:: list_with_headers(the_list: list[str], *headers: str) -> None

.. py:function:: choose_address_book_from_list(header: str, abooks: Union[khard.address_book.AddressBookCollection, list[khard.address_book.VdirAddressBook]]) -> Optional[khard.address_book.VdirAddressBook]

   Let the user select one of the given address books

   :param header: some text to print in front of the list
   :param abooks: the address books from which to select
   :returns: the selected address book
   :raises Canceled: when the user canceled the selection


.. py:function:: choose_vcard_from_list(header: str, vcards: list[khard.contacts.Contact], include_none: bool = False) -> Optional[khard.contacts.Contact]

   Let the user select a contact from a list

   :param header: some text to print in front of the list
   :param vcards: the contacts from which to select
   :returns: the selected contact
   :raises Canceled: when the user canceled the selection


.. py:function:: get_contact_list(address_books: Union[khard.address_book.VdirAddressBook, khard.address_book.AddressBookCollection], query: khard.query.Query) -> list[khard.contacts.Contact]

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

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


.. py:function:: sort_contacts(contacts: Iterable[khard.contacts.Contact], reverse: bool = False, group: bool = False, sort: str = 'first_name') -> list[khard.contacts.Contact]

   Sort a list of contacts

   :param contacts: the contact list to sort
   :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: sorted contact list


.. py:function:: prepare_search_queries(args: argparse.Namespace) -> dict[str, khard.query.Query]

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

   Each address book can get a search query string to filter vCards before
   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


.. py:function:: generate_contact_list(args: argparse.Namespace) -> list[khard.contacts.Contact]

   Find the contact list with which we will work later on

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


.. py:function:: new_subcommand(abooks: khard.address_book.AddressBookCollection, data: str, open_editor: bool) -> ExitStatus

   Create a new contact.

   :param abooks: a list of address books that were selected on the command
       line
   :param data: the data for the new contact as a yaml formatted string
   :param open_editor: whether to open the new contact in the editor after
       creation
   :raises Canceled: when the user canceled a selection


.. py:function:: add_email_to_contact(name: str, email_address: str, abooks: khard.address_book.AddressBookCollection, skip_already_added: bool) -> 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 address books that were selected on the command line
   :param skip_already_added: skip if email_address is part of one or more contacts
   :raises Canceled: when the user canceled a selection


.. py:function:: find_email_addresses(text: str, fields: list[str]) -> list[email.headerregistry.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.


.. py:function:: add_email_subcommand(text: str, abooks: khard.address_book.AddressBookCollection, fields: list[str], skip_already_added: bool) -> ExitStatus

   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 address books that were selected on the command line
   :param field: the header field to extract contacts from
   :param skip_already_added: skip already known email addresses
   :raises Canceled: when the user canceled a selection


.. py:function:: birthdays_subcommand(vcard_list: list[khard.contacts.Contact], parsable: bool) -> ExitStatus

   Print birthday contact table.

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


.. py:function:: phone_subcommand(search_terms: khard.query.Query, vcard_list: list[khard.contacts.Contact], parsable: bool) -> ExitStatus

   Print a phone application friendly contact table.

   :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 divided by tabulator (    )


.. py:function:: post_address_subcommand(search_terms: khard.query.Query, vcard_list: list[khard.contacts.Contact], parsable: bool) -> ExitStatus

   Print a contact table with all postal / mailing addresses

   :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 divided by tabulator (    )


.. py:function:: email_subcommand(search_terms: khard.query.Query, vcard_list: list[khard.contacts.Contact], parsable: bool, remove_first_line: bool) -> ExitStatus

   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 divided by tabulator (    )
   :param remove_first_line: remove first line (searching for '' ...)


.. py:function:: _filter_email_post_or_phone_number_results(search_terms: khard.query.Query, field_line_list: list[str]) -> list[str]

   Filter the created output of phone_subcommand, post_address_subcommand
   and email_subcommand by the given search term again.
   If no match is found, return the complete input list

   :param search_terms: used as search term to filter the contacts before
       printing
   :param field_line_list: The line-by-line output of the commands listed above


.. py:function:: list_subcommand(vcard_list: list[khard.contacts.Contact], parsable: bool, fields: list[str]) -> ExitStatus

   Print a user friendly contacts table.

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


.. py:function:: modify_subcommand(selected_vcard: khard.contacts.Contact, input_from_stdin_or_file: str, open_editor: bool, source: bool = False) -> ExitStatus

   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 incorporated into the contact, this should be a yaml
       formatted string
   :param open_editor: whether to open the new contact in the editor after
       creation
   :param source: edit the source file or a yaml version?


.. py:function:: remove_subcommand(selected_vcard: khard.contacts.Contact, force: bool) -> None

   Remove a contact from the address book.

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


.. py:function:: merge_subcommand(vcards: list[khard.contacts.Contact], abooks: khard.address_book.AddressBookCollection, search_terms: khard.query.Query) -> ExitStatus

   Merge two contacts into one.

   :param vcards: the vCards from which to choose contacts for merging
   :param abooks: the address books to use to find the target contact
   :param search_terms: the search terms to find the target contact
   :raises Canceled: when the user canceled a selection


.. py:function:: copy_or_move_subcommand(action: str, vcards: list[khard.contacts.Contact], target_address_books: khard.address_book.AddressBookCollection) -> ExitStatus

   Copy or move a contact to a different address book.

   :param action: the string "copy" or "move" to indicate what to do
   :param vcards: the contact list from which to select one for the action
   :param target_address_books: the target address books
   :raises Canceled: when the user canceled a selection


.. py:function:: main(argv: list[str] = sys.argv[1:]) -> ExitStatus

