Slotify Scheduling

Timezone-aware scheduling and appointment slot engine for Python.

Installation

pip install slotify-scheduling

Quick start

from slotify import SlotGenerator

generator = SlotGenerator(
    start="09:00",
    end="17:00",
    duration=30,
    timezone="Asia/Kolkata",
)

slots = generator.generate("2026-09-21", "2026-09-21")

for slot in slots:
    print(slot.start, "->", slot.end)

Why Slotify?

Scheduling becomes difficult when several rules interact:

working hours + breaks + holidays + overrides
+ timezones + DST + capacity + buffers
+ booking policies + reservations

Slotify keeps those rules in a scheduling layer while your application remains responsible for users, authentication, payments, notifications, databases, and UI.

Common use cases

• Doctor, therapist, consultant, salon, or clinic appointments
• Meeting and interview scheduling
• Classroom and group sessions
• Rooms, equipment, staff, and other resource booking
• Availability APIs in Django, FastAPI, Flask, or other Python applications

Why use Slotify?

Scheduling logic becomes complicated quickly when a system needs recurring availability, breaks, holidays, timezone conversion, daylight-saving transitions, booking limits, capacity, and conflicts.

Slotify focuses on that scheduling layer so your application can keep ownership of users, authentication, payments, notifications, and your database.

Good fit

• Appointment and booking APIs
• Django / Django REST Framework backends
• Doctor, therapist, consultant, and coach availability
• Classes, meetings, interviews, rooms, and shared resources
• Applications that need explicit timezone and DST behavior

Not a full booking platform

Slotify is a Python library, not a hosted booking service or complete frontend. You bring your application's users, database, authentication, payments, notifications, and UI.

Quick links

• Documentation — guides, Django integration, recipes, and API reference
• PyPI — install the package
• Examples — runnable starting points
• Issues — bugs and feature requests
• Roadmap — current project direction

Features

Weekly schedules

from slotify import Schedule, SlotGenerator

schedule = Schedule(
    weekly={
        "monday": [("09:00", "17:00")],
        "tuesday": [("09:00", "17:00")],
        "wednesday": [("12:00", "20:00")],
        "thursday": [("09:00", "17:00")],
        "friday": [("09:00", "14:00")],
    }
)

generator = SlotGenerator(
    schedule=schedule,
    duration=30,
    timezone="Asia/Kolkata",
)

Date overrides and closures

schedule = Schedule(
    weekly={"monday": [("09:00", "17:00")]},
    overrides={
        "2026-09-21": [("13:00", "18:00")],
        "2026-09-28": [],
    },
    closed_dates=["2026-10-02"],
    annual_closed_dates=["12-25", "01-01"],
)

An empty override closes that date.

Breaks and split windows

generator = SlotGenerator(
    windows=[
        ("09:00", "13:00"),
        ("14:00", "18:00"),
    ],
    breaks=[("11:00", "11:30")],
    duration=30,
    timezone="Asia/Kolkata",
)

Timezones and DST

generator = SlotGenerator(
    start="01:00",
    end="03:00",
    duration=30,
    timezone="America/New_York",
    dst_ambiguous="raise",
    dst_nonexistent="skip",
)

Ambiguous policies: raise, earlier, later, both.

Nonexistent-time policies: raise, skip.

See the Timezone & DST guide.

Upcoming availability

from datetime import datetime

slots = generator.upcoming(
    7,
    now=datetime.fromisoformat("2026-09-21T08:00:00+05:30"),
)

Passing now explicitly makes tests deterministic.

Recurring bookings, rescheduling and resources

Recurring appointment series, cancellation/rescheduling rules, multi-resource bookings, resource pools, availability queries, booking limits, named schedules, availability explanations, and iCalendar export are available in v0.3.0.

Booking and capacity

from slotify import AvailabilityEngine, SlotGenerator

generator = SlotGenerator(
    start="09:00",
    end="17:00",
    duration=30,
    timezone="Asia/Kolkata",
)

engine = AvailabilityEngine(
    generator,
    resource_id="doctor-123",
    capacity=1,
)

available = engine.available_slots("2026-09-21")

if available:
    booking = engine.reserve(available[0])
    print(booking.booking_id)

