Cron Expression Builder

Cron 表达式构建器

Build, parse, and validate cron expressions with natural language conversion and run time preview.

构建、解析和验证cron表达式，支持自然语言转换和运行时间预览。

Features

功能特性

Natural Language: Convert descriptions to cron expressions
Cron Parser: Parse cron to human-readable format
Validation: Validate cron syntax
Next Runs: Preview upcoming execution times
Presets: Common scheduling patterns
Both Formats: 5-field (standard) and 6-field (with seconds)

自然语言转换：将描述文本转换为cron表达式
Cron解析器：将cron表达式解析为人类可读格式
语法验证：验证cron表达式的语法正确性
下次运行时间预览：查看即将到来的执行时间
预设模板：常见的调度模式预设
双格式支持：5字段（标准格式）和6字段（包含秒数）

Quick Start

快速开始

python

from cron_builder import CronBuilder

builder = CronBuilder()

python

from cron_builder import CronBuilder

builder = CronBuilder()

Build from natural language

从自然语言构建cron表达式

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)

undefined

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

undefined

CLI Usage

CLI 使用方法

bash

undefined

bash

undefined

Build from text

从文本构建cron表达式

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

Describe a cron expression

描述cron表达式

python cron_builder.py --describe "0 9 * * 1"

Validate expression

验证表达式

python cron_builder.py --validate "0 9 * * 1"

Get next 10 runs

获取接下来10次运行时间

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

undefined

python cron_builder.py --interactive

undefined

API Reference

API 参考

CronBuilder Class

CronBuilder 类

python

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

python

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

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

    # 解析方法
    def describe(self, expression: str) -> str
    def parse(self, expression: str) -> dict

    # 验证方法
    def validate(self, expression: str) -> dict
    def is_valid(self, expression: str) -> bool

    # 执行时间方法
    def next_runs(self, expression: str, count: int = 5,
                 from_date: datetime = None) -> list
    def matches(self, expression: str, dt: datetime) -> bool

    # 预设模板方法
    def get_preset(self, name: str) -> str
    def list_presets(self) -> dict

Cron Expression Format

Cron 表达式格式

5-Field Format (Standard)

5字段格式（标准）

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

┌───────────── 分钟 (0-59)
│ ┌───────────── 小时 (0-23)
│ │ ┌───────────── 日期 (1-31)
│ │ │ ┌───────────── 月份 (1-12)
│ │ │ │ ┌───────────── 星期 (0-6，周日=0)
│ │ │ │ │
* * * * *

6-Field Format (With Seconds)

6字段格式（包含秒数）

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

┌───────────── 秒数 (0-59)
│ ┌───────────── 分钟 (0-59)
│ │ ┌───────────── 小时 (0-23)
│ │ │ ┌───────────── 日期 (1-31)
│ │ │ │ ┌───────────── 月份 (1-12)
│ │ │ │ │ ┌───────────── 星期 (0-6)
│ │ │ │ │ │
* * * * * *

Natural Language Conversion

自然语言转换

Supported Patterns

支持的模式

python

undefined

python

undefined

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 * * *

undefined

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

undefined

Presets

预设模板

Built-in common schedules:

Preset	Cron	Description
`every_minute`	`* * * * *`	Every minute
`every_5_minutes`	`/5 * * *`	Every 5 minutes
`every_15_minutes`	`/15 * * *`	Every 15 minutes
`every_30_minutes`	`/30 * * *`	Every 30 minutes
`hourly`	`0 * * * *`	Every hour
`daily_midnight`	`0 0 * * *`	Daily at midnight
`daily_noon`	`0 12 * * *`	Daily at noon
`weekly_sunday`	`0 0 * * 0`	Weekly on Sunday
`weekly_monday`	`0 0 * * 1`	Weekly on Monday
`monthly`	`0 0 1 * *`	First of month
`quarterly`	`0 0 1 1,4,7,10 *`	First day of quarter
`yearly`	`0 0 1 1 *`	January 1st

python

cron = builder.get_preset("daily_noon")

内置的常见调度计划：

