tickforge 0.1.0__py3-none-any.whl

tickforge/__init__.py

@@ -0,0 +1,107 @@
+"""tickforge: an advanced task scheduler with persistence and async support.
+
+Quick start
+-----------
+    import asyncio
+    from tickforge import AsyncScheduler, IntervalTrigger, SQLiteJobStore
+
+    async def ping():
+        print("pong")
+
+    async def main():
+        scheduler = AsyncScheduler(store=SQLiteJobStore("jobs.db"))
+        await scheduler.add_job(ping, IntervalTrigger(seconds=5), name="ping")
+        await scheduler.start()
+        await scheduler.wait_closed()
+
+    asyncio.run(main())
+"""
+
+from .core import (
+    ConfigurationError,
+    CronTrigger,
+    DateTrigger,
+    IntervalTrigger,
+    Job,
+    JobExecutionError,
+    JobLookupError,
+    JobResult,
+    JobRun,
+    JobStatus,
+    SchedulePlusError,
+    SerializationError,
+    Trigger,
+    TriggerError,
+    build_trigger,
+    callable_ref,
+    coerce_datetime,
+    coerce_timezone,
+    resolve_callable,
+    trigger_from_dict,
+    utcnow,
+)
+from .logging import (
+    JSONFormatter,
+    TextFormatter,
+    configure_logging,
+    get_logger,
+    job_context,
+)
+from .persistence import (
+    JobStore,
+    JSONFileJobStore,
+    MemoryJobStore,
+    SQLiteJobStore,
+    create_store,
+)
+from .scheduler import (
+    AsyncScheduler,
+    EventType,
+    Scheduler,
+    SchedulerConfig,
+    SchedulerEvent,
+    SchedulerState,
+)
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "__version__",
+    "SchedulePlusError",
+    "TriggerError",
+    "JobLookupError",
+    "JobExecutionError",
+    "SerializationError",
+    "ConfigurationError",
+    "Trigger",
+    "DateTrigger",
+    "IntervalTrigger",
+    "CronTrigger",
+    "Job",
+    "JobRun",
+    "JobResult",
+    "JobStatus",
+    "build_trigger",
+    "trigger_from_dict",
+    "resolve_callable",
+    "callable_ref",
+    "coerce_datetime",
+    "coerce_timezone",
+    "utcnow",
+    "JobStore",
+    "MemoryJobStore",
+    "SQLiteJobStore",
+    "JSONFileJobStore",
+    "create_store",
+    "AsyncScheduler",
+    "Scheduler",
+    "SchedulerConfig",
+    "SchedulerState",
+    "SchedulerEvent",
+    "EventType",
+    "configure_logging",
+    "get_logger",
+    "job_context",
+    "JSONFormatter",
+    "TextFormatter",
+]

tickforge/cli.py

