plain.jobs 0.33.0__py3-none-any.whl

plain_jobs-0.33.0.dist-info/METADATA

@@ -0,0 +1,264 @@
+Metadata-Version: 2.4
+Name: plain.jobs
+Version: 0.33.0
+Summary: Process background jobs with a database-driven job queue.
+Author-email: Dave Gaeddert <dave.gaeddert@dropseed.dev>
+License-File: LICENSE
+Requires-Python: >=3.13
+Requires-Dist: plain-models<1.0.0
+Requires-Dist: plain<1.0.0
+Description-Content-Type: text/markdown
+
+# plain.jobs
+
+**Process background jobs with a database-driven job queue.**
+
+- [Overview](#overview)
+- [Local development](#local-development)
+- [Job parameters](#job-parameters)
+- [Job methods](#job-methods)
+- [Scheduled jobs](#scheduled-jobs)
+- [Admin interface](#admin-interface)
+- [Job history](#job-history)
+- [Monitoring](#monitoring)
+- [FAQs](#faqs)
+- [Installation](#installation)
+
+## Overview
+
+Jobs are defined using the [`Job`](./jobs.py#Job) base class and the `run()` method at a minimum.
+
+```python
+from plain.jobs import Job, register_job
+from plain.email import send_mail
+
+
+@register_job
+class WelcomeUserJob(Job):
+    def __init__(self, user):
+        self.user = user
+
+    def run(self):
+        send_mail(
+            subject="Welcome!",
+            message=f"Hello from Plain, {self.user}",
+            from_email="welcome@plainframework.com",
+            recipient_list=[self.user.email],
+        )
+```
+
+You can then create an instance of the job and call [`run_in_worker()`](./jobs.py#Job.run_in_worker) to enqueue it for a background worker to pick up.
+
+```python
+user = User.query.get(id=1)
+WelcomeUserJob(user).run_in_worker()
+```
+
+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.
+
+Run database migrations after installation:
+
+```bash
+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.
+
+```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\" ."}
+```
+
+## Job parameters
+
+When calling `run_in_worker()`, you can specify several parameters to control job execution:
+
+```python
+job.run_in_worker(
+    queue="slow",  # Target a specific queue (default: "default")
+    delay=60,  # Delay in seconds (or timedelta/datetime)
+    priority=10,  # Higher numbers run first (default: 0, use negatives for lower priority)
+    retries=3,  # Number of retry attempts (default: 0)
+    unique_key="user-123-welcome",  # Prevent duplicate jobs
+)
+```
+
+For more advanced parameter options, see [`Job.run_in_worker()`](./jobs.py#Job.run_in_worker).
+
+## Job methods
+
+The [`Job`](./jobs.py#Job) base class provides several methods you can override to customize behavior:
+
+```python
+class MyJob(Job):
+    def run(self):
+        # Required: The main job logic
+        pass
+
+    def get_queue(self) -> str:
+        # Specify the default queue for this job type
+        return "default"
+
+    def get_priority(self) -> int:
+        # Set the default priority
+        # Higher numbers run first: 10 > 5 > 0 > -5 > -10
+        # Use positive numbers for high priority, negative for low priority
+        return 0
+
+    def get_retries(self) -> int:
+        # Number of retry attempts on failure
+        return 0
+
+    def get_retry_delay(self, attempt: int) -> int:
+        # Delay in seconds before retry (attempt starts at 1)
+        return 0
+
+    def get_unique_key(self) -> str:
+        # Return a key to prevent duplicate jobs
+        return ""
+```
+
+## Scheduled jobs
+
+You can schedule jobs to run at specific times using the [`Schedule`](./scheduling.py#Schedule) class:
+
+```python
+from plain.jobs import Job, register_job
+from plain.jobs.scheduling import Schedule
+
+@register_job
+class DailyReportJob(Job):
+    schedule = Schedule.from_cron("0 9 * * *")  # Every day at 9 AM
+
+    def run(self):
+        # Generate daily report
+        pass
+```
+
+The `Schedule` class supports standard cron syntax and special strings:
+
+- `@yearly` or `@annually` - Run once a year
+- `@monthly` - Run once a month
+- `@weekly` - Run once a week
+- `@daily` or `@midnight` - Run once a day
+- `@hourly` - Run once an hour
+
+For custom schedules, see [`Schedule`](./scheduling.py#Schedule).
+
+## Admin interface
+
+The jobs package includes admin views for monitoring jobs under the "Jobs" section. The admin interface provides:
+
+- **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, errored, lost, and retried jobs.
+
+## Job history
+
+Job execution history is stored in the [`JobResult`](./models.py#JobResult) model. This includes:
+
+- Job class and parameters
+- Start and end times
+- Success/failure status
+- Error messages and tracebacks for failed jobs
+- Worker information
+
+History retention is controlled by the `JOBS_RESULTS_RETENTION` setting (defaults to 7 days):
+
+```python
+# app/settings.py
+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
+
+Workers report statistics and can be monitored using the `--stats-every` option:
+
+```bash
+# Report stats every 60 seconds
+plain jobs worker --stats-every 60
+```
+
+The worker integrates with OpenTelemetry for distributed tracing. Spans are created for:
+
+- Job scheduling (`run_in_worker`)
+- Job execution
+- Job completion/failure
+
+Jobs can be linked to the originating trace context, allowing you to track jobs initiated from web requests.
+
+## FAQs
+
+#### How do I ensure a job only runs once?
+
+Return a unique key from the `get_unique_key()` method:
+
+```python
+class ProcessUserDataJob(Job):
+    def __init__(self, user_id):
+        self.user_id = user_id
+
+    def get_unique_key(self):
+        return f"process-user-{self.user_id}"
+```
+
+#### Can I run multiple workers?
+
+Yes, you can run multiple worker processes:
+
+```bash
+plain jobs worker --max-processes 4
+```
+
+Or run workers for specific queues:
+
+```bash
+plain jobs worker --queue slow --max-processes 2
+```
+
+#### How do I handle job failures?
+
+Set the number of retries and implement retry delays:
+
+```python
+class MyJob(Job):
+    def get_retries(self):
+        return 3
+
+    def get_retry_delay(self, attempt):
+        # Exponential backoff: 1s, 2s, 4s
+        return 2 ** (attempt - 1)
+```
+
+## Installation
+
+Install the `plain.jobs` package from [PyPI](https://pypi.org/project/plain.jobs/):
+
+```bash
+uv add plain.jobs
+```
+
+Add to your `INSTALLED_PACKAGES`:
+
+```python
+# app/settings.py
+INSTALLED_PACKAGES = [
+    ...
+    "plain.jobs",
+]
+```

plain_jobs-0.33.0.dist-info/RECORD

@@ -0,0 +1,27 @@
+plain/jobs/CHANGELOG.md,sha256=OWHFWE2xIcsfdhYTK999K06ilx6Ioc0sP4_2EzfMML8,8823
+plain/jobs/README.md,sha256=mzaGucJn54gBG4bobjjIj0hHUAYXz-0SsQZIRd503nI,6858
+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=gDkyMBeKsv-vE1vnZdIsg1wv2PDSWwOYr2GHtgbQIlg,4087
+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/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/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
+plain/jobs/migrations/0004_rename_tables_to_plainjobs.py,sha256=mCy4WMHI9xEXstbXI06cgSsFCMVSeQc9vOsU7ukhv4k,1061
+plain/jobs/migrations/0005_rename_constraints_and_indexes.py,sha256=PDGpOw6__tVfn-0BAFv_5OwWt6eBo2QF2kxeTZ92JKg,6408
+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.33.0.dist-info/METADATA,sha256=0GquVURZJxnR44lGpSrgYSg2LxKvXaXz7URnpSQjCCk,7185
+plain_jobs-0.33.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+plain_jobs-0.33.0.dist-info/licenses/LICENSE,sha256=cvKM3OlqHx3ijD6e34zsSUkPvzl-ya3Dd63A6EHL94U,1500
+plain_jobs-0.33.0.dist-info/RECORD,,

plain_jobs-0.33.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.27.0
+Root-Is-Purelib: true
+Tag: py3-none-any

plain_jobs-0.33.0.dist-info/licenses/LICENSE

@@ -0,0 +1,28 @@
+BSD 3-Clause License
+
+Copyright (c) 2023, Dropseed, LLC
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.