Welcome to khard’s documentation!

Command line usage

The following subsections give an overview of khard’s main features.

You may get general help and all available actions with

khard --help

If you need help on a specific action, use:

khard action --help

Beware, that the order of the command line parameters matters.

Show contacts

After you have created a new address book or calendar and you have synced it to your local machine, you can list all available contacts with the following command:

khard list

or if you have more than one address book and you want to filter the output:

khard list -a addressbook1,addressbook2

The resulting contact table only contains the first phone number and email address. If you want to view all contact details you can pick one from the list:

khard details

or search for it:

khard details [--strict-search] name of contact

or select the contact by it’s uid, which you can find at the contacts table:

khard details -u ID

The parameters -a and -u from the examples above are always optional. If you don’t use them or your input produces unambiguous results, you may pick the contacts from a list instead.

The search parameter searches in all data fields. Therefore you aren’t limited to the contact’s name but you also could for example search for a part of a phone number, email address or post address. However if you explicitly want to narrow your search to the name field, you may use the –strict-search parameter instead.

Create contact

Add new contact with the following command:

khard new [-a "address book name"]

The template for the new contact opens in the text editor, which you can set in the khard.conf file. It follows the yaml syntax.

Alternatively you can create the contact from stdin:

echo """
First name : John
Last name  : Smith
Email :
    work : john.smith@example.org
Phone :
    home : xxx 555 1234
Categories :
    - cat1
    - cat2
    - cat3
""" | khard new [-a "address book name"]

or create from input template file:

khard new -i contact.yaml [-a "address book name"]

You may get an empty contact template with the following command:

khard export --empty-contact-template -o empty.yaml

Per default khard creates vcards of version 3.0. If your other contact applications support vcards of the more recent version 4.0, you may change this with the option –vcard-version. Example:

khard new --vcard-version=4.0 [-a "address book name"]

For a more permanent solution you may set the preferred_version parameter in the vcard section of the khard config file (see misc/khard/khard.conf.example for more details). But beware, that khard cannot convert already existing contacts from version 3.0 to 4.0. Therefore this setting is not applicable to the modify action.

Edit contacts

Use the following to modify the contact after successful creation:

khard modify [-a addr_name] [-u uid|search terms [search terms ...]]

If you want to edit the contact elsewhere, you can export the filled contact template:

khard export -o contact.yaml [-a addr_name] [-u uid|search terms [search terms ...]]

Edit the yaml file and re-import either through stdin:

cat contact.yaml | khard modify [-a addr_name] [-u uid|search terms [search terms ...]]

or file name:

khard modify -i contact.yaml [-a addr_name] [-u uid|search terms [search terms ...]]

If you want to merge contacts use the following to select a first and then a second contact:

khard merge [-a source_abook] [-u uid|search terms [search terms ...]] [-A target_abook] [-U target_uid|-t target_search_terms]

You will be launched into your merge_editor ( see the “merge_editor” option in khard.conf) where you can merge all changes from the first selected contact onto the second. Once you are finished, the first contact is deleted and the second one updated.

Copy or move contact:

khard copy [-a source_abook] [-u uid|search terms [search terms ...]] [-A target_abook]
khard move [-a source_abook] [-u uid|search terms [search terms ...]] [-A target_abook]

Remove contact:

khard remove [-a addr_name] [-u uid|search terms [search terms ...]]

Davcontroller

Khard also contains a helper script called davcontroller. It’s designed to create and remove address books and calendars at the server. I have created davcontroller cause my previously used CalDAV server (Darwin calendarserver) offered no simple way to create new address books and calendars. But davcontroller should be considered as a hacky solution and it’s only tested against the Darwin calendarserver. So if your CalDAV server offers a way to create new address books and calendars I recommend to prefer that method over davcontroller.

If you nonetheless want to try davcontroller, you have to install the CalDAVClientLibrary first. Unfortunately that library isn’t compatible to python3 so you have to create an extra python2 virtual environment and install in there:

# create python2 virtual environment
virtualenv -p python2 ~/.virtualenvs/davcontroller
# get library from svn repository
sudo aptitude install subversion
svn checkout http://svn.calendarserver.org/repository/calendarserver/CalDAVClientLibrary/trunk CalDAVClientLibrary
cd CalDAVClientLibrary
# install library
~/.virtualenvs/davcontroller/bin/python setup.py install
# start davcontroller script
~/.virtualenvs/davcontroller/bin/python /path/to/khard-x.x.x/misc/davcontroller/davcontroller.py

This small script helps to create and remove new address books and calendars at the carddav and caldav server.

List available resources:

davcontroller -H example.com -p 11111 -u USERNAME -P PASSWORD list

