plain.jobs 0.33.0__tar.gz → 0.35.0__tar.gz

{plain_jobs-0.33.0 → plain_jobs-0.35.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: plain.jobs
-Version: 0.33.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
@@ -66,15 +66,17 @@ plain migrate
 
 ## Local development
 
-In development, you will typically want to run the worker alongside your app. With [`plain.dev`](/plain-dev/plain/dev/README.md) you can do this by adding it to the `[tool.plain.dev.run]` section of your `pyproject.toml` file. Currently, you will need to use something like [watchfiles](https://pypi.org/project/watchfiles/) to add auto-reloading to the worker.
+In development, you will typically want to run the worker alongside your app with auto-reloading enabled. With [`plain.dev`](/plain-dev/plain/dev/README.md) you can do this by adding it to the `[tool.plain.dev.run]` section of your `pyproject.toml` file.
 
 ```toml
 # pyproject.toml
 [tool.plain.dev.run]
-worker = {cmd = "watchfiles --filter python \"plain jobs worker --stats-every 0 --max-processes 2\" ."}
-worker-slow = {cmd = "watchfiles --filter python \"plain jobs worker --queue slow --stats-every 0 --max-processes 2\" ."}
+worker = {cmd = "plain jobs worker --reload --stats-every 0 --max-processes 2"}
+worker-slow = {cmd = "plain jobs worker --reload --queue slow --stats-every 0 --max-processes 2"}
 ```
 
+The `--reload` flag will automatically watch `.py` and `.env*` files for changes and restart the worker when changes are detected.
+
 ## Job parameters
 
 When calling `run_in_worker()`, you can specify several parameters to control job execution:

{plain_jobs-0.33.0 → plain_jobs-0.35.0}/plain/jobs/CHANGELOG.md

@@ -1,5 +1,30 @@
 # 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
+
+- Added `--reload` flag to `plain jobs worker` command for automatic reloading when code changes are detected ([f3db87e9aa](https://github.com/dropseed/plain/commit/f3db87e9aa))
+- Worker reloader now only watches `.py` and `.env*` files, not HTML files ([f2f31c288b](https://github.com/dropseed/plain/commit/f2f31c288b))
+
+### Upgrade instructions
+
+- Custom autoreloaders for development are no longer needed -- use the built-in `--reload` flag instead
+
 ## [0.33.0](https://github.com/dropseed/plain/releases/plain-jobs@0.33.0) (2025-10-10)
 
 ### What's changed

{plain_jobs-0.33.0 → plain_jobs-0.35.0}/plain/jobs/README.md

@@ -55,15 +55,17 @@ plain migrate
 
 ## Local development
 
-In development, you will typically want to run the worker alongside your app. With [`plain.dev`](/plain-dev/plain/dev/README.md) you can do this by adding it to the `[tool.plain.dev.run]` section of your `pyproject.toml` file. Currently, you will need to use something like [watchfiles](https://pypi.org/project/watchfiles/) to add auto-reloading to the worker.
+In development, you will typically want to run the worker alongside your app with auto-reloading enabled. With [`plain.dev`](/plain-dev/plain/dev/README.md) you can do this by adding it to the `[tool.plain.dev.run]` section of your `pyproject.toml` file.
 
 ```toml
 # pyproject.toml
 [tool.plain.dev.run]
-worker = {cmd = "watchfiles --filter python \"plain jobs worker --stats-every 0 --max-processes 2\" ."}
-worker-slow = {cmd = "watchfiles --filter python \"plain jobs worker --queue slow --stats-every 0 --max-processes 2\" ."}
+worker = {cmd = "plain jobs worker --reload --stats-every 0 --max-processes 2"}
+worker-slow = {cmd = "plain jobs worker --reload --queue slow --stats-every 0 --max-processes 2"}
 ```
 
+The `--reload` flag will automatically watch `.py` and `.env*` files for changes and restart the worker when changes are detected.
+
 ## Job parameters
 
 When calling `run_in_worker()`, you can specify several parameters to control job execution:

{plain_jobs-0.33.0 → plain_jobs-0.35.0}/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-0.35.0/plain/jobs/chores.py

@@ -0,0 +1,19 @@
+import datetime
+
+from plain.chores import Chore, register_chore
+from plain.runtime import settings
+from plain.utils import timezone
+
+from .models import JobResult
+
+
+@register_chore
+class ClearCompleted(Chore):
+    """Delete all completed job results in all queues."""
+
+    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-0.33.0 → plain_jobs-0.35.0}/plain/jobs/cli.py

@@ -62,35 +62,80 @@ def cli() -> None:
     type=int,
     envvar="PLAIN_JOBS_WORKER_STATS_EVERY",
 )
+@click.option(
+    "--reload",
+    is_flag=True,
+    help="Watch files and auto-reload worker on changes",
+)
 def worker(
     queues: tuple[str, ...],
     max_processes: int | None,
     max_jobs_per_process: int | None,
     max_pending_per_process: int,
     stats_every: int,
+    reload: bool,
 ) -> None:
     """Run the job worker."""
     jobs_schedule = load_schedule(settings.JOBS_SCHEDULE)
 
-    worker = Worker(
-        queues=list(queues),
-        jobs_schedule=jobs_schedule,
-        max_processes=max_processes,
-        max_jobs_per_process=max_jobs_per_process,
-        max_pending_per_process=max_pending_per_process,
-        stats_every=stats_every,
-    )
-
-    def _shutdown(signalnum: int, _: Any) -> None:
-        logger.info("Job worker shutdown signal received signalnum=%s", signalnum)
-        worker.shutdown()
-
-    # Allow the worker to be stopped gracefully on SIGTERM
-    signal.signal(signal.SIGTERM, _shutdown)
-    signal.signal(signal.SIGINT, _shutdown)
-
-    # Start processing jobs
-    worker.run()
+    if reload:
+        from plain.internal.reloader import Reloader
+
+        # Track whether we should continue restarting
+        should_restart = {"value": True}
+        current_worker = {"instance": None}
+
+        def file_changed(filename: str) -> None:
+            if current_worker["instance"]:
+                current_worker["instance"].shutdown()
+
+        def signal_shutdown(signalnum: int, _: Any) -> None:
+            should_restart["value"] = False
+            if current_worker["instance"]:
+                current_worker["instance"].shutdown()
+
+        # Allow the worker to be stopped gracefully on SIGTERM/SIGINT
+        signal.signal(signal.SIGTERM, signal_shutdown)
+        signal.signal(signal.SIGINT, signal_shutdown)
+
+        # Start file watcher once, outside the loop
+        reloader = Reloader(callback=file_changed, watch_html=False)
+        reloader.start()
+
+        while should_restart["value"]:
+            worker = Worker(
+                queues=list(queues),
+                jobs_schedule=jobs_schedule,
+                max_processes=max_processes,
+                max_jobs_per_process=max_jobs_per_process,
+                max_pending_per_process=max_pending_per_process,
+                stats_every=stats_every,
+            )
+            current_worker["instance"] = worker
+
+            # Start processing jobs (blocks until shutdown)
+            worker.run()
+
+    else:
+        worker = Worker(
+            queues=list(queues),
+            jobs_schedule=jobs_schedule,
+            max_processes=max_processes,
+            max_jobs_per_process=max_jobs_per_process,
+            max_pending_per_process=max_pending_per_process,
+            stats_every=stats_every,
+        )
+
+        def _shutdown(signalnum: int, _: Any) -> None:
+            logger.info("Job worker shutdown signal received signalnum=%s", signalnum)
+            worker.shutdown()
+
+        # Allow the worker to be stopped gracefully on SIGTERM
+        signal.signal(signal.SIGTERM, _shutdown)
+        signal.signal(signal.SIGINT, _shutdown)
+
+        # Start processing jobs
+        worker.run()
 
 
 @cli.command()
@@ -150,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-0.33.0 → plain_jobs-0.35.0}/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-0.33.0 → plain_jobs-0.35.0}/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-0.33.0 → plain_jobs-0.35.0}/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.33.0 → plain_jobs-0.35.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "plain.jobs"
-version = "0.33.0"
+version = "0.35.0"
 description = "Process background jobs with a database-driven job queue."
 authors = [{name = "Dave Gaeddert", email = "dave.gaeddert@dropseed.dev"}]
 readme = "README.md"

plain_jobs-0.33.0/plain/jobs/chores.py

@@ -1,17 +0,0 @@
-import datetime
-
-from plain.chores import register_chore
-from plain.runtime import settings
-from plain.utils import timezone
-
-from .models import JobResult
-
-
-@register_chore("jobs")
-def clear_completed() -> str:
-    """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"