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

.. py:module:: khard.khard

.. autoapi-nested-parse::

   Main application logic of khard includeing command line handling



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


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



Attributes
~~~~~~~~~~

.. autoapisummary::

   khard.khard.logger
   khard.khard.config


.. py:data:: logger
   

   

.. py:data:: config
   :annotation: :khard.config.Config

   

.. py:function:: version_check(contact: khard.carddav_object.CarddavObject, description: str) -> bool


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


.. py:function:: modify_existing_contact(old_contact: khard.carddav_object.CarddavObject) -> None


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


.. py:function:: copy_contact(contact: khard.carddav_object.CarddavObject, 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.carddav_object.CarddavObject], fields: Iterable[str] = (), parsable: bool = False) -> None


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


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


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


.. py:function:: get_contact_list(address_books: Union[khard.address_book.VdirAddressBook, khard.address_book.AddressBookCollection], query: khard.query.Query) -> List[khard.carddav_object.CarddavObject]

   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 CarddavObject objects


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

   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.carddav_object.CarddavObject]

   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(selected_address_books: khard.address_book.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


.. 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 addressbooks that were selected on the command line
   :param skip_already_added: skip if email_address is part of one or more contacts


.. 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) -> 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
   :param skip_already_added: skip already known email addresses


.. py:function:: birthdays_subcommand(vcard_list: List[khard.carddav_object.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 (    )


.. py:function:: phone_subcommand(search_terms: khard.query.Query, vcard_list: List[khard.carddav_object.CarddavObject], parsable: bool) -> None

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


.. py:function:: post_address_subcommand(search_terms: khard.query.Query, vcard_list: List[khard.carddav_object.CarddavObject], parsable: bool) -> None

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


.. py:function:: email_subcommand(search_terms: khard.query.Query, vcard_list: List[khard.carddav_object.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 '' ...)


.. 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.carddav_object.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


.. py:function:: modify_subcommand(selected_vcard: khard.carddav_object.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?


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

   Remove a contact from the addressbook.

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


.. py:function:: merge_subcommand(vcard_list: List[khard.carddav_object.CarddavObject], abooks: khard.address_book.AddressBookCollection, search_terms: khard.query.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


.. py:function:: copy_or_move_subcommand(action: str, vcard_list: List[khard.carddav_object.CarddavObject], target_address_books: khard.address_book.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


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


