khard.khard

Main application logic of khard including command line handling

Module Contents

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(...)

Let the user select a contact from a list

get_contact_list(...)

Find contacts in the given address book grouped, sorted and reversed

sort_contacts(→ List[khard.carddav_object.CarddavObject])

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(...)

Find the contact list with which we will work later on

new_subcommand(→ None)

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(→ None)

Add a new email address to contacts, creating new contacts if necessary.

birthdays_subcommand(→ None)

Print birthday contact table.

phone_subcommand(→ None)

Print a phone application friendly contact table.

post_address_subcommand(→ None)

Print a contact table with all postal / mailing addresses

email_subcommand(→ None)

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(→ None)

Print a user friendly contacts table.

modify_subcommand(→ None)

Modify a contact in an external editor.

remove_subcommand(→ None)

Remove a contact from the address book.

merge_subcommand(→ None)

Merge two contacts into one.

copy_or_move_subcommand(→ None)

Copy or move a contact to a different address book.

main(→ None)

Attributes

logger

config

khard.khard.logger
khard.khard.config: khard.config.Config
khard.khard.version_check(contact: khard.carddav_object.CarddavObject, description: str) → bool
khard.khard.create_new_contact(address_book: khard.address_book.VdirAddressBook) → None
khard.khard.modify_existing_contact(old_contact: khard.carddav_object.CarddavObject) → None
khard.khard.merge_existing_contacts(source_contact: khard.carddav_object.CarddavObject, target_contact: khard.carddav_object.CarddavObject, delete_source_contact: bool) → None
khard.khard.copy_contact(contact: khard.carddav_object.CarddavObject, 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.carddav_object.CarddavObject], 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:

interactive.Canceled – when the user canceled the selection

khard.khard.choose_vcard_from_list(header: str, vcards: List[khard.carddav_object.CarddavObject], include_none: bool = False) → khard.carddav_object.CarddavObject | 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:

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

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

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

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

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) → None

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:

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

interactive.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) → None

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:

interactive.Canceled – when the user canceled a selection

khard.khard.birthdays_subcommand(vcard_list: List[khard.carddav_object.CarddavObject], parsable: bool) → None

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.carddav_object.CarddavObject], parsable: bool) → None

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.carddav_object.CarddavObject], parsable: bool) → None

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

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.carddav_object.CarddavObject], parsable: bool, fields: List[str]) → None

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.carddav_object.CarddavObject, input_from_stdin_or_file: str, open_editor: bool, source: bool = False) → None

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.carddav_object.CarddavObject, 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.carddav_object.CarddavObject], abooks: khard.address_book.AddressBookCollection, search_terms: khard.query.Query) → None

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:

interactive.Canceled – when the user canceled a selection

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

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:

interactive.Canceled – when the user canceled a selection

khard.khard.main(argv: List[str] = sys.argv[1:]) → None