: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], search: Optional[List[str]], strict_search: bool) -> List[CarddavObject] returns a list of CarddavObject objects :param address_books: selected address books :param search: filter contact list :param strict_search: if True, search only in full name field :returns: list of CarddavObject objects .. function:: get_contacts(address_book: Union[VdirAddressBook, AddressBookCollection], query: Optional[List[str]], method: str = 'all', 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 method: the search method, one of "all", "name" or "uid" :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) 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 regexes have to be combined into one search string. :param args: the parsed command line :type args: argparse.Namespace :returns: a dict mapping abook names to their loading queries, if the query is None it means that all cards should be loaded :rtype: dict(str:list(list(str)) or None) .. function:: generate_contact_list(args: Namespace) -> List[CarddavObject] TODO: Docstring for generate_contact_list. :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_subcommand(text: str, abooks: AddressBookCollection) -> 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 .. 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(search_terms: List[str], vcard_list: List[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 ( ) .. function:: post_address_subcommand(search_terms: List[str], vcard_list: List[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 ( ) .. function:: email_subcommand(search_terms: List[str], 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, selected_address_books, search_terms, target_uid) -> None Merge two contacts into one. :param vcard_list: the vcards from which to choose contacts for mergeing :type vcard_list: list(carddav_object.CarddavObject) :param AddressBookCollection selected_address_books: the addressbooks to use to find the target contact :param str search_terms: the search terms to find the target contact :param str target_uid: the uid of the target contact or empty .. 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