stapel-calendar 0.1.0__tar.gz

stapel_calendar-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Stapel contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

stapel_calendar-0.1.0/PKG-INFO

@@ -0,0 +1,111 @@
+Metadata-Version: 2.4
+Name: stapel-calendar
+Version: 0.1.0
+Summary: Calendar and scheduling for the Stapel framework
+License: MIT
+Keywords: django,stapel,calendar
+Classifier: Framework :: Django
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: stapel-core<0.4,>=0.3.0
+Requires-Dist: python-dateutil<3,>=2.8
+Provides-Extra: all
+Dynamic: license-file
+
+# stapel-calendar
+
+Calendar, recurrence and scheduling for the [Stapel framework](https://github.com/usestapel) —
+composable Django apps that deploy as a monolith or as microservices
+without changing module code.
+
+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.
+
+## Install
+
+```bash
+pip install stapel-calendar
+```
+
+```python
+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.
+
+```python
+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):
+
+| Key | Default | Meaning |
+|---|---|---|
+| `SCOPE_PROVIDER` | `…scope.DefaultScopeProvider` | Resolve/filter the opaque `scope_key` |
+| `REMINDER_POLICY` | `…reminders.DefaultReminderPolicy` | When/what to remind |
+| `PRESETS` | `{}` | Custom recurrence presets (merged over built-ins) |
+| `REMINDER_OFFSETS` | `[10]` | Minutes before start to remind |
+| `REMINDER_SCAN_WINDOW_SECONDS` | `60` | Reminder cron granularity |
+| `DEFAULT_EXPANSION_HORIZON_DAYS` | `90` | Default range end |
+| `MAX_EXPANSION_OCCURRENCES` | `1000` | Expansion safety cap |
+| `DEFAULT_SLOT_MINUTES` | `30` | Default slot length |
+
+## comm surface
+
+| Kind | Name | Contract |
+|---|---|---|
+| Emit | `calendar.occurrence.materialized` | An occurrence was persisted — subscribe to attach a resource |
+| Emit | `calendar.event.reminder_due` | A reminder is due — deliver it |
+| Function | `calendar.free_busy` | `{user_id, start, end, scope_key?}` -> `{busy: [...]}` |
+
+## Extension points
+
+See [MODULE.md](MODULE.md) — the agent-facing map of every fork-free seam
+(the resource hook, reminder policy, scope provider, recurrence presets,
+serializer seams, settings).
+
+## Development
+
+```bash
+pip install -e . && pip install pytest pytest-django ruff
+./setup-hooks.sh
+pytest tests/
+```
+
+## License
+
+MIT

stapel_calendar-0.1.0/README.md

@@ -0,0 +1,94 @@
+# stapel-calendar
+
+Calendar, recurrence and scheduling for the [Stapel framework](https://github.com/usestapel) —
+composable Django apps that deploy as a monolith or as microservices
+without changing module code.
+
+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.
+
+## Install
+
+```bash
+pip install stapel-calendar
+```
+
+```python
+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.
+
+```python
+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):
+
+| Key | Default | Meaning |
+|---|---|---|
+| `SCOPE_PROVIDER` | `…scope.DefaultScopeProvider` | Resolve/filter the opaque `scope_key` |
+| `REMINDER_POLICY` | `…reminders.DefaultReminderPolicy` | When/what to remind |
+| `PRESETS` | `{}` | Custom recurrence presets (merged over built-ins) |
+| `REMINDER_OFFSETS` | `[10]` | Minutes before start to remind |
+| `REMINDER_SCAN_WINDOW_SECONDS` | `60` | Reminder cron granularity |
+| `DEFAULT_EXPANSION_HORIZON_DAYS` | `90` | Default range end |
+| `MAX_EXPANSION_OCCURRENCES` | `1000` | Expansion safety cap |
+| `DEFAULT_SLOT_MINUTES` | `30` | Default slot length |
+
+## comm surface
+
+| Kind | Name | Contract |
+|---|---|---|
+| Emit | `calendar.occurrence.materialized` | An occurrence was persisted — subscribe to attach a resource |
+| Emit | `calendar.event.reminder_due` | A reminder is due — deliver it |
+| Function | `calendar.free_busy` | `{user_id, start, end, scope_key?}` -> `{busy: [...]}` |
+
+## Extension points
+
+See [MODULE.md](MODULE.md) — the agent-facing map of every fork-free seam
+(the resource hook, reminder policy, scope provider, recurrence presets,
+serializer seams, settings).
+
+## Development
+
+```bash
+pip install -e . && pip install pytest pytest-django ruff
+./setup-hooks.sh
+pytest tests/
+```
+
+## License
+
+MIT

