The reminders module provides read/write access to the iOS Reminders database. Reminders are represented by the Reminder class, and lists of reminders by the Calendar class.
Note
The first time you use any of the functions that access your reminders, a system-provided permission dialog will be shown. If you deny access, most functions will return empty data. If you change your mind later, you can allow access to your reminders from the Privacy section in the Settings app.
To retrieve all reminders that are in the database, simply call get_reminders(). With the completed parameter, you can filter the list by their completion status (whether the reminder is checked off).:
import reminders
todo = reminders.get_reminders(completed=False)
print 'TODO List'
print '========='
for r in todo:
print '[ ] ' + r.title
done = reminders.get_reminders(completed=True)
print 'DONE'
print '===='
for r in done:
print '[x] ' + r.title
To add a new reminder, simply create a Reminder object, set its title, due date, etc., and then call its Reminder.save() method.:
import reminders
r = reminders.Reminder()
r.title = 'Added from Pythonista'
r.save()
print 'Reminder added'
You can have multiple lists of reminders in the Reminders app. Those lists are represented by Calendar objects in this module. If you don’t specify otherwise, reminders are added to the default list/calendar. To add a reminder to a different list, simply pass the corresponding Calendar object when creating the reminder.
The following example looks for a calendar with the title “Pythonista”, and adds a new reminder to it, if it exists.:
import reminders
all_calendars = reminders.get_all_calendars()
for calendar in all_calendars:
if calendar.title == 'Pythonista':
r = reminders.Reminder(calendar)
r.title = 'New Reminder in Pythonista List'
r.save()
break
else:
print 'Could not find calendar named "Pythonista"'
You can also create new calendars programmatically. This example adds a calendar with the title Pythonista if it doesn’t exist already:
import reminders
all_calendars = reminders.get_all_calendars()
for calendar in all_calendars:
if calendar.title == 'Pythonista':
print 'Calendar "Pythonista" already exists'
break
else:
new_calendar = reminders.Calendar()
new_calendar.title = 'Pythonista'
new_calendar.save()
print 'New calendar added'
Reminders are much more useful when they actually remind you of something, i.e. show a notification. To do that, you have to add one or more :class:`Alarm`s to a reminder. :class:`Alarm`s can be triggered at a specific time, or when entering/leaving a geographic location.
Let’s look at date/time-based alarms first. This example adds a new reminder that triggers a notification 25 minutes from now:
import reminders
import datetime
r = reminders.Reminder()
r.title = 'Take a break!'
minutes = 25
due = datetime.datetime.now() + datetime.timedelta(minutes=minutes)
# Note: We're setting the due date to the same time as the alarm here,
# but they can also be different.
r.due_date = due
a = reminders.Alarm()
a.date = due
r.alarms = [a]
r.save()
print 'You will be reminded in %i minutes.' % minutes
To add a geolocation-based alarm, you have to specify a title, latitude, and longitude. You can also specify a radius, and whether the alarm should be triggered when entering or leaving that radius:
import reminders
r = reminders.Reminder()
r.title = 'Take a selfie'
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()
Return all reminders in the given Calendar (or all calendars).
If the calendar parameter is omitted or None, all reminders in all calendars are returned.
The completed parameter can be used to filter reminders by completion status:
Return a list of all available calendars (Calendar objects). Calendars represent lists of reminders.
Return a specific Calendar by its unique identifier. If no calendar with the given id can be found, None is returned.
Calendar objects represent lists of reminders. Every reminder belongs to a single calendar, and you can retrieve the reminders of a specific calendar using the get_reminders() function. To get the default calendar for new reminders, use get_default_calendar(). Each calendar has a unique identifier that allows you to retrieve it reliably (using the get_calendar() function), regardless of whether its title has changed.
The title of the list of reminders (string/unicode).
The unique identifier of the calendar (readonly, string).
This can be used to retrieve this specific calendar later, even if its title may have changed.
Save changes to the database (only the calendar’s metadata is saved, reminders within the calendar have to be saved with their own Reminder.save() method).
Reminder objects represent a single reminder in a list. Reminders can have multiple :class:`Alarm`s which determine when/where/if the system shows a notification for the reminder.
The calendar argument is optional – if you don’t pass a value, the reminder is created in the default Calendar.
The title of the reminder (string/unicode).
Additional notes for the reminder (string/unicode).
Whether the reminder has been completed (checked off) yet (boolean).
The date when the reminder was completed (checked off) or None if it hasn’t been completed yet.
Alarm objects represents an alarm that is associated with a reminder. Alarms can be triggered at a specific time, or when entering/leaving a geographic location. You can associate an Alarm with a reminder by setting its Reminder.alarms attribute.
The absolute date when the alarm is triggered (datetime object).
The title, coordinates and radius for geo-location-based alarms. The location is represented as a 3- or 4-tuple (title, latitude, longitude[, radius]). The radius is set to 100m by default.
Determines if a location-based alarm is triggered when entering or leaving the specified area. Possible values are 'enter', 'leave' and 'none'.