pythonista 文档_Pythonista中文文档：contacts
contacts — 访问iOS上的联系人数据库
contacts模块允许你读取和修改iOS联系人(地址簿)数据库。
注意: 首次contacts导入模块时，将显示系统提供的权限对话框。如果你拒绝访问，get_all_people()将始终返回一个空列表。如果你以后改变主意，则可以允许从应用“设置”中的“隐私”部分访问你的联系人。
快速入门
作为读取地址簿中信息的简单示例，让我们从一个打印出所有在“备注”字段中带有文本的人的脚本开始：
1
2
3
4
5
6
7
8
9
10
11import 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字段的人打印名称和备注。
作为一个稍微复杂的示例，此脚本打印出生日即将到来的列表(以从现在开始的天数)：
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24import 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”)的元组中。让我们将居住在柏林的所有人的国家更改为德国：
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18import 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')]。尽管可以使用任何字符串作为标签，但建议在本文档末尾使用常量之一。这些标签看起来像’_$!!$‘，但是将在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