contacts — iOSの住所録データベースへのアクセス

　contacts モジュールは iOS の contacts(住所録)データベースを読み込んだり、修正したりするために使用します。

（注　最初にcontacts モジュールをインポートした際に、iOS の許可ダイアログが表示されます。住所録へのアクセスを許可しなかった場合、get_all_people() の戻り値は常に空のリストになります。このモジュールを使用する場合には、「設定」＞「プライバシー」で住所録へのアクセスを許可して下さい。）

クイックスタート

住所録の情報を読み込む簡単な例として、「電話番号」フィールドにデータがある全ての人の名前と電話番号を画面表示するスクリプトを以下に示します。

（注　本来のマニュアルでは、住所録の「メモ」欄にデータがある全ての人について表示するスクリプトとなっていましたが、iOS13から住所録のメモ欄へのアクセスが禁止されましたので、「電話番号」欄にデータがある全ての人を対象にするようスクリプトを修正しました。）

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

このスクリプトでは get_all_people() 関数を、住所録の全ての人のオブジェクトのリストを呼び出すために使用しています。このリストをイタレートして、 Person.phone フィールドにデータの入っている人全員の名前と電話番号を表示します。

　もう少し複雑な例として、こちらは「もうすぐ誕生日」（誕生日までの残り日数）のリストを表示するスクリプトです。

CopyOpen in Editor
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']))

　「メモ」欄と「誕生日」欄は1人の人に１つしかないので扱いが非常に簡単です。他の多くの欄（フィールド）は、例えば e-mail アドレスを複数持つ人もいるなど、複数の値があり得ます。これらの欄は複数のタプルのリストから成り立っています。これらのタプルは「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() 関数を呼び出す必要があります。

　複数の値を持つ属性については「スナップショット」として値を返します。これらのリストを直接操作しても、属性を再びアサインしないと操作内容は保存されません。

Functions

contacts.get_group(group_id)

　引数 group_id(整数、Group.id を参照）に該当する Group を返します。

contacts.get_all_groups()

　住所録の中の全ての Group オブジェクトのリストを返します。

contacts.add_group()

　住所録に Group を追加します。

contacts.remove_group(group)

　住所録から Group を一つ削除します。

contacts.add_person(person)

　住所録に1人の Person を追加します。

contacts.remove_person(person)

　住所録から一人の Person を削除します。

contacts.find(name)

　引数 name で前方一致検索し、合致した Person レコードのリストを返します。

contacts.get_all_people()

　住所録中の全員のリストを返します。それぞれのリストの項目は Person オブジェクトになっています。

contacts.get_person(person_id)

　引数 person_id（整数値、Person.id を参照）に該当するPerson を返します。

contacts.save()

　編集中の変更内容全てを contacts データベースに保存します。Group や Person オブジェクトに変更を加えたら、変更を保存するため、この関数を呼び出さなければなりません。

contacts.revert()

　全ての変更を contacts データベースの内容に戻します。

contacts.localized_label(label)

　複数の値を持つ項目の中で使用されるラベルのローカライズ版を返します。 Return a localized version of a label that is used in a multi-value property.

contacts.is_authorized()

　住所録へのアクセスが許可されている場合には True を、許可されていない場合には False を返します。（例えば、許可ダイアログがまだ表示されていない場合や、ペアレンタルコントロールでアクセスが禁止されている場合などは False となります）

Group オブジェクト

class contacts.Group

　Group オブジェクトは、「友人」、「家族」、「同僚」などを要素として、住所録の中で一つだけ設定されます。Group オブジェクトを初期化し、その名称の属性を設定すると、add_group() を呼ぶことで、住所録データベースに追加することできます。要素の名前を修正したい時には、save() 関数を呼び出して、修正内容を保存する必要があります。

Group.name

　「友達」とか「家族」のようなグループの名称です。

Group.id

　住所録の group レコードの固定ID（整数型、読込のみ）です。group が保存される前の場合は−1を返します。IDは get_group() 関数で使用可能です。

Person オブジェクト

class contacts.Person

Person オブジェクトは住所録に保存された人々を示します。Person オブジェクトを初期化し、属性を設定したら、add_person() 関数を呼び出すことで住所録データベースに追加することができます。属性を修正した場合は save() 関数を呼ぶことで修正内容を保管できます。

　多くの属性について、複数の値を持つことができます。例えば、1人の人が「仕事用」「プライベート用」など複数のe-mailアドレスを持ったり、「家電」「携帯」など複数の電話番号を持つ、などです。これらの属性は、ラベルと実際の値のタプルからなるタプルを要素としたタプルのリストという構成になっています。例えば、1人の人の e-mail については、以下のような構成になっています：

[('home', 'foo@work.com'), ('work', 'foo@work.com')]

　ラベルとしてどんな文字列でも使うことができますが、この説明書の最後に記した定数を使うことをお勧めします。これらのラベルは '_$!!$'のような形式ですが、iOS のユーザーインターフェイス特有のものです。また、localized_label() 関数を使えば地域固有のラベル用定数を調べることができます。

Person.address

　一つあるいは複数の住所（複数のディクショナリー型）です。キー値として contacts.STREET, contacts.CITY, contacts.STAT などの定数を使用することができます。

Person.birthday

　誕生日（daytime.daytime型）です。

Person.creation_date

　人の情報を住所録に追加した時期(読込み限定、datetime.datetime型)です。

Person.department

　所属（文字列型）です。

Person.email

　E-mail アドレス（複数の文字列型）です。

Person.first_name

　ファーストネーム（文字列型）です。

Person.first_name_phonetic

　ファーストネームの読み仮名（文字列型）です。

Person.full_name

　人のフルネーム（読込み限定、文字列型）です。名前を修正するには、Person.first_name, Person.last_name and Person.middle_nameの各属性を使用します。

Person.id

　住所録の個人データのレコードの固定ID（整数型、読込み限定）です。個人データを保存する前には−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

　メモ（文字列型）です。

（注　iOS13以降ではアップル社の方針によりメモへのアクセスは許可されなくなっています。）

Person.organization

　所属組織（文字列型）

Person.phone

　電話番号（複数の文字列型）

Person.prefix

　「サー」「公爵閣下」「大佐」などのような名前の前につける尊称（文字列型）です。

Person.related_names

　関係性（複数の文字列型）です。

Person.social_profile

　SNSでのプロファイル（例えば Twitter のアカウントなど。複数のディクショナリー型）です。

Person.suffix

　「Jr.」「Sr.」「3世」など、名前の後につける接尾語（文字列型）です。

contacts — iOSの住所録データベースへのアクセス