@@ -0,0 +1,516 @@
+"""Command line interface for tickforge."""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import os
+import signal
+import sys
+from datetime import datetime
+from typing import Any, Dict, List, Optional, Tuple
+
+import click
+
+from .core import (
+    ConfigurationError,
+    Job,
+    JobLookupError,
+    JobRun,
+    SchedulePlusError,
+    build_trigger,
+    callable_ref,
+    format_datetime,
+    humanize_delta,
+    utcnow,
+)
+from .logging import configure_logging, get_logger
+from .persistence import JobStore, create_store
+from .scheduler import AsyncScheduler, EventType, SchedulerConfig, SchedulerEvent
+
+__all__ = ["cli", "main"]
+
+logger = get_logger("cli")
+
+DEFAULT_DB = os.environ.get(
+    "TICKFORGE_DB",
+    os.path.join(os.path.expanduser("~"), ".tickforge", "jobs.db"),
+)
+
+
+def _version() -> str:
+    from . import __version__
+
+    return __version__
+
+
+def _fail(message: str, code: int = 1) -> "click.ClickException":
+    exc = click.ClickException(message)
+    exc.exit_code = code
+    return exc
+
+
+def _parse_value(raw: str) -> Any:
+    """Interpret a CLI value as JSON, falling back to a plain string."""
+    try:
+        return json.loads(raw)
+    except (TypeError, ValueError):
+        return raw
+
+
+def _parse_kwargs(pairs: Tuple[str, ...]) -> Dict[str, Any]:
+    result: Dict[str, Any] = {}
+    for pair in pairs:
+        key, sep, raw = pair.partition("=")
+        if not sep or not key.strip():
+            raise _fail("invalid --kwarg %r, expected key=value" % (pair,))
+        result[key.strip()] = _parse_value(raw)
+    return result
+
+
+def _short(value: Optional[str], width: int) -> str:
+    if not value:
+        return "-"
+    return value if len(value) <= width else value[: width - 1] + "…"
+
+
+def _job_row(job: Job) -> List[str]:
+    next_run = format_datetime(job.next_run_at) or "never"
+    return [
+        job.id[:8],
+        _short(job.name, 22),
+        _short(job.trigger.describe(), 34),
+        next_run,
+        "yes" if job.enabled else "no",
+        str(job.status),
+        "%d/%d" % (job.success_count, job.run_count),
+    ]
+
+
+def _print_table(headers: List[str], rows: List[List[str]]) -> None:
+    if not rows:
+        click.echo("no records")
+        return
+    widths = [len(header) for header in headers]
+    for row in rows:
+        for index, cell in enumerate(row):
+            widths[index] = max(widths[index], len(cell))
+    template = "  ".join("{:<%d}" % width for width in widths)
+    click.echo(click.style(template.format(*headers), bold=True))
+    click.echo("-" * (sum(widths) + 2 * (len(widths) - 1)))
+    for row in rows:
+        click.echo(template.format(*row))
+
+
+def _get_store(ctx: click.Context) -> JobStore:
+    store: JobStore = ctx.obj["store"]
+    store.setup()
+    return store
+
+
+def _resolve_job(store: JobStore, identifier: str) -> Job:
+    """Match a job by full id, id prefix or exact name."""
+    try:
+        return store.get_job(identifier)
+    except JobLookupError:
+        pass
+    matches = [
+        job
+        for job in store.get_jobs()
+        if job.id.startswith(identifier) or job.name == identifier
+    ]
+    if not matches:
+        raise _fail("no job matching %r" % (identifier,))
+    if len(matches) > 1:
+        names = ", ".join("%s (%s)" % (job.name, job.id[:8]) for job in matches)
+        raise _fail("ambiguous job reference %r: %s" % (identifier, names))
+    return matches[0]
+
+
+# --------------------------------------------------------------------------- #
+# Root group
+# --------------------------------------------------------------------------- #
+@click.group(context_settings={"help_option_names": ["-h", "--help"]})
+@click.option(
+    "--db",
+    default=DEFAULT_DB,
+    show_default=True,
+    envvar="TICKFORGE_DB",
+    help="Store URI or path (sqlite path, *.json, or memory://).",
+)
+@click.option("-v", "--verbose", count=True, help="Increase verbosity (-v, -vv).")
+@click.option("-q", "--quiet", is_flag=True, help="Suppress console logging.")
+@click.option(
+    "--log-format",
+    type=click.Choice(["text", "json"]),
+    default="text",
+    show_default=True,
+    help="Log output format.",
+)
+@click.option("--log-file", type=click.Path(dir_okay=False), default=None, help="Also log to this file.")
+@click.version_option(version=_version(), prog_name="tickforge")
+@click.pass_context
+def cli(
+    ctx: click.Context,
+    db: str,
+    verbose: int,
+    quiet: bool,
+    log_format: str,
+    log_file: Optional[str],
+) -> None:
+    """tickforge — persistent, async-capable task scheduler."""
+    level = "WARNING" if quiet else ("DEBUG" if verbose >= 2 else "INFO" if verbose == 1 else "INFO")
+    configure_logging(level=level, fmt=log_format, log_file=log_file, quiet=quiet, force=True)
+    try:
+        store = create_store(db)
+    except SchedulePlusError as exc:
+        raise _fail(str(exc))
+    ctx.ensure_object(dict)
+    ctx.obj["store"] = store
+    ctx.obj["db"] = db
+    ctx.call_on_close(store.close)
+
+
+# --------------------------------------------------------------------------- #
+# Job management
+# --------------------------------------------------------------------------- #
+@cli.command("add")
+@click.argument("func")
+@click.option("--name", default=None, help="Human-readable job name.")
+@click.option("--interval", default=None, help="Interval such as 30s, 5m, 1h30m.")
+@click.option("--cron", default=None, help="Cron expression 'min hour day month dow'.")
+@click.option("--at", default=None, help="One-shot ISO timestamp or natural date.")
+@click.option("--timezone", "tz", default=None, help="IANA timezone for the trigger.")
+@click.option("--start-at", default=None, help="Do not fire before this timestamp.")
+@click.option("--end-at", default=None, help="Do not fire after this timestamp.")
+@click.option("--jitter", type=float, default=None, help="Random delay up to N seconds (interval only).")
+@click.option("--arg", "positional", multiple=True, help="Positional argument (JSON or string).")
+@click.option("--kwarg", "keyword", multiple=True, help="Keyword argument as key=value.")
+@click.option("--retries", type=int, default=0, show_default=True, help="Retry attempts on failure.")
+@click.option("--retry-delay", type=float, default=5.0, show_default=True, help="Seconds between retries.")
+@click.option("--timeout", type=float, default=None, help="Abort a run after N seconds.")
+@click.option("--grace", type=float, default=None, help="Misfire grace window in seconds.")
+@click.option("--tag", "tags", multiple=True, help="Tag for filtering (repeatable).")
+@click.option("--allow-concurrent", is_flag=True, help="Permit overlapping runs of this job.")
+@click.option("--disabled", is_flag=True, help="Create the job in a paused state.")
+@click.pass_context
+def add_command(
+    ctx: click.Context,
+    func: str,
+    name: Optional[str],
+    interval: Optional[str],
+    cron: Optional[str],
+    at: Optional[str],
+    tz: Optional[str],
+    start_at: Optional[str],
+    end_at: Optional[str],
+    jitter: Optional[float],
+    positional: Tuple[str, ...],
+    keyword: Tuple[str, ...],
+    retries: int,
+    retry_delay: float,
+    timeout: Optional[float],
+    grace: Optional[float],
+    tags: Tuple[str, ...],
+    allow_concurrent: bool,
+    disabled: bool,
+) -> None:
+    """Register a job. FUNC is a 'package.module:callable' reference."""
+    store = _get_store(ctx)
+    try:
+        reference = callable_ref(func)
+        trigger = build_trigger(
+            interval=interval,
+            cron=cron,
+            at=at,
+            timezone=tz,
+            start_at=start_at,
+            end_at=end_at,
+            jitter=jitter,
+        )
+        job = Job.create(
+            reference,
+            trigger,
+            name=name or "",
+            args=tuple(_parse_value(item) for item in positional),
+            kwargs=_parse_kwargs(keyword),
+            max_retries=retries,
+            retry_delay=retry_delay,
+            timeout=timeout,
+            misfire_grace_time=grace,
+            allow_concurrent=allow_concurrent,
+            enabled=not disabled,
+            tags=list(tags),
+        )
+        store.add_job(job)
+    except (SchedulePlusError, ValueError) as exc:
+        raise _fail(str(exc))
+    click.echo("added job %s (%s)" % (click.style(job.name, bold=True), job.id))
+    click.echo("  trigger : %s" % (job.trigger.describe(),))
+    click.echo("  next run: %s" % (format_datetime(job.next_run_at) or "never",))
+
+
+@cli.command("list")
+@click.option("--tag", default=None, help="Only show jobs carrying this tag.")
+@click.option("--enabled/--disabled", "enabled", default=None, help="Filter by enabled state.")
+@click.option("--json", "as_json", is_flag=True, help="Emit JSON instead of a table.")
+@click.pass_context
+def list_command(
+    ctx: click.Context, tag: Optional[str], enabled: Optional[bool], as_json: bool
+) -> None:
+    """List registered jobs."""
+    store = _get_store(ctx)
+    jobs = store.get_jobs(enabled=enabled, tag=tag)
+    if as_json:
+        click.echo(json.dumps([job.to_dict() for job in jobs], indent=2, default=str))
+        return
+    _print_table(
+        ["ID", "NAME", "TRIGGER", "NEXT RUN", "ON", "STATUS", "OK/RUNS"],
+        [_job_row(job) for job in jobs],
+    )
+    click.echo("\n%d job(s)" % (len(jobs),))
+
+
+@cli.command("show")
+@click.argument("job_id")
+@click.option("--json", "as_json", is_flag=True, help="Emit JSON instead of text.")
+@click.pass_context
+def show_command(ctx: click.Context, job_id: str, as_json: bool) -> None:
+    """Show the full definition of one job."""
+    store = _get_store(ctx)
+    job = _resolve_job(store, job_id)
+    if as_json:
+        click.echo(json.dumps(job.to_dict(), indent=2, default=str))
+        return
+    data = job.to_dict()
+    data["trigger"] = job.trigger.describe()
+    for key in sorted(data):
+        click.echo("%-20s %s" % (key + ":", data[key]))
+
+
+@cli.command("remove")
+@click.argument("job_id")
+@click.option("--yes", is_flag=True, help="Skip the confirmation prompt.")
+@click.pass_context
+def remove_command(ctx: click.Context, job_id: str, yes: bool) -> None:
+    """Delete a job and its run history."""
+    store = _get_store(ctx)
+    job = _resolve_job(store, job_id)
+    if not yes:
+        click.confirm("remove job %s (%s)?" % (job.name, job.id[:8]), abort=True)
+    store.remove_job(job.id)
+    click.echo("removed %s" % (job.id,))
+
+
+@cli.command("pause")
+@click.argument("job_id")
+@click.pass_context
+def pause_command(ctx: click.Context, job_id: str) -> None:
+    """Disable a job without deleting it."""
+    from .core import JobStatus
+
+    store = _get_store(ctx)
+    job = _resolve_job(store, job_id)
+    job.enabled = False
+    job.status = JobStatus.PAUSED
+    store.update_job(job)
+    click.echo("paused %s" % (job.name,))
+
+
+@cli.command("resume")
+@click.argument("job_id")
+@click.pass_context
+def resume_command(ctx: click.Context, job_id: str) -> None:
+    """Re-enable a paused job and recompute its next run."""
+    from .core import JobStatus
+
+    store = _get_store(ctx)
+    job = _resolve_job(store, job_id)
+    job.enabled = True
+    job.status = JobStatus.PENDING
+    job.schedule_next(utcnow())
+    store.update_job(job)
+    click.echo("resumed %s, next run %s" % (job.name, format_datetime(job.next_run_at) or "never"))
+
+
+@cli.command("history")
+@click.argument("job_id", required=False)
+@click.option("--limit", type=int, default=20, show_default=True, help="Maximum rows to display.")
+@click.option("--json", "as_json", is_flag=True, help="Emit JSON instead of a table.")
+@click.pass_context
+def history_command(ctx: click.Context, job_id: Optional[str], limit: int, as_json: bool) -> None:
+    """Show recent run history, newest first."""
+    store = _get_store(ctx)
+    target = _resolve_job(store, job_id).id if job_id else None
+    runs: List[JobRun] = store.get_history(target, limit)
+    if as_json:
+        click.echo(json.dumps([run.to_dict() for run in runs], indent=2, default=str))
+        return
+    rows = [
+        [
+            run.id[:8],
+            _short(run.job_name or run.job_id[:8], 20),
+            format_datetime(run.started_at) or "-",
+            "%.3fs" % run.duration if run.duration is not None else "-",
+            str(run.status),
+            str(run.attempts),
+            _short(run.error, 40),
+        ]
+        for run in runs
+    ]
+    _print_table(["RUN", "JOB", "STARTED", "TOOK", "STATUS", "TRIES", "ERROR"], rows)
+
+
+@cli.command("clear")
+@click.option("--yes", is_flag=True, help="Skip the confirmation prompt.")
+@click.pass_context
+def clear_command(ctx: click.Context, yes: bool) -> None:
+    """Delete every job and run record in the store."""
+    store = _get_store(ctx)
+    if not yes:
+        click.confirm("delete ALL jobs and history from %s?" % (ctx.obj["db"],), abort=True)
+    count = store.clear()
+    click.echo("cleared %d job(s)" % (count,))
+
+
+@cli.command("run-now")
+@click.argument("job_id")
+@click.pass_context
+def run_now_command(ctx: click.Context, job_id: str) -> None:
+    """Execute a job immediately, ignoring its schedule."""
+    store = _get_store(ctx)
+    job = _resolve_job(store, job_id)
+    scheduler = AsyncScheduler(store=store)
+
+    async def _runner() -> JobRun:
+        await scheduler.start(paused=True)
+        try:
+            return await scheduler.run_job_now(job.id)
+        finally:
+            await scheduler.stop(wait=True)
+
+    run = asyncio.get_event_loop().run_until_complete(_runner()) if _loop_open() else asyncio.run(_runner())
+    click.echo("status  : %s" % (run.status,))
+    click.echo("duration: %s" % ("%.3fs" % run.duration if run.duration is not None else "-",))
+    if run.result:
+        click.echo("result  : %s" % (run.result,))
+    if run.error:
+        click.echo(click.style("error   : %s" % (run.error,), fg="red"))
+        raise SystemExit(1)
+
+
+def _loop_open() -> bool:
+    """True when a usable event loop is already installed in this thread."""
+    try:
+        loop = asyncio.get_event_loop()
+    except RuntimeError:
+        return False
+    return not loop.is_closed() and not loop.is_running()
+
+
+@cli.command("start")
+@click.option("--poll", type=float, default=1.0, show_default=True, help="Seconds between store polls.")
+@click.option("--concurrency", type=int, default=10, show_default=True, help="Maximum simultaneous jobs.")
+@click.option("--workers", type=int, default=8, show_default=True, help="Threads for sync callables.")
+@click.option("--grace", type=float, default=60.0, show_default=True, help="Default misfire grace window.")
+@click.option("--paused", is_flag=True, help="Start without dispatching until resumed.")
+@click.pass_context
+def start_command(
+    ctx: click.Context,
+    poll: float,
+    concurrency: int,
+    workers: int,
+    grace: float,
+    paused: bool,
+) -> None:
+    """Run the scheduler in the foreground until interrupted."""
+    store = _get_store(ctx)
+    try:
+        config = SchedulerConfig(
+            poll_interval=poll,
+            max_concurrent_jobs=concurrency,
+            worker_threads=workers,
+            misfire_grace_time=grace,
+        )
+    except ConfigurationError as exc:
+        raise _fail(str(exc))
+
+    scheduler = AsyncScheduler(store=store, config=config)
+
+    def _on_event(event: SchedulerEvent) -> None:
+        if event.type in (EventType.JOB_ERROR, EventType.JOB_MISSED):
+            logger.warning("event %s for job %s", event.type, event.job.name if event.job else "?")
+
+    scheduler.add_listener(_on_event)
+
+    async def _serve() -> None:
+        await scheduler.start(paused=paused)
+        loop = asyncio.get_event_loop()
+        stop_event = asyncio.Event()
+
+        def _request_stop() -> None:
+            logger.info("shutdown signal received")
+            stop_event.set()
+
+        for signal_name in ("SIGINT", "SIGTERM"):
+            handle = getattr(signal, signal_name, None)
+            if handle is None:
+                continue
+            try:
+                loop.add_signal_handler(handle, _request_stop)
+            except (NotImplementedError, RuntimeError):  # Windows
+                signal.signal(handle, lambda *_: _request_stop())
+        try:
+            await stop_event.wait()
+        finally:
+            await scheduler.stop(wait=True)
+
+    jobs = store.get_jobs(enabled=True)
+    click.echo("scheduler starting with %d enabled job(s) from %s" % (len(jobs), ctx.obj["db"]))
+    try:
+        asyncio.run(_serve())
+    except KeyboardInterrupt:  # pragma: no cover - defensive
+        click.echo("interrupted")
+    click.echo("scheduler stopped")
+
+
+@cli.command("next")
+@click.argument("job_id")
+@click.option("--count", type=int, default=5, show_default=True, help="How many fire times to preview.")
+@click.pass_context
+def next_command(ctx: click.Context, job_id: str, count: int) -> None:
+    """Preview upcoming fire times for a job without running it."""
+    if count <= 0:
+        raise _fail("--count must be positive")
+    store = _get_store(ctx)
+    job = _resolve_job(store, job_id)
+    cursor: Optional[datetime] = utcnow()
+    now = cursor
+    for index in range(count):
+        cursor = job.trigger.next_fire_time(cursor)
+        if cursor is None:
+            click.echo("%2d. no further runs" % (index + 1,))
+            break
+        click.echo("%2d. %s  (in %s)" % (index + 1, format_datetime(cursor), humanize_delta(cursor - now)))
+
+
+def main(argv: Optional[List[str]] = None) -> int:
+    """Console-script entry point."""
+    try:
+        cli.main(args=argv if argv is not None else sys.argv[1:], standalone_mode=False)
+    except click.ClickException as exc:
+        exc.show()
+        return exc.exit_code
+    except click.Abort:
+        click.echo("aborted", err=True)
+        return 130
+    except SchedulePlusError as exc:
+        click.echo("error: %s" % (exc,), err=True)
+        return 1
+    except SystemExit as exc:
+        return int(exc.code or 0)
+    return 0
+
+
+if __name__ == "__main__":  # pragma: no cover
+    sys.exit(main())