slotlock 0.3.0__py3-none-any.whl

slotlock/__init__.py

@@ -0,0 +1,17 @@
+"""A client for Slotlock's REST API: the agent tools and the application API, from Python.
+
+    from slotlock import Client
+
+    slotlock = Client("https://calendar.example.com", api_key)
+    hold = slotlock.acquire_hold(resource_id=..., start=..., end=..., ttl_seconds=600)["hold"]
+"""
+
+from ._operations import OPERATIONS, Operations
+from ._transport import UNSET, SlotlockError, Unset, __version__
+
+
+class Client(Operations):
+    """A Slotlock server, reached with one API key. `Transport` describes the arguments."""
+
+
+__all__ = ["OPERATIONS", "UNSET", "Client", "SlotlockError", "Unset", "__version__"]

slotlock/_operations.py

@@ -0,0 +1,829 @@
+# Generated from openapi.json by clients/generate.ts. Do not edit: change the server, then run
+# SLOTLOCK_WRITE_GENERATED=1 npx vitest run src/__tests__/generated.test.ts
+from __future__ import annotations
+
+from typing import Any
+
+from ._transport import UNSET, Operation, Transport, Unset
+
+#: Every operation, by name: its method, path, path parameters and query parameters.
+OPERATIONS: dict[str, Operation] = {
+    "slotlock_list_resources": Operation(
+        "slotlock_list_resources",
+        "GET",
+        "/v1/resources",
+        (),
+        ("cursor", "limit"),
+    ),
+    "slotlock_create_resource": Operation(
+        "slotlock_create_resource",
+        "POST",
+        "/v1/resources",
+        (),
+        (),
+    ),
+    "slotlock_get_free_busy": Operation(
+        "slotlock_get_free_busy",
+        "GET",
+        "/v1/free-busy",
+        (),
+        ("resource_ids", "start", "end"),
+    ),
+    "slotlock_find_next_available": Operation(
+        "slotlock_find_next_available",
+        "GET",
+        "/v1/next-available",
+        (),
+        ("resource_ids", "start", "end", "duration_minutes"),
+    ),
+    "slotlock_list_events": Operation(
+        "slotlock_list_events",
+        "GET",
+        "/v1/events",
+        (),
+        ("resource_ids", "start", "end", "cursor", "limit"),
+    ),
+    "slotlock_create_event": Operation(
+        "slotlock_create_event",
+        "POST",
+        "/v1/events",
+        (),
+        (),
+    ),
+    "slotlock_get_event": Operation(
+        "slotlock_get_event",
+        "GET",
+        "/v1/events/{event_id}",
+        ("event_id",),
+        (),
+    ),
+    "slotlock_update_event": Operation(
+        "slotlock_update_event",
+        "PATCH",
+        "/v1/events/{event_id}",
+        ("event_id",),
+        (),
+    ),
+    "slotlock_delete_event": Operation(
+        "slotlock_delete_event",
+        "DELETE",
+        "/v1/events/{event_id}",
+        ("event_id",),
+        ("expected_revision", "idempotency_key"),
+    ),
+    "slotlock_get_resource": Operation(
+        "slotlock_get_resource",
+        "GET",
+        "/v1/resources/{resource_id}",
+        ("resource_id",),
+        (),
+    ),
+    "slotlock_delete_resource": Operation(
+        "slotlock_delete_resource",
+        "DELETE",
+        "/v1/resources/{resource_id}",
+        ("resource_id",),
+        (),
+    ),
+    "slotlock_archive_resource": Operation(
+        "slotlock_archive_resource",
+        "POST",
+        "/v1/resources/{resource_id}/archive",
+        ("resource_id",),
+        (),
+    ),
+    "slotlock_restore_resource": Operation(
+        "slotlock_restore_resource",
+        "POST",
+        "/v1/resources/{resource_id}/restore",
+        ("resource_id",),
+        (),
+    ),
+    "slotlock_list_busy": Operation(
+        "slotlock_list_busy",
+        "GET",
+        "/v1/resources/{resource_id}/busy",
+        ("resource_id",),
+        ("start", "end"),
+    ),
+    "slotlock_set_resource_availability": Operation(
+        "slotlock_set_resource_availability",
+        "PUT",
+        "/v1/resources/{resource_id}/availability",
+        ("resource_id",),
+        (),
+    ),
+    "slotlock_set_tenant_availability": Operation(
+        "slotlock_set_tenant_availability",
+        "PUT",
+        "/v1/availability",
+        (),
+        (),
+    ),
+    "slotlock_acquire_hold": Operation(
+        "slotlock_acquire_hold",
+        "POST",
+        "/v1/holds",
+        (),
+        (),
+    ),
+    "slotlock_get_hold": Operation(
+        "slotlock_get_hold",
+        "GET",
+        "/v1/holds/{hold_id}",
+        ("hold_id",),
+        (),
+    ),
+    "slotlock_release_hold": Operation(
+        "slotlock_release_hold",
+        "DELETE",
+        "/v1/holds/{hold_id}",
+        ("hold_id",),
+        (),
+    ),
+    "slotlock_list_holds": Operation(
+        "slotlock_list_holds",
+        "GET",
+        "/v1/resources/{resource_id}/holds",
+        ("resource_id",),
+        ("limit", "cursor"),
+    ),
+    "slotlock_confirm_hold": Operation(
+        "slotlock_confirm_hold",
+        "POST",
+        "/v1/holds/{hold_id}/confirm",
+        ("hold_id",),
+        (),
+    ),
+    "slotlock_get_reservation": Operation(
+        "slotlock_get_reservation",
+        "GET",
+        "/v1/reservations/{reservation_ref}",
+        ("reservation_ref",),
+        (),
+    ),
+    "slotlock_put_reservation": Operation(
+        "slotlock_put_reservation",
+        "PUT",
+        "/v1/reservations/{reservation_ref}",
+        ("reservation_ref",),
+        (),
+    ),
+    "slotlock_cancel_reservation": Operation(
+        "slotlock_cancel_reservation",
+        "DELETE",
+        "/v1/reservations/{reservation_ref}",
+        ("reservation_ref",),
+        ("revision",),
+    ),
+    "slotlock_list_reservations": Operation(
+        "slotlock_list_reservations",
+        "GET",
+        "/v1/resources/{resource_id}/reservations",
+        ("resource_id",),
+        ("start", "end", "limit", "cursor"),
+    ),
+    "slotlock_record_coverage": Operation(
+        "slotlock_record_coverage",
+        "PUT",
+        "/v1/resources/{resource_id}/coverage/{source}",
+        ("resource_id", "source"),
+        (),
+    ),
+    "slotlock_list_tenant_events": Operation(
+        "slotlock_list_tenant_events",
+        "GET",
+        "/v1/tenant/events",
+        (),
+        ("resource_id", "start", "end", "limit", "cursor"),
+    ),
+    "slotlock_get_tenant_event": Operation(
+        "slotlock_get_tenant_event",
+        "GET",
+        "/v1/tenant/events/{event_id}",
+        ("event_id",),
+        (),
+    ),
+    "slotlock_cancel_tenant_event": Operation(
+        "slotlock_cancel_tenant_event",
+        "DELETE",
+        "/v1/tenant/events/{event_id}",
+        ("event_id",),
+        ("expected_revision", "expected_resource_id", "idempotency_key"),
+    ),
+    "slotlock_get_tenant": Operation(
+        "slotlock_get_tenant",
+        "GET",
+        "/v1/tenant",
+        (),
+        (),
+    ),
+    "slotlock_erase_tenant": Operation(
+        "slotlock_erase_tenant",
+        "POST",
+        "/v1/tenant/erase",
+        (),
+        (),
+    ),
+    "slotlock_run_maintenance": Operation(
+        "slotlock_run_maintenance",
+        "POST",
+        "/v1/maintenance",
+        (),
+        (),
+    ),
+}
+
+
+class Operations(Transport):
+    """Every Slotlock REST operation as a method; `call` runs one by name."""
+
+    def list_resources(
+        self,
+        *,
+        cursor: str | None = None,
+        limit: int | None = None,
+    ) -> dict[str, Any]:
+        """List calendar resources.
+
+        List resources visible to the authenticated tenant principal.
+        """
+        values: dict[str, Any] = {}
+        if cursor is not None:
+            values["cursor"] = cursor
+        if limit is not None:
+            values["limit"] = limit
+        return self.call("slotlock_list_resources", values)
+
+    def create_resource(
+        self,
+        *,
+        external_ref: str,
+        timezone: str | None = None,
+        visibility: str | None = None,
+    ) -> dict[str, Any]:
+        """Create or update a resource.
+
+        Create the resource with this external reference, or update its time zone if the tenant
+        already has it. Repeating the call changes nothing more. visibility is shared (the
+        default: agents list and book it) or private (agents never see it), fixed at creation:
+        naming another for an existing resource answers 409 resource_visibility_conflict.
+        """
+        values: dict[str, Any] = {"external_ref": external_ref}
+        if timezone is not None:
+            values["timezone"] = timezone
+        if visibility is not None:
+            values["visibility"] = visibility
+        return self.call("slotlock_create_resource", values)
+
+    def get_free_busy(self, *, resource_ids: list[str], start: str, end: str) -> dict[str, Any]:
+        """Get free-busy.
+
+        Return privacy-minimized busy intervals and explicit coverage certainty.
+        """
+        values: dict[str, Any] = {"resource_ids": resource_ids, "start": start, "end": end}
+        return self.call("slotlock_get_free_busy", values)
+
+    def find_next_available(
+        self,
+        *,
+        resource_ids: list[str],
+        start: str,
+        end: str,
+        duration_minutes: int,
+    ) -> dict[str, Any]:
+        """Find next available interval.
+
+        Find the earliest certain interval that satisfies the requested duration (up to the
+        367-day search window, so a multi-month rental slot can be found).
+        """
+        values: dict[str, Any] = {
+            "resource_ids": resource_ids,
+            "start": start,
+            "end": end,
+            "duration_minutes": duration_minutes,
+        }
+        return self.call("slotlock_find_next_available", values)
+
+    def list_events(
+        self,
+        *,
+        resource_ids: list[str],
+        start: str,
+        end: str,
+        cursor: str | None = None,
+        limit: int | None = None,
+    ) -> dict[str, Any]:
+        """List resource events.
+
+        List bounded events intersecting a time window.
+        """
+        values: dict[str, Any] = {"resource_ids": resource_ids, "start": start, "end": end}
+        if cursor is not None:
+            values["cursor"] = cursor
+        if limit is not None:
+            values["limit"] = limit
+        return self.call("slotlock_list_events", values)
+
+    def create_event(
+        self,
+        *,
+        resource_id: str,
+        starts_at: str,
+        ends_at: str,
+        timezone: str,
+        idempotency_key: str,
+        title: str | None = None,
+        description: str | None = None,
+        location: str | None = None,
+        organizer: dict[str, Any] | None = None,
+        transparency: str | None = None,
+        status: str | None = None,
+        recurrence_rule: str | None = None,
+        attendees: list[dict[str, Any]] | None = None,
+        reminders: list[dict[str, Any]] | None = None,
+        recurrence_exceptions: list[dict[str, Any]] | None = None,
+    ) -> dict[str, Any]:
+        """Create resource event.
+
+        Create an event of up to 3,660 days (a booking, lease or long rental); opaque occurrences
+        use the database overlap arbiter.
+        """
+        values: dict[str, Any] = {
+            "resource_id": resource_id,
+            "starts_at": starts_at,
+            "ends_at": ends_at,
+            "timezone": timezone,
+            "idempotency_key": idempotency_key,
+        }
+        if title is not None:
+            values["title"] = title
+        if description is not None:
+            values["description"] = description
+        if location is not None:
+            values["location"] = location
+        if organizer is not None:
+            values["organizer"] = organizer
+        if transparency is not None:
+            values["transparency"] = transparency
+        if status is not None:
+            values["status"] = status
+        if recurrence_rule is not None:
+            values["recurrence_rule"] = recurrence_rule
+        if attendees is not None:
+            values["attendees"] = attendees
+        if reminders is not None:
+            values["reminders"] = reminders
+        if recurrence_exceptions is not None:
+            values["recurrence_exceptions"] = recurrence_exceptions
+        return self.call("slotlock_create_event", values)
+
+    def get_event(self, event_id: str) -> dict[str, Any]:
+        """Get resource event.
+
+        Read one tenant-scoped event by stable identifier.
+        """
+        values: dict[str, Any] = {"event_id": event_id}
+        return self.call("slotlock_get_event", values)
+
+    def update_event(
+        self,
+        event_id: str,
+        *,
+        expected_revision: int,
+        idempotency_key: str,
+        resource_id: str | None = None,
+        starts_at: str | None = None,
+        ends_at: str | None = None,
+        timezone: str | None = None,
+        title: str | None | Unset = UNSET,
+        description: str | None | Unset = UNSET,
+        location: str | None | Unset = UNSET,
+        organizer: dict[str, Any] | None | Unset = UNSET,
+        attendees: list[dict[str, Any]] | None = None,
+        reminders: list[dict[str, Any]] | None = None,
+        transparency: str | None = None,
+        status: str | None = None,
+        recurrence_rule: str | None | Unset = UNSET,
+        recurrence_exceptions: list[dict[str, Any]] | None = None,
+        expected_resource_id: str | None = None,
+    ) -> dict[str, Any]:
+        """Update resource event.
+
+        Apply an expected-revision event patch and rematerialize occupancy atomically. With
+        expected_resource_id, the resource you read the event on, an event since moved elsewhere
+        is not found.
+        """
+        values: dict[str, Any] = {
+            "event_id": event_id,
+            "expected_revision": expected_revision,
+            "idempotency_key": idempotency_key,
+        }
+        if resource_id is not None:
+            values["resource_id"] = resource_id
+        if starts_at is not None:
+            values["starts_at"] = starts_at
+        if ends_at is not None:
+            values["ends_at"] = ends_at
+        if timezone is not None:
+            values["timezone"] = timezone
+        if not isinstance(title, Unset):
+            values["title"] = title
+        if not isinstance(description, Unset):
+            values["description"] = description
+        if not isinstance(location, Unset):
+            values["location"] = location
+        if not isinstance(organizer, Unset):
+            values["organizer"] = organizer
+        if attendees is not None:
+            values["attendees"] = attendees
+        if reminders is not None:
+            values["reminders"] = reminders
+        if transparency is not None:
+            values["transparency"] = transparency
+        if status is not None:
+            values["status"] = status
+        if not isinstance(recurrence_rule, Unset):
+            values["recurrence_rule"] = recurrence_rule
+        if recurrence_exceptions is not None:
+            values["recurrence_exceptions"] = recurrence_exceptions
+        if expected_resource_id is not None:
+            values["expected_resource_id"] = expected_resource_id
+        return self.call("slotlock_update_event", values)
+
+    def delete_event(
+        self,
+        event_id: str,
+        *,
+        expected_revision: int,
+        idempotency_key: str,
+    ) -> dict[str, Any]:
+        """Delete resource event.
+
+        Tombstone an event at an expected revision so stale sync cannot resurrect it.
+        """
+        values: dict[str, Any] = {
+            "event_id": event_id,
+            "expected_revision": expected_revision,
+            "idempotency_key": idempotency_key,
+        }
+        return self.call("slotlock_delete_event", values)
+
+    def get_resource(self, resource_id: str) -> dict[str, Any]:
+        """Get a resource.
+
+        One resource of the tenant, archived or not, with its own weekly bookable hours and its
+        visibility.
+        """
+        values: dict[str, Any] = {"resource_id": resource_id}
+        return self.call("slotlock_get_resource", values)
+
+    def delete_resource(self, resource_id: str) -> dict[str, Any]:
+        """Delete a resource.
+
+        Delete a resource with its history (past bookings, coverage, cancelled events), freeing
+        its place under the tenant's resource limit. Refused with 409 resource_in_use while a
+        booking on it has not ended, a hold on it is live, or a calendar event is on it: cancel or
+        move those first. deleted is false when the tenant has no such resource, deleted already,
+        say.
+        """
+        values: dict[str, Any] = {"resource_id": resource_id}
+        return self.call("slotlock_delete_resource", values)
+
+    def archive_resource(self, resource_id: str) -> dict[str, Any]:
+        """Archive a resource.
+
+        Take a resource out of use: no list shows it and it takes no new booking, hold or event
+        (409 resource_archived), while what is on it stays and can still be cancelled or released.
+        Archiving it again keeps the first time.
+        """
+        values: dict[str, Any] = {"resource_id": resource_id}
+        return self.call("slotlock_archive_resource", values)
+
+    def restore_resource(self, resource_id: str) -> dict[str, Any]:
+        """Restore a resource.
+
+        Put an archived resource back in use. Restoring one in use changes nothing.
+        """
+        values: dict[str, Any] = {"resource_id": resource_id}
+        return self.call("slotlock_restore_resource", values)
+
+    def list_busy(self, resource_id: str, *, start: str, end: str) -> dict[str, Any]:
+        """List a resource's busy time.
+
+        The time a resource of the tenant, private ones included, is occupied in a window of at
+        most 367 days, by start: bookings with their turnaround, live holds, and calendar events.
+        Adjacent intervals are not merged. More than 10,000 answers 400 calendar_work_limit:
+        narrow the window. Free/busy with coverage, for the resources agents see, is
+        slotlock_get_free_busy.
+        """
+        values: dict[str, Any] = {"resource_id": resource_id, "start": start, "end": end}
+        return self.call("slotlock_list_busy", values)
+
+    def set_resource_availability(
+        self,
+        resource_id: str,
+        *,
+        rules: list[dict[str, Any]] | None,
+    ) -> dict[str, Any]:
+        """Set a resource's bookable hours.
+
+        Give one resource its own weekly bookable hours. `null` makes it use the server's default;
+        `[]` makes it never bookable. Each rule is weekly with BYDAY, in the resource's time zone:
+        start_minutes after midnight, lasting duration_minutes.
+        """
+        values: dict[str, Any] = {"resource_id": resource_id, "rules": rules}
+        return self.call("slotlock_set_resource_availability", values)
+
+    def set_tenant_availability(self, *, rules: list[dict[str, Any]] | None) -> dict[str, Any]:
+        """Set every resource's bookable hours.
+
+        Set the weekly bookable hours of every resource the tenant has, as
+        slotlock_set_resource_availability does for one. `null` makes them all use the server's
+        default. Returns how many resources changed.
+        """
+        values: dict[str, Any] = {"rules": rules}
+        return self.call("slotlock_set_tenant_availability", values)
+
+    def acquire_hold(
+        self,
+        *,
+        resource_id: str,
+        start: str,
+        end: str,
+        ttl_seconds: int,
+        source: str | None = None,
+        idempotency_key: str | None = None,
+        buffer_after_minutes: int | None = None,
+    ) -> dict[str, Any]:
+        """Hold time.
+
+        Occupy a window without booking it, for example while a customer pays. The hold blocks
+        every other booking until it expires (the database clock, ttl_seconds from now), is
+        confirmed, or is released. buffer_after_minutes keeps the time after it busy as well, and
+        a confirmed hold keeps it. A taken window answers 409 overlap. With an idempotency key
+        (the Idempotency-Key header or idempotency_key), a retry answers the hold the first
+        request made, until that hold would have expired, is released or is confirmed; the same
+        key with another request is 409 idempotency_conflict.
+
+        Args:
+            idempotency_key: A retry identity, also accepted as the Idempotency-Key header: the
+            same key with the same request answers what the first did; with another request, 409
+            idempotency_conflict.
+        """
+        values: dict[str, Any] = {
+            "resource_id": resource_id,
+            "start": start,
+            "end": end,
+            "ttl_seconds": ttl_seconds,
+        }
+        if source is not None:
+            values["source"] = source
+        if idempotency_key is not None:
+            values["idempotency_key"] = idempotency_key
+        if buffer_after_minutes is not None:
+            values["buffer_after_minutes"] = buffer_after_minutes
+        return self.call("slotlock_acquire_hold", values)
+
+    def get_hold(self, hold_id: str) -> dict[str, Any]:
+        """Get a hold.
+
+        One of the tenant's live holds. An expired, confirmed, released or unknown one answers 404
+        hold_not_found; a confirmed one is a reservation whose reference is the hold's id.
+        """
+        values: dict[str, Any] = {"hold_id": hold_id}
+        return self.call("slotlock_get_hold", values)
+
+    def release_hold(self, hold_id: str) -> dict[str, Any]:
+        """Release a hold.
+
+        Free a held window. released is false when the hold was already gone: expired, confirmed
+        or released.
+        """
+        values: dict[str, Any] = {"hold_id": hold_id}
+        return self.call("slotlock_release_hold", values)
+
+    def list_holds(
+        self,
+        resource_id: str,
+        *,
+        limit: int | None = None,
+        cursor: str | None = None,
+    ) -> dict[str, Any]:
+        """List a resource's holds.
+
+        The live holds on one of the tenant's resources, by start then id, a page at a time: pass
+        next_cursor as cursor for the next page, until it is null.
+        """
+        values: dict[str, Any] = {"resource_id": resource_id}
+        if limit is not None:
+            values["limit"] = limit
+        if cursor is not None:
+            values["cursor"] = cursor
+        return self.call("slotlock_list_holds", values)
+
+    def confirm_hold(self, hold_id: str) -> dict[str, Any]:
+        """Confirm a hold.
+
+        Turn an unexpired hold into a confirmed reservation, whose reference is the hold's id at
+        revision 1: move or cancel it with the reservation routes by that reference (DELETE
+        /v1/reservations/{hold_id}?revision=2 cancels it). Confirming it again answers the same
+        reservation, so a retry is safe. An expired hold answers 409 hold_expired; a released or
+        unknown one, 404 hold_not_found.
+        """
+        values: dict[str, Any] = {"hold_id": hold_id}
+        return self.call("slotlock_confirm_hold", values)
+
+    def get_reservation(self, reservation_ref: str) -> dict[str, Any]:
+        """Get a reservation.
+
+        The tenant's booking with this reference as it now is, at its current revision: move it at
+        that revision plus 1. A cancelled or unknown reference, or a calendar event's time,
+        answers 404 reservation_not_found.
+        """
+        values: dict[str, Any] = {"reservation_ref": reservation_ref}
+        return self.call("slotlock_get_reservation", values)
+
+    def put_reservation(
+        self,
+        reservation_ref: str,
+        *,
+        resource_id: str,
+        start: str,
+        end: str,
+        revision: int,
+        buffer_after_minutes: int | None = None,
+        source: str | None = None,
+    ) -> dict[str, Any]:
+        """Book or move a reservation.
+
+        Book the reservation with this reference (revision 1), or move it (the next revision: the
+        current one plus 1). Sending the same reservation at its current revision again changes
+        nothing (replayed: true). A taken window answers 409 overlap and leaves a moved
+        reservation where it was. buffer_after_minutes keeps the time after it busy as well.
+        """
+        values: dict[str, Any] = {
+            "reservation_ref": reservation_ref,
+            "resource_id": resource_id,
+            "start": start,
+            "end": end,
+            "revision": revision,
+        }
+        if buffer_after_minutes is not None:
+            values["buffer_after_minutes"] = buffer_after_minutes
+        if source is not None:
+            values["source"] = source
+        return self.call("slotlock_put_reservation", values)
+
+    def cancel_reservation(self, reservation_ref: str, *, revision: int) -> dict[str, Any]:
+        """Cancel a reservation.
+
+        Cancel the reservation with this reference at the next revision (the current one plus 1).
+        Cancelling leaves a tombstone, so a delayed booking cannot bring it back; repeating the
+        cancel answers cancelled: false. Use a new reference for a new reservation.
+        """
+        values: dict[str, Any] = {"reservation_ref": reservation_ref, "revision": revision}
+        return self.call("slotlock_cancel_reservation", values)
+
+    def list_reservations(
+        self,
+        resource_id: str,
+        *,
+        start: str,
+        end: str,
+        limit: int | None = None,
+        cursor: str | None = None,
+    ) -> dict[str, Any]:
+        """List a resource's reservations.
+
+        The tenant's bookings on one resource whose time, turnaround included, meets a window of
+        at most 367 days, by start then id, a page at a time: pass next_cursor as cursor for the
+        next page, until it is null. Calendar events are not bookings; slotlock_list_tenant_events
+        lists them.
+        """
+        values: dict[str, Any] = {"resource_id": resource_id, "start": start, "end": end}
+        if limit is not None:
+            values["limit"] = limit
+        if cursor is not None:
+            values["cursor"] = cursor
+        return self.call("slotlock_list_reservations", values)
+
+    def record_coverage(
+        self,
+        resource_id: str,
+        source: str,
+        *,
+        start: str,
+        end: str,
+        revision: int,
+    ) -> dict[str, Any]:
+        """Record calendar coverage.
+
+        Record that the events of an external calendar (source) are complete for a window of a
+        resource, at that source's revision. Free/busy calls time unproven, not free, until every
+        source a resource requires covers it. Revisions only go forward; repeating one changes
+        nothing.
+        """
+        values: dict[str, Any] = {
+            "resource_id": resource_id,
+            "source": source,
+            "start": start,
+            "end": end,
+            "revision": revision,
+        }
+        return self.call("slotlock_record_coverage", values)
+
+    def list_tenant_events(
+        self,
+        *,
+        resource_id: str,
+        start: str,
+        end: str,
+        limit: int | None = None,
+        cursor: str | None = None,
+    ) -> dict[str, Any]:
+        """List a resource's events, every key's.
+
+        The calendar events on one of the tenant's resources with an occurrence in a window of at
+        most 367 days, whichever key wrote them (a revoked one's included), by start then id, a
+        page at a time: pass next_cursor as cursor for the next page, until it is null.
+        """
+        values: dict[str, Any] = {"resource_id": resource_id, "start": start, "end": end}
+        if limit is not None:
+            values["limit"] = limit
+        if cursor is not None:
+            values["cursor"] = cursor
+        return self.call("slotlock_list_tenant_events", values)
+
+    def get_tenant_event(self, event_id: str) -> dict[str, Any]:
+        """Get any event of the tenant.
+
+        One of the tenant's events by its id (the id slotlock_list_tenant_events gives), whichever
+        key wrote it. A cancelled or unknown one answers 404 event_not_found.
+        """
+        values: dict[str, Any] = {"event_id": event_id}
+        return self.call("slotlock_get_tenant_event", values)
+
+    def cancel_tenant_event(
+        self,
+        event_id: str,
+        *,
+        expected_revision: int,
+        idempotency_key: str,
+        expected_resource_id: str | None = None,
+    ) -> dict[str, Any]:
+        """Cancel any event of the tenant.
+
+        Cancel one of the tenant's events by its id, whichever key wrote it (a revoked key's
+        included, without charging its quota), at the revision you last read (expected_revision).
+        Its owner cannot create it again. With expected_resource_id, an event since moved to
+        another resource answers 404 event_not_found. Needs an idempotency key (the
+        Idempotency-Key header or idempotency_key): a retry with it answers the first cancellation
+        (replayed: true).
+
+        Args:
+            idempotency_key: A retry identity, also accepted as the Idempotency-Key header: the
+            same key with the same request answers what the first did; with another request, 409
+            idempotency_conflict.
+        """
+        values: dict[str, Any] = {
+            "event_id": event_id,
+            "expected_revision": expected_revision,
+            "idempotency_key": idempotency_key,
+        }
+        if expected_resource_id is not None:
+            values["expected_resource_id"] = expected_resource_id
+        return self.call("slotlock_cancel_tenant_event", values)
+
+    def get_tenant(self) -> dict[str, Any]:
+        """Get the tenant.
+
+        The key's tenant: its reference, and whether it is suspended. A suspended tenant may read
+        and writes nothing (403 tenant_suspended); only the server's operator suspends a tenant or
+        lifts a suspension (slotlock tenant suspend).
+        """
+        values: dict[str, Any] = {}
+        return self.call("slotlock_get_tenant", values)
+
+    def erase_tenant(self, *, confirm_tenant_ref: str) -> dict[str, Any]:
+        """Erase the tenant.
+
+        Delete everything the key's tenant has, at once and for good: resources, holds, bookings,
+        events, coverage and every API key, this one included. confirm_tenant_ref must be the
+        tenant's reference (slotlock_get_tenant), or it answers 400 invalid_confirmation. Off
+        unless the server allows it (403 tenant_erasure_disabled; slotlock serve does not: its
+        operator runs slotlock tenant erase). A suspended tenant cannot erase itself (403
+        tenant_suspended). Erasing again deletes nothing.
+        """
+        values: dict[str, Any] = {"confirm_tenant_ref": confirm_tenant_ref}
+        return self.call("slotlock_erase_tenant", values)
+
+    def run_maintenance(self) -> dict[str, Any]:
+        """Run maintenance.
+
+        Extend recurring events to the rolling horizon and prune what the retention window no
+        longer needs, for the caller's tenant. Run it at least daily (slotlock serve does). capped
+        is true when there was more than one call does: call again.
+        """
+        values: dict[str, Any] = {}
+        return self.call("slotlock_run_maintenance", values)

