Localizations

.github/FUNDING.yml

@@ -0,0 +1 @@
+buy_me_a_coffee: mpasternak

.github/workflows/docs.yaml

@@ -0,0 +1,33 @@
+name: Deploy docs
+
+# Builds the MkDocs site and publishes it to the `gh-pages` branch on every
+# push to master. Enable GitHub Pages once (Settings -> Pages -> Build and
+# deployment -> Deploy from a branch -> gh-pages / root) for it to go live at
+# https://iplweb.github.io/djangoql-iplweb/
+on:
+  push:
+    branches: [master]
+  workflow_dispatch:
+
+permissions:
+  contents: write  # mkdocs gh-deploy pushes the built site to gh-pages
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0  # full history so gh-deploy can update gh-pages
+      - name: Install uv
+        uses: astral-sh/setup-uv@f94ec6bedd8674c4426838e6b50417d36b6ab231 # v5.3.1
+      - name: Set up Python
+        run: uv python install 3.12
+      - name: Install dependencies
+        run: uv sync --all-extras
+      - name: Configure git identity
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+      - name: Build and deploy to GitHub Pages
+        run: uv run mkdocs gh-deploy --force --no-history

.github/workflows/tests.yaml

@@ -5,201 +5,93 @@ on:
   pull_request:
     branches: [master]
   workflow_dispatch:
-jobs:
-  notify-build-start:
-    # Secrets are not available for forks for security reasons, so pull
-    # request checks will fail when trying to send the Slack notification.
-    # Unfortunately, there's no way to explicitly check that a secret is
-    # available, so we check for event_name instead:
-    # https://github.com/actions/runner/issues/520
-    if: ${{ github.event_name == 'push' }}
-    runs-on: ubuntu-latest
-    steps:
-      # Send build notifications to Slack
-      - uses: ivelum/github-action-slack-notify-build@v1.7.2
-        id: slack
-        with:
-          channel_id: C0PT3267R
-          status: STARTED
-          color: '#ee9b00'
-        env:
-          SLACK_BOT_TOKEN: ${{ secrets.SLACK_BOT_TOKEN }}
-    outputs:
-      status_message_id: ${{ steps.slack.outputs.message_id }}
 
+# Minimal default token scope; tests only need to read the repo.
+permissions:
+  contents: read
+
+jobs:
   lint:
-    needs: [notify-build-start]
-    if: |
-      always() &&
-      (needs.notify-build-start.result == 'success' || needs.notify-build-start.result == 'skipped')
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
-      - uses: actions/setup-python@v5
-        with:
-          python-version: 3.9
-      - name: get pip cache dir
-        id: pip-cache
-        run: echo "dir=$(pip cache dir)" >> $GITHUB_OUTPUT
-      - name: cache pip
-        uses: actions/cache@v4
-        with:
-          path: ${{ steps.pip-cache.outputs.dir }}
-          key: pip|lint
-      - run: pip install -r requirements-dev.txt
-      - run: flake8
-      - run: isort --diff -c .
-
-      # Send notification on build failure
-      - name: Notify slack fail
-        uses: ivelum/github-action-slack-notify-build@v1.7.2
-        if: failure() && github.event_name == 'push'
-        env:
-          SLACK_BOT_TOKEN: ${{ secrets.SLACK_BOT_TOKEN }}
-        with:
-          message_id: ${{ needs.notify-build-start.outputs.status_message_id }}
-          channel_id: C0PT3267R
-          status: FAILED
-          color: '#d7263d'
+      - name: Install uv
+        uses: astral-sh/setup-uv@f94ec6bedd8674c4426838e6b50417d36b6ab231 # v5.3.1
+      - name: Set up Python
+        run: uv python install 3.14
+      - name: Install dependencies
+        run: uv sync --all-extras
+      # Lint is informational only (|| true): the codebase is intentionally
+      # not bulk-formatted; enforcement happens in pre-commit on staged files.
+      - name: Lint with ruff
+        run: uv run ruff check . || true
+      - name: Check formatting with ruff
+        run: uv run ruff format --check . || true
 
   tests:
