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

plain/jobs/CHANGELOG.md

@@ -1,5 +1,19 @@
 # plain-jobs changelog
 
+## [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,

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.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: plain.jobs
-Version: 0.34.0
+Version: 0.35.0
 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.0.dist-info}/RECORD

@@ -1,18 +1,18 @@
-plain/jobs/CHANGELOG.md,sha256=6jaE6mdMVx7jX9UFk5eEqT31LC0CgRVTJHGrwObeES4,9384
+plain/jobs/CHANGELOG.md,sha256=yYJsk577xvcH5jqLIEQ2prcY9WZP6wFbC1rRexi6PDw,10424
 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=Wa6Pcam2fahe9sNw2P-NkrODVvF294mqCF4EgaQvGBU,7885
 plain/jobs/middleware.py,sha256=bz8aPBY0RbtLS4kic8mzPOd3EyQFCVRQ2uTCttT3RpE,573
 plain/jobs/models.py,sha256=EvO5vHbsTdI0OJIIJRpGEKks9pm_INB33B1q6VeMSUc,16014
 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.0.dist-info/METADATA,sha256=BaQYwbTBdbyNW39E-MfNzLQWtMuLUgQVlzwAkbOEESQ,7162
+plain_jobs-0.35.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+plain_jobs-0.35.0.dist-info/licenses/LICENSE,sha256=cvKM3OlqHx3ijD6e34zsSUkPvzl-ya3Dd63A6EHL94U,1500
+plain_jobs-0.35.0.dist-info/RECORD,,