plain.jobs 0.43.2__py3-none-any.whl

plain/jobs/parameters.py

@@ -0,0 +1,193 @@
+from __future__ import annotations
+
+import datetime
+from typing import Any
+
+from plain.models import Model, models_registry
+
+
+class JobParameter:
+    """Base class for job parameter serialization/deserialization."""
+
+    STR_PREFIX: str | None = None  # Subclasses should define this
+
+    @classmethod
+    def serialize(cls, value: Any) -> str | None:
+        """Return serialized string or None if can't handle this value."""
+        return None
+
+    @classmethod
+    def deserialize(cls, data: Any) -> Any:
+        """Return deserialized value or None if can't handle this data."""
+        return None
+
+    @classmethod
+    def _extract_string_value(cls, data: Any) -> str | None:
+        """Extract value from string with prefix, return None if invalid format."""
+        if not isinstance(data, str) or not cls.STR_PREFIX:
+            return None
+        if not data.startswith(cls.STR_PREFIX) or len(data) <= len(cls.STR_PREFIX):
+            return None
+        return data[len(cls.STR_PREFIX) :]
+
+
+class ModelParameter(JobParameter):
+    """Handle Plain model instances using a new string format."""
+
+    STR_PREFIX = "__plain://model/"
+
+    @classmethod
+    def serialize(cls, value: Any) -> str | None:
+        if isinstance(value, Model):
+            return f"{cls.STR_PREFIX}{value.model_options.package_label}/{value.model_options.model_name}/{value.id}"
+        return None
+
+    @classmethod
+    def deserialize(cls, data: Any) -> Model | None:
+        if value_part := cls._extract_string_value(data):
+            try:
+                parts = value_part.split("/")
+                if len(parts) == 3 and all(parts):
+                    package, model_name, obj_id = parts
+                    model = models_registry.get_model(package, model_name)
+                    return model.query.get(id=obj_id)
+            except (ValueError, Exception):
+                pass
+        return None
+
+
+class DateParameter(JobParameter):
+    """Handle date objects."""
+
+    STR_PREFIX = "__plain://date/"
+
+    @classmethod
+    def serialize(cls, value: Any) -> str | None:
+        if isinstance(value, datetime.date) and not isinstance(
+            value, datetime.datetime
+        ):
+            return f"{cls.STR_PREFIX}{value.isoformat()}"
+        return None
+
+    @classmethod
+    def deserialize(cls, data: Any) -> datetime.date | None:
+        if value_part := cls._extract_string_value(data):
+            try:
+                return datetime.date.fromisoformat(value_part)
+            except ValueError:
+                pass
+        return None
+
+
+class DateTimeParameter(JobParameter):
+    """Handle datetime objects."""
+
+    STR_PREFIX = "__plain://datetime/"
+
+    @classmethod
+    def serialize(cls, value: Any) -> str | None:
+        if isinstance(value, datetime.datetime):
+            return f"{cls.STR_PREFIX}{value.isoformat()}"
+        return None
+
+    @classmethod
+    def deserialize(cls, data: Any) -> datetime.datetime | None:
+        if value_part := cls._extract_string_value(data):
+            try:
+                return datetime.datetime.fromisoformat(value_part)
+            except ValueError:
+                pass
+        return None
+
+
+class LegacyModelParameter(JobParameter):
+    """Legacy model parameter handling for backwards compatibility."""
+
+    STR_PREFIX = "gid://"
+
+    @classmethod
+    def serialize(cls, value: Any) -> str | None:
+        # Don't serialize new instances with legacy format
+        return None
+
+    @classmethod
+    def deserialize(cls, data: Any) -> Model | None:
+        if value_part := cls._extract_string_value(data):
+            try:
+                package, model, obj_id = value_part.split("/")
+                model = models_registry.get_model(package, model)
+                return model.query.get(id=obj_id)
+            except (ValueError, Exception):
+                pass
+        return None
+
+
+# Registry of parameter types to check in order
+# The order matters - more specific types should come first
+# DateTimeParameter must come before DateParameter since datetime is a subclass of date
+# LegacyModelParameter is last since it only handles deserialization
+PARAMETER_TYPES = [
+    ModelParameter,
+    DateTimeParameter,
+    DateParameter,
+    LegacyModelParameter,
+]
+
+
+class JobParameters:
+    """
+    Main interface for serializing and deserializing job parameters.
+    Uses the registered parameter types to handle different value types.
+    """
+
+    @staticmethod
+    def to_json(args: tuple[Any, ...], kwargs: dict[str, Any]) -> dict[str, Any]:
+        serialized_args = []
+        for arg in args:
+            serialized = JobParameters._serialize_value(arg)
+            serialized_args.append(serialized)
+
+        serialized_kwargs = {}
+        for key, value in kwargs.items():
+            serialized = JobParameters._serialize_value(value)
+            serialized_kwargs[key] = serialized
+
+        return {"args": serialized_args, "kwargs": serialized_kwargs}
+
+    @staticmethod
+    def _serialize_value(value: Any) -> Any:
+        """Serialize a single value using the registered parameter types."""
+        # Try each parameter type to see if it can serialize this value
+        for param_type in PARAMETER_TYPES:
+            result = param_type.serialize(value)
+            if result is not None:
+                return result
+
+        # If no parameter type can handle it, return as-is
+        return value
+
+    @staticmethod
+    def from_json(data: dict[str, Any]) -> tuple[tuple[Any, ...], dict[str, Any]]:
+        args = []
+        for arg in data["args"]:
+            deserialized = JobParameters._deserialize_value(arg)
+            args.append(deserialized)
+
+        kwargs = {}
+        for key, value in data["kwargs"].items():
+            deserialized = JobParameters._deserialize_value(value)
+            kwargs[key] = deserialized
+
+        return tuple(args), kwargs
+
+    @staticmethod
+    def _deserialize_value(value: Any) -> Any:
+        """Deserialize a single value using the registered parameter types."""
+        # Try each parameter type to see if it can deserialize this value
+        for param_type in PARAMETER_TYPES:
+            result = param_type.deserialize(value)
+            if result is not None:
+                return result
+
+        # If no parameter type can handle it, return as-is
+        return value

