pyboot-execute 0.1.1__tar.gz

pyboot_execute-0.1.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 pyboot contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

pyboot_execute-0.1.1/PKG-INFO

@@ -0,0 +1,338 @@
+Metadata-Version: 2.4
+Name: pyboot-execute
+Version: 0.1.1
+Summary: Task scheduling and background execution plugin for PyBoot
+Author: Siddharth Karn
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/devSiddharthKarn/pyboot
+Project-URL: Documentation, https://github.com/devSiddharthKarn/pyboot/tree/main/plugins/pyboot_execute
+Project-URL: Repository, https://github.com/devSiddharthKarn/pyboot
+Project-URL: Issues, https://github.com/devSiddharthKarn/pyboot/issues
+Keywords: pyboot,scheduler,task-scheduling,background-jobs,apscheduler
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: AsyncIO
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pyboot-framework>=0.1.3
+Requires-Dist: APScheduler<4,>=3.10
+Dynamic: license-file
+
+# pyboot-execute
+
+`pyboot-execute` is a PyBoot plugin for registering background services and
+running recurring synchronous jobs with APScheduler's
+`BackgroundScheduler`.
+
+## Features
+
+- Register background service classes with `BackgroundService`.
+- Run synchronous methods at a fixed interval.
+- Run a method again after a delay following the previous completion.
+- Apply an optional initial delay to interval and fixed-delay jobs.
+- Run methods from five-field cron expressions with `CronJob`.
+- Resolve constructor dependencies through PyBoot's IoC container.
+- Start the scheduler when PyBoot reaches its ready lifecycle stage.
+- Shut down the scheduler during normal interpreter exit.
+
+## Requirements
+
+- Python 3.10 or newer.
+- `pyboot-framework` 0.1.3 or newer.
+- APScheduler 3.10 through 3.x.
+
+The plugin uses APScheduler's in-process `BackgroundScheduler`. It is not a
+distributed or persistent job scheduler.
+
+## Installation
+
+Install the published distributions:
+
+```bash
+python -m pip install pyboot-framework pyboot-execute
+```
+
+For a source checkout from the repository root:
+
+```bash
+python -m pip install -e pyboot
+python -m pip install -e plugins/pyboot_execute
+```
+
+The package declares the PyBoot and APScheduler dependencies. Using
+`python -m pip` ensures they are installed into the interpreter used to run
+the application.
+
+Verify plugin discovery:
+
+```bash
+python -c "from importlib.metadata import entry_points; print([e.name for e in entry_points(group='pyboot.plugins')])"
+```
+
+The output should include `execute`.
+
+## Quick start
+
+Create a background service in the package passed to `bootstrap()`:
+
+```python
+from pyboot_execute import BackgroundService, Scheduled
+
+
+@BackgroundService()
+class NotificationService:
+    @Scheduled(interval_ms=5_000)
+    def send_notifications(self) -> None:
+        print("Checking pending notifications")
+```
+
+Bootstrap PyBoot:
+
+```python
+from pyboot.core.application import PyBoot
+
+
+pyboot = PyBoot(app_instance=None, debug=False)
+pyboot.bootstrap(package="app")
+```
+
+When PyBoot loads the installed `execute` entry point, it discovers the
+background service, registers it as an IoC bean, schedules its method, and
+starts the scheduler during `on_ready`.
+
+## Scheduling modes
+
+### Fixed interval
+
+`interval_ms` schedules executions at a recurring interval:
+
+```python
+@BackgroundService()
+class CacheRefresher:
+    @Scheduled(interval_ms=60_000, initial_delay_ms=5_000)
+    def refresh(self) -> None:
+        print("Refreshing cache")
+```
+
+The first execution occurs after `initial_delay_ms`; later executions use the
+configured interval. If the interval job takes longer than its interval,
+APScheduler's normal job execution rules apply and executions may overlap or
+be skipped according to the scheduler configuration.
+
+### Fixed delay
+
+`fixed_delay_ms` schedules the next run only after the previous invocation
+returns:
+
+```python
+@BackgroundService()
+class DataSynchronizer:
+    @Scheduled(fixed_delay_ms=30_000, initial_delay_ms=10_000)
+    def synchronize(self) -> None:
+        print("Synchronizing data")
+```
+
+If the method takes 8 seconds and the delay is 30 seconds, the next run is
+scheduled approximately 30 seconds after completion, not 30 seconds after the
+previous start.
+
+Exactly one of `interval_ms` and `fixed_delay_ms` must be supplied. Both must
+be positive. `initial_delay_ms` may be omitted or set to `None`; it must not be
+negative.
+
+### Cron schedules
+
+`CronJob` schedules a synchronous method using APScheduler's
+`CronTrigger.from_crontab()`:
+
+```python
+from pyboot_execute import BackgroundService, CronJob
+
+
+@BackgroundService()
+class CleanupService:
+    @CronJob("0 0 * * *")
+    def remove_expired_sessions(self) -> None:
+        print("Removing expired sessions")
+```
+
+The expression uses five fields:
+
+```text
+minute hour day-of-month month day-of-week
+```
+
+Examples:
+
+| Expression | Meaning |
+| --- | --- |
+| `* * * * *` | Every minute |
+| `*/5 * * * *` | Every five minutes |
+| `0 * * * *` | At the start of every hour |
+| `0 0 * * *` | Every day at midnight |
+| `0 9 * * 1-5` | At 09:00 on weekdays |
+| `0 0 1 * *` | At midnight on the first day of each month |
+
+Cron jobs use the scheduler's configured timezone. This plugin currently
+creates `BackgroundScheduler()` without an explicit timezone, so deployments
+should document the host or container timezone when relying on wall-clock
+schedules.
+
+## Dependency injection
+
+Background services are regular PyBoot-managed beans. Declare dependencies in
+the constructor with type annotations:
+
+```python
+from pyboot.core.builtins.component import Component
+from pyboot_execute import BackgroundService, Scheduled
+
+
+@Component()
+class ReportRepository:
+    def pending_reports(self) -> list[str]:
+        return ["daily-summary"]
+
+
+@BackgroundService()
+class ReportWorker:
+    def __init__(self, repository: ReportRepository) -> None:
+        self.repository = repository
+
+    @Scheduled(interval_ms=60_000)
+    def generate_reports(self) -> None:
+        for report in self.repository.pending_reports():
+            print(f"Generating {report}")
+```
+
+Do not instantiate a `BackgroundService` manually. PyBoot creates the bean and
+resolves its required constructor dependencies. All required constructor
+parameters need type annotations that the IoC container can resolve.
+
+## Public API
+
+### `BackgroundService`
+
+`@BackgroundService()` marks a class for registration by `ExecutePlugin`.
+Scheduled methods are inspected on the resulting bean after PyBoot creates it.
+
+### `Scheduled`
+
+```python
+@Scheduled(
+    interval_ms: int | None = None,
+    fixed_delay_ms: int | None = None,
+    initial_delay_ms: int | None = None,
+)
+```
+
+Exactly one primary schedule value is required. Invalid combinations and
+non-positive values raise `ValueError` during decorator construction.
+
+### `CronJob`
+
+```python
+@CronJob(trigger: str)
+```
+
+`CronJob` schedules the decorated method using APScheduler's
+`CronTrigger.from_crontab()`. The trigger string must be a valid five-field
+cron expression. Invalid expressions raise an APScheduler trigger error during
+application loading.
+
+### `ScheduleType`
+
+`ScheduleType.INTERVAL` and `ScheduleType.FIXED_DELAY` describe the internal
+schedule metadata used by `Scheduled`.
+
+### `ExecutePlugin`
+
+`ExecutePlugin` is registered automatically through the
+`pyboot.plugins` entry-point group:
+
+```toml
+[project.entry-points."pyboot.plugins"]
+execute = "pyboot_execute.execute:ExecutePlugin"
+```
+
+Most users should not instantiate it directly.
+
+## Application layout
+
+```text
+service/
+├── main.py
+└── app/
+    ├── __init__.py
+    ├── components.py
+    └── jobs.py
+```
+
+PyBoot scans the package passed to `bootstrap()` and its submodules. Keep
+background services and their dependencies inside that package, and define
+classes in the modules being scanned.
+
+## Lifecycle and shutdown
+
+The plugin registers background services during `on_register`, obtains their
+beans during `after_load`, and starts its `BackgroundScheduler` during
+`on_ready`. It registers an `atexit` callback and calls
+`shutdown(wait=False)` when the scheduler is running.
+
+Normal interpreter shutdown is covered; crashes and forced termination are not.
+Jobs are recreated from decorators on every process start. The plugin does not
+persist job state or dynamically created jobs.
+
+## Production guidance
+
+### Multiple workers
+
+Every process creates its own scheduler. If an application runs with four
+workers, the same job can execute four times. Use a single dedicated scheduler
+process, a distributed scheduler, or an application-level distributed lock
+when a job must run once globally.
+
+### Reliability
+
+- Make jobs idempotent where possible.
+- Use explicit timeouts for external calls.
+- Add structured logging and metrics around each job.
+- Catch and handle expected business failures inside the job.
+- Keep secrets out of log messages.
+- Consider a persistent or distributed job system for critical workloads.
+- Test startup and shutdown behavior in the deployment environment.
+
+### Concurrency
+
+Scheduled methods are synchronous and run in APScheduler worker threads.
+CPU-heavy or long-running jobs can consume worker capacity. Do not assume the
+main application thread and scheduled workers share transaction or request
+context.
+
+## Testing
+
+Test the service logic independently from scheduling, then verify registration
+with a PyBoot bootstrap:
+
+```python
+from pyboot.core.application import PyBoot
+
+
+def test_application_bootstrap() -> None:
+    pyboot = PyBoot(app_instance=None, debug=False)
+    pyboot.bootstrap(package="app")
+```
+
+For deterministic job tests, call the service method directly or use a
+controlled scheduler test fixture. Avoid waiting on real millisecond delays in
+unit tests.
+
+## License
+
+This project is distributed under the MIT License. See [LICENSE](./LICENSE).

