djanquiltdb-plugin-celery 1.0.0__tar.gz

djanquiltdb_plugin_celery-1.0.0/CHANGELOG.rst

@@ -0,0 +1,4 @@
+v 1.0.0 (2026-10-22)
+--------------------
+Added:
+ * Initial release.

djanquiltdb_plugin_celery-1.0.0/LICENSE

@@ -0,0 +1,23 @@
+Copyright (c) 2026, DjanQuiltDB Project
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+    * Redistributions of source code must retain the above copyright notice, this
+      list of conditions and the following disclaimer.
+    * 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.
+    * 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.

djanquiltdb_plugin_celery-1.0.0/MANIFEST.in

@@ -0,0 +1,19 @@
+# The sdist is what downstream packagers build and test from, so it includes the whole test project, not just the
+# importable package. Without the graft below, setuptools' defaults ship none of the fixture apps or settings that the
+# suite imports, and the suite in the sdist cannot run.
+#
+# The documentation is not here: docs/ is at the repository root and covers the core library and the in-tree plugins
+# together, so docs/ cannot be grafted into one package. The Documentation URL in pyproject.toml points to the
+# documentation.
+
+include CHANGELOG.rst
+include LICENSE
+include README.rst
+
+graft tests
+
+global-exclude *.py[cod]
+global-exclude __pycache__
+# A local test run leaves its coverage data in the test project; it is not part of the release.
+global-exclude .coverage
+global-exclude .coverage.*

djanquiltdb_plugin_celery-1.0.0/PKG-INFO