plain/jobs/registry.py

@@ -0,0 +1,60 @@
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import TYPE_CHECKING, Any, TypeVar
+
+from .parameters import JobParameters
+
+if TYPE_CHECKING:
+    from .jobs import Job
+
+T = TypeVar("T", bound=type["Job"])
+
+
+class JobsRegistry:
+    def __init__(self) -> None:
+        self.jobs: dict[str, type[Job]] = {}
+        self.ready = False
+
+    def register_job(self, job_class: type[Job], alias: str = "") -> None:
+        name = self.get_job_class_name(job_class)
+        self.jobs[name] = job_class
+
+        if alias:
+            self.jobs[alias] = job_class
+
+    def get_job_class_name(self, job_class: type[Job]) -> str:
+        return f"{job_class.__module__}.{job_class.__qualname__}"
+
+    def get_job_class(self, name: str) -> type[Job]:
+        return self.jobs[name]
+
+    def load_job(self, job_class_name: str, parameters: dict[str, Any]) -> Job:
+        if not self.ready:
+            raise RuntimeError("Jobs registry is not ready yet")
+
+        job_class = self.get_job_class(job_class_name)
+        args, kwargs = JobParameters.from_json(parameters)
+        return job_class(*args, **kwargs)
+
+
+jobs_registry = JobsRegistry()
+
+
+def register_job(
+    job_class: T | None = None, *, alias: str = ""
+) -> T | Callable[[T], T]:
+    """
+    A decorator that registers a job class in the jobs registry with an optional alias.
+    Can be used both with and without parentheses.
+    """
+    if job_class is None:
+
+        def wrapper(cls: T) -> T:
+            jobs_registry.register_job(cls, alias=alias)
+            return cls
+
+        return wrapper
+    else:
+        jobs_registry.register_job(job_class, alias=alias)
+        return job_class

plain/jobs/scheduling.py

