reminders — iOSのリマインダーデータベースへのアクセス

　reminders モジュールは、iOSのリマインダーデータベースの読込/書込のアクセスを提供します。リマインダーは Reminder クラスで扱うことができ、またリマインダーのリストは Calendar クラスで取扱います。

　（注　最初にリマインダーにアクセスする関数を使用する際には、システムの確認ダイヤログが表示されます。アクセスを拒否した場合、多くの関数は空のデータを返します。後でアクセスを許可したくなったら、設定アプリのプライバシーからリマインダーへのアクセス許可ができます。

クイックスタート

既存リマインダーの検索

　データベースにあるリマインダーを検索する場合には、シンプルに get_reminders() を呼び出します。引数 completed の設定により、リマインダーの未了/完了の状況（チェックがオフになっているか）でリストにフィルターをかけることができます：

import reminders
todo = reminders.get_reminders(completed=False)
print('やることリスト')
print('=========')
for r in todo:
    print('[ ] ' + r.title)
done = reminders.get_reminders(completed=True)
print('完了済の予定')
print('====')
for r in done:
    print('[x] ' + r.title)

新しいリマインダーを追加する

　新しいリマインダーを追加するためには、シンプルにタイトルと期日などを設定し、リマインダーオブジェクトを生成します。そして、Reminder.save() メソッドを呼び出して保存します：

import reminders
r = reminders.Reminder()
r.title = 'Pythonista からの追加項目です。'
r.save()
print('リマインダーに追加しましたよ。')

　Reminders アプリの中のリマインダーのリストは複数設定できます。これらのリストは reminders モジュールの中の Calendar オブジェクトで表現されます。特別な指定をしない場合、リマインダーはデフォルトのリストまたはカレンダーに追加されます。デフォルトとは異なるリストにリマインダーを追加するためには、シンプルにリマインダーを生成する際に、対応する Calendar オブジェクトを渡します。

　次の例はカレンダー（リスト）から「Pythonista」という名称のものを探し、見つかった場合には、「Pythonista リストの新しいリマインダーです。」という新しいリマインダ＝を追加します：

import reminders
all_calendars = reminders.get_all_calendars()
for calendar in all_calendars:
    if calendar.title == 'Pythonista':
        r = reminders.Reminder(calendar)
        r.title = 'Pythonista リストの新しいリマインダーです。'
        r.save()
        break
else:
    print('"Pythonista"というカレンダー（リスト）は見つかりませんでした。')

カレンダー（リスト）の追加

　新しいカレンダー（リスト）をプログラムで作成することもできます。以下の例では Pythonista という名称のカレンダーが無い場合に、新しく Pythonista というカレンダーを作成します：

import reminders
all_calendars = reminders.get_all_calendars()
for calendar in all_calendars:
    if calendar.title == 'Pythonista':
        print('"Pythonista" というカレンダーは既に存在します。')
        break
else:
    new_calendar = reminders.Calendar()
    new_calendar.title = 'Pythonista'
    new_calendar.save()
    print('新しいカレンダーを追加しました。')

アラームの追加

　リマインダーは、実際に何かをリマインドした際、すなわち、通知を表示すると便利さを実感できます。そのためには、一つないし複数の :class:'Alarm' をリマインダーに追加する必要があります。:class:'Alarm' は指定の時間になった時、または地理的な場所への到着/出発により起動します。

　まずは日付と時刻によるアラームについて見てみましょう。次の例は、現在から25分後に通知を表示する、新しいリマインダーを追加します：

import reminders
import datetime
r = reminders.Reminder()
r.title = '休憩にしませんか？'
minutes = 25
due = datetime.datetime.now() + datetime.timedelta(minutes=minutes)
# 注：ここでは締切日時にアラームを鳴らすよう設定していますが、
# 別の日時にすることもできます。
r.due_date = due
a = reminders.Alarm()
a.date = due
r.alarms = [a]
r.save()
print(' %i 分後にリマインダーが通知をします。' % minutes)

　地理的な場所に基づいたアラームを追加するには、タイトルと緯度、経度を設定する必要があります。指定地点を中心としたアラームを出すべきエリアの半径と、そのエリアに入った時に鳴らすか、エリアから出た時に鳴らすかも指定できます：

import reminders

r = reminders.Reminder()
r.title = '自撮りしよ！'

a = reminders.Alarm()
lat, lng = 37.332224, -122.030780
radius = 500 # metres
title = '1 Infinite Loop'
a.location = (title, lat, lng, radius)
a.proximity = 'enter'
r.alarms = [a]
r.save()

Functions

reminders.get_reminders(calendar=None, completed=None)

　引数 calendar で指定した（または全ての）カレンダーから全てのリマインダーを取得します。

　引数 calendar が省略された、あるいは None の場合、全てのカレンダーの全てのリマインダーが返されます。

