khard.address_book

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

Module Contents

khard.address_book.logger
khard.address_book.Query
exception khard.address_book.AddressBookParseError(filename: str, abook: str, reason: Exception)

Bases: Exception

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

__str__(self)
exception khard.address_book.AddressBookNameError

Bases: Exception

Indicate an error with an address book name.

class khard.address_book.AddressBook(name: str)

The base class of all address book implementations.

__str__(self)
__eq__(self, other: object)
__ne__(self, other: object)
static _compare_uids(uid1: str, uid2: str)

Calculate the minimum length of initial substrings of uid1 and uid2 for them to be different.

Parameters

  • uid1 – first uid to compare

  • uid2 – second uid to compare

Returns

the length of the shortes unequal initial substrings

_search_all(self, query)

Search in all fields for contacts matching query.

Parameters

query – the query to search for

Yields

all found contacts

_search_names(self, query)

Search in the name filed for contacts matching query.

Parameters

query – the query to search for

Yields

all found contacts

_search_uid(self, query)

Search for contacts with a matching uid.

Parameters

query – the query to search for

Yields

all found contacts

search(self, query: Optional[List[str]], method: str = '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 – the query to search for

  • method – the type of fileds to use when seaching

Returns

all found contacts

get_short_uid_dict(self, query: Optional[str] = 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 – see self.load()

Returns

the contacts mapped by the shortes unique prefix of their UID

get_short_uid(self, uid: str)

Get the shortend UID for the given UID.

Parameters

uid – the full UID to shorten

Returns

the shortend uid or the empty string

abstract load(self, query: 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 – the query to limit loading to matching entries

Returns

the number of loaded contacts and the number of errors

class khard.address_book.VdirAddressBook(name: str, path: str, private_objects: Optional[List[str]] = None, localize_dates: bool = True, skip: bool = False)

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(self, query: Query = None, search_in_source_files: bool = 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 – a regular expression to limit the results

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

Throws

AddressBookParseError

class khard.address_book.AddressBookCollection(name: str, abooks: List[VdirAddressBook])

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.

load(self, query: Query = None)

Load the wrapped address books with the given parameters

All parameters will be handed to VdirAddressBook.load.

Parameters

query – a regular expression to limit the results

Throws

AddressBookParseError

__getitem__(self, key: Union[int, str])

Get one of the backing address books by name or index

Parameters

key – the name of the address book to get or its index

Returns

the matching address book

Throws

KeyError

__iter__(self)
Returns

an iterator over the underlying address books

__len__(self)