Schedule Parsing

Purpose

Within the broader context of cron schedule parsing, this subtopic focuses on transforming a complete cron-like expression—consisting of five space-separated fields (minute, hour, day of month, month, and day of week)—into a structured, programmatically usable form. This parsing step enables subsequent components, such as the next run time calculator, to efficiently interpret and match schedule criteria.

The core problem addressed here is converting a human-readable cron string (e.g., "0 9 * * *") into a data structure that accurately represents all valid values for each time unit, handling common cron shorthand notations like wildcards (*), ranges (a-b), and lists (a,b,c). This structured representation is essential for reliable schedule computations and forms the foundation for further processing under the main topic of Cron Schedule Parsing.

Functionality

The parsing involves two primary functions:

• Field Expansion (_expand): Each individual cron field is parsed and expanded into a sorted list of unique integers that represent all acceptable values for that field. It supports:

  • Asterisk (*) to denote the full range (e.g., 0–59 for minutes).

  • Ranges specified with a dash (e.g., 1-5).

  • Comma-separated lists (e.g., 1,4,7).

• Complete Expression Parsing (parse): This function accepts a full cron expression string, splits it into its five components, and applies _expand to each field with the appropriate value bounds:

  • Minute: 0 to 59

  • Hour: 0 to 23

  • Day of Month: 1 to 31

  • Month: 1 to 12

  • Day of Week: 0 to 6 (Python's datetime.weekday() convention)

The output is a tuple of CronField dataclass instances, each encapsulating the expanded list of valid integers for its respective time unit.

Key Elements

• CronField Dataclass: Wraps the list of valid integers for clarity and type safety, supporting clean downstream usage.

• Expansion Logic:

  if field == "*":
      values = list(range(min_v, max_v + 1))
  elif "-" in field:
      a, b = field.split("-", 1)
      values = list(range(int(a), int(b) + 1))
  else:
      values = [int(x) for x in field.split(",")]
  

This approach balances simplicity with sufficient expressiveness for common cron expressions encountered in scheduling scenarios.

Integration

Schedule Parsing serves as a precursor step to the Next Run Calculation subtopic. By converting the raw cron string into structured fields, it enables the next run logic to efficiently check if candidate datetimes satisfy the schedule constraints.

It also complements the Cron Expression Expansion subtopic by applying the expansion logic uniformly across all five fields, ensuring consistent interpretation of the schedule. Parsing here is the bridge that connects raw user input to programmatic schedule evaluation.

The parsing functionality is consumed directly by the next_run function within the schedule.py module, which iterates through future datetimes and queries these expanded fields to find the next valid execution time.

Diagram

flowchart TD
A[Cron String Input]
A --> B[Split into 5 Fields]
B --> C1[Expand Minute Field]
B --> C2[Expand Hour Field]
B --> C3[Expand Day of Month Field]
B --> C4[Expand Month Field]
B --> C5[Expand Day of Week Field]
C1 --> D[CronField: Minute]
C2 --> D[CronField: Hour]
C3 --> D[CronField: Day of Month]
C4 --> D[CronField: Month]
C5 --> D[CronField: Day of Week]
D --> E[Tuple of CronField Objects]