Next Run Calculation

Overview and Purpose

The Next Run Calculation module addresses the need to determine the next occurrence of a scheduled event based on a cron-like expression. It solves the problem of computing the earliest future date and time that matches a specified recurring schedule, enabling automated task scheduling or time-based triggers in applications.

This module is essential for scenarios where tasks must run repeatedly at defined intervals—such as daily reports, periodic testing, or maintenance jobs. By providing a reliable calculation of the next run datetime, it supports precise timing coordination without requiring complex external libraries.

Core Concepts and Functionality

Cron Expression Parsing

At the heart of the module lies a minimal parser for standard five-field cron expressions, covering:

• Minute: 0–59

• Hour: 0–23

• Day of Month: 1–31

• Month: 1–12

• Day of Week: 0–6 (Monday=0, Sunday=6)

The parser accepts simple syntaxes:

• Asterisk (*) to select all valid values

• Ranges using dash (e.g., 1-5)

• Comma-separated lists (e.g., 1,3,5)

The parsing process converts each field into a sorted set of discrete integers (CronField), which represent valid values for that time unit.

Next Run Computation Logic

The main function next_run operates as follows:

1. Reference Time Initialization:
   Uses the given since datetime or defaults to the current time.

2. Normalization:
   Resets seconds and microseconds to zero and increments by one minute, starting the search from the next minute after since.

3. Iterative Search:
   Advances minute-by-minute, checking whether the current datetime matches all five cron fields.

4. Match Criteria:
   The datetime matches if its minute, hour, day, month, and weekday are included in the respective sets parsed from the cron expression.

5. Stopping Conditions:

   • If a match is found, returns that datetime immediately.

   • If no match is found within an iteration limit corresponding to one year (366 days × 24 hours × 60 minutes), raises an error.

This approach trades off some efficiency for simplicity and clarity, suitable for learning and lightweight use cases.

Module Interaction and Integration

• The parsing logic (parse and _expand) and the next run calculation (next_run) coexist within the same file (schedule.py), encapsulating all schedule-related functionality.

• Other components like the demo script (demo.py) utilize next_run to showcase and validate the schedule computation, illustrating typical usage patterns.

• This module is independent of the timer functionality (timer.py), but both together provide a comprehensive toolkit for timed task execution and scheduling.

Key Files and Snippets

schedule.py

• Parsing Fields:

  def parse(cron: str):
      m, h, dom, mon, dow = cron.split()
      return (
          _expand(m, min_v=0, max_v=59),
          _expand(h, min_v=0, max_v=23),
          _expand(dom, min_v=1, max_v=31),
          _expand(mon, min_v=1, max_v=12),
          _expand(dow, min_v=0, max_v=6),
      )
  

• Calculating Next Run:

  def next_run(cron: str, *, since: datetime | None = None) -> datetime:
      since = since or datetime.now()
      minute, hour, dom, mon, dow = parse(cron)
      t = since.replace(second=0, microsecond=0) + timedelta(minutes=1)
  
      for _ in range(366 * 24 * 60):
          if (t.minute in minute.values and
              t.hour in hour.values and
              t.day in dom.values and
              t.month in mon.values and
              t.weekday() in dow.values):
              return t
          t += timedelta(minutes=1)
      raise ValueError("No run time found within a year (demo implementation).")
  

demo.py

Demonstrates usage by computing the next daily 9:00 AM run time after a given datetime:

nr = next_run("0 9 * * *", since=datetime(2025, 10, 2, 8, 59))
print("Next run at 9:00 daily from 08:59 ->", nr)

Design Patterns and Concepts

• Data Class for Structured Representation:
  The CronField dataclass encapsulates a list of allowed integers for each cron field, promoting clarity and type safety.

• Incremental Search:
  The minute-by-minute iteration leverages a straightforward brute-force search pattern, prioritizing readability over algorithmic complexity.

• Input Validation via Expansion:
  The _expand function enforces acceptable ranges and formats early, simplifying downstream matching logic.

• Idempotent and Pure Functions:
  Parsing and calculation functions avoid side effects, enabling easier testing and predictable outcomes.

Mermaid Diagram: Next Run Calculation Flow

flowchart TD
Start["Receive cron & reference time"]
Start --> Parse["Parse cron expression"]
Parse --> Expand["Expand fields to integer sets"]
Expand --> Init["Initialize search time (next minute)"]
Init --> Loop["Iterate minute-by-minute (max 1 year)"]
Loop --> Check{"Does current time match all fields?"}
Check -- Yes --> Return["Return current datetime"]
Check -- No --> Increment["Add 1 minute"]
Increment --> Loop
Loop -- Exceeded limit --> Error["Raise no match error"]

This flowchart illustrates the stepwise process from input to output, highlighting the iterative search mechanism that underlies the next run calculation.