cronslator

Natural Language to Cron

A Python 3.9+ library to convert an English string to cron schedule.

Important

This is not the library you are looking for!

This codebase was generated entirely from prompting GitHub Copilot (Clause 3.5 Sonnet) and has not been audited, verified or even assumed to be correct.

This is an experiment to tinker with new shiny tools, and to share what's possible using them - your takeaway could be "Wow, that's nice!" or "Wow, that's crap!" and either are fine.

Beyond this line, there is no human written text or code, it is all LLM generated slop (hence the org name pyslop!).

Understanding Cron Format

The cron expressions generated follow the standard 5-field format:

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

Special characters:

• *: any value
• ,: value list separator
• -: range of values
• /: step values
• L: last day of month (only in day of month field)

Supported patterns:

Usage

As a Command Line Tool

After installation, you can use the cronslate command:

# Basic usage
cronslate "Every Monday at 3am"
# Output: 0 3 * * 1

# Using quotes is optional for simple phrases
cronslate Every Monday at 3am
# Output: 0 3 * * 1

# Pipe input from other commands
echo "Every 15 minutes" | cronslate
# Output: */15 * * * *

As a Python Library

Basic usage:

from pyslop.cronslator import cronslate

# Simple schedule
result = cronslate("Every Monday at 3am")
print(result)  # Output: 0 3 * * 1

# Multiple times
result = cronslate("Every day at 2am and 2pm")
print(result)  # Output: 0 2,14 * * *

# Complex schedules
result = cronslate("Every 30 minutes between 9am and 5pm on weekdays")
print(result)  # Output: */30 9-17 * * 1-5

Error handling:

from pyslop.cronslator import cronslate

try:
    # This will raise a ValueError
    result = cronslate("at 25:00")
except ValueError as e:
    print(f"Error: {e}")

# Invalid inputs will raise ValueError:
invalid_inputs = [
    "",                      # Empty string
    "invalid cron string",   # Nonsense input
    "at 25:00",             # Invalid hour
    "on day 32",            # Invalid day
]

for input_str in invalid_inputs:
    try:
        cronslate(input_str)
    except ValueError as e:
        print(f"'{input_str}' is invalid: {e}")

Complete script example:

#!/usr/bin/env python3
from pyslop.cronslator import cronslate

def process_schedules():
    schedules = [
        "Every Monday at 3am",
        "Every weekday at noon",
        "Every 15 minutes",
        "First day of every month at midnight",
        "Every Sunday at 4:30 PM"
    ]
    
    print("Natural Language → Cron Expression")
    print("─" * 40)
    
    for schedule in schedules:
        try:
            cron = cronslate(schedule)
            print(f"{schedule:<30} → {cron}")
        except ValueError as e:
            print(f"{schedule:<30} → Error: {e}")

if __name__ == "__main__":
    process_schedules()

# Output:
# Natural Language → Cron Expression
# ─────────────────────────────────────────────
# Every Monday at 3am             → 0 3 * * 1
# Every weekday at noon          → 0 12 * * 1-5
# Every 15 minutes               → */15 * * *
# First day of every month...    → 0 0 1 * *
# Every Sunday at 4:30 PM        → 30 16 * * 0

Installation

Install from PyPI using pipx (recommended):

# Install pipx if you haven't already
python -m pip install --user pipx
python -m pipx ensurepath

# Install from PyPI
pipx install pyslop-cronslator

# Or install from TestPyPI
pipx install --pip-args="--index-url https://test.pypi.org/simple/ --no-deps" pyslop-cronslator

Or install from PyPI using pip:

pip install pyslop-cronslator

Or install from source:

git clone https://github.com/pyslop/cronslator.git
cd cronslator
pip install .

Development

Clone and set up development environment:

# Clone the repository
git clone https://github.com/pyslop/cronslator.git
cd cronslator

# Install poetry if you haven't already
pip install poetry

# Install dependencies and development dependencies
poetry install

# Run tests
poetry run pytest

# Run specific test file
poetry run pytest tests/test_readme_examples.py

Publishing to PyPI

For maintainers, to publish a new version:

# Update version in pyproject.toml first, then:

# Build the package
poetry build

# Configure TestPyPI repository (one-time setup)
poetry config repositories.testpypi https://test.pypi.org/legacy/

# Publish to TestPyPI first (requires TestPyPI credentials)
poetry publish -r testpypi

# Test the package from TestPyPI
pip install --index-url https://test.pypi.org/simple/ --no-deps pyslop-cronslator

# If everything looks good, publish to PyPI (requires PyPI credentials)
poetry publish

# Or do both build and publish in one step
poetry publish --build