pyboot_execute-0.1.1/README.md

@@ -0,0 +1,312 @@
+# pyboot-execute
+
+`pyboot-execute` is a PyBoot plugin for registering background services and
+running recurring synchronous jobs with APScheduler's
+`BackgroundScheduler`.
+
+## Features
+
+- Register background service classes with `BackgroundService`.
+- Run synchronous methods at a fixed interval.
+- Run a method again after a delay following the previous completion.
+- Apply an optional initial delay to interval and fixed-delay jobs.
+- Run methods from five-field cron expressions with `CronJob`.
+- Resolve constructor dependencies through PyBoot's IoC container.
+- Start the scheduler when PyBoot reaches its ready lifecycle stage.
+- Shut down the scheduler during normal interpreter exit.
+
+## Requirements
+
+- Python 3.10 or newer.
+- `pyboot-framework` 0.1.3 or newer.
+- APScheduler 3.10 through 3.x.
+
+The plugin uses APScheduler's in-process `BackgroundScheduler`. It is not a
+distributed or persistent job scheduler.
+
+## Installation
+
+Install the published distributions:
+
+```bash
+python -m pip install pyboot-framework pyboot-execute
+```
+
+For a source checkout from the repository root:
+
+```bash
+python -m pip install -e pyboot
+python -m pip install -e plugins/pyboot_execute
+```
+
+The package declares the PyBoot and APScheduler dependencies. Using
+`python -m pip` ensures they are installed into the interpreter used to run
+the application.
+
+Verify plugin discovery:
+
+```bash
+python -c "from importlib.metadata import entry_points; print([e.name for e in entry_points(group='pyboot.plugins')])"
+```
+
+The output should include `execute`.
+
+## Quick start
+
+Create a background service in the package passed to `bootstrap()`:
+
+```python
+from pyboot_execute import BackgroundService, Scheduled
+
+
+@BackgroundService()
+class NotificationService:
+    @Scheduled(interval_ms=5_000)
+    def send_notifications(self) -> None:
+        print("Checking pending notifications")
+```
+
+Bootstrap PyBoot:
+
+```python
+from pyboot.core.application import PyBoot
+
+
+pyboot = PyBoot(app_instance=None, debug=False)
+pyboot.bootstrap(package="app")
+```
+
+When PyBoot loads the installed `execute` entry point, it discovers the
+background service, registers it as an IoC bean, schedules its method, and
+starts the scheduler during `on_ready`.
+
+## Scheduling modes
+
+### Fixed interval
+
+`interval_ms` schedules executions at a recurring interval:
+
+```python
+@BackgroundService()
+class CacheRefresher:
+    @Scheduled(interval_ms=60_000, initial_delay_ms=5_000)
+    def refresh(self) -> None:
+        print("Refreshing cache")
+```
+
+The first execution occurs after `initial_delay_ms`; later executions use the
+configured interval. If the interval job takes longer than its interval,
+APScheduler's normal job execution rules apply and executions may overlap or
+be skipped according to the scheduler configuration.
+
+### Fixed delay
+
+`fixed_delay_ms` schedules the next run only after the previous invocation
+returns:
+
+```python
+@BackgroundService()
+class DataSynchronizer:
+    @Scheduled(fixed_delay_ms=30_000, initial_delay_ms=10_000)
+    def synchronize(self) -> None:
+        print("Synchronizing data")
+```
+
+If the method takes 8 seconds and the delay is 30 seconds, the next run is
+scheduled approximately 30 seconds after completion, not 30 seconds after the
+previous start.
+
+Exactly one of `interval_ms` and `fixed_delay_ms` must be supplied. Both must
+be positive. `initial_delay_ms` may be omitted or set to `None`; it must not be
+negative.
+
+### Cron schedules
+
+`CronJob` schedules a synchronous method using APScheduler's
+`CronTrigger.from_crontab()`:
+
+```python
+from pyboot_execute import BackgroundService, CronJob
+
+
+@BackgroundService()
+class CleanupService:
+    @CronJob("0 0 * * *")
+    def remove_expired_sessions(self) -> None:
+        print("Removing expired sessions")
+```
+
+The expression uses five fields:
+
+```text
+minute hour day-of-month month day-of-week
+```
+
+Examples:
+
+| Expression | Meaning |
+| --- | --- |
+| `* * * * *` | Every minute |
+| `*/5 * * * *` | Every five minutes |
+| `0 * * * *` | At the start of every hour |
+| `0 0 * * *` | Every day at midnight |
+| `0 9 * * 1-5` | At 09:00 on weekdays |
+| `0 0 1 * *` | At midnight on the first day of each month |
+
+Cron jobs use the scheduler's configured timezone. This plugin currently
+creates `BackgroundScheduler()` without an explicit timezone, so deployments
+should document the host or container timezone when relying on wall-clock
+schedules.
+
+## Dependency injection
+
+Background services are regular PyBoot-managed beans. Declare dependencies in
+the constructor with type annotations:
+
+```python
+from pyboot.core.builtins.component import Component
+from pyboot_execute import BackgroundService, Scheduled
+
+
+@Component()
+class ReportRepository:
+    def pending_reports(self) -> list[str]:
+        return ["daily-summary"]
+
+
+@BackgroundService()
+class ReportWorker:
+    def __init__(self, repository: ReportRepository) -> None:
+        self.repository = repository
+
+    @Scheduled(interval_ms=60_000)
+    def generate_reports(self) -> None:
+        for report in self.repository.pending_reports():
+            print(f"Generating {report}")
+```
+
+Do not instantiate a `BackgroundService` manually. PyBoot creates the bean and
+resolves its required constructor dependencies. All required constructor
+parameters need type annotations that the IoC container can resolve.
+
+## Public API
+
+### `BackgroundService`
+
+`@BackgroundService()` marks a class for registration by `ExecutePlugin`.
+Scheduled methods are inspected on the resulting bean after PyBoot creates it.
+
+### `Scheduled`
+
+```python
+@Scheduled(
+    interval_ms: int | None = None,
+    fixed_delay_ms: int | None = None,
+    initial_delay_ms: int | None = None,
+)
+```
+
+Exactly one primary schedule value is required. Invalid combinations and
+non-positive values raise `ValueError` during decorator construction.
+
+### `CronJob`
+
+```python
+@CronJob(trigger: str)
+```
+
+`CronJob` schedules the decorated method using APScheduler's
+`CronTrigger.from_crontab()`. The trigger string must be a valid five-field
+cron expression. Invalid expressions raise an APScheduler trigger error during
+application loading.
+
+### `ScheduleType`
+
+`ScheduleType.INTERVAL` and `ScheduleType.FIXED_DELAY` describe the internal
+schedule metadata used by `Scheduled`.
+
+### `ExecutePlugin`
+
+`ExecutePlugin` is registered automatically through the
+`pyboot.plugins` entry-point group:
+
+```toml
+[project.entry-points."pyboot.plugins"]
+execute = "pyboot_execute.execute:ExecutePlugin"
+```
+
+Most users should not instantiate it directly.
+
+## Application layout
+
+```text
+service/
+├── main.py
+└── app/
+    ├── __init__.py
+    ├── components.py
+    └── jobs.py
+```
+
+PyBoot scans the package passed to `bootstrap()` and its submodules. Keep
+background services and their dependencies inside that package, and define
+classes in the modules being scanned.
+
+## Lifecycle and shutdown
+
+The plugin registers background services during `on_register`, obtains their
+beans during `after_load`, and starts its `BackgroundScheduler` during
+`on_ready`. It registers an `atexit` callback and calls
+`shutdown(wait=False)` when the scheduler is running.
+
+Normal interpreter shutdown is covered; crashes and forced termination are not.
+Jobs are recreated from decorators on every process start. The plugin does not
+persist job state or dynamically created jobs.
+
+## Production guidance
+
+### Multiple workers
+
+Every process creates its own scheduler. If an application runs with four
+workers, the same job can execute four times. Use a single dedicated scheduler
+process, a distributed scheduler, or an application-level distributed lock
+when a job must run once globally.
+
+### Reliability
+
+- Make jobs idempotent where possible.
+- Use explicit timeouts for external calls.
+- Add structured logging and metrics around each job.
+- Catch and handle expected business failures inside the job.
+- Keep secrets out of log messages.
+- Consider a persistent or distributed job system for critical workloads.
+- Test startup and shutdown behavior in the deployment environment.
+
+### Concurrency
+
+Scheduled methods are synchronous and run in APScheduler worker threads.
+CPU-heavy or long-running jobs can consume worker capacity. Do not assume the
+main application thread and scheduled workers share transaction or request
+context.
+
+## Testing
+
+Test the service logic independently from scheduling, then verify registration
+with a PyBoot bootstrap:
+
+```python
+from pyboot.core.application import PyBoot
+
+
+def test_application_bootstrap() -> None:
+    pyboot = PyBoot(app_instance=None, debug=False)
+    pyboot.bootstrap(package="app")
+```
+
+For deterministic job tests, call the service method directly or use a
+controlled scheduler test fixture. Avoid waiting on real millisecond delays in
+unit tests.
+
+## License
+
+This project is distributed under the MIT License. See [LICENSE](./LICENSE).

