{"id":29385578,"url":"https://github.com/me-umar/fastapi-crons","last_synced_at":"2026-01-08T19:21:41.502Z","repository":{"id":292628399,"uuid":"981468868","full_name":"mE-uMAr/fastapi-crons","owner":"mE-uMAr","description":"fastapi-crons is a FastAPI extension for running cron jobs and background tasks in a clean, reliable way with async support and syntyx just like fastapi.","archived":false,"fork":false,"pushed_at":"2025-06-04T01:23:58.000Z","size":24,"stargazers_count":17,"open_issues_count":0,"forks_count":7,"subscribers_count":3,"default_branch":"main","last_synced_at":"2025-06-04T08:45:00.548Z","etag":null,"topics":["asyncio","background-tasks","cron","crons","fastapi","fastapi-crons","schedular"],"latest_commit_sha":null,"homepage":"https://crons.meharumar.codes","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mE-uMAr.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-05-11T07:12:13.000Z","updated_at":"2025-06-04T01:23:59.000Z","dependencies_parsed_at":null,"dependency_job_id":"3b469ac1-09da-4802-ab0e-24fbc4c93277","html_url":"https://github.com/mE-uMAr/fastapi-crons","commit_stats":null,"previous_names":["me-umar/fastapi-crons"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/mE-uMAr/fastapi-crons","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mE-uMAr%2Ffastapi-crons","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mE-uMAr%2Ffastapi-crons/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mE-uMAr%2Ffastapi-crons/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mE-uMAr%2Ffastapi-crons/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mE-uMAr","download_url":"https://codeload.github.com/mE-uMAr/fastapi-crons/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mE-uMAr%2Ffastapi-crons/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":264473846,"owners_count":23613957,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["asyncio","background-tasks","cron","crons","fastapi","fastapi-crons","schedular"],"created_at":"2025-07-10T05:01:48.098Z","updated_at":"2026-01-04T14:14:02.126Z","avatar_url":"https://github.com/mE-uMAr.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"[![Python CI](https://github.com/me-umar/fastapi-crons/actions/workflows/ci.yml/badge.svg)](https://github.com/me-umar/fastapi-crons/actions/workflows/ci.yml)\n[![PyPI - Version](https://img.shields.io/pypi/v/fastapi-crons)](https://pypi.org/project/fastapi-crons/)\n[![GitHub Release](https://img.shields.io/github/v/release/me-umar/fastapi-crons)](https://github.com/me-umar/fastapi-crons/releases)\n\n\u003ch1                                                                                                                                                           \n                                                                                                                                                                align=\"center\"\u003e\u003cstrong\u003eFASTAPI-CRONS\u003c/strong\u003e\u003c/h1\u003e\n\n\n\u003cp align=\"center\"\u003e\u003cem\u003eEffortlessly schedule and manage your background tasks.\u003c/em\u003e\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"https://img.shields.io/badge/last%20commit-may-informational?style=flat-square\" /\u003e\n  \u003cimg src=\"https://img.shields.io/badge/python-100%25-blue?style=flat-square\" /\u003e\n  \u003cimg src=\"https://img.shields.io/badge/languages-1-blue?style=flat-square\" /\u003e\n\u003c/p\u003e\n\n\u003cbr/\u003e\n\n\u003cp align=\"center\"\u003e\u003cem\u003eBuilt with the tools and technologies:\u003c/em\u003e\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"https://img.shields.io/badge/-Markdown-000000?style=flat-square\u0026logo=markdown\" /\u003e\n  \u003cimg src=\"https://img.shields.io/badge/-Typer-000000?style=flat-square\u0026logo=python\" /\u003e\n  \u003cimg src=\"https://img.shields.io/badge/-TOML-bc4c3f?style=flat-square\" /\u003e\n  \u003cimg src=\"https://img.shields.io/badge/-FastAPI-009688?style=flat-square\u0026logo=fastapi\" /\u003e\n  \u003cimg src=\"https://img.shields.io/badge/-Python-306998?style=flat-square\u0026logo=python\" /\u003e\n  \u003cimg src=\"https://img.shields.io/badge/-AIOHTTP-2c5282?style=flat-square\" /\u003e\n  \u003cimg src=\"https://img.shields.io/badge/-Pydantic-d6336c?style=flat-square\" /\u003e\n\u003c/p\u003e\n\n\u003ch1 align=\"center\"\u003eFastAPI Crons – Developer Guide\u003c/h1\u003e\n\nWelcome to the official guide for using `fastapi_crons`, a high-performance, developer-friendly cron scheduling extension for FastAPI. This library enables you to define, monitor, and control scheduled background jobs using simple decorators and provides CLI tools, web-based monitoring, and SQLite-based job tracking.\n\n---\n\n## 🚀 Features\n\n* Native integration with FastAPI using `from fastapi import FastAPI, Crons`\n* Define cron jobs with decorators\n* Async + sync job support\n* SQLite job state persistence\n* CLI for listing and managing jobs\n* Automatic monitoring endpoint (`/crons`)\n* Named jobs, tags, and metadata\n* Easy to plug into any FastAPI project\n\n---\n\n## 📦 Installation\n\n```bash\npip install fastapi-crons\n```\n\n---\n\n## 🛠️ Quick Start\n\n### 1. Setup FastAPI with Crons\n\n```python\nfrom fastapi import FastAPI\nfrom fastapi_crons import Crons, get_cron_router\n\napp = FastAPI()\ncrons = Crons(app)\n\napp.include_router(get_cron_router())\n\n@app.get(\"/\")\ndef root():\n    return {\"message\": \"Hello from FastAPI\"}\n\n```\n\n### 2. Define Cron Jobs\n\n```python\n@crons.cron(\"*/5 * * * *\", name=\"print_hello\")\ndef print_hello():\n    print(\"Hello! I run every 5 minutes.\")\n\n@crons.cron(\"0 0 * * *\", name=\"daily_task\", tags=[\"rewards\"])\nasync def run_daily_task():\n    # Distribute daily rewards or any async task\n    await some_async_function()\n```\n## Cron Expression overview\n```bash\n┌───────────── minute (0 - 59)\n│ ┌───────────── hour (0 - 23)\n│ │ ┌───────────── day of the month (1 - 31)\n│ │ │ ┌───────────── month (1 - 12)\n│ │ │ │ ┌───────────── day of the week (0 - 6) (Sunday to Saturday)\n│ │ │ │ │\n* * * * *\n```\n#### Examples:\n- `* * * * *`: Every minute\n- `*/15 * * * *`: Every 15 minutes\n- `0 * * * *`: Every hour\n- `0 0 * * *`: Every day at midnight\n- `0 0 * * 0`: Every Sunday at midnight\n---\n\n## 🖥️ Cron Monitoring Endpoint\n\nOnce included, visit:\n\n```\nGET /crons\n```\n\nYou'll get a full list of jobs with:\n\n* `name`\n* `expr` (cron expression)\n* `tags`\n* `last_run` (from SQLite)\n* `next_run`\n\n---\n\n## 🧩 SQLite Job State Tracking\n\nWe use SQLite (via `aiosqlite`) to keep a persistent record of when each job last ran. This allows observability and resilience during restarts.\n\n### Table:\n\n```sql\nCREATE TABLE IF NOT EXISTS job_state (\n    name TEXT PRIMARY KEY,\n    last_run TEXT\n);\n```\n### Configuration\nBy default, job state is stored in a SQLite database named `cron_state.db` in the current directory. You can customize the database path:\n```python\nfrom fastapi_cron import Crons, SQLiteStateBackend\n\n# Custom database path\nstate_backend = SQLiteStateBackend(db_path=\"/path/to/my_crons.db\")\ncrons = Crons(state_backend=state_backend)\n```\n\n---\n\n## 🧵 Async + Thread Execution\n\nThe scheduler supports both async and sync job functions\nJobs can be:\n\n* `async def` → run in asyncio loop\n* `def` → run safely in background thread using `await asyncio.to_thread(...)`\n\n---\n\n## 🧪 CLI Support\n\n```bash\n# List all registered jobs\nfastapi_cron list\n\n# Manually run a specific job\nfastapi_cron run_job \u003c job_name \u003e\n```\n\n\u003e\n\n---\n## 🧩 Advanced Features\n\n* Distributed locking via Redis\n* Retry policies\n* Manual run triggers via HTTP\n* Admin dashboard with metrics\n\n### Job Tags\n\nYou can add tags to jobs for better organization:\n```python\n@cron_job(\"*/5 * * * *\", tags=[\"maintenance\", \"cleanup\"])\nasync def cleanup_job():\n    # This job has tags for categorization\n    pass\n```\n\n---\n\n## ⚙️ Architecture Overview\n\n```\nFastAPI App\n│\n├── Crons()\n│   ├── Registers decorated jobs\n│   ├── Starts background scheduler (async)\n│\n├── SQLite Backend\n│   ├── Tracks last run for each job\n│\n├── /crons endpoint\n│   ├── Shows current job status (with timestamps)\n│\n└── CLI Tool\n    ├── List jobs / Run manually\n```\n\n---\n\n## 🧠 Contributing\n\nWe welcome PRs and suggestions! If you'd like this added to FastAPI officially, fork the repo, polish it, and submit to FastAPI with a clear integration proposal.\n\n---\n\n## 🛡️ Error Handling\n\n* Each job has an isolated error handler\n* Errors are printed and don't block scheduler\n* Future: Add error logging / alert hooks\n\n---\n\n## 📄 License\n\n[Licence](LICENSE)\n\n---\n\n#### Need help? Reach out:\n[Email me](mailto:contact@meharumar.codes)\n\n[github](https://github.com/me-umar)\n\n## Read Documentation at:\n[Documentation](https://crons.meharumar.codes)\n---\n## 💬 Credits\n\nMade with ❤️ by Mehar Umar.  \nDesigned to give developers freedom, flexibility, and control when building production-grade FastAPI apps.\n\n---\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fme-umar%2Ffastapi-crons","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fme-umar%2Ffastapi-crons","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fme-umar%2Ffastapi-crons/lists"}