@@ -0,0 +1,137 @@
+Metadata-Version: 2.4
+Name: djanquiltdb-plugin-celery
+Version: 1.0.0
+Summary: Celery tasks that run in a shard, or once in every shard, of a DjanQuiltDB project
+Author-email: DjanQuiltDB Project <djanquiltdb@portal42.net>
+License-Expression: BSD-3-Clause
+Project-URL: Homepage, https://github.com/DjanQuiltDB/djanquiltdb
+Project-URL: Documentation, https://djanquiltdb.readthedocs.io/en/latest/plugins/celery/index.html
+Project-URL: Source, https://github.com/DjanQuiltDB/djanquiltdb/tree/master/packages/djanquiltdb-plugin-celery
+Project-URL: Issues, https://github.com/DjanQuiltDB/djanquiltdb/issues
+Project-URL: Changelog, https://github.com/DjanQuiltDB/djanquiltdb/blob/master/packages/djanquiltdb-plugin-celery/CHANGELOG.rst
+Keywords: django,database,sharding,postgresql,celery,tasks
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Environment :: Web Environment
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Framework :: Celery
+Classifier: Framework :: Django
+Classifier: Framework :: Django :: 6.0
+Classifier: Framework :: Django :: 6.1
+Classifier: Topic :: Database
+Requires-Python: >=3.14
+Description-Content-Type: text/x-rst
+License-File: LICENSE
+Requires-Dist: django<7.0,>=6.0
+Requires-Dist: djanquiltdb<5.0,>=4.4
+Requires-Dist: celery<6.0,>=5.6
+Provides-Extra: lint
+Requires-Dist: ruff==0.15.21; extra == "lint"
+Provides-Extra: test
+Requires-Dist: coverage; extra == "test"
+Requires-Dist: psycopg[binary]>=3.0.0; extra == "test"
+Requires-Dist: dj-database-url; extra == "test"
+Provides-Extra: docs
+Requires-Dist: sphinx<10,>=8; extra == "docs"
+Provides-Extra: dev
+Requires-Dist: djanquiltdb-plugin-celery[docs,lint,test]; extra == "dev"
+Requires-Dist: pre-commit; extra == "dev"
+Requires-Dist: tox>=4.21; extra == "dev"
+Requires-Dist: build; extra == "dev"
+Requires-Dist: twine; extra == "dev"
+Dynamic: license-file
+
+.. The logo needs an absolute URL: this README is the PyPI long description, where an image with a relative path does
+   not render.
+
+.. image:: https://raw.githubusercontent.com/DjanQuiltDB/djanquiltdb/master/assets/icon-128.png
+    :alt: DjanQuiltDB
+    :width: 128
+
+=========================
+djanquiltdb-plugin-celery
+=========================
+
+.. image:: https://img.shields.io/pypi/v/djanquiltdb-plugin-celery.svg
+    :target: https://pypi.org/project/djanquiltdb-plugin-celery/
+    :alt: PyPI
+
+.. image:: https://img.shields.io/pypi/pyversions/djanquiltdb-plugin-celery.svg
+    :target: https://pypi.org/project/djanquiltdb-plugin-celery/
+    :alt: Supported Python versions
+
+.. image:: https://img.shields.io/pypi/frameworkversions/django/djanquiltdb-plugin-celery.svg
+    :target: https://pypi.org/project/djanquiltdb-plugin-celery/
+    :alt: Supported Django versions
+
+.. image:: https://img.shields.io/badge/postgres-17%20%7C%2018-4169e1?logo=postgresql&logoColor=white
+    :target: https://www.postgresql.org/
+    :alt: Supported PostgreSQL versions
+
+.. image:: https://github.com/DjanQuiltDB/djanquiltdb/actions/workflows/ci.yml/badge.svg
+    :target: https://github.com/DjanQuiltDB/djanquiltdb/actions/workflows/ci.yml
+    :alt: CI
+
+.. image:: https://readthedocs.org/projects/djanquiltdb/badge/?version=latest
+    :target: https://djanquiltdb.readthedocs.io/en/latest/plugins/celery/index.html
+    :alt: Documentation
+
+.. image:: https://img.shields.io/pypi/l/djanquiltdb-plugin-celery.svg
+    :target: https://github.com/DjanQuiltDB/djanquiltdb/blob/master/LICENSE
+    :alt: BSD-3-Clause licence
+
+`DjanQuiltDB <https://github.com/djanquiltdb/djanquiltdb>`_ shards a database across schemas and nodes. This library
+provides `Celery <https://docs.celeryq.dev/>`_ tasks that run in the shard that they are sent to, and that are retried
+while that shard is in maintenance::
+
+    from djanquiltdb.decorators.celery import task_for_shard
+
+
+    @task_for_shard
+    def send_invoice(invoice_id):
+        Invoice.objects.get(pk=invoice_id).send()
+
+
+    send_invoice.for_shard(shard).delay(invoice_id=12)
+    send_invoice.delay(invoice_id=12, tenant_id=3)
+
+A task that is decorated with ``task_for_node`` runs in the public schema of the node that its ``node_name`` identifies.
+A task that is decorated with ``task_for_active_shard`` runs in the shard that is active where the task is sent. A task
+that is decorated with ``task_for_every_shard`` runs once in every active shard when it is sent without a shard::
+
+    from djanquiltdb.decorators.celery import task_for_every_shard
+
+
+    @task_for_every_shard(queue='fanout', spread=(0, 300))
+    def clean_up_drafts():
+        Draft.objects.filter(updated_at__lt=a_month_ago()).delete()
+
+
+    clean_up_drafts.delay()
+
+Install the plugin through the ``celery`` extra of DjanQuiltDB::
+
+    pip install djanquiltdb[celery]
+
+Full documentation is at https://djanquiltdb.readthedocs.io/en/latest/plugins/celery/index.html.
+
+Development
+===========
+
+This package is developed in the `DjanQuiltDB repository <https://github.com/DjanQuiltDB/djanquiltdb>`_ beside
+``djanquiltdb`` itself. Tests run through tox against the Postgres containers in the repository's
+``docker-compose.yml``; see ``DOCKER.md`` at the repository root::
+
+    docker compose run --rm test tox
+
+Requirements
+------------
+
+* Python 3.14
+* Django 6.0 or 6.1
+* PostgreSQL 17 or 18
+* djanquiltdb 4.4.0 or newer 4.x
+* Celery 5.6 or newer 5.x

djanquiltdb_plugin_celery-1.0.0/README.rst

