khard.address_book
¶
A simple class to load and manage the vcard files from disk.
Module Contents¶
Classes¶
The base class of all address book implementations. |
|
An AddressBook implementation based on a vdir. |
|
A collection of several address books. |
Attributes¶
- 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 ¶