Rename plain-worker to plain-jobs

Author: davegaeddert

README.md

@@ -31,7 +31,7 @@ With the official Plain ecosystem packages you can:
 - Style with [Tailwind CSS](https://plainframework.com/docs/plain-tailwind/plain/tailwind/README.md)
 - Add [OAuth login](https://plainframework.com/docs/plain-oauth/plain/oauth/README.md) and API access
 - Run tests with [pytest](https://plainframework.com/docs/plain-pytest/plain/pytest/README.md)
-- Run a [background job worker](https://plainframework.com/docs/plain-worker/plain/worker/README.md)
+- Run a [background job worker](https://plainframework.com/docs/plain-jobs/plain/jobs/README.md)
 - Build [admin dashboard and tools](https://plainframework.com/docs/plain-admin/plain/admin/README.md)
 
 Learn more at [plainframework.com](https://plainframework.com).

example/app/settings.py

@@ -11,6 +11,7 @@
     "plain.email",
     "plain.flags",
     "plain.htmx",
+    "plain.jobs",
     "plain.loginlink",
     "plain.models",
     "plain.oauth",
@@ -21,7 +22,6 @@
     "plain.support",
     "plain.tailwind",
     "plain.toolbar",
-    "plain.worker",
     "plain.redirection",
     "plain.observer",
     "app.users",

example/pyproject.toml

@@ -15,6 +15,7 @@ dependencies = [
     "plain-esbuild",
     "plain-flags",
     "plain-htmx",
+    "plain-jobs",
     "plain-loginlink",
     "plain-email",
     "plain-models",
@@ -30,7 +31,6 @@ dependencies = [
     "plain-toolbar",
     "plain-tunnel",
     "plain-vendor",
-    "plain-worker",
     "plain-observer",
 ]
 

plain-dev/plain/dev/README.md

@@ -61,7 +61,7 @@ postgres = {cmd = "docker run --name app-postgres --rm -p 54321:5432 -v $(pwd)/.
 
 #### Custom processes
 
-Unlike [services](#services), custom processes are _only_ run during `plain dev`. This is a good place to run something like [ngrok](https://ngrok.com/) or a [Plain worker](../../../plain-worker), which you might need to use your local site, but don't need running for executing tests, for example.
+Unlike [services](#services), custom processes are _only_ run during `plain dev`. This is a good place to run something like [ngrok](https://ngrok.com/) or a [Plain job worker](../../../plain-jobs), which you might need to use your local site, but don't need running for executing tests, for example.
 
 ```toml
 # pyproject.toml

plain-worker/.gitignore renamed to plain-jobs/.gitignore

@@ -0,0 +1 @@
+./plain/jobs/README.md

plain-worker/LICENSE renamed to plain-jobs/LICENSE

@@ -1,6 +1,6 @@
-# plain.worker
+# plain.jobs
 
-**Process background jobs with a database-driven worker.**
+**Process background jobs with a database-driven job queue.**
 
 - [Overview](#overview)
 - [Local development](#local-development)
@@ -18,7 +18,7 @@
 Jobs are defined using the [`Job`](./jobs.py#Job) base class and the `run()` method at a minimum.
 
 ```python
-from plain.worker import Job, register_job
+from plain.jobs import Job, register_job
 from plain.email import send_mail
 
 
@@ -43,7 +43,7 @@ user = User.query.get(id=1)
 WelcomeUserJob(user).run_in_worker()
 ```
 
-Workers are run using the `plain worker run` command.
+Workers are run using the `plain jobs worker` command.
 
 Jobs can be defined in any Python file, but it is suggested to use `app/jobs.py` or `app/{pkg}/jobs.py` as those will be imported automatically so the [`@register_job`](./registry.py#register_job) decorator will fire.
 
@@ -60,8 +60,8 @@ In development, you will typically want to run the worker alongside your app. Wi
 ```toml
 # pyproject.toml
 [tool.plain.dev.run]
-worker = {cmd = "watchfiles --filter python \"plain worker run --stats-every 0 --max-processes 2\" ."}
-worker-slow = {cmd = "watchfiles --filter python \"plain worker run --queue slow --stats-every 0 --max-processes 2\" ."}
+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\" ."}
 ```
 
 ## Job parameters
@@ -118,8 +118,8 @@ class MyJob(Job):
 You can schedule jobs to run at specific times using the [`Schedule`](./scheduling.py#Schedule) class:
 
 ```python
-from plain.worker import Job, register_job
-from plain.worker.scheduling import Schedule
+from plain.jobs import Job, register_job
+from plain.jobs.scheduling import Schedule
 
 @register_job
 class DailyReportJob(Job):
@@ -142,13 +142,13 @@ For custom schedules, see [`Schedule`](./scheduling.py#Schedule).
 
 ## Admin interface
 
-The worker package includes admin views for monitoring jobs. The admin interface provides:
+The jobs package includes admin views for monitoring jobs under the "Jobs" section. The admin interface provides:
 
-- **Job Requests**: View pending jobs in the queue
-- **Jobs**: Monitor currently running jobs
-- **Job Results**: Review completed and failed job history
+- **Requests**: View pending jobs in the queue
+- **Processes**: Monitor currently running jobs
+- **Results**: Review completed and failed job history
 
-Dashboard cards show at-a-glance statistics for successful and errored jobs.
+Dashboard cards show at-a-glance statistics for successful, errored, lost, and retried jobs.
 
 ## Job history
 
@@ -160,11 +160,18 @@ Job execution history is stored in the [`JobResult`](./models.py#JobResult) mode
 - Error messages and tracebacks for failed jobs
 - Worker information
 
-History retention can be configured in your settings:
+History retention is controlled by the `JOBS_RESULTS_RETENTION` setting (defaults to 7 days):
 
 ```python
 # app/settings.py
-WORKER_JOB_HISTORY_DAYS = 30
+JOBS_RESULTS_RETENTION = 60 * 60 * 24 * 30  # 30 days (in seconds)
+```
+
+Job timeout can be configured with `JOBS_TIMEOUT` (defaults to 1 day):
+
+```python
+# app/settings.py
+JOBS_TIMEOUT = 60 * 60 * 24  # 1 day (in seconds)
 ```
 
 ## Monitoring
@@ -173,7 +180,7 @@ Workers report statistics and can be monitored using the `--stats-every` option:
 
 ```bash
 # Report stats every 60 seconds
-plain worker run --stats-every 60
+plain jobs worker --stats-every 60
 ```
 
 The worker integrates with OpenTelemetry for distributed tracing. Spans are created for:
@@ -204,13 +211,13 @@ class ProcessUserDataJob(Job):
 Yes, you can run multiple worker processes:
 
 ```bash
-plain worker run --max-processes 4
+plain jobs worker --max-processes 4
 ```
 
 Or run workers for specific queues:
 
 ```bash
-plain worker run --queue slow --max-processes 2
+plain jobs worker --queue slow --max-processes 2
 ```
 
 #### How do I handle job failures?
@@ -229,10 +236,10 @@ class MyJob(Job):
 
 ## Installation
 
-Install the `plain.worker` package from [PyPI](https://pypi.org/project/plain.worker/):
+Install the `plain.jobs` package from [PyPI](https://pypi.org/project/plain.jobs/):
 
 ```bash
-uv add plain.worker
+uv add plain.jobs
 ```
 
 Add to your `INSTALLED_PACKAGES`:
@@ -241,6 +248,6 @@ Add to your `INSTALLED_PACKAGES`:
 # app/settings.py
 INSTALLED_PACKAGES = [
     ...
-    "plain.worker",
+    "plain.jobs",
 ]
 ```