Possible actions are: list, new-addressbook, new-calendar and remove. After creating or removing you must adapt your vdirsyncer config.

Contributing

Thank you for considering contributing to khard!

Benchmarking, profiling and performance

When benchmarking code it is important to reduce other load on the system (music player, web browser for example). One can use the python timeit module or a command line utility like hyperfine:

python -m timeit -s 'from khard.khard import main' 'main(["list"])'
hyperfine 'python -m khard list'

For profiling the cProfile python module works well. With the help of gprof2dot one can generate quite useful graphs:

python -m cProfile -o output.file -m khard list
gprof2dot -f pstats --show-samples output.file | dot -T png > graph.png
xdg-open graph.png

Khard is developed on Github where you are welcome to post bug reports, feature requests or join the discussion in general.

Bug reports

If you want to report a bug keep in mind that the following things make it much easier for maintainers to help:

• update to the latest version if possible and verify the bug there

• report the version(s) that are affected

• state the python version you are using

• if there are stack tracebacks post them with your bug report

• supply a minimal configuration (config file and vcards) to reproduce the error

Feature requests

Please stick to the following standards when you open pull requests:

• Khard’s development tries to follow Vincent’s branching model so normal pull requests should be made against the develop branch. Only important bug fixes that affect the current release should be opened against master.

• Write “good” commit messages, especially a proper subject line. This is also explained in the Git book.

• Format your python code according to PEP 8.

• Khard has a test suite, please provide tests for bugs that you fix and also for new code and new features that are introduced.

• Please verify all tests pass before sending a pull request, they will be checked again by travis but it might be a lot faster to check locally first:

Development

In order to start coding you need to fetch the develop branch:

git clone https://github.com/scheibler/khard
cd khard
git fetch --all
git checkout develop
python -m kard --help
# or
pip3 install --editable .
khard --help

Alternatively you can use the setup.py script directly. If you want to isolate khard from your system Python environment you can use a virtualenv to do so.

Manpages

The following man pages are available for khard:

khard

Synopsis

khard [-c CONFIG] [–debug] [–skip-unparsable] SUBCOMMAND …

khard -h|–help

khard -v|–version

Description

Khard is an address book for the Linux command line. It can read, create, modify and delete carddav address book entries. Khard only works with a local store of VCARD files. It is intended to be used in conjunction with other programs like an email client, text editor, vdir synchronizer or VOIP client.

Options

-c CONFIG, --config CONFIG

configuration file (default: ~/.config/khard/khard.conf)

--debug

output debugging information

--skip-unparsable

skip unparsable vcards when reading the address books

Subcommands

The functionality of khard is divided into several subcommands. All of these have their own help text which can be seen with khard SUBCOMMAND --help.

Listing subcommands

These subcommands list information of several contacts who match a search query.

list

list all (selected) contacts

birthdays

list birthdays (sorted by month and day)

email

list email addresses

phone

list phone numbers

postaddress

list postal addresses

filename

list filenames of all matching contacts

Detailed display

These subcommands display detailed information about one subcommand.

details

display detailed information about one contact

export

export a contact to the custom yaml format that is also used for editing and creating contacts

Modifying subcommands

These subcommands are used to modify contacts.

source

edit the vcard file of a contact directly

new

create a new contact

add-email

Extract email address from the “From:” field of an email header and add to an existing contact or create a new one

merge

merge two contacts

modify

edit the data of a contact

copy

copy a contact to a different addressbook

move

move a contact to a different addressbook

remove

remove a contact

Other subcommands

addressbooks

list all address books

Configuration

See khard.conf(5).

khard.conf

Summary

The config file for khard is a plain text file with an ini-like syntax. Many options have a corresponding command line option. The only mandatory section in the config file is the definition of the available address books.

Location

The file is looked up at $XDG_CONFIG_HOME/khard/khard.conf. If the environment variable $XDG_CONFIG_HOME is unset ~/.config/ is used in its stead.

The location can be changed with the environment variable $KHARD_CONFIG or the command line option -c (which takes precedence).

Syntax

The syntax of the config file is ini-style dialect. It is parsed with the configobj library. The precise definition of the corresponding ini syntax can be found at https://configobj.readthedocs.io/en/latest/configobj.html#the-config-file-format .

It supports sections marked with square brackets and nested sections with more square brackets. Each section contains several keys with values delimited by equal signs. The values are typed and type checked.

Options

The config file consists of these four sections:

adressbooks

This section contains several subsections, but at least one. Each subsection can have an arbitrary name which will be the name of an addressbook known to khard. Each of these subsections must have a path key with the path to the folder containing the vcard files for that addressbook.

general

This section allows one to configure some general features about khard. The following keys are available in this section:

• debug: a boolean indication weather the logging level should be set to debug by default (same effect as the --debug option on the command line)

• default_action: the default action/subcommand to use if the first non option argument does not match any of the available subcommands

• editor: the text editor to use to edit address book entries, if not given $EDITOR will be used

• merge_editor: a command used to merge two cards interactively, if not given, $MERGE_EDITOR will be used

contact table

This section is used to configure the behaviour of different output listings of khard. The following keys are available:

• display: which part of the name to use in listings; this can be one of first_name, last_name or formatted_name

• group_by_addressbook: weather or not to group contacts by address book in listings

• localize_dates: weather to localize dates or to use ISO date formats

• preferred_email_address_type: labels of email addresses to prefer

• preferred_phone_number_type: labels of telephone numbers to prefer

• reverse: weather to reverse the order of contact listings or not

• show_nicknames: weather to show nick names

• show_uids: weather to show uids

• sort: field by which to sort contact listings

vcard

• private_objects: a list of strings, these are the names of private vCard fields (starting with X-) that will be loaded and displayed by khard

• search_in_source_files: weather to search in the vcard files before parsing them in order to speed up searches

• skip_unparsable: weather to skip unparsable vcards, otherwise khard exits on the first unparsable card it encounters

• preferred_version: the preferred vcard version to use for new cards

Example

This is the example config file:

# example configuration file for khard version > 0.14.0
# place it under ~/.config/khard/khard.conf

[addressbooks]
[[family]]
path = ~/.contacts/family/
[[friends]]
path = ~/.contacts/friends/

[general]
debug = no
default_action = list
# These are either strings or comma seperated lists
editor = vim, -i, NONE
merge_editor = vimdiff

[contact table]
# display names by first or last name: first_name / last_name / formatted_name
display = first_name
# group by address book: yes / no
group_by_addressbook = no
# reverse table ordering: yes / no
reverse = no
# append nicknames to name column: yes / no
show_nicknames = no
# show uid table column: yes / no
show_uids = yes
# sort by first or last name: first_name / last_name / formatted_name
sort = last_name
# localize dates: yes / no
localize_dates = yes
# set a comma separated list of preferred phone number types in descending priority
# or nothing for non-filtered alphabetical order
preferred_phone_number_type = pref, cell, home
# set a comma separated list of preferred email address types in descending priority
# or nothing for non-filtered alphabetical order
preferred_email_address_type = pref, work, home

[vcard]
# extend contacts with your own private objects
# these objects are stored with a leading "X-" before the object name in the vcard files
# every object label may only contain letters, digits and the - character
# example:
#   private_objects = Jabber, Skype, Twitter
private_objects = Jabber, Skype, Twitter
# preferred vcard version: 3.0 / 4.0
preferred_version = 3.0
# Look into source vcf files to speed up search queries: yes / no
search_in_source_files = no
# skip unparsable vcard files: yes / no
skip_unparsable = no

khard

khard package

Submodules

khard.actions module

Names and aliases for the subcommands on the command line

class khard.actions.Actions

Bases: object

A class to manage the names and aliases of the command line subcommands.

action_map = {'add-email': [], 'addressbooks': ['abooks'], 'birthdays': ['bdays'], 'copy': ['cp'], 'edit': ['modify', 'ed'], 'email': [], 'export': [], 'filename': ['file'], 'list': ['ls'], 'merge': [], 'move': ['mv'], 'new': ['add'], 'phone': [], 'postaddress': ['post', 'postaddr'], 'remove': ['delete', 'del', 'rm'], 'show': ['details'], 'source': ['src'], 'template': []}

classmethod get_action(alias)

Find the name of the action for the supplied alias. If no action is asociated with the given alias, None is returned.

Parameters

alias (str) – the alias to look up

Rturns

the name of the corresponding action or None

Return type

str or NoneType

classmethod get_actions()

Find the names of all defined actions.

Returns

all action names

Return type

iterable(str)

classmethod get_aliases(action)

Find all aliases for the given action. If there is no such action, None is returned.

Parameters

action (str) – the action name to look up

Returns

the list of aliases corresponding to the action or None

Return type

list(str) or NoneType

classmethod get_all()

Find the names of all defined actions and their aliases.

Returns

the names of all actions and aliases

Return type

generator(str)

khard.address_book module

A simple class to load and manage the vcard files from disk.

class khard.address_book.AddressBook(name, private_objects=(), localize_dates=True, skip=False)

Bases: object

The base class of all address book implementations.

get_short_uid(uid)

Get the shortend UID for the given UID.

Parameters

uid (str) – the full UID to shorten

Returns

the shortend uid or the empty string

Return type

str

get_short_uid_dict(query=None)

Create a dictionary of shortend UIDs for all contacts.

