kiba-core 0.5.3.dev69__tar.gz → 0.5.3.dev70__tar.gz

{kiba_core-0.5.3.dev69 → kiba_core-0.5.3.dev70}/CHANGELOG.md

@@ -8,6 +8,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/)
 ## [Unreleased]
 
 ### Added
+- [MINOR] Added `core.cron` (install with the `cron` extra): `CronJob` schedules (interval with jitter, or crontab) that declare a `jobType`, `CronJobProcessor`s that declare the `jobTypes` they process, and `CronExecutor`, which takes a list of processors, routes each job to the processor for its type (failing at startup if a job type has no processor or more than one), runs jobs on an APScheduler scheduler, logs each run as a `CRON` api log with its status and duration, and keeps running when a job fails; also added `ApiRequestCronJob` with `ApiRequestCronJobProcessor` (needs the `requester` extra) for jobs that call a URL
 - [MAJOR] Updated `Requester` to raise `RequesterTimeoutException` (a `GatewayTimeoutException`, 504) instead of `httpx` timeout exceptions; it carries the method, the URL without credentials or query string, the timeout, how long the request ran and the `httpx` timeout type, and keeps the original exception as its cause. Code catching `httpx.TimeoutException` (or `ReadTimeout`, `ConnectTimeout`, …) around `Requester` calls must catch `RequesterTimeoutException` instead
 - [PATCH] Updated `MessageQueueProcessor` failure notifications to show the exception type before its message, so failures from exceptions without text (e.g. `httpx` timeouts) are still identifiable
 - [MINOR] Added `authorize_bearer_jwt_request` for validating bearer JWTs in `RouteAuthResolver` implementations; it and `authorize_bearer_jwt` now only strip the leading `Bearer ` prefix, let cancellation propagate, and log why a JWT was rejected

{kiba_core-0.5.3.dev69 → kiba_core-0.5.3.dev70}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: kiba-core
-Version: 0.5.3.dev69
+Version: 0.5.3.dev70
 Summary: Kiba Labs' python utilities
 Project-URL: repository, https://github.com/kibalabs/core-py
 Requires-Python: <4,>=3.12
@@ -34,6 +34,8 @@ Provides-Extra: requester
 Requires-Dist: httpx2>=2.13.0; extra == "requester"
 Provides-Extra: web3
 Requires-Dist: web3<8.0.0,>=7.16.0; extra == "web3"
+Provides-Extra: cron
+Requires-Dist: apscheduler<4,>=3.11.0; extra == "cron"
 Provides-Extra: types
 Requires-Dist: types-aiobotocore[essential]>=3.9.1; extra == "types"
 Requires-Dist: types-aiofiles>=25.1.0.20260518; extra == "types"

kiba_core-0.5.3.dev70/core/cron/api_request_cron_job_processor.py

@@ -0,0 +1,34 @@
+from typing import ClassVar
+
+from core.cron.cron_job_processor import CronJobProcessor
+from core.cron.model import CronJob
+from core.exceptions import KibaException
+from core.requester import Requester
+from core.util.typing_util import Json
+
+
+class ApiRequestCronJob(CronJob):
+    jobType: ClassVar[str] = 'api_request'
+    method: str
+    url: str
+    dataDict: Json | None = None
+    headers: dict[str, str] | None = None
+    timeout: int | None = None
+
+    @property
+    def query(self) -> dict[str, str]:
+        if not isinstance(self.dataDict, dict):
+            return {}
+        return {key: str(value) for key, value in self.dataDict.items() if isinstance(value, str | int | float | bool)}
+
+
+class ApiRequestCronJobProcessor(CronJobProcessor):
+    jobTypes: ClassVar[frozenset[str]] = frozenset({ApiRequestCronJob.jobType})
+
+    def __init__(self, requester: Requester) -> None:
+        self.requester = requester
+
+    async def process_job(self, job: CronJob) -> None:
+        if not isinstance(job, ApiRequestCronJob):
+            raise KibaException(message=f'{type(self).__name__} cannot process {type(job).__name__}')
+        await self.requester.make_request(method=job.method, url=job.url, dataDict=job.dataDict, headers=job.headers, timeout=job.timeout)