stapel_calendar-0.1.0/__init__.py

@@ -0,0 +1,31 @@
+"""stapel-calendar — Calendar and scheduling for the Stapel framework.
+
+Public API (lazily exported, PEP 562 — importing this package never pulls
+in Django or requires configured settings):
+
+- ``calendar_settings`` — resolved app settings (``stapel_calendar.conf``).
+"""
+
+__all__ = [
+    "calendar_settings",
+]
+
+# name -> submodule that defines it. Resolution is deferred until first
+# attribute access so that `import stapel_calendar` stays Django-free.
+_LAZY_EXPORTS = {
+    "calendar_settings": ".conf",
+}
+
+
+def __getattr__(name):
+    if name in _LAZY_EXPORTS:
+        from importlib import import_module
+
+        value = getattr(import_module(_LAZY_EXPORTS[name], __name__), name)
+        globals()[name] = value  # cache for subsequent lookups
+        return value
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+
+
+def __dir__():
+    return sorted(set(globals()) | set(__all__))

stapel_calendar-0.1.0/actions.py

@@ -0,0 +1,25 @@
+"""Action subscriptions of stapel-calendar.
+
+Handlers must be idempotent: delivery is at-least-once (outbox retries,
+broker redelivery). Consumes contracts live in ``schemas/consumes/``.
+"""
+import logging
+
+from stapel_core.comm import on_action
+
+logger = logging.getLogger(__name__)
+
+
+@on_action("user.deleted")
+def handle_user_deleted(event):
+    """Erase this module's PII when an account deletion is executed:
+    the user's owned events (and their occurrences/participants), their
+    participations in other events, and their availability windows."""
+    from .gdpr import CalendarGDPRProvider
+
+    user_id = event.payload.get("user_id")
+    if not user_id:
+        logger.error("user.deleted event without user_id: %s", event.event_id)
+        return
+    CalendarGDPRProvider().delete(user_id)
+    logger.info("calendar data erased for deleted user %s", user_id)

stapel_calendar-0.1.0/admin.py

@@ -0,0 +1,25 @@
+"""Admin registrations for stapel-calendar (observability; kept minimal)."""
+from django.contrib import admin
+
+from .models import AvailabilityWindow, Event, Participant
+
+
+class ParticipantInline(admin.TabularInline):
+    model = Participant
+    extra = 0
+    fields = ("user", "rsvp")
+
+
+@admin.register(Event)
+class EventAdmin(admin.ModelAdmin):
+    list_display = ("title", "start", "end", "owner", "scope_key", "recurrence_type")
+    list_filter = ("recurrence_type", "status")
+    search_fields = ("title", "scope_key")
+    date_hierarchy = "start"
+    inlines = [ParticipantInline]
+
+
+@admin.register(AvailabilityWindow)
+class AvailabilityWindowAdmin(admin.ModelAdmin):
+    list_display = ("user", "weekday", "start_time", "end_time", "timezone")
+    list_filter = ("weekday",)

stapel_calendar-0.1.0/apps.py

@@ -0,0 +1,24 @@
+from django.apps import AppConfig
+
+
+class CalendarConfig(AppConfig):
+    name = "stapel_calendar"
+    label = "calendar"
+    verbose_name = "Calendar and scheduling"
+    default_auto_field = "django.db.models.BigAutoField"
+
+    def ready(self):
+        # Import-time side effects: comm functions/actions, system checks,
+        # error-key registration. Keep each in its own module.
+        from . import actions  # noqa: F401
+        from . import checks  # noqa: F401
+        from . import errors  # noqa: F401
+        from . import functions  # noqa: F401
+
+        # GDPR: register the per-app data handler (monolith in-process mode).
+        from stapel_core.gdpr import gdpr_registry
+
+        from .gdpr import CalendarGDPRProvider
+
+        if not any(p.section == "calendar" for p in gdpr_registry.providers):
+            gdpr_registry.register(CalendarGDPRProvider())

stapel_calendar-0.1.0/checks.py

