calgebra 🗓️

Set algebra for calendars. Compose lazily and query efficiently.

Installation

pip install calgebra
Or with Google Calendar support
pip install calgebra[google-calendar]
Or with iCalendar (.ics) file support
pip install calgebra[ical]

Quick Start

from calgebra import dayofweek, timeofday, at_tz, pprint, hours, HOUR
from itertools import islice
tz = "US/Pacific" at = at_tz(tz)
Team calendars
alice, bob, charlie = ...  # Timeline objects (Google Calendar, .ics files, etc.)
Define when work happens
weekend = dayofweek(["saturday", "sunday"], tz=tz)
weekdays = ~weekend
workhours = timeofday(start=9HOUR, duration=8HOUR, tz=tz)
business_hours = weekdays & workhours
When is anyone busy?
team_busy = alice | bob | charlie
Free slots: business hours minus busy, at least 2 hours
freeslots = (businesshours - team_busy) & (hours >= 2)
Query January 2025
pprint(islice(free_slots[at("2025-01-01"):at("2025-02-01")], 5), tz=tz)
2025-01-06 14:00:00 -> 2025-01-06 17:00:00
2025-01-08 09:00:00 -> 2025-01-08 12:00:00
...

Core Features:

• Set operations: | (union), & (intersection), - (difference), ~ (complement)
• Lazy composition: Build complex queries, execute with slicing
• Recurring patterns: dayofweek(), timeofday(), recurring() (RFC 5545)
• Interval filtering: hours >= 2, summary == "standup", custom properties
• Google Calendar: Read/write via calgebra.gcsa
• iCalendar (.ics): Load/save standard RFC 5545 files

License

MIT License - see LICENSE file for details.