djanquiltdb-plugin-postgres-objects 1.0.0__py3-none-any.whl

djanquiltdb_plugin_postgres_objects/__init__.py

@@ -0,0 +1,34 @@
+"""
+The plugin object DjanQuiltDB discovers through the ``djanquiltdb.plugins`` entry-point group.
+
+It exposes two things. ``decorators`` is the module DjanQuiltDB serves from ``djanquiltdb.decorators``, so the
+placement decorators read the same as the model ones. ``install()`` runs when the app registry is ready, and gives
+declared objects their default placement.
+"""
+
+from types import SimpleNamespace
+
+from djanquiltdb_plugin_postgres_objects import decorators
+
+__version__ = '1.0.0'
+
+
+def install():
+    """
+    Give declared database objects a default placement.
+
+    django-postgres-objects manages Postgres objects that are not tables, and has no notion of placement: a declaration
+    carries no routing hints unless something puts them there, which is exactly right for the single-database projects
+    it is also meant to serve. Inside a sharded project the sensible default is the public schema, since that is where
+    a function called by a stored generated column belongs and it stays reachable from every shard's search path.
+
+    The placement decorators set the hints per declaration and so override this.
+    """
+    from djanquiltdb import ShardingMode
+    from postgres_objects.base import DeclarativeObject
+
+    if not DeclarativeObject.router_hints:
+        DeclarativeObject.router_hints = {'sharding_mode': ShardingMode.PUBLIC}
+
+
+plugin = SimpleNamespace(decorators=decorators, install=install)

djanquiltdb_plugin_postgres_objects/decorators.py

