V3 update

.github/workflows/ci.yml

@@ -61,6 +61,7 @@ jobs:
         with:
           name: coverage-${{ matrix.python-version }}
           path: .coverage.${{ matrix.python-version }}
+          include-hidden-files: true
 
   static-typing:
     name: Run Pyright

.pre-commit-config.yaml

@@ -29,7 +29,7 @@ repos:
       - id: trailing-whitespace
       - id: mixed-line-ending
   - repo: https://github.com/RobertCraigie/pyright-python
-    rev: v1.1.376
+    rev: v1.1.378
     hooks:
       - id: pyright
         additional_dependencies:
@@ -40,16 +40,16 @@ repos:
           - contextlib2==21.6.0
           - croniter==3.0.3
           - django-stubs==5.0.4
-          - django==4.2.15
-          - importlib-resources==6.4.2
+          - django==4.2.16
+          - importlib-resources==6.4.4
           - psycopg2-binary==2.9.9
           - psycopg[pool]==3.2.1
           - python-dateutil==2.9.0.post0
           - sphinx==7.1.2
-          - sqlalchemy==2.0.32
+          - sqlalchemy==2.0.34
           - typing-extensions==4.12.2
   - repo: https://github.com/astral-sh/ruff-pre-commit
-    rev: v0.6.1
+    rev: v0.6.4
     hooks:
       - id: ruff
         args: [--fix, --unsafe-fixes]

CONTRIBUTING.md

@@ -13,13 +13,13 @@ Of course, feel free to read the script before launching it.
 This script is intended to be a one-liner that sets up everything you need. It makes
 the following assumptions:
 
