macCal
A Python library to access local macOS calendars via EventKit and PyObjC. Works with macOS 26 Tahoe.
Overview
- Written in 100% python, easy to audit and extend
- Can search events, find free time, add/edit/delete events
- Fully typed
- Apache 2.0
Written by Guido Appenzeller, guido@appenzeller.net. Feedback and PR's welcome.
Requirements
- macOS 14+ (Sonoma or later)
- Python 3.13, but probably works with earlier versions
- Calendar access permission
Installation
With pip:
pip install maccal
For development:
git clone https://github.com/appenz/maccal
cd maccal
make install
Quick Start
from datetime import datetime, timedelta, timezone
from maccal import CalendarStore
store = CalendarStore()
# List calendars
for cal in store.list_calendars():
print(f"{cal.title} ({cal.type.name})")
# Get events for the next 7 days
now = datetime.now(tz=timezone.utc)
events = store.get_events(now, now + timedelta(days=7))
for event in events:
print(f"{event.start:%H:%M} {event.title}")
# Search events
results = store.find_events("standup", start=now, end=now + timedelta(days=30))
# Search specific fields
results = store.find_events(
"@acme.com",
start=now, end=now + timedelta(days=30),
fields=["attendee_email"],
)
# Create an event
event = store.add_event(
title="Team Lunch",
start=datetime(2026, 3, 15, 12, 0, tzinfo=timezone.utc),
end=datetime(2026, 3, 15, 13, 0, tzinfo=timezone.utc),
calendar="Personal",
location="Cafe",
)
# Find free time
slots = store.find_free_time(
start=datetime(2026, 3, 15, 9, 0, tzinfo=timezone.utc),
end=datetime(2026, 3, 15, 17, 0, tzinfo=timezone.utc),
duration=timedelta(minutes=30),
)
Searchable Fields
When using find_events, you can restrict search to specific fields:
title,location,notes,url,calendarorganizer_name,organizer_emailattendee_name,attendee_email
Pass fields=None (default) to search all fields.
Recurring Events
When querying events, recurring events are automatically expanded into individual occurrences. When editing or deleting a recurring event, you must specify which occurrences to affect:
store.update_event(
event.event_id,
title="New Title",
span="this", # "this" or "future"
occurrence_date=event.occurrence_date,
)
Omitting occurrence_date for a recurring event raises ValueError.
Development
make install # Install with dev dependencies
make test # Run tests
make lint # Check code style
make format # Auto-format code
make build # Build package
make benchmark # Run performance benchmarks
License
Apache 2.0. See LICENSE.
Metadata
Release files for maccal 1.0.2
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| maccal-1.0.2.tar.gz | 12.0 kB | Without provenance | Details for maccal-1.0.2.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| maccal-1.0.2-py3-none-any.whl | Python 3 | none | any | Details for maccal-1.0.2-py3-none-any.whl |
Total release size: 27.6 kB
Release files / maccal-1.0.2.tar.gz
| Download URL | maccal-1.0.2.tar.gz |
|---|---|
| Size | 12.0 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
c378d5962e6f1f27f88d712d28ae434ace0de17f1eb84e3be5cc3ebf8dd85f32
|
|
BLAKE2b-256 checksum How to use checksums |
35750dcaa1ba5c2c70514b5a27f8e7831c55c01b86c168cb42a005a937c937a6
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.8.8
|
Release files / maccal-1.0.2-py3-none-any.whl
| Download URL | maccal-1.0.2-py3-none-any.whl |
|---|---|
| Size | 15.7 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
310451296d8bb2ea629058271fb9f0e8bd66c915ab57bf8d1f1ef29c32581fa0
|
|
BLAKE2b-256 checksum How to use checksums |
0649f04b7e6fd65455993b05accbc755824851bb34864a757dd36cca004e6c27
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.8.8
|
Security for maccal 1.0.2
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.