-    needs: [notify-build-start, lint]
-    if: |
-      always() &&
-      (needs.notify-build-start.result == 'success' || needs.notify-build-start.result == 'skipped') &&
-      needs.lint.result == 'success'
-    runs-on: ubuntu-${{ matrix.ubuntu }}
+    runs-on: ubuntu-latest
     strategy:
       fail-fast: false
       matrix:
+        # requires-python = ">=3.10"; only currently-supported Django series.
+        # Django 5.2 LTS: Python 3.10-3.14; Django 6.0: Python 3.12-3.14;
+        # Django 6.1: Python 3.12-3.14.
         include:
-          - {django: '1.8.*', python: '2.7', ubuntu: '22.04'}
-
-          - {django: '1.9.*', python: '2.7', ubuntu: '22.04'}
-
-          - {django: '1.10.*', python: '2.7', ubuntu: '22.04'}
-
-          - {django: '1.11.*', python: '2.7', ubuntu: '22.04'}
-          - {django: '1.11.*', python: '3.6', ubuntu: '22.04'}
-          - {django: '1.11.*', python: '3.7', ubuntu: '22.04'}
-
-          - {django: '2.0.*', python: '3.6', ubuntu: '22.04'}
-          - {django: '2.0.*', python: '3.7', ubuntu: '22.04'}
-
-          - {django: '2.1.*', python: '3.6', ubuntu: '22.04'}
-          - {django: '2.1.*', python: '3.7', ubuntu: '22.04'}
-
-          - {django: '2.2.*', python: '3.6', ubuntu: '22.04'}
-          - {django: '2.2.*', python: '3.7', ubuntu: '22.04'}
-          - {django: '2.2.*', python: '3.8', ubuntu: '24.04'}
-          - {django: '2.2.*', python: '3.9', ubuntu: '24.04'}
-
-          - {django: '3.0.*', python: '3.6', ubuntu: '22.04'}
-          - {django: '3.0.*', python: '3.7', ubuntu: '22.04'}
-          - {django: '3.0.*', python: '3.8', ubuntu: '24.04'}
-          - {django: '3.0.*', python: '3.9', ubuntu: '24.04'}
-
-          - {django: '3.1.*', python: '3.6', ubuntu: '22.04'}
-          - {django: '3.1.*', python: '3.7', ubuntu: '22.04'}
-          - {django: '3.1.*', python: '3.8', ubuntu: '24.04'}
-          - {django: '3.1.*', python: '3.9', ubuntu: '24.04'}
-
-          - {django: '3.2.*', python: '3.6', ubuntu: '22.04'}
-          - {django: '3.2.*', python: '3.7', ubuntu: '22.04'}
-          - {django: '3.2.*', python: '3.8', ubuntu: '24.04'}
-          - {django: '3.2.*', python: '3.9', ubuntu: '24.04'}
-          - {django: '3.2.*', python: '3.10', ubuntu: '24.04'}
-
-          - {django: '4.0.*', python: '3.8', ubuntu: '24.04'}
-          - {django: '4.0.*', python: '3.9', ubuntu: '24.04'}
-          - {django: '4.0.*', python: '3.10', ubuntu: '24.04'}
-
-          - {django: '4.1.*', python: '3.8', ubuntu: '24.04'}
-          - {django: '4.1.*', python: '3.9', ubuntu: '24.04'}
-          - {django: '4.1.*', python: '3.10', ubuntu: '24.04'}
-          - {django: '4.1.*', python: '3.11', ubuntu: '24.04'}
-
-          - {django: '4.2.*', python: '3.8', ubuntu: '24.04'}
-          - {django: '4.2.*', python: '3.9', ubuntu: '24.04'}
-          - {django: '4.2.*', python: '3.10', ubuntu: '24.04'}
-          - {django: '4.2.*', python: '3.11', ubuntu: '24.04'}
-          - {django: '4.2.*', python: '3.12', ubuntu: '24.04'}
-
-          - {django: '5.0.*', python: '3.10', ubuntu: '24.04'}
-          - {django: '5.0.*', python: '3.11', ubuntu: '24.04'}
-          - {django: '5.0.*', python: '3.12', ubuntu: '24.04'}
-
-          - {django: '5.1.*', python: '3.10', ubuntu: '24.04'}
-          - {django: '5.1.*', python: '3.11', ubuntu: '24.04'}
-          - {django: '5.1.*', python: '3.12', ubuntu: '24.04'}
-          - {django: '5.1.*', python: '3.13', ubuntu: '24.04'}
-
-          - {django: '5.2.*', python: '3.10', ubuntu: '24.04'}
-          - {django: '5.2.*', python: '3.11', ubuntu: '24.04'}
-          - {django: '5.2.*', python: '3.12', ubuntu: '24.04'}
-          - {django: '5.2.*', python: '3.13', ubuntu: '24.04'}
-          - {django: '5.2.*', python: '3.14', ubuntu: '24.04'}
-
-          - {django: '6.0.*', python: '3.12', ubuntu: '24.04'}
-          - {django: '6.0.*', python: '3.13', ubuntu: '24.04'}
-          - {django: '6.0.*', python: '3.14', ubuntu: '24.04'}
-
+          - {python-version: '3.10', django-version: '5.2'}
+          - {python-version: '3.11', django-version: '5.2'}
+          - {python-version: '3.12', django-version: '5.2'}
+          - {python-version: '3.13', django-version: '5.2'}
+          - {python-version: '3.14', django-version: '5.2'}
+          - {python-version: '3.12', django-version: '6.0'}
+          - {python-version: '3.13', django-version: '6.0'}
+          - {python-version: '3.14', django-version: '6.0'}
+          - {python-version: '3.12', django-version: '6.1'}
+          - {python-version: '3.13', django-version: '6.1'}
+          - {python-version: '3.14', django-version: '6.1'}
     steps:
       - uses: actions/checkout@v4