kiba_core-0.5.3.dev70/core/cron/cron_executor.py

@@ -0,0 +1,68 @@
+import asyncio
+import datetime
+import time
+import urllib.parse as urlparse
+from collections.abc import Sequence
+
+from apscheduler.schedulers.asyncio import AsyncIOScheduler  # type: ignore[import-untyped]
+from apscheduler.triggers.cron import CronTrigger  # type: ignore[import-untyped]
+from apscheduler.triggers.interval import IntervalTrigger  # type: ignore[import-untyped]
+
+from core import logging
+from core.cron.cron_job_processor import CronJobProcessor
+from core.cron.model import CronJob
+from core.exceptions import KibaException
+
+# NOTE(krishan711): interval jobs are anchored to a fixed date so a restart keeps the same schedule instead of restarting every interval from boot
+INTERVAL_START_DATE = datetime.datetime(2025, 1, 1, tzinfo=datetime.UTC)
+
+
+class CronExecutor:
+    def __init__(self, jobs: Sequence[CronJob], jobProcessors: Sequence[CronJobProcessor]) -> None:
+        self.jobs = jobs
+        self.processorByJobType: dict[str, CronJobProcessor] = {}
+        for jobProcessor in jobProcessors:
+            for jobType in jobProcessor.jobTypes:
+                existingProcessor = self.processorByJobType.get(jobType)
+                if existingProcessor is not None:
+                    raise KibaException(message=f'Cron job type {jobType} is handled by both {type(existingProcessor).__name__} and {type(jobProcessor).__name__}')
+                self.processorByJobType[jobType] = jobProcessor
+        unprocessableJobNames = [job.name for job in jobs if job.jobType not in self.processorByJobType]
+        if unprocessableJobNames:
+            raise KibaException(message=f'No cron job processor for jobs: {", ".join(unprocessableJobNames)}')
+        self.scheduler = AsyncIOScheduler()
+
+    async def execute_job(self, job: CronJob) -> None:
+        path = job.name.replace(' ', '_').replace(':', '_').lower()
+        query = urlparse.urlencode(job.query, doseq=True)
+        logging.api(action='CRON', path=path, pathPattern=path, query=query)
+        startTime = time.time()
+        statusCode = 200
+        try:
+            await self.processorByJobType[job.jobType].process_job(job=job)
+        except Exception as exception:  # noqa: BLE001
+            statusCode = exception.statusCode if isinstance(exception, KibaException) else 500
+            logging.error('Caught exception whilst processing cron job:')
+            logging.exception(exception)
+        duration = time.time() - startTime
+        logging.api(action='CRON', path=path, pathPattern=path, query=query, response=statusCode, duration=duration)
+
+    def _build_trigger(self, job: CronJob) -> CronTrigger | IntervalTrigger:
+        if job.crontab:
+            return CronTrigger.from_crontab(expr=job.crontab)
+        return IntervalTrigger(weeks=job.weeks, days=job.days, hours=job.hours, minutes=job.minutes, seconds=job.seconds, jitter=job.jitter, start_date=INTERVAL_START_DATE)
+
+    async def start(self) -> None:
+        logging.info(f'Initializing CronExecutor with {len(self.jobs)} jobs')
+        for job in self.jobs:
+            self.scheduler.add_job(func=self.execute_job, kwargs={'job': job}, trigger=self._build_trigger(job=job), id=job.name, name=job.name, replace_existing=True)
+        self.scheduler.start()
+        logging.info('CronExecutor started successfully')
+
+    async def run(self) -> None:
+        await self.start()
+        try:
+            await asyncio.Event().wait()
+        finally:
+            logging.info('Shutting down scheduler...')
+            self.scheduler.shutdown()

kiba_core-0.5.3.dev70/core/cron/cron_job_processor.py

@@ -0,0 +1,13 @@
+import abc
+from abc import ABC
+from typing import ClassVar
+
+from core.cron.model import CronJob
+
+
+class CronJobProcessor(ABC):
+    jobTypes: ClassVar[frozenset[str]]
+
+    @abc.abstractmethod
+    async def process_job(self, job: CronJob) -> None:
+        raise NotImplementedError

