khard.address_book

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

Attributes

logger

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

class khard.address_book.AddressBook(name: str)

The base class of all address book implementations.

_loaded = False

contacts: dict[str, khard.contacts.Contact]

_short_uids: dict[str, khard.contacts.Contact] | None = None

name

__str__() → str

__eq__(other: object) → bool

__ne__(other: object) → bool

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.contacts.Contact, 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.contacts.Contact]

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

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

path

_private_objects = []

_localize_dates = True

_skip = False

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.

_abooks

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