cron-expression-builder

Cron 表达式构建器

通过自然语言转换和运行时间预览来构建、解析和验证 Cron 表达式。

功能

• 自然语言：将描述转换为 Cron 表达式
• Cron 解析器：将 Cron 解析为易读格式
• 验证：验证 Cron 语法
• 下次运行时间：预览即将执行的时间
• 预设：常见的调度模式
• 两种格式：5 字段（标准）和 6 字段（含秒）

快速开始

from cron_builder import CronBuilder

builder = CronBuilder()

# Build from natural language
cron = builder.from_text("every day at 3:30 PM")
print(cron)  # 30 15 * * *

# Parse to human-readable
description = builder.describe("0 */2 * * *")
print(description)  # "Every 2 hours"

# Get next run times
runs = builder.next_runs("30 15 * * *", count=5)
for run in runs:
    print(run)

CLI 用法

# Build from text
python cron_builder.py --from-text "every monday at 9am"

# Describe a cron expression
python cron_builder.py --describe "0 9 * * 1"

# Validate expression
python cron_builder.py --validate "0 9 * * 1"

# Get next 10 runs
python cron_builder.py --next "0 9 * * 1" --count 10

# List preset schedules
python cron_builder.py --presets

# Use preset
python cron_builder.py --preset daily_midnight

# Interactive builder
python cron_builder.py --interactive

API 参考

CronBuilder 类

class CronBuilder:
    def __init__(self, with_seconds: bool = False)

    # Building
    def from_text(self, text: str) -> str
    def build(self, minute: str = "*", hour: str = "*",
             day: str = "*", month: str = "*",
             weekday: str = "*") -> str

    # Parsing
    def describe(self, expression: str) -> str
    def parse(self, expression: str) -> dict

    # Validation
    def validate(self, expression: str) -> dict
    def is_valid(self, expression: str) -> bool

    # Execution times
    def next_runs(self, expression: str, count: int = 5,
                 from_date: datetime = None) -> list
    def matches(self, expression: str, dt: datetime) -> bool

    # Presets
    def get_preset(self, name: str) -> str
    def list_presets(self) -> dict

Cron 表达式格式

5 字段格式（标准）

┌───────────── minute (0-59)
│ ┌───────────── hour (0-23)
│ │ ┌───────────── day of month (1-31)
│ │ │ ┌───────────── month (1-12)
│ │ │ │ ┌───────────── day of week (0-6, Sun=0)
│ │ │ │ │
* * * * *

6 字段格式（含秒）

┌───────────── second (0-59)
│ ┌───────────── minute (0-59)
│ │ ┌───────────── hour (0-23)
│ │ │ ┌───────────── day of month (1-31)
│ │ │ │ ┌───────────── month (1-12)
│ │ │ │ │ ┌───────────── day of week (0-6)
│ │ │ │ │ │
* * * * * *

自然语言转换

支持的模式

# Time-based
builder.from_text("every minute")        # * * * * *
builder.from_text("every 5 minutes")     # */5 * * * *
builder.from_text("every hour")          # 0 * * * *
builder.from_text("every 2 hours")       # 0 */2 * * *

# Daily
builder.from_text("every day at noon")   # 0 12 * * *
builder.from_text("daily at 3pm")        # 0 15 * * *
builder.from_text("at 3:30 PM every day")# 30 15 * * *

# Weekly
builder.from_text("every monday")        # 0 0 * * 1
builder.from_text("weekdays at 9am")     # 0 9 * * 1-5
builder.from_text("every friday at 5pm") # 0 17 * * 5

# Monthly
builder.from_text("first of every month")# 0 0 1 * *
builder.from_text("15th of each month")  # 0 0 15 * *
builder.from_text("last day of month")   # 0 0 L * *

# Special
builder.from_text("every sunday at midnight") # 0 0 * * 0
builder.from_text("twice daily")         # 0 0,12 * * *

预设

内置常见调度计划：

预设	Cron	描述
every_minute	* * * * *	每分钟
every_5_minutes	*/5 * * * *	每 5 分钟
every_15_minutes	*/15 * * * *	每 15 分钟
every_30_minutes	*/30 * * * *	每 30 分钟
hourly	0 * * * *	每小时
daily_midnight	0 0 * * *	每天午夜
daily_noon	0 12 * * *	每天中午
weekly_sunday	0 0 * * 0	每周日
weekly_monday	0 0 * * 1	每周一
monthly	0 0 1 * *	每月 1 日
quarterly	0 0 1 1,4,7,10 *	每季度首日
yearly	0 0 1 1 *	1 月 1 日

cron = builder.get_preset("daily_noon")
# "0 12 * * *"

Cron 描述

将 Cron 转换为易读格式：

builder.describe("30 15 * * 1-5")
# "At 3:30 PM, Monday through Friday"

builder.describe("0 */6 * * *")
# "Every 6 hours"

builder.describe("0 9 15 * *")
# "At 9:00 AM on day 15 of every month"

验证

result = builder.validate("0 9 * * 1")

# Returns:
{
    "valid": True,
    "expression": "0 9 * * 1",
    "fields": {
        "minute": "0",
        "hour": "9",
        "day_of_month": "*",
        "month": "*",
        "day_of_week": "1"
    },
    "description": "At 9:00 AM, only on Monday"
}

# Invalid expression
result = builder.validate("60 25 * * *")
# Returns:
{
    "valid": False,
    "error": "Invalid minute: 60 (must be 0-59)"
}

下次运行时间

预览即将执行的时间：

runs = builder.next_runs("0 9 * * 1", count=5)

# Returns:
[
    "2024-01-15 09:00:00",  # Next Monday
    "2024-01-22 09:00:00",
    "2024-01-29 09:00:00",
    "2024-02-05 09:00:00",
    "2024-02-12 09:00:00"
]

检查特定时间

from datetime import datetime

# Does this cron run at this time?
matches = builder.matches("0 9 * * 1", datetime(2024, 1, 15, 9, 0))
# True (Monday at 9 AM)

手动构建

逐个字段构建表达式：

# Every Monday at 9:30 AM
cron = builder.build(
    minute="30",
    hour="9",
    day="*",
    month="*",
    weekday="1"
)
# "30 9 * * 1"

# Every 15 minutes during business hours on weekdays
cron = builder.build(
    minute="*/15",
    hour="9-17",
    day="*",
    month="*",
    weekday="1-5"
)
# "*/15 9-17 * * 1-5"

示例工作流

调度计划构建器

builder = CronBuilder()

# Create schedule from user input
schedule_text = "every weekday at 8:30 AM"
cron = builder.from_text(schedule_text)

# Validate and preview
if builder.is_valid(cron):
    print(f"Cron: {cron}")
    print(f"Description: {builder.describe(cron)}")
    print("\nNext 5 runs:")
    for run in builder.next_runs(cron, count=5):
        print(f"  {run}")

作业调度器集成

# Define schedules for different jobs
jobs = {
    "backup": builder.get_preset("daily_midnight"),
    "reports": builder.from_text("every monday at 8am"),
    "cleanup": builder.from_text("first sunday of month at 2am")
}

for job_name, cron in jobs.items():
    print(f"{job_name}: {cron}")
    print(f"  Next run: {builder.next_runs(cron, count=1)[0]}")

依赖项

• croniter>=1.4.0（用于计算下次运行时间）