Cron Expression Expansion

Purpose

This subtopic addresses the specific need to interpret individual fields within a standard five-part cron expression, transforming user-friendly shorthand notations into explicit sets of integers. Unlike the overall parsing of a full cron schedule [Schedule Parsing](/78814), this expansion logic focuses exclusively on resolving each field's meaning—such as minutes, hours, or days—supporting wildcards, ranges, and lists. This granularity enables precise and efficient downstream computations like next run time calculation [Next Run Calculation](/78815) by working with fully enumerated values rather than raw strings.

Functionality

The core functionality here is embodied in the _expand function, which accepts a single cron field string alongside its valid numeric range boundaries. It recognizes three types of shorthand:

* wildcard, expanded to the entire allowed range.
a-b range, expanded to all integers between a and b, inclusive.
a,b,c,... list of discrete values.

The result is a CronField dataclass instance holding a sorted, deduplicated list of integers representing all valid values for that field.

Key Workflow

Input: A raw field string (e.g., "*" or "1-5" or "0,15,30,45").
Detection: Determine if the field is a wildcard, range, or list.
Expansion: Convert shorthand to a full list of integers.
Output: Return a CronField object encapsulating the expanded values.

This expansion is then used by the full parsing logic in parse() to process all five fields of the cron expression.

Code Snippet

def _expand(field: str, *, min_v: int, max_v: int) -> CronField:
    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(",")]
    return CronField(sorted(set(values)))

This snippet illustrates the concise logic branching for the three supported syntaxes, ensuring all output lists are sorted and free of duplicates.

Integration

The expansion functionality is foundational within the [Cron Schedule Parsing](/78814) topic. It converts each cron field into a concrete set of integers, which the overall parser uses to build structured schedule data. These expanded sets are then referenced in the [Next Run Calculation](/78815) subtopic to efficiently verify candidate datetimes against the schedule constraints.

By isolating this expansion logic, the project maintains clarity and modularity. Future enhancements like supporting step values (*/5) or named months/days can extend _expand without altering the larger parsing or scheduling algorithms.

Diagram

flowchart TD
InputField["Input cron field"]
InputField --> CheckType{"Field type?"}
CheckType -->|Wildcard (*)| ExpandWildcard["Expand to full range"]
CheckType -->|Range (a-b)| ExpandRange["Expand to range a-b"]
CheckType -->|List (a,b,c)| ExpandList["Split and parse list"]
ExpandWildcard --> SortUnique["Sort & remove duplicates"]
ExpandRange --> SortUnique
ExpandList --> SortUnique
SortUnique --> Output["Return CronField with values"]

This flowchart visualizes the decision and expansion process for a single cron field handled by this subtopic.