pre-commit run -a

guewen · guewen · commit 1bde09a873fd · 2026-03-23T14:46:11.000+01:00
diff --git a/queue_job/README.rst b/queue_job/README.rst
@@ -1,7 +1,3 @@
-.. image:: https://odoo-community.org/readme-banner-image
-   :target: https://odoo-community.org/get-involved?utm_source=readme
-   :alt: Odoo Community Association
-
 =========
 Job Queue
 =========
@@ -17,7 +13,7 @@ Job Queue
 .. |badge1| image:: https://img.shields.io/badge/maturity-Mature-brightgreen.png
     :target: https://odoo-community.org/page/development-status
     :alt: Mature
-.. |badge2| image:: https://img.shields.io/badge/license-LGPL--3-blue.png
+.. |badge2| image:: https://img.shields.io/badge/licence-LGPL--3-blue.png
     :target: http://www.gnu.org/licenses/lgpl-3.0-standalone.html
     :alt: License: LGPL-3
 .. |badge3| image:: https://img.shields.io/badge/github-OCA%2Fqueue-lightgray.png?logo=github
@@ -85,6 +81,36 @@ Features:
 .. contents::
    :local:
 
+Use Cases / Context
+===================
+
+Odoo treats task synchronously, like when you import a list of products
+it will treat each line in one big task. "Queue job" gives you the
+ability to detail big tasks in many smaller ones.
+
+Imagine you have a lot of data to change for thousand orders, you can do
+it in one step and cause a heavy load on the server, and this may affect
+the performance of Odoo. With queue_job you can divide the work in jobs
+and run thousand jobs (one job for each orders). An other benefit is if
+one line failed it doesn't block the processing of the others, as the
+jobs are independent. Plus you can schedule the jobs and set a number of
+retries.
+
+Here are some community usage examples:
+
+- Mass sending invoices:
+  `account_invoice_mass_sending <https://github.com/OCA/account-invoicing/tree/17.0/account_invoice_mass_sending>`__
+- Import data in the background:
+  `base_import_async <https://github.com/OCA/queue/tree/17.0/base_import_async>`__
+- Export data in the background:
+  `base_export_async <https://github.com/OCA/queue/tree/17.0/base_export_async>`__
+- Generate contract invoices with jobs:
+  `contract_queue_job <https://github.com/OCA/contract/tree/17.0/contract_queue_job>`__
+- Generate partner invoices with
+  jobs:`partner_invoicing_mode <https://github.com/OCA/account-invoicing/tree/17.0/partner_invoicing_mode>`__
+- Process the Sales Automatic Workflow actions with jobs:
+  `sale_automatic_workflow_job <https://github.com/OCA/sale-workflow/tree/17.0/sale_automatic_workflow_job>`__
+
 Installation
 ============
 
diff --git a/queue_job/static/description/index.html b/queue_job/static/description/index.html
@@ -3,7 +3,7 @@
 <head>
 <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
 <meta name="generator" content="Docutils: https://docutils.sourceforge.io/" />
