# khard.khard

Main application logic of khard including command line handling

## Attributes

`logger` |
`config` |
`ExitStatus` |

## Functions

`version_check`(→ bool) |
`create_new_contact`(→ None) |
`modify_existing_contact`(→ None) |
`merge_existing_contacts`(→ None) |
`copy_contact`(→ None) |
`list_address_books`(→ None) |
`list_contacts`(, parsable) |
`list_with_headers`(→ None) |
`choose_address_book_from_list`(...) | Let the user select one of the given address books
`choose_vcard_from_list`(→ Optional[khard.contacts.Contact]) | Let the user select a contact from a list
`get_contact_list`(→ list[khard.contacts.Contact]) | Find contacts in the given address book grouped, sorted and reversed
`sort_contacts`(→ list[khard.contacts.Contact]) | Sort a list of contacts
`prepare_search_queries`(→ dict[str, khard.query.Query]) | Prepare the search query string from the given command line args.
`generate_contact_list`(→ list[khard.contacts.Contact]) | Find the contact list with which we will work later on
`new_subcommand`(→ ExitStatus) | Create a new contact.
`add_email_to_contact`(→ None) | Add a new email address to the given contact,
`find_email_addresses`(→ list[email.headerregistry.Address]) | Search the text for email addresses in the given fields.
`add_email_subcommand`(→ ExitStatus) | Add a new email address to contacts, creating new contacts if necessary.
`birthdays_subcommand`(→ ExitStatus) | Print birthday contact table.
`phone_subcommand`(→ ExitStatus) | Print a phone application friendly contact table.
`post_address_subcommand`(→ ExitStatus) | Print a contact table with all postal / mailing addresses
`email_subcommand`(→ ExitStatus) | Print a mail client friendly contacts table that is compatible with the
`_filter_email_post_or_phone_number_results`(→ list[str]) | Filter the created output of phone_subcommand, post_address_subcommand
`list_subcommand`(→ ExitStatus) | Print a user friendly contacts table.
`modify_subcommand`(→ ExitStatus) | Modify a contact in an external editor.
`remove_subcommand`(→ None) | Remove a contact from the address book.
`merge_subcommand`(→ ExitStatus) | Merge two contacts into one.
`copy_or_move_subcommand`(→ ExitStatus) | Copy or move a contact to a different address book.
`main`(→ ExitStatus) |

## Module Contents

khard.khard.logger

khard.khard.config: khard.config.Config

khard.khard.ExitStatus

khard.khard.version_check(contact: khard.contacts.Contact, description: str) → bool

khard.khard.create_new_contact(address_book: khard.address_book.VdirAddressBook) → None

khard.khard.modify_existing_contact(old_contact: khard.contacts.Contact) → None

khard.khard.merge_existing_contacts(source_contact: khard.contacts.Contact, target_contact: khard.contacts.Contact, delete_source_contact: bool) → None

khard.khard.copy_contact(contact: khard.contacts.Contact, target_address_book: khard.address_book.VdirAddressBook, delete_source_contact: bool) → None

khard.khard.list_address_books(address_books: khard.address_book.AddressBookCollection | list[khard.address_book.VdirAddressBook]) → None

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

khard.khard.list_with_headers(the_list: list[str], *headers: str) → None

khard.khard.choose_address_book_from_list(header: str, abooks: khard.address_book.AddressBookCollection | list[khard.address_book.VdirAddressBook]) → khard.address_book.VdirAddressBook | None

  Let the user select one of the given address books

  Parameters:

    - header – some text to print in front of the list

    - abooks – the address books from which to select

  Returns:

    the selected address book

  Raises:

    Canceled – when the user canceled the selection

khard.khard.choose_vcard_from_list(header: str, vcards: list[khard.contacts.Contact], include_none: bool = False) → khard.contacts.Contact | None

  Let the user select a contact from a list

  Parameters:

    - header – some text to print in front of the list

    - vcards – the contacts from which to select

  Returns:

    the selected contact

  Raises:

    Canceled – when the user canceled the selection