All arguments are only used if the address book is not yet initialized and will just be handed to self.load().

Parameters

query (str) – see self.load()

Returns

the contacts mapped by the shortes unique prefix of their UID

Return type

dict(str: CarddavObject)

abstract load(query=None)

Load the vCards from the backing store.

If a query is given loading is limited to entries which match the query. If the query is None all entries will be loaded.

Parameters

query (str) – the query to limit loading to matching entries

Returns

the number of loaded contacts and the number of errors

Return type

(int, int)

search(query, method='all')

Search this address book for contacts matching the query.

The method can be one of “all”, “name” and “uid”. The backend for this address book migth be load()ed if needed.

Parameters

• query (str) – the query to search for

• method (str) – the type of fileds to use when seaching

Returns

all found contacts

Return type

list(carddav_object.CarddavObject)

class khard.address_book.AddressBookCollection(name, abooks, **kwargs)

Bases: khard.address_book.AddressBook

A collection of several address books.

This represents a temporary merege of the contact collections provided by the underlying adress books. On load all contacts from all subadressbooks are copied into a dict in this address book. This allow this class to use all other methods from the parent AddressBook class.

get_abook(name)

Get one of the backing abdress books by its name,

Parameters

name (str) – the name of the address book to get

Returns

the matching address book or None

Return type

AddressBook or NoneType

load(query=None)

Load the vCards from the backing store.

If a query is given loading is limited to entries which match the query. If the query is None all entries will be loaded.

Parameters

query (str) – the query to limit loading to matching entries

Returns

the number of loaded contacts and the number of errors

Return type

(int, int)

exception khard.address_book.AddressBookParseError(filename, abook, reason, *args, **kwargs)

Bases: Exception

Indicate an error while parsing data from an address book backend.

class khard.address_book.VdirAddressBook(name, path, **kwargs)

Bases: khard.address_book.AddressBook

An AddressBook implementation based on a vdir.

This address book can load contacts from vcard files that reside in one direcotry on disk.

load(query=None, search_in_source_files=False)

Load all vcard files in this address book from disk.

If a search string is given only files which contents match that will be loaded.

Parameters

• query (str) – a regular expression to limit the results

• search_in_source_files (bool) – apply search regexp directly on the .vcf files to speed up parsing (less accurate)

Returns

the number of successfully loaded cards and the number of errors

Return type

int, int

Throws

AddressBookParseError

khard.carddav_object module

Classes and logic to handle vCards in khard.

This module explicitly supports the vCard specifications version 3.0 and 4.0 which can be found here: - version 3.0: https://tools.ietf.org/html/rfc2426 - version 4.0: https://tools.ietf.org/html/rfc6350

class khard.carddav_object.CarddavObject(vcard, address_book, filename, supported_private_objects=None, vcard_version=None, localize_dates=False)

Bases: khard.carddav_object.YAMLEditable

classmethod clone_with_yaml_update(contact, yaml, localize_dates=False)

Use this if you want to clone an existing contact and replace its data with new user input in one step.

delete_vcard_file()

classmethod from_file(address_book, filename, query, supported_private_objects=None, localize_dates=False)

Load a CarddavObject object from a .vcf file if the plain file matches the query.

Parameters

• address_book (address_book.AddressBook) – the address book where this contact is stored

• filename (str) – the file name of the .vcf file

• query (re.Pattern|str|NoneType) – the regex to search in the source file or None to load the file unconditionally

• supported_private_objects (list(str)|NoneType) – the list of private property names that will be loaded from the actual vcard and represented in this pobject

• vcard_version (str|NoneType) – the version of the RFC to use

• localize_dates (bool) – should the formatted output of anniversary and birthday be localized or should the isoformat be used instead

Returns

the loaded CarddavObject or None if the file didn’t match

Return type

CarddavObject or NoneType

classmethod from_yaml(address_book, yaml, supported_private_objects=None, version=None, localize_dates=False)

Use this if you want to create a new contact from user input.

classmethod new(address_book, supported_private_objects=None, version=None, localize_dates=False)

Create a new CarddavObject from scratch

print_vcard(show_address_book=True, show_uid=True)

write_to_file(overwrite=False)

class khard.carddav_object.VCardWrapper(vcard, version=None)

Bases: object

Wrapper class around a vobject.vCard object.

This class can wrap a single vCard and presents its data in a manner suitable for khard. Additionally some details of the vCard specifications in RFC 2426 (version 3.0) and RFC 6350 (version 4.0) that are not enforced by the vobject library are enforced here.

add_email(type, address)

address_types_v3 = ('dom', 'intl', 'home', 'parcel', 'postal', 'work')

address_types_v4 = ('home', 'work')

property anniversary

Returns

