Skip to content

time

time #

Candidate future time slots: the instants a session could be captured at.

times lays slots out at a fixed resolution across a span; times_of_day lays them on the requested hours of one day. Both start at start (now, by default) and drop nothing but the past.

times(resolution=timedelta(minutes=5), span=timedelta(hours=24), start=None) #

Generate candidate timestamps over a time span.

Parameters:

Name Type Description Default
resolution timedelta

Time between candidate slots. Defaults to 5 minutes.

timedelta(minutes=5)
span timedelta

Total time span to cover. Defaults to 24 hours.

timedelta(hours=24)
start datetime | None

Starting time. Defaults to now.

None

Returns:

Type Description
Array[datetime]

The instants from start up to (not including) start + span, one

Array[datetime]

every resolution.

Source code in capturegraph-recipes/capturegraph_recipes/scheduling/forecast/time.py
def times(
    resolution: timedelta = timedelta(minutes=5),
    span: timedelta = timedelta(hours=24),
    start: datetime | None = None,
) -> cg.Array[datetime]:
    """Generate candidate timestamps over a time span.

    Args:
        resolution: Time between candidate slots. Defaults to 5 minutes.
        span: Total time span to cover. Defaults to 24 hours.
        start: Starting time. Defaults to now.

    Returns:
        The instants from `start` up to (not including) `start + span`, one
        every `resolution`.
    """
    first = start if start is not None else datetime.now()
    count = math.ceil(span / resolution)
    return cg.Array(first + resolution * step for step in range(count))

times_of_day(hours, start=None) #

Generate candidate time slots at specific hours of the day.

Creates slots for today (the date of start) at the specified hours, returning only those strictly after start. Slots already in the past are dropped, so late in the day the result may be empty.

Parameters:

Name Type Description Default
hours list[int]

List of hours (0-23) to generate slots for.

required
start datetime | None

Starting time. Defaults to now.

None

Returns:

Type Description
Array[datetime]

The slots still ahead of start, sorted chronologically.

Example
times = cgr.scheduling.forecast.times_of_day(hours=[10, 12, 14, 16, 18, 20, 22])
chosen = reservations.reserve(user_id, among=times)
Source code in capturegraph-recipes/capturegraph_recipes/scheduling/forecast/time.py
def times_of_day(
    hours: list[int],
    start: datetime | None = None,
) -> cg.Array[datetime]:
    """Generate candidate time slots at specific hours of the day.

    Creates slots for today (the date of `start`) at the specified hours,
    returning only those strictly after `start`. Slots already in the past
    are dropped, so late in the day the result may be empty.

    Args:
        hours: List of hours (0-23) to generate slots for.
        start: Starting time. Defaults to now.

    Returns:
        The slots still ahead of `start`, sorted chronologically.

    Example:
        ```python
        times = cgr.scheduling.forecast.times_of_day(hours=[10, 12, 14, 16, 18, 20, 22])
        chosen = reservations.reserve(user_id, among=times)
        ```
    """
    first = start if start is not None else datetime.now()
    slots = [datetime.combine(first.date(), time(hour), tzinfo=first.tzinfo) for hour in hours]
    return cg.Array(sorted(slot for slot in slots if slot > first))