Merge pull request #960 from procrastinate-org/django-tests-doc

README.md

@@ -16,7 +16,7 @@
 Procrastinate is an open-source Python 3.8+ distributed task processing
 library, leveraging PostgreSQL to store task definitions, manage locks and
 dispatch tasks. It can be used within both sync and async code,
-has [Django](howto/django) integration, and is easy to use with ASGI frameworks.
+has [Django](howto/django/configuration) integration, and is easy to use with ASGI frameworks.
 It supports periodic tasks, retries, arbitrary task locks etc.
 
 In other words, from your main code, you call specific functions (tasks) in a

docs/conf.py

@@ -18,6 +18,8 @@
 import datetime
 import os
 
+import django
+
 # -- Project information -----------------------------------------------------
 
 project = "Procrastinate"
@@ -98,3 +100,8 @@
 # -- Options for sphinx_github_changelog ---------------------------------
 
 sphinx_github_changelog_token = os.environ.get("CHANGELOG_GITHUB_TOKEN")
+
+# Provide settings so that Django models are importable
+os.environ["DJANGO_SETTINGS_MODULE"] = "tests.acceptance.django_settings"
+
+django.setup()

docs/howto/django/basic_usage.md

@@ -0,0 +1,62 @@
+# Use Procrastinate in a Django application
+
+## Defining tasks
+
+Add your tasks to `tasks.py` in your Django app.
+Inside tasks, you can use the classical ORM API or the [async ORM API] to access your models.
+
+```python
+from procrastinate.contrib.django import app
+
+@app.task
+def mytask1(obj_pk):
+    obj = MyModel.objects.get(pj=obj_pk)
+    ...
+
+@app.task
+async def mytask2(obj_pk):
+    obj = await MyModel.objects.aget(pj=obj_pk)
+    ...
+```
+
+See {doc}`../tasks` for more details on how to define tasks.
+
+## Running the worker & other CLI commands
+
+Run the worker with the following command.
+```console
+$ (venv) ./manage.py procrastinate worker
+```
+
+`./manage.py procrastinate` mostly behaves like the `procrastinate` command
+itself, with some commands removed and the app is configured for you.
+Apart from `worker`, subcommands such as `defer` are supported.
+
+:::{note}
+Procrastinate generates a fully async connector for you using a `Psycopg` (by
+default) or `Aiopg` connector depending on whether `psycopg` version 3 or
+`aiopg` is installed, and connects using the `DATABASES` settings. If neither
+library is installed, an error will be raised.
+:::
+
+See {doc}`../command_line` for more details on the CLI.
+If you prefer writing your own scripts, see {doc}`scripts`.
+
+## Deferring jobs
+
+Defer jobs from your views works as you would expect:
+
+```python
+from myapp.tasks import mytask
+
+def myview(request):
+    ...
+    mytask.defer(obj_pk=obj.pk)
+
+async def myasyncview(request):
+    ...
+    await mytask.defer_async(obj_pk=obj.pk)
+```
+
+See {doc}`../defer` for more details on how to defer jobs.
+[async orm api]: https://docs.djangoproject.com/en/4.2/topics/async/#queries-the-orm

docs/howto/django/configuration.md

@@ -0,0 +1,51 @@
+# Configure Django & Procrastinate to work together
+
+Many Django projects are deployed using PostgreSQL, so using procrastinate in
+conjunction with Django would remove the necessity of having another broker to
+schedule tasks.
+
+## Configuration
+
+To start, install procrastinate with:
+
+```console
+(venv) $ pip install 'procrastinate[django]'
+```
+
+Add procrastinate Django app to your `INSTALLED_APPS`. You may want to add it
+before your own apps to ensure that procrastinate is ready before your own code
+runs.
+
+```python
+INSTALLED_APPS = [
+    ...
+    "procrastinate.contrib.django",
+    ...
+]
+```
+
+## Configuring the app
+
+An app will be configured for you in `procrastinate.contrib.django.app`.
+You don't have to configure an app yourself, but you can if you want to.
+
+You can modify the app after its creation, for example to load additional tasks from
+blueprints, with:
+
+```python
+# settings.py
+PROCRASTINATE_ON_APP_READY = "myapp.procrastinate.on_app_ready"
+```
+```python
+# myapp/procrastinate.py
+import procrastinate
+
+def on_app_ready(app: procrastinate.App):
+    app.add_tasks_from(some_blueprint)
+```
+
+:::{note}
+While not recoomended, you may decide to use a different app from the one
+provided in `procrastinate.contrib.django.app`, it's not strictly incompatible,
+but it might be more complicated and you may run into issues.
+:::