@@ -0,0 +1,250 @@
+from djanquiltdb import ShardingMode
+from djanquiltdb.postgresql_backend.base import PUBLIC_SCHEMA_NAME
+from djanquiltdb.router import get_active_connection
+from djanquiltdb.utils import get_all_databases, transaction_for_every_node, use_shard
+
+
+def _annotate_refresh(cls, sharding_mode):
+    """
+    Point a declared materialized view's refresh at the correct copy.
+
+    Left alone, django-postgres-objects sends a refresh to the connection its own routing picks, which for a raw-sql
+    declaration is the default one: the wrong copy for any view that does not live on the public schema of the default
+    node. ``db_for_refresh`` is the hook it documents for exactly this, so the active connection goes there instead.
+    Which schema that is resolves through the search path, since the view is named unqualified, and a view is either
+    sharded or public and never both.
+
+    A mirrored view is the one mode no single connection answers for: its copies sit on the public schema of every
+    node. Its refresh is wrapped to visit them all inside one cascading transaction, the way
+    ``atomic_write_to_every_node`` propagates any other mirrored write, so either every copy moves or none does.
+    Naming a connection with ``using`` still pins it to one.
+    """
+
+    def db_for_refresh(declaration):
+        return get_active_connection()
+
+    cls.db_for_refresh = classmethod(db_for_refresh)
+
+    if sharding_mode is not ShardingMode.MIRRORED:
+        # Re-annotating away from MIRRORED, either on the declaration itself or on a subclass of a mirrored one, has to
+        # drop the fan-out the mirrored annotation wraps around refresh.
+        base = getattr(cls.refresh.__func__, '__wrapped_refresh__', None)
+        if base is not None:
+            cls.refresh = classmethod(base)
+        return
+
+    # The plain function rather than the bound classmethod, so a subclassed declaration refreshes its own view and not
+    # its parent's, and unwrapped first, so annotating an already annotated declaration cannot nest the loop.
+    base = getattr(cls.refresh.__func__, '__wrapped_refresh__', cls.refresh.__func__)
+
+    def refresh(declaration, concurrently=False, using=None):
+        if using is not None:
+            return base(declaration, concurrently=concurrently, using=using)
+
+        with transaction_for_every_node():
+            for node_name in get_all_databases():
+                with use_shard(node_name=node_name, schema_name=PUBLIC_SCHEMA_NAME):
+                    base(declaration, concurrently=concurrently)
+
+    refresh.__wrapped_refresh__ = base
+    cls.refresh = classmethod(refresh)
+
+
+def _annotate_object(cls, sharding_mode):
+    """
+    Mark a declared database object as belonging to a sharding mode.
+
+    django-postgres-objects hands ``router_hints`` to ``allow_migrate`` for every operation on the object, so putting
+    the sharding mode there routes it exactly the way a model of that mode is routed. It knows nothing about sharding
+    itself; this is the whole of the seam between the two libraries.
+    """
+    cls.router_hints = {'sharding_mode': sharding_mode}
+
+    if hasattr(cls, 'db_for_refresh'):
+        _annotate_refresh(cls, sharding_mode)
+
+    return cls
+
+
+def mirrored_function():
+    """
+    A decorator for marking a declared Postgres function as being mirrored across the various nodes.
+
+    The function is created on the public schema of every node, which is where ``@public_function()`` puts it too: a
+    function holds no data, so there is nothing for the two modes to differ by. Pick whichever names the intent, the
+    way the model decorators do.
+
+    :Example:
+        .. code-block:: python
+
+            from djanquiltdb.decorators import mirrored_function
+            from postgres_objects import Function
+
+
+            @mirrored_function()
+            class AllUppercase(Function):
+                arguments = 'input TEXT'
+                returns = 'TEXT'
+                volatility = 'IMMUTABLE'
+                body = '''
+                    BEGIN
+                        RETURN UPPER(input);
+                    END;
+                '''
+    """
+
+    def configure(cls):
+        return _annotate_object(cls, ShardingMode.MIRRORED)
+
+    return configure
+
+
+def public_function():
+    """
+    A decorator for marking a declared Postgres function as living in the public schema.
+
+    This is what a function used by a stored generated column normally wants. The search path of a shard covers the
+    shard's own schema and the public schema, so an unqualified call from inside a shard resolves.
+
+    The function is created on the public schema of every node, since that is where every shard's search path can
+    reach it. That is the same placement ``@mirrored_function()`` gives, and for a function the two are equivalent;
+    what a mode records here is intent rather than a different set of schemas.
+
+    :Example:
+        .. code-block:: python
+
+            from djanquiltdb.decorators import public_function
+            from postgres_objects import Function
+
+
+            @public_function()
+            class AllUppercase(Function):
+                arguments = 'input TEXT'
+                returns = 'TEXT'
+                volatility = 'IMMUTABLE'
+                strict = True
+                parallel = 'SAFE'
+                body = '''
+                    BEGIN
+                        RETURN UPPER(input);
+                    END;
+                '''
+    """
+
+    def configure(cls):
+        return _annotate_object(cls, ShardingMode.PUBLIC)
+
+    return configure
+
+
+def sharded_function():
+    """
+    A decorator for marking a declared Postgres function as being sharded.
+
+    The function is created on the template schema and on every shard, and not on the public schema. Note that a
+    ``PUBLIC`` function can already read sharded tables: as long as the table names in its body are not
+    schema-qualified, they resolve at execution time to the tables of whichever schema the caller is pointed at. Reach
+    for a sharded function when the *function itself* has to differ per shard.
+
+    :Example:
+        .. code-block:: python
+
+            from djanquiltdb.decorators import sharded_function
+            from postgres_objects import Function
+
+
+            @sharded_function()
+            class ShardTotal(Function):
+                returns = 'BIGINT'
+                body = '''
+                    BEGIN
+                        RETURN (SELECT COUNT(*) FROM example_cake);
+                    END;
+                '''
+    """
+
+    def configure(cls):
+        return _annotate_object(cls, ShardingMode.SHARDED)
+
+    return configure
+
+
+def mirrored_view():
+    """
+    A decorator for marking a declared Postgres view as being mirrored across the various nodes.
+
+    The view is created on the public schema of every node, which is where a view over mirrored tables belongs. A
+    ``@public_view()`` reaches those same schemas; what MIRRORED adds is that the copies are kept in step, so a
+    materialized one refreshes on every node at once rather than on the connection in context.
+
+    :Example:
+        .. code-block:: python
+
+            from djanquiltdb.decorators import mirrored_view
+            from postgres_objects import View
+
+
+            @mirrored_view()
+            class ActiveTypes(View):
+                sql = 'SELECT id, name FROM example_type WHERE active'
+    """
+
+    def configure(cls):
+        return _annotate_object(cls, ShardingMode.MIRRORED)
+
+    return configure
+
+
+def public_view():
+    """
+    A decorator for marking a declared Postgres view as living in the public schema.
+
+    A view is created on the public schema of every node and reads the tables that live there. Those are the same
+    schemas a mirrored view reaches; what PUBLIC says is that each copy stands on its own, over sources that may differ
+    per node, and that a materialized one is refreshed on the connection in context rather than everywhere at once.
+
+    Note that unlike a function, a public view is *not* a way to read sharded tables: a view's body is resolved when it
+    is created, not when it is queried, so the tables it names are pinned to the schema it was created in. A view over
+    sharded tables has to be sharded itself.
+
+    :Example:
+        .. code-block:: python
+
+            from djanquiltdb.decorators import public_view
+            from postgres_objects import View
+
+
+            @public_view()
+            class CakeTypeNames(View):
+                sql = 'SELECT id, name FROM example_caketype'
+    """
+
+    def configure(cls):
+        return _annotate_object(cls, ShardingMode.PUBLIC)
+
+    return configure
+
+
+def sharded_view():
+    """
+    A decorator for marking a declared Postgres view as being sharded.
+
+    The view is created on the template schema and on every shard, and not on the public schema. This is what a view
+    over sharded tables needs: each shard gets its own copy, reading the tables of the schema it was created in.
+
+    :Example:
+        .. code-block:: python
+
+            from djanquiltdb.decorators import sharded_view
+            from postgres_objects import View
+
+
+            @sharded_view()
+            class LoudCakes(View):
+                sql = 'SELECT id, upper(name) AS name FROM example_cake'
+    """
+
+    def configure(cls):
+        return _annotate_object(cls, ShardingMode.SHARDED)
+
+    return configure

