khard.address_book

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

Module Contents

Classes

AddressBook

The base class of all address book implementations.

VdirAddressBook

An AddressBook implementation based on a vdir.

AddressBookCollection

A collection of several address books.

khard.address_book.logger
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) str

Return 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) str

Return str(self).

__eq__(self, other: object) bool

Return self==value.

__ne__(self, other: object) bool

Return self!=value.

static _compare_uids(uid1: str, uid2: str) int

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(self, query: Query) Generator['carddav_object.CarddavObject', None, None]

Search this address book for contacts matching the query.

The backend for this address book migth be load()ed if needed.

Parameters

query – the query to search for

Yields

all found contacts

get_short_uid_dict(self, query: Query = AnyQuery()) Dict[str, 'carddav_object.CarddavObject']

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) 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 = AnyQuery()) 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 = AnyQuery(), search_in_source_files: bool = False) None

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 – query to limit the vcards that should be parsed

  • 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 address books. On load, all contacts from all subaddressbooks are copied into a dict in this address book. This allows this class to use all other methods from the parent AddressBook class.

load(self, query: Query = AnyQuery()) None

Load the wrapped address books with the given parameters

All parameters will be handed to VdirAddressBook.load.

Parameters

query – a query to limit the vcards that should be parsed

Throws

AddressBookParseError

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

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) Iterator[VdirAddressBook]
Returns

an iterator over the underlying address books

__len__(self) int