Metadata-Version: 2.4
Name: slotify-scheduling
Version: 0.1.2
Summary: Timezone-aware Python scheduling and appointment slot engine for availability and booking systems.
Author: Kalash Gulati
License: MIT
Project-URL: Homepage, https://github.com/failedengineers/Slotify
Project-URL: Documentation, https://failedengineers.github.io/Slotify/
Project-URL: Repository, https://github.com/failedengineers/Slotify
Project-URL: Issues, https://github.com/failedengineers/Slotify/issues
Project-URL: Changelog, https://github.com/failedengineers/Slotify/blob/main/CHANGELOG.md
Keywords: scheduling,appointment scheduling,time slots,booking,availability,timezone,daylight saving,django
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: tzdata>=2022.1; platform_system == "Windows"
Dynamic: license-file

# Slotify Scheduling

**Timezone-aware scheduling and appointment slot engine for Python.**

Slotify helps you build appointment and booking systems without implementing scheduling logic from scratch.

**Use it for:** appointment slots, provider availability, resource booking, recurring schedules, breaks, holidays, booking rules, capacity, buffers, reservations, timezones, and daylight-saving transitions.

[![PyPI](https://img.shields.io/pypi/v/slotify-scheduling.svg)](https://pypi.org/project/slotify-scheduling/)
[![Python](https://img.shields.io/pypi/pyversions/slotify-scheduling.svg)](https://pypi.org/project/slotify-scheduling/)
[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)

## Installation

~~~bash
pip install slotify-scheduling
~~~

## Quick start

~~~python
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:

~~~text
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

## Features

### Weekly schedules

~~~python
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

~~~python
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

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

### Timezones and DST

~~~python
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 docs/timezones.md.

### Upcoming availability

~~~python
from datetime import datetime

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

Passing now explicitly makes tests deterministic.

### Booking and capacity

~~~python
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.

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

### Booking buffers

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

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

### Booking policies

~~~python
from datetime import timedelta
from slotify import BookingPolicy

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

Blocked periods:

~~~python
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.

~~~bash
pip install slotify-scheduling
~~~

Example service:

~~~python
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:

~~~python
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

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

## Documentation

- [Getting Started](https://failedengineers.github.io/Slotify/getting-started/)
- [Django Integration](https://failedengineers.github.io/Slotify/django/)
- [Timezone & DST](https://failedengineers.github.io/Slotify/timezones/)
- [Recipes](https://failedengineers.github.io/Slotify/recipes/)
- [API Guide](https://failedengineers.github.io/Slotify/api/)

## Requirements

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

## Project status

Current version: **0.1.2**

Slotify is actively developed and the API may evolve before 1.0.0.

## License

MIT License

## Author

Kalash Gulati
