calque 0.1.0__py3-none-any.whl

calque/__init__.py

@@ -0,0 +1,3 @@
+"""Mirror accepted calendar events into another local macOS calendar as anonymised busy blocks."""
+
+__version__ = "0.1.0"

calque/cli.py

@@ -0,0 +1,200 @@
+"""Command-line entry point: parse options into a configuration and drive a synchronisation run."""
+
+import logging
+import re
+import sys
+from argparse import Action, ArgumentParser, BooleanOptionalAction, Namespace
+from collections.abc import Sequence
+from dataclasses import fields
+from typing import Any, cast
+
+from calque.config import DEFAULT_EXCLUDES, Config
+from calque.errors import CalqueError
+from calque.service import install, uninstall
+from calque.store import CalendarStore
+from calque.sync import synchronise
+
+
+class CompilePatterns(Action):
+    """Compile the given regular expressions and store them as the immutable exclusion-pattern set."""
+
+    def __call__(
+        self,
+        parser: ArgumentParser,  # noqa: ARG002
+        namespace: Namespace,
+        values: str | Sequence[Any] | None,
+        option_string: str | None = None,
+    ) -> None:
+        """Compile every pattern and store the resulting tuple on the namespace."""
+        setattr(namespace, self.dest, tuple(re.compile(pattern) for pattern in cast("Sequence[str]", values)))
+
+
+class CollectMapping(Action):
+    """Collect one or more ``--option-for KEY VALUE`` pairs into a mapping.
+
+    Requires that the destination field is defaulted to a mutable mapping type, which it updates in-place with each pair.
+    """
+
+    def __call__(
+        self,
+        parser: ArgumentParser,  # noqa: ARG002
+        namespace: Namespace,
+        values: str | Sequence[Any] | None,
+        option_string: str | None = None,
+    ) -> None:
+        """Store one parsed key/value pair into the mapping."""
+        key, value = cast("Sequence[str]", values)
+        getattr(namespace, self.dest)[key] = value
+
+
+class CollectSet(Action):
+    """Collect the given values into an immutable set on the namespace."""
+
+    def __call__(
+        self,
+        parser: ArgumentParser,  # noqa: ARG002
+        namespace: Namespace,
+        values: str | Sequence[Any] | None,
+        option_string: str | None = None,
+    ) -> None:
+        """Store the values as a frozenset on the namespace."""
+        setattr(namespace, self.dest, frozenset(cast("Sequence[str]", values)))
+
+
+def parse_arguments(arguments: list[str] | None) -> Namespace:
+    """Build the parser and parse the given command-line arguments."""
+    parser = ArgumentParser(
+        prog="calque",
+        description="Mirror accepted events from one local calendar into another as anonymised busy blocks.",
+    )
+    parser.add_argument(
+        "--list-calendars",
+        action="store_true",
+        help="list all local calendar titles (qualified account.calendar names) and exit",
+    )
+    parser.add_argument(
+        "--title",
+        default="Busy ({account} calendar)",
+        help="title template used for every mirror block",
+    )
+    parser.add_argument(
+        "--title-to",
+        nargs=2,
+        action=CollectMapping,
+        default={},
+        metavar=("ACCOUNT", "TEMPLATE"),
+        help="title template to use when writing into ACCOUNT's calendar, overriding --title; repeatable",
+    )
+    parser.add_argument(
+        "--title-from",
+        nargs=2,
+        action=CollectMapping,
+        default={},
+        metavar=("ACCOUNT", "TEMPLATE"),
+        help="title template for events read from ACCOUNT's calendar, overriding both --title and --title-to; repeatable",
+    )
+    parser.add_argument(
+        "--lookback",
+        type=int,
+        default=1,
+        help="days before now to mirror; with --cleanup, the window within which finished events are removed",
+    )
+    parser.add_argument("--lookahead", type=int, default=60, help="days after now to mirror")
+    parser.add_argument(
+        "--cleanup",
+        action=BooleanOptionalAction,
+        default=False,
+        help="remove mirror blocks once their event is over, instead of keeping them through the lookback window",
+    )
+    parser.add_argument("--dry-run", action="store_true", help="report the plan without writing anything")
+    parser.add_argument(
+        "--install",
+        type=int,
+        metavar="SECONDS",
+        help="install a launchd agent that runs this same command every SECONDS seconds, then exit",
+    )
+    parser.add_argument("--uninstall", action="store_true", help="remove the installed launchd agent and exit")
+    parser.add_argument("--logging", default="info", help="set the logging level")
+    parser.add_argument(
+        "--exclude-pattern",
+        dest="exclude_patterns",
+        nargs="+",
+        action=CompilePatterns,
+        default=tuple(re.compile(pattern) for pattern in DEFAULT_EXCLUDES),
+        metavar="REGEX",
+        help="Exclude calendar events with titles that match any of these patterns",
+    )
+    parser.add_argument(
+        "--exclude-clashes",
+        action=BooleanOptionalAction,
+        default=True,
+        help="skip a source event when the target is already busy over any part of its slot",
+    )
+    parser.add_argument(
+        "--exclude-all-day",
+        action=BooleanOptionalAction,
+        default=True,
+        help="skip all-day events",
+    )
+    parser.add_argument(
+        "--exclude-out-of-hours",
+        action=BooleanOptionalAction,
+        default=True,
+        help="skip events that fall entirely outside working hours (Mon-Fri 08:00-18:00)",
+    )
+    parser.add_argument(
+        "--mute",
+        dest="muted",
+        nargs="+",
+        action=CollectSet,
+        default=frozenset(),
+        metavar="CALENDAR",
+        help="calendar names that should not be mirrored to; their viewers won't see the mirrored busy blocks",
+    )
+    parser.add_argument(
+        "calendars",
+        nargs="*",
+        help="calendars to mirror; the first is the primary calendar that every auxiliary is mirrored into and back out from",
+    )
+    options = parser.parse_args(arguments)
+    # --list-calendars and --uninstall stand alone; a sync or an install needs a primary and at least one auxiliary.
+    if len(options.calendars) <= 1 and not (options.list_calendars or options.uninstall):
+        parser.error("at least two calendars are required: a primary and some auxiliary calendars to mirror with")
+    return options
+
+
+def to_config(options: Namespace) -> Config:
+    """Project the parsed options onto the configuration fields they share a name with.
+
+    The parser is responsible for giving every shared option its final type, so this mapping
+    stays uniform: a new option needs only to match on name.
+    """
+    return Config(
+        **{field.name: getattr(options, field.name) for field in fields(Config) if hasattr(options, field.name)}
+    )
+
+
+def main(arguments: list[str] | None = None) -> int:
+    """Dispatch one calque invocation — list, install, uninstall, or sync — and return a process exit code."""
+    arguments = sys.argv[1:] if arguments is None else arguments
+    options = parse_arguments(arguments)
+    logging.basicConfig(level=options.logging.upper(), format="%(levelname)s: %(message)s")
+
+    try:
+        if options.list_calendars:
+            for name in CalendarStore().qualified_names():
+                print(name)
+        elif options.install is not None:
+            install(arguments, options.install)
+        elif options.uninstall:
+            uninstall()
+        else:
+            synchronise(to_config(options), options.calendars)
+    except CalqueError as exception:
+        logging.error("calque failed: %s", exception)
+        return 1
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