pyboot_execute-0.1.1/pyproject.toml

@@ -0,0 +1,53 @@
+[build-system]
+requires = ["setuptools>=75", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "pyboot-execute"
+version = "0.1.1"
+description = "Task scheduling and background execution plugin for PyBoot"
+readme = "README.md"
+requires-python = ">=3.11"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [
+    { name = "Siddharth Karn" }
+]
+keywords = [
+    "pyboot",
+    "scheduler",
+    "task-scheduling",
+    "background-jobs",
+    "apscheduler"
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Framework :: AsyncIO",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Software Development :: Libraries :: Python Modules"
+]
+
+dependencies = [
+    "pyboot-framework>=0.1.3",
+    "APScheduler>=3.10,<4"
+]
+
+[project.urls]
+Homepage = "https://github.com/devSiddharthKarn/pyboot"
+Documentation = "https://github.com/devSiddharthKarn/pyboot/tree/main/plugins/pyboot_execute"
+Repository = "https://github.com/devSiddharthKarn/pyboot"
+Issues = "https://github.com/devSiddharthKarn/pyboot/issues"
+
+
+[project.entry-points."pyboot.plugins"]
+execute="pyboot_execute.execute:ExecutePlugin"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools]
+include-package-data = true

pyboot_execute-0.1.1/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