@@ -0,0 +1,91 @@
+.. The logo needs an absolute URL: this README is the PyPI long description, where an image with a relative path does
+   not render.
+
+.. image:: https://raw.githubusercontent.com/DjanQuiltDB/djanquiltdb/master/assets/icon-128.png
+    :alt: DjanQuiltDB
+    :width: 128
+
+=========================
+djanquiltdb-plugin-celery
+=========================
+
+.. image:: https://img.shields.io/pypi/v/djanquiltdb-plugin-celery.svg
+    :target: https://pypi.org/project/djanquiltdb-plugin-celery/
+    :alt: PyPI
+
+.. image:: https://img.shields.io/pypi/pyversions/djanquiltdb-plugin-celery.svg
+    :target: https://pypi.org/project/djanquiltdb-plugin-celery/
+    :alt: Supported Python versions
+
+.. image:: https://img.shields.io/pypi/frameworkversions/django/djanquiltdb-plugin-celery.svg
+    :target: https://pypi.org/project/djanquiltdb-plugin-celery/
+    :alt: Supported Django versions
+
+.. image:: https://img.shields.io/badge/postgres-17%20%7C%2018-4169e1?logo=postgresql&logoColor=white
+    :target: https://www.postgresql.org/
+    :alt: Supported PostgreSQL versions
+
+.. image:: https://github.com/DjanQuiltDB/djanquiltdb/actions/workflows/ci.yml/badge.svg
+    :target: https://github.com/DjanQuiltDB/djanquiltdb/actions/workflows/ci.yml
+    :alt: CI
+
+.. image:: https://readthedocs.org/projects/djanquiltdb/badge/?version=latest
+    :target: https://djanquiltdb.readthedocs.io/en/latest/plugins/celery/index.html
+    :alt: Documentation
+
+.. image:: https://img.shields.io/pypi/l/djanquiltdb-plugin-celery.svg
+    :target: https://github.com/DjanQuiltDB/djanquiltdb/blob/master/LICENSE
+    :alt: BSD-3-Clause licence
+
+`DjanQuiltDB <https://github.com/djanquiltdb/djanquiltdb>`_ shards a database across schemas and nodes. This library
+provides `Celery <https://docs.celeryq.dev/>`_ tasks that run in the shard that they are sent to, and that are retried
+while that shard is in maintenance::
+
+    from djanquiltdb.decorators.celery import task_for_shard
+
+
+    @task_for_shard
+    def send_invoice(invoice_id):
+        Invoice.objects.get(pk=invoice_id).send()
+
+
+    send_invoice.for_shard(shard).delay(invoice_id=12)
+    send_invoice.delay(invoice_id=12, tenant_id=3)
+
+A task that is decorated with ``task_for_node`` runs in the public schema of the node that its ``node_name`` identifies.
+A task that is decorated with ``task_for_active_shard`` runs in the shard that is active where the task is sent. A task
+that is decorated with ``task_for_every_shard`` runs once in every active shard when it is sent without a shard::
+
+    from djanquiltdb.decorators.celery import task_for_every_shard
+
+
+    @task_for_every_shard(queue='fanout', spread=(0, 300))
+    def clean_up_drafts():
+        Draft.objects.filter(updated_at__lt=a_month_ago()).delete()
+
+
+    clean_up_drafts.delay()
+
+Install the plugin through the ``celery`` extra of DjanQuiltDB::
+
+    pip install djanquiltdb[celery]
+
+Full documentation is at https://djanquiltdb.readthedocs.io/en/latest/plugins/celery/index.html.
+
+Development
+===========
+
+This package is developed in the `DjanQuiltDB repository <https://github.com/DjanQuiltDB/djanquiltdb>`_ beside
+``djanquiltdb`` itself. Tests run through tox against the Postgres containers in the repository's
+``docker-compose.yml``; see ``DOCKER.md`` at the repository root::
+
+    docker compose run --rm test tox
+
+Requirements
+------------
+
+* Python 3.14
+* Django 6.0 or 6.1
+* PostgreSQL 17 or 18
+* djanquiltdb 4.4.0 or newer 4.x
+* Celery 5.6 or newer 5.x

djanquiltdb_plugin_celery-1.0.0/pyproject.toml

