health.appointment-slots Unreviewed

def appointment_slots(sessions: Sequence[ClinicSession], slot_minutes: int, breaks: Sequence[ClinicBreak], bookings: Sequence[Booking]) -> List[AppointmentSlot]

@dataclass(frozen=True)
class ClinicSession:
    """One clinic session on one day; it cannot cross midnight."""

    date: str
    #: HH:MM, 24-hour
    start: str
    #: HH:MM, after start
    end: str

@dataclass(frozen=True)
class ClinicBreak:
    """A break inside sessions, such as lunch; slots restart after it."""

    #: null for a break on every session day
    date: Optional[str]
    #: HH:MM
    start: str
    #: HH:MM, after start
    end: str

@dataclass(frozen=True)
class Booking:
    """An existing appointment."""

    date: str
    #: HH:MM
    start: str
    #: HH:MM, after start
    end: str

@dataclass(frozen=True)
class AppointmentSlot:
    """One bookable slot."""

    date: str
    #: HH:MM
    start: str
    #: HH:MM
    end: str

from fune.health.appointment_slots import appointment_slots  # health.appointment-slots@^1

from typing import List, Optional, Sequence, Tuple

from .health_appointment_slots_types import AppointmentSlot, Booking, ClinicBreak, ClinicSession
from .time_minutes_between import minutes_between  ← from time.minutes-between ^1.0.0 · built alongside by fune

#: A break without a date still needs a real date for the time check.
_ANY_DATE = "2000-01-01"


def _minute_of_day(date: str, time: str) -> int:
    """Minute of the day, 0 to 1439; raises on a malformed date or time."""
    return minutes_between(date, "00:00", date, time)


def _interval(kind: str, date: Optional[str], start: str, end: str) -> Tuple[str, int, int]:
    on = _ANY_DATE if date is None else date
    begin = _minute_of_day(on, start)
    finish = _minute_of_day(on, end)
    if finish <= begin:
        raise ValueError(
            "%s on %s must end after it starts (%s to %s)" % (kind, "every day" if date is None else date, start, end)
        )
    return on, begin, finish


