khard.khard

Main application logic of khard includeing command line handling

Module Contents

Functions

confirm(message: str) → bool

Ask the user for confirmation on the terminal.

select(items: List[T], include_none: bool = False) → Optional[T]

Ask the user to select an item from a list.

write_temp_file(text: str = '') → str

Create a new temporary file and write some initial text to it.

edit(*filenames: str, merge: bool = False) → None

Edit the given files with the configured editor or merge editor

create_new_contact(address_book: VdirAddressBook) → None

modify_existing_contact(old_contact: CarddavObject) → None

merge_existing_contacts(source_contact: CarddavObject, target_contact: CarddavObject, delete_source_contact: bool) → None

copy_contact(contact: CarddavObject, target_address_book: VdirAddressBook, delete_source_contact: bool) → None

list_address_books(address_books: Union[AddressBookCollection, List[VdirAddressBook]]) → None

list_contacts(vcard_list: List[CarddavObject], fields: Iterable[str] = (), parsable: bool = False) → None

list_with_headers(the_list: List, *headers: str) → None

choose_address_book_from_list(header_string: str, address_books: Union[AddressBookCollection, List[VdirAddressBook]]) → Optional[VdirAddressBook]

choose_vcard_from_list(header_string: str, vcard_list: List[CarddavObject], include_none: bool = False) → Optional[CarddavObject]

get_contact_list_by_user_selection(address_books: Union[VdirAddressBook, AddressBookCollection], query: Query) → List[CarddavObject]

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

get_contacts(address_book: Union[VdirAddressBook, AddressBookCollection], query: Query, reverse: bool = False, group: bool = False, sort: str = 'first_name') → List[CarddavObject]

Get a list of contacts from one or more address books.

prepare_search_queries(args: Namespace) → Dict[str, Query]

Prepare the search query string from the given command line args.

generate_contact_list(args: Namespace) → List[CarddavObject]

Find the contact list with which we will work later on

new_subcommand(selected_address_books: AddressBookCollection, input_from_stdin_or_file: str, open_editor: bool) → None

Create a new contact.

add_email_to_contact(name: str, email_address: str, abooks: AddressBookCollection) → None

Add a new email address to the given contact,

find_email_addresses(text: str, fields: List[str]) → List[Address]

Search the text for email addresses in the given fields.

add_email_subcommand(text: str, abooks: AddressBookCollection, fields: List[str]) → None

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

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

Print birthday contact table.

phone_subcommand(vcard_list: List[CarddavObject], parsable: bool) → None

Print a phone application friendly contact table.

post_address_subcommand(vcard_list: List[CarddavObject], parsable: bool) → None

Print a contact table. with all postal / mailing addresses

email_subcommand(search_terms: Query, vcard_list: List[CarddavObject], parsable: bool, remove_first_line: bool) → None

Print a mail client friendly contacts table that is compatible with the

list_subcommand(vcard_list: List[CarddavObject], parsable: bool, fields: List[str]) → None

Print a user friendly contacts table.

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.

remove_subcommand(selected_vcard: CarddavObject, force: bool) → None

Remove a contact from the addressbook.

merge_subcommand(vcard_list: List[CarddavObject], abooks: AddressBookCollection, search_terms: Query) → None

Merge two contacts into one.

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.

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

khard.khard.logger
khard.khard.config :Config
khard.khard.T
khard.khard.confirm(message: str)bool

Ask the user for confirmation on the terminal.

Parameters

message – the question to print

Returns

the answer of the user

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

Parameters
  • items – the list from which to select

  • include_none – weather to allow the selection of no item

Returns

None or the selected item

khard.khard.write_temp_file(text: str = '')str

Create a new temporary file and write some initial text to it.

Parameters

text – the text to write to the temp file

Returns

the file name of the newly created temp file

khard.khard.edit(*filenames: str, merge: bool = False)None

Edit the given files with the configured editor or merge editor