预设名称	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日执行

python

cron = builder.get_preset("daily_noon")

"0 12 * * *"

undefined

undefined

Cron Description

Cron 表达式描述

Convert cron to human-readable:

python

builder.describe("30 15 * * 1-5")

将cron表达式转换为人类可读文本：

python

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"

undefined

undefined

Validation

语法验证

python

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

python

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)" }

undefined

{ "valid": False, "error": "Invalid minute: 60 (must be 0-59)" }

undefined

Next Run Times

下次运行时间预览

Preview upcoming executions:

python

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

查看即将到来的执行时间：

python

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" ]

undefined

[ "2024-01-15 09:00:00", # 下周一 "2024-01-22 09:00:00", "2024-01-29 09:00:00", "2024-02-05 09:00:00", "2024-02-12 09:00:00" ]

undefined

Check Specific Time

检查特定时间是否匹配

python

from datetime import datetime

python

from datetime import datetime

Does this cron run at this time?

该cron表达式是否在指定时间执行？

matches = builder.matches("0 9 * * 1", datetime(2024, 1, 15, 9, 0))

True (Monday at 9 AM)

True（周一上午9点）

undefined

undefined

Manual Building

手动构建表达式

Build expression field by field:

python

undefined

逐字段构建cron表达式：

python

undefined

Every Monday at 9:30 AM

每周一上午9:30执行

cron = builder.build( minute="30", hour="9", day="", month="", weekday="1" )

"30 9 * * 1"

Every 15 minutes during business hours on weekdays

工作日工作时间内每15分钟执行一次

cron = builder.build( minute="/15", hour="9-17", day="", month="*", weekday="1-5" )

"/15 9-17 * 1-5"

undefined

undefined

Example Workflows

示例工作流

Schedule Builder

调度计划构建器

python

builder = CronBuilder()

python

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}")

undefined

if builder.is_valid(cron): print(f"Cron表达式: {cron}") print(f"描述: {builder.describe(cron)}") print("\n接下来5次运行时间:") for run in builder.next_runs(cron, count=5): print(f" {run}")

undefined

Job Scheduler Integration

任务调度器集成

python

undefined

python

undefined

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]}")

undefined

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" 下次运行时间: {builder.next_runs(cron, count=1)[0]}")

undefined

Dependencies

依赖项

croniter>=1.4.0 (for next run calculations)

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

cron-expression-builder

Original

Translation

Cron Expression Builder

Cron 表达式构建器

Features

功能特性

Quick Start

快速开始

Build from natural language

从自然语言构建cron表达式

Parse to human-readable

解析为人类可读描述

Get next run times

获取下次运行时间

CLI Usage

CLI 使用方法

Build from text

从文本构建cron表达式

Describe a cron expression

描述cron表达式

Validate expression

验证表达式

Get next 10 runs

获取接下来10次运行时间

List preset schedules

列出预设调度

Use preset

使用预设模板

Interactive builder

交互式构建器

API Reference

API 参考

CronBuilder Class

CronBuilder 类

Cron Expression Format

Cron 表达式格式

5-Field Format (Standard)

5字段格式（标准）

6-Field Format (With Seconds)

6字段格式（包含秒数）

Natural Language Conversion

自然语言转换

Supported Patterns

支持的模式

Time-based

基于时间的调度

Daily

每日调度

Weekly

每周调度

Monthly

每月调度

Special

特殊调度

Presets

预设模板

"0 12 * * *"

"0 12 * * *"

Cron Description

Cron 表达式描述

"At 3:30 PM, Monday through Friday"

"At 3:30 PM, Monday through Friday"

"Every 6 hours"

"Every 6 hours"

"At 9:00 AM on day 15 of every month"

"At 9:00 AM on day 15 of every month"

Validation

语法验证

Returns:

返回结果：

Invalid expression

无效表达式示例

Returns:

返回结果：

Next Run Times

下次运行时间预览

Returns:

返回结果：

Check Specific Time

"/15 9-17 * 1-5"

"/15 9-17 * 1-5"