streamlit-job-scheduler 0.0.1

A Streamlit-based job scheduler with one-time and cron scheduling support

Streamlit Job Scheduler

A simple and interactive Streamlit-based UI to configure and manage scheduled jobs — either one-time or cron-based.

Features

• One-time scheduling (date + time + minute)
• Cron scheduling with flexible frequency (daily, weekly, monthly, etc.)
• Multi-hour and multi-day support in a single cron expression
• Human-readable cron descriptions
• Pytest unit tests

Quick start

Install (editable during development) and run the Streamlit app:

pip install -e .
streamlit run -m streamlit_job_scheduler/ui.py

Or run directly (development):

python -m streamlit_job_scheduler/ui.py

🧩 Usage

pip install streamlit-job-scheduler

Programmatic usage

Primary UI entry is streamlit_job_scheduler.ui.job_scheduler. Signature:

• job_scheduler(callback_func, config: SchedulerConfig = None) -> ScheduleInfo | None

• callback_func: optional callable that will be invoked with a streamlit_job_scheduler.models.ScheduleInfo when the user finalizes a schedule.

• config: optional streamlit_job_scheduler.models.SchedulerConfig to control initial UI state, title, pre-filled cron (parsed by streamlit_job_scheduler.scheduler.parse_cron_to_preconfig), and display options.

Example (use inside a Streamlit session):

from streamlit_job_scheduler.ui import job_scheduler
from streamlit_job_scheduler.models import SchedulerConfig
from streamlit_job_scheduler.enums import ScheduleType

config = SchedulerConfig(schedule_type=ScheduleType.CRONJOB, schedule="*/10 * * * *")
job = job_scheduler(None, config=config)  # returns a ScheduleInfo when not using a callback

Returned object is a streamlit_job_scheduler.models.ScheduleInfo with .schedule_type and .schedule attributes.

Cron helpers

• generate_cron_expr(frequency, ...) — build a cron expression for frequencies like "Every X minutes", "Hourly", "Daily", "Weekly", "Monthly", or "Custom". See implementation: streamlit_job_scheduler/scheduler.py and symbol: streamlit_job_scheduler.scheduler.generate_cron_expr

• describe_cron(expr) — turn a standard 5-field cron into a human-friendly description. See: streamlit_job_scheduler.scheduler.describe_cron

• parse_cron_to_preconfig(cron_expr) — parse a cron expression into a dict suitable for pre-filling the UI. See: streamlit_job_scheduler.scheduler.parse_cron_to_preconfig

Example:

from streamlit_job_scheduler.scheduler import generate_cron_expr, describe_cron

expr = generate_cron_expr("Daily", hours=[9,17], minutes=[0,30])
print(expr)                 # -> "0,30 9,17 * * *"
print(describe_cron(expr))  # human readable description

Tests

Pytest tests cover scheduler logic and a smoke UI test harness.

Run tests:

pytest -q

Tests to review:

• streamlit_job_scheduler/tests/test_scheduler.py
• streamlit_job_scheduler/tests/test_ui.py

Development notes & gotchas

• The package requires Streamlit (see setup.cfg and pyproject.toml).
• The UI function is designed to be run inside a Streamlit app — running it outside Streamlit will not render widgets.
• The UI function signature is job_scheduler(callback_func, config=None). When using programmatically prefer passing the config as the second positional argument or as a keyword (config=...) so the function can detect the callback and config correctly. See implementation: streamlit_job_scheduler.ui.job_scheduler
• Cron parsing expects standard 5-field cron expressions (minute hour day month weekday). See: streamlit_job_scheduler.scheduler.is_valid_cron

Contributing

• Modify code in streamlit_job_scheduler/ and add tests in streamlit_job_scheduler/tests/.
• Run tests with pytest.
• Keep examples and README in sync with code in:
  • streamlit_job_scheduler/ui.py
  • streamlit_job_scheduler/scheduler.py
  • streamlit_job_scheduler/models.py
  • streamlit_job_scheduler/enums.py

License

MIT — see LICENSE