kiba_core-0.5.3.dev70/core/cron/model.py

@@ -0,0 +1,19 @@
+from typing import ClassVar
+
+from pydantic import BaseModel
+
+
+class CronJob(BaseModel):
+    jobType: ClassVar[str]
+    name: str
+    weeks: int = 0
+    days: int = 0
+    hours: int = 0
+    minutes: int = 0
+    seconds: int = 0
+    jitter: int = 0
+    crontab: str | None = None
+
+    @property
+    def query(self) -> dict[str, str]:
+        return {}

{kiba_core-0.5.3.dev69 → kiba_core-0.5.3.dev70}/kiba_core.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: kiba-core
-Version: 0.5.3.dev69
+Version: 0.5.3.dev70
 Summary: Kiba Labs' python utilities
 Project-URL: repository, https://github.com/kibalabs/core-py
 Requires-Python: <4,>=3.12
@@ -34,6 +34,8 @@ Provides-Extra: requester
 Requires-Dist: httpx2>=2.13.0; extra == "requester"
 Provides-Extra: web3
 Requires-Dist: web3<8.0.0,>=7.16.0; extra == "web3"
+Provides-Extra: cron
+Requires-Dist: apscheduler<4,>=3.11.0; extra == "cron"
 Provides-Extra: types
 Requires-Dist: types-aiobotocore[essential]>=3.9.1; extra == "types"
 Requires-Dist: types-aiofiles>=25.1.0.20260518; extra == "types"

{kiba_core-0.5.3.dev69 → kiba_core-0.5.3.dev70}/kiba_core.egg-info/SOURCES.txt

@@ -40,6 +40,11 @@ core/caching/__init__.py
 core/caching/cache.py
 core/caching/dict_cache.py
 core/caching/file_cache.py
+core/cron/__init__.py
+core/cron/api_request_cron_job_processor.py
+core/cron/cron_executor.py
+core/cron/cron_job_processor.py
+core/cron/model.py
 core/http/__init__.py
 core/http/basic_authentication.py
 core/http/jwt.py
@@ -104,6 +109,8 @@ tests/api/test_route.py
 tests/api/test_streaming_json_route.py
 tests/caching/test_dict_cache.py
 tests/caching/test_file_cache.py
+tests/cron/__init__.py
+tests/cron/test_cron_executor.py
 tests/locks/test_sql_lock.py
 tests/queues/conftest.py
 tests/queues/test_aqs_queue.py

{kiba_core-0.5.3.dev69 → kiba_core-0.5.3.dev70}/kiba_core.egg-info/requires.txt

@@ -10,6 +10,9 @@ uvicorn[standard]>=0.53.0
 starlette>=1.6.0
 uvicorn[standard]>=0.53.0
 
+[cron]
+apscheduler<4,>=3.11.0
+
 [database-psql]
 sqlalchemy[asyncio]>=2.0.54
 asyncpg>=0.31.0

{kiba_core-0.5.3.dev69 → kiba_core-0.5.3.dev70}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "kiba-core"
-version = "0.5.3.dev69"
+version = "0.5.3.dev70"
 description = "Kiba Labs' python utilities"
 readme = "README.md"
 requires-python = ">=3.12, <4"
