Skip to main content

kicker

Lightweight job runner built on FastAPI and APScheduler with a simple web UI.

Features

  • FastAPI-style developer experience
    • app = Kicker()
    • @app.kick(...)
    • standard uvicorn module:app
  • Schedule jobs with APScheduler using decorators
  • Run jobs manually from UI
  • Pause/resume scheduler and individual jobs
  • Supports both sync and async functions
  • Simple HTML interface
  • Use multiple log outputs
  • Save execution state between job runs
  • Supports multiple named instances of the same job
  • Allows job-scoped setup/teardown using lifespan context manager
  • Provides event handlers like on_shutdown_requested and on_job_paused

Installation

uv add kicker

Usage

Create a project and define your jobs:

# main.py
from kicker import Kicker, JobContext

app = Kicker(logger_fmt="%(prefix)s[%(levelname)s] %(message)s at %(asctime)s")


@app.kick(day_of_week="mon-fri", hour="9-20/2", minute=0)
async def job_echo(ctx: JobContext):
    ctx.logger.info("job_echo executed")


# run the app
# uv run uvicorn package.module:app --reload

To see logs in the UI, use ctx.logger. Jobs that never log still run fine, but they will not produce UI output.

Splitting jobs across files

Like FastAPI's APIRouter, Coworker lets you define jobs in separate files and include them in the main app — no circular imports, no shared app instance.

# jobs/weekly_report.py
from kicker import Coworker, JobContext

worker = Coworker()


@worker.kick(hour=8, minute=0)
async def weekly_report(ctx: JobContext):
    ctx.logger.info("weekly_report executed")
# main.py
from kicker import Kicker
from jobs.weekly_report import worker

app = Kicker()
app.include_coworker(worker)

Adding multiple log outputs

It is possible to have multiple visual log output "containers". By default, the default output container is used. To send logs to a different output container, pass the standard extra keyword argument to the logger method you use (error in this example) with an output key and a string value as the new container name:

from kicker import Kicker, JobContext

app = Kicker()


@app.kick(second="*/5")
def sync_job(ctx: JobContext):
    try:
        ...
    except:
        ctx.logger.error(
            "error in a sync job executed in the thread pool",
            extra={"output": "errors"},
        )

or, cleaner with partial:

from functools import partial

from kicker import Kicker, JobContext

app = Kicker()


@app.kick(second="*/5")
def sync_job(ctx: JobContext):
    log_error = partial(ctx.logger.error, extra={"output": "errors"})
    try:
        ...
    except:
        log_error("error in a sync job executed in the thread pool")

Getting access to the scheduler and the job

Along with the logger, kicker also injects the scheduler object and the job_id of the current job. This is useful for managing jobs — for example, you can change the next run time of the current job:

from datetime import datetime, timedelta
from functools import partial

from kicker import Kicker, JobContext

app = Kicker()


@app.kick(second="*/5")
def sync_job(ctx: JobContext):
    log_debug = partial(ctx.logger.debug, extra={"output": "debug"})
    slowdown_interval_minutes = 10
    try:
        ...
    except Exception as e:
        ctx.scheduler.modify_job(
            ctx.job_id,
            next_run_time=datetime.now() + timedelta(minutes=slowdown_interval_minutes),
        )
        log_debug(f"error: {e} - slowing down for {slowdown_interval_minutes} minutes")

Save execution state between job runs

You can save arbitrary data in ctx.storage between job runs.

from kicker import Coworker, JobContext

worker = Coworker()


@worker.kick(second="*/6")
async def very_important_job_with_runs_counter(ctx: JobContext):
    counter = ctx.storage.get("counter", 0)
    ctx.logger.info(f"important job executed ({counter}) times")
    ctx.storage["counter"] = counter + 1

Run multiple named instances of the same job

It is possible to specify an instance name when including a coworker:

from kicker import Kicker
from jobs.weekly_report import worker

app = Kicker()
app.include_coworker(worker)  # default instance
app.include_coworker(worker, instance="v2")

or just directly in the job decorator:

from datetime import datetime, timedelta
from functools import partial

from kicker import Kicker, JobContext

app = Kicker()


def same_business_logic(ctx: JobContext):
    ctx.logger.info(
        f"sync job {ctx.instance} executed in the thread pool with a very long message",
        extra={"output": "sync_job"},
    )


@app.kick(second="*/5")
def sync_job1(ctx: JobContext):
    same_business_logic(ctx)


@app.kick(second="*/4", instance="v2")
def sync_job2(ctx: JobContext):
    same_business_logic(ctx)

Visible job execution status with color intensity

You can report failure or success job execution status to the UI. The status will be displayed with a green or red dot next to the job name.

The script below shows how to report job execution status with a color intensity. Every error has a cooldown interval, which keeps the error visible for that period, but with reduced intensity.

from datetime import datetime, UTC
from kicker import Coworker, JobContext