calque/config.py

@@ -0,0 +1,69 @@
+"""Runtime configuration shared across every mirror direction."""
+
+import re
+from dataclasses import dataclass, field
+from datetime import time
+
+from calque.model import Participation
+from calque.store import Calendar
+
+# Titles that signal availability rather than a genuine commitment: a bare "Working"
+# status block, and any annual-leave marker (the "A/L" shorthand).
+DEFAULT_EXCLUDES = [r"^Working$", r"\bA/L\b"]
+
+
+@dataclass(frozen=True, slots=True)
+class Config:
+    """Settings governing how events are mirrored, independent of direction.
+
+    :param title: The default title template for mirror blocks; ``{field}`` placeholders are
+        filled from the source event (e.g. ``{account}``, ``{title}``).
+    :param title_to: Title templates keyed by the fully-qualified name of the
+        calendar being written into, overriding ``title`` for that target.
+    :param title_from: Title templates keyed by the fully-qualified name of the calendar an event was
+        read from, overriding ``title`` and any ``title_to`` entry for that source.
+    :param lookback: Days before now to keep mirrored, so recently-passed events stay tidy. When
+        ``cleanup`` is set, this instead bounds the window within which finished events are removed.
+    :param lookahead: Days after now to mirror.
+    :param statuses: The participation responses that count as "busy" and get mirrored.
+    :param exclude_patterns: Patterns whose match against a source title drops that event from the mirror.
+    :param exclude_clashes: Whether to drop a source event that overlaps an existing target event.
+    :param exclude_all_day: Whether to drop all-day events.
+    :param exclude_out_of_hours: Whether to drop events that fall entirely outside working hours.
+    :param work_days: Weekdays (Monday is 0) whose working hours are mirrored.
+    :param work_start: Start of the daily working-hours window, in local time.
+    :param work_end: End of the daily working-hours window, in local time.
+    :param muted: Names of calendars that should not be mirrored to, so their viewers never see the
+        mirrored busy blocks; the calendar is still read as a source and mirrored into the others.
+    :param cleanup: Whether to remove a mirror block once its event is over (end time has passed),
+        rather than keeping it for the ``lookback`` window.
+    :param dry_run: Whether to report the plan without writing any changes.
+    """
+
+    title: str = "Busy"
+    title_to: dict[str, str] = field(default_factory=dict)
+    title_from: dict[str, str] = field(default_factory=dict)
+    lookback: int = 1
+    lookahead: int = 60
+    statuses: frozenset[Participation] = field(default_factory=lambda: frozenset({Participation.ACCEPTED}))
+    exclude_patterns: tuple[re.Pattern[str], ...] = field(
+        default_factory=lambda: tuple(re.compile(pattern) for pattern in DEFAULT_EXCLUDES),
+    )
+    exclude_clashes: bool = True
+    exclude_all_day: bool = True
+    exclude_out_of_hours: bool = True
+    work_days: frozenset[int] = frozenset({0, 1, 2, 3, 4})
+    work_start: time = time(8)
+    work_end: time = time(18)
+    muted: frozenset[str] = frozenset()
+    cleanup: bool = False
+    dry_run: bool = False
+
+    def title_for_calendar(self, source: Calendar, target: Calendar) -> str:
+        """Return the title template for mirroring from ``source`` into ``target``, or the default.
+
+        A source override (``title_from``) wins over a target override (``title_to``), so a calendar
+        whose events should always be opaque can be pinned once wherever they land. Both are keyed on the
+        fully-qualified name (e.g. ``ClientCompany.Calendar``, as shown by ``--list-calendars``).
+        """
+        return self.title_from.get(source.qualified, self.title_to.get(target.qualified, self.title))

