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 * * *	毎日午前 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（次回実行時刻の計算用）