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.
Retrieving Existing Reminders#
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)
Adding New Reminders#
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 an
Alarm to a reminder. An
Alarm 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()
- reminders.get_reminders(calendar=None, completed=None)#
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:
None(the default): return all reminders
True: return only completed (checked off) reminders
Falsereturn only reminders that haven’t been completed yet
Return a list of all available calendars (
Calendarobjects). Calendars represent lists of reminders.
Return a specific
Calendarby its unique identifier. If no calendar with the given id can be found, None is returned.
Reminderfrom the database.
If the removal is successful, True is returned, otherwise False.
- class reminders.Calendar#
Calendarobjects 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.
- class reminders.Reminder([calendar])#
A list of
Alarmobjects that are associated with this reminder.
Note: The value represents a copy/snapshot; changing the list in-place won’t change the alarms unless you re-assign the attribute.
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.
The due date of the reminder.
Note: Setting a due date is not the same as setting an alarm. While the due date is shown in the Reminders app, you won’t get a notification unless you also add an
Alarm(by setting the
alarmsattribute of the reminder).
Additional notes for the reminder (string/unicode).
Priority of the reminder (0 = no priority, 1 = highest priority, 9 = lowest priority).
The title of the reminder (string/unicode).
A URL that is associated with the reminder.
- class reminders.Alarm#
Alarmobjects 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
Alarmwith a reminder by setting its
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