khard.khard.get_contact_list(address_books: 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.

  Parameters:

    - address_books – the address book to search

    - query – the query to use when searching

  Returns:

    list of found Contact objects

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

  Parameters:

    - contacts – the contact list to sort

    - reverse – reverse the order of the returned contacts

    - group – group results by address book

    - sort – the field to use for sorting, one of “first_name”, “last_name”, “formatted_name”

  Returns:

    sorted contact list

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

  Parameters:

    args – the parsed command line

  Returns:

    a dict mapping abook names to their loading queries

khard.khard.generate_contact_list(args: argparse.Namespace) → list[khard.contacts.Contact]

  Find the contact list with which we will work later on

  Parameters:

    args – the command line arguments

  Returns:

    the contacts for further processing

khard.khard.new_subcommand(abooks: khard.address_book.AddressBookCollection, data: str, open_editor: bool) → ExitStatus

  Create a new contact.

  Parameters:

    - abooks – a list of address books that were selected on the command line

    - data – the data for the new contact as a yaml formatted string

    - open_editor – whether to open the new contact in the editor after creation

  Raises:

    Canceled – when the user canceled a selection

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

  Parameters:

    - name – name of the contact

    - email_address – email address of the contact

    - abooks – the address books that were selected on the command line

    - skip_already_added – skip if email_address is part of one or more contacts

  Raises:

    Canceled – when the user canceled a selection

khard.khard.find_email_addresses(text: str, fields: list[str]) → list[email.headerregistry.Address]

  Search the text for email addresses in the given fields.

  Parameters:

    - text – the text to search for email addresses

    - fields – the fields to look in for email addresses. The all field searches all headers.

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

  Parameters:

    - text – the input text to search for the new email

    - abooks – the address books that were selected on the command line

    - field – the header field to extract contacts from

    - skip_already_added – skip already known email addresses

  Raises:

    Canceled – when the user canceled a selection

khard.khard.birthdays_subcommand(vcard_list: list[khard.contacts.Contact], parsable: bool) → ExitStatus

  Print birthday contact table.

  Parameters:

    - vcard_list – the vCards to search for matching entries which should be printed

    - parsable – machine readable output: columns divided by tabulator ( )

khard.khard.phone_subcommand(search_terms: khard.query.Query, vcard_list: list[khard.contacts.Contact], parsable: bool) → ExitStatus

  Print a phone application friendly contact table.

  Parameters:

    - search_terms – used as search term to filter the contacts before printing

    - vcard_list – the vCards to search for matching entries which should be printed

    - parsable – machine readable output: columns divided by tabulator ( )

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

  Parameters:

    - search_terms – used as search term to filter the contacts before printing

    - vcard_list – the vCards to search for matching entries which should be printed

    - parsable – machine readable output: columns divided by tabulator ( )

khard.khard.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:

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

  Parameters:

    - search_terms – used as search term to filter the contacts before printing

    - vcard_list – the vCards to search for matching entries which should be printed

    - parsable – machine readable output: columns divided by tabulator ( )

    - remove_first_line – remove first line (searching for ‘’ …)

khard.khard._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

  Parameters:

    - search_terms – used as search term to filter the contacts before printing

    - field_line_list – The line-by-line output of the commands listed above

khard.khard.list_subcommand(vcard_list: list[khard.contacts.Contact], parsable: bool, fields: list[str]) → ExitStatus

  Print a user friendly contacts table.

  Parameters:

    - vcard_list – the vCards to print

    - parsable – machine readable output: columns divided by tabulator ( )

    - fields – list of strings for field evaluation

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

  Parameters:

    - selected_vcard – the contact to modify

    - 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

    - open_editor – whether to open the new contact in the editor after creation

    - source – edit the source file or a yaml version?

khard.khard.remove_subcommand(selected_vcard: khard.contacts.Contact, force: bool) → None

  Remove a contact from the address book.

  Parameters:

    - selected_vcard – the contact to delete

    - force – delete without confirmation

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

  Merge two contacts into one.

  Parameters:

    - vcards – the vCards from which to choose contacts for merging

    - abooks – the address books to use to find the target contact

    - search_terms – the search terms to find the target contact

  Raises:

    Canceled – when the user canceled a selection

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

  Parameters:

    - action – the string “copy” or “move” to indicate what to do

    - vcards – the contact list from which to select one for the action

    - target_address_books – the target address books

  Raises:

    Canceled – when the user canceled a selection

khard.khard.main(argv: list[str] = sys.argv[1:]) → ExitStatus