def _clock(minute: int) -> str:
    return "%02d:%02d" % (minute // 60, minute % 60)


def appointment_slots(
    sessions: Sequence[ClinicSession],
    slot_minutes: int,
    breaks: Sequence[ClinicBreak],
    bookings: Sequence[Booking],
) -> List[AppointmentSlot]:
    """Free appointment slots.

    Breaks split a session into segments and the slot grid restarts at the
    start of each segment, so a 12:30-13:30 lunch gives slots from 13:30.
    Bookings only take slots away: they never move the grid, because they are
    booked into slots. Intervals are half-open, so a booking ending at 09:15
    does not touch the 09:15 slot.
    """
    if isinstance(slot_minutes, bool) or not isinstance(slot_minutes, int) or slot_minutes < 1 or slot_minutes > 480:
        raise ValueError("slotMinutes must be a whole number from 1 to 480, received %r" % (slot_minutes,))
    clinic = [_interval("session", s.date, s.start, s.end) for s in sessions]
    closed = [(b.date is None,) + _interval("break", b.date, b.start, b.end) for b in breaks]
    booked = [_interval("booking", b.date, b.start, b.end) for b in bookings]

    clinic.sort(key=lambda s: (s[0], s[1]))
    for previous, current in zip(clinic, clinic[1:]):
        if current[0] == previous[0] and current[1] < previous[2]:
            raise ValueError("sessions overlap on %s" % (current[0],))

    slots: List[AppointmentSlot] = []
    for date, start, end in clinic:
        pauses = sorted(
            ((b_start, b_end) for always, b_date, b_start, b_end in closed if always or b_date == date),
        )
        segments: List[Tuple[int, int]] = []
        cursor = start
        for p_start, p_end in pauses:
            if p_end <= cursor or p_start >= end:
                continue
            if p_start > cursor:
                segments.append((cursor, p_start))
            cursor = max(cursor, p_end)
        if cursor < end:
            segments.append((cursor, end))

        for seg_start, seg_end in segments:
            t = seg_start
            while t + slot_minutes <= seg_end:
                slot_end = t + slot_minutes
                taken = any(b_date == date and b_start < slot_end and b_end > t for b_date, b_start, b_end in booked)
                if not taken:
                    slots.append(AppointmentSlot(date=date, start=_clock(t), end=_clock(slot_end)))
                t += slot_minutes
    return slots

Install

fune build

With that line in your source, in a Python project (language python in fune.project), fune build resolves it and its 1 dependency, pins them in fune.lock, downloads only the Python package of each, and builds the code above into your project’s .fune/build, one readable file per capability with a header linking back here. Or pin a range in fune.project and build in one step:

fune add health.appointment-slots

The manifest, vectors and README with only the Python implementation. Install it without the registry with fune add ./health.appointment-slots-1.0.1-python.fune, or fetch it from a terminal with fune pull health.appointment-slots@1.0.1:python.

The whole function, every language, is one file too: health.appointment-slots-1.0.1.fune, 28,395 bytes, sha256 9b81b0c2ed4032adce8b962d58a67032ce0817f7dcf79e05cf4ec899e66e00a1. It installs into a project of any language.

# fune: before health.appointment-slots

# fune: after health.appointment-slots

# fune: replace time.minutes-between in health.appointment-slots

# fune: step health.appointment-slots after <n|label>

More from the author

- **Breaks reshape a session.** A break (lunch, a team meeting) splits the session into free segments. Slots are laid back to back from the start of each segment, so after a 12:30-13:30 lunch the first slot is at 13:30, not wherever the morning's grid would have landed. A break with a null date applies to every session day. A break with a date applies to that day only. - **Leftovers are dropped.** A slot must fit wholly inside its segment. With 20-minute slots, 09:00-12:30 gives ten slots ending at 12:20, and the last 10 minutes are not offered. - **Bookings only take slots away.** A slot that overlaps any booking on the same date is removed, but the grid does not move. Bookings are made into slots, so a 5-minute booking at 09:05 removes the 09:00 slot and leaves 09:20 where it was. A booking across two slots removes both. - **Touching is not overlapping.** Intervals are half-open (start included, end excluded), so a booking ending at 09:15 leaves the 09:15 slot free.

Sessions may be given in any order. The result is sorted by date, then start time.

## Errors

The function refuses, rather than guessing, when:

- a time is not `HH:MM` from 00:00 to 23:59 (`9:00` and `24:00` are refused) - a date is not a real ISO date - a session, break or booking does not end after it starts - two sessions on the same date overlap - `slotMinutes` is not a whole number from 1 to 480

A session cannot cross midnight. Split an overnight clinic into two sessions, one on each date.

## What it does not do

It does not handle clinicians, rooms or appointment types. Call it once per clinician or resource. It does not handle double-booking capacity (more than one patient per slot) or daylight-saving changes. It does not keep slots in the past out of the list, because it never reads the clock: pass only the sessions still to come.

## Before you rely on this

**Not professional advice.** This capability calculates health figures from published rules. It is a software component for developers, not medical advice. Rules change and every rate here has an effective date. Check that the dates cover your case. Verify results against the official sources listed above, and have a clinician review how you use it, before anyone relies on the output. Provided "as is" under its licence, without warranty.

**Not a medical device.** It is not intended to diagnose, treat or support clinical decisions about any individual. Anyone building it into clinical software is responsible for that software's regulatory status, and must validate it under their own clinical governance.

**Unreviewed.** This capability's implementations agree in every language and pass its published test vectors, which were worked out from the official sources cited. But no qualified clinician has yet checked those vectors, or confirmed that the capability covers the cases it claims. Treat it as a draft. Do not use it for real people, money or decisions without your own expert review. Once a qualified reviewer signs off, this notice is replaced with their name, qualification and the date. Each new version needs fresh sign-off.

1.0.1 marks it unreviewed. The code and the tests are unchanged.

Files