contacts — 访问iOS上的联系人数据库

contacts模块允许你读取和修改iOS联系人（地址簿）数据库。

注意: 首次contacts导入模块时，将显示系统提供的权限对话框。如果你拒绝访问，get_all_people()将始终返回一个空列表。如果你以后改变主意，则可以允许从应用“设置”中的“隐私”部分访问你的联系人。

快速入门

作为读取地址簿中信息的简单示例，让我们从一个打印出所有在“备注”字段中带有文本的人的脚本开始：

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)

该脚本使用get_all_people()函数来检索通讯簿中所有Person对象的列表，遍历该列表，并为每个具有（非空）Person.note字段的人打印名称和备注。

作为一个稍微复杂的示例，此脚本打印出生日即将到来的列表（以从现在开始的天数）：

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']))

备注和生日字段非常易于使用，因为每个人只有一个。许多其他字段可以具有多个值，例如，一个人可以拥有多个电子邮件地址。这些字段表示为元组列表，每个元组包含一个标签（例如，“home”，“work” …）和实际值。Person.email属性的示例为[('home', 'me@example.com'), ('work', 'work@example.com')]。

到目前为止，我们仅从通讯录数据库中读取信息，但是你也可以使用contacts模块进行更改。因为前面的示例使用了一个简单的单值属性，所以让我们现在使用更复杂的Person.address属性，该属性表示为多个字典的列表，每个字典都包裹在一个包含标签（例如“home”，“work”）的元组中。让我们将居住在柏林的所有人的国家更改为德国：

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')

请注意，我们在地址字典中使用了常量作为键–你可以在本文档的末尾找到这些键的列表。对通讯簿进行任何更改后，你必须调用save()函数以使它们持久化。

请注意，所有多值属性均作为“快照”返回。除非你重新分配属性，否则直接修改这些列表无效。

函数

contacts.get_group(group_id)
返回具有给定ID（整数，Group.id）的Group。

contacts.get_all_groups()
返回通讯簿中所有Group对象的列表。

contacts.add_group()
将一个Group添加到通讯簿。

contacts.remove_group(group)
从通讯簿中删除一个Group。

contacts.add_person(person)
将一个Person添加到通讯簿。

contacts.remove_person(person)
从通讯簿中删除一个Person。

contacts.find(name)
对给定名称进行前缀搜索，并返回所有匹配记录的Person列表。

contacts.get_all_people()
返回通讯录中所有人员的列表。每个列表条目都是一个Person对象。

contacts.get_person(person_id)
返回具有给定ID（整数，Person.id）的Person。

contacts.save()
将所有待处理的更改保存在联系人数据库中。更改Group或Person对象的任何属性后，必须调用此函数才能使更改持久化。

contacts.revert()
还原联系人数据库中所有未决的更改。

contacts.localized_label(label)
返回在多值属性中使用的标签的本地化版本。

contacts.is_authorized()
如果当前允许访问通讯簿，则返回True；否则返回False（例如，如果尚未显示权限对话框，或者由于家长控制而拒绝访问）。

群组对象

class contacts.Group
一个Group对象表示在地址簿中一组朋友，家人或同事。初始化Group对象并设置其name属性后，可以通过调用add_group()将其添加到地址簿数据库。修改组的名称后，必须调用save()函数才能使更改持久化。

Group.name
群组的名称，例如“朋友”或“家庭”。

Group.id
通讯录中组记录的持久标识符（int，只读），或者-1：尚未保存该组。id可以与get_group()函数一起使用。

人对象

class contacts.Person
Person对象代表通讯录中的人。初始化Person并设置其各种属性后，可以通过调用add_person()将其添加到地址簿数据库中。修改任何属性后，必须调用save()函数以使更改持久化。

许多属性可以具有多个值，例如，一个人可以具有多个电子邮件地址（工作，私人，…）或电话号码（家庭，移动，…）。这些属性中的每一个都表示为2元组的列表，每个元组包含一个标签和实际值。例如，这可能是一个人的email属性的内容：[('home', 'foo@work.com'), ('work', 'foo@work.com')]。尽管可以使用任何字符串作为标签，但建议在本文档末尾使用常量之一。这些标签看起来像’_$!<Work>!$‘，但是将在UI中进行本地化。你可以使用localized_label()函数获得标签常量的本地化表示。

Person.address
街道地址（多字典）。使用常数contacts.STREET，contacts.CITY，contacts.STATE等作为关键字。

Person.birthday
生日（datetime.datetime）。

Person.creation_date
将该人添加到地址簿的时间（只读，datetime.datetime）。

Person.department
部门（字符串）。

Person.email
电子邮件地址（多字符串）

Person.first_name
名字（字符串）

Person.first_name_phonetic
名字拼音（字符串）

Person.full_name
人的全名（只读，字符串）。要修改名称，使用Person.first_name，Person.last_name和Person.middle_name属性。

Person.id
人记录的永久标识符在地址簿中（int，只读），或者-1：人员尚未保存。id可以与get_person()函数一起使用。

Person.image_data
人的图像，例如照片（代表常见图像文件格式（如PNG或JPEG的字节字符串，如果未设置图像则为None）。

Person.instant_message
即时消息帐户（多词典）。

Person.job_title
职务（字符串）。

Person.kind
地址簿记录的类型（0对于一个人，1对于一个组织，它是整数）。

Person.last_name
姓氏（字符串）。

Person.last_name_phonetic
姓氏拼音（字符串）。

Person.middle_name
中间名（字符串）。

Person.middle_name_phonetic
中间名拼音（字符串）。

Person.modification_date
上次修改的时间（只读，datetime.datetime）。

Person.nickname
昵称（字符串）。

Person.note
备注（字符串）。

Person.organization
组织（字符串）。

Person.phone
电话号码（多字符串）

Person.prefix
前缀，例如“Sir”，“Duke”，“General”（字符串）。

Person.related_names
相关名称（多字符串）。

Person.social_profile
社交资料，例如Twitter帐户（多字典）。

Person.suffix
后缀，例如“Jr.”，“Sr.”，“III”（字符串）。

Person.url
URL，例如主页（多字符串）。

Person.vcard
VCard表示个人数据（只读，字符串）。

常量

多值属性的通用标签：

contacts.HOME
contacts.WORK
contacts.OTHER

Person.phone多字符串属性的标签：

contacts.IPHONE
contacts.MAIN_PHONE
contacts.HOME_FAX
contacts.WORK_FAX
contacts.OTHER_FAX
contacts.PAGER

Person.related_names多字符串属性的标签：

contacts.FATHER
contacts.MOTHER
contacts.PARENT
contacts.BROTHER
contacts.SISTER
contacts.CHILD
contacts.FRIEND
contacts.SPOUSE
contacts.PARTNER
contacts.ASSISTANT
contacts.MANAGER

Person.url多字符串属性的标签：

contacts.HOMEPAGE

Person.address字典键：

contacts.STREET
contacts.CITY
contacts.STATE
contacts.ZIP
contacts.COUNTRY
contacts.COUNTRY_CODE