worker = Coworker()
FAILURE_COOLDOWN_MINUTES = 5
DEFAULT_ERROR_INTENSITY = 100


@worker.kick(second="*/30")
async def some_job(ctx: JobContext):
    try:
        ...
    except Exception:
        ctx.report_execution_status("failure", DEFAULT_ERROR_INTENSITY)
        ctx.storage["error_intensity"] = DEFAULT_ERROR_INTENSITY
        ctx.storage["last_error_time"] = datetime.now(UTC)
    else:
        if (
            datetime.now(UTC) - ctx.storage.get("last_error_time", datetime.min)
        ).total_seconds() > FAILURE_COOLDOWN_MINUTES * 60:
            ctx.report_execution_status("success")
        else:
            saved_intensity = ctx.storage.get(
                "error_intensity", DEFAULT_ERROR_INTENSITY
            )
            reduced_intensity = min(0, saved_intensity - 10)
            ctx.report_execution_status("failure", reduced_intensity)
            ctx.storage["error_intensity"] = reduced_intensity

Worker setup/teardown using a lifespan context manager

If a job needs shared setup and teardown for all of its executions (for example a database engine), you can pass a lifespan context manager to @kick or include_coworker. Setup runs once when the app starts, before jobs run. Teardown runs on shutdown after in-flight jobs finish and the scheduler has stopped. A job-level lifespan overrides a coworker-level one. Sync and async context managers are both supported.

from contextlib import asynccontextmanager

from sqlalchemy import text
from sqlalchemy.exc import SQLAlchemyError
from sqlalchemy.ext.asyncio import create_async_engine

from kicker import Coworker, JobContext

worker = Coworker()


@asynccontextmanager
async def db_lifespan(ctx: JobContext):
    engine = create_async_engine(
        "postgresql+asyncpg://user:password@localhost/db",
        echo=True,
    )
    ctx.storage["db_engine"] = engine
    ctx.logger.info("engine created")
    try:
        yield
    finally:
        await engine.dispose()
        del ctx.storage["db_engine"]


@worker.kick(second="*/6", lifespan=db_lifespan)
async def test_db_access(ctx: JobContext):
    engine = ctx.storage["db_engine"]
    try:
        async with engine.begin() as trn:
            await trn.execute(
                text(
                    "insert into table_name (column_name) select max(column_name)+1 from table_name"
                )
            )
        ctx.logger.info("inserted")
    except SQLAlchemyError as e:
        ctx.logger.error(f"Error occurred: {e}")

Various event handlers

from kicker import Coworker, JobContext

worker = Coworker()


async def on_paused(ctx: JobContext):
    ctx.logger.info("I'm paused!")
    
async def on_system_shutdown(ctx: JobContext):
    ctx.logger.info("The system is about to be shut down!")

@worker.kick(second="*/6", 
             on_shutdown_requested=on_system_shutdown, 
             on_job_paused=on_paused)
async def test_on_pause(ctx: JobContext):
    ctx.logger.info("I'm working!")

Notes

  • Scheduler runs in-process (not distributed)
  • Running with multiple workers will duplicate job execution
  • Designed for simple internal tools and automation

License

MIT

Metadata

Release files for kicker 1.4.2

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for kicker 1.4.2
File Size Uploaded Provenance Actions
kicker-1.4.2.tar.gz 11.0 kB Without provenance Details for kicker-1.4.2.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for kicker 1.4.2
File Interpreter ABI Platform Actions
kicker-1.4.2-py3-none-any.whl Python 3 none any Details for kicker-1.4.2-py3-none-any.whl

Total release size: 24.4 kB

Release files / kicker-1.4.2.tar.gz

Download URL kicker-1.4.2.tar.gz
Size 11.0 kB
Tags Source
SHA-256 checksum
How to use checksums
90a3e7b9542933f81f1196d9ded40f35308c7455b83b4c82fb45a023392b82f7
BLAKE2b-256 checksum
How to use checksums
978ffb002b4253f70319cac6d757883ebfa6f9b64f46be9a68e98cf5b03b43f1
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via uv/0.10.4 {"installer":{"name":"uv","version":"0.10.4","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Linux Mint","version":"22.3","id":"zena","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}

Release files / kicker-1.4.2-py3-none-any.whl

Download URL kicker-1.4.2-py3-none-any.whl
Size 13.4 kB
Tags Python 3
SHA-256 checksum
How to use checksums
08e72cc417ee6391e4777cdbd9ead1f090785f56c66b038f9f550cc85b415802
BLAKE2b-256 checksum
How to use checksums
a9e7f368cfd0c906e1f5b40aefd2f451375f3d89d5c689ebe3f96871f38a6e5f
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via uv/0.10.4 {"installer":{"name":"uv","version":"0.10.4","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Linux Mint","version":"22.3","id":"zena","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}

Security for kicker 1.4.2

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page