pythonista 文档_Pythonista中文文档:contacts

袁翔
2023-12-01

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

 类似资料: