django-overlay 0.1.0__tar.gz

django_overlay-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,47 @@
+name: Publish
+
+on:
+  push:
+    branches:
+      - master
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write
+
+    steps:
+      - uses: actions/checkout@v3
+
+      - name: Set up Python
+        uses: actions/setup-python@v4
+        with:
+          python-version: '3.12'
+
+      - name: Install build tools
+        run: |
+          python -m pip install --upgrade pip setuptools wheel build
+
+      - name: Check if version changed
+        id: check_version
+        run: |
+          LOCAL_VERSION=$(python -c "import tomllib; print(tomllib.load(open('pyproject.toml', 'rb'))['project']['version'])")
+          PUBLISHED_VERSION=$(curl -s -f https://pypi.org/pypi/django-overlay/json | python -c "import json, sys; print(json.load(sys.stdin).get('info', {}).get('version', ''))" || echo "")
+          echo "Local version: $LOCAL_VERSION, published version: $PUBLISHED_VERSION"
+          if [ "$LOCAL_VERSION" = "$PUBLISHED_VERSION" ]; then
+            echo "should_publish=false" >> "$GITHUB_OUTPUT"
+          else
+            echo "should_publish=true" >> "$GITHUB_OUTPUT"
+          fi
+
+      - name: Build package
+        if: steps.check_version.outputs.should_publish == 'true'
+        run: |
+          python -m build
+
+      - name: Publish to PyPI
+        if: steps.check_version.outputs.should_publish == 'true'
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          packages-dir: dist

django_overlay-0.1.0/.github/workflows/tests.yml

@@ -0,0 +1,64 @@
+name: Tests
+
+on:
+  push:
+    branches:
+      - master
+  pull_request:
+    branches:
+      - master
+
+jobs:
+  test:
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ['3.11', '3.12', '3.13', '3.14']
+        os-version: [ubuntu-22.04]
+
+    runs-on: ${{ matrix.os-version }}
+
+    services:
+      postgres:
+        image: postgres:16
+        env:
+          POSTGRES_USER: postgres
+          POSTGRES_PASSWORD: postgres
+          POSTGRES_DB: django_overlay_test
+        ports:
+          - 5432:5432
+        options: >-
+          --health-cmd pg_isready
+          --health-interval 10s
+          --health-timeout 5s
+          --health-retries 5
+
+    env:
+      POSTGRES_HOST: localhost
+      POSTGRES_PORT: 5432
+      POSTGRES_USER: postgres
+      POSTGRES_PASSWORD: postgres
+      POSTGRES_DB: django_overlay_test
+      POSTGRES_TENANTS_DB: django_overlay_tenants_test
+
+    steps:
+      - uses: actions/checkout@v3
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v3
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: |
+          uv sync
+
+      - name: Run tests with coverage
+        run: |
+          uv run pytest --cov=django_overlay --cov-report=term-missing
+
+      - name: Run multi-tenant tests
+        env:
+          DJANGO_SETTINGS_MODULE: tests.django_tenants_settings
+        run: |
+          uv run pytest tests/test_tenants -o addopts="" --create-db

django_overlay-0.1.0/.gitignore

@@ -0,0 +1,21 @@
+# Python
+__pycache__
+*.pyc
+.pytest_cache
+.ruff_cache
+.coverage
+htmlcov
+.hypothesis
+
+# IDEs & Editors
+.idea
+
+# Frameworks & Libraries
+dist
+poetry.lock
+
+# venv
+.venv
+
+# Project Specific
+# ETC

django_overlay-0.1.0/.pre-commit-config.yaml

@@ -0,0 +1,23 @@
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v5.0.0
+    hooks:
+      - id: end-of-file-fixer
+      - id: trailing-whitespace
+      - id: check-yaml
+      - id: check-added-large-files
+
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.9.0
+    hooks:
+      - id: ruff
+        args: [ --fix ]
+      - id: ruff-format
+
+  - repo: https://github.com/sqlfluff/sqlfluff
+    rev: 4.2.2
+    hooks:
+      - id: sqlfluff-lint
+        files: \.sql\.j2$
+        types: [text]
+        additional_dependencies: ["jinja2"]

django_overlay-0.1.0/.sqlfluff

@@ -0,0 +1,28 @@
+[sqlfluff]
+dialect = postgres
+templater = jinja
+max_line_length = 120
+library_path = sqlfluff_libs
+# AM04: ambiguous column count in a SELECT * (n/a, we always name columns).
+# LT02/LT03/LT05/LT14/CV06/CV07/CP01: pure layout/formatting rules that
+# fight the compact-but-valid whitespace real Jinja for-loops produce
+# (e.g. a comma-joined column list rendered on one line). These templates'
+# actual SQL correctness is verified empirically by the test suite
+# executing every one of them against real Postgres, not by sqlfluff.
+exclude_rules = AM04, LT02, LT03, LT05, LT14, CV06, CV07, CP01
+
+[sqlfluff:templater:jinja:context]
+tenant_schema = public
+view_name = person_view
+base_table = person
+function_name = person_view_instead_of_update
+pk_column = id
+pk_default_expr = nextval('"public"."person_id_seq"')
+columns = ["id", "first_name", "age"]
+trigger_name = overlayfk_note_person_id
+referencing_table = note
+column = person_id
+table_name = note
+negate = True
+source = {"schema": "public", "table": "personsource", "id_column": "id", "extra_where": "", "negate": True}
+target_tables = [{"schema": "public", "table": "person", "id_column": "id", "negate": False}, {"schema": "public", "table": "personsource", "id_column": "id", "negate": True}]

django_overlay-0.1.0/.sqlfluffignore

@@ -0,0 +1,4 @@
+# Bare SQL expressions (not full statements) spliced into a larger
+# statement elsewhere — there's no standalone statement here for sqlfluff
+# to parse on its own.
+django_overlay/sql_templates/pk_defaults/

django_overlay-0.1.0/INDEX.md

@@ -0,0 +1 @@
+docs/INDEX.md

django_overlay-0.1.0/LICENCE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Işık Kaplan
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

django_overlay-0.1.0/PKG-INFO

@@ -0,0 +1,59 @@
+Metadata-Version: 2.4
+Name: django-overlay
+Version: 0.1.0
+Summary: Writable Django models layered over read-only, shared source tables — one view, no coalescing at read time.
+Project-URL: Homepage, https://github.com/isik-kaplan/django-overlay
+Project-URL: Repository, https://github.com/isik-kaplan/django-overlay
+Author-email: Işık Kaplan <isik.kaplan@outlook.com>
+License: MIT
+License-File: LICENCE
+Keywords: django,multi-tenant,postgres,views
+Classifier: Framework :: Django
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development
+Requires-Python: >=3.11
+Requires-Dist: django>=4.2
+Requires-Dist: jinja2>=3.1.0
+Description-Content-Type: text/markdown
+
+# django-overlay
+
+A writable Django model layered on top of a read-only table you don't own —
+one model to query, no `COALESCE`/`FULL OUTER JOIN` at read time.
+
+## The problem
+
+You have a big shared read-only table (a vendor import, a third-party
+dataset) and a small table of tenant edits on top of it. You want one Django model to
+query, writes landing only in your own table, an edit that copies the row
+over on first touch, and a foreign key that can still point at it even
+though Postgres can't put a real FK on a view.
+
+This is [OverlayFS](https://docs.kernel.org/filesystems/overlayfs.html)
+applied to Postgres: a writable "upper" table merged with one read-only
+"lower" table into one "merged" view. Each overlay model has exactly one
+source table, though which physical table that is can be resolved per
+tenant — a single, tenant-scoped source, not a union of several.
+
+```python
+from django.db import models
+
+from django_overlay.models import OverlayMeta, OverlayModel
+from django_overlay.sources import SourceTable
+
+
+class Person(OverlayModel):
+    first_name = models.CharField(max_length=100)
+
+    class OverlayMeta(OverlayMeta):
+        @staticmethod
+        def get_source():
+            return SourceTable(schema="external_source", table="people")
+
+
+Person.objects.create(first_name="Jane")  # goes straight into the writable table
+```
+
+See [docs/INDEX.md](docs/INDEX.md) for everything else — usage, how it
+works, ids, uniqueness, deletion, migrations, and running the tests.

django_overlay-0.1.0/README.md

@@ -0,0 +1,40 @@
+# django-overlay
+
+A writable Django model layered on top of a read-only table you don't own —
+one model to query, no `COALESCE`/`FULL OUTER JOIN` at read time.
+
+## The problem
+
+You have a big shared read-only table (a vendor import, a third-party
+dataset) and a small table of tenant edits on top of it. You want one Django model to
+query, writes landing only in your own table, an edit that copies the row
+over on first touch, and a foreign key that can still point at it even
+though Postgres can't put a real FK on a view.
+
+This is [OverlayFS](https://docs.kernel.org/filesystems/overlayfs.html)
+applied to Postgres: a writable "upper" table merged with one read-only
+"lower" table into one "merged" view. Each overlay model has exactly one
+source table, though which physical table that is can be resolved per
+tenant — a single, tenant-scoped source, not a union of several.
+
+```python
+from django.db import models
+
+from django_overlay.models import OverlayMeta, OverlayModel
+from django_overlay.sources import SourceTable
+
+
+class Person(OverlayModel):
+    first_name = models.CharField(max_length=100)
+
+    class OverlayMeta(OverlayMeta):
+        @staticmethod
+        def get_source():
+            return SourceTable(schema="external_source", table="people")
+
+
+Person.objects.create(first_name="Jane")  # goes straight into the writable table
+```
+
+See [docs/INDEX.md](docs/INDEX.md) for everything else — usage, how it
+works, ids, uniqueness, deletion, migrations, and running the tests.

django_overlay-0.1.0/django_overlay/_templating.py

@@ -0,0 +1,22 @@
+"""Shared Jinja env for sql_templates/. Split out of sql.py so
+strategies.py can render templates too without a circular import."""
+
+import jinja2
+
+
+def _qi(name: str) -> str:
+    """Jinja filter: quote a Postgres identifier, e.g. reserved words like `order`."""
+    return '"' + name.replace('"', '""') + '"'
+
+
+_ENV = jinja2.Environment(
+    loader=jinja2.PackageLoader("django_overlay", "sql_templates"),
+    autoescape=False,
+    trim_blocks=True,
+    lstrip_blocks=True,
+)
+_ENV.filters["qi"] = _qi
+
+
+def render(template_name: str, **context) -> str:
+    return _ENV.get_template(template_name).render(**context).strip()

django_overlay-0.1.0/django_overlay/apps.py

@@ -0,0 +1,20 @@
+from django.apps import AppConfig
+from django.core.exceptions import ImproperlyConfigured
+
+
+class DjangoOverlayConfig(AppConfig):
+    name = "django_overlay"
+    verbose_name = "Django Overlay"
+    default_auto_field = "django.db.models.AutoField"
+
+    def ready(self):
+        from . import checks  # also registers the manage.py check
+
+        # Runs on every process boot, not just `manage.py check` — a bad
+        # FK/M2M against an overlay model should fail loudly right away.
+        errors = checks.check_no_plain_fk_to_overlay_models(None)
+        if errors:
+            raise ImproperlyConfigured(
+                "django_overlay found unsafe references to overlay view models:\n"
+                + "\n".join(f"{error.id}: {error.msg}" for error in errors)
+            )

django_overlay-0.1.0/django_overlay/checks.py

@@ -0,0 +1,59 @@
+from django.apps import apps
+from django.core import checks
+from django.db import models
+
+from .fields import OverlayForeignKey
+
+
+@checks.register(checks.Tags.models)
+def check_no_plain_fk_to_overlay_models(app_configs, **kwargs):
+    """Fails `manage.py check` for a plain ForeignKey/OneToOneField
+    pointing at an OverlayModel, or a ManyToManyField pointing at one
+    without an explicit through= model."""
+    errors = []
+    for model in apps.get_models(include_auto_created=True):
+        for field in model._meta.get_fields():
+            if not field.is_relation:
+                continue
+            related_model = field.related_model
+            if related_model is None or not getattr(related_model, "_is_overlay_view_model", False):
+                continue
+
+            # M2M fields are never "concrete" (even the declaring side), so
+            # check the type directly instead.
+            if isinstance(field, models.ManyToManyField):
+                if not field.remote_field.through._meta.auto_created:
+                    continue
+                errors.append(
+                    checks.Error(
+                        f"{model.__name__}.{field.name} is a plain ManyToManyField pointing at "
+                        f"{related_model.__name__}, which is a django_overlay view model. Django's "
+                        "auto-created through table would use a plain ForeignKey, which can't hold "
+                        "a real FK constraint against a view.",
+                        hint="Use django_overlay.fields.OverlayManyToManyField (through=... is "
+                        "required) or write your own explicit through model with OverlayForeignKey "
+                        "fields.",
+                        obj=field,
+                        id="django_overlay.E002",
+                    )
+                )
+                continue
+
+            # Every concrete, non-M2M relation field Django has is a
+            # ForeignKey or OneToOneField (or a subclass), so this is
+            # already effectively "is a plain FK/O2O".
+            if not getattr(field, "concrete", False):
+                continue
+            if isinstance(field, OverlayForeignKey):
+                continue
+            errors.append(
+                checks.Error(
+                    f"{model.__name__}.{field.name} is a plain {type(field).__name__} pointing at "
+                    f"{related_model.__name__}, which is a django_overlay view model. Postgres cannot "
+                    f"hold a real FK constraint against a view.",
+                    hint=f"Use django_overlay.fields.OverlayForeignKey instead of {type(field).__name__}.",
+                    obj=field,
+                    id="django_overlay.E001",
+                )
+            )
+    return errors

django_overlay-0.1.0/django_overlay/constraints.py

@@ -0,0 +1,18 @@
+from django.db import models
+
+from .models import OverlayConfigurationError
+
+
+class OverlayUniqueConstraint(models.UniqueConstraint):
+    """Also guards against a value already present in the source table.
+    Postgres can't enforce that across a view's UNION ALL, so that half is
+    a trigger instead (see AddOverlayUniqueConstraint)."""
+
+    def __init__(self, *args, **kwargs):
+        if kwargs.get("condition") is not None:
+            raise OverlayConfigurationError(
+                "OverlayUniqueConstraint doesn't support condition= — the source-vs-base trigger "
+                "has no way to apply it, so it would silently check for collisions the condition "
+                "should have excluded."
+            )
+        super().__init__(*args, **kwargs)

django_overlay-0.1.0/django_overlay/fields.py

@@ -0,0 +1,76 @@
+from django.db import models
+
+from .models import OverlayConfigurationError
+from .strategies import negates_source_ids
+
+
+class OverlayForeignKey(models.ForeignKey):
+    """FK for pointing at an OverlayModel. Postgres can't hold a real FK
+    against a view, so this never creates a db constraint; referential
+    integrity instead comes from a constraint trigger (see
+    operations.AddOverlayConstraint)."""
+
+    def __init__(self, to, *args, **kwargs):
+        if "db_constraint" in kwargs:
+            raise OverlayConfigurationError(
+                "OverlayForeignKey always sets db_constraint=False (Postgres can't hold a real FK "
+                "against a view) — don't pass db_constraint yourself."
+            )
+        kwargs["db_constraint"] = False
+        super().__init__(to, *args, **kwargs)
+
+    def deconstruct(self):
+        name, path, args, kwargs = super().deconstruct()
+        kwargs.pop("db_constraint", None)
+        return name, path, args, kwargs
+
+    def trigger_name(self, model) -> str:
+        return f"overlayfk_{model._meta.db_table}_{self.column}"[:63]
+
+    def target_tables(self, tenant_schema: str) -> list[dict]:
+        """The target's base table plus its source, if any — see target_tables_for()."""
+        return target_tables_for(self.remote_field.model, tenant_schema)
+
+
+def target_tables_for(target, tenant_schema: str) -> list[dict]:
+    """[{"schema", "table", "id_column", "negate", "soft_delete"}, ...] for
+    `target`'s base table (never negated) plus its source, if any (negated
+    for a NEGATIVE_ID target). Takes the target model directly, not `self`, so a
+    migration operation can call it against a *live* model even when the
+    referencing field only exists in migration-historical state."""
+    tables = [
+        {
+            "schema": tenant_schema,
+            "table": target._base_model._meta.db_table,
+            "id_column": "id",
+            "negate": False,
+            "soft_delete": target._overlay_meta.soft_delete,
+        }
+    ]
+    source = target.get_source()
+    if source is not None:
+        negate = negates_source_ids(target._overlay_meta.strategy)
+        tables.append(
+            {
+                "schema": source.schema,
+                "table": source.table,
+                "id_column": source.id_column,
+                "negate": negate,
+                "soft_delete": False,
+            }
+        )
+    return tables
+
+
+class OverlayOneToOneField(OverlayForeignKey, models.OneToOneField):
+    pass
+
+
+class OverlayManyToManyField(models.ManyToManyField):
+    """M2M field for relating to an OverlayModel. Requires an explicit
+    through= model with OverlayForeignKey fields — Django's auto-created
+    through table always uses a plain ForeignKey, which can never be safe
+    against a view."""
+
+    def __init__(self, to, *args, through, **kwargs):
+        super().__init__(to, *args, through=through, **kwargs)