pyboot_execute-0.1.1/src/pyboot_execute/Attr.py

@@ -0,0 +1,12 @@
+from enum import Enum
+
+class BGAttr(Enum):
+    IS_BACKGROUND_SERVICE="__is_background_service__"
+
+    IS_SCHEDULED_SERVICE_EXECUTOR="__is_scheduled_service_executor__"
+    SCHEDULE_TYPE="__schedule_type__"
+    SCHEDULE_VALUE_MS="__schedule_value_ms__"
+    SCHEDULE_INITIAL_DELAY_MS="__schedule_initial_delay_ms__"
+
+    IS_CRON_JOB_EXECUTOR="__is_cron_job_executor__"
+    CRON_JOB_TRIGGER="__cron_job_trigger__"

pyboot_execute-0.1.1/src/pyboot_execute/__init__.py

@@ -0,0 +1,17 @@
+"""Public API for the PyBoot background execution plugin."""
+
+from .execute import (
+    BackgroundService,
+    CronJob,
+    ExecutePlugin,
+    ScheduleType,
+    Scheduled,
+)
+
+__all__ = [
+    "BackgroundService",
+    "CronJob",
+    "ExecutePlugin",
+    "ScheduleType",
+    "Scheduled",
+]

pyboot_execute-0.1.1/src/pyboot_execute/execute.py

