:mod:`khard.address_book`
=========================

.. py:module:: khard.address_book

.. autoapi-nested-parse::

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



Module Contents
---------------

.. data:: logger
   

   

.. data:: Query
   

   

.. py:exception:: AddressBookParseError(filename: str, abook: str, reason: Exception)

   Bases: :class:`Exception`

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

   .. method:: __str__(self)




.. py:exception:: AddressBookNameError

   Bases: :class:`Exception`

   Indicate an error with an address book name.


.. py:class:: AddressBook(name: str)

   The base class of all address book implementations.

   .. method:: __str__(self)



   .. method:: __eq__(self, other: object)



   .. method:: __ne__(self, other: object)



   .. method:: _compare_uids(uid1: str, uid2: str)
      :staticmethod:


      Calculate the minimum length of initial substrings of uid1 and uid2
      for them to be different.

      :param uid1: first uid to compare
      :param uid2: second uid to compare
      :returns: the length of the shortes unequal initial substrings


   .. method:: _search_all(self, query)


      Search in all fields for contacts matching query.

      :param query: the query to search for
      :yields: all found contacts


   .. method:: _search_names(self, query)


      Search in the name filed for contacts matching query.

      :param query: the query to search for
      :yields: all found contacts


   .. method:: _search_uid(self, query)


      Search for contacts with a matching uid.

      :param query: the query to search for
      :yields: all found contacts


   .. method:: search(self, query: Optional[List[str]], method: str = 'all')


      Search this address book for contacts matching the query.

      The method can be one of "all", "name" and "uid".  The backend for this
      address book migth be load()ed if needed.

      :param query: the query to search for
      :param method: the type of fileds to use when seaching
      :returns: all found contacts


   .. method:: get_short_uid_dict(self, query: Optional[str] = None)


      Create a dictionary of shortend 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().

      :param query: see self.load()
      :returns: the contacts mapped by the shortes unique prefix of their UID


   .. method:: get_short_uid(self, uid: str)


      Get the shortend UID for the given UID.

      :param uid: the full UID to shorten
      :returns: the shortend uid or the empty string


   .. method:: load(self, query: Query = None)
      :abstractmethod:


      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.

      :param query: the query to limit loading to matching entries
      :returns: the number of loaded contacts and the number of errors



.. py:class:: VdirAddressBook(name: str, path: str, private_objects: Optional[List[str]] = None, localize_dates: bool = True, skip: bool = False)

   Bases: :class:`khard.address_book.AddressBook`

   An AddressBook implementation based on a vdir.

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

   .. method:: load(self, query: Query = None, search_in_source_files: bool = False)


      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.

      :param query: a regular expression to limit the results
      :param search_in_source_files: apply search regexp directly on the .vcf
          files to speed up parsing (less accurate)
      :throws: AddressBookParseError



.. py:class:: AddressBookCollection(name: str, abooks: List[VdirAddressBook])

   Bases: :class:`khard.address_book.AddressBook`

   A collection of several address books.

   This represents a temporary merege of the contact collections provided by
   the underlying adress books.  On load all contacts from all subadressbooks
   are copied into a dict in this address book.  This allow this class to use
   all other methods from the parent AddressBook class.

   .. method:: load(self, query: Query = None)


      Load the wrapped address books with the given parameters

      All parameters will be handed to VdirAddressBook.load.

      :param query: a regular expression to limit the results
      :throws: AddressBookParseError


   .. method:: __getitem__(self, key: Union[int, str])


      Get one of the backing address books by name or index

      :param key: the name of the address book to get or its index
      :returns: the matching address book
      :throws: KeyError


   .. method:: __iter__(self)


      :return: an iterator over the underlying address books


   .. method:: __len__(self)