Skip to content

capturegraph.scheduling.forecast.time #

Time Forecasting - Generate Future Time Slots#

Creates a list of candidate timestamps for the scheduler to choose from.

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
List[datetime]

List of datetime objects at the given resolution.
Source code in capturegraph-lib/capturegraph/scheduling/forecast/time.py 
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
def times(
    resolution: timedelta = timedelta(minutes=5),
    span: timedelta = timedelta(hours=24),
    start: datetime | None = None,
) -> cg.List[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:
        List of datetime objects at the given resolution.
    """
    if start is None:
        start = datetime.now()

    times = []
    end = start + span
    current = start

    while current < end:
        times.append(current)
        current += resolution

    return cg.List(times)

times_of_day(hours, start=None, span=timedelta(hours=24)) #

Generate candidate time slots at specific hours of the day.

Creates slots for today and tomorrow at the specified hours, returning only those that are in the future.

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
span timedelta

Total time span to cover. Defaults to 24 hours.

 timedelta(hours=24)

Returns:

Type Description
List[datetime]

List of datetime objects.
Example 
slots = cgsh.forecast.times_of_day(
    hours=[10, 12, 14, 16, 18, 20, 22],
    start=datetime.now(),
    span=timedelta(hours=24),
)
next_slot = store.assign_next(user_id, slots)
Source code in capturegraph-lib/capturegraph/scheduling/forecast/time.py 
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
def times_of_day(
    hours: list[int],
    start: datetime | None = None,
    span: timedelta = timedelta(hours=24),
) -> cg.List[datetime]:
    """Generate candidate time slots at specific hours of the day.

    Creates slots for today and tomorrow at the specified hours,
    returning only those that are in the future.

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

    Returns:
        List of datetime objects.

    Example:
        ```python
        slots = cgsh.forecast.times_of_day(
            hours=[10, 12, 14, 16, 18, 20, 22],
            start=datetime.now(),
            span=timedelta(hours=24),
        )
        next_slot = store.assign_next(user_id, slots)
        ```
    """
    if start is None:
        start = datetime.now()

    slots = []
    today = start.date()

    for hour in hours:
        slot_time = datetime.combine(today, datetime.min.time()).replace(hour=hour)

        if slot_time > start:
            slots.append(slot_time)

    # Sort by date
    slots.sort(key=lambda s: s)
    return cg.List(slots)