-      - name: Setup Python 3.7+
-        if: ${{ matrix.python != '2.7' && matrix.python != '3.6' }}
-        uses: actions/setup-python@v5
-        with:
-          python-version: ${{ matrix.python }}
-      - name: Setup Python 2.7/3.6
-        if: ${{ matrix.python == '2.7' || matrix.python == '3.6' }}
-        uses: MatteoH2O1999/setup-python@v2
-        with:
-          python-version: ${{ matrix.python }}
-          allow-build: info
-          cache-build: true
-      - name: update pip
+      - name: Install uv
+        uses: astral-sh/setup-uv@f94ec6bedd8674c4426838e6b50417d36b6ab231 # v5.3.1
+      - name: Set up Python ${{ matrix.python-version }}
+        run: uv python install ${{ matrix.python-version }}
+      - name: Install dependencies (project + Django ${{ matrix.django-version }})
         run: |
-          pip install -U wheel
-          pip install -U setuptools
-          python -m pip install -U pip
-      - name: get pip cache dir
-        id: pip-cache
-        run: echo "dir=$(pip cache dir)" >> $GITHUB_OUTPUT
-      - name: cache pip
-        uses: actions/cache@v4
-        with:
-          path: ${{ steps.pip-cache.outputs.dir }}
-          key: pip|${{ matrix.python }}|${{ matrix.django }}
-      - run: pip install PLY
-      - run: pip install Django==${{ matrix.django }}
-      - run: pip install -e .
-      - run: python test_project/manage.py test core.tests
-
-      # Send notification on build failure
-      - name: Notify slack fail
-        uses: ivelum/github-action-slack-notify-build@v1.7.2
-        if: failure() && github.event_name == 'push'
-        env:
-          SLACK_BOT_TOKEN: ${{ secrets.SLACK_BOT_TOKEN }}
-        with:
-          message_id: ${{ needs.notify-build-start.outputs.status_message_id }}
-          channel_id: C0PT3267R
-          status: FAILED
-          color: '#d7263d'
-
-  notify-build-success:
-    if: ${{ github.event_name == 'push' }}
-    needs: [notify-build-start, tests]
+          uv sync --all-extras
+          uv pip install "django~=${{ matrix.django-version }}.0"
+      - name: Compile translation catalogs (Babel)
+        # .mo files are not tracked in git; compile them with the same Babel
+        # function the build backend uses (no system gettext needed).
+        run: uv run --no-sync python -c "from _translations import compile_catalogs; compile_catalogs()"
+      - name: Run tests
+        # --no-sync so the matrix-pinned Django above is not reverted by uv.
+        run: uv run --no-sync pytest
+      - name: Run example_project tests
+        # The example_project is a separate Django project (its own settings and
+        # models), so it isn't collected by the main pytest run; exercise its
+        # suite via manage.py so the showcase schema/views don't rot.
+        working-directory: example_project
+        run: uv run --no-sync python manage.py test library -v2
+
+  tests-postgres:
     runs-on: ubuntu-latest
     steps:
