khard.address_book
==================

.. py:module:: khard.address_book

.. autoapi-nested-parse::

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



Attributes
----------

.. autoapisummary::

   khard.address_book.logger


Classes
-------

.. autoapisummary::

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


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

.. py:data:: logger

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

   The base class of all address book implementations.


   .. py:attribute:: _loaded
      :value: False



   .. py:attribute:: contacts
      :type:  dict[str, khard.contacts.Contact]


   .. py:attribute:: _short_uids
      :type:  Optional[dict[str, khard.contacts.Contact]]
      :value: None



   .. py:attribute:: name


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


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


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


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

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

      :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:attribute:: path


   .. py:attribute:: _private_objects
      :value: []



   .. py:attribute:: _localize_dates
      :value: True



   .. py:attribute:: _skip
      :value: False



   .. 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:attribute:: _abooks


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