Cancel with engine.cancel(booking.booking_id).

For group sessions, use a larger capacity.

engine = AvailabilityEngine(
    generator,
    resource_id="class-1",
    capacity=10,
)

Booking buffers

engine = AvailabilityEngine(
    generator,
    buffer_before=10,
    buffer_after=15,
)

Useful for setup, cleanup, travel, or preparation time.

Booking policies

from datetime import timedelta
from slotify import BookingPolicy

policy = BookingPolicy(
    minimum_notice=timedelta(hours=2),
    maximum_horizon=timedelta(days=30),
)

Blocked periods:

from datetime import datetime
from slotify import BlockedPeriod, BookingPolicy

policy = BookingPolicy(
    blocked_periods=(
        BlockedPeriod(
            start=datetime.fromisoformat("2026-10-10T10:00:00+05:30"),
            end=datetime.fromisoformat("2026-10-10T14:00:00+05:30"),
            reason="Provider unavailable",
        ),
    ),
)

Django

Slotify can sit behind a Django or Django REST Framework endpoint.

pip install slotify-scheduling

Example service:

from slotify import AvailabilityEngine, SlotGenerator

def get_provider_engine(provider):
    generator = SlotGenerator(
        start=provider.work_start.strftime("%H:%M"),
        end=provider.work_end.strftime("%H:%M"),
        duration=provider.slot_duration,
        timezone=provider.timezone,
    )

    return AvailabilityEngine(
        generator,
        resource_id=str(provider.pk),
        capacity=1,
    )

Example view:

from django.http import JsonResponse
from .models import Provider
from .services import get_provider_engine

def available_slots(request, provider_id):
    provider = Provider.objects.get(pk=provider_id)
    engine = get_provider_engine(provider)

    slots = engine.available_slots("2026-09-21")

    return JsonResponse({
        "provider_id": provider.pk,
        "slots": [slot.to_dict() for slot in slots],
    })

Production note: the built-in InMemoryBookingStore is for tests and simple single-process applications. Multi-worker or distributed Django deployments should provide a database-backed BookingStore and enforce the required transaction/concurrency rules in the application's database layer.

Architecture

Your Django/FastAPI/etc. application
├── users and authentication
├── providers/resources
├── database
├── payments
├── notifications
└── frontend/API
          |
          v
       Slotify
       ├── Schedule
       ├── SlotGenerator
       ├── Slot
       ├── AvailabilityEngine
       ├── BookingPolicy
       └── Booking

Resource pools

A resource pool lets Slotify choose any available resource:

engine = AvailabilityEngine(
    generator,
    resource_pool=("doctor-1", "doctor-2", "doctor-3"),
)

booking = engine.reserve_first_available("2026-10-05")
print(booking.resource_id)

Availability queries

first = engine.next_available("2026-10-05", "2026-10-12")
slots = engine.available_between(start_datetime, end_datetime)
longer = engine.available_for_duration(90, "2026-10-05", "2026-10-12")

Availability explanations

result = engine.check_availability(slot)
print(result.available)
print(result.reason)
print(result.resource_id)

Booking limits

policy = BookingPolicy(
    max_bookings_per_day=3,
    max_bookings_per_week=10,
    max_upcoming_bookings=5,
    min_gap_between_bookings=timedelta(minutes=15),
)

Named availability schedules

engine = AvailabilityEngine.from_schedules(
    {"default": normal_generator, "evening": evening_generator},
    default_schedule="default",
)
slots = engine.available_slots("2026-10-05", schedule_name="evening")

More recurrence options

RecurrenceRule supports daily, weekly, monthly, and yearly recurrence, plus excluded dates.

RecurrenceRule(
    frequency="monthly",
    day_of_month=15,
    count=6,
)

Documentation

• Documentation home
• Getting Started
• Django / DRF
• Timezone & DST
• Recipes
• API Guide

Community

• Contributing
• Roadmap
• Support
• Security

Requirements

• Python 3.10+
• No third-party runtime dependency on Linux/macOS
• tzdata is installed automatically on Windows

Project status

Current version: 0.3.0

Slotify is currently in alpha. The API may evolve before 1.0.0, so pin the version in production applications and review the changelog when upgrading.

License

MIT License

Author

Kalash Gulati