　引数 completed の値によって、リマインダーをフィルターにかけます：

None (the default): 全てのリマインダーを返します。
True: 完了済みの（チェックが外された）リマインダーのみを返します。
False: まだ完了していないリマインダーのみを返します。

reminders.get_all_calendars()

　使用できる全てのカレンダー（Clendar オブジェクト）のリストを返します。カレンダーはリマインダーのリストを示します。 Return a list of all available calendars (Calendar objects). Calendars represent lists of reminders.

reminders.get_default_calendar()

　デフォルトで新しいリマインダーとして使用されるカレンダーを返します。

reminders.get_calendar(calendar_id)

　引数 calendar_id で指定したカレンダーを返します。該当するカレンダーが見つからなかった場合には、None を返します。

reminders.delete_reminder(reminder)

　データベースからリマインダーを削除します。

　削除できた場合には、True を、できなかった場合には False を返します。

reminders.delete_calendar(calendar)

　データベースからカレンダーを削除します。

　削除できた場合には、True を、できなかった場合には False を返します。

Calendar オブジェクト

class reminders.Calendar

　カレンダーオブジェクトはリマインダーのリストを示します。全てのリマインダーは1つのカレンダーに属し、get_reminders() 関数を使用して特定のカレンダーのリマインダーを検索することができます。新しいリマインダーのためにデフォルトのカレンダーを取得するには、get_default_calendar() を使用します。全てのカレンダーはいずれも get_calendar() 関数を使用して検索できるようなIDを持っており、カレンダーの名称（タイトル）が変更されても、このIDは変更されません。

Calendar の属性

Calendar.title

　リマインダーのリストのタイトルです。（文字列、ユニコード）

Calendar.identifier

　カレンダーのIDです。（読込専用、文字列）

　この IDは、特定のカレンダーを検索することに後で使用できます。なお、カレンダーの名称（タイトル）が変更されてもIDは変更されません。

Calendar メソッド

Calendar.save()

　変更内容をデータベースに保存します。（カレンダーのメタデータのみが保存され、カレンダーに含まれているリマインダーは個別に Reminder.save() メソッドにより保存が必要です。）

Reminder オブジェクト

class reminders.Reminder([calendar])

　Reminder オブジェクトはリストの中の単体のリマインダーを意味します。リマインダーには複数のアラームオブジェクトを付属させることができます。アラームオブジェクトには、システムがリマインダーを通知する時刻や場所の属性を持っています。

　リマインダーは、常にリマインダーのリストを意味するカレンダーの構成要素です。リマインダーを初期設定する際に特定のカレンダーを指定しない場合には、デフォルトのカレンダーが使用されます。

Reminder の属性

Reminder.alarms

　リマインダーに関連づけられたアラームオブジェクトのリストです。

　（注：値は複製されます。アラームの属性を再設定しない限り、このリストの変更をしてもアラームは変更されません。）

Reminder.completed

　リマインダーが既に完了済（チェックが外されているか）を示します。（論理型）

Reminder.completion_date

　リマインダーが完了した（チェックが外された）日付を示します。完了していない場合には None となります。

Reminder.due_date

　リマインダーの締切日を示します。

　（注：締切日はアラームを設定する日とは同じではありません。リマインダーアプリに締切日が表示されても、アラームの追加をしない限り、通知を受けることはできません。アラームの追加は、リマインダーのアラーム属性を設定することによって行います。

Reminder.notes

　リマインダーに追加する注釈です。（文字列、ユニコード）

Reminder.priority

　リマインダーの優先順位です。（0＝優先順位付けなし、1＝優先順位最高、9＝優先順位最低）

Reminder.title

　リマインダーのタイトル（名称）です。（文字列、ユニコード）

Reminder.url

　リマインダーに関連づけた URL です。

Reminder メソッド

Reminder.save()

　修正した内容をデータベースに保存します。（例　リマインダーのタイトルや完了/未了の属性を変更した場合など）

Alarm オブジェクト

class reminders.Alarm

　Alarm オブジェクトは、リマインダーに関連づけられたアラームを意味します。アラームは、指定時刻、または指定地点への進入/退出の際に起動できます。 Reminder.alarms 属性を設定することでリマインダーとアラームを関連づけることができます。

Alarm の属性

Alarm.date

　アラームが予定されている日付です。（datetime オブジェクト）

Alarm.location

　地理的位置に基づいたアラームのタイトル（名称）、緯度、経度および半径です。位置は3要素または4要素のタプルで示されます。（タイトル、緯度、経度［、半径］）半径はデフォルトで100mになっています。

Alarm.proximity

　場所に応じたアラームの、到着または退出といった起動の条件を指定します。'enter'、'leave'または'none'のいずれかの値に設定します。