Cron Expression Parser (python, written by Gemini Code Assist)

Gemini Code Assist wrote this python project from the task below. It does not run on a clean Ubuntu 22.04 machine as written.

Task given to the agent:

TASK: Cron Expression Parser

Write a program that parses, validates, and explains cron expressions, computing the next N execution times and generating human-readable descriptions of the schedule.

FUNCTIONAL REQUIREMENTS:
- Accept a cron expression as a command-line argument (standard 5-field format: minute, hour, day-of-month, month, day-of-week)
- Support extended 6-field format with seconds as the first field via --with-seconds flag
- Support special characters: * (all), , (list), - (range), / (step), L (last), W (nearest weekday), # (nth day of week), and ? (any)
- Validate the expression and report clear errors for invalid fields with the specific position and reason (e.g., "Field 2 (hour): value 25 exceeds maximum 23")
- Compute and display the next N execution times via --next flag (default: 10), formatted in ISO 8601 and local human-readable format, relative to current time or a specified start time via --from flag
- Generate a human-readable English description of the schedule (e.g., "At 03:30 AM, every Monday and Wednesday, in January through March")
- Support time zone handling via --timezone flag (default: UTC)
- Compute the interval statistics: average gap between executions, minimum gap, maximum gap, total executions per day/week/month/year
- Support checking if a specific datetime matches the cron expression via --check flag
- Support converting between cron expression and a verbal description via --describe flag (cron to English) and --parse flag (English-like input to cron expression for common patterns)
- Print results to console in a formatted display
- Save results as JSON with --output flag (default: cron_analysis.json)
- Support batch validation of multiple expressions from a file via --batch flag
- If no expression is given, demonstrate with several example expressions: "*/5 * * * *" (every 5 minutes), "0 9 * * 1-5" (weekdays at 9am), "0 0 1,15 * *" (1st and 15th at midnight), "30 4 * * SUN" (Sundays at 4:30am), showing next 5 runs and descriptions for each
- Handle errors: invalid syntax, out-of-range values, impossible combinations (e.g., Feb 31), and malformed special characters

Create a complete Python project for a clean Ubuntu 22.04 machine with only Python 3.10+ installed. Include:
- Source code
- requirements.txt with all dependencies (direct and transitive) pinned to exact versions
- README.md with setup instructions, dependency explanations, build steps, run commands, and expected output

[]

import sys
import argparse
import json
import datetime
from croniter import croniter
from cron_descriptor import get_description
import pytz

def analyze_cron(expression, next_n=10, tz='UTC'):
    timezone = pytz.timezone(tz)
    now = datetime.datetime.now(timezone)
    
    # 1. Human readable description
    try:
        desc = get_description(expression)
    except Exception as e:
        desc = f"Error describing: {e}"

    # 2. Next N execution times
    iter = croniter(expression, now)
    next_times = []
    for _ in range(next_n):
        next_times.append(iter.get_next(datetime.datetime).isoformat())

    return {
        "expression": expression,
        "description": desc,
        "next_executions": next_times,
        "timezone": tz
    }

def main():
    parser = argparse.ArgumentParser(description="Cron Expression Parser")
    parser.add_argument("expression", nargs="?", help="Cron expression (e.g. '*/5 * * * *')")
    parser.add_argument("--next", type=int, default=10, help="Number of next executions to show")
    parser.add_argument("--tz", default="UTC", help="Timezone")
    parser.add_argument("--output", default="cron_analysis.json")
    
    args = parser.parse_args()
    
    if not args.expression:
        print("Demo Mode: Analyzing common expressions...")
        examples = ["*/5 * * * *", "0 9 * * 1-5", "0 0 1,15 * *"]
        all_results = [analyze_cron(ex) for ex in examples]
        print(json.dumps(all_results, indent=4))
        return

    result = analyze_cron(args.expression, args.next, args.tz)
    print("
--- Cron Analysis ---")
    print(f"Expression:  {result['expression']}")
    print(f"Description: {result['description']}")
    print("
Next Executions:")
    for t in result['next_executions']:
        print(f" - {t}")

    with open(args.output, 'w') as f:
        json.dump(result, f, indent=4)

if __name__ == "__main__":
    main()

# Cron Expression Parser (Python)

A tool for parsing, validating, and explaining cron expressions.

## Setup Instructions

1. Ensure Python 3.10+ is installed.
2. Create a virtual environment:
   ```bash
   python3 -m venv venv
   source venv/bin/activate
   ```
3. Install dependencies:
   ```bash
   pip install -r requirements.txt
   ```

## Run Commands

- **Analyze Expression**:
  ```bash
  python cron_parser.py "0 9 * * 1-5" --next 5
  ```
- **Custom Timezone**:
  ```bash
  python cron_parser.py "*/15 * * * *" --tz "America/New_York"
  ```
- **Run demonstration**:
  ```bash
  python cron_parser.py
  ```

## Features
- **Human-Readable Description**: Converts cryptic cron strings into English sentences.
- **Predictive Execution**: Computes the next N occurrences relative to the current time.
- **Timezone Support**: Accurate calculations across different world timezones.

croniter==2.0.1
cron-descriptor==1.4.3
python-dateutil==2.8.2
pytz==2024.1