@@ -49,6 +49,9 @@ requester = [
 web3 = [
     "web3>=7.16.0,<8.0.0",
 ]
+cron = [
+    "apscheduler>=3.11.0,<4",
+]
 types = [
     "types-aiobotocore[essential]>=3.9.1",
     "types-aiofiles>=25.1.0.20260518",

kiba_core-0.5.3.dev70/tests/cron/test_cron_executor.py

@@ -0,0 +1,75 @@
+from typing import ClassVar
+
+import pytest
+
+from core.cron.cron_executor import CronExecutor
+from core.cron.cron_job_processor import CronJobProcessor
+from core.cron.model import CronJob
+from core.exceptions import KibaException
+
+
+class EmailCronJob(CronJob):
+    jobType: ClassVar[str] = 'email'
+
+
+class ReportCronJob(CronJob):
+    jobType: ClassVar[str] = 'report'
+
+
+class RecordingProcessor(CronJobProcessor):
+    def __init__(self, failingJobNames: frozenset[str] = frozenset()) -> None:
+        self.failingJobNames = failingJobNames
+        self.processedJobNames: list[str] = []
+
+    async def process_job(self, job: CronJob) -> None:
+        self.processedJobNames.append(job.name)
+        if job.name in self.failingJobNames:
+            raise ValueError(f'{job.name} failed')
+
+
+class EmailProcessor(RecordingProcessor):
+    jobTypes: ClassVar[frozenset[str]] = frozenset({EmailCronJob.jobType})
+
+
+class ReportProcessor(RecordingProcessor):
+    jobTypes: ClassVar[frozenset[str]] = frozenset({ReportCronJob.jobType})
+
+
+class EmailAndReportProcessor(RecordingProcessor):
+    jobTypes: ClassVar[frozenset[str]] = frozenset({EmailCronJob.jobType, ReportCronJob.jobType})
+
+
+@pytest.mark.asyncio
+async def test_jobs_are_routed_to_the_processor_for_their_type() -> None:
+    emailProcessor = EmailProcessor()
+    reportProcessor = ReportProcessor()
+    emailJob = EmailCronJob(name='send-emails', minutes=1)
+    reportJob = ReportCronJob(name='build-report', minutes=1)
+    executor = CronExecutor(jobs=[emailJob, reportJob], jobProcessors=[emailProcessor, reportProcessor])
+
+    await executor.execute_job(job=reportJob)
+    await executor.execute_job(job=emailJob)
+
+    assert (emailProcessor.processedJobNames, reportProcessor.processedJobNames) == (['send-emails'], ['build-report'])
+
+
+@pytest.mark.asyncio
+async def test_failing_job_does_not_stop_later_jobs() -> None:
+    processor = EmailProcessor(failingJobNames=frozenset({'first'}))
+    first, second = EmailCronJob(name='first', minutes=1), EmailCronJob(name='second', minutes=1)
+    executor = CronExecutor(jobs=[first, second], jobProcessors=[processor])
+
+    await executor.execute_job(job=first)
+    await executor.execute_job(job=second)
+
+    assert processor.processedJobNames == ['first', 'second']
+
+
+def test_job_without_a_processor_fails_at_startup() -> None:
+    with pytest.raises(KibaException, match='No cron job processor for jobs: build-report'):
+        CronExecutor(jobs=[ReportCronJob(name='build-report', minutes=1)], jobProcessors=[EmailProcessor()])
+
+
+def test_job_type_claimed_by_two_processors_fails_at_startup() -> None:
+    with pytest.raises(KibaException, match='Cron job type email is handled by both'):
+        CronExecutor(jobs=[], jobProcessors=[EmailProcessor(), EmailAndReportProcessor()])

{kiba_core-0.5.3.dev69 → kiba_core-0.5.3.dev70}/uv.lock

@@ -204,6 +204,18 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/12/b8/4bd346e22b28902df4d651910f5242c28d84e4a5c2435ca5c3f797ed7e2e/anyio-4.15.1-py3-none-any.whl", hash = "sha256:6152fdbbf9a77fdec97731721bebf7c4c44f7c29b424b0065826173efc7ed101", size = 132079, upload-time = "2026-09-05T10:42:37.923Z" },
 ]
 
+[[package]]
+name = "apscheduler"
+version = "3.11.3"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "tzlocal" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/8c/6b/eeff360196bb20b312c9e762a820fd1b2c6d809466c755ef57863478e454/apscheduler-3.11.3.tar.gz", hash = "sha256:cd2fcc9330039a81a5893472ad49facf23a6d5604cbe1d918c835c6de7834d5a", size = 110312, upload-time = "2026-06-28T19:39:22.493Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/42/c9/8638db32514dbb9157b3d82680c6faea89283523edf9ed2415ea3884f2ae/apscheduler-3.11.3-py3-none-any.whl", hash = "sha256:bbeb2ec02d23d3c06a6c07ed7f0f3939ada6680eb121fae809a69bb42c537a30", size = 66024, upload-time = "2026-06-28T19:39:20.982Z" },
+]
+
 [[package]]
 name = "ast-serialize"
 version = "0.11.2"
