:py:mod:`khard.khard` ===================== .. py:module:: khard.khard .. autoapi-nested-parse:: Main application logic of khard including 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 :type: 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[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 interactive.Canceled: when the user canceled the selection .. py:function:: choose_vcard_from_list(header: str, vcards: List[khard.carddav_object.CarddavObject], include_none: bool = False) -> Optional[khard.carddav_object.CarddavObject] 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 interactive.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.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(abooks: khard.address_book.AddressBookCollection, data: str, open_editor: bool) -> None 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 interactive.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 interactive.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) -> 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 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 interactive.Canceled: when the user canceled a selection .. 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 divided 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 divided 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 divided 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 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.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 divided 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 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.carddav_object.CarddavObject, 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.carddav_object.CarddavObject], abooks: khard.address_book.AddressBookCollection, search_terms: khard.query.Query) -> None 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 interactive.Canceled: when the user canceled a selection .. py:function:: copy_or_move_subcommand(action: str, vcards: 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 vcards: the contact list from which to select one for the action :param target_address_books: the target address books :raises interactive.Canceled: when the user canceled a selection .. py:function:: main(argv: List[str] = sys.argv[1:]) -> None