contacts anniversary or None if not available

Return type

datetime.datetime or str

property birthday

Return the birthday as a datetime object or a string depending on weather it is of type text or not. If no birthday is present in the vcard None is returned.

Returns

contacts birthday or None if not available

Return type

datetime.datetime or str or NoneType

property categories

Return type

list(str) or list(list(str))

email_types_v3 = ('home', 'internet', 'work', 'x400')

email_types_v4 = ('home', 'internet', 'work')

property emails

Returns

dict of type and email address list

Return type

dict(str, list(str))

property formatted_name

get_first_name_last_name()

Return type

str

get_formatted_post_addresses()

get_last_name_first_name()

Return type

str

property nicknames

Return type

list(str or dict(str))

property notes

Return type

list(str or dict(str))

property organisations

Returns

list of organisations, sorted alphabetically

Return type

list(list(str) or dict(list(str)))

property phone_numbers

Returns

dict of type and phone number list

Return type

dict(str, list(str))

phone_types_v3 = ('bbs', 'car', 'cell', 'fax', 'home', 'isdn', 'msg', 'modem', 'pager', 'pcs', 'video', 'voice', 'work')

phone_types_v4 = ('text', 'voice', 'fax', 'cell', 'video', 'pager', 'textphone', 'home', 'work')

property post_addresses

Returns

dict of type and post address list

Return type

dict(str, list(dict(str,list|str)))

property roles

Return type

list(str or dict(str))

property titles

Return type

list(str or dict(str))

property uid

property version

property webpages

Return type

list(str or dict(str))

class khard.carddav_object.YAMLEditable(vcard, supported_private_objects=None, version=None, localize_dates=False)

Bases: khard.carddav_object.VCardWrapper

Conversion of vcards to YAML and updateing the vcard from YAML

get_formatted_anniversary()

get_formatted_birthday()

get_template()

update(input)

Update this vcard with some yaml input

Parameters

input (str) – a yaml string to parse and then use to update self

Returns

None

khard.carddav_object.convert_to_vcard(name, value, allowed_object_type)

converts user input into vcard compatible data structures

Parameters

• name (str) – object name, only required for error messages

• value (str or list(str)) – user input

• allowed_object_type (enum of type ObjectType) – set the accepted return type for vcard attribute

Returns

cleaned user input, ready for vcard or a ValueError

Return type

str or list(str)

khard.carddav_object.multi_property_key(item)

key function to pass to sorted(), allowing sorting of dicts with lists and strings. Dicts will be sorted by their label, after other types.

Parameters

item (a dict with a single entry or any sortable type) – member of the list being sorted

Returns