@@ -1499,6 +1511,9 @@ core-api = [
     { name = "starlette" },
     { name = "uvicorn", extra = ["standard"] },
 ]
+cron = [
+    { name = "apscheduler" },
+]
 database-psql = [
     { name = "asyncpg" },
     { name = "sqlalchemy", extra = ["asyncio"] },
@@ -1545,6 +1560,7 @@ requires-dist = [
     { name = "aiobotocore", marker = "extra == 'storage'", specifier = ">=3.9.1" },
     { name = "aiofiles", specifier = ">=25.1.0" },
     { name = "aiosqlite", marker = "extra == 'database-sqlite'", specifier = ">=0.22.1" },
+    { name = "apscheduler", marker = "extra == 'cron'", specifier = ">=3.11.0,<4" },
     { name = "asyncpg", marker = "extra == 'database-psql'", specifier = ">=0.31.0" },
     { name = "azure-cosmos", marker = "extra == 'queue-cosmos'", specifier = ">=4.17.0" },
     { name = "azure-storage-queue", extras = ["aio"], marker = "extra == 'queue-aqs'", specifier = ">=12.17.0" },
@@ -1561,7 +1577,7 @@ requires-dist = [
     { name = "uvicorn", extras = ["standard"], marker = "extra == 'core-api'", specifier = ">=0.53.0" },
     { name = "web3", marker = "extra == 'web3'", specifier = ">=7.16.0,<8.0.0" },
 ]
-provides-extras = ["api", "core-api", "storage", "queues", "queue-sqs", "queue-aqs", "queue-cosmos", "database-psql", "database-sqlite", "requester", "web3", "types"]
+provides-extras = ["api", "core-api", "storage", "queues", "queue-sqs", "queue-aqs", "queue-cosmos", "database-psql", "database-sqlite", "requester", "web3", "cron", "types"]
 
 [package.metadata.requires-dev]
 dev = [{ name = "kiba-build", specifier = "==0.1.11.dev15" }]
@@ -2995,6 +3011,27 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/67/81/4add07e5172b7ac40d8ed5ff580409a7801a4fe26d529bdd915401dabfbe/typing_inspection-0.4.4-py3-none-any.whl", hash = "sha256:65b8397ba37ccbce054456aaccddfc91e6e3083c92824df348d96ca832f3f147", size = 14750, upload-time = "2026-08-12T12:37:24.648Z" },
 ]
 
+[[package]]
+name = "tzdata"
+version = "2026.4"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/e4/31/3d74fa778a63b98b7374323befcc0be5ab3bd94afd4096a0124e7379152c/tzdata-2026.4.tar.gz", hash = "sha256:f1b8bd365d8d210c55353f4d7f8d6d8561c0ba50d704b700d195a9424bba0d79", size = 199350, upload-time = "2026-09-12T12:56:03.251Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/f9/bc/8737e8d54cf51106118039b83f485a4783112fab49ea9d044b234978a46e/tzdata-2026.4-py2.py3-none-any.whl", hash = "sha256:c2169a8b0a7a5e9674da5a135ccdfb2b3e671b333ed9fed17b41f73c34476e81", size = 347494, upload-time = "2026-09-12T12:56:01.67Z" },
+]
+
+[[package]]
+name = "tzlocal"
+version = "5.4.4"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "tzdata", marker = "sys_platform == 'win32'" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/81/5b/879b2f932adfa7a053c360d50bc896c977fa6426109185f7c12ebdd0cb9d/tzlocal-5.4.4.tar.gz", hash = "sha256:8dbb8660838688a7b6ba4fed31d18dedf842afb4d47ca050d6d891c2c15f3be4", size = 31170, upload-time = "2026-06-29T08:03:40.026Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/9e/a4/017a7a6cbe387d961a688ec31364ae60a5c4e22c96ae9921b79a947c855d/tzlocal-5.4.4-py3-none-any.whl", hash = "sha256:aae09f0126a8a86fa736be266eb4a471380d26a0de3bc14844e7821fee3e2a15", size = 18115, upload-time = "2026-06-29T08:03:38.666Z" },
+]
+
 [[package]]
 name = "urllib3"
 version = "2.8.0"