-<title>README.rst</title>
+<title>Job Queue</title>
 <style type="text/css">
 
 /*
@@ -360,21 +360,16 @@
 </style>
 </head>
 <body>
-<div class="document">
+<div class="document" id="job-queue">
+<h1 class="title">Job Queue</h1>
 
-
-<a class="reference external image-reference" href="https://odoo-community.org/get-involved?utm_source=readme">
-<img alt="Odoo Community Association" src="https://odoo-community.org/readme-banner-image" />
-</a>
-<div class="section" id="job-queue">
-<h1>Job Queue</h1>
 <!-- !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
 !! This file is generated by oca-gen-addon-readme !!
 !! changes will be overwritten.                   !!
 !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
 !! source digest: sha256:0b61ae169205114262bbac28e15c8729ea4056e5f2d2c08e8f38adbe479da264
 !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! -->
-<p><a class="reference external image-reference" href="https://odoo-community.org/page/development-status"><img alt="Mature" src="https://img.shields.io/badge/maturity-Mature-brightgreen.png" /></a> <a class="reference external image-reference" href="http://www.gnu.org/licenses/lgpl-3.0-standalone.html"><img alt="License: LGPL-3" src="https://img.shields.io/badge/license-LGPL--3-blue.png" /></a> <a class="reference external image-reference" href="https://github.com/OCA/queue/tree/18.0/queue_job"><img alt="OCA/queue" src="https://img.shields.io/badge/github-OCA%2Fqueue-lightgray.png?logo=github" /></a> <a class="reference external image-reference" href="https://translation.odoo-community.org/projects/queue-18-0/queue-18-0-queue_job"><img alt="Translate me on Weblate" src="https://img.shields.io/badge/weblate-Translate%20me-F47D42.png" /></a> <a class="reference external image-reference" href="https://runboat.odoo-community.org/builds?repo=OCA/queue&amp;target_branch=18.0"><img alt="Try me on Runboat" src="https://img.shields.io/badge/runboat-Try%20me-875A7B.png" /></a></p>
+<p><a class="reference external image-reference" href="https://odoo-community.org/page/development-status"><img alt="Mature" src="https://img.shields.io/badge/maturity-Mature-brightgreen.png" /></a> <a class="reference external image-reference" href="http://www.gnu.org/licenses/lgpl-3.0-standalone.html"><img alt="License: LGPL-3" src="https://img.shields.io/badge/licence-LGPL--3-blue.png" /></a> <a class="reference external image-reference" href="https://github.com/OCA/queue/tree/18.0/queue_job"><img alt="OCA/queue" src="https://img.shields.io/badge/github-OCA%2Fqueue-lightgray.png?logo=github" /></a> <a class="reference external image-reference" href="https://translation.odoo-community.org/projects/queue-18-0/queue-18-0-queue_job"><img alt="Translate me on Weblate" src="https://img.shields.io/badge/weblate-Translate%20me-F47D42.png" /></a> <a class="reference external image-reference" href="https://runboat.odoo-community.org/builds?repo=OCA/queue&amp;target_branch=18.0"><img alt="Try me on Runboat" src="https://img.shields.io/badge/runboat-Try%20me-875A7B.png" /></a></p>
 <p>This addon adds an integrated Job Queue to Odoo.</p>
 <p>It allows to postpone method calls executed asynchronously.</p>
 <p>Jobs are executed in the background by a <tt class="docutils literal">Jobrunner</tt>, in their own
@@ -420,41 +415,70 @@ <h1>Job Queue</h1>
 <p><strong>Table of contents</strong></p>
 <div class="contents local topic" id="contents">
 <ul class="simple">
-<li><a class="reference internal" href="#installation" id="toc-entry-1">Installation</a></li>
-<li><a class="reference internal" href="#configuration" id="toc-entry-2">Configuration</a></li>
-<li><a class="reference internal" href="#usage" id="toc-entry-3">Usage</a><ul>
-<li><a class="reference internal" href="#developers" id="toc-entry-4">Developers</a><ul>
-<li><a class="reference internal" href="#delaying-jobs" id="toc-entry-5">Delaying jobs</a></li>
-<li><a class="reference internal" href="#enqueing-job-options" id="toc-entry-6">Enqueing Job Options</a></li>
-<li><a class="reference internal" href="#configure-default-options-for-jobs" id="toc-entry-7">Configure default options for jobs</a></li>
-<li><a class="reference internal" href="#testing" id="toc-entry-8">Testing</a></li>
-<li><a class="reference internal" href="#tips-and-tricks" id="toc-entry-9">Tips and tricks</a></li>
-<li><a class="reference internal" href="#patterns" id="toc-entry-10">Patterns</a></li>
+<li><a class="reference internal" href="#use-cases-context" id="toc-entry-1">Use Cases / Context</a></li>
+<li><a class="reference internal" href="#installation" id="toc-entry-2">Installation</a></li>
+<li><a class="reference internal" href="#configuration" id="toc-entry-3">Configuration</a></li>
+<li><a class="reference internal" href="#usage" id="toc-entry-4">Usage</a><ul>
+<li><a class="reference internal" href="#developers" id="toc-entry-5">Developers</a><ul>
+<li><a class="reference internal" href="#delaying-jobs" id="toc-entry-6">Delaying jobs</a></li>
+<li><a class="reference internal" href="#enqueing-job-options" id="toc-entry-7">Enqueing Job Options</a></li>
+<li><a class="reference internal" href="#configure-default-options-for-jobs" id="toc-entry-8">Configure default options for jobs</a></li>
+<li><a class="reference internal" href="#testing" id="toc-entry-9">Testing</a></li>
+<li><a class="reference internal" href="#tips-and-tricks" id="toc-entry-10">Tips and tricks</a></li>
+<li><a class="reference internal" href="#patterns" id="toc-entry-11">Patterns</a></li>
 </ul>
 </li>
 </ul>
 </li>
-<li><a class="reference internal" href="#known-issues-roadmap" id="toc-entry-11">Known issues / Roadmap</a></li>
-<li><a class="reference internal" href="#changelog" id="toc-entry-12">Changelog</a><ul>
-<li><a class="reference internal" href="#next" id="toc-entry-13">Next</a></li>
+<li><a class="reference internal" href="#known-issues-roadmap" id="toc-entry-12">Known issues / Roadmap</a></li>
+<li><a class="reference internal" href="#changelog" id="toc-entry-13">Changelog</a><ul>
+<li><a class="reference internal" href="#next" id="toc-entry-14">Next</a></li>
 </ul>
 </li>
-<li><a class="reference internal" href="#bug-tracker" id="toc-entry-14">Bug Tracker</a></li>
-<li><a class="reference internal" href="#credits" id="toc-entry-15">Credits</a><ul>
-<li><a class="reference internal" href="#authors" id="toc-entry-16">Authors</a></li>
-<li><a class="reference internal" href="#contributors" id="toc-entry-17">Contributors</a></li>
-<li><a class="reference internal" href="#other-credits" id="toc-entry-18">Other credits</a></li>
-<li><a class="reference internal" href="#maintainers" id="toc-entry-19">Maintainers</a></li>
+<li><a class="reference internal" href="#bug-tracker" id="toc-entry-15">Bug Tracker</a></li>
+<li><a class="reference internal" href="#credits" id="toc-entry-16">Credits</a><ul>
+<li><a class="reference internal" href="#authors" id="toc-entry-17">Authors</a></li>
+<li><a class="reference internal" href="#contributors" id="toc-entry-18">Contributors</a></li>
+<li><a class="reference internal" href="#other-credits" id="toc-entry-19">Other credits</a></li>
+<li><a class="reference internal" href="#maintainers" id="toc-entry-20">Maintainers</a></li>
 </ul>
 </li>
 </ul>
 </div>
+<div class="section" id="use-cases-context">
+<h1><a class="toc-backref" href="#toc-entry-1">Use Cases / Context</a></h1>
+<p>Odoo treats task synchronously, like when you import a list of products
+it will treat each line in one big task. “Queue job” gives you the
+ability to detail big tasks in many smaller ones.</p>
+<p>Imagine you have a lot of data to change for thousand orders, you can do
+it in one step and cause a heavy load on the server, and this may affect
+the performance of Odoo. With queue_job you can divide the work in jobs
+and run thousand jobs (one job for each orders). An other benefit is if
+one line failed it doesn’t block the processing of the others, as the
+jobs are independent. Plus you can schedule the jobs and set a number of
+retries.</p>
+<p>Here are some community usage examples:</p>
+<ul class="simple">
+<li>Mass sending invoices:
+<a class="reference external" href="https://github.com/OCA/account-invoicing/tree/17.0/account_invoice_mass_sending">account_invoice_mass_sending</a></li>
+<li>Import data in the background:
+<a class="reference external" href="https://github.com/OCA/queue/tree/17.0/base_import_async">base_import_async</a></li>
+<li>Export data in the background:
+<a class="reference external" href="https://github.com/OCA/queue/tree/17.0/base_export_async">base_export_async</a></li>
+<li>Generate contract invoices with jobs:
+<a class="reference external" href="https://github.com/OCA/contract/tree/17.0/contract_queue_job">contract_queue_job</a></li>
+<li>Generate partner invoices with
+jobs:<a class="reference external" href="https://github.com/OCA/account-invoicing/tree/17.0/partner_invoicing_mode">partner_invoicing_mode</a></li>
+<li>Process the Sales Automatic Workflow actions with jobs:
+<a class="reference external" href="https://github.com/OCA/sale-workflow/tree/17.0/sale_automatic_workflow_job">sale_automatic_workflow_job</a></li>
+</ul>
+</div>
 <div class="section" id="installation">
-<h2><a class="toc-backref" href="#toc-entry-1">Installation</a></h2>
+<h1><a class="toc-backref" href="#toc-entry-2">Installation</a></h1>
 <p>Be sure to have the <tt class="docutils literal">requests</tt> library.</p>
 </div>
 <div class="section" id="configuration">
-<h2><a class="toc-backref" href="#toc-entry-2">Configuration</a></h2>
+<h1><a class="toc-backref" href="#toc-entry-3">Configuration</a></h1>
 <ul class="simple">
 <li>Using environment variables and command line:<ul>
 <li>Adjust environment variables (optional):<ul>
@@ -517,15 +541,15 @@ <h2><a class="toc-backref" href="#toc-entry-2">Configuration</a></h2>
 </table>
 </div>
 <div class="section" id="usage">
-<h2><a class="toc-backref" href="#toc-entry-3">Usage</a></h2>
+<h1><a class="toc-backref" href="#toc-entry-4">Usage</a></h1>
 <p>To use this module, you need to:</p>
 <ol class="arabic simple">
 <li>Go to <tt class="docutils literal">Job Queue</tt> menu</li>
 </ol>
 <div class="section" id="developers">
-<h3><a class="toc-backref" href="#toc-entry-4">Developers</a></h3>
+<h2><a class="toc-backref" href="#toc-entry-5">Developers</a></h2>
 <div class="section" id="delaying-jobs">
-<h4><a class="toc-backref" href="#toc-entry-5">Delaying jobs</a></h4>
+<h3><a class="toc-backref" href="#toc-entry-6">Delaying jobs</a></h3>
 <p>The fast way to enqueue a job for a method is to use <tt class="docutils literal">with_delay()</tt> on
 a record or model:</p>
 <pre class="code python literal-block">
@@ -645,7 +669,7 @@ <h4><a class="toc-backref" href="#toc-entry-5">Delaying jobs</a></h4>
 </pre>
 </div>
 <div class="section" id="enqueing-job-options">
-<h4><a class="toc-backref" href="#toc-entry-6">Enqueing Job Options</a></h4>
+<h3><a class="toc-backref" href="#toc-entry-7">Enqueing Job Options</a></h3>
 <ul class="simple">
 <li>priority: default is 10, the closest it is to 0, the faster it will be
 executed</li>
@@ -664,7 +688,7 @@ <h4><a class="toc-backref" href="#toc-entry-6">Enqueing Job Options</a></h4>
 </ul>
 </div>
 <div class="section" id="configure-default-options-for-jobs">
-<h4><a class="toc-backref" href="#toc-entry-7">Configure default options for jobs</a></h4>
+<h3><a class="toc-backref" href="#toc-entry-8">Configure default options for jobs</a></h3>
 <p>In earlier versions, jobs could be configured using the <tt class="docutils literal">&#64;job</tt>
 decorator. This is now obsolete, they can be configured using optional
 <tt class="docutils literal">queue.job.function</tt> and <tt class="docutils literal">queue.job.channel</tt> XML records.</p>
@@ -792,7 +816,7 @@ <h4><a class="toc-backref" href="#toc-entry-7">Configure default options for job
 delaying any jobs.</p>
 </div>
 <div class="section" id="testing">
-<h4><a class="toc-backref" href="#toc-entry-8">Testing</a></h4>
+<h3><a class="toc-backref" href="#toc-entry-9">Testing</a></h3>
 <p><strong>Asserting enqueued jobs</strong></p>
 <p>The recommended way to test jobs, rather than running them directly and
 synchronously is to split the tests in two parts:</p>
@@ -907,7 +931,7 @@ <h4><a class="toc-backref" href="#toc-entry-8">Testing</a></h4>
 synchronously</p>
 </div>
 <div class="section" id="tips-and-tricks">
-<h4><a class="toc-backref" href="#toc-entry-9">Tips and tricks</a></h4>
+<h3><a class="toc-backref" href="#toc-entry-10">Tips and tricks</a></h3>
 <ul class="simple">
 <li><strong>Idempotency</strong>
 (<a class="reference external" href="https://www.restapitutorial.com/lessons/idempotency.html">https://www.restapitutorial.com/lessons/idempotency.html</a>): The
@@ -920,7 +944,7 @@ <h4><a class="toc-backref" href="#toc-entry-9">Tips and tricks</a></h4>
 </ul>
 </div>
 <div class="section" id="patterns">
-<h4><a class="toc-backref" href="#toc-entry-10">Patterns</a></h4>
+<h3><a class="toc-backref" href="#toc-entry-11">Patterns</a></h3>
 <p>Through the time, two main patterns emerged:</p>
 <ol class="arabic simple">
 <li>For data exposed to users, a model should store the data and the
@@ -934,16 +958,16 @@ <h4><a class="toc-backref" href="#toc-entry-10">Patterns</a></h4>
 </div>
 </div>
 <div class="section" id="known-issues-roadmap">
-<h2><a class="toc-backref" href="#toc-entry-11">Known issues / Roadmap</a></h2>
+<h1><a class="toc-backref" href="#toc-entry-12">Known issues / Roadmap</a></h1>
 <ul class="simple">
 <li>After creating a new database or installing <tt class="docutils literal">queue_job</tt> on an
 existing database, Odoo must be restarted for the runner to detect it.</li>
 </ul>
 </div>
 <div class="section" id="changelog">
-<h2><a class="toc-backref" href="#toc-entry-12">Changelog</a></h2>
+<h1><a class="toc-backref" href="#toc-entry-13">Changelog</a></h1>
 <div class="section" id="next">
-<h3><a class="toc-backref" href="#toc-entry-13">Next</a></h3>
+<h2><a class="toc-backref" href="#toc-entry-14">Next</a></h2>
 <ul class="simple">
 <li>[ADD] Run jobrunner as a worker process instead of a thread in the
 main process (when running with –workers &gt; 0)</li>
@@ -954,24 +978,24 @@ <h3><a class="toc-backref" href="#toc-entry-13">Next</a></h3>
 </div>
 </div>
 <div class="section" id="bug-tracker">
-<h2><a class="toc-backref" href="#toc-entry-14">Bug Tracker</a></h2>
+<h1><a class="toc-backref" href="#toc-entry-15">Bug Tracker</a></h1>
 <p>Bugs are tracked on <a class="reference external" href="https://github.com/OCA/queue/issues">GitHub Issues</a>.
 In case of trouble, please check there if your issue has already been reported.
 If you spotted it first, help us to smash it by providing a detailed and welcomed
 <a class="reference external" href="https://github.com/OCA/queue/issues/new?body=module:%20queue_job%0Aversion:%2018.0%0A%0A**Steps%20to%20reproduce**%0A-%20...%0A%0A**Current%20behavior**%0A%0A**Expected%20behavior**">feedback</a>.</p>
 <p>Do not contact contributors directly about support or help with technical issues.</p>
 </div>
 <div class="section" id="credits">
-<h2><a class="toc-backref" href="#toc-entry-15">Credits</a></h2>
+<h1><a class="toc-backref" href="#toc-entry-16">Credits</a></h1>
 <div class="section" id="authors">
-<h3><a class="toc-backref" href="#toc-entry-16">Authors</a></h3>
+<h2><a class="toc-backref" href="#toc-entry-17">Authors</a></h2>
 <ul class="simple">
 <li>Camptocamp</li>
 <li>ACSONE SA/NV</li>
 </ul>
 </div>
 <div class="section" id="contributors">
-<h3><a class="toc-backref" href="#toc-entry-17">Contributors</a></h3>
+<h2><a class="toc-backref" href="#toc-entry-18">Contributors</a></h2>
 <ul class="simple">
 <li>Guewen Baconnier &lt;<a class="reference external" href="mailto:guewen.baconnier&#64;camptocamp.com">guewen.baconnier&#64;camptocamp.com</a>&gt;</li>
 <li>Stéphane Bidoul &lt;<a class="reference external" href="mailto:stephane.bidoul&#64;acsone.eu">stephane.bidoul&#64;acsone.eu</a>&gt;</li>
@@ -991,12 +1015,12 @@ <h3><a class="toc-backref" href="#toc-entry-17">Contributors</a></h3>
 </ul>
 </div>
 <div class="section" id="other-credits">
-<h3><a class="toc-backref" href="#toc-entry-18">Other credits</a></h3>
+<h2><a class="toc-backref" href="#toc-entry-19">Other credits</a></h2>
 <p>The migration of this module from 17.0 to 18.0 was financially supported
 by Camptocamp.</p>
 </div>
 <div class="section" id="maintainers">
-<h3><a class="toc-backref" href="#toc-entry-19">Maintainers</a></h3>
+<h2><a class="toc-backref" href="#toc-entry-20">Maintainers</a></h2>
 <p>This module is maintained by the OCA.</p>
 <a class="reference external image-reference" href="https://odoo-community.org">
 <img alt="Odoo Community Association" src="https://odoo-community.org/logo.png" />
@@ -1011,6 +1035,5 @@ <h3><a class="toc-backref" href="#toc-entry-19">Maintainers</a></h3>
 </div>
 </div>
 </div>
-</div>
 </body>
 </html>
