Remove sphinx-autodoc-typehints, upgrade Myst & Sphinx

.github/workflows/ci.yml

@@ -46,9 +46,7 @@ jobs:
           python-version: "${{ matrix.python-version }}"
           cache: "poetry"
 
-      - run: poetry env use "${{ matrix.python-version }}"
-
-      - run: poetry install --extras "django sqlalchemy"
+      - run: poetry install --all-extras
 
       - name: Run tests
         run: scripts/tests
@@ -75,7 +73,7 @@ jobs:
 
       - uses: actions/setup-python@v5
         with:
-          python-version: "3.8" # Important for importlib_metadata
+          python-version: "3.8"
           cache: "poetry"
 
       - name: Install dependencies

.pre-commit-config.yaml

@@ -41,7 +41,6 @@ repos:
           - croniter==3.0.3
           - django-stubs==5.0.4
           - django==4.2.15
-          - importlib-metadata==8.2.0
           - importlib-resources==6.4.2
           - psycopg2-binary==2.9.9
           - psycopg[pool]==3.2.1

.readthedocs.yml

@@ -8,7 +8,7 @@ version: 2
 build:
   os: "ubuntu-22.04"
   tools:
-    python: "3.10"
+    python: "latest"
   jobs:
     post_create_environment:
       - python -m pip install poetry

dev-env

@@ -61,6 +61,6 @@ echo "We've gone ahead and set up a few additional commands for you:"
 echo "- htmlcov: Opens the test coverage results in your browser"
 echo "- htmldoc: Opens the locally built sphinx documentation in your browser"
 echo "- lint: Run code formatters & linters"
-echo "- docs: Build doc"
+echo "- docs: Build doc (note: needs 'poetry install --with docs' which needs a recent Python)"
 echo ""
 echo 'Quit the poetry shell with the command `deactivate`'

docs/conf.py

@@ -39,7 +39,6 @@
     "myst_parser",
     "sphinx.ext.napoleon",
     "sphinx.ext.autodoc",
-    "sphinx_autodoc_typehints",
     "sphinxcontrib.programoutput",
     "sphinx_github_changelog",
     "sphinx_copybutton",
@@ -99,6 +98,13 @@
 
 html_favicon = "favicon.ico"
 
+# -- Options for sphinx.ext.autodoc ------------------------------------------
+
+autodoc_typehints = "both"
+autodoc_type_aliases = {
+    "JSONDict": "procrastinate.types.JSONDict",
+}
+
 # -- Options for sphinx_github_changelog ---------------------------------
 
 sphinx_github_changelog_token = os.environ.get("CHANGELOG_GITHUB_TOKEN")

docs/reference.rst

@@ -7,33 +7,26 @@ App
 .. autoclass:: procrastinate.App
     :members: open, open_async, task, run_worker, run_worker_async, configure_task,
               from_path, add_tasks_from, add_task_alias, with_connector, periodic,
+              tasks, job_manager
 
 Connectors
 ----------
 .. autoclass:: procrastinate.PsycopgConnector
-    :members:
-    :exclude-members: open_async, close_async
 
 .. autoclass:: procrastinate.SyncPsycopgConnector
-    :members:
-    :exclude-members: open, close
 
 .. autoclass:: procrastinate.contrib.aiopg.AiopgConnector
-    :members:
-    :exclude-members: open_async, close_async
 
 .. autoclass:: procrastinate.contrib.psycopg2.Psycopg2Connector
-    :members:
-    :exclude-members: open, close
 
 .. autoclass:: procrastinate.testing.InMemoryConnector
-    :members: reset
-
+    :members: reset, jobs
 
 Tasks
 -----
 .. autoclass:: procrastinate.tasks.Task
-    :members: defer, defer_async, configure
+    :members: defer, defer_async, configure, name, aliases, retry_strategy,
+              pass_context, queue, lock, queueing_lock
 
 When tasks are created with argument ``pass_context``, they are provided a
 `JobContext` argument:
@@ -62,6 +55,7 @@ Jobs
 ----
 
 .. autoclass:: procrastinate.jobs.Job
+    :members:
 
 
 Retry strategies

procrastinate/app.py

@@ -23,14 +23,6 @@ class App(blueprints.Blueprint):
     and use it to decorate your tasks with `App.task`.
 
     You can run a worker with `App.run_worker`.