calque/errors.py

@@ -0,0 +1,33 @@
+"""Exception hierarchy for the mirror. Each composes its own message from the failing value."""
+
+
+class CalqueError(Exception):
+    """Base for every error raised by calque."""
+
+
+class AccessError(CalqueError):
+    """Calendar access was denied or could not be resolved in time."""
+
+    def __init__(self, status: object) -> None:
+        super().__init__(f"calendar access not granted (authorisation status {status})")
+
+
+class CalendarError(CalqueError):
+    """No calendar with the requested title exists in the local store."""
+
+    def __init__(self, title: str) -> None:
+        super().__init__(f"no calendar titled {title!r} found in the local store")
+
+
+class WriteError(CalqueError):
+    """EventKit refused to save or remove a mirror block."""
+
+    def __init__(self, detail: object) -> None:
+        super().__init__(f"EventKit write failed: {detail}")
+
+
+class ServiceError(CalqueError):
+    """Installing or removing the launchd agent failed."""
+
+    def __init__(self, detail: object) -> None:
+        super().__init__(f"launchctl failed: {detail}")

calque/exclusions.py

@@ -0,0 +1,186 @@
+"""Composable exclusion rules that keep selected source events out of the mirror.
+
+An :data:`Exclusion` is a predicate over an event, true when that event should be dropped.
+Builders turn configuration and target-calendar context into rules, :func:`rules` assembles
+the active ones, and :func:`excluded` runs them.
+"""
+
+import logging
+import re
+from collections.abc import Callable, Container, Iterable, Iterator
+from datetime import UTC, date, datetime, time, timedelta
+
+from calque.config import Config
+from calque.model import Event, Participation, untag
+
+Exclusion = Callable[[Event], bool]
+
+
+def dates_spanned(start: datetime, end: datetime) -> Iterator[date]:
+    """Yield each local calendar date an event touches, from its start through its end."""
+    day = start.date()
+    while day <= end.date():
+        yield day
+        day += timedelta(days=1)
+
+
+def by_title(patterns: tuple[re.Pattern[str], ...]) -> Exclusion:
+    """Build a rule excluding events whose title matches any of the given patterns."""
+
+    def rule(event: Event) -> bool:
+        """Test the event's title against every configured pattern."""
+        for pattern in patterns:
+            if pattern.search(event.title):
+                logging.debug("excluding %r by title (%r)", event.title, pattern.pattern)
+                return True
+        return False
+
+    return rule
+
+
+def by_clash(events: Iterable[Event]) -> Exclusion:
+    """Build a rule excluding events that overlap any interval already busy in the target."""
+    busy = tuple(event.window for event in events)
+
+    def rule(event: Event) -> bool:
+        """Half-open overlap test of the event against each busy interval."""
+        for interval in busy:
+            if event.start < interval.end and interval.start < event.end:
+                logging.debug("excluding %r due to clash with %s", event.title, interval)
+                return True
+        return False
+
+    return rule
+
+
+def by_passed() -> Exclusion:
+    """Build a rule excluding events whose end time has already passed.
+
+    Enabled by cleanup: the cut-off is the moment the rule is built — cheap to read and captured by
+    the returned closure — so a finished event drops out of the desired set and reconciliation
+    deletes its now-stale mirror block instead of keeping it through the lookback window.
+    """
+    now = datetime.now(UTC)
+
+    def rule(event: Event) -> bool:
+        """True when the event has already ended."""
+        result = event.end < now
+        if result:
+            logging.debug("excluding %r as already ended", event.title)
+        return result
+
+    return rule
+
+
+def by_origin(target: str) -> Exclusion:
+    """Build a rule excluding our own mirror blocks that we previously copied from ``target``.
+
+    A mirror is dropped only when it would return to the calendar it came from — which would become a
+    mirror of a mirror (this would otherwise be caused by a deleted event).
+    A mirror in the primary, sourced from one calendar, still propagates onward to the others.
+    """
+
+    def rule(event: Event) -> bool:
+        """True when the event is our mirror block originating from the target calendar."""
+        marker = untag(event.notes)
+        result = marker is not None and marker.origin == target
+        if result:
+            logging.debug("excluding %r as our own mirror returning to %s", event.title, target)
+        return result
+
+    return rule
+
+
+def is_all_day(event: Event) -> bool:
+    """Whether the event is an all-day event, which would otherwise block the whole day."""
+    result = event.all_day
+    if result:
+        logging.debug("excluding %r by all-day", event.title)
+    return result
+
+
+def by_participation(statuses: frozenset[Participation]) -> Exclusion:
+    """Build a rule excluding events whose participation is not among the mirrored statuses."""
+
+    def rule(event: Event) -> bool:
+        """True when the event's participation is not one we mirror."""
+        result = event.participation not in statuses
+        if result:
+            logging.debug("excluding %r by participation (%s)", event.title, event.participation.value)
+        return result
+
+    return rule
+
+
+def by_hours(days: Container[int], opening: time, closing: time) -> Exclusion:
+    """Build a rule excluding events that fall entirely outside the working-hours window.
+
+    Hours are compared in local time. An event is kept if it overlaps the window on any
+    working day it touches, so an event straddling the edge (e.g. 17:00-19:00) still mirrors.
+    """
+
+    def rule(event: Event) -> bool:
+        """True when no working-hours interval on any day the event spans overlaps it."""
+        start = event.start.astimezone()
+        end = event.end.astimezone()
+        result = not any(
+            start < datetime.combine(day, closing, start.tzinfo) and datetime.combine(day, opening, start.tzinfo) < end
+            for day in dates_spanned(start, end)
+            if day.weekday() in days
+        )
+        if result:
+            logging.debug("excluding %r by hours (%s-%s)", event.title, opening, closing)
+        return result
+
+    return rule
+
+
+def rules(config: Config, events: Iterable[Event], target: str) -> tuple[Exclusion, ...]:
+    """Return the active exclusion rule chain for mirroring into ``target`` given its busy ``events``.
+
+    The full exclusion chain:
+    - intrinsic rules:
+      - participation status
+      - title patterns
+      - all-day
+      - out-of-hours
+      - finished events, when cleanup is enabled
+    - our own mirror blocks returning to ``target``
+    - clash against target busy periods - which itself filters using the intrinsic rules
+
+    A mirror block is excluded only when its origin is ``target``, so a block written by a previous sync is never
+    returned to its source (which would chain into a mirror of a mirror) yet still propagates to the other
+    calendars. Genuinely busy periods are the target events the intrinsic rules don't themselves exclude, so a
+    focus block, all-day, out-of-hours or unaccepted event never blocks a source event.
+    """
+
+    def build() -> Iterable[Exclusion]:
+        yield by_participation(config.statuses)
+        if config.exclude_patterns:
+            yield by_title(config.exclude_patterns)
+        if config.exclude_all_day:
+            yield is_all_day
+        if config.exclude_out_of_hours:
+            yield by_hours(config.work_days, config.work_start, config.work_end)
+        if config.cleanup:
+            yield by_passed()
+
+    intrinsic = tuple(build())
+    exclusions = (*intrinsic, by_origin(target))
+    if not config.exclude_clashes:
+        return exclusions
+    # The clash rule takes the target events, which we filter to the genuinely busy periods using the intrinsic rules.
+    # Then, when it is used, it excludes any source event that overlaps the busy periods.
+    return (*exclusions, by_clash(included(events, intrinsic)))
+
+
+def excluded(event: Event, exclusions: Iterable[Exclusion]) -> bool:
+    """Predicate: whether any rule in the chain excludes the event."""
+    return any(rule(event) for rule in exclusions)
+
+
+def included(events: Iterable[Event], exclusions: Iterable[Exclusion]) -> Iterator[Event]:
+    """Filter: yield only the events that no exclusion rule rejects."""
+    for event in events:
+        if not excluded(event, exclusions):
+            yield event

