`contacts` — Access the iOS Contacts Database#

The contacts module allows you to read and modify the iOS contacts (address book) database.

Note

The first time the contacts module is imported, a system-provided permission dialog will be shown. If you deny access, get_all_people() will always return an empty list. If you change your mind later, you can allow access to your contacts from the Privacy section in the Settings app.

Quick Start#

As a simple example for reading information in the address book, let’s start with a script that prints out all people that have text in the ‘Notes’ field:

import contacts
print('Address Book Notes')
print('=' * 40)
people = contacts.get_all_people()
for p in people:
  note = p.note
  if note:
    print(p.full_name)
    print('-' * 40)
    print(note)
    print('=' * 40)

The script uses the get_all_people() function to retrieve a list of all Person objects in the address book, iterates over the list, and prints the name and note for each person that has a (non-empty) Person.note field.

As a slightly more complex example, this script prints out a list of upcoming birthdays (as number of days from now):

import contacts
from datetime import datetime
import operator

days_list = []
people = contacts.get_all_people()
now = datetime.now()
for p in people:
  b = p.birthday
  if b:
    next_birthday = datetime(now.year, b.month, b.day)
    if next_birthday < now:
      next_birthday = datetime(now.year + 1, b.month, b.day)
    days = (next_birthday - now).days
    days_list.append({'name': p.full_name, 'days': days})

if not days_list:
  print('You don\'t have any birthdays in your address book.')
else:
  days_list.sort(key=operator.itemgetter('days'))
  print('Upcoming Birthdays')
  print('=' * 40)
  for item in days_list:
    print('* %s in %i days' % (item['name'], item['days']))

The note and birthday fields are very easy to use because there is only one for each person. Many other fields can have multiple values, e.g. a person can have more than one email address. These fields are represented as lists of tuples, with each tuple containing a label (e.g. ‘home’, ‘work’…), and the actual value. An example for the Person.email attribute would be [('home', 'me@example.com'), ('work', 'work@example.com')].

So far, we’ve only read information from the address book database, but you can also use the contacts module to make changes. Because the previous example used a simple single-value attribute, let’s use the more complex Person.address attribute now, which is represented as a list of multiple dictionaries, each wrapped in a tuple that contains a label (e.g. ‘home’, ‘work’…). Let’s change the country of all people that live in Berlin to be Germany:

import contacts
people = contacts.get_all_people()
for p in people:
  changed = False
  addresses = p.address
  for address_tuple in addresses:
    address = address_tuple[1]
    city = address.get(contacts.CITY, None)
    country = address.get(contacts.COUNTRY, None)
    if city == 'Berlin' and country != 'Germany':
      address[contacts.COUNTRY] = 'Germany'
      address[contacts.COUNTRY_CODE] = 'de'
      changed = True
  if changed:
    p.address = addresses
    print('Updated country of', p.full_name)
contacts.save()
print('Done')

Note that we’ve used constants for the keys in the address dictionary – you can find a list of these keys at the end of this document. After making any changes to the address book, you have to call the save() function to make them persistent.

Note that all multi-value attributes are returned as ‘snapshots’. Modifying these lists directly has no effect unless you re-assign the attribute.

Functions#

contacts.get_group(group_id)#: Return the Group with the given id (an integer, c.f. Group.id).

contacts.get_all_groups()#: Return a list of all Group objects in the address book.

contacts.add_group()#: Add a Group to the address book.

contacts.remove_group(group)#: Remove a Group from the address book.

contacts.add_person(person)#: Add a Person to the address book.

contacts.remove_person(person)#: Remove a Person from the address book.

contacts.find(name)#: Do a prefix search for the given name and return a list of all matching Person records.

contacts.get_all_people()#: Return a list of all people in the address book. Each list entry is a Person object.

contacts.get_person(person_id)#: Return the Person with the given id (an integer, c.f. Person.id).

contacts.save()#: Save all pending changes in the contacts database. After changing any attributes of a Group or Person object, this function has to be called in order to make the changes persistent.

contacts.revert()#: Revert all pending changes in the contacts database.

contacts.localized_label(label)#: Return a localized version of a label that is used in a multi-value property.

contacts.is_authorized()#: Returns True if access to the address book is currently allowed, False otherwise (e.g. if the permission dialog hasn’t been shown yet or if access is denied due to parental controls).