-
-    Attributes
-    ----------
-    tasks : ``Dict[str, tasks.Task]``
-        The mapping of all tasks known by the app. Only procrastinate is expected to
-        make changes to this mapping.
-    job_manager : `manager.JobManager`
-        The `JobManager` linked to the application
     """
 
     @classmethod
@@ -95,7 +87,10 @@ def __init__(
         self.worker_defaults = worker_defaults or {}
         self.periodic_defaults = periodic_defaults or {}
 
-        self.job_manager = manager.JobManager(connector=self.connector)
+        #: The :py:class:`~manager.JobManager` linked to the application
+        self.job_manager: manager.JobManager = manager.JobManager(
+            connector=self.connector
+        )
 
         self._register_builtin_tasks()
 
@@ -113,7 +108,7 @@ def with_connector(self, connector: connector_module.BaseConnector) -> App:
 
         Returns
         -------
-        `App`
+        :
             A new compatible app.
         """
         app = App(
@@ -137,7 +132,7 @@ def replace_connector(
         connector :
             The new connector to use.
 
-        Returns
+        Yields
         -------
         `App`
             A new compatible app.
@@ -174,7 +169,7 @@ def configure_task(
 
         Parameters
         ----------
-        name : str
+        name:
             Name of the task. If not explicitly defined, this will be the dotted path
             to the task (``my.module.my_task``)
 
@@ -183,7 +178,7 @@ def configure_task(
 
         Returns
         -------
-        ``jobs.JobDeferrer``
+        :
             Launch ``.defer(**task_kwargs)`` on this object to defer your job.
         """
         from procrastinate import tasks
@@ -227,32 +222,32 @@ async def run_worker_async(self, **kwargs) -> None:
 
         Parameters
         ----------
-        queues : ``Optional[Iterable[str]]``
+        queues: ``Optional[Iterable[str]]``
             List of queues to listen to, or None to listen to every queue (defaults to
             ``None``).
-        wait : ``bool``
+        wait: ``bool``
             If False, the worker will terminate as soon as it has caught up with the
             queues. If True, the worker will work until it is stopped by a signal
             (``ctrl+c``, ``SIGINT``, ``SIGTERM``) (defaults to ``True``).
-        concurrency : ``int``
+        concurrency: ``int``
             Indicates how many asynchronous jobs the worker can run in parallel.
             Do not use concurrency if you have synchronous blocking tasks.
             See `howto/production/concurrency` (defaults to ``1``).
-        name : ``Optional[str]``
+        name: ``Optional[str]``
             Name of the worker. Will be passed in the `JobContext` and used in the
             logs (defaults to ``None`` which will result in the worker named
             ``worker``).
-        timeout : ``float``
+        timeout: ``float``
             Indicates the maximum duration (in seconds) the worker waits between
             each database job poll. Raising this parameter can lower the rate at which
             the worker makes queries to the database for requesting jobs.
             (defaults to 5.0)
-        listen_notify : ``bool``
+        listen_notify: ``bool``
             If ``True``, the worker will dedicate a connection from the pool to
             listening to database events, notifying of newly available jobs.
             If ``False``, the worker will just poll the database periodically
             (see ``timeout``). (defaults to ``True``)
-        delete_jobs : ``str``
+        delete_jobs: ``str``
             If ``always``, the worker will automatically delete all jobs on completion.
             If ``successful`` the worker will only delete successful jobs.
             If ``never``, the worker will keep the jobs in the database.

procrastinate/blueprints.py

@@ -69,6 +69,8 @@ def my_task():
     """
 
     def __init__(self) -> None:
+        #: The mapping of all tasks known by the app. Only procrastinate is
+        #: expected to make changes to this mapping.
         self.tasks: dict[str, Task] = {}
         self.periodic_registry = periodic.PeriodicRegistry()
         self._check_stack()

procrastinate/builtin_tasks.py

@@ -26,13 +26,13 @@ async def remove_old_jobs(
     queue :
         The name of the queue in which jobs will be deleted. If not specified, the
         task will delete jobs from all queues.
-    remove_error : ``Optional[bool]``
+    remove_error:
         By default only successful jobs will be removed. When this parameter is True
         failed jobs will also be deleted.
-    remove_cancelled : ``Optional[bool]``
+    remove_cancelled:
         By default only successful jobs will be removed. When this parameter is True
         cancelled jobs will also be deleted.
-    remove_aborted : ``Optional[bool]``
+    remove_aborted:
         By default only successful jobs will be removed. When this parameter is True
         aborted jobs will also be deleted.
     """

procrastinate/contrib/aiopg/aiopg_connector.py

@@ -98,35 +98,35 @@ def __init__(
 
         Parameters
         ----------
-        json_dumps :
+        json_dumps:
             The JSON dumps function to use for serializing job arguments. Defaults to
             the function used by psycopg2. See the `psycopg2 doc`_.
-        json_loads :
+        json_loads:
             The JSON loads function to use for deserializing job arguments. Defaults
             to the function used by psycopg2. See the `psycopg2 doc`_. Unused if the
             pool is externally created and set into the connector through the
             ``App.open_async`` method.
-        dsn : ``Optional[str]``
+        dsn: ``Optional[str]``
             Passed to aiopg. Default is "" instead of None, which means if no argument
             is passed, it will connect to localhost:5432 instead of a Unix-domain
             local socket file.
-        enable_json : ``bool``
+        enable_json: ``bool``
             Passed to aiopg. Default is False instead of True to avoid messing with
             the global state.
         enable_hstore: ``bool``
             Passed to aiopg. Default is False instead of True to avoid messing with
             the global state.
-        enable_uuid : ``bool``
+        enable_uuid: ``bool``
             Passed to aiopg. Default is False instead of True to avoid messing with
             the global state.
-        cursor_factory : ``psycopg2.extensions.cursor``
+        cursor_factory: ``psycopg2.extensions.cursor``
             Passed to aiopg. Default is ``psycopg2.extras.RealDictCursor``
             instead of standard cursor. There is no identified use case for changing
             this.
-        maxsize : ``int``
+        maxsize: ``int``
             Passed to aiopg. If value is 1, then listen/notify feature will be
             deactivated.
-        minsize : ``int``
+        minsize: ``int``
             Passed to aiopg. Initial connections are not opened when the connector
             is created, but at first use of the pool.
         """

procrastinate/contrib/django/django_connector.py

@@ -156,7 +156,7 @@ def get_worker_connector(self) -> connector.BaseAsyncConnector:
 
         Returns
         -------
-        ``procrastinate.contrib.aiopg.AiopgConnector`` or ``procrastinate.contrib.psycopg3.PsycopgConnector``
+        :
             A connector that can be used in a worker
         """
         alias = settings.settings.DATABASE_ALIAS

procrastinate/contrib/django/utils.py

@@ -20,7 +20,7 @@ def connector_params(alias: str = "default") -> dict[str, Any]:
 
     Returns
     -------
-    ``Dict[str, Any]``
+    :
         Provide these keyword arguments when instantiating your connector
     """
     wrapper = connections[alias]

procrastinate/contrib/psycopg2/psycopg2_connector.py

@@ -83,23 +83,23 @@ def __init__(
 
         Parameters
         ----------
-        json_dumps :
+        json_dumps:
             The JSON dumps function to use for serializing job arguments. Defaults to
             the function used by psycopg2. See the `psycopg2 doc`_.
-        json_loads :
+        json_loads:
             The JSON loads function to use for deserializing job arguments. Defaults
             to the function used by psycopg2. See the `psycopg2 doc`_. Unused if the
             pool is externally created and set into the connector through the
             ``App.open`` method.
-        minconn : int
+        minconn: int
             Passed to psycopg2, default set to 1 (same as aiopg).
-        maxconn : int
+        maxconn: int
             Passed to psycopg2, default set to 10 (same as aiopg).
-        dsn : ``Optional[str]``
+        dsn: ``Optional[str]``
             Passed to psycopg2. Default is "" instead of None, which means if no
             argument is passed, it will connect to localhost:5432 instead of a
             Unix-domain local socket file.
-        cursor_factory : ``psycopg2.extensions.cursor``
+        cursor_factory: ``psycopg2.extensions.cursor``
             Passed to psycopg2. Default is ``psycopg2.extras.RealDictCursor``
             instead of standard cursor. There is no identified use case for changing
             this.