spakky-task 6.0.0__tar.gz

spakky_task-6.0.0/PKG-INFO

@@ -0,0 +1,147 @@
+Metadata-Version: 2.3
+Name: spakky-task
+Version: 6.0.0
+Summary: Task queue abstraction for Spakky Framework (@TaskHandler, @task)
+Author: Spakky
+Author-email: Spakky <sejong418@icloud.com>
+License: MIT
+Requires-Dist: spakky>=6.0.0
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+
+# spakky-task
+
+Task queue abstraction layer for [Spakky Framework](https://github.com/E5resso/spakky-framework).
+
+## Installation
+
+```bash
+pip install spakky-task
+```
+
+## Features
+
+- **`@TaskHandler` stereotype**: Marks classes as task handler pods
+- **`@task` decorator**: Marks methods as on-demand dispatchable tasks
+- **`@schedule` decorator**: Marks methods for periodic execution (interval, daily, crontab)
+- **`Crontab` value object**: Python-native cron specification with `Weekday`/`Month` enums
+- **Post-processor**: Automatically scans and registers task routes from `@TaskHandler` pods
+- **Implementation-agnostic**: Works with any task queue backend (Celery, etc.) via plugins
+
+## Usage
+
+### On-Demand Tasks
+
+`@task` marks methods for on-demand dispatch. The backend plugin (e.g., `spakky-celery`)
+intercepts calls via AOP and routes them to the task queue.
+
+```python
+from spakky.task import TaskHandler, task
+
+
+@TaskHandler()
+class EmailTaskHandler:
+    @task
+    def send_email(self, to: str, subject: str, body: str) -> None:
+        """Dispatched to the task queue when called."""
+        ...
+```
+
+### Scheduled Tasks
+
+`@schedule` marks methods for periodic execution. Exactly one of `interval`, `at`, or `crontab`
+must be specified.
+
+```python
+from datetime import time, timedelta
+
+from spakky.task import TaskHandler, Crontab, Weekday, schedule
+
+
+@TaskHandler()
+class MaintenanceHandler:
+    @schedule(interval=timedelta(minutes=30))
+    def health_check(self) -> None:
+        """Runs every 30 minutes."""
+        ...
+
+    @schedule(at=time(3, 0))
+    def daily_cleanup(self) -> None:
+        """Runs daily at 03:00."""
+        ...
+
+    @schedule(crontab=Crontab(weekday=Weekday.MONDAY, hour=9))
+    def weekly_report(self) -> None:
+        """Runs every Monday at 09:00."""
+        ...
+```
+
+### Crontab Specification
+
+`Crontab` uses Python-native types instead of cron strings. `None` means "every" (wildcard).
+
+```python
+from spakky.task import Crontab, Weekday, Month
+
+# Every Monday at 03:00
+Crontab(weekday=Weekday.MONDAY, hour=3)
+
+# Mon/Wed/Fri at 09:00
+Crontab(weekday=(Weekday.MONDAY, Weekday.WEDNESDAY, Weekday.FRIDAY), hour=9)
+
+# 1st and 15th of every month at midnight
+Crontab(day=(1, 15))
+
+# Every January 1st at midnight
+Crontab(month=Month.JANUARY, day=1)
+```
+
+**Field order** (descending temporal granularity):
+
+| Field     | Type                              | Default |
+|-----------|-----------------------------------|---------|
+| `month`   | `Month \| tuple[Month, ...] \| None` | `None` (every) |
+| `day`     | `int \| tuple[int, ...] \| None`    | `None` (every) |
+| `weekday` | `Weekday \| tuple[Weekday, ...] \| None` | `None` (every) |
+| `hour`    | `int`                             | `0`     |
+| `minute`  | `int`                             | `0`     |
+
+### Accessing Task Routes
+
+```python
+from spakky.task import TaskRegistrationPostProcessor
+
+post_processor = container.get(TaskRegistrationPostProcessor)
+routes = post_processor.get_task_routes()
+# {<bound method send_email>: TaskRoute(), ...}
+```
+
+## Components
+
+| Component | Description |
+|-----------|-------------|
+| `TaskHandler` | Stereotype decorator for task handler classes |
+| `@task` | Method decorator for on-demand task dispatch |
+| `@schedule` | Method decorator for periodic execution (`interval`, `at`, `crontab`) |
+| `TaskRoute` | Annotation for `@task` methods |
+| `ScheduleRoute` | Annotation for `@schedule` methods |
+| `Crontab` | Frozen dataclass for cron-like schedule specification |
+| `Weekday` | `IntEnum` for day of the week (Monday=0 ... Sunday=6) |
+| `Month` | `IntEnum` for month of the year (January=1 ... December=12) |
+| `TaskRegistrationPostProcessor` | Scans `@TaskHandler` pods and collects `@task` methods |
+
+## Errors
+
+| Error | Description |
+|-------|-------------|
+| `TaskNotFoundError` | Task reference not found in the registry |
+| `DuplicateTaskError` | Attempting to register an already-registered task |
+| `InvalidScheduleSpecificationError` | `@schedule` called with zero or multiple schedule options |
+
+## Related Packages
+
+- **`spakky-celery`**: Celery backend for task dispatch and schedule registration via AOP
+
+## License
+
+MIT License

spakky_task-6.0.0/README.md

@@ -0,0 +1,136 @@
+# spakky-task
+
+Task queue abstraction layer for [Spakky Framework](https://github.com/E5resso/spakky-framework).
+
+## Installation
+
+```bash
+pip install spakky-task
+```
+
+## Features
+
+- **`@TaskHandler` stereotype**: Marks classes as task handler pods
+- **`@task` decorator**: Marks methods as on-demand dispatchable tasks
+- **`@schedule` decorator**: Marks methods for periodic execution (interval, daily, crontab)
+- **`Crontab` value object**: Python-native cron specification with `Weekday`/`Month` enums
+- **Post-processor**: Automatically scans and registers task routes from `@TaskHandler` pods
+- **Implementation-agnostic**: Works with any task queue backend (Celery, etc.) via plugins
+
+## Usage
+
+### On-Demand Tasks
+
+`@task` marks methods for on-demand dispatch. The backend plugin (e.g., `spakky-celery`)
+intercepts calls via AOP and routes them to the task queue.
+
+```python
+from spakky.task import TaskHandler, task
+
+
+@TaskHandler()
+class EmailTaskHandler:
+    @task
+    def send_email(self, to: str, subject: str, body: str) -> None:
+        """Dispatched to the task queue when called."""
+        ...
+```
+
+### Scheduled Tasks
+
+`@schedule` marks methods for periodic execution. Exactly one of `interval`, `at`, or `crontab`
+must be specified.
+
+```python
+from datetime import time, timedelta
+
+from spakky.task import TaskHandler, Crontab, Weekday, schedule
+
+
+@TaskHandler()
+class MaintenanceHandler:
+    @schedule(interval=timedelta(minutes=30))
+    def health_check(self) -> None:
+        """Runs every 30 minutes."""
+        ...
+
+    @schedule(at=time(3, 0))
+    def daily_cleanup(self) -> None:
+        """Runs daily at 03:00."""
+        ...
+
+    @schedule(crontab=Crontab(weekday=Weekday.MONDAY, hour=9))
+    def weekly_report(self) -> None:
+        """Runs every Monday at 09:00."""
+        ...
+```
+
+### Crontab Specification
+
+`Crontab` uses Python-native types instead of cron strings. `None` means "every" (wildcard).
+
+```python
+from spakky.task import Crontab, Weekday, Month
+
+# Every Monday at 03:00
+Crontab(weekday=Weekday.MONDAY, hour=3)
+
+# Mon/Wed/Fri at 09:00
+Crontab(weekday=(Weekday.MONDAY, Weekday.WEDNESDAY, Weekday.FRIDAY), hour=9)
+
+# 1st and 15th of every month at midnight
+Crontab(day=(1, 15))
+
+# Every January 1st at midnight
+Crontab(month=Month.JANUARY, day=1)
+```
+
+**Field order** (descending temporal granularity):
+
+| Field     | Type                              | Default |
+|-----------|-----------------------------------|---------|
+| `month`   | `Month \| tuple[Month, ...] \| None` | `None` (every) |
+| `day`     | `int \| tuple[int, ...] \| None`    | `None` (every) |
+| `weekday` | `Weekday \| tuple[Weekday, ...] \| None` | `None` (every) |
+| `hour`    | `int`                             | `0`     |
+| `minute`  | `int`                             | `0`     |
+
+### Accessing Task Routes
+
+```python
+from spakky.task import TaskRegistrationPostProcessor
+
+post_processor = container.get(TaskRegistrationPostProcessor)
+routes = post_processor.get_task_routes()
+# {<bound method send_email>: TaskRoute(), ...}
+```
+
+## Components
+
+| Component | Description |
+|-----------|-------------|
+| `TaskHandler` | Stereotype decorator for task handler classes |
+| `@task` | Method decorator for on-demand task dispatch |
+| `@schedule` | Method decorator for periodic execution (`interval`, `at`, `crontab`) |
+| `TaskRoute` | Annotation for `@task` methods |
+| `ScheduleRoute` | Annotation for `@schedule` methods |
+| `Crontab` | Frozen dataclass for cron-like schedule specification |
+| `Weekday` | `IntEnum` for day of the week (Monday=0 ... Sunday=6) |
+| `Month` | `IntEnum` for month of the year (January=1 ... December=12) |
+| `TaskRegistrationPostProcessor` | Scans `@TaskHandler` pods and collects `@task` methods |
+
+## Errors
+
+| Error | Description |
+|-------|-------------|
+| `TaskNotFoundError` | Task reference not found in the registry |
+| `DuplicateTaskError` | Attempting to register an already-registered task |
+| `InvalidScheduleSpecificationError` | `@schedule` called with zero or multiple schedule options |
+
+## Related Packages
+
+- **`spakky-celery`**: Celery backend for task dispatch and schedule registration via AOP
+
+## License
+
+MIT License

spakky_task-6.0.0/pyproject.toml

@@ -0,0 +1,69 @@
+[project]
+name = "spakky-task"
+version = "6.0.0"
+description = "Task queue abstraction for Spakky Framework (@TaskHandler, @task)"
+readme = "README.md"
+requires-python = ">=3.11"
+license = { text = "MIT" }
+authors = [{ name = "Spakky", email = "sejong418@icloud.com" }]
+dependencies = ["spakky>=6.0.0"]
+
+[project.entry-points."spakky.plugins"]
+spakky-task = "spakky.task.main:initialize"
+
+[build-system]
+requires = ["uv_build>=0.10.10,<0.11.0"]
+build-backend = "uv_build"
+
+[tool.uv.build-backend]
+module-root = "src"
+module-name = "spakky.task"
+
+[tool.pyrefly]
+python-version = "3.14"
+search_path = ["src", "."]
+project_excludes = ["**/__pycache__", "**/*.pyc"]
+
+[tool.ruff]
+builtins = ["_"]
+cache-dir = "~/.cache/ruff"
+
+[tool.pytest.ini_options]
+pythonpath = "src/spakky/task"
+testpaths = "tests"
+python_files = ["test_*.py"]
+asyncio_mode = "auto"
+addopts = """
+    --cov
+    --cov-report=term
+    --cov-report=xml
+    --no-cov-on-fail
+    --strict-markers
+    --dist=load
+    -p no:warnings
+    -n auto
+    --spec
+"""
+spec_test_format = "{result} {docstring_summary}"
+
+[tool.coverage.run]
+include = ["src/spakky/task/**/*.py"]
+branch = true
+
+[tool.coverage.report]
+show_missing = true
+precision = 2
+fail_under = 90
+skip_empty = true
+exclude_lines = [
+    "pragma: no cover",
+    "def __repr__",
+    "raise AssertionError",
+    "raise NotImplementedError",
+    "@(abc\\.)?abstractmethod",
+    "@(typing\\.)?overload",
+    "\\.\\.\\.",
+    "pass",
+]
+
+

spakky_task-6.0.0/src/spakky/task/__init__.py

@@ -0,0 +1,42 @@
+"""Spakky Task package - Task queue abstraction support."""
+
+from spakky.core.application.plugin import Plugin
+
+from spakky.task.error import (
+    AbstractSpakkyTaskError,
+    DuplicateTaskError,
+    InvalidScheduleSpecificationError,
+    TaskNotFoundError,
+)
+from spakky.task.post_processor import TaskRegistrationPostProcessor
+from spakky.task.stereotype.crontab import Crontab, Month, Weekday
+from spakky.task.stereotype.schedule import ScheduleRoute, schedule
+from spakky.task.stereotype.task_handler import (
+    TaskHandler,
+    TaskRoute,
+    task,
+)
+
+PLUGIN_NAME = Plugin(name="spakky-task")
+"""Plugin identifier for the Spakky Task package."""
+
+__all__ = [
+    # Stereotype
+    "TaskHandler",
+    "TaskRoute",
+    "task",
+    "Crontab",
+    "Weekday",
+    "Month",
+    "ScheduleRoute",
+    "schedule",
+    # Post-Processors
+    "TaskRegistrationPostProcessor",
+    # Errors
+    "AbstractSpakkyTaskError",
+    "TaskNotFoundError",
+    "DuplicateTaskError",
+    "InvalidScheduleSpecificationError",
+    # Plugin
+    "PLUGIN_NAME",
+]

spakky_task-6.0.0/src/spakky/task/error.py

@@ -0,0 +1,29 @@
+"""Spakky Task error hierarchy."""
+
+from abc import ABC
+
+from spakky.core.common.error import AbstractSpakkyFrameworkError
+
+
+class AbstractSpakkyTaskError(AbstractSpakkyFrameworkError, ABC):
+    """Base class for all spakky-task errors."""
+
+    ...
+
+
+class TaskNotFoundError(AbstractSpakkyTaskError):
+    """Raised when a task reference cannot be found in the registry."""
+
+    message = "Task not found in the registry"
+
+
+class DuplicateTaskError(AbstractSpakkyTaskError):
+    """Raised when attempting to register a task that already exists."""
+
+    message = "Duplicate task registered"
+
+
+class InvalidScheduleSpecificationError(AbstractSpakkyTaskError):
+    """Raised when a ScheduleRoute has invalid schedule options."""
+
+    message = "Exactly one of 'interval', 'at', or 'crontab' must be provided"

spakky_task-6.0.0/src/spakky/task/interfaces/task_result.py

@@ -0,0 +1,30 @@
+"""Abstract task result handle for background task dispatchers."""
+
+from abc import ABC, abstractmethod
+from typing import Generic, TypeVar
+
+from spakky.core.common.interfaces.equatable import IEquatable
+
+T = TypeVar("T")
+
+
+class AbstractTaskResult(ABC, Generic[T]):
+    """Abstract handle for the result of a dispatched background task.
+
+    Concrete adapters (e.g. CeleryTaskResult) implement this for each broker.
+    """
+
+    @property
+    @abstractmethod
+    def task_id(self) -> IEquatable:
+        """Unique identifier for the dispatched task."""
+        ...
+
+    @abstractmethod
+    def get(self) -> T:
+        """Block until the task completes and return its result.
+
+        Returns:
+            The return value of the executed task method.
+        """
+        ...

spakky_task-6.0.0/src/spakky/task/main.py

@@ -0,0 +1,14 @@
+"""Plugin initialization entry point."""
+
+from spakky.core.application.application import SpakkyApplication
+
+from spakky.task.post_processor import TaskRegistrationPostProcessor
+
+
+def initialize(app: SpakkyApplication) -> None:
+    """Initialize the spakky-task plugin.
+
+    Args:
+        app: The SpakkyApplication instance.
+    """
+    app.add(TaskRegistrationPostProcessor)

spakky_task-6.0.0/src/spakky/task/post_processor.py

@@ -0,0 +1,58 @@
+"""Task handler registration post-processor."""
+
+from inspect import getmembers, ismethod
+from logging import getLogger
+
+from spakky.core.common.types import Func
+from spakky.core.pod.annotations.pod import Pod
+from spakky.core.pod.interfaces.post_processor import IPostProcessor
+
+from spakky.task.stereotype.task_handler import TaskHandler, TaskRoute
+
+logger = getLogger(__name__)
+
+
+@Pod()
+class TaskRegistrationPostProcessor(IPostProcessor):
+    """Post-processor that scans @TaskHandler pods for @task methods.
+
+    This post-processor collects all task routes from TaskHandler pods
+    and makes them available for task queue implementations to register.
+    """
+
+    _task_routes: dict[Func, TaskRoute]
+
+    def __init__(self) -> None:
+        self._task_routes = {}
+
+    def post_process(self, pod: object) -> object:
+        """Scan pod for @task methods and register their routes.
+
+        Args:
+            pod: The pod instance to process.
+
+        Returns:
+            The unmodified pod instance.
+        """
+        pod_type = type(pod)
+
+        if not TaskHandler.exists(pod_type):
+            return pod
+
+        for name, method in getmembers(pod, predicate=ismethod):
+            route = TaskRoute.get_or_none(method)
+            if route is None:
+                continue
+
+            self._task_routes[method] = route
+            logger.debug(f"Registered task {pod_type.__name__}.{name}")
+
+        return pod
+
+    def get_task_routes(self) -> dict[Func, TaskRoute]:
+        """Get all registered task routes.
+
+        Returns:
+            Dictionary mapping task methods to their routes.
+        """
+        return self._task_routes.copy()

spakky_task-6.0.0/src/spakky/task/stereotype/__init__.py

@@ -0,0 +1 @@
+"""Task handler stereotype module."""

spakky_task-6.0.0/src/spakky/task/stereotype/crontab.py

@@ -0,0 +1,67 @@
+"""Crontab value object for schedule specification."""
+
+from dataclasses import dataclass
+from enum import IntEnum
+
+
+class Weekday(IntEnum):
+    """Day of the week (ISO 8601: Monday=0)."""
+
+    MONDAY = 0
+    TUESDAY = 1
+    WEDNESDAY = 2
+    THURSDAY = 3
+    FRIDAY = 4
+    SATURDAY = 5
+    SUNDAY = 6
+
+
+class Month(IntEnum):
+    """Month of the year (1-12)."""
+
+    JANUARY = 1
+    FEBRUARY = 2
+    MARCH = 3
+    APRIL = 4
+    MAY = 5
+    JUNE = 6
+    JULY = 7
+    AUGUST = 8
+    SEPTEMBER = 9
+    OCTOBER = 10
+    NOVEMBER = 11
+    DECEMBER = 12
+
+
+@dataclass(frozen=True)
+class Crontab:
+    """Cron-like schedule specification using Python native types.
+
+    Fields use ``None`` to mean "every" (wildcard).
+    A single ``int`` means exactly that value; a ``tuple`` means multiple values.
+
+    Example:
+        # Every Monday at 03:00
+        Crontab(weekday=Weekday.MONDAY, hour=3)
+
+        # Mon/Wed/Fri at 09:00
+        Crontab(weekday=(Weekday.MONDAY, Weekday.WEDNESDAY, Weekday.FRIDAY), hour=9)
+
+        # 1st and 15th of every month at midnight
+        Crontab(day=(1, 15))
+    """
+
+    month: Month | tuple[Month, ...] | None = None
+    """Month of the year. None means every month."""
+
+    day: int | tuple[int, ...] | None = None
+    """Day of the month (1-31). None means every day."""
+
+    weekday: Weekday | tuple[Weekday, ...] | None = None
+    """Day of the week. None means every day."""
+
+    hour: int = 0
+    """Hour of the day (0-23)."""
+
+    minute: int = 0
+    """Minute of the hour (0-59)."""

spakky_task-6.0.0/src/spakky/task/stereotype/schedule.py

@@ -0,0 +1,76 @@
+"""Schedule stereotype for periodic task execution.
+
+Provides @schedule decorator to mark TaskHandler methods for
+periodic execution (interval, daily, or crontab-based).
+"""
+
+from dataclasses import dataclass
+from datetime import time, timedelta
+from typing import Callable, ParamSpec, TypeVar, cast
+
+from spakky.core.common.annotation import FunctionAnnotation
+
+from spakky.task.error import InvalidScheduleSpecificationError
+from spakky.task.stereotype.crontab import Crontab
+
+P = ParamSpec("P")
+T = TypeVar("T")
+
+
+@dataclass
+class ScheduleRoute(FunctionAnnotation):
+    """Annotation for marking methods as periodically scheduled tasks.
+
+    Exactly one of ``interval``, ``at``, or ``crontab`` must be provided.
+    """
+
+    interval: timedelta | None = None
+    """Fixed interval between executions."""
+
+    at: time | None = None
+    """Daily execution at a specific time."""
+
+    crontab: Crontab | None = None
+    """Cron-like schedule specification."""
+
+    def __post_init__(self) -> None:
+        specified = sum(x is not None for x in (self.interval, self.at, self.crontab))
+        if specified != 1:
+            raise InvalidScheduleSpecificationError()
+
+
+def schedule(
+    *,
+    interval: timedelta | None = None,
+    at: time | None = None,
+    crontab: Crontab | None = None,
+) -> Callable[[Callable[P, T]], Callable[P, T]]:
+    """Decorator for marking methods as periodically scheduled tasks.
+
+    Exactly one of ``interval``, ``at``, or ``crontab`` must be specified.
+
+    Example:
+        @TaskHandler()
+        class MaintenanceHandler:
+            @schedule(interval=timedelta(minutes=30))
+            def health_check(self) -> None:
+                ...
+
+            @schedule(at=time(3, 0))
+            def daily_cleanup(self) -> None:
+                ...
+
+            @schedule(crontab=Crontab(hour=9, weekday=(Weekday.MONDAY, Weekday.WEDNESDAY, Weekday.FRIDAY)))
+            def triweekly_report(self) -> None:
+                ...
+
+    Args:
+        interval: Fixed interval between executions.
+        at: Daily execution at a specific time.
+        crontab: Cron-like schedule specification.
+
+    Returns:
+        A decorator that annotates the method with ScheduleRoute.
+    """
+    route = ScheduleRoute(interval=interval, at=at, crontab=crontab)
+    return cast(Callable[[Callable[P, T]], Callable[P, T]], route)

spakky_task-6.0.0/src/spakky/task/stereotype/task_handler.py

@@ -0,0 +1,55 @@
+"""TaskHandler stereotype and task routing decorators.
+
+This module provides @TaskHandler stereotype and @task decorator
+for organizing task-queue-driven architectures.
+"""
+
+from dataclasses import dataclass
+from typing import Callable, ParamSpec, TypeVar, cast
+
+from spakky.core.common.annotation import FunctionAnnotation
+from spakky.core.pod.annotations.pod import Pod
+
+P = ParamSpec("P")
+T = TypeVar("T")
+
+
+@dataclass
+class TaskRoute(FunctionAnnotation):
+    """Annotation for marking methods as dispatchable tasks.
+
+    Associates a method as a task that can be dispatched to a task queue.
+    """
+
+
+def task(obj: Callable[P, T]) -> Callable[P, T]:
+    """Decorator for marking methods as dispatchable tasks.
+
+    All @task methods are dispatched to the task queue by the plugin aspect.
+
+    Example:
+        @TaskHandler()
+        class EmailTaskHandler:
+            @task
+            def send_email(self, to: str, subject: str, body: str) -> None:
+                ...
+
+    Args:
+        obj: The method to mark as a task.
+
+    Returns:
+        The annotated method.
+    """
+    route = TaskRoute()
+    return cast(Callable[P, T], route(obj))
+
+
+@dataclass(eq=False)
+class TaskHandler(Pod):
+    """Stereotype for task handler classes.
+
+    TaskHandlers contain methods decorated with @task that
+    can be dispatched to task queues asynchronously.
+    """
+
+    ...