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.

Attributes

logger

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