khard.address_book

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

Attributes

logger

Exceptions

AddressBookParseError

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

AddressBookNameError

Indicate an error with an address book name.

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.

Module Contents

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__() 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__() str

Return str(self).

__eq__(other: object) bool

Return self==value.

__ne__(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 shortest unequal initial substrings

search(query: khard.query.Query) Generator[khard.carddav_object.CarddavObject, None, None]

Search this address book for contacts matching the query.

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

Parameters:

query – the query to search for

Yields:

all found contacts

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

Create a dictionary of shortened 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 shortest unique prefix of their UID

get_short_uid(uid: str) str

Get the shortened UID for the given UID.

Parameters:

uid – the full UID to shorten

Returns:

the shortened uid or the empty string

abstract load(query: khard.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: List[str] | None = None, localize_dates: bool = True, skip: bool = False)

Bases: AddressBook

An AddressBook implementation based on a vdir.

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

load(query: khard.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: AddressBook, collections.abc.Mapping, collections.abc.Sequence

A collection of several address books.

This represents a temporary merge 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(query: khard.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__(key: int | str) VdirAddressBook
__getitem__(key: slice) List[VdirAddressBook]

Get one or more 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(s)

Throws:

KeyError

__iter__() Iterator[VdirAddressBook]
Returns:

an iterator over the underlying address books

__len__() int