Typed Job Scheduler

Design a small scheduling utility that loads job definitions from a JSON file, validates them, and computes the next few run times. The implementation must rely on precise Python standard-library typing so static analyzers can verify correct usage of filesystem paths, date/time objects, immutable collections, and iterable inputs.

Capabilities

Parse job file

• Reads a JSON file containing an array of job objects and returns strongly typed records; each job has a string name, a string list command, an ISO-8601 start_at timestamp with offset info, an integer interval_minutes, and an optional string list tags @test
• Rejects a job entry missing any required field (name, command, start_at, interval_minutes) by raising a ValueError @test

Compute next run times

• Given the loaded jobs and a reference timestamp, produces the next N run times across all jobs in chronological order, skipping times earlier than the reference point @test
• Starts from the first occurrence at or after the reference timestamp for each job, adds later intervals in minutes, and only returns future occurrences until the requested count is filled @test

Filter by tag

• When a tag filter is provided, only jobs containing that tag contribute run times; untagged jobs are excluded in that mode @test

Implementation

@generates

API

from dataclasses import dataclass
from datetime import datetime, timedelta
from pathlib import Path
from typing import Iterable, Sequence

@dataclass(frozen=True)
class JobDefinition:
    name: str
    command: Sequence[str]
    start_at: datetime
    interval: timedelta
    tags: frozenset[str] | None = None

@dataclass(frozen=True)
class RunPlan:
    job: JobDefinition
    run_at: datetime


def load_jobs(path: Path) -> list[JobDefinition]:
    ...


def next_runs(
    jobs: Iterable[JobDefinition],
    now: datetime,
    limit: int = 5,
    tag: str | None = None,
) -> list[RunPlan]:
    ...

Dependencies { .dependencies }

typeshed { .dependency }

Provides standard library type stubs so type checkers can validate usage of filesystem, datetime, and typing constructs.