khard.khard.create_new_contact(address_book: VdirAddressBook)None
khard.khard.modify_existing_contact(old_contact: CarddavObject)None
khard.khard.merge_existing_contacts(source_contact: CarddavObject, target_contact: CarddavObject, delete_source_contact: bool)None
khard.khard.copy_contact(contact: CarddavObject, target_address_book: VdirAddressBook, delete_source_contact: bool)None
khard.khard.list_address_books(address_books: Union[AddressBookCollection, List[VdirAddressBook]])None
khard.khard.list_contacts(vcard_list: List[CarddavObject], fields: Iterable[str] = (), parsable: bool = False)None
khard.khard.list_with_headers(the_list: List, *headers: str)None
khard.khard.choose_address_book_from_list(header_string: str, address_books: Union[AddressBookCollection, List[VdirAddressBook]])Optional[VdirAddressBook]
khard.khard.choose_vcard_from_list(header_string: str, vcard_list: List[CarddavObject], include_none: bool = False)Optional[CarddavObject]
khard.khard.get_contact_list_by_user_selection(address_books: Union[VdirAddressBook, AddressBookCollection], query: Query)List[CarddavObject]

Find contacts in the given address book grouped, sorted and reversed acording 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.get_contacts(address_book: Union[VdirAddressBook, AddressBookCollection], query: Query, reverse: bool = False, group: bool = False, sort: str = 'first_name')List[CarddavObject]

Get a list of contacts from one or more address books.

Parameters
  • address_book – the address book to search

  • query – a search query to select contacts

  • 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

contacts from the address_book that match the query

khard.khard.prepare_search_queries(args: Namespace)Dict[str, Query]

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 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: Namespace)List[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(selected_address_books: AddressBookCollection, input_from_stdin_or_file: str, open_editor: bool)None

Create a new contact.

Parameters
  • selected_address_books – a list of addressbooks that were selected on the command line

  • input_from_stdin_or_file – the data for the new contact as a yaml formatted string

  • open_editor – whether to open the new contact in the edior after creation

khard.khard.add_email_to_contact(name: str, email_address: str, abooks: AddressBookCollection)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 addressbooks that were selected on the command line

khard.khard.find_email_addresses(text: str, fields: List[str])List[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: AddressBookCollection, fields: List[str])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 addressbooks that were selected on the command line

  • field – the header field to extract contacts from

khard.khard.birthdays_subcommand(vcard_list: List[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 devided by tabulator ( )

khard.khard.phone_subcommand(vcard_list: List[CarddavObject], parsable: bool)None

Print a phone application friendly contact table.

Parameters
  • vcard_list – the vcards to search for matching entries which should be printed

  • parsable – machine readable output: columns devided by tabulator ( )

khard.khard.post_address_subcommand(vcard_list: List[CarddavObject], parsable: bool)None

Print a contact table. with all postal / mailing addresses

Parameters
  • vcard_list – the vcards to search for matching entries which should be printed

  • parsable – machine readable output: columns devided by tabulator ( )

khard.khard.email_subcommand(search_terms: Query, 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:

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

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

khard.khard.list_subcommand(vcard_list: List[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 devided by tabulator ( )

  • fields – list of strings for field evaluation

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

Parameters
  • selected_vcard – the contact to modify

  • 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

  • open_editor – whether to open the new contact in the edior after creation

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

khard.khard.remove_subcommand(selected_vcard: CarddavObject, force: bool)None

Remove a contact from the addressbook.

Parameters
  • selected_vcard – the contact to delete

  • force – delete without confirmation

khard.khard.merge_subcommand(vcard_list: List[CarddavObject], abooks: AddressBookCollection, search_terms: Query)None

Merge two contacts into one.

Parameters
  • vcard_list – the vcards from which to choose contacts for mergeing

  • abooks – the addressbooks to use to find the target contact

  • search_terms – the search terms to find the target contact

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

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

  • vcard_list – the contact list from which to select one for the action

  • target_address_books – the target address books

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