slotlock/_transport.py

@@ -0,0 +1,238 @@
+"""The HTTP side of the Slotlock client: the key, JSON, and errors. Standard library only."""
+
+from __future__ import annotations
+
+import json
+import re
+import time
+import urllib.error
+import urllib.parse
+import urllib.request
+from collections.abc import Mapping
+from datetime import datetime, timezone
+from typing import Any, NamedTuple
+
+__version__ = "0.3.0"
+
+_LOOPBACK = {"localhost", "127.0.0.1", "::1"}
+
+#: The longest wait a Retry-After is read as: one day.
+_MAX_RETRY_AFTER = 86400.0
+_SECONDS = re.compile(r"[0-9]+(?:\.[0-9]+)?")
+_MONTHS = ("Jan", "Feb", "Mar", "Apr", "May", "Jun", "Jul", "Aug", "Sep", "Oct", "Nov", "Dec")
+_HTTP_DATE = re.compile(
+    r"(?:Mon|Tue|Wed|Thu|Fri|Sat|Sun), ([0-9]{2}) (" + "|".join(_MONTHS) + r") ([0-9]{4}) "
+    r"([0-9]{2}):([0-9]{2}):([0-9]{2}) GMT"
+)
+
+
+class Unset:
+    """The default of an optional argument that may be null: leave it out of the request."""
+
+    _instance: Unset | None = None
+
+    def __new__(cls) -> Unset:
+        if cls._instance is None:
+            cls._instance = super().__new__(cls)
+        return cls._instance
+
+    def __repr__(self) -> str:
+        return "UNSET"
+
+    def __bool__(self) -> bool:
+        return False
+
+
+UNSET = Unset()
+
+
+class Operation(NamedTuple):
+    name: str
+    method: str
+    path: str
+    path_params: tuple[str, ...]
+    query: tuple[str, ...]
+
+
+class SlotlockError(Exception):
+    """The server refused a call: `status` is the HTTP status, `code` says why.
+
+    `code` is the server's error code (`overlap`, `forbidden`, `confirmation_required`, ...), or
+    `http_<status>` when the response carried none; a redirect is one too (`http_302`), never
+    followed. `retry_after` is the seconds a 429 or 503 asks for, when its Retry-After says, in
+    seconds or as a date (at most a day).
+    """
+
+    def __init__(self, status: int, code: str, retry_after: float | None = None) -> None:
+        super().__init__(f"Slotlock answered {status} {code}")
+        self.status = status
+        self.code = code
+        self.retry_after = retry_after
+
+
+class _NoRedirect(urllib.request.HTTPRedirectHandler):
+    """Follows no redirect: the 3xx is raised as it came, and the key goes nowhere else."""
+
+    def redirect_request(self, *args: Any) -> None:
+        return None
+
+
+class Transport:
+    """Calls a Slotlock server's REST API with an API key.
+
+    Args:
+        base_url: The server's public URL (SLOTLOCK_PUBLIC_URL), such as
+            `https://calendar.example.com`.
+        api_key: A Slotlock API key (`slk_...`) or the server token. The application API needs a
+            key with the admin scope.
+        timeout: Seconds a call may take, its response body included.
+        allow_insecure: Send the key over plain HTTP to a host other than this machine. Never
+            needed for `http://localhost`, which is reached without the environment's proxy.
+        user_agent: Sent as User-Agent; `slotlock-python/<version>` unless given.
+    """
+
+    def __init__(
+        self,
+        base_url: str,
+        api_key: str,
+        *,
+        timeout: float = 30.0,
+        allow_insecure: bool = False,
+        user_agent: str | None = None,
+    ) -> None:
+        parsed = urllib.parse.urlsplit(base_url)
+        if parsed.scheme not in ("http", "https") or not parsed.hostname:
+            raise ValueError("base_url must be an http:// or https:// URL")
+        if parsed.query or parsed.fragment:
+            raise ValueError("base_url must not have a query or a fragment")
+        if parsed.scheme == "http" and parsed.hostname not in _LOOPBACK and not allow_insecure:
+            raise ValueError(
+                "base_url is plain HTTP to another host, which would send the key unencrypted; "
+                "use https://, or pass allow_insecure=True"
+            )
+        if not api_key or any(ord(c) < 0x21 or ord(c) > 0x7E for c in api_key):
+            raise ValueError("api_key must be a Slotlock API key or the server token")
+        self._base_url = base_url.rstrip("/")
+        self._api_key = api_key
+        self._timeout = timeout
+        self._user_agent = user_agent or f"slotlock-python/{__version__}"
+        # This machine is reached directly: a proxy from the environment would carry the key off it.
+        direct = [urllib.request.ProxyHandler({})] if parsed.hostname in _LOOPBACK else []
+        self._opener = urllib.request.build_opener(_NoRedirect(), *direct)
+
+    def __repr__(self) -> str:
+        # Never the key.
+        return f"{type(self).__name__}({self._base_url!r})"
+
+    def call(self, operation: str, values: Mapping[str, Any] | None = None) -> dict[str, Any]:
+        """Run an operation by name (`slotlock_...`) with its arguments, path parameters included.
+
+        Raises:
+            SlotlockError: The server refused the call.
+            ValueError: No such operation, or a path parameter is missing.
+        """
+        from ._operations import OPERATIONS
+
+        spec = OPERATIONS.get(operation)
+        if spec is None:
+            raise ValueError(f"no Slotlock operation named {operation!r}")
+        arguments = dict(values or {})
+        path = spec.path
+        for name in spec.path_params:
+            value = arguments.pop(name, None)
+            # The server resolves `.` and `..` as path segments, which would name another route.
+            if not isinstance(value, str) or value in ("", ".", ".."):
+                raise ValueError(f"{operation} needs {name}, a non-empty string other than . and ..")
+            path = path.replace("{" + name + "}", urllib.parse.quote(value, safe=""))
+        body: bytes | None = None
+        if spec.method in ("GET", "DELETE"):
+            unknown = [name for name in arguments if name not in spec.query]
+            if unknown:
+                raise ValueError(f"{operation} has no argument {unknown[0]}")
+            pairs: list[tuple[str, str]] = []
+            for name, value in arguments.items():
+                for item in value if isinstance(value, (list, tuple)) else [value]:
+                    pairs.append((name, _query_value(item)))
+            if pairs:
+                path = f"{path}?{urllib.parse.urlencode(pairs)}"
+        else:
+            body = json.dumps(arguments, ensure_ascii=False, allow_nan=False).encode("utf-8")
+        return self._send(spec.method, path, body)
+
+    def _send(self, method: str, path: str, body: bytes | None) -> dict[str, Any]:
+        headers = {
+            "Authorization": f"Bearer {self._api_key}",
+            "Accept": "application/json",
+            "User-Agent": self._user_agent,
+        }
+        if body is not None:
+            headers["Content-Type"] = "application/json"
+        request = urllib.request.Request(
+            f"{self._base_url}{path}", data=body, method=method, headers=headers
+        )
+        deadline = time.monotonic() + self._timeout
+        try:
+            with self._opener.open(request, timeout=self._timeout) as response:
+                payload = _read(response, deadline)
+        except urllib.error.HTTPError as error:
+            with error:
+                body = _read(error, deadline)
+            raise _refusal(error.code, body, error.headers.get("Retry-After")) from None
+        decoded = json.loads(payload) if payload else {}
+        if not isinstance(decoded, dict):
+            raise SlotlockError(200, "invalid_response")
+        return decoded
+
+
+def _read(response: Any, deadline: float) -> bytes:
+    """The body, as long as it arrives before `deadline`."""
+    chunks: list[bytes] = []
+    while True:
+        if time.monotonic() > deadline:
+            raise TimeoutError("Slotlock's answer did not arrive in time")
+        chunk = response.read1(65536)
+        if not chunk:
+            return b"".join(chunks)
+        chunks.append(chunk)
+
+
+def _retry_after(value: str | None) -> float | None:
+    """Retry-After in seconds or as an HTTP date, at most a day; anything else is no wait."""
+    if value is None:
+        return None
+    value = value.strip()
+    if _SECONDS.fullmatch(value):
+        return min(float(value), _MAX_RETRY_AFTER)
+    date = _HTTP_DATE.fullmatch(value)
+    if date is None:
+        return None
+    day, month, year, hour, minute, second = date.groups()
+    try:
+        when = datetime(
+            int(year), _MONTHS.index(month) + 1, int(day), int(hour), int(minute), int(second),
+            tzinfo=timezone.utc,
+        )
+    except ValueError:
+        return None
+    return max(0.0, min(when.timestamp() - time.time(), _MAX_RETRY_AFTER))
+
+
+def _query_value(value: Any) -> str:
+    if isinstance(value, bool):
+        return "true" if value else "false"
+    if isinstance(value, (int, float, str)):
+        return str(value)
+    raise TypeError(f"a query argument is a string, number or boolean, not {type(value).__name__}")
+
+
+def _refusal(status: int, payload: bytes, retry_after: str | None) -> SlotlockError:
+    code = f"http_{status}"
+    try:
+        decoded = json.loads(payload)
+        if isinstance(decoded, dict) and isinstance(decoded.get("error"), dict):
+            found = decoded["error"].get("code")
+            if isinstance(found, str) and found:
+                code = found
+    except ValueError:
+        pass
+    return SlotlockError(status, code, _retry_after(retry_after))