@@ -0,0 +1,253 @@
+from __future__ import annotations
+
+import datetime
+import subprocess
+from typing import Any
+
+from plain.utils import timezone
+
+from .jobs import Job
+from .registry import jobs_registry, register_job
+
+_MONTH_NAMES = {
+    "JAN": 1,
+    "FEB": 2,
+    "MAR": 3,
+    "APR": 4,
+    "MAY": 5,
+    "JUN": 6,
+    "JUL": 7,
+    "AUG": 8,
+    "SEP": 9,
+    "OCT": 10,
+    "NOV": 11,
+    "DEC": 12,
+}
+_DAY_NAMES = {
+    "MON": 0,
+    "TUE": 1,
+    "WED": 2,
+    "THU": 3,
+    "FRI": 4,
+    "SAT": 5,
+    "SUN": 6,
+}
+
+
+class _ScheduleComponent:
+    def __init__(self, values: list[int], raw: str | int = "") -> None:
+        self.values = sorted(values)
+        self._raw = raw
+
+    def __str__(self) -> str:
+        if self._raw:
+            return str(self._raw)
+        return ",".join(str(v) for v in self.values)
+
+    def __eq__(self, other: Any) -> bool:
+        return self.values == other.values
+
+    @classmethod
+    def parse(
+        cls,
+        value: int | str,
+        min_allowed: int,
+        max_allowed: int,
+        str_conversions: dict[str, int] | None = None,
+    ) -> _ScheduleComponent:
+        if str_conversions is None:
+            str_conversions = {}
+
+        if isinstance(value, int):
+            if value < min_allowed or value > max_allowed:
+                raise ValueError(
+                    f"Schedule component should be between {min_allowed} and {max_allowed}"
+                )
+            return cls([value], raw=value)
+
+        if not isinstance(value, str):
+            raise ValueError("Schedule component should be an int or str")
+
+        # First split any subcomponents and re-parse them
+        if "," in value:
+            return cls(
+                sum(
+                    (
+                        cls.parse(
+                            sub_value, min_allowed, max_allowed, str_conversions
+                        ).values
+                        for sub_value in value.split(",")
+                    ),
+                    [],
+                ),
+                raw=value,
+            )
+
+        if value == "*":
+            return cls(list(range(min_allowed, max_allowed + 1)), raw=value)
+
+        def _convert(value: str) -> int:
+            result = str_conversions.get(value.upper(), value)
+            return int(result)
+
+        if "/" in value:
+            values, step = value.split("/")
+            values = cls.parse(values, min_allowed, max_allowed, str_conversions)
+            return cls([v for v in values.values if v % int(step) == 0], raw=value)
+
+        if "-" in value:
+            start, end = value.split("-")
+            return cls(list(range(_convert(start), _convert(end) + 1)), raw=value)
+
+        return cls([_convert(value)], raw=value)
+
+
+class Schedule:
+    def __init__(
+        self,
+        *,
+        minute: int | str = "*",
+        hour: int | str = "*",
+        day_of_month: int | str = "*",
+        month: int | str = "*",
+        day_of_week: int | str = "*",
+        raw: str = "",
+    ) -> None:
+        self.minute = _ScheduleComponent.parse(minute, min_allowed=0, max_allowed=59)
+        self.hour = _ScheduleComponent.parse(hour, min_allowed=0, max_allowed=23)
+        self.day_of_month = _ScheduleComponent.parse(
+            day_of_month, min_allowed=1, max_allowed=31
+        )
+        self.month = _ScheduleComponent.parse(
+            month,
+            min_allowed=1,
+            max_allowed=12,
+            str_conversions=_MONTH_NAMES,
+        )
+        self.day_of_week = _ScheduleComponent.parse(
+            day_of_week,
+            min_allowed=0,
+            max_allowed=6,
+            str_conversions=_DAY_NAMES,
+        )
+        self._raw = raw
+
+    def __str__(self) -> str:
+        if self._raw:
+            return self._raw
+        return f"{self.minute} {self.hour} {self.day_of_month} {self.month} {self.day_of_week}"
+
+    def __repr__(self) -> str:
+        return f"<Schedule {self}>"
+
+    @classmethod
+    def from_cron(cls, cron: str) -> Schedule:
+        raw = cron
+
+        if cron == "@yearly" or cron == "@annually":
+            cron = "0 0 1 1 *"
+        elif cron == "@monthly":
+            cron = "0 0 1 * *"
+        elif cron == "@weekly":
+            cron = "0 0 * * 0"
+        elif cron == "@daily" or cron == "@midnight":
+            cron = "0 0 * * *"
+        elif cron == "@hourly":
+            cron = "0 * * * *"
+
+        minute, hour, day_of_month, month, day_of_week = cron.split()
+
+        return cls(
+            minute=minute,
+            hour=hour,
+            day_of_month=day_of_month,
+            month=month,
+            day_of_week=day_of_week,
+            raw=raw,
+        )
+
+    def next(self, now: datetime.datetime | None = None) -> datetime.datetime:
+        """
+        Find the next datetime that matches the schedule after the given datetime.
+        """
+        dt = now or timezone.localtime()  # Use the defined plain timezone by default
+
+        # We only care about minutes, so immediately jump to the next minute
+        dt += datetime.timedelta(minutes=1)
+        dt = dt.replace(second=0, microsecond=0)
+
+        def _go_to_next_day(v: datetime.datetime) -> datetime.datetime:
+            v = v + datetime.timedelta(days=1)
+            return v.replace(
+                hour=self.hour.values[0],
+                minute=self.minute.values[0],
+            )
+
+        # If we don't find a value in the next 500 days,
+        # then the schedule is probably never going to match (i.e. Feb 31)
+        max_future = dt + datetime.timedelta(days=500)
+
+        while True:
+            is_valid_day = (
+                dt.month in self.month.values
+                and dt.day in self.day_of_month.values
+                and dt.weekday() in self.day_of_week.values
+            )
+            if is_valid_day:
+                # We're on a valid day, now find the next valid hour and minute
+                for hour in self.hour.values:
+                    if hour < dt.hour:
+                        continue
+                    for minute in self.minute.values:
+                        if hour == dt.hour and minute < dt.minute:
+                            continue
+                        candidate_datetime = dt.replace(hour=hour, minute=minute)
+                        if candidate_datetime >= dt:
+                            return candidate_datetime
+                # If no valid time is found today, reset to the first valid minute and hour of the next day
+                dt = _go_to_next_day(dt)
+            else:
+                # Increment the day until a valid month/day/weekday combination is found
+                dt = _go_to_next_day(dt)
+
+            if dt > max_future:
+                raise ValueError("No valid schedule match found in the next 500 days")
+
+
+@register_job
+class ScheduledCommand(Job):
+    """Run a shell command on a schedule."""
+
+    def __init__(self, command: str) -> None:
+        self.command = command
+
+    def __repr__(self) -> str:
+        return f"<ScheduledCommand: {self.command}>"
+
+    def run(self) -> None:
+        subprocess.run(self.command, shell=True, check=True)
+
+    def default_concurrency_key(self) -> str:
+        # The ScheduledCommand can be used for different commands,
+        # so we need the concurrency_key to separate them for uniqueness
+        return self.command
+
+
+def load_schedule(
+    schedules: list[tuple[str | Job, str | Schedule]],
+) -> list[tuple[Job, Schedule]]:
+    jobs_schedule: list[tuple[Job, Schedule]] = []
+
+    for job, schedule in schedules:
+        if isinstance(job, str):
+            if job.startswith("cmd:"):
+                job = ScheduledCommand(job[4:])
+            else:
+                job = jobs_registry.load_job(job, {"args": [], "kwargs": {}})
+
+        if isinstance(schedule, str):
+            schedule = Schedule.from_cron(schedule)
+
+        jobs_schedule.append((job, schedule))
+
+    return jobs_schedule

plain/jobs/templates/admin/plainqueue/jobresult_detail.html

@@ -0,0 +1,8 @@
+{% extends "admin/detail.html" %}
+
+{% block actions %}
+<form method="post">
+    <input type="hidden" name="action" value="retry">
+    <button type="submit">Retry job</button>
+</form>
+{% endblock %}