Make Your Complex Scheduling Simple with Timeboard, a Python Library

If you‘ve ever had to deal with complex scheduling needs in your Python applications, you know how challenging it can be to model things like business days, employee shifts, recurring appointments, and other calendar-based events. Many common Python libraries like Pandas have some support for calendars and datetime manipulation, but quickly fall short when it comes to more advanced scenarios.

That‘s where timeboard comes in. Timeboard is a powerful and flexible Python library that allows you to easily create schedules of work periods and perform all sorts of useful calendar calculations over them. With timeboard, you can build anything from a simple Monday-Friday business day calendar to complex shift schedules that incorporate custom working hours, holidays, days off, and more.

What is Timeboard?

At its core, timeboard provides a set of tools for constructing timeboards, which are collections of one or more work schedules built on a common timeline. The basic workflow looks like this:

1. Define a frame which sets the overall start, end, and granularity of your calendar
2. Establish the rules for how the frame will be divided into individual units of work called workshifts
3. Create one or more schedules that specify which workshifts are considered "on-duty" vs "off-duty"

Once you have a timeboard set up, you can perform all sorts of date calculations and calendar queries that intelligently take into account only the "on-duty" periods from the schedule(s) you specify.

The true power of timeboard lies in its flexibility. The library provides constructs that let you model just about any kind of calendar logic you can imagine. Workshifts can be any length, from standard 8-hour days to multi-day periods or even a few minutes. You can have multiple schedules for the same timeboard, each one selecting different subsets of workshifts that are considered "on-duty". And custom selector functions allow you to categorize workshifts however you need based on any criteria.

Getting Started with Timeboard

The easiest way to get started with timeboard is to use one of the built-in calendar presets. For example, here‘s how you would set up a standard business day calendar for the United States:

import timeboard.calendars.US as US 

cal = US.Weekly8x5()

This creates a timeboard instance cal pre-configured with a Monday-Friday schedule that observes US federal holidays. With our calendar ready, let‘s look at some examples of what we can do.

To check if a given date is a business day (on-duty):

from datetime import date

day = date(2023, 5, 27)  # May 27, 2023 
shift = cal(day)
shift.is_on_duty()  # False (it‘s a Saturday)

Calling the timeboard (cal) with a date or datetime returns the corresponding workshift. We can then check its is_on_duty() status.

To count the number of business days in a month:

may2023 = cal(‘May 2023‘, period=‘M‘) 
may2023.count()  # 23

Passing a month string and period=‘M‘ gives us the interval of time covering that whole month. The count() method then returns the number of on-duty workshifts (business days) in that interval.

We can even do date math that skips over off-duty days:

start = date(2023, 5, 1) 
deadline = cal(start).rollforward(22)
print(deadline)  # 2023-06-01

Here rollforward(22) advances the calendar by 22 on-duty workshifts (business days), landing us on June 1st.

Building Custom Schedules

While the built-in calendars are great for simple use cases, the real flexibility of timeboard comes from the ability to build your own custom schedules from scratch.

Let‘s consider an example of a business that operates in two shifts per day: 8am-4pm and 4pm-12am. We want a timeboard that treats each of these shifts as distinct workshifts so that we can perform calculations over them like "How many evening shifts did this employee work in May?"

Here‘s how we could define that:

import timeboard as tb

am_shift = tb.Marker(‘D‘, at=[{‘hours‘:8}])
pm_shift = tb.Marker(‘D‘, at=[{‘hours‘:16}])
shifts = tb.Organizer(marker=[am_shift, pm_shift], 
                      structure=[‘AM‘,‘PM‘])

schedule = tb.Timeboard(base_unit_freq=‘H‘,
                        start=‘2023-01-01‘, 
                        end=‘2023-12-31‘,
                        layout=shifts)

Breaking this down:

• We define two Marker objects, am_shift and pm_shift, which specify the time of day when each shift begins
• The Organizer groups these markers together and assigns labels to each shift (‘AM‘ and ‘PM‘)
• Finally the Timeboard constructor creates the actual timeboard, specifying that the smallest unit of time resolution is one hour (base_unit_freq=‘H‘)

With this timeboard, we can now calculate things like:

may2023 = schedule(‘May 2023‘, period=‘M‘)

# Count evening shifts in May
pm_shifts = may2023.count(selector=lambda x: x==‘PM‘) 
print(pm_shifts)  # 31 

# Get total hours worked in May
may2023.worktime()  # 744

The count() method takes an optional selector argument, which is a function that filters the workshifts to include in the count. Here we use it to consider only workshifts labeled ‘PM‘.

By chaining together different selectors, markers, and organizers in creative ways, it‘s possible to model extremely complex schedules with timeboard. You can define custom working hours, rolling periods, sub-schedules for different groups, and almost any other calendar logic you can imagine.

Practical Use Cases for Timeboard

To further illustrate the potential of timeboard, here are a few real-world use cases where it could come in handy:

Employee Scheduling

Imagine you need to build an employee scheduling system for a business with multiple locations, each of which operates on a different schedule. Employees may work at any of the locations. With timeboard, you could:

• Define a distinct schedule for each location
• Calculate employee pay periods based on the number of shifts worked at each location
• Determine which employees are available to work at a given time/location
• Forecast staffing needs based on the "on-duty" periods across schedules

Appointment Booking

Consider a service-based business where customers book appointments for a specific day and time slot. Timeboard would allow you to:

• Set up a booking calendar with custom start/end times and days of week
• Determine a customer‘s next eligible appointment slot based on timeboard intervals
• Aggregate bookings to analyze trends and allocate resources
• Perform complex availability lookups across multiple schedules

Deadline/Task Management

For any application involving project management and tracking deadlines, timeboard provides a robust way to handle date-based calculations. You could:

• Build a team schedule that specifies working hours for a project
• Adjust delivery estimates based on "on-duty" workshift availability
• Optimize task allocation by matching employee schedules
• Roll up time tracking data based on custom calendar intervals

Learning More

This article has only scratched the surface of what‘s possible with timeboard. To dive deeper, consult the official documentation:

• Timeboard Documentation
• GitHub Repo
• PyPI Package

The docs include a wealth of additional examples and use cases, as well as a complete API reference detailing all of the classes, methods and options available in the library.

Timeboard is an incredibly powerful tool to add to your Python developer toolkit. It allows you to model complex real-world scheduling scenarios in a way that would be difficult or impossible with other standard Python libraries.

While there is certainly a learning curve to utilizing its full capabilities, the flexibility and extensibility of timeboard make it well worth the effort for anyone regularly dealing with non-trivial calendar or datetime operations in Python. So the next time you have a scheduling challenge to tackle, be sure to give timeboard a try!