:py: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
---------------

Classes
~~~~~~~

.. autoapisummary::

   khard.address_book.AddressBook
   khard.address_book.VdirAddressBook
   khard.address_book.AddressBookCollection




Attributes
~~~~~~~~~~

.. autoapisummary::

   khard.address_book.logger


.. py:data:: logger

   

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


   Bases: :py:obj:`Exception`

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

   .. py:method:: __str__() -> str

      Return str(self).



.. py:exception:: AddressBookNameError


   Bases: :py:obj:`Exception`

   Indicate an error with an address book name.


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


   The base class of all address book implementations.

   .. py:method:: __str__() -> str

      Return str(self).


   .. py:method:: __eq__(other: object) -> bool

      Return self==value.


   .. py:method:: __ne__(other: object) -> bool

      Return self!=value.


   .. py:method:: _compare_uids(uid1: str, uid2: str) -> int
      :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 shortest unequal initial substrings


   .. py:method:: 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.

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


   .. py:method:: 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().

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


   .. py:method:: get_short_uid(uid: str) -> str

      Get the shortened UID for the given UID.

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


   .. py:method:: load(query: khard.query.Query = AnyQuery()) -> 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: :py:obj:`AddressBook`

   An AddressBook implementation based on a vdir.

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

   .. py:method:: 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.

      :param query: query to limit the vcards that should be parsed
      :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: :py:obj:`AddressBook`, :py:obj:`collections.abc.Mapping`, :py:obj:`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.

   .. py:method:: load(query: khard.query.Query = AnyQuery()) -> None

      Load the wrapped address books with the given parameters

      All parameters will be handed to VdirAddressBook.load.

      :param query: a query to limit the vcards that should be parsed
      :throws: AddressBookParseError


   .. py:method:: __getitem__(key: Union[int, str]) -> VdirAddressBook
                  __getitem__(key: slice) -> List[VdirAddressBook]

      Get one or more 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(s)
      :throws: KeyError


   .. py:method:: __iter__() -> Iterator[VdirAddressBook]

      :return: an iterator over the underlying address books


   .. py:method:: __len__() -> int