-- You're using `MacOS` or `Linux`, and `bash` or `zsh`.
-- You already have `python3` available
-- You have `poetry` [installed](https://python-poetry.org/docs/#installation)
-- Either you've already setup a PostgreSQL database and environment variables (`PG*`)
-  are set or you have `docker-compose` available and port 5432 is free.
-- Either `psql` and other `libpq` executables are available in the `PATH` or they
-  are located in `usr/local/opt/libpq/bin` (`Homebrew`).
+-   You're using `MacOS` or `Linux`, and `bash` or `zsh`.
+-   You already have `python3` available
+-   You have `poetry` [installed](https://python-poetry.org/docs/#installation)
+-   Either you've already setup a PostgreSQL database and environment variables (`PG*`)
+    are set or you have `docker compose` available and port 5432 is free.
+-   Either `psql` and other `libpq` executables are available in the `PATH` or they
+    are located in `usr/local/opt/libpq/bin` (`Homebrew`).
 
 The `dev-env` script will add the `scripts` folder to your `$PATH` for the current
 shell, so in the following documentation, if you see `scripts/foo`, you're welcome
@@ -46,7 +46,7 @@ The PostgreSQL database we used is a fresh standard out-of-the-box database
 on the latest stable version.
 
 ```console
-$ docker-compose up -d postgres
+$ docker compose up -d postgres
 ```
 
 If you want to try out the project locally, it's useful to have `postgresql-client`
@@ -129,7 +129,6 @@ In addition, an [editorconfig] file will help your favorite editor to respect
 procrastinate coding style. It is automatically used by most famous IDEs, such as
 Pycharm and VS Code.
 
-
 ### Write the documentation
 
 The documentation is written in `Markdown` and built with `Sphinx` and `MyST`.
@@ -301,23 +300,23 @@ Python environment on the host system. Alternatively, they can be installed in a
 image, and Procrastinate and all the development tools can be run in Docker containers.
 Docker is useful when you can't, or don't want to, install system requirements.
 
-This section shows, through `docker-compose` command examples, how to test and run
+This section shows, through `docker compose` command examples, how to test and run
 Procrastinate in Docker.
 
 Build the `procrastinate` Docker image:
 
 ```console
 $ export UID GID
-$ docker-compose build procrastinate
+$ docker compose build procrastinate
 ```
 
 Run the automated tests:
 
 ```console
-$ docker-compose run --rm procrastinate pytest
+$ docker compose run --rm procrastinate pytest
 ```
 
-Docker Compose is configured (in `docker-compose.yml`) to mount the local directory on
+Docker Compose is configured (in `docker compose.yml`) to mount the local directory on
 the host system onto `/src` in the container. This means that local
 changes made to the Procrastinate code are visible in Procrastinate containers.
 
@@ -326,63 +325,63 @@ container to be run with the current user id and group id. If not set or exporte
 Procrastinate container will run as root, and files owned by root may be created in the
 developer's working directory.
 
-In the definition of the `procrastinate` service in `docker-compose.yml` the
+In the definition of the `procrastinate` service in `docker compose.yml` the
 `PROCRASTINATE_APP` variable is set to `procrastinate_demo.app.app` (the
 Procrastinate demo application). So `procrastinate` commands run in Procrastinate
 containers are always run as if they were passed `--app procrastinate_demo.app.app`.
 
 Run the `procrastinate` command :
 
 ```console
-$ docker-compose run --rm procrastinate procrastinate -h
+$ docker compose run --rm procrastinate procrastinate -h
 ```
 
 Apply the Procrastinate database schema:
 
 ```console
-$ docker-compose run --rm procrastinate procrastinate schema --apply
+$ docker compose run --rm procrastinate procrastinate schema --apply
 ```
 
 Run the Procrastinate healthchecks:
 
 ```console
-$ docker-compose run --rm procrastinate procrastinate healthchecks
+$ docker compose run --rm procrastinate procrastinate healthchecks
 ```
 
 Start a Procrastinate worker (`-d` used to start the container in detached mode):
 
 ```console
-$ docker-compose up -d procrastinate
+$ docker compose up -d procrastinate
 ```
 
 Run a command (`bash` here) in the Procrastinate worker container just started:
 
 ```console
-$ docker-compose exec procrastinate bash
+$ docker compose exec procrastinate bash
 ```
 
 Watch the Procrastinate worker logs:
 
 ```console
-$ docker-compose logs -ft procrastinate
+$ docker compose logs -ft procrastinate
 ```
 
 Use the `procrastinate defer` command to create a job:
 
 ```console
-$ docker-compose run --rm procrastinate procrastinate defer procrastinate_demo.tasks.sum '{"a":3, "b": 5}'
+$ docker compose run --rm procrastinate procrastinate defer procrastinate_demo.tasks.sum '{"a":3, "b": 5}'
 ```
 
 Or run the demo main file:
 
 ```console
-$ docker-compose run --rm procrastinate python -m procrastinate_demo
+$ docker compose run --rm procrastinate python -m procrastinate_demo
 ```
 
 Stop and remove all the containers (including the `postgres` container):
 
 ```console
-$ docker-compose down
+$ docker compose down
 ```
 
 ## Wait, there are `async` and `await` keywords everywhere!?

dev-env

@@ -26,7 +26,7 @@ export GID=$(id -g)
 if ! pg_isready ; then
     echo "Starting database"
     export PGDATABASE=procrastinate PGHOST=127.0.0.1 PGUSER=postgres PGPASSWORD=password
-    docker-compose up -d postgres || return
+    docker compose up -d postgres || return
     sleep 3
 fi
 

docs/howto/advanced/sync_defer.md

@@ -55,24 +55,6 @@ app = App(connector=SQLAlchemyPsycopg2Connector())
 app.open(engine)
 ```
 
-## Having multiple apps
-
-If you need to have multiple connectors interact with the tasks, you can
-create multiple synchronized apps with {py:meth}`App.with_connector`:
-
-```
-import procrastinate
-
-
-app = procrastinate.App(
-    connector=procrastinate.PsycopgConnector(...),
-)
-
-sync_app = app.with_connector(
-    connector=procrastinate.SyncPsycopgConnector(...),
-)
-```
-
 ## Procrastinate's automatic connector selection
 
 Async connectors are able to summon their synchronous counterpart when needed

docs/howto/basics/defer.md

@@ -4,7 +4,7 @@ There are several ways to do this.
 
 In the following examples, the task will be:
 
-```
+```python
 @app.task(queue="some_queue")
 def my_task(a: int, b:int):
     pass
@@ -14,39 +14,62 @@ Task name is `my_module.my_task`.
 
 ## The direct way
 
-```
+By using the sync method:
+
+```python
 my_task.defer(a=1, b=2)
 ```
 
-## With parameters
+Or the async method:
 
+```python
+await my_task.defer_async(a=1, b=2)
 ```
+
+## With parameters
+
+Using the sync defer method:
+
+```python
 my_task.configure(
     lock="the name of my lock",
     schedule_in={"hours": 1},
     queue="not_the_default_queue"
 ).defer(a=1, b=2)
+
+# or
+await my_task.configure(
+    lock="the name of my lock",
+    schedule_in={"hours": 1},
+    queue="not_the_default_queue"
+).defer_async(a=1, b=2)
 ```
 
 See details in {py:meth}`Task.configure`
 
 ## Create a job pattern, launch multiple jobs
 
-```
+```python
 pattern = my_task.configure(task_kwargs={"a": 1})
 
 pattern.defer(b=2)
 pattern.defer(b=3)
 pattern.defer(b=4)
+# or
+await pattern.defer_async(b=2)
+await pattern.defer_async(b=3)
+await pattern.defer_async(b=4)
 ```
 
 ## Defer a job if you can't access the task
 
 This is useful if the code that defers jobs is not in the same code base as the code
 that runs the jobs. You can defer a job with just the name of its task.
 
-```
+```python
 app.configure_task(name="my_module.my_task", queue="some_queue").defer(a=1, b=2)
+# or
+await app.configure_task(name="my_module.my_task", queue="some_queue").defer_async(a=1, b=2)
 ```
 
 Any parameter you would use for {py:meth}`Task.configure` can be used in

docs/howto/basics/tasks.md

@@ -1,22 +1,43 @@
 # Define a task
 
-You can specify a task with:
+Specify a sync task with:
 
-```
+```python
 @app.task(...)
 def mytask(argument, other_argument):
     ...
 ```
 
+:::{note}
+Each sync task runs in its own thread (independently of the worker thread).
+:::
+
+Or an async task with:
+
+```python
+@app.task(...)
+async def mytask(argument, other_argument):
+    ...
+```
+
+:::{note}
+All async tasks run in the same event loop.
+:::
+
 See {py:meth}`App.task` for the exact parameters. In particular, you can define values for
 `queue`, `lock` and  `queueing_lock` that will be used as default values when
 calling {py:meth}`Task.configure` or {py:meth}`Task.defer` on this task.
 
 If you're OK with all the default parameters, you can omit parentheses after
 `task`:
 
-```
+```python
 @app.task
 def mytask(argument, other_argument):
     ...
+
+# or
+@app.task
+async def mytask(argument, other_argument):
+    ...
 ```

docs/howto/django/scripts.md

@@ -21,8 +21,8 @@ def main():
     django.setup()
     # By default, the app uses the Django database connection, which is unsuitable
     # for the worker.
-    app = app.with_connector(app.connector.get_worker_connector())
-    app.run_worker()
+    with app.replace_connector(app.connector.get_worker_connector()):
+        app.run_worker()
 
 if __name__ == "__main__":
     main()

docs/howto/django/tests.md

@@ -24,8 +24,8 @@ def app():
     # Replace the connector in the current app
     # Note that this fixture gives you the app back for convenience, but it's
     # the same instance as you'd get with `procrastinate.contrib.django.app`.
-    with procrastinate_app.current_app.replace_connector(in_memory) as app_with_connector:
-        yield app_with_connector
+    with procrastinate_app.current_app.replace_connector(in_memory) as app:
+        yield app
 
 def test_my_task(app):
     # Run the task
@@ -126,8 +126,8 @@ class TestingTaskClass(TransactionTestCase):
         my_task.defer(a=1, b=2)
 
         # Start worker
-        app = app.with_connector(app.connector.get_worker_connector())
-        app.run_worker(wait=False, install_signal_handlers=False, listen_notify=False)
+        with app.replace_connector(app.connector.get_worker_connector())
+            app.run_worker(wait=False, install_signal_handlers=False, listen_notify=False)
 
         # Check task has been executed
         assert ProcrastinateJob.objects.filter(task_name="my_task").status == "succeeded"
@@ -144,20 +144,20 @@ def test_task():
     my_task.defer(a=1, b=2)
 
     # Start worker
-    app = app.with_connector(app.connector.get_worker_connector())
-    app.run_worker(wait=False, install_signal_handlers=False, listen_notify=False)
+    with app.replace_connector(app.connector.get_worker_connector())
+        app.run_worker(wait=False, install_signal_handlers=False, listen_notify=False)
 
     # Check task has been executed
     assert ProcrastinateJob.objects.filter(task_name="my_task").status == "succeeded"
 
 # Or with a fixture
 @pytest.fixture
 def worker(transactional_db):
-    def _():
-        app = app.with_connector(app.connector.get_worker_connector())
-        app.run_worker(wait=False, install_signal_handlers=False, listen_notify=False)
-        return app
-    return _
+    with app.replace_connector(app.connector.get_worker_connector())
+        def f():
+            app.run_worker(wait=False, install_signal_handlers=False, listen_notify=False)
+            return app
+    yield f
 
 def test_task(worker):
     # Run tasks