djanquiltdb_plugin_postgres_objects-1.0.0.dist-info/METADATA

@@ -0,0 +1,135 @@
+Metadata-Version: 2.4
+Name: djanquiltdb-plugin-postgres-objects
+Version: 1.0.0
+Summary: DjanQuiltDB decorators for functions/views as declared by django-postgres-objects
+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/postgres-objects/index.html
+Project-URL: Source, https://github.com/DjanQuiltDB/djanquiltdb/tree/master/packages/djanquiltdb-plugin-postgres-objects
+Project-URL: Issues, https://github.com/DjanQuiltDB/djanquiltdb/issues
+Project-URL: Changelog, https://github.com/DjanQuiltDB/djanquiltdb/blob/master/packages/djanquiltdb-plugin-postgres-objects/CHANGELOG.rst
+Keywords: django,database,sharding,postgresql,migrations
+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 :: 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.0
+Requires-Dist: django-postgres-objects<2.0,>=1.0
+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-postgres-objects[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 a relative path renders broken.
+
+.. image:: https://raw.githubusercontent.com/DjanQuiltDB/djanquiltdb/master/assets/icon-128.png
+    :alt: DjanQuiltDB
+    :width: 128
+
+===================================
+djanquiltdb-plugin-postgres-objects
+===================================
+
+.. image:: https://img.shields.io/pypi/v/djanquiltdb-plugin-postgres-objects.svg
+    :target: https://pypi.org/project/djanquiltdb-plugin-postgres-objects/
+    :alt: PyPI
+
+.. image:: https://img.shields.io/pypi/pyversions/djanquiltdb-plugin-postgres-objects.svg
+    :target: https://pypi.org/project/djanquiltdb-plugin-postgres-objects/
+    :alt: Supported Python versions
+
+.. image:: https://img.shields.io/pypi/frameworkversions/django/djanquiltdb-plugin-postgres-objects.svg
+    :target: https://pypi.org/project/djanquiltdb-plugin-postgres-objects/
+    :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/postgres-objects/index.html
+    :alt: Documentation
+
+.. image:: https://img.shields.io/pypi/l/djanquiltdb-plugin-postgres-objects.svg
+    :target: https://github.com/DjanQuiltDB/djanquiltdb/blob/master/LICENSE
+    :alt: BSD-3-Clause licence
+
+`django-postgres-objects <https://github.com/djanquiltdb/django-postgres-objects>`_ declares Postgres functions and
+views as classes and lets ``makemigrations`` manage them. `DjanQuiltDB <https://github.com/djanquiltdb/djanquiltdb>`_
+shards a database across schemas and nodes. This library serves as a compatibility layer between them, allowing you to
+mark declarative functions and views as sharded::
+
+    # example/functions.py
+    from djanquiltdb.decorators import public_function
+    from postgres_objects import Function
+
+
+    @public_function()
+    class AllUppercase(Function):
+        arguments = 'input TEXT'
+        returns = 'TEXT'
+        volatility = 'IMMUTABLE'
+        strict = True
+        parallel = 'SAFE'
+        body = """
+            BEGIN
+                RETURN UPPER(input);
+            END;
+        """
+
+Install it through DjanQuiltDB's extra::
+
+    pip install djanquiltdb[postgres-objects]
+
+The decorators are importable from ``djanquiltdb.decorators`` beside the model ones, as above.
+
+Functions get ``@public_function``, ``@mirrored_function`` and ``@sharded_function``; views get ``@public_view``,
+``@mirrored_view`` and ``@sharded_view``. An unannotated declaration is placed in the public schema, so declarations
+written for a single-database project keep working once that project is sharded.
+
+Full documentation is at https://djanquiltdb.readthedocs.io/en/latest/plugins/postgres-objects/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.x
+* django-postgres-objects 1.x

djanquiltdb_plugin_postgres_objects-1.0.0.dist-info/RECORD

@@ -0,0 +1,8 @@
+djanquiltdb_plugin_postgres_objects/__init__.py,sha256=-pcKqDW1csaXDO5fmVbn9IhjWyFf90OCQV62BqRF6CE,1422
+djanquiltdb_plugin_postgres_objects/decorators.py,sha256=n4Hdc7NcBfbk9M0aGMHK4Tpf6fIOs13JtUtDNQH58Ng,9356
+djanquiltdb_plugin_postgres_objects-1.0.0.dist-info/licenses/LICENSE,sha256=SjqLhDqFqtKwwJqhC-80QG9cPUmuTv3yBPEp67_7dQE,1505
+djanquiltdb_plugin_postgres_objects-1.0.0.dist-info/METADATA,sha256=8YUqJialoDZRxrv1XHihzKGT5TxKC6y8hBE3ohli3Qo,5692
+djanquiltdb_plugin_postgres_objects-1.0.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+djanquiltdb_plugin_postgres_objects-1.0.0.dist-info/entry_points.txt,sha256=6DJMa7zy91HQhZJhID_Ip4eMx7oEZMdwooya5uem6_8,84
+djanquiltdb_plugin_postgres_objects-1.0.0.dist-info/top_level.txt,sha256=jjrA6v2_W4CmFSOIl1MpyQnc-IiRfrV07o3DuEoBQ2Y,36
+djanquiltdb_plugin_postgres_objects-1.0.0.dist-info/RECORD,,

djanquiltdb_plugin_postgres_objects-1.0.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

djanquiltdb_plugin_postgres_objects-1.0.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[djanquiltdb.plugins]
+postgres_objects = djanquiltdb_plugin_postgres_objects:plugin

djanquiltdb_plugin_postgres_objects-1.0.0.dist-info/licenses/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_postgres_objects-1.0.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+djanquiltdb_plugin_postgres_objects