slotlock-0.3.0.dist-info/METADATA

@@ -0,0 +1,48 @@
+Metadata-Version: 2.4
+Name: slotlock
+Version: 0.3.0
+Summary: A client for Slotlock's REST API: calendars AI agents cannot double-book.
+Project-URL: Homepage, https://slotlock.pylota.io
+Project-URL: Source, https://github.com/PILOTAAI/slotlock/tree/main/clients/python
+License-Expression: Apache-2.0
+Classifier: Programming Language :: Python :: 3
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+# Slotlock for Python
+
+A client for [Slotlock](https://slotlock.pylota.io)'s REST API: the agent tools and the application
+API, one method per operation. Python 3.10+, standard library only.
+
+```sh
+pip install "git+https://github.com/PILOTAAI/slotlock.git#subdirectory=clients/python"
+```
+
+```python
+from slotlock import Client, SlotlockError
+
+slotlock = Client("https://calendar.example.com", api_key)  # a key with the admin scope
+van = slotlock.create_resource(external_ref="vehicle-42", timezone="Europe/London")["resource"]
+
+hold = slotlock.acquire_hold(
+    resource_id=van["id"], start="2027-03-29T09:00:00Z", end="2027-03-29T10:00:00Z", ttl_seconds=600
+)["hold"]
+try:
+    slotlock.acquire_hold(
+        resource_id=van["id"], start="2027-03-29T09:30:00Z", end="2027-03-29T10:30:00Z", ttl_seconds=600
+    )
+except SlotlockError as error:
+    assert (error.status, error.code) == (409, "overlap")
+
+reservation = slotlock.confirm_hold(hold["id"])["reservation"]
+```
+
+- Every method returns the response body as a `dict`; `client.call("slotlock_...", {...})` runs an
+  operation by name.
+- A refusal raises `SlotlockError` with `status`, `code` and `retry_after`.
+- `update_event(..., description=None)` clears the description; leaving it out keeps it.
+- `Client(url, key, timeout=30.0, allow_insecure=False, user_agent=None)`. Plain HTTP is refused
+  except to `localhost`.
+
+The [clients overview](../README.md) covers keys, errors and testing.

slotlock-0.3.0.dist-info/RECORD

@@ -0,0 +1,7 @@
+slotlock/__init__.py,sha256=UItAwMuulBPV_-ZIO6XzhVwW-3S0by_122gY-KjFPrU,608
+slotlock/_operations.py,sha256=o_5o187YYaUTNS37tgjQcf5Lu4xoOtNOy3icB1e9r7c,30163
+slotlock/_transport.py,sha256=wAHxkGloxcLBWA1ERCVRuAKTH9l6hOf1CzgQ9j7xhzI,9256
+slotlock/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+slotlock-0.3.0.dist-info/METADATA,sha256=8YsZfvmokwgC8Vv5hdeSkRJ9kQ61w3-3wPgCohUlIeo,1890
+slotlock-0.3.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+slotlock-0.3.0.dist-info/RECORD,,

slotlock-0.3.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.27.0
+Root-Is-Purelib: true
+Tag: py3-none-any