@@ -0,0 +1,222 @@
+from pyboot.core.pyboot_context import PyBootContext
+from pyboot.core.types import ClassT, MethodTBase
+from pyboot.core.pyboot_plugin import PyBootPlugin
+
+from .Attr import BGAttr
+
+from apscheduler.schedulers.background import BackgroundScheduler  # type: ignore[reportUnknownMemberType]
+from apscheduler.triggers.cron import CronTrigger  # type: ignore[reportUnknownMemberType]
+
+import inspect
+import atexit
+from enum import Enum
+from datetime import datetime,timedelta,timezone
+
+#Decorates a class to mark it as a background service. Background services are automatically registered in the IoC container and can have scheduled methods.
+class BackgroundService:
+    """
+    Decorator to mark a class as a background service. Background services are automatically registered in the IoC container and can have scheduled methods.
+    Usage:
+    @BackgroundService()
+    class MyBackgroundService:
+        
+        //methods
+
+
+    """
+    def __init__(self) -> None:
+        pass
+
+    def __call__(self, clazz: ClassT) -> ClassT:
+        setattr(clazz, BGAttr.IS_BACKGROUND_SERVICE.value, True)
+        return clazz
+
+class ScheduleType(Enum):
+    """
+    Enum for schedule types used in the Scheduled decorator.
+    INTERVAL: Represents a schedule that runs at fixed intervals.
+    FIXED_DELAY: Represents a schedule that runs with a fixed delay after the previous execution completes.
+    """
+    INTERVAL="__interval_type__"
+    FIXED_DELAY="__fixed_delay_type__"
+
+#Schedules a method to be executed at fixed intervals or with a fixed delay after the previous execution completes. It can either be an interval schedule or a fixed delay schedule, but not both.
+class Scheduled:
+    """
+    Decorator to mark a method as scheduled.According to the specified schedule type, the method will be executed at fixed intervals or with a fixed delay after the previous execution completes. It can either be an interval schedule or a fixed delay schedule, but not both.
+    """
+    def __init__(
+        self, interval_ms: int | None = None, fixed_delay_ms: int | None = None,initial_delay_ms:int|None=None
+    ) -> None:
+        if (interval_ms is None) == (fixed_delay_ms is None):
+            raise ValueError("Specify exactly one of interval_ms or fixed_delay_ms")
+
+        if interval_ms is not None:
+            if interval_ms<=0:
+                raise ValueError("interval_ms must be positive")
+
+            if initial_delay_ms is not None and initial_delay_ms<0:
+                raise ValueError("initial_delay_ms must be non-negative")
+
+            self.scheduled_type=ScheduleType.INTERVAL
+            self.value_ms=interval_ms
+            self.initial_delay_ms=initial_delay_ms
+
+        elif fixed_delay_ms is not None:
+            if fixed_delay_ms<=0:
+                raise ValueError("fixed_delay_ms must be  positive")
+
+            if initial_delay_ms is not None and initial_delay_ms<0:
+                raise ValueError("initial_delay_ms must be non-negative")
+
+            self.scheduled_type=ScheduleType.FIXED_DELAY
+            self.value_ms=fixed_delay_ms
+            self.initial_delay_ms=initial_delay_ms
+        return
+    
+    def __call__(self, method: MethodTBase) -> MethodTBase:
+        setattr(method, BGAttr.IS_SCHEDULED_SERVICE_EXECUTOR.value, True)
+        setattr(method,BGAttr.SCHEDULE_TYPE.value,self.scheduled_type)
+        setattr(method,BGAttr.SCHEDULE_VALUE_MS.value,self.value_ms)
+        setattr(method,BGAttr.SCHEDULE_INITIAL_DELAY_MS.value,self.initial_delay_ms)
+        return method
+
+#CronJob decorator to mark a method as a cron job executor. The method will be executed according to the specified cron trigger. trigger should be a string in the format of a cron expression, e.g. "0 0 * * *" for every day at midnight.
+class CronJob:
+    """
+    Decorator to mark a method as a cron job executor. The method will be executed according to the specified cron trigger. trigger should be a string in the format of a cron expression, e.g. "0 0 * * *" for every day at midnight.
+    """
+    def __init__(self, trigger: str) -> None:
+        self.trigger = trigger
+        return
+
+    def __call__(self, method: MethodTBase) -> MethodTBase:
+        setattr(method, BGAttr.IS_CRON_JOB_EXECUTOR.value, True)
+        setattr(method, BGAttr.CRON_JOB_TRIGGER.value, self.trigger)
+        return method
+
+
+#The ExecutorPlugin class is a PyBoot plugin that manages background services and their scheduled methods. It uses the APScheduler library to schedule and execute methods based on the specified schedule type (interval, fixed delay, or cron job). The plugin automatically registers background service classes in the IoC container and starts the scheduler when the application is ready.
+class ExecutePlugin(PyBootPlugin):
+    """
+    The ExecutorPlugin class is a PyBoot plugin that manages background services and their scheduled methods. It uses the APScheduler library to schedule and execute methods based on the specified schedule type (interval, fixed delay, or cron job). The plugin automatically registers background service classes in the IoC container and starts the scheduler when the application is ready.
+    """
+    def __init__(self) -> None:
+        self.simple_scheduler: BackgroundScheduler = BackgroundScheduler()
+        atexit.register(self.shutdown)
+        return
+
+    def shutdown(self) -> None:
+        if self.simple_scheduler.running:
+            self.simple_scheduler.shutdown(wait=False)  # type: ignore[reportUnknownMemberType]
+
+    def after_plugins_discovery(self, context: PyBootContext) -> None:
+        return super().after_plugins_discovery(context)
+
+    def before_classes_discovery(self, context: PyBootContext) -> None:
+        return super().before_classes_discovery(context)
+
+    def after_classes_discovery(self, context: PyBootContext) -> None:
+        return super().after_classes_discovery(context)
+
+    def before_register(self, context: PyBootContext) -> None:
+        return super().before_register(context)
+
+    def on_register(self, context: PyBootContext) -> None:
+        for clazz in context.discovered_classes:
+
+            # skip other classes
+            if not getattr(clazz, BGAttr.IS_BACKGROUND_SERVICE.value, False):
+                continue
+
+            context.ioc.register_class(clazz=clazz)
+
+        return
+
+    def after_register(self, context: PyBootContext) -> None:
+        return super().after_register(context)
+
+    def before_load(self, context: PyBootContext) -> None:
+        return super().before_load(context)
+
+    def on_load(self, context: PyBootContext) -> None:
+        return super().on_load(context)
+
+    def _create_fixed_delay_job(self, method:MethodTBase, delay_ms: int):
+        def execute():
+            try:
+                method()
+            finally:
+                if self.simple_scheduler.running:
+                    self.simple_scheduler.add_job(# type: ignore[reportUnknownMemberType]
+                        execute,
+                        trigger="date",
+                        run_date=datetime.now(timezone.utc)
+                        + timedelta(milliseconds=delay_ms),
+                    )
+
+        return execute
+
+    def after_load(self, context: PyBootContext) -> None:
+        for clazz in context.discovered_classes:
+
+            # skip other classes
+            if not getattr(clazz, BGAttr.IS_BACKGROUND_SERVICE.value, False):
+                continue
+
+            bg_service_bean = context.ioc.get_bean(clazz=clazz)
+
+            for method_name, method in inspect.getmembers(
+                bg_service_bean, inspect.ismethod
+            ):
+
+                # handle scheduled
+                if getattr(method, BGAttr.IS_SCHEDULED_SERVICE_EXECUTOR.value, False):
+
+                    scheduled_type=getattr(method,BGAttr.SCHEDULE_TYPE.value,None)
+
+                    value_ms=getattr(method,BGAttr.SCHEDULE_VALUE_MS.value,None)
+
+                    if scheduled_type is None or value_ms is None:
+                        raise ValueError(
+                            f"Scheduled method {method_name} in class {clazz.__name__} is missing required attributes and got values: {scheduled_type}, value_ms={value_ms}"
+                        )
+
+                    initial_delay_ms=getattr(method,BGAttr.SCHEDULE_INITIAL_DELAY_MS.value,0)
+
+                    if scheduled_type==ScheduleType.INTERVAL:
+                        self.simple_scheduler.add_job(# type: ignore[reportUnknownMemberType]
+                            func=method,
+                            trigger="interval",
+                            seconds=value_ms/1000,
+                            next_run_time=datetime.now(timezone.utc)+timedelta(milliseconds=initial_delay_ms)
+                        )
+                    elif scheduled_type==ScheduleType.FIXED_DELAY:
+                        job =self._create_fixed_delay_job(method=method,delay_ms=value_ms)
+
+                        self.simple_scheduler.add_job(# type: ignore[reportUnknownMemberType]
+                            func=job,
+                            trigger="date",
+                            run_date=datetime.now(timezone.utc)+timedelta(milliseconds=initial_delay_ms)
+                        )
+
+                #handle cron-jobs
+                if getattr(method, BGAttr.IS_CRON_JOB_EXECUTOR.value, False):
+                    trigger_str: str = str(
+                                        getattr(method, BGAttr.CRON_JOB_TRIGGER.value, "")
+                                    )
+                
+                    trigger = CronTrigger.from_crontab(trigger_str) # type: ignore[reportUnknownMemberType]
+                
+                    self.simple_scheduler.add_job(  # type: ignore[reportUnknownMemberType]
+                                        func=method, trigger=trigger
+                                    )
+                
+                # skip other
+                continue
+
+        return
+
+    def on_ready(self, context: PyBootContext) -> None:
+        self.simple_scheduler.start()  # type: ignore[reportUnknownMemberType]
+        return

