cloudshift-library-v2 1.1.1

A core logic engine for employee scheduling and shift management.

Shiftwise 🕒

Shiftwise is a robust, lightweight Python library designed to handle the core logic of employee scheduling, shift management, and leave coordination. It provides a clean, model-driven approach to validatng business rules, preventing scheduling conflicts, and managing complex shift swaps.

Developed as the engine behind the Cloud Shift platform, shiftwise is now available as a standalone package for any workforce management application.

🚀 Features

• Model-Driven Architecture: Clean dataclass models for User, Shift, Leave, and SwapRequest.
• Intelligent Validation:
  • Automated capacity checks for shifts.
  • Skill-based assignment verification.
  • Overlap and conflict detection for shifts and leaves.
• Manager Classes:
  • ShiftManager: Manage employee assignments and removals.
  • LeaveManager: Workflow for requesting, approving, and rejecting leave.
  • SwapManager: Peer-to-peer shift swap logic with safety checks.
• Custom Exceptions: Descriptive errors like ShiftFullError, ShiftConflictError, and LeaveConflictError.

📦 Installation

pip install shiftwise

🛠️ Quick Start

1. Define your Models

from datetime import datetime
from shiftwise import Shift, User, Role

# Create a shift
night_shift = Shift(
    shift_id="S123",
    title="Night Watch",
    start_time=datetime(2023, 10, 20, 22, 0),
    end_time=datetime(2023, 10, 21, 6, 0),
    max_capacity=5,
    required_skills=["FirstAid"]
)

# Create an employee
employee = User(
    user_id="E001",
    email="[e-mail]",
    first_name="Alice",
    last_name="Smith",
    role=Role.EMPLOYEE,
    skills=["FirstAid"]
)

2. Manage Assignments

from shiftwise import ShiftManager

manager = ShiftManager()

# Assign employee to shift (validates capacity, skills, and conflicts)
try:
    manager.assign_employee(
        shift=night_shift,
        employee_id=employee.user_id,
        employee_skills=employee.skills,
        current_employee_shifts=[],
        current_employee_leaves=[]
    )
    print(f"Successfully assigned {employee.first_name} to {night_shift.title}")
except Exception as e:
    print(f"Assignment failed: {e}")

3. Handle Leave Requests

from shiftwise import LeaveManager, Leave, LeaveType
from datetime import date

leave_mgr = LeaveManager()
requested_leave = Leave(
    leave_id="L1",
    employee_id="E001",
    leave_type=LeaveType.ANNUAL,
    start_date=date(2023, 12, 24),
    end_date=date(2023, 12, 26)
)

# Request leave (fails if overlaps with existing requests)
new_request = leave_mgr.request_leave("E001", [], requested_leave)

⚖️ License

Distributed under the MIT License. See LICENSE for more information.

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.