# khard.address_book

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

## Attributes

`logger` |

## Classes

`AddressBook` | The base class of all address book implementations.
`VdirAddressBook` | An AddressBook implementation based on a vdir.
`AddressBookCollection` | A collection of several address books.

## 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, khard.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