@@ -0,0 +1,99 @@
+[build-system]
+# The PEP 639 license expression below needs setuptools 77, which is also new enough that `wheel` does not have to be
+# declared here.
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "djanquiltdb-plugin-celery"
+dynamic = ["version"]
+description = "Celery tasks that run in a shard, or once in every shard, of a DjanQuiltDB project"
+readme = "README.rst"
+requires-python = ">=3.14"
+license = "BSD-3-Clause"
+license-files = ["LICENSE"]
+authors = [
+    { name = "DjanQuiltDB Project", email = "djanquiltdb@portal42.net" },
+]
+keywords = [
+    "django",
+    "database",
+    "sharding",
+    "postgresql",
+    "celery",
+    "tasks",
+]
+classifiers = [
+    "Development Status :: 5 - Production/Stable",
+    "Environment :: Web Environment",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.14",
+    "Framework :: Celery",
+    "Framework :: Django",
+    "Framework :: Django :: 6.0",
+    "Framework :: Django :: 6.1",
+    "Topic :: Database",
+]
+dependencies = [
+    "django>=6.0,<7.0",
+    # 4.4 enters a shard id or a mapping value of 0, and reads the shard again once use_shard holds its lock, so that a
+    # task that is retried during a move does not enter the shard where it was before the move.
+    "djanquiltdb>=4.4,<5.0",
+    # 5.6 is the first release that supports Python 3.14. QuiltTask, the task class of the plugin, subclasses
+    # celery.contrib.django.task.DjangoTask and relies on Celery passing custom message headers on to
+    # task.request.headers, so a new major version has to be checked before the upper bound is raised.
+    "celery>=5.6,<6.0",
+]
+
+[project.entry-points."djanquiltdb.plugins"]
+celery = "djanquiltdb_plugin_celery:plugin"
+
+[project.urls]
+Homepage = "https://github.com/DjanQuiltDB/djanquiltdb"
+Documentation = "https://djanquiltdb.readthedocs.io/en/latest/plugins/celery/index.html"
+Source = "https://github.com/DjanQuiltDB/djanquiltdb/tree/master/packages/djanquiltdb-plugin-celery"
+Issues = "https://github.com/DjanQuiltDB/djanquiltdb/issues"
+Changelog = "https://github.com/DjanQuiltDB/djanquiltdb/blob/master/packages/djanquiltdb-plugin-celery/CHANGELOG.rst"
+
+[project.optional-dependencies]
+lint = [
+    "ruff==0.15.21",
+]
+test = [
+    "coverage",
+    "psycopg[binary]>=3.0.0",
+    "dj-database-url",
+]
+docs = [
+    "sphinx>=8,<10",
+]
+dev = [
+    "djanquiltdb-plugin-celery[test,lint,docs]",
+    "pre-commit",
+    # 4.21 is the first release with native TOML configuration, so that tox.ini is not needed.
+    "tox>=4.21",
+    "build",
+    "twine",
+]
+
+[tool.setuptools.dynamic]
+version = { attr = "djanquiltdb_plugin_celery.__version__" }
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.coverage.run]
+source = ["djanquiltdb_plugin_celery"]
+branch = true
+
+[tool.coverage.report]
+show_missing = true
+fail_under = 100
+
+# The shared settings are in ruff.toml at the repository root, and only the src roots are set per package.
+[tool.ruff]
+extend = "../../ruff.toml"
+src = ["src", "tests"]

djanquiltdb_plugin_celery-1.0.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

djanquiltdb_plugin_celery-1.0.0/src/djanquiltdb_plugin_celery/__init__.py

@@ -0,0 +1,52 @@
+"""
+This package defines the plugin object, which DjanQuiltDB finds through the ``djanquiltdb.plugins`` entry-point group,
+and exports the public API of the plugin. DjanQuiltDB serves the decorators as ``djanquiltdb.decorators.celery``, and
+the helpers as ``djanquiltdb.utils.celery``.
+"""
+
+from types import SimpleNamespace
+
+from djanquiltdb_plugin_celery import decorators, utils
+from djanquiltdb_plugin_celery.decorators import (
+    task_for_active_shard,
+    task_for_every_node,
+    task_for_every_shard,
+    task_for_node,
+    task_for_shard,
+)
+from djanquiltdb_plugin_celery.utils import (
+    aggregate_per_shard,
+    fan_out,
+    fan_out_to_nodes,
+    fanout_shards,
+    per_node_signatures,
+    per_shard_signatures,
+)
+
+__version__ = '1.0.0'
+
+
+def install():
+    """
+    Registers the plugin's system checks. DjanQuiltDB calls install() once the app registry is ready.
+    """
+    from djanquiltdb_plugin_celery import checks  # noqa: F401
+
+
+plugin = SimpleNamespace(decorators=decorators, utils=utils, install=install)
+
+__all__ = [
+    'aggregate_per_shard',
+    'fan_out',
+    'fan_out_to_nodes',
+    'fanout_shards',
+    'install',
+    'per_node_signatures',
+    'per_shard_signatures',
+    'plugin',
+    'task_for_active_shard',
+    'task_for_every_node',
+    'task_for_every_shard',
+    'task_for_node',
+    'task_for_shard',
+]

