Calendar Module Overview

PyXA supports nearly all AppleScript/JXA commands for the Calendar application while adding some additional quality-of-life methods that AppleScript is missing. Alarms are not currently supported, but they will be by the time of PyXA’s full release. New methods, such as PyXA.apps.Calendar.XACalendarEvent.add_attachment(), attempt to follow the style of JXA and make use of Apple’s EventKit Framework.

Calendar Tutorials

There are two (planned) tutorials for working with the Calendar application:

• Create a Daily Event Summary Script

• How To: Add a Zoom link to all events with a given tag

Calendar Examples

The examples below provide an overview of the capabilities of the Calendar module. They do not provide any output. For more in-depth examples that show output and provide more detailed explanations, refer to the previous section (Tutorials).

Example 1 - Listing Calendars and Events

One of the most common tasks when working with the Calendar application is that of listing events. PyXA offers several ways to obtain such lists, all of which may be useful in different contexts. In order to list events, you must first obtain a reference to one or more calendars, which can be done in a few ways as well. Lines 5-10 show the primary ways of obtain a calendar reference, while lines 12-18 show ways to obtain lists of events from the selected calendar.

A general rule of thumb when using PyXA to list events is that the more specific you can make your query, the better. While listing all events is necessary in some situations, a more specific query will always perform better. Filters, such as {“title”: “Learn PyXA”}, can be used to decrease the number of queried events and, likewise, decrease the time of the listing operation. Filters can contain multiple parameters to further narrow the selection of events. The Calendar module provides some helper methods to assist in the creation and application of filters. For example, PyXA.apps.Calendar.XACalendar.events_in_range() can (and should) be used to find events occurring between two dates.

In addition to listing events, you can obtain references to specific events using the methods shown in lines 20-25. These methods always select the first event that matches their respective filter, if applicable, so there are no performance concerns there. However, there is no guarantee that the list of events will maintain a consistent order. A filter that directly identifies an event using its unique properties is therefore preferred over a general filter that matches with multiple events.

from datetime import datetime, timedelta
import PyXA
app = PyXA.Application("Calendar")

# Getting calendars
all_calendars = app.calendars()
calendar = app.default_calendar()
calendar0 = app.calendar(0)
calendar1 = app.calendar(1)
named_calendar = app.calendar({"title": "Calendar"})

# Getting lists of events
all_events = calendar.events()
events_at_location = calendar.events({"location": "1 Main Street\\nPortland ME 04101\\nUnited States"})
named_events = calendar.events({"title": "Learn PyXA"})
events_between_dates = calendar.events_in_range(datetime.now(), datetime.now() + timedelta(days = 7))
events_today = calendar.events_today()
events_this_week = calendar.week_events()

# Getting specific events
event0 = calendar.event(0)
first_event = calendar.first_event()
last_event = calendar.last_event()
named_event = calendar.events({"title": "Learn PyXA"})[0]
event_by_id = calendar.event({"uid": "A54CF13A-36D2-5DE1-9980-BE19C4C102A4"})

# Get today's event from each calendar
events = []
for calendar in all_calendars:
   events.extend(calendar.events_today())

Example 2 - Creating Calendars and Events

from datetime import datetime, timedelta
import PyXA
app = PyXA.Application("Calendar")

# Create a new calendar
new_calendar = app.new_calendar("PyXA Development")

# Create new events
start_date = datetime.now()
end_date = start_date + timedelta(hours = 1)
app.new_event("Test 1", start_date, end_date) # Created in default/currently selected calendar
app.new_event("Test 2", start_date, end_date, new_calendar) # Created in the new calendar
new_calendar.new_event("Test 3", start_date, end_date) # Same as Test 2

Example 3 - Modifying and Manipulating Events

from datetime import date
import PyXA
app = PyXA.Application("Calendar")

calendar = app.default_calendar()
calendar1 = app.calendar(1)
event = calendar.events_today()[0]

# Modify event properties
event.rename("Title changed")

new_start_date = date(2022, 6, 6)
new_end_date = date(2022, 6, 7)
event.set_property("startDate", new_start_date)
event.set_property("endDate", new_end_date)

# Execute event actions
event.duplicate()
event.copy_to(calendar1)
event.move_to(calendar1)
event.delete()

Example 5 - Displaying Events in Calendar.app

from datetime import date
import PyXA
app = PyXA.Application("Calendar")

calendar = app.default_calendar()
calendar1 = app.calendar(1)
event = calendar.events_today()[0]

event.show()
app.switch_view_to("day")
app.switch_view_to("week")
app.switch_view_to("month")
app.view_calendar_at(date(2022, 6, 5))
app.view_calendar_at(event.end_date)

Calendar Resources

• Calendar User Guide - Apple Support

For all classes, methods, and inherited members of the Calendar module, see the Calendar Module Reference.