-      # Send notification on build success
-      - name: Notify slack success
-        uses: ivelum/github-action-slack-notify-build@v1.7.2
+      - uses: actions/checkout@v4
+      - name: Install uv
+        uses: astral-sh/setup-uv@f94ec6bedd8674c4426838e6b50417d36b6ab231 # v5.3.1
+      - name: Set up Python 3.12
+        run: uv python install 3.12
+      - name: Install dependencies (project + Django 5.2)
+        run: |
+          uv sync --all-extras
+          uv pip install "django~=5.2.0"
+      - name: Compile translation catalogs (Babel)
+        # .mo files are not tracked in git; compile them with the same Babel
+        # function the build backend uses (no system gettext needed).
+        run: uv run --no-sync python -c "from _translations import compile_catalogs; compile_catalogs()"
+      - name: Run tests (PostgreSQL via testcontainers)
+        # --no-sync so the pinned Django above is not reverted by uv.
+        # Testcontainers manages the postgres:16-alpine container itself;
+        # no services: block needed — the runner's Docker daemon is used.
         env:
-          SLACK_BOT_TOKEN: ${{ secrets.SLACK_BOT_TOKEN }}
-        with:
-          message_id: ${{ needs.notify-build-start.outputs.status_message_id }}
-          channel_id: C0PT3267R
-          status: SUCCESS
-          color: '#16db65'
+          DJANGOQL_TEST_DB: postgres
+        run: uv run --no-sync pytest

.gitignore

@@ -4,7 +4,34 @@
 
 node_modules
 test_project/db.sqlite3
+example_project/db.sqlite3
 
 build
 dist
 djangoql.egg-info
+site/
+
+# Compiled gettext catalogs: generated from .po at build time (Babel), not
+# tracked. See _translations.py / _build_meta.py.
+*.mo
+
+.venv/
+uv.lock
+
+.pytest_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+*.egg-info/
+
+# Secrets / credentials (never commit)
+.env
+.env.*
+!.env.example
+!.env.sample
+*.pem
+*.key
+*.p12
+*.pfx
+credentials.json
+service-account*.json

.pre-commit-config.yaml

@@ -0,0 +1,41 @@
+# Pre-commit runs on STAGED files only — changed files get linted before
+# they land, the rest of the repo is untouched.
+#
+# Install:  uv sync --all-extras && pre-commit install
+# Manual:   pre-commit run                  # staged files only
+#           pre-commit run --all-files      # everything (escape hatch)
+#
+# Ruff replaces the previous flake8 + isort stack. The enforced rules are
+# mirrored in pyproject.toml [tool.ruff] (E/F/W + flake8-quotes Q +
+# flake8-print T20 + flake8-builtins A + isort I), so lint coverage is
+# preserved. pyupgrade / django-upgrade modernize syntax, but only on the
+# files you actually stage — never run them across the whole repo.
+
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v6.0.0
+    hooks:
+      - id: trailing-whitespace
+      - id: end-of-file-fixer
+      - id: check-yaml
+      - id: check-added-large-files
+      - id: detect-private-key
+
+  - repo: https://github.com/asottile/pyupgrade
+    rev: v3.21.2
+    hooks:
+      - id: pyupgrade
+        args: [--py310-plus]  # floor from requires-python = ">=3.10"
+
+  - repo: https://github.com/adamchainz/django-upgrade
+    rev: 1.30.0
+    hooks:
+      - id: django-upgrade
+        args: [--target-version, "4.2"]  # floor from the supported Django range
+
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.15.15
+    hooks:
+      - id: ruff-check
+        args: [--fix]
+      - id: ruff-format