django-postgres-denormalize 1.0.0__py3-none-any.whl

django_postgres_denormalize-1.0.0.dist-info/METADATA

@@ -0,0 +1,154 @@
+Metadata-Version: 2.4
+Name: django-postgres-denormalize
+Version: 1.0.0
+Summary: Trigger-maintained copies of ancestor columns for Django on PostgreSQL.
+Author-email: DjanQuiltDB Project <djanquiltdb@portal42.net>
+License-Expression: BSD-3-Clause
+Project-URL: Homepage, https://github.com/djanquiltdb/django-postgres-denormalize
+Project-URL: Documentation, https://django-postgres-denormalize.readthedocs.io/
+Project-URL: Source, https://github.com/djanquiltdb/django-postgres-denormalize
+Project-URL: Issues, https://github.com/djanquiltdb/django-postgres-denormalize/issues
+Project-URL: Changelog, https://github.com/djanquiltdb/django-postgres-denormalize/blob/master/CHANGELOG.rst
+Keywords: django,database,postgresql,denormalization,triggers
+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
+Classifier: Typing :: Typed
+Requires-Python: >=3.14
+Description-Content-Type: text/x-rst
+License-File: LICENSE
+Requires-Dist: django<7.0,>=6.0
+Requires-Dist: django-pgtrigger<5,>=4.17
+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"
+Requires-Dist: sphinx-rtd-theme<4,>=3.1; extra == "docs"
+Requires-Dist: psycopg[binary]>=3.0.0; extra == "docs"
+Provides-Extra: dev
+Requires-Dist: django-postgres-denormalize[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
+
+.. image:: https://raw.githubusercontent.com/DjanQuiltDB/django-postgres-denormalize/master/assets/icon-128.png
+    :alt: django-postgres-denormalize
+    :width: 128
+
+===========================
+django-postgres-denormalize
+===========================
+
+.. image:: https://img.shields.io/pypi/v/django-postgres-denormalize.svg
+    :target: https://pypi.org/project/django-postgres-denormalize/
+    :alt: PyPI
+
+.. image:: https://img.shields.io/pypi/pyversions/django-postgres-denormalize.svg
+    :target: https://pypi.org/project/django-postgres-denormalize/
+    :alt: Supported Python versions
+
+.. image:: https://img.shields.io/pypi/frameworkversions/django/django-postgres-denormalize.svg
+    :target: https://pypi.org/project/django-postgres-denormalize/
+    :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/django-postgres-denormalize/actions/workflows/ci.yml/badge.svg
+    :target: https://github.com/djanquiltdb/django-postgres-denormalize/actions/workflows/ci.yml
+    :alt: CI
+
+.. image:: https://readthedocs.org/projects/django-postgres-denormalize/badge/?version=latest
+    :target: https://django-postgres-denormalize.readthedocs.io/
+    :alt: Documentation
+
+.. image:: https://img.shields.io/pypi/l/django-postgres-denormalize.svg
+    :target: https://github.com/djanquiltdb/django-postgres-denormalize/blob/master/LICENSE
+    :alt: BSD-3-Clause licence
+
+PostgreSQL cannot index, sort or constrain on a value that is stored in another table. A value that is several joins
+away, such as the tenant that a row belongs to through its parent, cannot be part of an index or a unique constraint on
+the row's table, and every query that filters or orders by it pays for the joins.
+
+This package lets a model store a copy of such a value in an ordinary column, and keeps the copy correct with
+PostgreSQL triggers. That works for every write, whether it comes from the ORM, a bulk update, raw SQL or the previous
+release that is still serving during a rolling deploy. The model declares the lookup path and nothing else;
+``makemigrations`` writes the column, the triggers and their changes.
+
+Full documentation is at https://django-postgres-denormalize.readthedocs.io/.
+
+.. code-block:: python
+
+    from django.db import models
+    from postgres_denormalize.fields import DenormalizedField, DenormalizedForeignKey
+
+
+    class Task(models.Model):
+        project = models.ForeignKey('Project', on_delete=models.CASCADE)
+        title = models.CharField(max_length=100)
+        # A copy of project.tenant: a real foreign key, its target and on_delete rule inferred from the path.
+        tenant = DenormalizedForeignKey('project__tenant')
+        # A copy of project.name: a column of the same type as the source.
+        project_name = DenormalizedField('project__name')
+
+        class Meta:
+            ordering = ['project_name', 'title']
+            constraints = [models.UniqueConstraint(fields=['tenant', 'title'], name='unique_task_title_per_tenant')]
+            indexes = [models.Index(fields=['tenant', 'project_name', 'title'], name='task_listing')]
+
+From then on, saving a task computes its copies in the database and reads them back onto the instance. Moving a
+project to another tenant, or renaming it, rewrites the copies of its tasks in the same transaction, but only the
+copies that change.
+
+**Use it for** values that an index or a unique constraint needs, and values that most queries sort or filter by across
+several joins. **Do not use it** to save a join for rendering, because ``select_related`` does that for free. Do not use
+it either for values whose source is often updated in bulk by code that you cannot wrap in one of its batch helpers.
+See `when to use it, and when not to
+<https://django-postgres-denormalize.readthedocs.io/en/latest/getting_started/when_to_use.html>`_, and the
+`alternatives <https://django-postgres-denormalize.readthedocs.io/en/latest/getting_started/alternatives.html>`_ page,
+which compares it with django-pgconstraints and django-computedfields.
+
+Installation
+------------
+
+.. code-block:: bash
+
+    pip install django-postgres-denormalize
+
+.. code-block:: python
+
+    INSTALLED_APPS = [
+        # ...
+        'pgtrigger',
+        'postgres_denormalize',
+    ]
+
+Requires PostgreSQL and django-pgtrigger, with pgtrigger's migration support turned on (the default). See the
+`settings reference <https://django-postgres-denormalize.readthedocs.io/en/latest/reference/settings.html>`_ for the
+options.
+
+Relationship to DjanQuiltDB
+---------------------------
+
+While this library was written in conjunction with `DjanQuiltDB <https://github.com/djanquiltdb/djanquiltdb>`_ and the
+libraries were designed to work together seamlessly in projects where both are installed, both libraries are written to
+be used as standalone libraries as well. For using django-postgres-denormalize, it is not necessary to use or be
+familiar with DjanQuiltDB.
+
+If you wish to use DjanQuiltDB features for the copies that django-postgres-denormalize keeps, you can install the
+``djanquiltdb[postgres-denormalize]`` extra. For more information, please refer to the DjanQuiltDB documentation.

django_postgres_denormalize-1.0.0.dist-info/RECORD

@@ -0,0 +1,15 @@
+django_postgres_denormalize-1.0.0.dist-info/licenses/LICENSE,sha256=SjqLhDqFqtKwwJqhC-80QG9cPUmuTv3yBPEp67_7dQE,1505
+postgres_denormalize/__init__.py,sha256=h2Exolqdz_lWkfG9CHR4v_pgUk8OET-deYTLt8WPm2E,2112
+postgres_denormalize/apps.py,sha256=5NMFH3Cw5bO7CmTApEChIMPpRV_8gDZCVFKh0hYW-qE,886
+postgres_denormalize/batch.py,sha256=bde0VQ3vwPz1ot_cs4sguZgt336mjoZrDcfeWj27i3M,7100
+postgres_denormalize/chains.py,sha256=d97jiCI4QO7bin3neRBsG5F_ONeTPARqt8vGSeZhO3M,5215
+postgres_denormalize/checks.py,sha256=tmH3JEA7MqYEM6Xaws9tJYqDDhjELUQoZpyFPDDd5KI,17574
+postgres_denormalize/conf.py,sha256=qK3mZb4bZeglKBqHcSp9A8Kz9eg1xOkdf3SJoasaqPM,7198
+postgres_denormalize/fields.py,sha256=aNDsle6S7V1EBVbepxeCwBMIdKFhll09nLiEHG3N-bw,34954
+postgres_denormalize/operations.py,sha256=2yMu-ejpM5d01NfZCegh28XzraN5wzoAjsf_52FulwI,7830
+postgres_denormalize/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+postgres_denormalize/triggers.py,sha256=tQLe7deabYCRQYaxoUeB3BxpzhJ51M6lD3Ky5ebWKrM,28882
+django_postgres_denormalize-1.0.0.dist-info/METADATA,sha256=c2VVsjfFS9xXZn-wOftycEhmSOqM-HRg6W_qpyY0Lvs,7417
+django_postgres_denormalize-1.0.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+django_postgres_denormalize-1.0.0.dist-info/top_level.txt,sha256=TiY8OQ1hfNrDOlg2pMMaoE5kfdktfvuUiFDk5rz5pAM,21
+django_postgres_denormalize-1.0.0.dist-info/RECORD,,

django_postgres_denormalize-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
+

django_postgres_denormalize-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.

django_postgres_denormalize-1.0.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+postgres_denormalize

postgres_denormalize/__init__.py

@@ -0,0 +1,36 @@
+"""
+Columns that store a copy of a value at the end of a chain of foreign keys, kept equal to it by PostgreSQL triggers.
+
+Terms that are used throughout this package:
+
+- A *denormalized field* is a ``DenormalizedForeignKey``, which copies a foreign key, or a ``DenormalizedField``, which
+  copies any other column. The model that declares it is the *leaf*.
+- The field's ``denormalize_from`` is a *lookup path* such as ``'project__tenant'`` or ``'project__name'``: a chain of
+  forward foreign keys that starts on the leaf. It ends at the column whose value the field copies, which is the
+  *source column*.
+- Each foreign key along the lookup path is a *hop*. The first hop is a column of the leaf itself. The model that has a
+  later hop, or the source column, is the *owner* of that segment.
+
+A model declares the field and nothing else::
+
+    class Task(models.Model):
+        project = models.ForeignKey(Project, on_delete=models.CASCADE)
+        tenant = DenormalizedForeignKey('project__tenant', on_delete=models.CASCADE)
+        project_name = DenormalizedField('project__name')
+
+The package has these modules:
+
+- ``chains`` walks a lookup path.
+- ``fields`` has both kinds of denormalized field, and the helpers that find a model's denormalized fields and compare
+  their stored values with their lookup paths.
+- ``triggers`` has the triggers that keep every denormalized field correct, and the registration that derives them from
+  the fields while ``PostgresDenormalizeConfig.ready()`` runs.
+- ``operations`` has ``BackfillDenormalized``, the migration operation that corrects stored values before a migration
+  installs or changes the triggers.
+- ``batch`` has ``ignore_cascades`` and ``defer_cascades``, which skip the cascade triggers during a batch update and
+  correct the copies in one set-based pass when the batch ends. Inside the block, those copies are out of date.
+- ``checks`` has the system checks. ``conf`` has the ``POSTGRES_DENORMALIZE`` setting, including ``EXCLUDE_MODELS``
+  and ``EXCLUDE_MODELS_CALLBACK``, which name the models that this package skips.
+"""
+
+__version__ = '1.0.0'

postgres_denormalize/apps.py

@@ -0,0 +1,18 @@
+from django.apps import AppConfig
+
+
+class PostgresDenormalizeConfig(AppConfig):
+    name = 'postgres_denormalize'
+    verbose_name = 'PostgreSQL denormalize'
+
+    def ready(self):
+        from postgres_denormalize import checks, conf  # noqa: F401 -- importing checks registers them.
+        from postgres_denormalize.fields import resolve_denormalized_fields
+        from postgres_denormalize.triggers import register_triggers
+
+        conf.validate_settings()
+        # Every model is loaded by the time any AppConfig.ready() runs, so every lookup path resolves here. The column
+        # type of each DenormalizedField is inferred first, because Django reads `null` when it builds queries. Then the
+        # triggers are derived from the fields and registered with pgtrigger, which adds them to the migration state.
+        resolve_denormalized_fields()
+        register_triggers()

postgres_denormalize/batch.py

@@ -0,0 +1,130 @@
+"""
+Context managers for batch updates of the models that a lookup path crosses. They skip the cascade triggers of those
+models and correct the copies below them in one set-based pass.
+
+A cascade trigger is row-level. A statement that changes a copied column on *N* rows of an owner therefore runs the
+trigger *N* times, and each run is an indexed UPDATE of the leaf rows below one row. Both context managers skip the
+cascade triggers on the tables of the named owners. When the block ends, they run ``backfill_denormalized`` for each
+leaf that those triggers serve: one UPDATE per denormalized field, which corrects every leaf row that differs from its
+lookup path. The block and the correction run in one transaction, so no other transaction sees out-of-date copies. The
+block itself does see them: until it ends, every copy below a row that the batch changed has its old value. A query in
+the block that reads or filters on such a copy gets a wrong answer, and saving a leaf row in the block does not correct
+the row, because the save writes the old copy back unchanged.
+
+The two context managers skip the triggers in different ways:
+
+- ``ignore_cascades`` uses ``pgtrigger.ignore``. It works with any ``DEFERRABLE_CASCADES`` value, but Postgres still
+  calls each trigger function once per changed row, and the function returns at once. It skips the triggers only for
+  queries that Django sends from the current thread. A statement that is sent through another connection still runs the
+  cascade triggers.
+- ``defer_cascades`` lists the triggers in a transaction-local Postgres setting that their WHEN condition reads, so
+  Postgres does not call the function at all. It skips the triggers for every statement in the transaction, including
+  raw SQL. It needs ``DEFERRABLE_CASCADES``, which is on by default.
+
+Neither makes the work on the leaf's side cheaper. The correction reads every row of each leaf to find the rows that
+differ, and every row that it rewrites runs the leaf's ``denormalize_set`` trigger, because the UPDATE writes a copy.
+Both save the per-row work on the owner's side. That work dominates when a batch changes many owner rows that each have
+few leaf rows below them.
+"""
+
+import contextlib
+
+import pgtrigger
+from django.core.exceptions import ImproperlyConfigured
+from django.db import connections, router, transaction
+
+from postgres_denormalize import conf
+from postgres_denormalize.operations import backfill_denormalized
+from postgres_denormalize.triggers import DEFERRED_CASCADES_SETTING, cascade_triggers_on
+
+
+def _find_cascade_triggers(owners, using):
+    """
+    Return the ``(owner, leaf, trigger)`` triples of the cascade triggers on ``owners``, and the database to use.
+    """
+    if not owners:
+        raise TypeError('Name at least one model whose rows the batch updates.')
+    found = cascade_triggers_on(owners)
+    return found, using or router.db_for_write(found[0][0])
+
+
+def _correct_leaves(found, using):
+    """
+    Correct the copies of every leaf that the triggers in ``found`` serve, each leaf once, in label order.
+    """
+    leaves = {leaf._meta.label: leaf for _owner, leaf, _trigger in found}
+    for label in sorted(leaves):
+        backfill_denormalized(leaves[label], using=using)
+
+
+@contextlib.contextmanager
+def ignore_cascades(*owners, using=None):
+    """
+    Skip the cascade triggers on ``owners`` for the queries that Django sends inside the block, through
+    ``pgtrigger.ignore``, and correct the copies below them when the block ends.
+
+    The block runs in a transaction, or in a savepoint inside one, on ``using``. By default, that is the database that
+    the router chooses for writing the first model in ``owners``. If the block raises, the transaction rolls back and
+    nothing is corrected::
+
+        with ignore_cascades(Project):
+            Project.objects.filter(tenant=old).update(tenant=new)
+
+    .. warning::
+
+        Until the block ends, every copy below a row that the batch changed has its old value. A query in the block that
+        reads or filters on such a copy gets a wrong answer, and saving a leaf row in the block does not correct it. See
+        :doc:`/guides/batch_updates`.
+    """
+    found, using = _find_cascade_triggers(owners, using)
+    with transaction.atomic(using=using):
+        with pgtrigger.ignore(*(trigger.get_uri(owner) for owner, _leaf, trigger in found), databases=[using]):
+            # pgtrigger.ignore runs a query to clear its setting when it ends. The savepoint first rolls back a database
+            # error that the block raises, so that this query does not fail on an aborted transaction and hide the
+            # error.
+            with transaction.atomic(using=using):
+                yield
+        _correct_leaves(found, using)
+
+
+@contextlib.contextmanager
+def defer_cascades(*owners, using=None):
+    """
+    Skip the cascade triggers on ``owners`` for every statement inside the block, through their WHEN condition, and
+    correct the copies below them when the block ends.
+
+    This needs ``DEFERRABLE_CASCADES``, and raises ``ImproperlyConfigured`` when it is off. ``ignore_cascades`` works
+    with either value. The block runs in a transaction on ``using``, as in ``ignore_cascades``. The triggers are listed
+    in ``DEFERRED_CASCADES_SETTING`` with ``set_config(..., true)``, and a rollback undoes that together with the rest
+    of the block. A nested block adds its triggers to the listed ones and restores the list when it ends. At that point
+    it corrects its own leaves. The outer block corrects its leaves when it ends, so a leaf that both blocks serve is
+    read twice.
+
+    .. warning::
+
+        Until the block ends, every copy below a row that the batch changed has its old value. A query in the block that
+        reads or filters on such a copy gets a wrong answer, and saving a leaf row in the block does not correct it. See
+        :doc:`/guides/batch_updates`.
+    """
+    if not conf.get_setting('DEFERRABLE_CASCADES'):
+        raise ImproperlyConfigured(
+            f'defer_cascades() needs {conf.SETTING_NAME}["DEFERRABLE_CASCADES"], which is off, so the cascade triggers '
+            f'cannot be skipped through their WHEN condition. Use ignore_cascades() instead.'
+        )
+    found, using = _find_cascade_triggers(owners, using)
+    with transaction.atomic(using=using):
+        with connections[using].cursor() as cursor:
+            cursor.execute('SELECT current_setting(%s, true)', [DEFERRED_CASCADES_SETTING])
+            previous = cursor.fetchone()[0] or ''
+            listed = [pgid for pgid in previous.split(',') if pgid]
+            listed.extend(trigger.get_pgid(owner) for owner, _leaf, trigger in found)
+            cursor.execute(
+                'SELECT set_config(%s, %s, true)', [DEFERRED_CASCADES_SETTING, ','.join(dict.fromkeys(listed))]
+            )
+        yield
+        with connections[using].cursor() as cursor:
+            cursor.execute('SELECT set_config(%s, %s, true)', [DEFERRED_CASCADES_SETTING, previous])
+        _correct_leaves(found, using)
+
+
+__all__ = ['defer_cascades', 'ignore_cascades']

postgres_denormalize/chains.py

@@ -0,0 +1,121 @@
+"""
+Walking a lookup path through a model's foreign keys, which both ``fields`` and ``triggers`` need.
+"""
+
+
+class PathRefused(ValueError):
+    """
+    A lookup path that names only fields that exist, but crosses a field that no lookup path may cross. ``code`` is the
+    id of the system check that reports it, and ``hint`` names the path to use instead.
+    """
+
+    def __init__(self, message, *, code, hint):
+        super().__init__(message)
+        self.code = code
+        self.hint = hint
+
+
+def is_forward_hop(field):
+    """
+    Say whether ``field`` is a hop that a lookup path can cross: a concrete foreign key or one-to-one field, which
+    leads to exactly one row.
+    """
+    return field.concrete and (field.many_to_one or field.one_to_one)
+
+
+def refuse_hop(model, field, path, position):
+    """
+    Raise ``PathRefused`` when the segment of ``path`` at ``position``, which names ``field`` on ``model``, is a field
+    that no lookup path may cross or end at.
+
+    A denormalized field is refused, because its own value comes from a trigger. A path through it would need that
+    trigger to run before the trigger of the path, and a ``DenormalizedForeignKey`` along the path may not have its
+    target yet. The hint names the path that the copy itself walks.
+
+    A field that ``model`` inherits from a concrete parent is refused, because its column is in the parent's table and
+    not in the table of ``model``. The hint names the path through the parent links.
+    """
+    segments = path.split('__')
+    copied = getattr(field, 'denormalize_from', None)
+    if copied is not None:
+        suggestion = '__'.join([*segments[:position], copied, *segments[position + 1 :]])
+        raise PathRefused(
+            f'`{path}` crosses `{field.name}`, which is itself a copy of `{copied}`',
+            code='postgres_denormalize.E006',
+            hint=f"Copy from '{suggestion}' instead.",
+        )
+    if field.model._meta.concrete_model is not model._meta.concrete_model:
+        suggestion = '__'.join([*segments[:position], *parent_link_names(model, field.model), *segments[position:]])
+        raise PathRefused(
+            f'`{path}` crosses `{field.name}`, which {model._meta.label} inherits from {field.model._meta.label}, '
+            f'so the column is in the table of {field.model._meta.label}',
+            code='postgres_denormalize.E007',
+            hint=f"Copy from '{suggestion}' instead.",
+        )
+
+
+def can_cross(model, field):
+    """
+    Say whether a lookup path from ``model`` may cross ``field`` as a hop: ``is_forward_hop`` accepts it, and
+    ``refuse_hop`` does not refuse it.
+    """
+    if not is_forward_hop(field):
+        return False
+    try:
+        refuse_hop(model, field, field.name, 0)
+    except PathRefused:
+        return False
+    return True
+
+
+def parent_link_names(model, ancestor):
+    """
+    Return the names of the parent links that lead from ``model`` to its concrete parent ``ancestor``.
+    """
+    names = []
+    while model._meta.concrete_model is not ancestor._meta.concrete_model:
+        link = model._meta.get_ancestor_link(ancestor)
+        names.append(link.name)
+        model = link.related_model
+    return names
+
+
+def resolve_chain(model, path, allow_column_terminal=False):
+    """
+    Walk a lookup path from ``model`` and return the field that each segment names, starting with the first hop.
+
+    Every segment except the last must be a hop that ``is_forward_hop`` accepts. The last segment must be one too,
+    unless ``allow_column_terminal`` is set. In that case, it may also be a concrete column that is not a relation: the
+    column that a ``DenormalizedField`` copies.
+
+    Raises ``FieldDoesNotExist`` if a segment names no field on the model that it is resolved against. Raises
+    ``ValueError`` if a segment names a field that the walk cannot cross: a reverse accessor, a many-to-many, or a plain
+    column anywhere except at the end. Walking one of those yields either a set of rows or no row at all, and the
+    trigger needs exactly one value to copy. Raises ``PathRefused``, which is a ``ValueError``, for the fields that
+    ``refuse_hop`` refuses.
+    """
+    segments = path.split('__')
+    chain = []
+    current = model
+    for position, segment in enumerate(segments):
+        field = current._meta.get_field(segment)
+        is_last = position == len(segments) - 1
+        if is_forward_hop(field):
+            refuse_hop(current, field, path, position)
+            if isinstance(field.related_model, str):
+                raise ValueError(
+                    f'`{path}` traverses `{segment}`, which points at {field.related_model}, '
+                    'a model that is not installed'
+                )
+            chain.append(field)
+            current = field.related_model
+            continue
+        if is_last and allow_column_terminal and field.concrete and not field.is_relation:
+            refuse_hop(current, field, path, position)
+            chain.append(field)
+            continue
+        raise ValueError(f'`{path}` traverses `{segment}`, which is not a forward foreign key')
+    return chain
+
+
+__all__ = ['PathRefused', 'can_cross', 'is_forward_hop', 'refuse_hop', 'resolve_chain']