@@ -0,0 +1,73 @@
+"""Django system checks for stapel-calendar configuration.
+
+Policy (docs/library-standard.md §3.7): E-level for configuration the
+service cannot run with; W-level for entries that only degrade lazily.
+
+- SCOPE_PROVIDER unimportable / not a ScopeProvider -> E (create & list
+  cannot resolve/filter scope).
+- REMINDER_POLICY unimportable -> W (only reminders degrade; the calendar
+  still serves).
+- REMINDER_OFFSETS not a list of non-negative ints -> E (would crash the
+  reminder cron with a confusing error).
+"""
+from django.core import checks
+
+
+@checks.register(checks.Tags.compatibility)
+def check_scope_provider(app_configs, **kwargs):
+    from .conf import calendar_settings
+    from .scope import ScopeProvider
+
+    try:
+        provider = calendar_settings.SCOPE_PROVIDER
+    except Exception as exc:
+        return [
+            checks.Error(
+                f"STAPEL_CALENDAR['SCOPE_PROVIDER'] could not be imported: {exc}",
+                id="stapel_calendar.E001",
+            )
+        ]
+    target = provider if isinstance(provider, type) else type(provider)
+    if not issubclass(target, ScopeProvider):
+        return [
+            checks.Error(
+                "STAPEL_CALENDAR['SCOPE_PROVIDER'] must be a ScopeProvider subclass",
+                id="stapel_calendar.E002",
+            )
+        ]
+    return []
+
+
+@checks.register(checks.Tags.compatibility)
+def check_reminder_policy(app_configs, **kwargs):
+    from .conf import calendar_settings
+
+    try:
+        calendar_settings.REMINDER_POLICY
+    except Exception as exc:
+        return [
+            checks.Warning(
+                f"STAPEL_CALENDAR['REMINDER_POLICY'] could not be imported: {exc}. "
+                "Reminders are disabled until this resolves.",
+                id="stapel_calendar.W001",
+            )
+        ]
+    return []
+
+
+@checks.register(checks.Tags.compatibility)
+def check_reminder_offsets(app_configs, **kwargs):
+    from .conf import calendar_settings
+
+    offsets = calendar_settings.REMINDER_OFFSETS
+    if not isinstance(offsets, (list, tuple)) or any(
+        not isinstance(o, int) or o < 0 for o in offsets
+    ):
+        return [
+            checks.Error(
+                "STAPEL_CALENDAR['REMINDER_OFFSETS'] must be a list of "
+                "non-negative integers (minutes).",
+                id="stapel_calendar.E003",
+            )
+        ]
+    return []

stapel_calendar-0.1.0/conf.py

@@ -0,0 +1,60 @@
+"""Settings namespace for stapel-calendar.
+
+All configuration is read through ``calendar_settings`` (lazily, at call
+time) — never via module-level ``os.getenv`` (values would freeze at import).
+Resolution order per key: ``settings.STAPEL_CALENDAR`` dict -> flat Django
+setting of the same name -> environment variable -> default below.
+
+Dotted-path keys listed in ``import_strings`` are resolved with
+``import_string`` — the fork-free escape hatch for swappable behavior.
+
+The four documented extension seams (see MODULE.md):
+
+- ``SCOPE_PROVIDER`` — resolves/filters the opaque ``scope_key`` from the
+  request (meettoday supplies ``workspace_id``). The library itself is
+  scope-agnostic.
+- ``REMINDER_POLICY`` — decides *when* and *what* to remind; the default
+  emits ``calendar.event.reminder_due`` for stapel-notifications to deliver.
+- ``PRESETS`` — recurrence presets merged OVER the built-ins
+  (none/daily/weekdays/weekly/biweekly/monthly/custom), so a host can add
+  custom RRULE presets without restating the built-ins (``None`` removes).
+- the *resource hook* is the ``calendar.occurrence.materialized`` comm
+  emit (schemas/emits/) — no setting; app-layers subscribe.
+"""
+from stapel_core.conf import AppSettings
+
+calendar_settings = AppSettings(
+    "STAPEL_CALENDAR",
+    defaults={
+        # Cap for virtual expansion of an unbounded series (no UNTIL/COUNT
+        # in the RRULE and no explicit range end): how many days ahead of
+        # the range start to expand for display.
+        "DEFAULT_EXPANSION_HORIZON_DAYS": 90,
+        # Hard safety cap on the number of occurrences a single expansion
+        # may yield — protects against a pathological RRULE.
+        "MAX_EXPANSION_OCCURRENCES": 1000,
+        # Reminder offsets in minutes before an event's start that the
+        # default policy fires a `calendar.event.reminder_due` for.
+        "REMINDER_OFFSETS": [10],
+        # Granularity (seconds) of the reminder cron scan — a reminder is
+        # "due" when now falls in [fire_time, fire_time + this window).
+        "REMINDER_SCAN_WINDOW_SECONDS": 60,
+        # Dotted path to a ReminderPolicy — the reminder seam. The default
+        # emits the reminder_due event; swap for a custom cadence/channel
+        # decision without forking.
+        "REMINDER_POLICY": "stapel_calendar.reminders.DefaultReminderPolicy",
+        # Dotted path to a ScopeProvider — resolves the opaque scope_key
+        # from a request and filters querysets by it. The default is a
+        # no-op (single global scope); meettoday returns workspace_id.
+        "SCOPE_PROVIDER": "stapel_calendar.scope.DefaultScopeProvider",
+        # Recurrence presets merged OVER recurrence.BUILTIN_PRESETS. A value
+        # is a dict of dateutil.rrule kwargs (freq/interval/byweekday/...);
+        # None removes a built-in.
+        "PRESETS": {},
+        # Default slot length (minutes) for availability slot computation.
+        "DEFAULT_SLOT_MINUTES": 30,
+    },
+    import_strings=("REMINDER_POLICY", "SCOPE_PROVIDER"),
+)
+
+__all__ = ["calendar_settings"]