a list with two members. The first is int(isinstance(item, dict). The second is either the key from the dict or the unchanged item if it is not a dict.

:rtype list(int, type(item)) or list(int, str)

khard.cli module

Command line parsing and configuration logic for khard

khard.cli.create_parsers()

Create two argument parsers.

The first parser is manly used to find the config file which can than be used to set some default values on the second parser. The second parser can parse the remainder of the command line with the subcommand and all further options and arguments.

Returns

the two parsers for the first and the second parsing pass

Return type

(argparse.ArgumentParser, argparse.ArgumentParser)

khard.cli.init(argv)

Initialize khard by parsing the command line and reading the config file

Parameters

argv (list(str)) – the command line arguments

Returns

the parsed command line and the fully initialized config

Return type

(argparse.Namespace, Config)

khard.cli.merge_args_into_config(args, config)

Merge the parsed arguments from argparse into the config object.

Parameters

• args (argparse.Namespace) – the parsed command line arguments

• config (config.Config) – the parsed config file

Returns

the merged config object

Return type

config.Config

khard.cli.parse_args(argv)

Parse the command line arguments and return the namespace that was creates by argparse.ArgumentParser.parse_args().

Parameters

argv (list(str)) – the command line arguments

Returns

the namespace parsed from the command line

Return type

argparse.Namespace

khard.config module

Loading and validation of the configuration file

class khard.config.Config(config_file=None)

Bases: object

load_address_books()

merge(other)

Merge the config with some other dict or ConfigObj

Parameters

other – the other dict or ConfigObj to merge into self

Returns

None

supported_vcard_versions = ('3.0', '4.0')

khard.config.exit(message, prefix='Error in config file\n')

Exit with a message and a return code indicating an error in the config file.

This function doesn’t return, it calls sys.exit.

Parameters

• message (str) – the message to print

• prefix (str) – the prefix to put in front of the message

Returns

does not return

khard.config.validate_action(value)

Check that the given value is a valid action.

Parameters

value – the config value to check

Returns

the same value

Return type

str

Raises

validate.ValidateError

khard.config.validate_command(value)

Special validator to check shell commands

The input must either be a list of strings or a string that shlex.split can parse into such.

Parameters

value – the config value to validate

Returns

the command after validation

Return type

list(str)

Raises

validate.ValidateError

khard.config.validate_private_objects(value)

Check that the private objects are reasonable

Parameters

value – the config value to check

Returns

the list of private objects

Return type

list(str)

Raises

validate.ValidateError

khard.helpers module

Some helper functions for khard

khard.helpers.convert_to_yaml(name, value, indentation, index_of_colon, show_multi_line_character)

converts a value list into yaml syntax

Parameters

• name (str) – name of object (example: phone)

• value (str, list(str), list(list(str)), list(dict)) – object contents

• indentation (int) – indent all by number of spaces

• index_of_colon (int) – use to position : at the name string (-1 for no space)

• show_multi_line_character (bool) – option to hide “|”

Returns

yaml formatted string array of name, value pair

Return type

list(str)

khard.helpers.file_modification_date(filename)

khard.helpers.get_new_contact_template(supported_private_objects=None)

khard.helpers.get_random_uid()

khard.helpers.indent_multiline_string(input, indentation, show_multi_line_character)

khard.helpers.list_to_string(input, delimiter)

converts list to string recursively so that nested lists are supported

Parameters

• input (list) – a list of strings and lists of strings (and so on recursive)

• delimiter (str) – the deimiter to use when joining the items

Returns

the recursively joined list

Return type

str

khard.helpers.pretty_print(table, justify='L')

khard.helpers.string_to_date(string)

Convert a date string into a date object.

Parameters

string (str) – the date string to parse

Returns

the parsed datetime object

Return type

datetime.datetime

khard.helpers.string_to_list(input, delimiter)

khard.khard module

Main application logic of khard includeing command line handling

khard.khard.add_email_subcommand(text, abooks)

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

Parameters

• text (str) – the input text to search for the new email

• abooks (list of address_book.AddressBook) – the addressbooks that were selected on the command line

Returns

None

Return type

None

khard.khard.birthdays_subcommand(vcard_list, parsable)

Print birthday contact table.

Parameters

• vcard_list (list of carddav_object.CarddavObject) – the vcards to search for matching entries which should be printed

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

Returns

None

Return type

None

khard.khard.choose_address_book_from_list(header_string, address_book_list)

khard.khard.choose_vcard_from_list(header_string, vcard_list, include_none=False)

khard.khard.copy_contact(contact, target_address_book, delete_source_contact)

khard.khard.copy_or_move_subcommand(action, vcard_list, target_address_book_list)

Copy or move a contact to a different address book.

Action

the string “copy” or “move” to indicate what to do

Parameters

• vcard_list (list of carddav_object.CarddavObject) – the contact list from which to select one for the action

• target_address_book_list (list(addressbook.AddressBook)) – the list of target address books

Returns

None

Return type

None

khard.khard.create_new_contact(address_book)

khard.khard.edit(*filenames, merge=False)

Edit the given files with the configured editor or merge editor

khard.khard.email_subcommand(search_terms, vcard_list, parsable, remove_first_line)

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 (str) – used as search term to filter the contacts before printing

• vcard_list (list of carddav_object.CarddavObject) – the vcards to search for matching entries which should be printed

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

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

Returns

None

Return type

None

khard.khard.generate_contact_list(args)

TODO: Docstring for generate_contact_list.

Parameters

args (argparse.Namespace) – the command line arguments

Returns

the contacts for further processing (TODO)

Return type

list(TODO)

khard.khard.get_contact_list_by_user_selection(address_books, search, strict_search)

returns a list of CarddavObject objects :param address_books: list of selected address books :type address_books: list(address_book.AddressBook) :param search: filter contact list :type search: str :param strict_search: if True, search only in full name field :type strict_search: bool :returns: list of CarddavObject objects :rtype: list(CarddavObject)

khard.khard.get_contacts(address_books, query, method='all', reverse=False, group=False, sort='first_name')

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

Parameters

• address_books (list(address_book.AddressBook)) – the address books to search

• query (str) – a search query to select contacts

• method (str) – the search method, one of “all”, “name” or “uid”

• reverse (bool) – reverse the order of the returned contacts

• group (bool) – group results by address book

• sort (str) – the field to use for sorting, one of “first_name”, “last_name”, “formatted_name”

Returns

contacts from the address_books that match the query

Return type

list(CarddavObject)

khard.khard.list_address_books(address_book_list)

khard.khard.list_birthdays(birthday_list)

khard.khard.list_contacts(vcard_list)

khard.khard.list_email_addresses(email_address_list)

khard.khard.list_phone_numbers(phone_number_list)

khard.khard.list_post_addresses(post_address_list)

khard.khard.list_subcommand(vcard_list, parsable)

Print a user friendly contacts table.

Parameters

• vcard_list (list of carddav_object.CarddavObject) – the vcards to print

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

Returns

None

Return type

None

khard.khard.load_address_books(names, config, search_queries)

Load all address books with the given names from the config.

Parameters

• names (list(str)) – the address books to load

• config (config.Config) – the config instance to use when looking up address books

• search_queries (dict) – a mapping of address book names to search queries

Yields

the loaded address books

Ytype

addressbook.AddressBook

khard.khard.main(argv=['-M', 'singlehtml', 'source', 'build'])

khard.khard.merge_existing_contacts(source_contact, target_contact, delete_source_contact)

khard.khard.merge_subcommand(vcard_list, selected_address_books, search_terms, target_uid)

Merge two contacts into one.

Parameters

• vcard_list (list of carddav_object.CarddavObject) – the vcards from which to choose contacts for mergeing

• selected_address_books (list(addressbook.AddressBook)) – the addressbooks to use to find the target contact

• search_terms (str) – the search terms to find the target contact

• target_uid (str) – the uid of the target contact or empty

Returns

None

Return type

None

khard.khard.modify_existing_contact(old_contact)

khard.khard.modify_subcommand(selected_vcard, input_from_stdin_or_file, open_editor, source=False)

Modify a contact in an external editor.

Parameters

• selected_vcard (carddav_object.CarddavObject) – the contact to modify

• input_from_stdin_or_file (str) – new data from stdin (or a file) that should be incorperated into the contact, this should be a yaml formatted string

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

• source (bool) – edit the source file or a yaml version?

Returns

None

Return type

None

khard.khard.new_subcommand(selected_address_books, input_from_stdin_or_file, open_editor)

Create a new contact.

Parameters

• selected_address_books (list of address_book.AddressBook) – a list of addressbooks that were selected on the command line

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

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

Returns

None

Return type

None

khard.khard.phone_subcommand(search_terms, vcard_list, parsable)

Print a phone application friendly contact table.

Parameters

• search_terms (str) – used as search term to filter the contacts before printing

• vcard_list (list of carddav_object.CarddavObject) – the vcards to search for matching entries which should be printed

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

Returns

None

Return type

None

khard.khard.post_address_subcommand(search_terms, vcard_list, parsable)

Print a contact table. with all postal / mailing addresses

Parameters

• search_terms (str) – used as search term to filter the contacts before printing

• vcard_list (list of carddav_object.CarddavObject) – the vcards to search for matching entries which should be printed

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

Returns

None

Return type

None

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

Parameters

args (argparse.Namespace) – the parsed command line

Returns

a dict mapping abook names to their loading queries, if the query is None it means that all cards should be loaded

Return type

dict(str:str or None)

khard.khard.remove_subcommand(selected_vcard, force)

Remove a contact from the addressbook.

Parameters

• selected_vcard (carddav_object.CarddavObject) – the contact to delete

• force (bool) – delete without confirmation

Returns

None

Return type

None

khard.khard.write_temp_file(text='')

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

Parameters

text (str) – the text to write to the temp file

Returns

the file name of the newly created temp file

Return type

str

khard.object_type module

Helper module for validating typed vcard properties

class khard.object_type.ObjectType

Bases: enum.Enum

An enumeration.

list_with_strings = 2

string = 1

string_or_list_with_strings = 3

khard.version module

Indices and tables

• Index

• Module Index

• Search Page

Khard is an address book for the Linux command line. It can read, create, modify and delete carddav address book entries. Khard only works with a local store of VCARD files. It is intended to be used in conjunction with other programs like an email client, text editor, vdir synchronizer or VOIP client.

Installation

Khard is available as a native package for some Linux distributions so you should check your package manager first. If you want or need to install manually you can use the release from PyPi:

pip3 install khard

If you want to help the development or need more advanced installation instructions see Contributing.

Configuration

The configuration file of khard is stored in the XDG conform config directory. If the environment variable $XDG_CONFIG_HOME is set, it is $XDG_CONFIG_HOME/khard/khard.conf and it defaults to ~/.config/khard/khard.conf otherwise.

A minimal configuration is provided in the source tree. It looks like this:

# example configuration file for khard version > 0.14.0
# place it under ~/.config/khard/khard.conf

[addressbooks]
[[family]]
path = ~/.contacts/family/
[[friends]]
path = ~/.contacts/friends/

[general]
debug = no
default_action = list
# These are either strings or comma seperated lists
editor = vim, -i, NONE
merge_editor = vimdiff

[contact table]
# display names by first or last name: first_name / last_name / formatted_name
display = first_name
# group by address book: yes / no
group_by_addressbook = no
# reverse table ordering: yes / no
reverse = no
# append nicknames to name column: yes / no
show_nicknames = no
# show uid table column: yes / no
show_uids = yes
# sort by first or last name: first_name / last_name / formatted_name
sort = last_name
# localize dates: yes / no
localize_dates = yes
# set a comma separated list of preferred phone number types in descending priority
# or nothing for non-filtered alphabetical order
preferred_phone_number_type = pref, cell, home
# set a comma separated list of preferred email address types in descending priority
# or nothing for non-filtered alphabetical order
preferred_email_address_type = pref, work, home

[vcard]
# extend contacts with your own private objects
# these objects are stored with a leading "X-" before the object name in the vcard files
# every object label may only contain letters, digits and the - character
# example:
#   private_objects = Jabber, Skype, Twitter
private_objects = Jabber, Skype, Twitter
# preferred vcard version: 3.0 / 4.0
preferred_version = 3.0
# Look into source vcf files to speed up search queries: yes / no
search_in_source_files = no
# skip unparsable vcard files: yes / no
skip_unparsable = no

Integration with other programs

Khard can be used together with email or SIP clients or a synchronisation program like vdirsyncer.

mutt

Khard may be used as an external address book for the email client mutt. To accomplish that, add the following to your mutt config file (mostly ~/.mutt/muttrc):

set query_command= "khard email --parsable %s"
bind editor <Tab> complete-query
bind editor ^T    complete

Then you can complete email addresses by pressing the Tab-key in mutt’s new mail dialog. If your address books contain hundreds or even thousands of contacts and the query process is very slow, you may try the --search-in-source-files option to speed up the search:

set query_command= "khard email --parsable --search-in-source-files %s"

If you want to complete multi-word search strings like “john smith” then you may try out the following instead:

set query_command = "echo %s | xargs khard email --parsable --"

To add email addresses to khard’s address book, you may also add the following lines to your muttrc file:

macro index,pager A \
  "<pipe-message>khard add-email<return>" \
  "add the sender email address to khard"

Then navigate to an email message in mutt’s index view and press “A” to start the address import dialog.

Alot

Add the following lines to your alot config file:

[accounts]
    [[youraccount]]
        [[[abook]]]
            type = shellcommand
            command = khard email --parsable
            regexp = '^(?P<email>[^@]+@[^\t]+)\t+(?P<name>[^\t]+)'
            ignorecase = True

Twinkle

For those who also use the SIP client twinkle to take phone calls, khard can be used to query incoming numbers. The plugin tries to find the incoming caller id and speaks it together with the phone’s ring tone. The plugin needs the following programs:

sudo aptitude install ffmpeg espeak sox mpc

sox and ffmpeg are used to cut and convert the new ring tone and espeak speaks the caller id. mpc is a client for the music player daemon (mpd). It’s required to stop music during an incoming call. Skip the last, if you don’t use mpd. Don’t forget to set the “stop_music”-parameter in the config.py file to False, too.

After the installation, copy the scripts and sounds folders to your twinkle config folder:

cp -R misc/twinkle/* ~/.twinkle/

Then edit your twinkle config file (mostly ~/.twinkle/twinkle.cfg) like this:

# RING TONES
# We need a default ring tone. Otherwise the phone would not ring at all, if
# something with the custom ring tone creation goes wrong.
ringtone_file=/home/USERNAME/.twinkle/sounds/incoming_call.wav
ringback_file=/home/USERNAME/.twinkle/sounds/outgoing_call.wav

# SCRIPTS
script_incoming_call=/home/USERNAME/.twinkle/scripts/incoming_call.py
script_in_call_answered=
script_in_call_failed=/home/USERNAME/.twinkle/scripts/incoming_call_failed.py
script_outgoing_call=
script_out_call_answered=
script_out_call_failed=
script_local_release=/home/USERNAME/.twinkle/scripts/incoming_call_ended.py
script_remote_release=/home/USERNAME/.twinkle/scripts/incoming_call_ended.py

Zsh

The file misc/zsh/_khard contains a khard cli completion function for the zsh and misc/zsh/_email-khard completes email addresses.

Install by copying to a directory where zsh searches for completion functions (the $fpath array). If you, for example, put all completion functions into the folder ~/.zsh/completions you must add the following to your zsh main config file:

fpath=( $HOME/.zsh/completions $fpath )
autoload -U compinit
compinit

sdiff

Use the wrapper script misc/sdiff/sdiff_khard_wrapper.sh if you want to use sdiff as your contact merging tool. Just make the script executable and set it as your merge editor in khard’s config file:

merge_editor = /path/to/sdiff_khard_wrapper.sh