calque/model.py

@@ -0,0 +1,158 @@
+"""Domain model for the mirror: events, anonymised busy blocks, and the reconciliation plan."""
+
+import logging
+from dataclasses import dataclass, field
+from datetime import datetime
+from enum import Enum
+from typing import Protocol
+
+MARKER = "⟦calque⟧"
+
+
+class Participation(Enum):
+    """The current user's response to an event invitation."""
+
+    ACCEPTED = "accepted"
+    TENTATIVE = "tentative"
+    DECLINED = "declined"
+    PENDING = "pending"
+    UNKNOWN = "unknown"
+
+
+class Source(Protocol):
+    """The slice of an EventKit ``EKSource`` we read: the account a calendar belongs to.
+
+    A narrowing of PyObjC's untyped objects; ``store.Calendar.source`` returns one.
+    """
+
+    def title(self) -> str:
+        """The account name (e.g. the Google or Exchange account behind the calendar)."""
+        ...
+
+
+@dataclass(frozen=True, slots=True)
+class Window:
+    """A half-open time range in UTC — a query range or an interval occupied by an event."""
+
+    start: datetime
+    end: datetime
+
+    def __str__(self) -> str:
+        """A readable local-time rendering of the range, dropping seconds and the timezone."""
+        start = self.start.astimezone()
+        end = self.end.astimezone()
+        until = f"{end:%H:%M}" if start.date() == end.date() else f"{end:%a %Y-%m-%d %H:%M}"
+        return f"{start:%a %Y-%m-%d %H:%M} to {until}"
+
+
+@dataclass(frozen=True, slots=True)
+class Event:
+    """A source-calendar event reduced to the fields the mirror cares about."""
+
+    identifier: str
+    title: str
+    account: str
+    window: Window
+    participation: Participation
+    all_day: bool
+    notes: str | None = None
+
+    @property
+    def start(self) -> datetime:
+        """The event's start, in UTC."""
+        return self.window.start
+
+    @property
+    def end(self) -> datetime:
+        """The event's end, in UTC."""
+        return self.window.end
+
+    def __str__(self) -> str:
+        """A human-readable representation of the event for logging and diagnostics."""
+        return f"title={self.title!r} {self.window}"
+
+
+@dataclass(frozen=True, slots=True)
+class Mirror:
+    """An anonymised busy block in the target calendar, linked to its source by identifier."""
+
+    source: str
+    window: Window
+    title: str
+    # Excluded from equality:
+    original: str | None = field(default=None, compare=False)
+    # The calendar this block was copied from, stored in the tag so a mirror is never returned to its
+    # source. Excluded from equality: it is fixed per direction and absent on blocks read back for diffing.
+    origin: str = field(default="", compare=False)
+
+    @property
+    def start(self) -> datetime:
+        """The block's start, in UTC."""
+        return self.window.start
+
+    @property
+    def end(self) -> datetime:
+        """The block's end, in UTC."""
+        return self.window.end
+
+    def __str__(self) -> str:
+        """A human-readable representation of the mirror, in local time, for diagnostics."""
+        return f"title={self.title!r} original={self.original!r} window={self.window} source={self.source!r}"
+
+
+@dataclass(frozen=True, slots=True)
+class Plan:
+    """The reconciliation outcome: blocks to create, retime, and remove in the target."""
+
+    create: tuple[Mirror, ...]
+    update: tuple[Mirror, ...]
+    delete: tuple[Mirror, ...]
+
+    @property
+    def empty(self) -> bool:
+        """Whether the plan would change nothing."""
+        return not (self.create or self.update or self.delete)
+
+    def __str__(self) -> str:
+        """A human-readable summary of the plan's contents for logging and diagnostics."""
+        return f"create={len(self.create)} update={len(self.update)} delete={len(self.delete)}"
+
+    def log(self) -> None:
+        """Log the plan's contents in a human-readable form."""
+        logging.info("create:")
+        for event in self.create:
+            logging.info("  %s", event)
+        logging.info("update:")
+        for event in self.update:
+            logging.info("  %s", event)
+        logging.info("delete:")
+        for event in self.delete:
+            logging.info("  %s", event)
+
+
+@dataclass(frozen=True, slots=True)
+class Tag:
+    """The provenance encoded on a mirror block: the calendar it was copied from and that source's event id."""
+
+    origin: str
+    identifier: str
+
+
+def tag(origin: str, identifier: str) -> str:
+    """Encode a mirror block's origin calendar and source event id into the marker stored on its notes.
+
+    The fields are space-separated: the identifier never contains a space, so it is the first token,
+    and the origin (which may) is the remainder. A space survives any normalisation that some
+    calendar backends apply, where a tab or newline does not.
+    """
+    return f"{MARKER} {identifier} {origin}"
+
+
+def untag(notes: str | None) -> Tag | None:
+    """Recover the origin and source id from a mirror block's notes, or ``None`` if not one of ours."""
+    if not notes or not notes.startswith(MARKER):
+        return None
+    identifier, _, origin = notes.removeprefix(MARKER).strip().partition(" ")
+    if not identifier:
+        return None
+    return Tag(origin=origin, identifier=identifier)