stapel_calendar-0.1.0/conftest.py

@@ -0,0 +1,115 @@
+def pytest_configure(config):
+    from django.conf import settings
+    if not settings.configured:
+        settings.configure(
+            SECRET_KEY="test-secret-key-not-for-production",
+            INSTALLED_APPS=[
+                "django.contrib.contenttypes",
+                "django.contrib.auth",
+                "django.contrib.sessions",
+                "django.contrib.admin",
+                "django.contrib.messages",
+                "stapel_core.django.users",
+                "rest_framework",
+                "stapel_calendar",
+            ],
+            AUTH_USER_MODEL="users.User",
+            DATABASES={
+                "default": {
+                    "ENGINE": "django.db.backends.sqlite3",
+                    "NAME": ":memory:",
+                }
+            },
+            DEFAULT_AUTO_FIELD="django.db.models.BigAutoField",
+            USE_TZ=True,
+            ROOT_URLCONF="stapel_calendar.tests.urls",
+            CACHES={
+                "default": {
+                    "BACKEND": "django.core.cache.backends.locmem.LocMemCache",
+                }
+            },
+            # Synchronous in-process comm with schema validation ON, so the
+            # committed contracts in schemas/ are enforced by the tests.
+            STAPEL_BUS_BACKEND="stapel_core.bus.backends.memory.MemoryBus",
+            STAPEL_COMM={
+                "OUTBOX_ENABLED": False,
+                "ACTION_TRANSPORT": "inprocess",
+                "VALIDATE_SCHEMAS": True,
+            },
+            MIGRATION_MODULES={
+                "users": None,
+                "calendar": None,
+            },
+        )
+        import django
+        django.setup()
+
+        from stapel_core.comm.schemas import autoload_schemas
+        autoload_schemas()
+
+
+import pytest  # noqa: E402
+
+
+@pytest.fixture
+def api_client():
+    from rest_framework.test import APIClient
+    return APIClient()
+
+
+@pytest.fixture
+def user(db):
+    from django.contrib.auth import get_user_model
+    return get_user_model().objects.create_user(
+        username="alice", email="alice@example.com", password="x"
+    )
+
+
+@pytest.fixture
+def other_user(db):
+    from django.contrib.auth import get_user_model
+    return get_user_model().objects.create_user(
+        username="bob", email="bob@example.com", password="x"
+    )
+
+
+@pytest.fixture
+def auth_client(api_client, user):
+    api_client.force_authenticate(user=user)
+    return api_client
+
+
+@pytest.fixture(autouse=True)
+def _reset_recurrence_presets():
+    """Keep the recurrence preset registry clean between tests."""
+    from stapel_calendar.recurrence import reset_presets
+    reset_presets()
+    yield
+    reset_presets()
+
+
+@pytest.fixture
+def captured_events():
+    """Subscribe to calendar emits (in-process) and collect the Event
+    envelopes. Delivery is synchronous with OUTBOX disabled, so the list is
+    populated by the time emit() returns."""
+    from stapel_core.comm import action_registry, subscribe_action
+
+    collected = []
+
+    def _handler(event):
+        collected.append(event)
+
+    names = [
+        "calendar.occurrence.materialized",
+        "calendar.event.reminder_due",
+    ]
+    for name in names:
+        subscribe_action(name, _handler)
+    try:
+        yield collected
+    finally:
+        for name in names:
+            handlers = action_registry._subscribers.get(name, [])
+            if _handler in handlers:
+                handlers.remove(_handler)