stapel-calendar

Calendar and scheduling: events with participants and RSVP, RFC 5545 recurring series (virtual expansion, on-demand materialization, per-instant cancellation and reschedule), availability windows with free/busy and bookable slot computation, ICS export, and event-driven reminders.

Part of the Stapel framework — composable Django apps that deploy as a monolith or as microservices without changing module code.

Install

pip install stapel-calendar

At a glance

Documentation

OpenAPI · capabilities.json · llms.txt (for agents)

What this is

A generic calendar core — Event / Participant / RSVP, an RFC 5545 recurrence engine (RRULE via python-dateutil, virtual expansion + on-demand materialization), availability (working windows, free/busy, slots) and ICS export. Two flavors of one domain — meetings and bookings — share this core; everything app-specific lives behind seams.

Quick start

INSTALLED_APPS = [
    # ...
    "stapel_calendar",
]

# urls.py
path("calendar/", include("stapel_calendar.urls"))

Concepts

• Event — a scheduled thing (meeting/booking/appointment) with tz-aware start/end, an owner and an opaque scope_key. No FK to any host concept (org, room) — scoping and resources are seams.
• Recurrence — the series master stores a canonical RRULE. Occurrences are virtual until they gain their own state (an RSVP or a resource), at which point they are materialized (persisted) on demand.
• Availability — recurring working windows minus busy events give open booking slots.

from stapel_calendar import services

series = services.create_event(
    owner=user, title="Standup",
    start=start, end=end,
    recurrence_type="weekdays",            # -> FREQ=DAILY;BYDAY=MO,TU,WE,TH,FR
)
occurrences = services.expand_event(series, range_start, range_end)  # virtual
services.materialize(series, occurrence_start)  # persist one + emit hook
busy = services.free_busy(user, range_start, range_end)
slots = services.compute_slots(user, range_start, range_end, slot_minutes=30)

Settings

All configuration lives in the STAPEL_CALENDAR namespace (dict setting, flat setting, or env var — resolved lazily):

comm surface

Extension points

See MODULE.md — the agent-facing map of every fork-free seam (the resource hook, reminder policy, scope provider, recurrence presets, serializer seams, settings).

Development

pip install -e . && pip install pytest pytest-django ruff
./setup-hooks.sh
pytest tests/

License

MIT — see LICENSE.

_{This page is assembled by stapel-readme from docs/readme.md plus the contract artifacts in docs/. Edit the prose in docs/readme.md; the badges, facts and links above and below it are generated — do not hand-edit README.md.}