plain.jobs 0.34.0__py3-none-any.whl → 0.35.1__py3-none-any.whl

plain/jobs/CHANGELOG.md

@@ -1,5 +1,32 @@
 # plain-jobs changelog
 
+## [0.35.1](https://github.com/dropseed/plain/releases/plain-jobs@0.35.1) (2025-10-17)
+
+### What's changed
+
+- The `run_in_worker()` method now returns `None` when a duplicate job is detected instead of attempting to return the list of in-progress jobs ([72f48d21bc](https://github.com/dropseed/plain/commit/72f48d21bc))
+- Fixed type annotations for `run_in_worker()` to properly indicate it can return `JobRequest | None` ([72f48d21bc](https://github.com/dropseed/plain/commit/72f48d21bc))
+- The `retry_job()` method now properly handles explicit `delay=0` parameter to intentionally retry immediately ([72f48d21bc](https://github.com/dropseed/plain/commit/72f48d21bc))
+- Fixed type annotations for `retry_job()` to properly indicate it can return `JobRequest | None` ([72f48d21bc](https://github.com/dropseed/plain/commit/72f48d21bc))
+
+### Upgrade instructions
+
+- No changes required
+
+## [0.35.0](https://github.com/dropseed/plain/releases/plain-jobs@0.35.0) (2025-10-17)
+
+### What's changed
+
+- The `Job` base class is now an abstract base class requiring implementation of the `run()` method ([e34282bba8](https://github.com/dropseed/plain/commit/e34282bba8))
+- Job worker processes now properly initialize the Plain framework before processing jobs, fixing potential startup issues ([c4551d1b84](https://github.com/dropseed/plain/commit/c4551d1b84))
+- The `plain jobs list` command now displays job descriptions from docstrings in a cleaner format ([4b6881a49e](https://github.com/dropseed/plain/commit/4b6881a49e))
+- Job requests in the admin interface are now ordered by priority, start time, and created time to match worker processing order ([c18f0e3fb6](https://github.com/dropseed/plain/commit/c18f0e3fb6))
+- The `ClearCompleted` chore has been refactored to use the new abstract base class pattern ([c4466d3c60](https://github.com/dropseed/plain/commit/c4466d3c60))
+
+### Upgrade instructions
+
+- No changes required
+
 ## [0.34.0](https://github.com/dropseed/plain/releases/plain-jobs@0.34.0) (2025-10-13)
 
 ### What's changed

plain/jobs/admin.py

@@ -109,6 +109,7 @@ class JobRequestViewset(AdminViewset):
         title = "Requests"
         fields = ["id", "job_class", "priority", "created_at", "start_at", "unique_key"]
         actions = ["Delete"]
+        queryset_order = ["priority", "-start_at", "-created_at"]
 
         def perform_action(self, action: str, target_ids: list[int]) -> None:
             if action == "Delete":

plain/jobs/chores.py

@@ -1,17 +1,19 @@
 import datetime
 
-from plain.chores import register_chore
+from plain.chores import Chore, register_chore
 from plain.runtime import settings
 from plain.utils import timezone
 
 from .models import JobResult
 
 
-@register_chore("jobs")
-def clear_completed() -> str:
+@register_chore
+class ClearCompleted(Chore):
     """Delete all completed job results in all queues."""
-    cutoff = timezone.now() - datetime.timedelta(
-        seconds=settings.JOBS_RESULTS_RETENTION
-    )
-    results = JobResult.query.filter(created_at__lt=cutoff).delete()
-    return f"{results[0]} jobs deleted"
+
+    def run(self) -> str:
+        cutoff = timezone.now() - datetime.timedelta(
+            seconds=settings.JOBS_RESULTS_RETENTION
+        )
+        results = JobResult.query.filter(created_at__lt=cutoff).delete()
+        return f"{results[0]} jobs deleted"

plain/jobs/cli.py

@@ -195,4 +195,10 @@ def run(job_class_name: str) -> None:
 def list_jobs() -> None:
     """List all registered jobs."""
     for name, job_class in jobs_registry.jobs.items():
-        click.echo(f"{click.style(name, fg='blue')}: {job_class}")
+        click.secho(f"{name}", bold=True, nl=False)
+        # Get description from class docstring
+        description = job_class.__doc__.strip() if job_class.__doc__ else ""
+        if description:
+            click.secho(f": {description}", dim=True)
+        else:
+            click.echo("")

plain/jobs/jobs.py

@@ -3,6 +3,7 @@ from __future__ import annotations
 import datetime
 import inspect
 import logging
+from abc import ABCMeta, abstractmethod
 from typing import TYPE_CHECKING, Any
 
 from opentelemetry import trace
@@ -33,7 +34,7 @@ logger = logging.getLogger(__name__)
 tracer = trace.get_tracer("plain.jobs")
 
 
-class JobType(type):
+class JobType(ABCMeta):
     """
     Metaclass allows us to capture the original args/kwargs
     used to instantiate the job, so we can store them in the database
@@ -48,8 +49,9 @@ class JobType(type):
 
 
 class Job(metaclass=JobType):
+    @abstractmethod
     def run(self) -> None:
-        raise NotImplementedError
+        pass
 
     def run_in_worker(
         self,
@@ -60,7 +62,7 @@ class Job(metaclass=JobType):
         retries: int | None = None,
         retry_attempt: int = 0,
         unique_key: str | None = None,
-    ) -> JobRequest | list[JobRequest | JobProcess]:
+    ) -> JobRequest | None:
         from .models import JobRequest
 
         job_class_name = jobs_registry.get_job_class_name(self.__class__)
@@ -168,8 +170,7 @@ class Job(metaclass=JobType):
                 span.set_attribute(ERROR_TYPE, "IntegrityError")
                 span.set_status(trace.Status(trace.StatusCode.ERROR, "Duplicate job"))
                 logger.warning("Job already in progress: %s", e)
-                # Try to return the _in_progress list again
-                return self._in_progress(unique_key)
+                return None
 
     def _in_progress(self, unique_key: str) -> list[JobRequest | JobProcess]:
         """Get all JobRequests and JobProcess that are currently in progress, regardless of queue."""

plain/jobs/models.py

@@ -412,10 +412,14 @@ class JobResult(models.Model):
         ],
     )
 
-    def retry_job(self, delay: int | None = None) -> JobRequest:
+    def retry_job(self, delay: int | None = None) -> JobRequest | None:
         retry_attempt = self.retry_attempt + 1
         job = jobs_registry.load_job(self.job_class, self.parameters)
-        retry_delay = delay or job.get_retry_delay(retry_attempt)
+
+        if delay is None:
+            retry_delay = job.get_retry_delay(retry_attempt)
+        else:
+            retry_delay = delay
 
         with transaction.atomic():
             result = job.run_in_worker(
@@ -427,12 +431,9 @@ class JobResult(models.Model):
                 retry_attempt=retry_attempt,
                 # Unique key could be passed also?
             )
+            if result:
+                self.retry_job_request_uuid = result.uuid
+                self.save(update_fields=["retry_job_request_uuid"])
+                return result
 
-            # TODO it is actually possible that result is a list
-            # of pending jobs, which would need to be handled...
-            # Right now it will throw an exception which could be caught by retry_failed_jobs.
-
-            self.retry_job_request_uuid = result.uuid  # type: ignore
-            self.save(update_fields=["retry_job_request_uuid"])
-
-        return result  # type: ignore
+        return None

plain/jobs/scheduling.py

@@ -216,6 +216,8 @@ class Schedule:
 
 @register_job
 class ScheduledCommand(Job):
+    """Run a shell command on a schedule."""
+
     def __init__(self, command: str) -> None:
         self.command = command
 

plain/jobs/workers.py

@@ -7,7 +7,7 @@ import os
 import time
 from concurrent.futures import Future, ProcessPoolExecutor
 from functools import partial
-from typing import Any
+from typing import TYPE_CHECKING, Any
 
 from plain import models
 from plain.models import transaction
@@ -16,12 +16,44 @@ from plain.signals import request_finished, request_started
 from plain.utils import timezone
 from plain.utils.module_loading import import_string
 
-from .models import JobProcess, JobRequest, JobResult, JobResultStatuses
 from .registry import jobs_registry
 
+if TYPE_CHECKING:
+    from .models import JobResult
+
+# Models are NOT imported at the top of this file!
+# See comment on _worker_process_initializer() for explanation.
+
 logger = logging.getLogger("plain.jobs")
 
 
+def _worker_process_initializer() -> None:
+    """Initialize Plain framework in worker process before processing jobs.
+
+    Why this is needed:
+    - We use multiprocessing with 'spawn' context (not 'fork')
+    - Spawn creates fresh Python processes, not forked copies
+    - When a spawned process starts, it re-imports this module BEFORE the initializer runs
+    - If we imported models at the top of this file, model registration would
+      happen before plain.runtime.setup(), causing PackageRegistryNotReady errors
+
+    Solution:
+    - This initializer runs plain.runtime.setup() FIRST in each worker process
+    - All model imports happen lazily inside functions (after setup completes)
+    - This ensures packages registry is ready before any models are accessed
+
+    Execution order in spawned worker:
+    1. Re-import workers.py (but models NOT imported yet - lazy!)
+    2. Run this initializer → plain.runtime.setup()
+    3. Execute process_job() → NOW it's safe to import models
+    """
+    from plain.runtime import setup
+
+    # Each spawned worker process needs to set up Plain
+    # (spawn context creates fresh processes, not forks)
+    setup()
+
+
 class Worker:
     def __init__(
         self,
@@ -39,6 +71,7 @@ class Worker:
             max_workers=max_processes,
             max_tasks_per_child=max_jobs_per_process,
             mp_context=multiprocessing.get_context("spawn"),
+            initializer=_worker_process_initializer,
         )
 
         self.queues = queues
@@ -56,6 +89,9 @@ class Worker:
         self._is_shutting_down = False
 
     def run(self) -> None:
+        # Lazy import - see _worker_process_initializer() comment for why
+        from .models import JobRequest
+
         logger.info(
             "⬣ Starting Plain worker\n    Registered jobs: %s\n    Queues: %s\n    Jobs schedule: %s\n    Stats every: %s seconds\n    Max processes: %s\n    Max jobs per process: %s\n    Max pending per process: %s\n    PID: %s",
             "\n                     ".join(
@@ -211,6 +247,9 @@ class Worker:
             self._jobs_schedule_checked_at = now
 
     def log_stats(self) -> None:
+        # Lazy import - see _worker_process_initializer() comment for why
+        from .models import JobProcess, JobRequest
+
         try:
             num_proccesses = len(self.executor._processes)
         except (AttributeError, TypeError):
@@ -232,12 +271,18 @@ class Worker:
 
     def rescue_job_results(self) -> None:
         """Find any lost or failed jobs on this worker's queues and handle them."""
+        # Lazy import - see _worker_process_initializer() comment for why
+        from .models import JobProcess, JobResult
+
         # TODO return results and log them if there are any?
         JobProcess.query.filter(queue__in=self.queues).mark_lost_jobs()
         JobResult.query.filter(queue__in=self.queues).retry_failed_jobs()
 
 
 def future_finished_callback(job_process_uuid: str, future: Future) -> None:
+    # Lazy import - see _worker_process_initializer() comment for why
+    from .models import JobProcess, JobResultStatuses
+
     if future.cancelled():
         logger.warning("Job cancelled job_process_uuid=%s", job_process_uuid)
         try:
@@ -264,6 +309,9 @@ def future_finished_callback(job_process_uuid: str, future: Future) -> None:
 
 
 def process_job(job_process_uuid: str) -> None:
+    # Lazy import - see _worker_process_initializer() comment for why
+    from .models import JobProcess
+
     try:
         worker_pid = os.getpid()
 

{plain_jobs-0.34.0.dist-info → plain_jobs-0.35.1.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: plain.jobs
-Version: 0.34.0
+Version: 0.35.1
 Summary: Process background jobs with a database-driven job queue.
 Author-email: Dave Gaeddert <dave.gaeddert@dropseed.dev>
 License-File: LICENSE

{plain_jobs-0.34.0.dist-info → plain_jobs-0.35.1.dist-info}/RECORD

@@ -1,18 +1,18 @@
-plain/jobs/CHANGELOG.md,sha256=6jaE6mdMVx7jX9UFk5eEqT31LC0CgRVTJHGrwObeES4,9384
+plain/jobs/CHANGELOG.md,sha256=o0DXNqFtf8N7ndAfzEUxyb5Zvl1V-ASquJl3yxDy5NY,11310
 plain/jobs/README.md,sha256=Xuhz2Q48G9WeGCh5OWGVBlaSea4eKCqWzcTAtZRrS0I,6835
 plain/jobs/__init__.py,sha256=p2ATql3HyPzPTV34gJQ04caT7tcNQLbBGM6uIoDPbjo,92
-plain/jobs/admin.py,sha256=IhB6nkHKHB5CJfwPEoNW4pQKUi_4ewpNGkOCo4XwO0g,6719
-plain/jobs/chores.py,sha256=5WdLlCDPppX78yfS4LczIG7UeVR9DAoJsJHTT2Codd4,483
-plain/jobs/cli.py,sha256=KnazGup1JumjrSjhoMO2FwgLBATRW70YewkdMcLzsrI,5683
+plain/jobs/admin.py,sha256=t1UEchq1-Eews_wPsVUofaqbzPaYpb-8H1bUlA59JGI,6785
+plain/jobs/chores.py,sha256=oyVU-BfcJxMM3eK2_umn38N2mBsNpcDrZfpeEQju_DA,528
+plain/jobs/cli.py,sha256=PPoT7xjl818BZnmI0yA_UCLEQkzl_Tv1_hiuJW9UE-Q,5911
 plain/jobs/config.py,sha256=PQsl-LxWsWLnjC98f0mvtdcCOuXvXKDMjrCRf1fq44Y,550
 plain/jobs/default_settings.py,sha256=r_95ucg_KY1XW1jarZy8VO3p-ylbllKMUrHzOPJiX6U,227
-plain/jobs/jobs.py,sha256=IPQ2vlhfLm5gvdZTR52WINDAWRUPN0Mjc_EhKjqYhAk,7843
+plain/jobs/jobs.py,sha256=ZEne6eTVPoWBv-JUAB9GugdIR0pb2I5SDfJlxCrNI4c,7775
 plain/jobs/middleware.py,sha256=bz8aPBY0RbtLS4kic8mzPOd3EyQFCVRQ2uTCttT3RpE,573
-plain/jobs/models.py,sha256=EvO5vHbsTdI0OJIIJRpGEKks9pm_INB33B1q6VeMSUc,16014
+plain/jobs/models.py,sha256=TYOjMT0dSF69uzfY2m13ZPwo6G0WOVJUbgJvsDFxBhI,15889
 plain/jobs/parameters.py,sha256=t9PwEZgwNCJx3YobsT-jfaVZdfMBS54XJcBrT9Wnsg0,6313
 plain/jobs/registry.py,sha256=Rwn5Htll10e549vD2Mu0oyoDynyHhE0bGYZ2bq9uzPU,1679
-plain/jobs/scheduling.py,sha256=4BQWeRGPYrhNjq9296GCvGw6-1-a3anjFGqc1mdK3fw,7805
-plain/jobs/workers.py,sha256=e32UgMch2pugqwLxRWZfH_kq0PtDuxMxHwbAQ0yYMV4,11941
+plain/jobs/scheduling.py,sha256=fqpFnVoIIV-muf82WzuLyioSmiilfZ76KFjXzt8grIk,7851
+plain/jobs/workers.py,sha256=dtr-yxH8FT3nByDbUN8wzIaWfk09enYy6mNr3VmuXiU,13867
 plain/jobs/migrations/0001_initial.py,sha256=EIgIEMVyTsStyx9dmKM8Jb_hwn694Yo31-74DZkNTqo,9452
 plain/jobs/migrations/0002_job_span_id_job_trace_id_jobrequest_span_id_and_more.py,sha256=ph5BwwOAwdfjdNh9RItYmX_IA29lO-Dd9GymYzvChXQ,1953
 plain/jobs/migrations/0003_rename_job_jobprocess_and_more.py,sha256=EdLucHxiH_QshLL2peIcMULRCQyFMPxh476AxCxW5Wk,2615
@@ -21,7 +21,7 @@ plain/jobs/migrations/0005_rename_constraints_and_indexes.py,sha256=PDGpOw6__tVf
 plain/jobs/migrations/0006_alter_jobprocess_table_alter_jobrequest_table_and_more.py,sha256=FY0_pcw0mL8MkUSatpDXWtA_xQw0kTZBGIyjLcmYeJE,546
 plain/jobs/migrations/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 plain/jobs/templates/admin/plainqueue/jobresult_detail.html,sha256=Ybp1s_dARo_bFDcLEzEfETheP8SzqHHE_NNSKhv_eh8,198
-plain_jobs-0.34.0.dist-info/METADATA,sha256=8uXilZ1ZfAqKsipubMNFgbcBY6KD2JLa7eGqavgtZTk,7162
-plain_jobs-0.34.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
-plain_jobs-0.34.0.dist-info/licenses/LICENSE,sha256=cvKM3OlqHx3ijD6e34zsSUkPvzl-ya3Dd63A6EHL94U,1500
-plain_jobs-0.34.0.dist-info/RECORD,,
+plain_jobs-0.35.1.dist-info/METADATA,sha256=SubahgvtL-4vBbSKNAS1wudQZHVH8_gzWjSdn0ewBFg,7162
+plain_jobs-0.35.1.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+plain_jobs-0.35.1.dist-info/licenses/LICENSE,sha256=cvKM3OlqHx3ijD6e34zsSUkPvzl-ya3Dd63A6EHL94U,1500
+plain_jobs-0.35.1.dist-info/RECORD,,