Skip to content

codex_services.booking._shared.interfaces

interfaces

codex_services.booking._shared.interfaces

Protocol contracts for booking-specific adapters. Implement these protocols when building a new adapter for the booking engine.

Classes

ScheduleProvider

Bases: Protocol

Provides working schedules for resources.

Source code in src/codex_services/booking/_shared/interfaces.py 
17
18
19
20
21
22
23
24
25
26
class ScheduleProvider(Protocol):
    """Provides working schedules for resources."""

    def get_working_hours(self, resource_id: str, target_date: date) -> tuple[time, time] | None:
        """Return (start, end) of working day or None if day off."""
        ...

    def get_break_interval(self, resource_id: str, target_date: date) -> tuple[datetime, datetime] | None:
        """Return (start, end) of break or None."""
        ...
Functions
get_working_hours(resource_id, target_date)

Return (start, end) of working day or None if day off.

Source code in src/codex_services/booking/_shared/interfaces.py 
20
21
22
def get_working_hours(self, resource_id: str, target_date: date) -> tuple[time, time] | None:
    """Return (start, end) of working day or None if day off."""
    ...
get_break_interval(resource_id, target_date)

Return (start, end) of break or None.

Source code in src/codex_services/booking/_shared/interfaces.py 
24
25
26
def get_break_interval(self, resource_id: str, target_date: date) -> tuple[datetime, datetime] | None:
    """Return (start, end) of break or None."""
    ...

BusySlotsProvider

Bases: Protocol

Provides busy time slots for resources.

Source code in src/codex_services/booking/_shared/interfaces.py 
29
30
31
32
33
34
35
36
class BusySlotsProvider(Protocol):
    """Provides busy time slots for resources."""

    def get_busy_intervals(
        self, resource_ids: list[str], target_date: date
    ) -> dict[str, list[tuple[datetime, datetime]]]:
        """Return {resource_id: [(start, end), ...]} of busy times."""
        ...
Functions
get_busy_intervals(resource_ids, target_date)

Return {resource_id: [(start, end), ...]} of busy times.

Source code in src/codex_services/booking/_shared/interfaces.py 
32
33
34
35
36
def get_busy_intervals(
    self, resource_ids: list[str], target_date: date
) -> dict[str, list[tuple[datetime, datetime]]]:
    """Return {resource_id: [(start, end), ...]} of busy times."""
    ...

AvailabilityProvider

Bases: Protocol

Full availability provider — the main adapter contract. Implement this protocol for each framework adapter (Django, SQLAlchemy, etc.).

Source code in src/codex_services/booking/_shared/interfaces.py 
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
class AvailabilityProvider(Protocol):
    """
    Full availability provider — the main adapter contract.
    Implement this protocol for each framework adapter (Django, SQLAlchemy, etc.).
    """

    def build_resources_availability(
        self,
        resource_ids: list[str],
        target_date: date,
        cache_ttl: int = 300,
        exclude_appointment_ids: list[int] | None = None,
    ) -> dict[str, ResourceAvailability]:
        """Build availability for a single date. Return {resource_id: ResourceAvailability}."""
        ...

    def build_availability_batch(
        self,
        resource_ids: list[str],
        start_date: date,
        end_date: date,
    ) -> dict[date, dict[str, ResourceAvailability]]:
        """
        Build availability for a date range in a single batch.
        Must avoid N+1 queries — group appointments in memory.
        Return {date: {resource_id: ResourceAvailability}}.
        """
        ...
Functions
build_resources_availability(resource_ids, target_date, cache_ttl=300, exclude_appointment_ids=None)

Build availability for a single date. Return {resource_id: ResourceAvailability}.

Source code in src/codex_services/booking/_shared/interfaces.py 
45
46
47
48
49
50
51
52
53
def build_resources_availability(
    self,
    resource_ids: list[str],
    target_date: date,
    cache_ttl: int = 300,
    exclude_appointment_ids: list[int] | None = None,
) -> dict[str, ResourceAvailability]:
    """Build availability for a single date. Return {resource_id: ResourceAvailability}."""
    ...
build_availability_batch(resource_ids, start_date, end_date)

Build availability for a date range in a single batch. Must avoid N+1 queries — group appointments in memory. Return {date: {resource_id: ResourceAvailability}}.

Source code in src/codex_services/booking/_shared/interfaces.py 
55
56
57
58
59
60
61
62
63
64
65
66
def build_availability_batch(
    self,
    resource_ids: list[str],
    start_date: date,
    end_date: date,
) -> dict[date, dict[str, ResourceAvailability]]:
    """
    Build availability for a date range in a single batch.
    Must avoid N+1 queries — group appointments in memory.
    Return {date: {resource_id: ResourceAvailability}}.
    """
    ...