djanquiltdb_plugin_celery-1.0.0/src/djanquiltdb_plugin_celery/checks.py

@@ -0,0 +1,79 @@
+from django.conf import settings
+from django.core import checks
+from djanquiltdb.utils import get_mapping_class
+
+from djanquiltdb_plugin_celery.settings import (
+    QUEUE_DESCRIPTION,
+    QUILT_CELERY_DEFAULTS,
+    SPREAD_DESCRIPTION,
+    is_spread,
+)
+from djanquiltdb_plugin_celery.targets import NODE_NAME_KWARG, SHARD_ID_KWARG
+
+#: For each key of QUILT_CELERY: a function that returns whether a value of the key is valid, and how a message
+#: describes the valid values. A boolean is an instance of int, so the keys that accept an integer and not a boolean
+#: exclude it.
+QUILT_CELERY_VALIDATORS = {
+    'MAPPING_KWARG': (lambda value: isinstance(value, (str, type(None))), 'a string or None'),
+    'MAX_RETRIES': (
+        lambda value: value is None or (isinstance(value, int) and not isinstance(value, bool)),
+        'an integer or None',
+    ),
+    'RETRY_BACKOFF': (lambda value: isinstance(value, (bool, int)), 'a boolean or an integer'),
+    'RETRY_BACKOFF_MAX': (lambda value: isinstance(value, int) and not isinstance(value, bool), 'an integer'),
+    'RETRY_JITTER': (lambda value: isinstance(value, bool), 'a boolean'),
+    'FANOUT_QUEUE': (lambda value: isinstance(value, (str, type(None))), QUEUE_DESCRIPTION),
+    'FANOUT_SPREAD': (is_spread, SPREAD_DESCRIPTION),
+}
+
+
+@checks.register(checks.Tags.compatibility)
+def check_quilt_celery_setting(app_configs, **kwargs):
+    """
+    Reports a QUILT_CELERY setting, key or value that the celery plugin cannot use.
+    """
+    quilt_celery = getattr(settings, 'QUILT_CELERY', {})
+
+    if not isinstance(quilt_celery, dict):
+        return [checks.Error('QUILT_CELERY is not a dict.', id='djanquiltdb_plugin_celery.E002')]
+
+    messages = [
+        checks.Error(
+            'QUILT_CELERY has the key {!r}, which the celery plugin does not read.'.format(name),
+            hint='The plugin reads the keys {}.'.format(', '.join(QUILT_CELERY_DEFAULTS)),
+            id='djanquiltdb_plugin_celery.E001',
+        )
+        for name in quilt_celery
+        if name not in QUILT_CELERY_DEFAULTS
+    ]
+
+    for name, (is_valid, description) in QUILT_CELERY_VALIDATORS.items():
+        if name in quilt_celery and not is_valid(quilt_celery[name]):
+            messages.append(
+                checks.Error(
+                    "QUILT_CELERY['{}'] is {!r}, and it accepts {}.".format(name, quilt_celery[name], description),
+                    id='djanquiltdb_plugin_celery.E002',
+                )
+            )
+
+    if quilt_celery.get('MAPPING_KWARG') in (SHARD_ID_KWARG, NODE_NAME_KWARG):
+        messages.append(
+            checks.Error(
+                "QUILT_CELERY['MAPPING_KWARG'] is {!r}, which already identifies a target in another way.".format(
+                    quilt_celery['MAPPING_KWARG']
+                ),
+                hint='Set it to the keyword argument that has the mapping value, such as tenant_id.',
+                id='djanquiltdb_plugin_celery.E002',
+            )
+        )
+    elif quilt_celery.get('MAPPING_KWARG') and get_mapping_class() is None:
+        messages.append(
+            checks.Error(
+                "QUILT_CELERY['MAPPING_KWARG'] is {!r}, but QUILT_DB has no MAPPING_MODEL in which a task can look up "
+                'the shard of a mapping value.'.format(quilt_celery['MAPPING_KWARG']),
+                hint="Set QUILT_DB['MAPPING_MODEL'], or remove QUILT_CELERY['MAPPING_KWARG'].",
+                id='djanquiltdb_plugin_celery.E002',
+            )
+        )
+
+    return messages