Group Objects#

class contacts.Group#: A Group object represents a group in the address book, e.g. friends, family, or co-workers. After initializing a Group object and setting its name attribute, it can be added to the address book database by calling add_group(). When a group’s name is modified, the save() function has to be called in order to make the change persistent.

Group.name#: The group’s name, e.g. ‘Friends’ or ‘Family’.

Group.id#: The persistent identifier of the group record in the address book (int, readonly), or -1 if the group has not been saved yet. The id can be used with the get_group() function.

Person Objects#

class contacts.Person#

Person objects represent people in the address book. After initializing a Person and setting its various attributes, it can be added to the address book database by calling add_person(). After any attributes are modified, the save() function has to be called in order to make the changes persistent.

A lot of attributes can have multiple values, e.g. a person can have multiple email addresses (work, private, …) or phone numbers (home, mobile, …). Each of these attributes is represented as a list of 2-tuples, with each tuple containing a label and the actual value. For example, this could be the contents of a person’s email attribute: [('home', 'foo@work.com'), ('work', 'foo@work.com')]. Though it’s possible to use any string as a label, it is recommended to use one of the constants at the end of this document. These labels look like '_$!<Work>!$', but will be localized in the UI. You can get a localized representation of a label constant by using the localized_label() function.

Person.address#: Street address(es) (multi-dictionary). Use the constants contacts.STREET, contacts.CITY, contacts.STATE etc. as keys.

Person.birthday#: Birthday (datetime.datetime).

Person.creation_date#: When the person was added to the address book (readonly, datetime.datetime).

Person.department#: Department (string).

Person.email#: Email address(es) (multi-string)

Person.first_name#: First name (string)

Person.first_name_phonetic#: First name phonetic (string)

Person.full_name#: The person’s full name (readonly, string). To modify the name, use the Person.first_name, Person.last_name and Person.middle_name attributes.

Person.id#: The persistent identifier of the person record in the address book (int, readonly), or -1 if the person has not been saved yet. The id can be used with the get_person() function.

Person.image_data#: The person’s image, e.g. a photo (byte string representing a common image file format, like PNG or JPEG, or None if no image was set).

Person.instant_message#: Instant message accounts (multi-dictionary).

Person.job_title#: Job title (string).

Person.kind#: The kind of address book record (int, 0 for a person, 1 for an organization).

Person.last_name#: Last name (string).

Person.last_name_phonetic#: Last name phonetic (string).

Person.middle_name#: Middle name (string).

Person.middle_name_phonetic#: Middle name phonetic (string).

Person.modification_date#: When the person was last modified (readonly, datetime.datetime).

Person.nickname#: Nickname (string).

Person.note#: Note (string).

Person.organization#: Organization (string).

Person.phone#: Phone number(s) (multi-string).

Person.prefix#: Prefix, e.g. “Sir,” “Duke,” “General” (string).

Person.related_names#: Related names (multi-string).

Person.social_profile#: Social profile(s), e.g. Twitter accounts (multi-dictionary).

Person.suffix#: Suffix, e.g. “Jr.,” “Sr.,” “III” (string).

Person.url#: URL(s), e.g. homepage (multi-string).

Person.vcard#: VCard reprentation of the person’s data (readonly, string).

Constants#

Generic labels for multi-value attributes:

contacts.HOME#

contacts.WORK#

contacts.OTHER#

Labels for the Person.phone multi-string attribute:

contacts.IPHONE#

contacts.MAIN_PHONE#

contacts.HOME_FAX#

contacts.WORK_FAX#

contacts.OTHER_FAX#

contacts.PAGER#

Labels for the Person.related_names multi-string attribute:

contacts.FATHER#

contacts.MOTHER#

contacts.PARENT#

contacts.BROTHER#

contacts.SISTER#

contacts.CHILD#

contacts.FRIEND#

contacts.SPOUSE#

contacts.PARTNER#

contacts.ASSISTANT#

contacts.MANAGER#

Labels for the Person.url multi-string attribute:

contacts.HOMEPAGE#

Keys for Person.address dictionaries:

contacts.STREET#

contacts.CITY#

contacts.STATE#

contacts.ZIP#

contacts.COUNTRY#

contacts.COUNTRY_CODE#