Metadata-Version: 2.3
Name: kicker
Version: 0.3.0
Summary: Lightweight job runner framework built on FastAPI and APScheduler with a simple web UI.
Author: Andrey Morozov
Author-email: Andrey Morozov <andrey@morozov.lv>
Requires-Dist: apscheduler>=3.11.2
Requires-Dist: fastapi>=0.136.1
Requires-Dist: uvicorn>=0.46.0
Requires-Python: >=3.14
Description-Content-Type: text/markdown

# kicker

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

## Features

* **FastAPI-style developer experience**
  * `app = Kicker()`
  * `@app.job(...)`
  * standard `uvicorn module:app`
* Schedule jobs with APScheduler
* Run jobs manually from UI
* Pause/resume scheduler and individual jobs
* Supports both sync and async functions
* Simple HTML interface

---

## Installation

```bash
uv add kicker
```

---

## Usage

Create a project and define your jobs:

```python
# main.py
from kicker import Kicker

kicker = Kicker()

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


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

To see logs in the UI, declare a `logger` parameter — kicker injects it automatically. Jobs without it work fine but won't produce UI logs.

## 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.

```python
# jobs/weekly_report.py
from kicker import Coworker

worker = Coworker()

@worker.kick(hour=8, minute=0)
async def weekly_report():
  ...
```

```python
# main.py
from kicker import Kicker
from jobs.weekly_report import worker

app = Kicker()
app.include_coworker(worker)
```

---

## Notes

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

---

## License

MIT