pyboot_execute-0.1.1/src/pyboot_execute.egg-info/PKG-INFO

@@ -0,0 +1,338 @@
+Metadata-Version: 2.4
+Name: pyboot-execute
+Version: 0.1.1
+Summary: Task scheduling and background execution plugin for PyBoot
+Author: Siddharth Karn
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/devSiddharthKarn/pyboot
+Project-URL: Documentation, https://github.com/devSiddharthKarn/pyboot/tree/main/plugins/pyboot_execute
+Project-URL: Repository, https://github.com/devSiddharthKarn/pyboot
+Project-URL: Issues, https://github.com/devSiddharthKarn/pyboot/issues
+Keywords: pyboot,scheduler,task-scheduling,background-jobs,apscheduler
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: AsyncIO
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pyboot-framework>=0.1.3
+Requires-Dist: APScheduler<4,>=3.10
+Dynamic: license-file
+
+# pyboot-execute
+
+`pyboot-execute` is a PyBoot plugin for registering background services and
+running recurring synchronous jobs with APScheduler's
+`BackgroundScheduler`.
+
+## Features
+
+- Register background service classes with `BackgroundService`.
+- Run synchronous methods at a fixed interval.
+- Run a method again after a delay following the previous completion.
+- Apply an optional initial delay to interval and fixed-delay jobs.
+- Run methods from five-field cron expressions with `CronJob`.
+- Resolve constructor dependencies through PyBoot's IoC container.
+- Start the scheduler when PyBoot reaches its ready lifecycle stage.
+- Shut down the scheduler during normal interpreter exit.
+
+## Requirements
+
+- Python 3.10 or newer.
+- `pyboot-framework` 0.1.3 or newer.
+- APScheduler 3.10 through 3.x.
+
+The plugin uses APScheduler's in-process `BackgroundScheduler`. It is not a
+distributed or persistent job scheduler.
+
+## Installation
+
+Install the published distributions:
+
+```bash
+python -m pip install pyboot-framework pyboot-execute
+```
+
+For a source checkout from the repository root:
+
+```bash
+python -m pip install -e pyboot
+python -m pip install -e plugins/pyboot_execute
+```
+
+The package declares the PyBoot and APScheduler dependencies. Using
+`python -m pip` ensures they are installed into the interpreter used to run
+the application.
+
+Verify plugin discovery:
+
+```bash
+python -c "from importlib.metadata import entry_points; print([e.name for e in entry_points(group='pyboot.plugins')])"
+```
+
+The output should include `execute`.
+
+## Quick start
+
+Create a background service in the package passed to `bootstrap()`:
+
+```python
+from pyboot_execute import BackgroundService, Scheduled
+
+
+@BackgroundService()
+class NotificationService:
+    @Scheduled(interval_ms=5_000)
+    def send_notifications(self) -> None:
+        print("Checking pending notifications")
+```
+
+Bootstrap PyBoot:
+
+```python
+from pyboot.core.application import PyBoot
+
+
+pyboot = PyBoot(app_instance=None, debug=False)
+pyboot.bootstrap(package="app")
+```
+
+When PyBoot loads the installed `execute` entry point, it discovers the
+background service, registers it as an IoC bean, schedules its method, and
+starts the scheduler during `on_ready`.
+
+## Scheduling modes
+
+### Fixed interval
+
+`interval_ms` schedules executions at a recurring interval:
+
+```python
+@BackgroundService()
+class CacheRefresher:
+    @Scheduled(interval_ms=60_000, initial_delay_ms=5_000)
+    def refresh(self) -> None:
+        print("Refreshing cache")
+```
+
+The first execution occurs after `initial_delay_ms`; later executions use the
+configured interval. If the interval job takes longer than its interval,
+APScheduler's normal job execution rules apply and executions may overlap or
+be skipped according to the scheduler configuration.
+
+### Fixed delay
+
+`fixed_delay_ms` schedules the next run only after the previous invocation
+returns:
+
+```python
+@BackgroundService()
+class DataSynchronizer:
+    @Scheduled(fixed_delay_ms=30_000, initial_delay_ms=10_000)
+    def synchronize(self) -> None:
+        print("Synchronizing data")
+```
+
+If the method takes 8 seconds and the delay is 30 seconds, the next run is
+scheduled approximately 30 seconds after completion, not 30 seconds after the
+previous start.
+
+Exactly one of `interval_ms` and `fixed_delay_ms` must be supplied. Both must
+be positive. `initial_delay_ms` may be omitted or set to `None`; it must not be
+negative.
+
+### Cron schedules
+
+`CronJob` schedules a synchronous method using APScheduler's
+`CronTrigger.from_crontab()`:
+
+```python
+from pyboot_execute import BackgroundService, CronJob
+
+
+@BackgroundService()
+class CleanupService:
+    @CronJob("0 0 * * *")
+    def remove_expired_sessions(self) -> None:
+        print("Removing expired sessions")
+```
+
+The expression uses five fields:
+
+```text
+minute hour day-of-month month day-of-week
+```
+
+Examples:
+
+| Expression | Meaning |
+| --- | --- |
+| `* * * * *` | Every minute |
+| `*/5 * * * *` | Every five minutes |
+| `0 * * * *` | At the start of every hour |
+| `0 0 * * *` | Every day at midnight |
+| `0 9 * * 1-5` | At 09:00 on weekdays |
+| `0 0 1 * *` | At midnight on the first day of each month |
+
+Cron jobs use the scheduler's configured timezone. This plugin currently
+creates `BackgroundScheduler()` without an explicit timezone, so deployments
+should document the host or container timezone when relying on wall-clock
+schedules.
+
+## Dependency injection
+
+Background services are regular PyBoot-managed beans. Declare dependencies in
+the constructor with type annotations:
+
+```python
+from pyboot.core.builtins.component import Component
+from pyboot_execute import BackgroundService, Scheduled
+
+
+@Component()
+class ReportRepository:
+    def pending_reports(self) -> list[str]:
+        return ["daily-summary"]
+
+
+@BackgroundService()
+class ReportWorker:
+    def __init__(self, repository: ReportRepository) -> None:
+        self.repository = repository
+
+    @Scheduled(interval_ms=60_000)
+    def generate_reports(self) -> None:
+        for report in self.repository.pending_reports():
+            print(f"Generating {report}")
+```
+
+Do not instantiate a `BackgroundService` manually. PyBoot creates the bean and
+resolves its required constructor dependencies. All required constructor
+parameters need type annotations that the IoC container can resolve.
+
+## Public API
+
+### `BackgroundService`
+
+`@BackgroundService()` marks a class for registration by `ExecutePlugin`.
+Scheduled methods are inspected on the resulting bean after PyBoot creates it.
+
+### `Scheduled`
+
+```python
+@Scheduled(
+    interval_ms: int | None = None,
+    fixed_delay_ms: int | None = None,
+    initial_delay_ms: int | None = None,
+)
+```
+
+Exactly one primary schedule value is required. Invalid combinations and
+non-positive values raise `ValueError` during decorator construction.
+
+### `CronJob`
+
+```python
+@CronJob(trigger: str)
+```
+
+`CronJob` schedules the decorated method using APScheduler's
+`CronTrigger.from_crontab()`. The trigger string must be a valid five-field
+cron expression. Invalid expressions raise an APScheduler trigger error during
+application loading.
+
+### `ScheduleType`
+
+`ScheduleType.INTERVAL` and `ScheduleType.FIXED_DELAY` describe the internal
+schedule metadata used by `Scheduled`.
+
+### `ExecutePlugin`
+
+`ExecutePlugin` is registered automatically through the
+`pyboot.plugins` entry-point group:
+
+```toml
+[project.entry-points."pyboot.plugins"]
+execute = "pyboot_execute.execute:ExecutePlugin"
+```
+
+Most users should not instantiate it directly.
+
+## Application layout
+
+```text
+service/
+├── main.py
+└── app/
+    ├── __init__.py
+    ├── components.py
+    └── jobs.py
+```
+
+PyBoot scans the package passed to `bootstrap()` and its submodules. Keep
+background services and their dependencies inside that package, and define
+classes in the modules being scanned.
+
+## Lifecycle and shutdown
+
+The plugin registers background services during `on_register`, obtains their
+beans during `after_load`, and starts its `BackgroundScheduler` during
+`on_ready`. It registers an `atexit` callback and calls
+`shutdown(wait=False)` when the scheduler is running.
+
+Normal interpreter shutdown is covered; crashes and forced termination are not.
+Jobs are recreated from decorators on every process start. The plugin does not
+persist job state or dynamically created jobs.
+
+## Production guidance
+
+### Multiple workers
+
+Every process creates its own scheduler. If an application runs with four
+workers, the same job can execute four times. Use a single dedicated scheduler
+process, a distributed scheduler, or an application-level distributed lock
+when a job must run once globally.
+
+### Reliability
+
+- Make jobs idempotent where possible.
+- Use explicit timeouts for external calls.
+- Add structured logging and metrics around each job.
+- Catch and handle expected business failures inside the job.
+- Keep secrets out of log messages.
+- Consider a persistent or distributed job system for critical workloads.
+- Test startup and shutdown behavior in the deployment environment.
+
+### Concurrency
+
+Scheduled methods are synchronous and run in APScheduler worker threads.
+CPU-heavy or long-running jobs can consume worker capacity. Do not assume the
+main application thread and scheduled workers share transaction or request
+context.
+
+## Testing
+
+Test the service logic independently from scheduling, then verify registration
+with a PyBoot bootstrap:
+
+```python
+from pyboot.core.application import PyBoot
+
+
+def test_application_bootstrap() -> None:
+    pyboot = PyBoot(app_instance=None, debug=False)
+    pyboot.bootstrap(package="app")
+```
+
+For deterministic job tests, call the service method directly or use a
+controlled scheduler test fixture. Avoid waiting on real millisecond delays in
+unit tests.
+
+## License
+
+This project is distributed under the MIT License. See [LICENSE](./LICENSE).

pyboot_execute-0.1.1/src/pyboot_execute.egg-info/SOURCES.txt

@@ -0,0 +1,12 @@
+LICENSE
+README.md
+pyproject.toml
+src/pyboot_execute/Attr.py
+src/pyboot_execute/__init__.py
+src/pyboot_execute/execute.py
+src/pyboot_execute.egg-info/PKG-INFO
+src/pyboot_execute.egg-info/SOURCES.txt
+src/pyboot_execute.egg-info/dependency_links.txt
+src/pyboot_execute.egg-info/entry_points.txt
+src/pyboot_execute.egg-info/requires.txt
+src/pyboot_execute.egg-info/top_level.txt

pyboot_execute-0.1.1/src/pyboot_execute.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

pyboot_execute-0.1.1/src/pyboot_execute.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[pyboot.plugins]
+execute = pyboot_execute.execute:ExecutePlugin

pyboot_execute-0.1.1/src/pyboot_execute.egg-info/requires.txt

@@ -0,0 +1,2 @@
+pyboot-framework>=0.1.3
+APScheduler<4,>=3.10

pyboot_execute-0.1.1/src/pyboot_execute.egg-info/top_level.txt

@@ -0,0 +1 @@
+pyboot_execute