khard.address_book
******************

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


Attributes
==========

+------------+--------------------------------------------------------------------------------------------+
| "logger"   |                                                                                            |
+------------+--------------------------------------------------------------------------------------------+


Classes
=======

+------------+--------------------------------------------------------------------------------------------+
| "AddressBo | The base class of all address book implementations.                                        |
| ok"        |                                                                                            |
+------------+--------------------------------------------------------------------------------------------+
| "VdirAddre | An AddressBook implementation based on a vdir.                                             |
| ssBook"    |                                                                                            |
+------------+--------------------------------------------------------------------------------------------+
| "AddressBo | A collection of several address books.                                                     |
| okCollecti |                                                                                            |
| on"        |                                                                                            |
+------------+--------------------------------------------------------------------------------------------+


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, 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
