Chore: Tidy leftover parentheses and the samples module docstring

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>

.github/actions/apt-install/action.yml

@@ -0,0 +1,53 @@
+name: Install apt packages
+description: >
+  Installs apt packages with a per-attempt timeout and retries. The hosted runner's Azure apt mirror intermittently serves archives at a crawl, which apt's own timeout does not catch. A stuck attempt is killed and retried, which usually lands on a healthy mirror node.
+
+inputs:
+  packages:
+    description: Space separated list of packages to install
+    required: true
+  attempts:
+    description: Maximum number of attempts
+    default: "3"
+  attempt-timeout:
+    description: Seconds before a single attempt is killed
+    default: "180"
+runs:
+  using: composite
+  steps:
+    - name: Install ${{ inputs.packages }}
+      shell: bash
+      env:
+        PACKAGES: ${{ inputs.packages }}
+        ATTEMPTS: ${{ inputs.attempts }}
+        ATTEMPT_TIMEOUT: ${{ inputs.attempt-timeout }}
+      run: |
+        SUDO=""
+        if [ "$(id -u)" -ne 0 ]; then
+          SUDO="sudo"
+        fi
+
+        attempt_install() {
+          $SUDO apt-get update -q
+          # Intentionally unquoted, this is a list of package names
+          $SUDO apt-get install -q --yes --no-install-recommends $PACKAGES
+        }
+        export -f attempt_install
+        export SUDO PACKAGES
+
+        for attempt in $(seq 1 "${ATTEMPTS}"); do
+          echo "::group::apt install attempt ${attempt}/${ATTEMPTS}"
+          start=$(date +%s)
+          if timeout --kill-after=10 "${ATTEMPT_TIMEOUT}" bash -c attempt_install; then
+            echo "::endgroup::"
+            echo "Installed in $(( $(date +%s) - start ))s"
+            exit 0
+          fi
+          echo "::endgroup::"
+          echo "::warning::apt install attempt ${attempt}/${ATTEMPTS} failed or exceeded ${ATTEMPT_TIMEOUT}s"
+          # A killed attempt can leave dpkg half configured
+          $SUDO dpkg --configure -a || true
+        done
+
+        echo "::error::apt install failed after ${ATTEMPTS} attempts"
+        exit 1

.github/dependabot.yml

@@ -59,7 +59,6 @@ updates:
           - "drf-*"
           - "djangorestframework"
           - "whitenoise"
-          - "bleach"
           - "jinja2"
       # Async, Task Queuing & Caching
       async-tasks:

.github/workflows/ci-backend.yml

@@ -102,17 +102,16 @@ jobs:
         with:
           python-version: "${{ matrix.python-version }}"
       - name: Install uv
-        uses: astral-sh/setup-uv@bec219d24cd3e171d82865faccec33120bb574f4 # v10.1.0
+        uses: astral-sh/setup-uv@c18668ad3cf93ea998bef934396af7bb5c839dc7 # v10.2.0
         with:
           version: ${{ env.DEFAULT_UV_VERSION }}
           enable-cache: true
           python-version: ${{ steps.setup-python.outputs.python-version }}
       - name: Install system dependencies
-        timeout-minutes: 10
-        run: |
-          sudo apt-get update -qq
-          sudo apt-get install -qq --no-install-recommends \
-            unpaper tesseract-ocr imagemagick ghostscript poppler-utils
+        timeout-minutes: 12
+        uses: $/.github/actions/apt-install
+        with:
+          packages: unpaper tesseract-ocr imagemagick ghostscript poppler-utils
       - name: Configure ImageMagick
         run: |
           sudo cp docker/rootfs/etc/ImageMagick-6/paperless-policy.xml /etc/ImageMagick-6/policy.xml
@@ -139,13 +138,13 @@ jobs:
             pytest
       - name: Upload test results to Codecov
         if: always()
-        uses: codecov/codecov-action@fb8b3582c8e4def4969c97caa2f19720cb33a72f # v7.0.0
+        uses: codecov/codecov-action@303a32d7a59b442fa8d48b6a1cc6825c09c847a5 # v7.1.1
         with:
           flags: backend-python-${{ matrix.python-version }}
           files: junit.xml
           report_type: test_results
       - name: Upload coverage to Codecov
-        uses: codecov/codecov-action@fb8b3582c8e4def4969c97caa2f19720cb33a72f # v7.0.0
+        uses: codecov/codecov-action@303a32d7a59b442fa8d48b6a1cc6825c09c847a5 # v7.1.1
         with:
           flags: backend-python-${{ matrix.python-version }}
           files: coverage.xml
@@ -176,7 +175,7 @@ jobs:
         with:
           python-version: "${{ env.DEFAULT_PYTHON }}"
       - name: Install uv
-        uses: astral-sh/setup-uv@bec219d24cd3e171d82865faccec33120bb574f4 # v10.1.0
+        uses: astral-sh/setup-uv@c18668ad3cf93ea998bef934396af7bb5c839dc7 # v10.2.0
         with:
           version: ${{ env.DEFAULT_UV_VERSION }}
           enable-cache: true

.github/workflows/ci-docker.yml

@@ -106,7 +106,7 @@ jobs:
           echo "repository=${repo_name}"
           echo "name=${repo_name}" >> $GITHUB_OUTPUT
       - name: Set up Docker Buildx
-        uses: docker/setup-buildx-action@37fe631027851001ddb9b187196cc803df7f5f0e # v4.3.0
+        uses: docker/setup-buildx-action@f87e5991a6d7451dcb8d9637bfbc97413f497069 # v4.4.1
       - name: Login to GitHub Container Registry
         uses: docker/login-action@dbcb813823bdd20940b903addbd779551569679f # v4.6.0
         with:
@@ -132,7 +132,7 @@ jobs:
             type=semver,pattern={{major}}.{{minor}}
       - name: Build and push by digest
         id: build
-        uses: docker/build-push-action@53b7df96c91f9c12dcc8a07bcb9ccacbed38856a # v7.3.0
+        uses: docker/build-push-action@c3c9e263c25d99ce0380d002d59b67737d91b0dc # v7.4.0
         with:
           context: .
           file: ./Dockerfile
@@ -182,7 +182,7 @@ jobs:
           echo "Downloaded digests:"
           ls -la /tmp/digests/
       - name: Set up Docker Buildx
-        uses: docker/setup-buildx-action@37fe631027851001ddb9b187196cc803df7f5f0e # v4.3.0
+        uses: docker/setup-buildx-action@f87e5991a6d7451dcb8d9637bfbc97413f497069 # v4.4.1
       - name: Login to GitHub Container Registry
         uses: docker/login-action@dbcb813823bdd20940b903addbd779551569679f # v4.6.0
         with:

.github/workflows/ci-docs.yml

@@ -78,7 +78,7 @@ jobs:
         with:
           python-version: ${{ env.DEFAULT_PYTHON_VERSION }}
       - name: Install uv
-        uses: astral-sh/setup-uv@bec219d24cd3e171d82865faccec33120bb574f4 # v10.1.0
+        uses: astral-sh/setup-uv@c18668ad3cf93ea998bef934396af7bb5c839dc7 # v10.2.0
         with:
           version: ${{ env.DEFAULT_UV_VERSION }}
           enable-cache: true

.github/workflows/ci-frontend.yml

@@ -174,13 +174,13 @@ jobs:
         run: cd src-ui && pnpm run test --max-workers=2 --shard=${{ matrix.shard-index }}/${{ matrix.shard-count }}
       - name: Upload test results to Codecov
         if: always()
-        uses: codecov/codecov-action@fb8b3582c8e4def4969c97caa2f19720cb33a72f # v7.0.0
+        uses: codecov/codecov-action@303a32d7a59b442fa8d48b6a1cc6825c09c847a5 # v7.1.1
         with:
           flags: frontend-node-${{ matrix.node-version }}
           directory: src-ui/
           report_type: test_results
       - name: Upload coverage to Codecov
-        uses: codecov/codecov-action@fb8b3582c8e4def4969c97caa2f19720cb33a72f # v7.0.0
+        uses: codecov/codecov-action@303a32d7a59b442fa8d48b6a1cc6825c09c847a5 # v7.1.1
         with:
           flags: frontend-node-${{ matrix.node-version }}
           directory: src-ui/coverage/
@@ -216,7 +216,7 @@ jobs:
         with:
           python-version: '3.12'
       - name: Install uv
-        uses: astral-sh/setup-uv@bec219d24cd3e171d82865faccec33120bb574f4 # v10.1.0
+        uses: astral-sh/setup-uv@c18668ad3cf93ea998bef934396af7bb5c839dc7 # v10.2.0
         with:
           version: '0.12.x'
           enable-cache: false
@@ -231,9 +231,10 @@ jobs:
       - name: Install dependencies
         run: cd src-ui && pnpm install --frozen-lockfile
       - name: Install backend system dependencies
-        run: |
-          apt-get update
-          apt-get install --yes --quiet --no-install-recommends libmagic1
+        timeout-minutes: 12
+        uses: $/.github/actions/apt-install
+        with:
+          packages: libmagic1
       - name: Install backend dependencies
         env:
           PYTHON_VERSION: ${{ steps.setup-python.outputs.python-version }}

.github/workflows/ci-release.yml

@@ -59,7 +59,7 @@ jobs:
         with:
           python-version: ${{ env.DEFAULT_PYTHON_VERSION }}
       - name: Install uv
-        uses: astral-sh/setup-uv@bec219d24cd3e171d82865faccec33120bb574f4 # v10.1.0
+        uses: astral-sh/setup-uv@c18668ad3cf93ea998bef934396af7bb5c839dc7 # v10.2.0
         with:
           version: ${{ env.DEFAULT_UV_VERSION }}
           enable-cache: false
@@ -70,9 +70,10 @@ jobs:
         run: |
           uv sync --python "${PYTHON_VERSION}" --dev --frozen
       - name: Install system dependencies
-        run: |
-          sudo apt-get update -qq
-          sudo apt-get install -qq --no-install-recommends gettext liblept5
+        timeout-minutes: 12
+        uses: $/.github/actions/apt-install
+        with:
+          packages: gettext liblept5
       # ---- Build Documentation ----
       - name: Build documentation
         env:
@@ -212,7 +213,7 @@ jobs:
         with:
           python-version: ${{ env.DEFAULT_PYTHON_VERSION }}
       - name: Install uv
-        uses: astral-sh/setup-uv@bec219d24cd3e171d82865faccec33120bb574f4 # v10.1.0
+        uses: astral-sh/setup-uv@c18668ad3cf93ea998bef934396af7bb5c839dc7 # v10.2.0
         with:
           version: ${{ env.DEFAULT_UV_VERSION }}
           enable-cache: false

.github/workflows/ci-static-analysis.yml

@@ -44,7 +44,7 @@ jobs:
       - name: Run Semgrep
         run: semgrep scan --config auto --sarif-output results.sarif
       - name: Upload results to GitHub code scanning
-        uses: github/codeql-action/upload-sarif@b96794f015dfd88f77b49b1c93e0fa7110f94c63 # v4.38.0
+        uses: github/codeql-action/upload-sarif@2892aa5e19bbd11bc0cff5427e3b750a04d9e3c2 # v4.38.2
         if: always()
         with:
           sarif_file: results.sarif

.github/workflows/cleanup-tags.yml

@@ -29,7 +29,7 @@ jobs:
     steps:
       - name: Clean temporary images
         if: "${{ env.TOKEN != '' }}"
-        uses: stumpylog/image-cleaner-action/ephemeral@4fe057d991d63b8f6d5d22c40f17c1bca2226537 # v0.12.0
+        uses: stumpylog/image-cleaner-action/ephemeral@21f875bab2376314e0525c614e923c669434f0e4 # v0.13.0
         with:
           token: "${{ env.TOKEN }}"
           owner: "${{ github.repository_owner }}"
@@ -56,7 +56,7 @@ jobs:
     steps:
       - name: Clean untagged images
         if: "${{ env.TOKEN != '' }}"
-        uses: stumpylog/image-cleaner-action/untagged@4fe057d991d63b8f6d5d22c40f17c1bca2226537 # v0.12.0
+        uses: stumpylog/image-cleaner-action/untagged@21f875bab2376314e0525c614e923c669434f0e4 # v0.13.0
         with:
           token: "${{ env.TOKEN }}"
           owner: "${{ github.repository_owner }}"

.github/workflows/codeql-analysis.yml

@@ -39,7 +39,7 @@ jobs:
           persist-credentials: false
       # Initializes the CodeQL tools for scanning.
       - name: Initialize CodeQL
-        uses: github/codeql-action/init@b96794f015dfd88f77b49b1c93e0fa7110f94c63 # v4.38.0
+        uses: github/codeql-action/init@2892aa5e19bbd11bc0cff5427e3b750a04d9e3c2 # v4.38.2
         with:
           languages: ${{ matrix.language }}
           # If you wish to specify custom queries, you can do so here or in a config file.
@@ -47,4 +47,4 @@ jobs:
           # Prefix the list here with "+" to use these queries and those in the config file.
           # queries: ./path/to/local/query, your-org/your-repo/queries@main
       - name: Perform CodeQL Analysis
-        uses: github/codeql-action/analyze@b96794f015dfd88f77b49b1c93e0fa7110f94c63 # v4.38.0
+        uses: github/codeql-action/analyze@2892aa5e19bbd11bc0cff5427e3b750a04d9e3c2 # v4.38.2

.github/workflows/crowdin.yml

@@ -22,7 +22,7 @@ jobs:
           token: ${{ secrets.PNGX_BOT_PAT }}
           persist-credentials: false
       - name: crowdin action
-        uses: crowdin/github-action@0d5670f539973aea2f01abce61a8989934df0025 # v3.0.2
+        uses: crowdin/github-action@9c23991700c0ec5256fd41089b9d9d7d540e424e # v3.3.0
         with:
           upload_translations: false
           download_translations: true

.github/workflows/translate-strings.yml

@@ -25,11 +25,12 @@ jobs:
         id: setup-python
         uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
       - name: Install system dependencies
-        run: |
-          sudo apt-get update -qq
-          sudo apt-get install -qq --no-install-recommends gettext
+        timeout-minutes: 12
+        uses: $/.github/actions/apt-install
+        with:
+          packages: gettext
       - name: Install uv
-        uses: astral-sh/setup-uv@bec219d24cd3e171d82865faccec33120bb574f4 # v10.1.0
+        uses: astral-sh/setup-uv@c18668ad3cf93ea998bef934396af7bb5c839dc7 # v10.2.0
         with:
           version: ${{ env.DEFAULT_UV_VERSION }}
           enable-cache: true

.pre-commit-config.yaml

@@ -38,7 +38,7 @@ repos:
           - json
   # See https://github.com/prettier/prettier/issues/15742 for the fork reason
   - repo: https://github.com/rbubley/mirrors-prettier
-    rev: 'v3.9.6'
+    rev: 'v3.9.9'
     hooks:
       - id: prettier
         types_or:
@@ -46,11 +46,11 @@ repos:
           - ts
           - markdown
         additional_dependencies:
-          - prettier@3.9.6
+          - prettier@3.9.9
           - 'prettier-plugin-organize-imports@4.3.0'
   # Python hooks
   - repo: https://github.com/astral-sh/ruff-pre-commit
-    rev: v0.16.7
+    rev: v0.16.9
     hooks:
       - id: ruff-check
       - id: ruff-format

Dockerfile

@@ -30,7 +30,7 @@ RUN set -eux \
 # Purpose: Installs s6-overlay and rootfs
 # Comments:
 #  - Don't leave anything extra in here either
-FROM ghcr.io/astral-sh/uv:0.12.16-python3.14-trixie-slim AS s6-overlay-base
+FROM ghcr.io/astral-sh/uv:0.12.23-python3.14-trixie-slim AS s6-overlay-base
 
 WORKDIR /usr/src/s6
 
@@ -171,7 +171,9 @@ RUN set -eux \
         && cp /etc/ImageMagick-6/paperless-policy.xml /etc/ImageMagick-6/policy.xml \
       && echo "Cleaning up image layer" \
         && rm --force --verbose *.deb \
-    && rm --recursive --force --verbose /var/lib/apt/lists/*
+    && rm --recursive --force --verbose /var/lib/apt/lists/* \
+    && echo "Configuring interactive shells to source the s6 container environment" \
+      && echo '. /etc/profile.d/contenv.sh' >> /etc/bash.bashrc
 
 WORKDIR /usr/src/paperless/src/
 

docker/compose/docker-compose.ci-test.yml

@@ -24,7 +24,7 @@ services:
     network_mode: host
     restart: unless-stopped
   greenmail:
-    image: docker.io/greenmail/standalone:2.1.13
+    image: docker.io/greenmail/standalone:2.1.14
     hostname: greenmail
     container_name: greenmail
     environment:

docker/rootfs/etc/profile.d/contenv.sh

@@ -0,0 +1,18 @@
+#!/bin/sh
+# Source s6 container environment for interactive shells.
+# Ensures variables resolved from *_FILE secret injection are visible
+# when using 'docker exec bash'. Does not affect s6 services (those
+# use with-contenv directly). Has no effect in non-container contexts
+# because the directory will not exist.
+# Note: sh/dash shells opened via 'docker exec sh' are not covered;
+# only bash-based sessions benefit from this file.
+_pngx_contenv="/run/s6/container_environment"
+if [ -d "${_pngx_contenv}" ]; then
+	for _pngx_f in "${_pngx_contenv}"/*; do
+		[ -f "${_pngx_f}" ] || continue
+		_pngx_name=$(basename "${_pngx_f}")
+		_pngx_val=$(cat "${_pngx_f}")
+		export "${_pngx_name}=${_pngx_val}"
+	done
+fi
+unset _pngx_contenv _pngx_f _pngx_name _pngx_val

docs/advanced_usage.md

@@ -136,13 +136,15 @@ for suggested generation and embedding models.
 ### AI-assisted suggestions
 
 With AI enabled, Paperless-ngx can suggest a title, tags, correspondent, document type,
-storage path and dates by sending the document to the LLM. This is **opt-in per request**
-and surfaces through the "Suggest" control on the document detail page, alongside the
-classic classifier-based suggestions — it does not disable them. Suggestions are requested
-automatically when you open a document that carries an inbox tag unless "Automatically request
-suggestions for inbox documents" under Settings > Documents is disabled. Suggestion output
-language can be steered with
-[`PAPERLESS_AI_LLM_OUTPUT_LANGUAGE`](configuration.md#PAPERLESS_AI_LLM_OUTPUT_LANGUAGE)
+storage path and dates by sending the document to the LLM using "Suggest" button on the document
+detail page. You can choose which type of suggestions are requested by default under Settings >
+Documents, either ML (classifier-based) suggestions, AI suggestions, or both. When both are requested
+the results are combined.
+
+Suggestions are requested automatically when you open a document that carries an inbox tag
+unless "Automatically request suggestions for inbox documents" under Settings > Documents is disabled.
+
+Suggestion output language can be steered with [`PAPERLESS_AI_LLM_OUTPUT_LANGUAGE`](configuration.md#PAPERLESS_AI_LLM_OUTPUT_LANGUAGE)
 (otherwise it follows the user's UI language).
 
 ### The LLM index (RAG) and similar documents

pyproject.toml

@@ -19,7 +19,6 @@ classifiers = [
 dependencies = [
   "azure-ai-documentintelligence>=1.0.2",
   "babel>=2.17",
-  "bleach~=6.4.0",
   "celery[redis]~=5.6.2",
   "channels~=4.2",
   "channels-redis~=4.2",
@@ -35,7 +34,7 @@ dependencies = [
   "django-cors-headers~=4.9.0",
   "django-extensions~=4.1",
   "django-filter~=25.1",
-  "django-guardian>=3.3.3,<3.5",
+  "django-guardian>=3.3.3,<3.6",
   "django-multiselectfield~=1.0.1",
   "django-rich~=2.2.0",
   "django-soft-delete~=1.0.18",
@@ -45,7 +44,7 @@ dependencies = [
   "drf-spectacular-sidecar>=2026.7.1,<2026.10",
   "drf-writable-nested~=0.7.1",
   "filelock~=3.32.0",
-  "flower>=2.0.1,<2.2",
+  "flower>=2.0.1,<2.3",
   "gotenberg-client[httpx]~=1.0",
   "httpx-oauth~=0.17",
   "ijson>=3.5.1",
@@ -77,6 +76,7 @@ dependencies = [
   "tantivy~=0.26.0",
   "tika-client[httpx]~=1.0",
   "torch>=2.13,<2.15",
+  "turbohtml~=1.10.0",
   "watchfiles>=1.2",
   "whitenoise~=6.11",
   "whoosh-compat[tantivy]==0.3",
@@ -84,13 +84,13 @@ dependencies = [
 ]
 [project.optional-dependencies]
 mariadb = [
-  "mysqlclient~=2.2.7",
+  "mysqlclient>=2.2.7,<2.4",
 ]
 postgres = [
   "psycopg[c,pool]==3.3.4",
   # Direct dependency for proper resolution of the pre-built wheels
   "psycopg-c==3.3.4",
-  "psycopg-pool==3.3.1",
+  "psycopg-pool==3.3.2",
 ]
 webserver = [
   "granian[uvloop]>=2.7,<2.9",
@@ -112,7 +112,7 @@ lint = [
 testing = [
   "daphne",
   "factory-boy~=3.3.1",
-  "faker>=40.36,<40.39",
+  "faker>=40.36,<40.40",
   "imagehash",
   "pytest~=9.1.1",
   "pytest-cov~=7.1.0",
@@ -136,7 +136,6 @@ typing = [
   "mypy",
   "mypy-baseline",
   "pyrefly",
-  "types-bleach",
   "types-channels",
   "types-colorama",
   "types-dateparser",
@@ -151,6 +150,7 @@ typing = [
 
 [tool.uv]
 required-version = ">=0.9.0"
+prerelease = "disallow"
 environments = [
   "sys_platform == 'darwin'",
   "sys_platform == 'linux'",
@@ -256,8 +256,8 @@ isort.force-single-line = true
 [tool.codespell]
 ignore-words-list = "criterias,afterall,valeu,ureue,equest,ure,assertIn,Oktober,commitish,NIN,nin,reprot"
 skip = """\
-  src-ui/src/locale/*,src-ui/pnpm-lock.yaml,src-ui/e2e/*,src/paperless_mail/tests/samples/*,src/paperless/tests/samples\
-  /mail/*,src/documents/tests/samples/*,*.po,*.json\
+  src-ui/src/locale/*,src-ui/pnpm-lock.yaml,src-ui/e2e/*,src/paperless/tests/samples/mail/*,src/documents/tests/samples\
+  /*,src/paperless_testing/sample_files/*,*.po,*.json\
   """
 write-changes = true
 

src-ui/angular.json

@@ -91,6 +91,11 @@
                 "glob": "**/*",
                 "input": "node_modules/pdfjs-dist/iccs/",
                 "output": "/assets/iccs/"
+              },
+              {
+                "glob": "**/*",
+                "input": "node_modules/pdfjs-dist/cmaps/",
+                "output": "/assets/cmaps/"
               }
             ],
             "styles": [

src-ui/package.json

@@ -15,16 +15,16 @@
   },
   "private": true,
   "dependencies": {
-    "@angular/cdk": "^22.1.6",
-    "@angular/common": "~22.1.6",
-    "@angular/compiler": "~22.1.6",
-    "@angular/core": "~22.1.6",
-    "@angular/forms": "~22.1.6",
-    "@angular/localize": "~22.1.6",
-    "@angular/platform-browser": "~22.1.6",
-    "@angular/router": "~22.1.6",
+    "@angular/cdk": "^22.2.0",
+    "@angular/common": "~22.2.0",
+    "@angular/compiler": "~22.2.0",
+    "@angular/core": "~22.2.0",
+    "@angular/forms": "~22.2.0",
+    "@angular/localize": "~22.2.0",
+    "@angular/platform-browser": "~22.2.0",
+    "@angular/router": "~22.2.0",
     "@ng-bootstrap/ng-bootstrap": "^21.0.0",
-    "@ng-select/ng-select": "~24.1.1",
+    "@ng-select/ng-select": "~24.1.2",
     "@ngneat/dirty-check-forms": "^3.0.3",
     "@popperjs/core": "^2.11.8",
     "bootstrap": "^5.3.8",
@@ -45,29 +45,29 @@
   },
   "devDependencies": {
     "@angular-builders/jest": "^22.0.1",
-    "@angular-devkit/core": "^22.1.8",
-    "@angular-devkit/schematics": "^22.1.8",
+    "@angular-devkit/core": "^22.2.0",
+    "@angular-devkit/schematics": "^22.2.0",
     "@angular-eslint/builder": "22.5.0",
     "@angular-eslint/eslint-plugin": "22.5.0",
     "@angular-eslint/eslint-plugin-template": "22.5.0",
     "@angular-eslint/schematics": "22.5.0",
     "@angular-eslint/template-parser": "22.5.0",
-    "@angular/build": "22.1.8",
-    "@angular/cli": "22.1.8",
-    "@angular/compiler-cli": "~22.1.6",
+    "@angular/build": "22.2.0",
+    "@angular/cli": "22.2.0",
+    "@angular/compiler-cli": "~22.2.0",
     "@playwright/test": "^1.62.1",
     "@types/jest": "^30.0.0",
-    "@types/node": "^26.5.0",
-    "@typescript-eslint/eslint-plugin": "^8.70.0",
-    "@typescript-eslint/parser": "^8.70.0",
-    "@typescript-eslint/utils": "^8.70.0",
-    "eslint": "^10.10.0",
-    "jest": "30.5.1",
-    "jest-environment-jsdom": "^30.5.1",
+    "@types/node": "^26.6.2",
+    "@typescript-eslint/eslint-plugin": "^8.70.1",
+    "@typescript-eslint/parser": "^8.70.1",
+    "@typescript-eslint/utils": "^8.70.1",
+    "eslint": "^10.11.0",
+    "jest": "30.5.2",
+    "jest-environment-jsdom": "^30.5.2",
     "jest-junit": "^17.0.0",
     "jest-preset-angular": "^17.0.0",
     "jest-websocket-mock": "^2.5.0",
-    "prettier": "^3.9.6",
+    "prettier": "^3.9.9",
     "prettier-plugin-organize-imports": "^4.3.0",
     "ts-node": "~10.9.2",
     "typescript": "^6.0.3"

src-ui/src/app/components/admin/settings/settings.component.html

@@ -253,6 +253,24 @@
               </div>
             </div>
 
+            @if (aiEnabled) {
+              <div class="row mb-3">
+                <div class="col-md-3 col-form-label pt-0">
+                  <span i18n>Suggestions default to</span>
+                </div>
+                <div class="col">
+                  <fieldset class="btn-group btn-group-sm">
+                    <input type="radio" class="btn-check" id="suggestionSourceBoth" [value]="SuggestionSource.Both" formControlName="documentEditingSuggestionSource">
+                    <label class="btn btn-outline-primary" for="suggestionSourceBoth"><ng-container i18n>Both</ng-container></label>
+                    <input type="radio" class="btn-check" id="suggestionSourceML" [value]="SuggestionSource.ML" formControlName="documentEditingSuggestionSource">
+                    <label class="btn btn-outline-primary" for="suggestionSourceML"><i-bs class="me-1" name="cpu"></i-bs><ng-container i18n>ML only</ng-container></label>
+                    <input type="radio" class="btn-check" id="suggestionSourceAI" [value]="SuggestionSource.AI" formControlName="documentEditingSuggestionSource">
+                    <label class="btn btn-outline-primary" for="suggestionSourceAI"><i-bs class="me-1" name="stars"></i-bs><ng-container i18n>AI only</ng-container></label>
+                  </fieldset>
+                </div>
+              </div>
+            }
+
             <div class="row">
               <div class="col">
                 <pngx-input-check i18n-title title="Automatically request suggestions for inbox documents" i18n-hint hint="If un-checked, suggestions must be requested via the Suggest button." formControlName="documentEditingAutoSuggest"></pngx-input-check>

src-ui/src/app/components/admin/settings/settings.component.spec.ts

@@ -307,7 +307,7 @@ describe('SettingsComponent', () => {
     expect(toastErrorSpy).toHaveBeenCalled()
     expect(storeSpy).toHaveBeenCalled()
     expect(appearanceSettingsSpy).not.toHaveBeenCalled()
-    expect(setSpy).toHaveBeenCalledTimes(34)
+    expect(setSpy).toHaveBeenCalledTimes(35)
     expect(setSpy).toHaveBeenCalledWith(SETTINGS_KEYS.SIDEBAR_HIDDEN_ITEMS, [
       HideableSidebarItemID.Workflows,
     ])

src-ui/src/app/components/admin/settings/settings.component.ts

@@ -44,6 +44,7 @@ import {
   HIDEABLE_SIDEBAR_ITEM_IDS,
   HideableSidebarItemID,
   SETTINGS_KEYS,
+  SuggestionSource,
 } from 'src/app/data/ui-settings'
 import { User } from 'src/app/data/user'
 import { IfPermissionsDirective } from 'src/app/directives/if-permissions.directive'
@@ -184,6 +185,7 @@ export class SettingsComponent
     documentEditingRemoveInboxTags: new FormControl(null),
     documentEditingOverlayThumbnail: new FormControl(null),
     documentEditingAutoSuggest: new FormControl(null),
+    documentEditingSuggestionSource: new FormControl(null),
     documentDetailsHiddenFields: new FormControl([]),
     searchDbOnly: new FormControl(null),
     searchLink: new FormControl(null),
@@ -217,6 +219,11 @@ export class SettingsComponent
   public readonly PdfZoomScale = PdfZoomScale
 
   public readonly PdfEditorEditMode = PdfEditorEditMode
+  public readonly SuggestionSource = SuggestionSource
+
+  get aiEnabled(): boolean {
+    return this.settings.get(SETTINGS_KEYS.AI_ENABLED)
+  }
 
   public readonly documentDetailFieldOptions = documentDetailFieldOptions
   public readonly sidebarItemOptions = HIDEABLE_SIDEBAR_ITEM_IDS.map((id) => ({
@@ -404,6 +411,9 @@ export class SettingsComponent
       documentEditingAutoSuggest: this.settings.get(
         SETTINGS_KEYS.DOCUMENT_EDITING_AUTO_SUGGEST
       ),
+      documentEditingSuggestionSource: this.settings.get(
+        SETTINGS_KEYS.DOCUMENT_EDITING_SUGGESTION_SOURCE
+      ),
       documentDetailsHiddenFields: this.settings.get(
         SETTINGS_KEYS.DOCUMENT_DETAILS_HIDDEN_FIELDS
       ),
@@ -625,6 +635,10 @@ export class SettingsComponent
       SETTINGS_KEYS.DOCUMENT_EDITING_AUTO_SUGGEST,
       this.settingsForm.value.documentEditingAutoSuggest
     )
+    this.settings.set(
+      SETTINGS_KEYS.DOCUMENT_EDITING_SUGGESTION_SOURCE,
+      this.settingsForm.value.documentEditingSuggestionSource
+    )
     this.settings.set(
       SETTINGS_KEYS.DOCUMENT_DETAILS_HIDDEN_FIELDS,
       this.settingsForm.value.documentDetailsHiddenFields

src-ui/src/app/components/common/pdf-viewer/pdf-viewer.component.scss

@@ -154,11 +154,29 @@
   & section {
     position: absolute;
     text-align: initial;
+    pointer-events: auto;
     box-sizing: border-box;
     transform-origin: 0 0;
   }
 
+  & :is(.linkAnnotation, .buttonWidgetAnnotation.pushButton) > a {
+    position: absolute;
+    inset: 0;
+    font-size: 1em;
+    transition: none;
+  }
+
+  & :is(.linkAnnotation, .buttonWidgetAnnotation.pushButton):not(.hasBorder)
+    > a:hover {
+    opacity: 0.2;
+    background-color: rgb(255 255 0);
+  }
+
   & .annotationTextContent {
     opacity: 0;
   }
 }
+
+:host ::ng-deep .textLayer.selecting ~ .annotationLayer section {
+  pointer-events: none;
+}

src-ui/src/app/components/common/pdf-viewer/pdf-viewer.component.spec.ts

@@ -1,7 +1,11 @@
 import { SimpleChange } from '@angular/core'
 import { ComponentFixture, TestBed } from '@angular/core/testing'
 import * as pdfjs from 'pdfjs-dist/legacy/build/pdf.mjs'
-import { PDFSinglePageViewer, PDFViewer } from 'pdfjs-dist/web/pdf_viewer.mjs'
+import {
+  LinkTarget,
+  PDFSinglePageViewer,
+  PDFViewer,
+} from 'pdfjs-dist/web/pdf_viewer.mjs'
 import { PngxPdfViewerComponent } from './pdf-viewer.component'
 import { PdfRenderMode, PdfZoomLevel, PdfZoomScale } from './pdf-viewer.types'
 
@@ -58,6 +62,16 @@ describe('PngxPdfViewerComponent', () => {
     expect((component as any).pdfViewer).toBeInstanceOf(PDFViewer)
   })
 
+  it('opens external links in a new tab', () => {
+    const linkService = (component as any).linkService
+    expect(linkService.options).toEqual(
+      expect.objectContaining({
+        externalLinkTarget: LinkTarget.BLANK,
+        externalLinkRel: 'noopener noreferrer nofollow',
+      })
+    )
+  })
+
   it('resolves the worker source relative to the document base URI', async () => {
     setBaseHref('/paperless/')
     const getDocumentSpy = jest.spyOn(pdfjs, 'getDocument')
@@ -76,6 +90,7 @@ describe('PngxPdfViewerComponent', () => {
       withCredentials: true,
       wasmUrl: expect.stringContaining('/paperless/assets/wasm/'),
       iccUrl: expect.stringContaining('/paperless/assets/iccs/'),
+      cMapUrl: expect.stringContaining('/paperless/assets/cmaps/'),
     })
   })
 

src-ui/src/app/components/common/pdf-viewer/pdf-viewer.component.ts

@@ -21,6 +21,7 @@ import {
 } from 'pdfjs-dist/legacy/build/pdf.mjs'
 import {
   EventBus,
+  LinkTarget,
   PDFFindController,
   PDFLinkService,
   PDFSinglePageViewer,
@@ -75,7 +76,11 @@ export class PngxPdfViewerComponent
   private lastViewerPage?: number
 
   private readonly eventBus = new EventBus()
-  private readonly linkService = new PDFLinkService({ eventBus: this.eventBus })
+  private readonly linkService = new PDFLinkService({
+    eventBus: this.eventBus,
+    externalLinkTarget: LinkTarget.BLANK,
+    externalLinkRel: 'noopener noreferrer nofollow',
+  })
   private readonly findController = new PDFFindController({
     eventBus: this.eventBus,
     linkService: this.linkService,
@@ -185,6 +190,7 @@ export class PngxPdfViewerComponent
       withCredentials: true,
       wasmUrl: new URL('assets/wasm/', this.document.baseURI).toString(),
       iccUrl: new URL('assets/iccs/', this.document.baseURI).toString(),
+      cMapUrl: new URL('assets/cmaps/', this.document.baseURI).toString(),
     }
     this.loadingTask = getDocument(initOptions)
     try {

src-ui/src/app/components/common/suggestions-dropdown/suggestions-dropdown.component.html

@@ -1,58 +1,84 @@
-<div class="btn-group">
-  <button type="button" class="btn btn-sm btn-outline-primary" (click)="clickSuggest()" [disabled]="disabled() || loading() || (suggestions() && !aiEnabled())" [aria-label]="noSuggestions ? 'No suggestions' : 'Suggest'" i18n-aria-label>
-    @if (loading()) {
-      <div class="spinner-border spinner-border-sm" role="status"></div>
-    } @else if (noSuggestions) {
-      <i-bs width="1.2em" height="1.2em" name="check-circle"></i-bs>
-    } @else {
-      <i-bs width="1.2em" height="1.2em" name="stars"></i-bs>
+<div class="d-flex align-items-center">
+  <div class="btn-group">
+    <button type="button" class="btn btn-sm btn-outline-primary" (click)="clickSuggest()" [disabled]="disabled() || loading() || (suggestions() && !aiEnabled())" [aria-label]="noSuggestions ? 'No suggestions' : 'Suggest'" i18n-aria-label>
+      @if (loading()) {
+        <div class="spinner-border spinner-border-sm" role="status"></div>
+      } @else if (noSuggestions) {
+        <i-bs width="1.2em" height="1.2em" name="check-circle"></i-bs>
+      } @else {
+        <i-bs width="1.2em" height="1.2em" name="lightbulb"></i-bs>
+      }
+      @if (noSuggestions) {
+        <span class="d-none d-lg-inline ps-1" i18n>No suggestions</span>
+      } @else {
+        <span class="d-none d-lg-inline ps-1" i18n>Suggest</span>
+      }
+      @if (totalSuggestions > 0) {
+        <span class="badge bg-primary ms-2">{{ totalSuggestions }}</span>
+      }
+    </button>
+
+    @if (aiEnabled()) {
+      <div class="btn-group" ngbDropdown #dropdown="ngbDropdown" [popperOptions]="popperOptions">
+        <button type="button" class="btn btn-sm btn-outline-primary" ngbDropdownToggle [disabled]="disabled() || loading() || !suggestions()" aria-expanded="false" aria-controls="suggestionsDropdown" aria-label="Suggestions dropdown">
+          <span class="visually-hidden" i18n>Show suggestions</span>
+        </button>
+
+        <div ngbDropdownMenu aria-labelledby="suggestionsDropdown" class="shadow suggestions-dropdown">
+          <div class="list-group list-group-flush small pb-0">
+            @if (novelSuggestions === 0 && reusableSuggestions === 0) {
+              <div class="list-group-item text-muted fst-italic">
+                <small class="text-muted small fst-italic" i18n>No novel suggestions</small>
+              </div>
+            }
+            @if (suggestions()?.suggested_tags?.length > 0) {
+              <small class="list-group-item text-uppercase text-muted small"><i-bs class="me-2" name="tags"></i-bs><ng-container i18n>Tags</ng-container></small>
+              @for (tag of suggestions().suggested_tags; track tag) {
+                <button type="button" class="list-group-item list-group-item-action bg-light" (click)="addTag.emit(tag)">{{ tag }}</button>
+              }
+            }
+            @if (suggestions()?.suggested_document_types?.length > 0) {
+              <div class="list-group-item text-uppercase text-muted small"><i-bs class="me-2" name="hash"></i-bs><ng-container i18n>Document Types</ng-container></div>
+              @for (type of suggestions().suggested_document_types; track type) {
+                <button type="button" class="list-group-item list-group-item-action bg-light" (click)="addDocumentType.emit(type)">{{ type }}</button>
+              }
+            }
+            @if (suggestions()?.suggested_correspondents?.length > 0) {
+              <div class="list-group-item text-uppercase text-muted small"><i-bs class="me-2" name="person"></i-bs><ng-container i18n>Correspondents</ng-container></div>
+              @for (correspondent of suggestions().suggested_correspondents; track correspondent) {
+                <button type="button" class="list-group-item list-group-item-action bg-light" (click)="addCorrespondent.emit(correspondent)">{{ correspondent }}</button>
+              }
+            }
+            @if (reusableSuggestions > 0) {
+              <div class="list-group-item text-muted fst-italic">
+                <small class="text-muted small fst-italic" i18n>{reusableSuggestions, plural, =1 {1 existing value suggested below} other {{{reusableSuggestions}} existing values suggested below}}</small>
+              </div>
+            }
+          </div>
+        </div>
+      </div>
     }
-    @if (noSuggestions) {
-      <span class="d-none d-lg-inline ps-1" i18n>No suggestions</span>
-    } @else {
-      <span class="d-none d-lg-inline ps-1" i18n>Suggest</span>
-    }
-    @if (totalSuggestions > 0) {
-      <span class="badge bg-primary ms-2">{{ totalSuggestions }}</span>
-    }
-  </button>
+  </div>
 
   @if (aiEnabled()) {
-    <div class="btn-group" ngbDropdown #dropdown="ngbDropdown" [popperOptions]="popperOptions">
-      <button type="button" class="btn btn-sm btn-outline-primary" ngbDropdownToggle [disabled]="disabled() || loading() || !suggestions()" aria-expanded="false" aria-controls="suggestionsDropdown" aria-label="Suggestions dropdown">
-        <span class="visually-hidden" i18n>Show suggestions</span>
+    <div ngbDropdown autoClose="outside" placement="bottom-end" [popperOptions]="popperOptions">
+      <button type="button" class="btn btn-sm btn-link position-relative" ngbDropdownToggle [disabled]="disabled() || loading()" i18n-title title="Suggestion options">
+        <i-bs name="three-dots"></i-bs>
+        @if (source() !== defaultSource()) {
+          <span class="position-absolute top-0 start-100 translate-middle p-1 bg-primary border border-light rounded-circle">
+            <span class="visually-hidden" i18n>Not using default</span>
+          </span>
+        }
       </button>
-
-      <div ngbDropdownMenu aria-labelledby="suggestionsDropdown" class="shadow suggestions-dropdown">
-        <div class="list-group list-group-flush small pb-0">
-          @if (novelSuggestions === 0 && reusableSuggestions === 0) {
-            <div class="list-group-item text-muted fst-italic">
-              <small class="text-muted small fst-italic" i18n>No novel suggestions</small>
-            </div>
-          }
-          @if (suggestions()?.suggested_tags?.length > 0) {
-            <small class="list-group-item text-uppercase text-muted small"><i-bs class="me-2" name="tags"></i-bs><ng-container i18n>Tags</ng-container></small>
-            @for (tag of suggestions().suggested_tags; track tag) {
-              <button type="button" class="list-group-item list-group-item-action bg-light" (click)="addTag.emit(tag)">{{ tag }}</button>
-            }
-          }
-          @if (suggestions()?.suggested_document_types?.length > 0) {
-            <div class="list-group-item text-uppercase text-muted small"><i-bs class="me-2" name="hash"></i-bs><ng-container i18n>Document Types</ng-container></div>
-            @for (type of suggestions().suggested_document_types; track type) {
-              <button type="button" class="list-group-item list-group-item-action bg-light" (click)="addDocumentType.emit(type)">{{ type }}</button>
-            }
-          }
-          @if (suggestions()?.suggested_correspondents?.length > 0) {
-            <div class="list-group-item text-uppercase text-muted small"><i-bs class="me-2" name="person"></i-bs><ng-container i18n>Correspondents</ng-container></div>
-            @for (correspondent of suggestions().suggested_correspondents; track correspondent) {
-              <button type="button" class="list-group-item list-group-item-action bg-light" (click)="addCorrespondent.emit(correspondent)">{{ correspondent }}</button>
-            }
-          }
-          @if (reusableSuggestions > 0) {
-            <div class="list-group-item text-muted fst-italic">
-              <small class="text-muted small fst-italic" i18n>{reusableSuggestions, plural, =1 {1 existing value suggested below} other {{{reusableSuggestions}} existing values suggested below}}</small>
-            </div>
-          }
+      <div ngbDropdownMenu class="shadow p-3">
+        <div class="small text-muted mb-2" i18n>Suggest using:</div>
+        <div class="form-check small">
+          <input class="form-check-input" type="checkbox" id="suggestionSourceML" [checked]="useML" [disabled]="useML && !useAI" (change)="setSources($event.target.checked, useAI)">
+          <label class="form-check-label d-inline-flex align-items-center gap-1" for="suggestionSourceML"><i-bs name="cpu"></i-bs><ng-container i18n>ML</ng-container></label>
+        </div>
+        <div class="form-check small">
+          <input class="form-check-input" type="checkbox" id="suggestionSourceAI" [checked]="useAI" [disabled]="useAI && !useML" (change)="setSources(useML, $event.target.checked)">
+          <label class="form-check-label d-inline-flex align-items-center gap-1" for="suggestionSourceAI"><i-bs name="stars"></i-bs><ng-container i18n>AI</ng-container></label>
         </div>
       </div>
     </div>

src-ui/src/app/components/common/suggestions-dropdown/suggestions-dropdown.component.scss

@@ -1,3 +1,7 @@
 .suggestions-dropdown {
   min-width: 250px;
 }
+
+.btn-link.dropdown-toggle::after {
+  display: none;
+}

src-ui/src/app/components/common/suggestions-dropdown/suggestions-dropdown.component.spec.ts

@@ -1,6 +1,7 @@
 import { ComponentFixture, TestBed } from '@angular/core/testing'
 import { NgbDropdownModule } from '@ng-bootstrap/ng-bootstrap'
 import { NgxBootstrapIconsModule, allIcons } from 'ngx-bootstrap-icons'
+import { SuggestionSource } from 'src/app/data/ui-settings'
 import { SuggestionsDropdownComponent } from './suggestions-dropdown.component'
 
 describe('SuggestionsDropdownComponent', () => {
@@ -179,14 +180,71 @@ describe('SuggestionsDropdownComponent', () => {
 
   it('should toggle dropdown when clickSuggest is called and suggestions are not null', () => {
     fixture.componentRef.setInput('aiEnabled', true)
+    fixture.componentRef.setInput('fetchedSources', [SuggestionSource.ML])
     fixture.detectChanges()
     fixture.componentRef.setInput('suggestions', {
       suggested_correspondents: [],
       suggested_tags: [],
       suggested_document_types: [],
     })
+    fixture.detectChanges()
     component.clickSuggest()
-    expect(component.dropdown.open).toBeTruthy()
+    expect(component.dropdown.isOpen()).toBeTruthy()
     expect(fixture.nativeElement.textContent).toContain('No novel suggestions')
   })
+
+  it('should fetch unfetched sources and show existing suggestions', () => {
+    jest.spyOn(component.getSuggestions, 'emit')
+    fixture.componentRef.setInput('aiEnabled', true)
+    fixture.componentRef.setInput('source', SuggestionSource.Both)
+    fixture.componentRef.setInput('fetchedSources', [SuggestionSource.ML])
+    fixture.componentRef.setInput('suggestions', { tags: [1] })
+    fixture.detectChanges()
+    component.clickSuggest()
+    expect(component.getSuggestions.emit).toHaveBeenCalledWith(
+      SuggestionSource.Both
+    )
+    expect(component.dropdown.isOpen()).toBeTruthy()
+  })
+
+  it('should only show source options when AI is enabled', () => {
+    expect(
+      fixture.nativeElement.querySelector('#suggestionSourceML')
+    ).toBeNull()
+    fixture.componentRef.setInput('aiEnabled', true)
+    fixture.detectChanges()
+    fixture.nativeElement
+      .querySelector('button[title="Suggestion options"]')
+      .click()
+    fixture.detectChanges()
+    expect(
+      fixture.nativeElement.querySelector('#suggestionSourceML')
+    ).not.toBeNull()
+  })
+
+  it('should emit source changes and never allow no source', () => {
+    const emitSpy = jest.spyOn(component.sourceChange, 'emit')
+    component.setSources(true, true)
+    expect(emitSpy).toHaveBeenCalledWith(SuggestionSource.Both)
+    component.setSources(true, false)
+    expect(emitSpy).toHaveBeenCalledWith(SuggestionSource.ML)
+    component.setSources(false, true)
+    expect(emitSpy).toHaveBeenCalledWith(SuggestionSource.AI)
+
+    emitSpy.mockClear()
+    component.setSources(false, false)
+    expect(emitSpy).not.toHaveBeenCalled()
+  })
+
+  it('should indicate a non-default source', () => {
+    fixture.componentRef.setInput('aiEnabled', true)
+    fixture.componentRef.setInput('source', SuggestionSource.AI)
+    fixture.componentRef.setInput('defaultSource', SuggestionSource.AI)
+    fixture.detectChanges()
+    expect(fixture.nativeElement.textContent).not.toContain('Not using default')
+
+    fixture.componentRef.setInput('source', SuggestionSource.Both)
+    fixture.detectChanges()
+    expect(fixture.nativeElement.textContent).toContain('Not using default')
+  })
 })

src-ui/src/app/components/common/suggestions-dropdown/suggestions-dropdown.component.ts

@@ -8,6 +8,7 @@ import {
 import { NgbDropdown, NgbDropdownModule } from '@ng-bootstrap/ng-bootstrap'
 import { NgxBootstrapIconsModule } from 'ngx-bootstrap-icons'
 import { DocumentSuggestions } from 'src/app/data/document-suggestions'
+import { SuggestionSource } from 'src/app/data/ui-settings'
 import { pngxPopperOptions } from 'src/app/utils/popper-options'
 
 @Component({
@@ -18,12 +19,16 @@ import { pngxPopperOptions } from 'src/app/utils/popper-options'
 })
 export class SuggestionsDropdownComponent {
   public popperOptions = pngxPopperOptions
+  public readonly SuggestionSource = SuggestionSource
 
   @ViewChild('dropdown') dropdown: NgbDropdown
   readonly suggestions = input<DocumentSuggestions>(null)
   readonly aiEnabled = input(false)
   readonly loading = input(false)
   readonly disabled = input(false)
+  readonly source = input<SuggestionSource>(SuggestionSource.ML)
+  readonly defaultSource = input<SuggestionSource>(SuggestionSource.ML)
+  readonly fetchedSources = input<SuggestionSource[]>([])
 
   readonly appliedTags = input<number[]>([])
   readonly appliedCorrespondent = input<number>(null)
@@ -31,8 +36,10 @@ export class SuggestionsDropdownComponent {
   readonly appliedStoragePath = input<number>(null)
 
   @Output()
-  getSuggestions: EventEmitter<SuggestionsDropdownComponent> =
-    new EventEmitter()
+  getSuggestions: EventEmitter<SuggestionSource> = new EventEmitter()
+
+  @Output()
+  sourceChange: EventEmitter<SuggestionSource> = new EventEmitter()
 
   @Output()
   addTag: EventEmitter<string> = new EventEmitter()
@@ -53,12 +60,42 @@ export class SuggestionsDropdownComponent {
     }
 
     if (!this.suggestions()) {
-      this.getSuggestions.emit(this)
+      this.getSuggestions.emit(this.source())
+    } else if (this.hasUnfetchedSources) {
+      // sources changed, fetch the rest and show what we have meanwhile
+      this.getSuggestions.emit(this.source())
+      this.dropdown?.open()
     } else {
       this.dropdown?.toggle()
     }
   }
 
+  get useML(): boolean {
+    return this.source() !== SuggestionSource.AI
+  }
+
+  get useAI(): boolean {
+    return this.source() !== SuggestionSource.ML
+  }
+
+  get hasUnfetchedSources(): boolean {
+    const fetched = this.fetchedSources()
+    return (
+      (this.useML && !fetched.includes(SuggestionSource.ML)) ||
+      (this.useAI && !fetched.includes(SuggestionSource.AI))
+    )
+  }
+
+  public setSources(ml: boolean, ai: boolean) {
+    if (ml && ai) {
+      this.sourceChange.emit(SuggestionSource.Both)
+    } else if (ml) {
+      this.sourceChange.emit(SuggestionSource.ML)
+    } else if (ai) {
+      this.sourceChange.emit(SuggestionSource.AI)
+    }
+  }
+
   get novelSuggestions(): number {
     return (
       (this.suggestions()?.suggested_correspondents?.length ?? 0) +

src-ui/src/app/components/document-detail/document-detail.component.html

@@ -134,11 +134,15 @@
                 [loading]="suggestionsLoading()"
                 [suggestions]="suggestions()"
                 [aiEnabled]="aiEnabled"
+                [source]="suggestionSource"
+                [defaultSource]="defaultSuggestionSource"
+                [fetchedSources]="fetchedSuggestionSources()"
                 [appliedTags]="documentForm.value.tags"
                 [appliedCorrespondent]="documentForm.value.correspondent"
                 [appliedDocumentType]="documentForm.value.document_type"
                 [appliedStoragePath]="documentForm.value.storage_path"
-                (getSuggestions)="getSuggestions()"
+                (getSuggestions)="getSuggestions($event)"
+                (sourceChange)="suggestionSourceOverride.set($event)"
                 (addTag)="createTag($event)"
                 (addDocumentType)="createDocumentType($event)"
                 (addCorrespondent)="createCorrespondent($event)">

src-ui/src/app/components/document-detail/document-detail.component.spec.ts

@@ -43,7 +43,7 @@ import {
 } from 'src/app/data/filter-rule-type'
 import { StoragePath } from 'src/app/data/storage-path'
 import { Tag } from 'src/app/data/tag'
-import { SETTINGS_KEYS } from 'src/app/data/ui-settings'
+import { SETTINGS_KEYS, SuggestionSource } from 'src/app/data/ui-settings'
 import { PermissionsGuard } from 'src/app/guards/permissions.guard'
 import { CustomDatePipe } from 'src/app/pipes/custom-date.pipe'
 import { DocumentTitlePipe } from 'src/app/pipes/document-title.pipe'
@@ -1528,6 +1528,113 @@ describe('DocumentDetailComponent', () => {
     expect(component.suggestionsLoading()).toBeFalsy()
   })
 
+  it('should get and merge ML and AI suggestions when source is both', () => {
+    settingsService.set(
+      SETTINGS_KEYS.DOCUMENT_EDITING_SUGGESTION_SOURCE,
+      SuggestionSource.Both
+    )
+    const getSetting = settingsService.get.bind(settingsService)
+    jest
+      .spyOn(settingsService, 'get')
+      .mockImplementation((key) =>
+        key === SETTINGS_KEYS.AI_ENABLED ? true : getSetting(key)
+      )
+    const suggestionsSpy = jest
+      .spyOn(documentService, 'getSuggestions')
+      .mockReturnValue(of({ tags: [42], dates: ['2024-01-01'] }))
+    const aiSuggestionsSpy = jest
+      .spyOn(documentService, 'getAiSuggestions')
+      .mockReturnValue(
+        of({ title: 'AI title', tags: [42, 43], suggested_tags: ['New'] })
+      )
+    initNormally()
+    expect(suggestionsSpy).toHaveBeenCalled()
+    expect(aiSuggestionsSpy).toHaveBeenCalled()
+    expect(component.suggestions().title).toEqual('AI title')
+    expect(component.suggestions().tags).toEqual([42, 43])
+    expect(component.suggestions().suggested_tags).toEqual(['New'])
+    expect(component.suggestions().dates).toEqual(['2024-01-01'])
+  })
+
+  it('should only fetch sources not yet fetched for the document', () => {
+    settingsService.set(SETTINGS_KEYS.DOCUMENT_EDITING_AUTO_SUGGEST, false)
+    settingsService.set(
+      SETTINGS_KEYS.DOCUMENT_EDITING_SUGGESTION_SOURCE,
+      SuggestionSource.ML
+    )
+    const getSetting = settingsService.get.bind(settingsService)
+    jest
+      .spyOn(settingsService, 'get')
+      .mockImplementation((key) =>
+        key === SETTINGS_KEYS.AI_ENABLED ? true : getSetting(key)
+      )
+    const suggestionsSpy = jest
+      .spyOn(documentService, 'getSuggestions')
+      .mockReturnValue(of({ tags: [42] }))
+    const aiSuggestionsSpy = jest
+      .spyOn(documentService, 'getAiSuggestions')
+      .mockReturnValue(of({ tags: [43] }))
+    initNormally()
+
+    component.getSuggestions()
+    expect(suggestionsSpy).toHaveBeenCalledTimes(1)
+    expect(aiSuggestionsSpy).not.toHaveBeenCalled()
+
+    component.getSuggestions(SuggestionSource.Both)
+    expect(suggestionsSpy).toHaveBeenCalledTimes(1)
+    expect(aiSuggestionsSpy).toHaveBeenCalledTimes(1)
+    expect(component.suggestions().tags).toEqual([42, 43])
+
+    component.getSuggestions(SuggestionSource.Both)
+    expect(suggestionsSpy).toHaveBeenCalledTimes(1)
+    expect(aiSuggestionsSpy).toHaveBeenCalledTimes(1)
+  })
+
+  it('should use the per-document source override and reset it on document change', () => {
+    settingsService.set(SETTINGS_KEYS.DOCUMENT_EDITING_AUTO_SUGGEST, false)
+    const getSetting = settingsService.get.bind(settingsService)
+    jest
+      .spyOn(settingsService, 'get')
+      .mockImplementation((key) =>
+        key === SETTINGS_KEYS.AI_ENABLED ? true : getSetting(key)
+      )
+    initNormally()
+    expect(component.suggestionSource).toEqual(SuggestionSource.AI)
+    component.suggestionSourceOverride.set(SuggestionSource.ML)
+    expect(component.suggestionSource).toEqual(SuggestionSource.ML)
+
+    jest
+      .spyOn(documentService, 'get')
+      .mockReturnValueOnce(of(Object.assign({}, doc)))
+    ;(component as any).loadDocument(doc.id, true)
+    expect(component.suggestionSourceOverride()).toBeNull()
+    expect(component.fetchedSuggestionSources()).toEqual([])
+  })
+
+  it('should keep suggestions from one source if the other fails', () => {
+    settingsService.set(
+      SETTINGS_KEYS.DOCUMENT_EDITING_SUGGESTION_SOURCE,
+      SuggestionSource.Both
+    )
+    const getSetting = settingsService.get.bind(settingsService)
+    jest
+      .spyOn(settingsService, 'get')
+      .mockImplementation((key) =>
+        key === SETTINGS_KEYS.AI_ENABLED ? true : getSetting(key)
+      )
+    const errorSpy = jest.spyOn(toastService, 'showError')
+    jest
+      .spyOn(documentService, 'getSuggestions')
+      .mockReturnValue(of({ tags: [42] }))
+    jest
+      .spyOn(documentService, 'getAiSuggestions')
+      .mockReturnValue(throwError(() => new Error('failed')))
+    initNormally()
+    expect(errorSpy).toHaveBeenCalled()
+    expect(component.suggestions().tags).toEqual([42])
+    expect(component.fetchedSuggestionSources()).toEqual([SuggestionSource.ML])
+  })
+
   it('should show error if needed for get suggestions', () => {
     const suggestionsSpy = jest.spyOn(documentService, 'getSuggestions')
     const errorSpy = jest.spyOn(toastService, 'showError')

src-ui/src/app/components/document-detail/document-detail.component.ts

@@ -28,7 +28,7 @@ import {
 import { dirtyCheck, DirtyComponent } from '@ngneat/dirty-check-forms'
 import { NgxBootstrapIconsModule } from 'ngx-bootstrap-icons'
 import { DeviceDetectorService } from 'ngx-device-detector'
-import { BehaviorSubject, Observable, of, Subject, timer } from 'rxjs'
+import { BehaviorSubject, merge, Observable, of, Subject, timer } from 'rxjs'
 import {
   catchError,
   debounceTime,
@@ -48,7 +48,10 @@ import { DataType } from 'src/app/data/datatype'
 import { Document, DocumentVersionInfo } from 'src/app/data/document'
 import { DocumentMetadata } from 'src/app/data/document-metadata'
 import { DocumentNote } from 'src/app/data/document-note'
-import { DocumentSuggestions } from 'src/app/data/document-suggestions'
+import {
+  DocumentSuggestions,
+  mergeSuggestions,
+} from 'src/app/data/document-suggestions'
 import { DocumentType } from 'src/app/data/document-type'
 import { FilterRule } from 'src/app/data/filter-rule'
 import {
@@ -63,7 +66,7 @@ import {
 import { ObjectWithId } from 'src/app/data/object-with-id'
 import { StoragePath } from 'src/app/data/storage-path'
 import { Tag } from 'src/app/data/tag'
-import { SETTINGS_KEYS } from 'src/app/data/ui-settings'
+import { SETTINGS_KEYS, SuggestionSource } from 'src/app/data/ui-settings'
 import { User } from 'src/app/data/user'
 import { IfPermissionsDirective } from 'src/app/directives/if-permissions.directive'
 import { CustomDatePipe } from 'src/app/pipes/custom-date.pipe'
@@ -240,6 +243,10 @@ export class DocumentDetailComponent
   private readonly autoSuggestSetting = this.settings.getSignal<boolean>(
     SETTINGS_KEYS.DOCUMENT_EDITING_AUTO_SUGGEST
   )
+  private readonly suggestionSourceSetting =
+    this.settings.getSignal<SuggestionSource>(
+      SETTINGS_KEYS.DOCUMENT_EDITING_SUGGESTION_SOURCE
+    )
   private readonly hiddenFieldsSetting = this.settings.getSignal<
     DocumentDetailFieldID[]
   >(SETTINGS_KEYS.DOCUMENT_DETAILS_HIDDEN_FIELDS)
@@ -261,6 +268,9 @@ export class DocumentDetailComponent
   readonly metadata = signal<DocumentMetadata>(undefined)
   readonly suggestions = signal<DocumentSuggestions>(undefined)
   readonly suggestionsLoading = signal(false)
+  // per-document, resets on navigation
+  readonly suggestionSourceOverride = signal<SuggestionSource>(null)
+  readonly fetchedSuggestionSources = signal<SuggestionSource[]>([])
   readonly users = signal<User[]>(undefined)
 
   readonly title = signal<string>(undefined)
@@ -365,6 +375,15 @@ export class DocumentDetailComponent
     return this.autoSuggestSetting()
   }
 
+  get defaultSuggestionSource(): SuggestionSource {
+    return this.aiEnabled ? this.suggestionSourceSetting() : SuggestionSource.ML
+  }
+
+  get suggestionSource(): SuggestionSource {
+    if (!this.aiEnabled) return SuggestionSource.ML
+    return this.suggestionSourceOverride() ?? this.defaultSuggestionSource
+  }
+
   get archiveContentRenderType(): ContentRenderType {
     const hasArchiveVersion =
       this.metadata()?.has_archive_version ??
@@ -590,6 +609,8 @@ export class DocumentDetailComponent
           }
           this.documentId.set(doc.id)
           this.suggestions.set(null)
+          this.suggestionSourceOverride.set(null)
+          this.fetchedSuggestionSources.set([])
           const openDocument = this.openDocumentService.getOpenDocument(
             this.documentId()
           )
@@ -1077,29 +1098,44 @@ export class DocumentDetailComponent
     return this.documentForm.get('custom_fields') as FormArray
   }
 
-  getSuggestions() {
+  getSuggestions(source: SuggestionSource = this.suggestionSource) {
+    const sources = (
+      source === SuggestionSource.Both
+        ? [SuggestionSource.ML, SuggestionSource.AI]
+        : [source]
+    ).filter((s) => !this.fetchedSuggestionSources().includes(s))
+    if (!sources.length) return
+
     this.suggestionsLoading.set(true)
-    const suggestionsObservable = this.aiEnabled
-      ? this.documentsService.getAiSuggestions(this.documentId())
-      : this.documentsService.getSuggestions(this.documentId())
-    suggestionsObservable
+    merge(
+      ...sources.map((s) =>
+        (s === SuggestionSource.AI
+          ? this.documentsService.getAiSuggestions(this.documentId())
+          : this.documentsService.getSuggestions(this.documentId())
+        ).pipe(
+          first(),
+          map((result) => ({ source: s, result })),
+          catchError((error) => {
+            this.toastService.showError(
+              $localize`Error retrieving suggestions.`,
+              error
+            )
+            return of(null)
+          })
+        )
+      )
+    )
       .pipe(
-        first(),
         takeUntil(this.unsubscribeNotifier),
         takeUntil(this.docChangeNotifier),
         finalize(() => this.suggestionsLoading.set(false))
       )
-      .subscribe({
-        next: (result) => {
-          this.suggestions.set(result)
-        },
-        error: (error) => {
-          this.suggestions.set(null)
-          this.toastService.showError(
-            $localize`Error retrieving suggestions.`,
-            error
-          )
-        },
+      .subscribe((response) => {
+        if (!response) return
+        this.fetchedSuggestionSources.update((f) => [...f, response.source])
+        this.suggestions.set(
+          mergeSuggestions(this.suggestions(), response.result)
+        )
       })
   }
 

src-ui/src/app/data/document-suggestions.ts

@@ -15,3 +15,33 @@ export interface DocumentSuggestions {
 
   dates?: string[] // ISO-formatted date string e.g. 2022-11-03
 }
+
+const union = <T>(a: T[] = [], b: T[] = []): T[] => [...new Set([...a, ...b])]
+
+export function mergeSuggestions(
+  a: DocumentSuggestions,
+  b: DocumentSuggestions
+): DocumentSuggestions {
+  if (!a) return b
+  return {
+    title: a.title || b.title,
+    tags: union(a.tags, b.tags),
+    suggested_tags: union(a.suggested_tags, b.suggested_tags),
+    correspondents: union(a.correspondents, b.correspondents),
+    suggested_correspondents: union(
+      a.suggested_correspondents,
+      b.suggested_correspondents
+    ),
+    document_types: union(a.document_types, b.document_types),
+    suggested_document_types: union(
+      a.suggested_document_types,
+      b.suggested_document_types
+    ),
+    storage_paths: union(a.storage_paths, b.storage_paths),
+    suggested_storage_paths: union(
+      a.suggested_storage_paths,
+      b.suggested_storage_paths
+    ),
+    dates: union(a.dates, b.dates),
+  }
+}

src-ui/src/app/data/ui-settings.ts

@@ -20,6 +20,12 @@ export enum GlobalSearchType {
   TITLE_CONTENT = 'title-content',
 }
 
+export enum SuggestionSource {
+  ML = 'ml',
+  AI = 'ai',
+  Both = 'both',
+}
+
 export enum CollapsibleSection {
   ATTRIBUTES = 'attributes',
 }
@@ -98,6 +104,8 @@ export const SETTINGS_KEYS = {
     'general-settings:document-editing:overlay-thumbnail',
   DOCUMENT_EDITING_AUTO_SUGGEST:
     'general-settings:document-editing:auto-suggest',
+  DOCUMENT_EDITING_SUGGESTION_SOURCE:
+    'general-settings:document-editing:suggestion-source',
   DOCUMENT_DETAILS_HIDDEN_FIELDS:
     'general-settings:document-details:hidden-fields',
   SEARCH_DB_ONLY: 'general-settings:search:db-only',
@@ -326,6 +334,11 @@ export const SETTINGS: UiSetting[] = [
     type: 'boolean',
     default: true,
   },
+  {
+    key: SETTINGS_KEYS.DOCUMENT_EDITING_SUGGESTION_SOURCE,
+    type: 'string',
+    default: SuggestionSource.AI,
+  },
   {
     key: SETTINGS_KEYS.DOCUMENT_DETAILS_HIDDEN_FIELDS,
     type: 'array',

src-ui/src/main.ts

@@ -74,6 +74,7 @@ import {
   clipboardCheckFill,
   clipboardFill,
   clockHistory,
+  cpu,
   creditCard,
   dash,
   dashCircle,
@@ -118,6 +119,7 @@ import {
   infoCircle,
   journalBookmarkFill,
   journals,
+  lightbulb,
   link,
   list,
   listNested,
@@ -322,6 +324,7 @@ const icons = {
   clipboardCheckFill,
   clipboardFill,
   clockHistory,
+  cpu,
   cash,
   creditCard,
   dash,
@@ -367,6 +370,7 @@ const icons = {
   infoCircle,
   journalBookmarkFill,
   journals,
+  lightbulb,
   link,
   list,
   listNested,

src-ui/src/styles.scss

@@ -292,6 +292,7 @@ a.btn-link:active,
 a.btn-link:focus-visible,
 .btn-link:hover,
 .btn-link:active,
+.btn-link.show,
 .btn-link:focus-visible {
   color: var(--pngx-primary-lighten-10) !important;
   .primary-light & {

src-ui/src/test/mocks/pdfjs-web-pdf_viewer.ts

@@ -25,10 +25,20 @@ export class PDFFindController {
   onIsPageVisible?: () => boolean
 }
 
+export const LinkTarget = {
+  NONE: 0,
+  SELF: 1,
+  BLANK: 2,
+  PARENT: 3,
+  TOP: 4,
+}
+
 export class PDFLinkService {
   private document?: unknown
   private viewer?: unknown
 
+  constructor(readonly options: Record<string, unknown> = {}) {}
+
   setDocument(document: unknown): void {
     this.document = document
   }

src/conftest.py

@@ -11,6 +11,8 @@ from typing import TYPE_CHECKING
 
 import pytest
 
+from paperless_testing import samples
+
 if TYPE_CHECKING:
     from collections.abc import Generator
     from pathlib import Path
@@ -149,3 +151,39 @@ def fake_progress_manager(
 
     monkeypatch.setattr("documents.tasks.ProgressManager", FakeProgressManager)
     return FakeProgressManager
+
+
+@pytest.fixture(scope="session")
+def shared_samples_dir() -> Path:
+    """Directory of sample files used by more than one app's tests."""
+    return samples.SHARED_SAMPLES_DIR
+
+
+@pytest.fixture(scope="session")
+def simple_digital_pdf_file() -> Path:
+    """One-page PDF with a text layer."""
+    return samples.SIMPLE_DIGITAL_PDF
+
+
+@pytest.fixture(scope="session")
+def multi_page_digital_pdf_file() -> Path:
+    """Three-page PDF with a text layer."""
+    return samples.MULTI_PAGE_DIGITAL_PDF
+
+
+@pytest.fixture(scope="session")
+def with_form_pdf_file() -> Path:
+    """PDF containing a fillable form."""
+    return samples.WITH_FORM_PDF
+
+
+@pytest.fixture(scope="session")
+def multi_page_images_pdf_file() -> Path:
+    """Multi-page PDF of scanned images, no text layer."""
+    return samples.MULTI_PAGE_IMAGES_PDF
+
+
+@pytest.fixture(scope="session")
+def thumbnail_webp_file() -> Path:
+    """Small WebP thumbnail."""
+    return samples.THUMBNAIL_WEBP

src/documents/serialisers.py

@@ -1079,6 +1079,16 @@ class DocumentSerializer(
     )
 
     def get_page_count(self, obj) -> int | None:
+        # Like content versions get their own page count from the newest version,
+        # use the prefetched versions cache to avoid an extra query
+        prefetched_cache = getattr(obj, "_prefetched_objects_cache", None)
+        prefetched_versions = (
+            prefetched_cache.get("versions")
+            if isinstance(prefetched_cache, dict)
+            else None
+        )
+        if obj.root_document_id is None and prefetched_versions:
+            return sort_versions_newest_first(prefetched_versions)[0].page_count
         return obj.page_count
 
     @extend_schema_field(DuplicateDocumentSummarySerializer(many=True))

src/documents/templates/index.html

@@ -12,7 +12,7 @@
 	<meta name="robots" content="noindex,nofollow">
 	<meta name="author" content="The Paperless-ngx Team">
 	<link rel="icon" type="image/x-icon" href="favicon.ico">
-	<link rel="manifest" href="{% static webmanifest %}">
+	<link rel="manifest" href="{% static webmanifest %}" crossorigin="use-credentials">
 	<link rel="stylesheet" href="{% static styles_css %}">
 	<link rel="apple-touch-icon" href="{% static apple_touch_icon %}">
 </head>

src/documents/tests/conftest.py

@@ -12,29 +12,25 @@ if TYPE_CHECKING:
     from paperless_testing.dirs import PaperlessDirs
 
 
-@pytest.fixture(scope="session")
-def document_samples_dir() -> Path:
-    """Path to the shared test sample documents."""
-    return Path(__file__).parent / "samples" / "documents"
-
-
 @pytest.fixture()
 def sample_doc(
     paperless_dirs: "PaperlessDirs",
-    document_samples_dir: Path,
+    simple_digital_pdf_file: Path,
+    multi_page_images_pdf_file: Path,
+    thumbnail_webp_file: Path,
 ) -> "Document":
     """Create a document with valid files and matching checksums."""
     with filelock.FileLock(paperless_dirs.media_lock):
         shutil.copy(
-            document_samples_dir / "originals" / "0000001.pdf",
+            simple_digital_pdf_file,
             paperless_dirs.originals_dir / "0000001.pdf",
         )
         shutil.copy(
-            document_samples_dir / "archive" / "0000001.pdf",
+            multi_page_images_pdf_file,
             paperless_dirs.archive_dir / "0000001.pdf",
         )
         shutil.copy(
-            document_samples_dir / "thumbnails" / "0000001.webp",
+            thumbnail_webp_file,
             paperless_dirs.thumbnail_dir / "0000001.webp",
         )
 

src/documents/tests/samples/simple.txt

@@ -1 +0,0 @@
-This is a test file.

src/documents/tests/test_api_bulk_download.py

@@ -53,7 +53,7 @@ class TestBulkDownload(DirectoriesMixin, SampleDirMixin, APITestCase):
             archive_checksum="D",
         )
 
-        shutil.copy(self.SAMPLE_DIR / "simple.pdf", self.doc2.source_path)
+        shutil.copy(self.SIMPLE_PDF, self.doc2.source_path)
         shutil.copy(self.SAMPLE_DIR / "simple.png", self.doc2b.source_path)
         shutil.copy(self.SAMPLE_DIR / "simple.jpg", self.doc3.source_path)
         shutil.copy(self.SAMPLE_DIR / "test_with_bom.pdf", self.doc3.archive_path)

src/documents/tests/test_api_document_versions.py

@@ -19,6 +19,7 @@ from documents.models import Document
 from documents.versioning import annotate_effective_content
 from documents.views import DocumentSelectionMixin
 from paperless_testing.dirs import DirectoriesMixin
+from paperless_testing.factories import DocumentFactory
 from paperless_testing.factories import UserFactory
 from paperless_testing.http import read_streaming_response
 from paperless_testing.permissions import grant_global
@@ -821,6 +822,26 @@ class TestDocumentVersioningApi(DirectoriesMixin, APITestCase):
         self.assertEqual(resp.status_code, status.HTTP_200_OK)
         self.assertEqual(resp.data["content"], "v1-content")
 
+    def test_page_count_resolves_to_latest_version(self) -> None:
+        root = DocumentFactory(page_count=2)
+        DocumentFactory(root_document=root, version_index=1, page_count=1)
+        unversioned = DocumentFactory(page_count=5)
+
+        resp = self.client.get("/api/documents/?fields=id,page_count")
+        self.assertEqual(resp.status_code, status.HTTP_200_OK)
+        self.assertEqual(
+            {doc["id"]: doc["page_count"] for doc in resp.data["results"]},
+            {root.id: 1, unversioned.id: 5},
+        )
+
+        resp = self.client.get(f"/api/documents/{root.id}/")
+        self.assertEqual(resp.status_code, status.HTTP_200_OK)
+        self.assertEqual(resp.data["page_count"], 1)
+
+        resp = self.client.get(f"/api/documents/{root.id}/?version={root.id}")
+        self.assertEqual(resp.status_code, status.HTTP_200_OK)
+        self.assertEqual(resp.data["page_count"], 2)
+
     def _make_root_with_out_of_order_versions(self) -> tuple[Document, ...]:
         """
         A root whose newest version has a *lower* id than an older one, which is

src/documents/tests/test_api_documents.py

@@ -56,6 +56,8 @@ from paperless_testing.http import read_streaming_response
 from paperless_testing.permissions import grant_all_global
 from paperless_testing.permissions import grant_global
 from paperless_testing.permissions import grant_object
+from paperless_testing.samples import SIMPLE_DIGITAL_PDF
+from paperless_testing.samples import THUMBNAIL_WEBP
 
 
 class TestDocumentApi(DirectoriesMixin, ConsumeTaskMixin, APITestCase):
@@ -1852,7 +1854,11 @@ class TestDocumentApi(DirectoriesMixin, ConsumeTaskMixin, APITestCase):
             id=str(uuid.uuid4()),
         )
 
-        with (Path(__file__).parent / "samples" / "simple.pdf").open("rb") as f:
+        with SimpleUploadedFile(
+            "simple.pdf",
+            SIMPLE_DIGITAL_PDF.read_bytes(),
+            content_type="application/pdf",
+        ) as f:
             response = self.client.post(
                 "/api/documents/post_document/",
                 {"document": f},
@@ -1880,7 +1886,7 @@ class TestDocumentApi(DirectoriesMixin, ConsumeTaskMixin, APITestCase):
 
         payload = SimpleUploadedFile(
             "../../outside.pdf",
-            (Path(__file__).parent / "samples" / "simple.pdf").read_bytes(),
+            SIMPLE_DIGITAL_PDF.read_bytes(),
             content_type="application/pdf",
         )
 
@@ -1909,7 +1915,7 @@ class TestDocumentApi(DirectoriesMixin, ConsumeTaskMixin, APITestCase):
             id=str(uuid.uuid4()),
         )
 
-        pdf_bytes = (Path(__file__).parent / "samples" / "simple.pdf").read_bytes()
+        pdf_bytes = SIMPLE_DIGITAL_PDF.read_bytes()
         boundary = "paperless-boundary"
         payload = (
             (
@@ -1985,7 +1991,7 @@ class TestDocumentApi(DirectoriesMixin, ConsumeTaskMixin, APITestCase):
     def test_upload_insufficient_permissions(self) -> None:
         self.client.force_authenticate(user=UserFactory(username="testuser2"))
 
-        with (Path(__file__).parent / "samples" / "simple.pdf").open("rb") as f:
+        with SIMPLE_DIGITAL_PDF.open("rb") as f:
             response = self.client.post(
                 "/api/documents/post_document/",
                 {"document": f},
@@ -1998,7 +2004,11 @@ class TestDocumentApi(DirectoriesMixin, ConsumeTaskMixin, APITestCase):
             id=str(uuid.uuid4()),
         )
 
-        with (Path(__file__).parent / "samples" / "simple.pdf").open("rb") as f:
+        with SimpleUploadedFile(
+            "simple.pdf",
+            SIMPLE_DIGITAL_PDF.read_bytes(),
+            content_type="application/pdf",
+        ) as f:
             response = self.client.post(
                 "/api/documents/post_document/",
                 {
@@ -2031,7 +2041,7 @@ class TestDocumentApi(DirectoriesMixin, ConsumeTaskMixin, APITestCase):
             id=str(uuid.uuid4()),
         )
 
-        with (Path(__file__).parent / "samples" / "simple.pdf").open("rb") as f:
+        with SIMPLE_DIGITAL_PDF.open("rb") as f:
             response = self.client.post(
                 "/api/documents/post_document/",
                 {"documenst": f},
@@ -2057,7 +2067,7 @@ class TestDocumentApi(DirectoriesMixin, ConsumeTaskMixin, APITestCase):
             id=str(uuid.uuid4()),
         )
 
-        with (Path(__file__).parent / "samples" / "simple.pdf").open("rb") as f:
+        with SIMPLE_DIGITAL_PDF.open("rb") as f:
             response = self.client.post(
                 "/api/documents/post_document/",
                 {"document": f, "title": "my custom title"},
@@ -2077,7 +2087,7 @@ class TestDocumentApi(DirectoriesMixin, ConsumeTaskMixin, APITestCase):
         )
 
         c = Correspondent.objects.create(name="test-corres")
-        with (Path(__file__).parent / "samples" / "simple.pdf").open("rb") as f:
+        with SIMPLE_DIGITAL_PDF.open("rb") as f:
             response = self.client.post(
                 "/api/documents/post_document/",
                 {"document": f, "correspondent": c.id},
@@ -2096,7 +2106,7 @@ class TestDocumentApi(DirectoriesMixin, ConsumeTaskMixin, APITestCase):
             id=str(uuid.uuid4()),
         )
 
-        with (Path(__file__).parent / "samples" / "simple.pdf").open("rb") as f:
+        with SIMPLE_DIGITAL_PDF.open("rb") as f:
             response = self.client.post(
                 "/api/documents/post_document/",
                 {"document": f, "correspondent": 3456},
@@ -2111,7 +2121,7 @@ class TestDocumentApi(DirectoriesMixin, ConsumeTaskMixin, APITestCase):
         )
 
         dt = DocumentType.objects.create(name="invoice")
-        with (Path(__file__).parent / "samples" / "simple.pdf").open("rb") as f:
+        with SIMPLE_DIGITAL_PDF.open("rb") as f:
             response = self.client.post(
                 "/api/documents/post_document/",
                 {"document": f, "document_type": dt.id},
@@ -2130,7 +2140,7 @@ class TestDocumentApi(DirectoriesMixin, ConsumeTaskMixin, APITestCase):
             id=str(uuid.uuid4()),
         )
 
-        with (Path(__file__).parent / "samples" / "simple.pdf").open("rb") as f:
+        with SIMPLE_DIGITAL_PDF.open("rb") as f:
             response = self.client.post(
                 "/api/documents/post_document/",
                 {"document": f, "document_type": 34578},
@@ -2145,7 +2155,7 @@ class TestDocumentApi(DirectoriesMixin, ConsumeTaskMixin, APITestCase):
         )
 
         sp = StoragePath.objects.create(name="invoices")
-        with (Path(__file__).parent / "samples" / "simple.pdf").open("rb") as f:
+        with SIMPLE_DIGITAL_PDF.open("rb") as f:
             response = self.client.post(
                 "/api/documents/post_document/",
                 {"document": f, "storage_path": sp.id},
@@ -2164,7 +2174,7 @@ class TestDocumentApi(DirectoriesMixin, ConsumeTaskMixin, APITestCase):
             id=str(uuid.uuid4()),
         )
 
-        with (Path(__file__).parent / "samples" / "simple.pdf").open("rb") as f:
+        with SIMPLE_DIGITAL_PDF.open("rb") as f:
             response = self.client.post(
                 "/api/documents/post_document/",
                 {"document": f, "storage_path": 34578},
@@ -2180,7 +2190,7 @@ class TestDocumentApi(DirectoriesMixin, ConsumeTaskMixin, APITestCase):
 
         t1 = Tag.objects.create(name="tag1")
         t2 = Tag.objects.create(name="tag2")
-        with (Path(__file__).parent / "samples" / "simple.pdf").open("rb") as f:
+        with SIMPLE_DIGITAL_PDF.open("rb") as f:
             response = self.client.post(
                 "/api/documents/post_document/",
                 {"document": f, "tags": [t2.id, t1.id]},
@@ -2201,7 +2211,7 @@ class TestDocumentApi(DirectoriesMixin, ConsumeTaskMixin, APITestCase):
 
         t1 = Tag.objects.create(name="tag1")
         t2 = Tag.objects.create(name="tag2")
-        with (Path(__file__).parent / "samples" / "simple.pdf").open("rb") as f:
+        with SIMPLE_DIGITAL_PDF.open("rb") as f:
             response = self.client.post(
                 "/api/documents/post_document/",
                 {"document": f, "tags": [t2.id, t1.id, 734563]},
@@ -2225,7 +2235,7 @@ class TestDocumentApi(DirectoriesMixin, ConsumeTaskMixin, APITestCase):
             0,
             tzinfo=zoneinfo.ZoneInfo("America/Los_Angeles"),
         )
-        with (Path(__file__).parent / "samples" / "simple.pdf").open("rb") as f:
+        with SIMPLE_DIGITAL_PDF.open("rb") as f:
             response = self.client.post(
                 "/api/documents/post_document/",
                 {"document": f, "created": created},
@@ -2241,7 +2251,11 @@ class TestDocumentApi(DirectoriesMixin, ConsumeTaskMixin, APITestCase):
             id=str(uuid.uuid4()),
         )
 
-        with (Path(__file__).parent / "samples" / "simple.pdf").open("rb") as f:
+        with SimpleUploadedFile(
+            "simple.pdf",
+            SIMPLE_DIGITAL_PDF.read_bytes(),
+            content_type="application/pdf",
+        ) as f:
             response = self.client.post(
                 "/api/documents/post_document/",
                 {"document": f, "archive_serial_number": 500},
@@ -2268,7 +2282,11 @@ class TestDocumentApi(DirectoriesMixin, ConsumeTaskMixin, APITestCase):
             data_type=CustomField.FieldDataType.STRING,
         )
 
-        with (Path(__file__).parent / "samples" / "simple.pdf").open("rb") as f:
+        with SimpleUploadedFile(
+            "simple.pdf",
+            SIMPLE_DIGITAL_PDF.read_bytes(),
+            content_type="application/pdf",
+        ) as f:
             response = self.client.post(
                 "/api/documents/post_document/",
                 {
@@ -2323,7 +2341,7 @@ class TestDocumentApi(DirectoriesMixin, ConsumeTaskMixin, APITestCase):
         w1.actions.add(action1)
         w1.save()
 
-        with (Path(__file__).parent / "samples" / "simple.pdf").open("rb") as f:
+        with SIMPLE_DIGITAL_PDF.open("rb") as f:
             response = self.client.post(
                 "/api/documents/post_document/",
                 {
@@ -2364,7 +2382,11 @@ class TestDocumentApi(DirectoriesMixin, ConsumeTaskMixin, APITestCase):
             data_type=CustomField.FieldDataType.INT,
         )
 
-        with (Path(__file__).parent / "samples" / "simple.pdf").open("rb") as f:
+        with SimpleUploadedFile(
+            "simple.pdf",
+            SIMPLE_DIGITAL_PDF.read_bytes(),
+            content_type="application/pdf",
+        ) as f:
             response = self.client.post(
                 "/api/documents/post_document/",
                 {
@@ -2413,7 +2435,7 @@ class TestDocumentApi(DirectoriesMixin, ConsumeTaskMixin, APITestCase):
         ]
 
         for payload in error_payloads:
-            with (Path(__file__).parent / "samples" / "simple.pdf").open("rb") as f:
+            with SIMPLE_DIGITAL_PDF.open("rb") as f:
                 data = {"document": f, **payload}
                 response = self.client.post(
                     "/api/documents/post_document/",
@@ -2471,7 +2493,7 @@ class TestDocumentApi(DirectoriesMixin, ConsumeTaskMixin, APITestCase):
             id=str(uuid.uuid4()),
         )
 
-        with (Path(__file__).parent / "samples" / "simple.pdf").open("rb") as f:
+        with SIMPLE_DIGITAL_PDF.open("rb") as f:
             response = self.client.post(
                 "/api/documents/post_document/",
                 {"document": f, "from_webui": True},
@@ -2510,14 +2532,8 @@ class TestDocumentApi(DirectoriesMixin, ConsumeTaskMixin, APITestCase):
             archive_filename="archive.pdf",
         )
 
-        source_file: Path = (
-            Path(__file__).parent
-            / "samples"
-            / "documents"
-            / "thumbnails"
-            / "0000001.webp"
-        )
-        archive_file: Path = Path(__file__).parent / "samples" / "simple.pdf"
+        source_file: Path = THUMBNAIL_WEBP
+        archive_file: Path = SIMPLE_DIGITAL_PDF
 
         shutil.copy(source_file, doc.source_path)
         shutil.copy(archive_file, doc.archive_path)
@@ -2550,7 +2566,7 @@ class TestDocumentApi(DirectoriesMixin, ConsumeTaskMixin, APITestCase):
             mime_type="application/pdf",
         )
 
-        shutil.copy(Path(__file__).parent / "samples" / "simple.pdf", doc.source_path)
+        shutil.copy(SIMPLE_DIGITAL_PDF, doc.source_path)
 
         response = self.client.get(f"/api/documents/{doc.pk}/metadata/")
         self.assertEqual(response.status_code, status.HTTP_200_OK)
@@ -4288,8 +4304,8 @@ class TestDocumentApi(DirectoriesMixin, ConsumeTaskMixin, APITestCase):
             filename="test2.pdf",
         )
 
-        archive_file = Path(__file__).parent / "samples" / "simple.pdf"
-        source_file = Path(__file__).parent / "samples" / "simple.pdf"
+        archive_file = SIMPLE_DIGITAL_PDF
+        source_file = SIMPLE_DIGITAL_PDF
 
         shutil.copy(archive_file, doc.archive_path)
         shutil.copy(source_file, doc2.source_path)

src/documents/tests/test_api_email.py

@@ -12,6 +12,9 @@ from documents.tests.utils import SampleDirMixin
 from paperless_testing.dirs import DirectoriesMixin
 from paperless_testing.factories import UserFactory
 from paperless_testing.permissions import grant_global
+from paperless_testing.samples import MULTI_PAGE_DIGITAL_PDF
+from paperless_testing.samples import SIMPLE_DIGITAL_PDF
+from paperless_testing.samples import WITH_FORM_PDF
 
 
 class TestEmail(DirectoriesMixin, SampleDirMixin, APITestCase):
@@ -42,15 +45,15 @@ class TestEmail(DirectoriesMixin, SampleDirMixin, APITestCase):
 
         # Copy sample files to document paths (using different files to distinguish versions)
         shutil.copy(
-            self.SAMPLE_DIR / "documents" / "originals" / "0000001.pdf",
+            SIMPLE_DIGITAL_PDF,
             self.doc1.archive_path,
         )
         shutil.copy(
-            self.SAMPLE_DIR / "documents" / "originals" / "0000002.pdf",
+            MULTI_PAGE_DIGITAL_PDF,
             self.doc1.source_path,
         )
         shutil.copy(
-            self.SAMPLE_DIR / "documents" / "originals" / "0000003.pdf",
+            WITH_FORM_PDF,
             self.doc2.source_path,
         )
 
@@ -377,7 +380,7 @@ class TestEmail(DirectoriesMixin, SampleDirMixin, APITestCase):
             checksum="3",
             filename="test3.pdf",
         )
-        shutil.copy(self.SAMPLE_DIR / "simple.pdf", doc3.source_path)
+        shutil.copy(self.SIMPLE_PDF, doc3.source_path)
 
         doc4 = Document.objects.create(
             title="test1",
@@ -386,7 +389,7 @@ class TestEmail(DirectoriesMixin, SampleDirMixin, APITestCase):
             checksum="4",
             filename="test4.pdf",
         )
-        shutil.copy(self.SAMPLE_DIR / "simple.pdf", doc4.source_path)
+        shutil.copy(self.SIMPLE_PDF, doc4.source_path)
 
         response = self.client.post(
             self.ENDPOINT,

src/documents/tests/test_barcodes.py

@@ -150,7 +150,7 @@ class TestBarcode(
             - No barcodes detected
             - No pages to split on
         """
-        test_file = self.SAMPLE_DIR / "simple.pdf"
+        test_file = self.SIMPLE_PDF
         with self.get_reader(test_file) as reader:
             reader.detect()
             separator_page_numbers = reader.get_separation_pages()
@@ -442,7 +442,7 @@ class TestBarcode(
         THEN:
             - Nothing happens
         """
-        test_file = self.SAMPLE_DIR / "simple.pdf"
+        test_file = self.SIMPLE_PDF
 
         with self.get_reader(test_file) as reader:
             try:

src/documents/tests/test_bulk_edit.py

@@ -24,6 +24,9 @@ from documents.models import Tag
 from documents.permissions import set_permissions_for_objects
 from paperless_testing.dirs import DirectoriesMixin
 from paperless_testing.permissions import grant_object
+from paperless_testing.samples import MULTI_PAGE_DIGITAL_PDF
+from paperless_testing.samples import SIMPLE_DIGITAL_PDF
+from paperless_testing.samples import WITH_FORM_PDF
 
 
 class TestBulkEdit(DirectoriesMixin, TestCase):
@@ -701,47 +704,27 @@ class TestPDFActions(DirectoriesMixin, TestCase):
         super().setUp()
         sample1 = self.dirs.scratch_dir / "sample.pdf"
         shutil.copy(
-            Path(__file__).parent
-            / "samples"
-            / "documents"
-            / "originals"
-            / "0000001.pdf",
+            SIMPLE_DIGITAL_PDF,
             sample1,
         )
         sample1_archive = self.dirs.archive_dir / "sample_archive.pdf"
         shutil.copy(
-            Path(__file__).parent
-            / "samples"
-            / "documents"
-            / "originals"
-            / "0000001.pdf",
+            SIMPLE_DIGITAL_PDF,
             sample1_archive,
         )
         sample2 = self.dirs.scratch_dir / "sample2.pdf"
         shutil.copy(
-            Path(__file__).parent
-            / "samples"
-            / "documents"
-            / "originals"
-            / "0000002.pdf",
+            MULTI_PAGE_DIGITAL_PDF,
             sample2,
         )
         sample2_archive = self.dirs.archive_dir / "sample2_archive.pdf"
         shutil.copy(
-            Path(__file__).parent
-            / "samples"
-            / "documents"
-            / "originals"
-            / "0000002.pdf",
+            MULTI_PAGE_DIGITAL_PDF,
             sample2_archive,
         )
         sample3 = self.dirs.scratch_dir / "sample3.pdf"
         shutil.copy(
-            Path(__file__).parent
-            / "samples"
-            / "documents"
-            / "originals"
-            / "0000003.pdf",
+            WITH_FORM_PDF,
             sample3,
         )
         self.doc1 = Document.objects.create(
@@ -775,11 +758,7 @@ class TestPDFActions(DirectoriesMixin, TestCase):
         )
         img_doc_archive = self.dirs.archive_dir / "sample_image.pdf"
         shutil.copy(
-            Path(__file__).parent
-            / "samples"
-            / "documents"
-            / "originals"
-            / "0000001.pdf",
+            SIMPLE_DIGITAL_PDF,
             img_doc_archive,
         )
         self.img_doc = Document.objects.create(

src/documents/tests/test_consumer.py

@@ -36,6 +36,9 @@ from paperless_testing.assertions import FileSystemAssertsMixin
 from paperless_testing.dirs import DirectoriesMixin
 from paperless_testing.factories import UserFactory
 from paperless_testing.fakes.progress import FakeProgressManager
+from paperless_testing.samples import MULTI_PAGE_DIGITAL_PDF
+from paperless_testing.samples import MULTI_PAGE_IMAGES_PDF
+from paperless_testing.samples import SIMPLE_DIGITAL_PDF
 
 
 class _BaseNewStyleParser:
@@ -112,9 +115,7 @@ class _BaseNewStyleParser:
 
 
 class DummyParser(_BaseNewStyleParser):
-    _ARCHIVE_SRC = (
-        Path(__file__).parent / "samples" / "documents" / "archive" / "0000001.pdf"
-    )
+    _ARCHIVE_SRC = MULTI_PAGE_IMAGES_PDF
 
     def parse(self, document_path, mime_type, *, produce_archive: bool = True) -> None:
         self._text = "The Text"
@@ -200,33 +201,19 @@ class TestConsumer(
         self.addCleanup(patcher.stop)
 
     def get_test_file(self):
-        src = (
-            Path(__file__).parent
-            / "samples"
-            / "documents"
-            / "originals"
-            / "0000001.pdf"
-        )
+        src = SIMPLE_DIGITAL_PDF
         dst = self.dirs.scratch_dir / "sample.pdf"
         shutil.copy(src, dst)
         return dst
 
     def get_test_file2(self):
-        src = (
-            Path(__file__).parent
-            / "samples"
-            / "documents"
-            / "originals"
-            / "0000002.pdf"
-        )
+        src = MULTI_PAGE_DIGITAL_PDF
         dst = self.dirs.scratch_dir / "sample2.pdf"
         shutil.copy(src, dst)
         return dst
 
     def get_test_archive_file(self):
-        src = (
-            Path(__file__).parent / "samples" / "documents" / "archive" / "0000001.pdf"
-        )
+        src = MULTI_PAGE_IMAGES_PDF
         dst = self.dirs.scratch_dir / "sample_archive.pdf"
         shutil.copy(src, dst)
         return dst
@@ -1062,7 +1049,7 @@ class TestConsumer(
     @mock.patch("documents.consumer.get_parser_registry")
     def test_similar_filenames(self, m) -> None:
         shutil.copy(
-            Path(__file__).parent / "samples" / "simple.pdf",
+            SIMPLE_DIGITAL_PDF,
             settings.CONSUMPTION_DIR / "simple.pdf",
         )
         shutil.copy(
@@ -1603,13 +1590,7 @@ class TestConsumerRemoteOCR(
         self.addCleanup(patcher.stop)
 
     def _consume(self, *, overrides: DocumentMetadataOverrides | None = None) -> bool:
-        src = (
-            Path(__file__).parent
-            / "samples"
-            / "documents"
-            / "originals"
-            / "0000001.pdf"
-        )
+        src = SIMPLE_DIGITAL_PDF
         dst = self.dirs.scratch_dir / "sample.pdf"
         shutil.copy(src, dst)
 

src/documents/tests/test_double_sided.py

@@ -37,12 +37,15 @@ class TestDoubleSided(
         self.double_sided_dir.mkdir()
         self.staging_file = self.dirs.scratch_dir / STAGING_FILE_NAME
 
+    def _sample(self, name: str) -> Path:
+        return self.SIMPLE_PDF if name == "simple.pdf" else self.SAMPLE_DIR / name
+
     def consume_file(self, srcname, dstname: str | Path = "foo.pdf"):
         """
         Starts the consume process and also ensures the
         destination file does not exist afterwards
         """
-        src = self.SAMPLE_DIR / srcname
+        src = self._sample(srcname)
         dst = self.double_sided_dir / dstname
         dst.parent.mkdir(parents=True, exist_ok=True)
         shutil.copy(src, dst)
@@ -57,7 +60,7 @@ class TestDoubleSided(
         return msg
 
     def create_staging_file(self, src="double-sided-odd.pdf", datetime=None) -> None:
-        shutil.copy(self.SAMPLE_DIR / src, self.staging_file)
+        shutil.copy(self._sample(src), self.staging_file)
         if datetime is None:
             datetime = dt.datetime.now()
         os.utime(str(self.staging_file), (datetime.timestamp(),) * 2)

src/documents/tests/test_management.py

@@ -22,8 +22,9 @@ from documents.models import Document
 from documents.tasks import update_document_content_maybe_archive_file
 from paperless_testing.assertions import FileSystemAssertsMixin
 from paperless_testing.dirs import DirectoriesMixin
+from paperless_testing.samples import SIMPLE_DIGITAL_PDF
 
-sample_file: Path = Path(__file__).parent / "samples" / "simple.pdf"
+sample_file: Path = SIMPLE_DIGITAL_PDF
 
 
 @pytest.mark.management

src/documents/tests/test_management_exporter.py

@@ -51,6 +51,7 @@ from paperless_testing.assertions import FileSystemAssertsMixin
 from paperless_testing.dirs import DirectoriesMixin
 from paperless_testing.dirs import paperless_environment
 from paperless_testing.permissions import grant_object
+from paperless_testing.samples import install_document_samples
 
 
 @pytest.mark.management
@@ -196,10 +197,7 @@ class TestExportImport(
 
     def test_exporter(self, *, use_filename_format=False) -> None:
         shutil.rmtree(Path(self.dirs.media_dir) / "documents")
-        shutil.copytree(
-            Path(__file__).parent / "samples" / "documents",
-            Path(self.dirs.media_dir) / "documents",
-        )
+        install_document_samples(Path(self.dirs.media_dir) / "documents")
 
         num_permission_objects = Permission.objects.count()
 
@@ -303,10 +301,7 @@ class TestExportImport(
 
     def test_exporter_with_filename_format(self) -> None:
         shutil.rmtree(Path(self.dirs.media_dir) / "documents")
-        shutil.copytree(
-            Path(__file__).parent / "samples" / "documents",
-            Path(self.dirs.media_dir) / "documents",
-        )
+        install_document_samples(Path(self.dirs.media_dir) / "documents")
 
         with override_settings(
             FILENAME_FORMAT="{created_year}/{correspondent}/{title}",
@@ -315,10 +310,7 @@ class TestExportImport(
 
     def test_exporter_includes_share_links_and_bundles(self) -> None:
         shutil.rmtree(Path(self.dirs.media_dir) / "documents")
-        shutil.copytree(
-            Path(__file__).parent / "samples" / "documents",
-            Path(self.dirs.media_dir) / "documents",
-        )
+        install_document_samples(Path(self.dirs.media_dir) / "documents")
 
         share_link = ShareLink.objects.create(
             slug="share-link-slug",
@@ -417,10 +409,7 @@ class TestExportImport(
 
     def test_update_export_changed_time(self) -> None:
         shutil.rmtree(Path(self.dirs.media_dir) / "documents")
-        shutil.copytree(
-            Path(__file__).parent / "samples" / "documents",
-            Path(self.dirs.media_dir) / "documents",
-        )
+        install_document_samples(Path(self.dirs.media_dir) / "documents")
 
         self._do_export()
         self.assertIsFile(self.target / "manifest.json")
@@ -456,10 +445,7 @@ class TestExportImport(
 
     def test_update_export_changed_checksum(self) -> None:
         shutil.rmtree(Path(self.dirs.media_dir) / "documents")
-        shutil.copytree(
-            Path(__file__).parent / "samples" / "documents",
-            Path(self.dirs.media_dir) / "documents",
-        )
+        install_document_samples(Path(self.dirs.media_dir) / "documents")
 
         self._do_export()
 
@@ -486,10 +472,7 @@ class TestExportImport(
 
     def test_update_export_deleted_document(self) -> None:
         shutil.rmtree(Path(self.dirs.media_dir) / "documents")
-        shutil.copytree(
-            Path(__file__).parent / "samples" / "documents",
-            Path(self.dirs.media_dir) / "documents",
-        )
+        install_document_samples(Path(self.dirs.media_dir) / "documents")
 
         manifest = self._do_export()
 
@@ -521,10 +504,7 @@ class TestExportImport(
     @override_settings(FILENAME_FORMAT="{title}/{correspondent}")
     def test_update_export_changed_location(self) -> None:
         shutil.rmtree(Path(self.dirs.media_dir) / "documents")
-        shutil.copytree(
-            Path(__file__).parent / "samples" / "documents",
-            Path(self.dirs.media_dir) / "documents",
-        )
+        install_document_samples(Path(self.dirs.media_dir) / "documents")
 
         self._do_export(use_filename_format=True)
         self.assertIsFile(self.target / "wow1" / "c.pdf")
@@ -566,10 +546,7 @@ class TestExportImport(
             - Zipfile contains exported files
         """
         shutil.rmtree(Path(self.dirs.media_dir) / "documents")
-        shutil.copytree(
-            Path(__file__).parent / "samples" / "documents",
-            Path(self.dirs.media_dir) / "documents",
-        )
+        install_document_samples(Path(self.dirs.media_dir) / "documents")
 
         args = ["document_exporter", self.target, "--zip"]
 
@@ -598,10 +575,7 @@ class TestExportImport(
             - Zipfile contains exported files
         """
         shutil.rmtree(Path(self.dirs.media_dir) / "documents")
-        shutil.copytree(
-            Path(__file__).parent / "samples" / "documents",
-            Path(self.dirs.media_dir) / "documents",
-        )
+        install_document_samples(Path(self.dirs.media_dir) / "documents")
 
         args = ["document_exporter", self.target, "--zip", "--use-filename-format"]
 
@@ -637,10 +611,7 @@ class TestExportImport(
             - The existing file and directory in target are removed
         """
         shutil.rmtree(Path(self.dirs.media_dir) / "documents")
-        shutil.copytree(
-            Path(__file__).parent / "samples" / "documents",
-            Path(self.dirs.media_dir) / "documents",
-        )
+        install_document_samples(Path(self.dirs.media_dir) / "documents")
 
         # Create stuff in target directory
         existing_file = self.target / "test.txt"
@@ -736,10 +707,7 @@ class TestExportImport(
             - Documents can be imported again
         """
         shutil.rmtree(Path(self.dirs.media_dir) / "documents")
-        shutil.copytree(
-            Path(__file__).parent / "samples" / "documents",
-            Path(self.dirs.media_dir) / "documents",
-        )
+        install_document_samples(Path(self.dirs.media_dir) / "documents")
 
         manifest = self._do_export()
         has_archive = False
@@ -782,10 +750,7 @@ class TestExportImport(
             - Documents can be imported again
         """
         shutil.rmtree(Path(self.dirs.media_dir) / "documents")
-        shutil.copytree(
-            Path(__file__).parent / "samples" / "documents",
-            Path(self.dirs.media_dir) / "documents",
-        )
+        install_document_samples(Path(self.dirs.media_dir) / "documents")
 
         manifest = self._do_export()
         has_thumbnail = False
@@ -830,10 +795,7 @@ class TestExportImport(
             - Documents can be imported again
         """
         shutil.rmtree(Path(self.dirs.media_dir) / "documents")
-        shutil.copytree(
-            Path(__file__).parent / "samples" / "documents",
-            Path(self.dirs.media_dir) / "documents",
-        )
+        install_document_samples(Path(self.dirs.media_dir) / "documents")
 
         manifest = self._do_export(split_manifest=True)
         has_document = False
@@ -866,10 +828,7 @@ class TestExportImport(
             - Documents can be imported again
         """
         shutil.rmtree(Path(self.dirs.media_dir) / "documents")
-        shutil.copytree(
-            Path(__file__).parent / "samples" / "documents",
-            Path(self.dirs.media_dir) / "documents",
-        )
+        install_document_samples(Path(self.dirs.media_dir) / "documents")
 
         self._do_export(use_folder_prefix=True)
 
@@ -896,10 +855,7 @@ class TestExportImport(
             - Documents can be imported again
         """
         shutil.rmtree(Path(self.dirs.media_dir) / "documents")
-        shutil.copytree(
-            Path(__file__).parent / "samples" / "documents",
-            Path(self.dirs.media_dir) / "documents",
-        )
+        install_document_samples(Path(self.dirs.media_dir) / "documents")
 
         self._do_export(use_folder_prefix=True, split_manifest=True)
 
@@ -926,10 +882,7 @@ class TestExportImport(
         """
 
         shutil.rmtree(Path(self.dirs.media_dir) / "documents")
-        shutil.copytree(
-            Path(__file__).parent / "samples" / "documents",
-            Path(self.dirs.media_dir) / "documents",
-        )
+        install_document_samples(Path(self.dirs.media_dir) / "documents")
 
         num_content_type_objects = ContentType.objects.count()
         num_permission_objects = Permission.objects.count()
@@ -966,10 +919,7 @@ class TestExportImport(
 
     def test_exporter_with_auditlog_disabled(self) -> None:
         shutil.rmtree(Path(self.dirs.media_dir) / "documents")
-        shutil.copytree(
-            Path(__file__).parent / "samples" / "documents",
-            Path(self.dirs.media_dir) / "documents",
-        )
+        install_document_samples(Path(self.dirs.media_dir) / "documents")
 
         with override_settings(
             AUDIT_LOG_ENABLED=False,
@@ -989,10 +939,7 @@ class TestExportImport(
               survive the round-trip with deleted_at preserved
         """
         shutil.rmtree(Path(self.dirs.media_dir) / "documents")
-        shutil.copytree(
-            Path(__file__).parent / "samples" / "documents",
-            Path(self.dirs.media_dir) / "documents",
-        )
+        install_document_samples(Path(self.dirs.media_dir) / "documents")
 
         # d1 has self.note and self.cfi1 attached via setUp
         self.d1.delete()
@@ -1036,10 +983,7 @@ class TestExportImport(
         """
 
         shutil.rmtree(self.dirs.media_dir / "documents")
-        shutil.copytree(
-            self.SAMPLE_DIR / "documents",
-            self.dirs.media_dir / "documents",
-        )
+        install_document_samples(self.dirs.media_dir / "documents")
 
         _ = self._do_export(data_only=True)
 

src/documents/tests/test_management_thumbnails.py

@@ -11,6 +11,7 @@ from documents.models import Document
 from documents.parsers import get_default_thumbnail
 from paperless_testing.assertions import FileSystemAssertsMixin
 from paperless_testing.dirs import DirectoriesMixin
+from paperless_testing.samples import SIMPLE_DIGITAL_PDF
 
 
 @pytest.mark.management
@@ -24,7 +25,7 @@ class TestMakeThumbnails(DirectoriesMixin, FileSystemAssertsMixin, TestCase):
             filename="test.pdf",
         )
         shutil.copy(
-            Path(__file__).parent / "samples" / "simple.pdf",
+            SIMPLE_DIGITAL_PDF,
             self.d1.source_path,
         )
 
@@ -36,7 +37,7 @@ class TestMakeThumbnails(DirectoriesMixin, FileSystemAssertsMixin, TestCase):
             filename="test2.pdf",
         )
         shutil.copy(
-            Path(__file__).parent / "samples" / "simple.pdf",
+            SIMPLE_DIGITAL_PDF,
             self.d2.source_path,
         )
 

src/documents/tests/test_sample_files.py

@@ -0,0 +1,61 @@
+import hashlib
+from collections import defaultdict
+from pathlib import Path
+
+from paperless_testing.samples import SHARED_SAMPLES_DIR
+from paperless_testing.samples import SIMPLE_DIGITAL_PDF
+from paperless_testing.samples import install_document_samples
+
+EXPECTED_MEDIA_FILES = [
+    "originals/0000001.pdf",
+    "originals/0000002.pdf",
+    "originals/0000003.pdf",
+    "originals/0000004.pdf",
+    "originals/0000005.pdf",
+    "originals/0000006.pdf",
+    "archive/0000001.pdf",
+    "thumbnails/0000001.webp",
+    "thumbnails/0000002.webp",
+    "thumbnails/0000003.webp",
+    "thumbnails/0000004.webp",
+]
+
+
+def _sha(path: Path) -> str:
+    return hashlib.sha256(path.read_bytes()).hexdigest()
+
+
+def test_install_recreates_every_historical_opaque_name(tmp_path: Path) -> None:
+    install_document_samples(tmp_path)
+    for relpath in EXPECTED_MEDIA_FILES:
+        assert (tmp_path / relpath).is_file(), relpath
+
+
+def test_install_uses_the_shared_bytes(tmp_path: Path) -> None:
+    install_document_samples(tmp_path)
+    assert _sha(tmp_path / "originals" / "0000001.pdf") == _sha(SIMPLE_DIGITAL_PDF)
+
+
+APP_SAMPLE_TREES = [
+    Path(__file__).parent / "samples",
+    Path(__file__).parents[2] / "paperless" / "tests" / "samples",
+    SHARED_SAMPLES_DIR,
+]
+
+
+def test_no_two_sample_files_have_identical_bytes() -> None:
+    by_hash: dict[str, list[Path]] = defaultdict(list)
+    for tree in APP_SAMPLE_TREES:
+        assert tree.is_dir(), f"Sample tree does not exist: {tree}"
+        for path in tree.rglob("*"):
+            # Skip empty placeholders, which would all hash identically
+            if path.is_file() and path.stat().st_size > 0:
+                by_hash[_sha(path)].append(path)
+    assert by_hash, "No sample files were found to compare"
+    duplicates = {h: ps for h, ps in by_hash.items() if len(ps) > 1}
+    lines = ["  " + ", ".join(str(p) for p in ps) for ps in duplicates.values()]
+    message = (
+        "Duplicate sample files, move one to paperless_testing/sample_files:\n"
+        + "\n".join(lines)
+    )
+    assert not duplicates, message

src/documents/tests/test_tasks.py

@@ -20,6 +20,7 @@ from documents.sanity_checker import SanityCheckMessages
 from documents.tests.helpers import dummy_preprocess
 from paperless_testing.assertions import FileSystemAssertsMixin
 from paperless_testing.dirs import DirectoriesMixin
+from paperless_testing.samples import SIMPLE_DIGITAL_PDF
 
 
 @pytest.mark.django_db
@@ -228,20 +229,12 @@ class TestUpdateContent(DirectoriesMixin, TestCase):
         """
         sample1 = self.dirs.scratch_dir / "sample.pdf"
         shutil.copy(
-            Path(__file__).parent
-            / "samples"
-            / "documents"
-            / "originals"
-            / "0000001.pdf",
+            SIMPLE_DIGITAL_PDF,
             sample1,
         )
         sample1_archive = self.dirs.archive_dir / "sample_archive.pdf"
         shutil.copy(
-            Path(__file__).parent
-            / "samples"
-            / "documents"
-            / "originals"
-            / "0000001.pdf",
+            SIMPLE_DIGITAL_PDF,
             sample1_archive,
         )
         doc = Document.objects.create(
@@ -269,11 +262,7 @@ class TestUpdateContent(DirectoriesMixin, TestCase):
         """
         sample1 = self.dirs.scratch_dir / "sample.pdf"
         shutil.copy(
-            Path(__file__).parent
-            / "samples"
-            / "documents"
-            / "originals"
-            / "0000001.pdf",
+            SIMPLE_DIGITAL_PDF,
             sample1,
         )
         doc = Document.objects.create(

src/documents/tests/test_workflows.py

@@ -178,7 +178,7 @@ class TestWorkflows(
         self.assertEqual(action.__str__(), "WorkflowAction 1")
 
         test_file = shutil.copy(
-            self.SAMPLE_DIR / "simple.pdf",
+            self.SIMPLE_PDF,
             self.dirs.scratch_dir / "simple.pdf",
         )
 
@@ -290,7 +290,7 @@ class TestWorkflows(
         w.save()
 
         test_file = shutil.copy(
-            self.SAMPLE_DIR / "simple.pdf",
+            self.SIMPLE_PDF,
             self.dirs.scratch_dir / "simple.pdf",
         )
 
@@ -409,7 +409,7 @@ class TestWorkflows(
         w2.save()
 
         test_file = shutil.copy(
-            self.SAMPLE_DIR / "simple.pdf",
+            self.SIMPLE_PDF,
             self.dirs.scratch_dir / "simple.pdf",
         )
 
@@ -478,7 +478,7 @@ class TestWorkflows(
         w.save()
 
         test_file = shutil.copy(
-            self.SAMPLE_DIR / "simple.pdf",
+            self.SIMPLE_PDF,
             self.dirs.scratch_dir / "simple.pdf",
         )
 
@@ -531,7 +531,7 @@ class TestWorkflows(
         w.save()
 
         test_file = shutil.copy(
-            self.SAMPLE_DIR / "simple.pdf",
+            self.SIMPLE_PDF,
             self.dirs.scratch_dir / "simple.pdf",
         )
 
@@ -608,7 +608,7 @@ class TestWorkflows(
         w.save()
 
         test_file = shutil.copy(
-            self.SAMPLE_DIR / "simple.pdf",
+            self.SIMPLE_PDF,
             self.dirs.scratch_dir / "simple.pdf",
         )
 
@@ -687,7 +687,7 @@ class TestWorkflows(
         w.save()
 
         test_file = shutil.copy(
-            self.SAMPLE_DIR / "simple.pdf",
+            self.SIMPLE_PDF,
             self.dirs.scratch_dir / "simple.pdf",
         )
 
@@ -765,7 +765,7 @@ class TestWorkflows(
         w.save()
 
         test_file = shutil.copy(
-            self.SAMPLE_DIR / "simple.pdf",
+            self.SIMPLE_PDF,
             self.dirs.scratch_dir / "simple.pdf",
         )
 
@@ -876,7 +876,7 @@ class TestWorkflows(
         w.save()
 
         test_file = shutil.copy(
-            self.SAMPLE_DIR / "simple.pdf",
+            self.SIMPLE_PDF,
             self.dirs.scratch_dir / "simple.pdf",
         )
 
@@ -928,7 +928,7 @@ class TestWorkflows(
         generated = generate_unique_filename(doc)
         destination = (settings.ORIGINALS_DIR / generated).resolve()
         create_source_path_directory(destination)
-        shutil.copy(self.SAMPLE_DIR / "simple.pdf", destination)
+        shutil.copy(self.SIMPLE_PDF, destination)
         Document.objects.filter(pk=doc.pk).update(filename=generated.as_posix())
         doc.refresh_from_db()
 
@@ -2023,7 +2023,7 @@ class TestWorkflows(
         superuser = UserFactory(username="superuser", superuser=True)
         self.client.force_authenticate(user=superuser)
         test_file = shutil.copy(
-            self.SAMPLE_DIR / "simple.pdf",
+            self.SIMPLE_PDF,
             self.dirs.scratch_dir / "simple.pdf",
         )
         tasks.consume_file(
@@ -3009,7 +3009,7 @@ class TestWorkflows(
         generated = generate_unique_filename(doc)
         destination = (settings.ORIGINALS_DIR / generated).resolve()
         create_source_path_directory(destination)
-        shutil.copy(self.SAMPLE_DIR / "simple.pdf", destination)
+        shutil.copy(self.SIMPLE_PDF, destination)
         Document.objects.filter(pk=doc.pk).update(filename=generated.as_posix())
         doc.refresh_from_db()
         doc.tags.set([self.t1, self.t2])
@@ -3073,7 +3073,7 @@ class TestWorkflows(
         generated = generate_unique_filename(doc)
         destination = (settings.ORIGINALS_DIR / generated).resolve()
         create_source_path_directory(destination)
-        shutil.copy(self.SAMPLE_DIR / "simple.pdf", destination)
+        shutil.copy(self.SIMPLE_PDF, destination)
         Document.objects.filter(pk=doc.pk).update(filename=generated.as_posix())
         doc.refresh_from_db()
         doc.tags.set([self.t1])
@@ -3222,7 +3222,7 @@ class TestWorkflows(
         w.save()
 
         test_file = shutil.copy(
-            self.SAMPLE_DIR / "simple.pdf",
+            self.SIMPLE_PDF,
             self.dirs.scratch_dir / "simple.pdf",
         )
 
@@ -3346,7 +3346,7 @@ class TestWorkflows(
         w.save()
 
         test_file = shutil.copy(
-            self.SAMPLE_DIR / "simple.pdf",
+            self.SIMPLE_PDF,
             self.dirs.scratch_dir / "simple.pdf",
         )
 
@@ -3496,7 +3496,7 @@ class TestWorkflows(
         workflow.actions.set([assignment_action, email_action])
 
         temp_working_copy = shutil.copy(
-            self.SAMPLE_DIR / "simple.pdf",
+            self.SIMPLE_PDF,
             self.dirs.scratch_dir / "working-copy.pdf",
         )
 
@@ -3596,7 +3596,7 @@ class TestWorkflows(
 
         # move the file
         test_file = shutil.copy(
-            self.SAMPLE_DIR / "simple.pdf",
+            self.SIMPLE_PDF,
             self.dirs.scratch_dir / "simple.pdf",
         )
 
@@ -3704,7 +3704,7 @@ class TestWorkflows(
         generated = generate_unique_filename(doc)
         destination = (settings.ORIGINALS_DIR / generated).resolve()
         create_source_path_directory(destination)
-        shutil.copy(self.SAMPLE_DIR / "simple.pdf", destination)
+        shutil.copy(self.SIMPLE_PDF, destination)
         Document.objects.filter(pk=doc.pk).update(filename=generated.as_posix())
 
         run_workflows(WorkflowTrigger.WorkflowTriggerType.DOCUMENT_UPDATED, doc)
@@ -3915,7 +3915,7 @@ class TestWorkflows(
         w.save()
 
         test_file = shutil.copy(
-            self.SAMPLE_DIR / "simple.pdf",
+            self.SIMPLE_PDF,
             self.dirs.scratch_dir / "simple.pdf",
         )
 
@@ -4036,7 +4036,7 @@ class TestWorkflows(
         w.save()
 
         test_file = shutil.copy(
-            self.SAMPLE_DIR / "simple.pdf",
+            self.SIMPLE_PDF,
             self.dirs.scratch_dir / "simple.pdf",
         )
 
@@ -4387,7 +4387,7 @@ class TestWorkflows(
         w.save()
 
         test_file = shutil.copy(
-            self.SAMPLE_DIR / "simple.pdf",
+            self.SIMPLE_PDF,
             self.dirs.scratch_dir / "simple.pdf",
         )
 
@@ -4835,7 +4835,7 @@ class TestWorkflows(
         w.save()
 
         test_file = shutil.copy(
-            self.SAMPLE_DIR / "simple.pdf",
+            self.SIMPLE_PDF,
             self.dirs.scratch_dir / "simple.pdf",
         )
 
@@ -5027,7 +5027,7 @@ class TestWorkflows(
 
         # Create a test file to be consumed
         test_file = shutil.copy(
-            self.SAMPLE_DIR / "simple.pdf",
+            self.SIMPLE_PDF,
             self.dirs.scratch_dir / "simple.pdf",
         )
         test_file_path = Path(test_file)
@@ -5091,7 +5091,7 @@ class TestWorkflows(
 
         # Create a test file to be consumed
         test_file = shutil.copy(
-            self.SAMPLE_DIR / "simple.pdf",
+            self.SIMPLE_PDF,
             self.dirs.scratch_dir / "simple2.pdf",
         )
         test_file_path = Path(test_file)
@@ -5529,7 +5529,7 @@ class TestDateWorkflowLocalization(
         )
 
         test_file = shutil.copy(
-            self.SAMPLE_DIR / "simple.pdf",
+            self.SIMPLE_PDF,
             tmp_path / "simple.pdf",
         )
 
@@ -5596,7 +5596,7 @@ class TestRemoteOCRWorkflowAction(DirectoriesMixin, SampleDirMixin, APITestCase)
         self._make_workflow(WorkflowTrigger.WorkflowTriggerType.CONSUMPTION)
 
         test_file = shutil.copy(
-            self.SAMPLE_DIR / "simple.pdf",
+            self.SIMPLE_PDF,
             self.dirs.scratch_dir / "simple.pdf",
         )
         overrides = DocumentMetadataOverrides()
@@ -5814,7 +5814,7 @@ class TestApplyAISuggestionsWorkflowAction(
         )
 
         test_file = shutil.copy(
-            self.SAMPLE_DIR / "simple.pdf",
+            self.SIMPLE_PDF,
             self.dirs.scratch_dir / "simple.pdf",
         )
 

src/documents/tests/utils.py

@@ -11,6 +11,7 @@ from documents.data_models import ConsumableDocument
 from documents.data_models import DocumentMetadataOverrides
 from documents.data_models import DocumentSource
 from paperless_testing.fakes.progress import FakeProgressManager
+from paperless_testing.samples import SIMPLE_DIGITAL_PDF
 
 
 class ConsumeTaskMixin:
@@ -53,6 +54,8 @@ class SampleDirMixin:
 
     BARCODE_SAMPLE_DIR = SAMPLE_DIR / "barcodes"
 
+    SIMPLE_PDF = SIMPLE_DIGITAL_PDF
+
 
 class GetConsumerMixin:
     @contextmanager

src/documents/views.py

@@ -1192,6 +1192,7 @@ class DocumentViewSet(
                     "version_label",
                     "root_document_id",
                     "version_index",
+                    "page_count",
                 ),
             ),
             "tags",
@@ -1271,13 +1272,16 @@ class DocumentViewSet(
         if (
             "version" not in request.query_params
             or not isinstance(response.data, dict)
-            or "content" not in response.data
+            or not ({"content", "page_count"} & response.data.keys())
         ):
             return response
 
         root_doc = self.get_object()
         content_doc = self._resolve_file_doc(root_doc, request)
-        response.data["content"] = content_doc.content or ""
+        if "content" in response.data:
+            response.data["content"] = content_doc.content or ""
+        if "page_count" in response.data:
+            response.data["page_count"] = content_doc.page_count
         return response
 
     def update(self, request, *args, **kwargs):

src/locale/en_US/LC_MESSAGES/django.po

@@ -2,7 +2,7 @@ msgid ""
 msgstr ""
 "Project-Id-Version: paperless-ngx\n"
 "Report-Msgid-Bugs-To: \n"
-"POT-Creation-Date: 2026-09-23 19:00+0000\n"
+"POT-Creation-Date: 2026-10-02 23:09+0000\n"
 "PO-Revision-Date: 2022-02-17 04:17\n"
 "Last-Translator: \n"
 "Language-Team: English\n"
@@ -1632,7 +1632,7 @@ msgid "workflow runs"
 msgstr ""
 
 #: documents/serialisers.py:514 documents/serialisers.py:871
-#: documents/serialisers.py:2885 documents/views.py:342 documents/views.py:2725
+#: documents/serialisers.py:2895 documents/views.py:342 documents/views.py:2729
 #: paperless_mail/serialisers.py:156
 msgid "Insufficient permissions."
 msgstr ""
@@ -1641,39 +1641,39 @@ msgstr ""
 msgid "Invalid color."
 msgstr ""
 
-#: documents/serialisers.py:2352
+#: documents/serialisers.py:2362
 #, python-format
 msgid "File type %(type)s not supported"
 msgstr ""
 
-#: documents/serialisers.py:2396
+#: documents/serialisers.py:2406
 #, python-format
 msgid "Custom field id must be an integer: %(id)s"
 msgstr ""
 
-#: documents/serialisers.py:2403
+#: documents/serialisers.py:2413
 #, python-format
 msgid "Custom field with id %(id)s does not exist"
 msgstr ""
 
-#: documents/serialisers.py:2420 documents/serialisers.py:2430
+#: documents/serialisers.py:2430 documents/serialisers.py:2440
 msgid ""
 "Custom fields must be a list of integers or an object mapping ids to values."
 msgstr ""
 
-#: documents/serialisers.py:2425
+#: documents/serialisers.py:2435
 msgid "Some custom fields don't exist or were specified twice."
 msgstr ""
 
-#: documents/serialisers.py:2572
+#: documents/serialisers.py:2582
 msgid "Invalid variable detected."
 msgstr ""
 
-#: documents/serialisers.py:2941
+#: documents/serialisers.py:2951
 msgid "Duplicate document identifiers are not allowed."
 msgstr ""
 
-#: documents/serialisers.py:2971 documents/views.py:4780
+#: documents/serialisers.py:2981 documents/views.py:4784
 #, python-format
 msgid "Documents not found: %(ids)s"
 msgstr ""
@@ -1941,40 +1941,40 @@ msgstr ""
 msgid "Unable to parse URI {value}"
 msgstr ""
 
-#: documents/views.py:335 documents/views.py:2722
+#: documents/views.py:335 documents/views.py:2726
 msgid "Invalid more_like_id"
 msgstr ""
 
-#: documents/views.py:1669
+#: documents/views.py:1673
 msgid "Invalid AI configuration."
 msgstr ""
 
-#: documents/views.py:1680
+#: documents/views.py:1684
 msgid "AI backend request timed out."
 msgstr ""
 
-#: documents/views.py:1692
+#: documents/views.py:1696
 msgid "AI backend rejected the request. Check logs for details."
 msgstr ""
 
-#: documents/views.py:2547 documents/views.py:2863
+#: documents/views.py:2551 documents/views.py:2867
 msgid "Specify only one of text, title_search, query, or more_like_id."
 msgstr ""
 
-#: documents/views.py:4793
+#: documents/views.py:4797
 #, python-format
 msgid "Insufficient permissions to share document %(id)s."
 msgstr ""
 
-#: documents/views.py:4839
+#: documents/views.py:4843
 msgid "Bundle is already being processed."
 msgstr ""
 
-#: documents/views.py:4903
+#: documents/views.py:4907
 msgid "The share link bundle is still being prepared. Please try again later."
 msgstr ""
 
-#: documents/views.py:4917
+#: documents/views.py:4921
 msgid "The share link bundle is unavailable."
 msgstr ""
 
@@ -2262,155 +2262,155 @@ msgstr ""
 msgid "paperless application settings"
 msgstr ""
 
-#: paperless/settings/__init__.py:559
+#: paperless/settings/__init__.py:560
 msgid "English (US)"
 msgstr ""
 
-#: paperless/settings/__init__.py:560
+#: paperless/settings/__init__.py:561
 msgid "Arabic"
 msgstr ""
 
-#: paperless/settings/__init__.py:561
+#: paperless/settings/__init__.py:562
 msgid "Afrikaans"
 msgstr ""
 
-#: paperless/settings/__init__.py:562
+#: paperless/settings/__init__.py:563
 msgid "Belarusian"
 msgstr ""
 
-#: paperless/settings/__init__.py:563
+#: paperless/settings/__init__.py:564
 msgid "Bulgarian"
 msgstr ""
 
-#: paperless/settings/__init__.py:564
+#: paperless/settings/__init__.py:565
 msgid "Catalan"
 msgstr ""
 
-#: paperless/settings/__init__.py:565
+#: paperless/settings/__init__.py:566
 msgid "Czech"
 msgstr ""
 
-#: paperless/settings/__init__.py:566
+#: paperless/settings/__init__.py:567
 msgid "Danish"
 msgstr ""
 
-#: paperless/settings/__init__.py:567
+#: paperless/settings/__init__.py:568
 msgid "German"
 msgstr ""
 
-#: paperless/settings/__init__.py:568
+#: paperless/settings/__init__.py:569
 msgid "Greek"
 msgstr ""
 
-#: paperless/settings/__init__.py:569
+#: paperless/settings/__init__.py:570
 msgid "English (GB)"
 msgstr ""
 
-#: paperless/settings/__init__.py:570
+#: paperless/settings/__init__.py:571
 msgid "Spanish"
 msgstr ""
 
-#: paperless/settings/__init__.py:571
+#: paperless/settings/__init__.py:572
 msgid "Persian"
 msgstr ""
 
-#: paperless/settings/__init__.py:572
+#: paperless/settings/__init__.py:573
 msgid "Finnish"
 msgstr ""
 
-#: paperless/settings/__init__.py:573
+#: paperless/settings/__init__.py:574
 msgid "French"
 msgstr ""
 
-#: paperless/settings/__init__.py:574
+#: paperless/settings/__init__.py:575
 msgid "Hungarian"
 msgstr ""
 
-#: paperless/settings/__init__.py:575
+#: paperless/settings/__init__.py:576
 msgid "Indonesian"
 msgstr ""
 
-#: paperless/settings/__init__.py:576
+#: paperless/settings/__init__.py:577
 msgid "Italian"
 msgstr ""
 
-#: paperless/settings/__init__.py:577
+#: paperless/settings/__init__.py:578
 msgid "Japanese"
 msgstr ""
 
-#: paperless/settings/__init__.py:578
+#: paperless/settings/__init__.py:579
 msgid "Korean"
 msgstr ""
 
-#: paperless/settings/__init__.py:579
+#: paperless/settings/__init__.py:580
 msgid "Luxembourgish"
 msgstr ""
 
-#: paperless/settings/__init__.py:580
+#: paperless/settings/__init__.py:581
 msgid "Norwegian"
 msgstr ""
 
-#: paperless/settings/__init__.py:581
+#: paperless/settings/__init__.py:582
 msgid "Dutch"
 msgstr ""
 
-#: paperless/settings/__init__.py:582
+#: paperless/settings/__init__.py:583
 msgid "Polish"
 msgstr ""
 
-#: paperless/settings/__init__.py:583
+#: paperless/settings/__init__.py:584
 msgid "Portuguese (Brazil)"
 msgstr ""
 
-#: paperless/settings/__init__.py:584
+#: paperless/settings/__init__.py:585
 msgid "Portuguese"
 msgstr ""
 
-#: paperless/settings/__init__.py:585
+#: paperless/settings/__init__.py:586
 msgid "Romanian"
 msgstr ""
 
-#: paperless/settings/__init__.py:586
+#: paperless/settings/__init__.py:587
 msgid "Russian"
 msgstr ""
 
-#: paperless/settings/__init__.py:587
+#: paperless/settings/__init__.py:588
 msgid "Slovak"
 msgstr ""
 
-#: paperless/settings/__init__.py:588
+#: paperless/settings/__init__.py:589
 msgid "Slovenian"
 msgstr ""
 
-#: paperless/settings/__init__.py:589
+#: paperless/settings/__init__.py:590
 msgid "Serbian"
 msgstr ""
 
-#: paperless/settings/__init__.py:590
+#: paperless/settings/__init__.py:591
 msgid "Swedish"
 msgstr ""
 
-#: paperless/settings/__init__.py:591
+#: paperless/settings/__init__.py:592
 msgid "Turkish"
 msgstr ""
 
-#: paperless/settings/__init__.py:592
+#: paperless/settings/__init__.py:593
 msgid "Ukrainian"
 msgstr ""
 
-#: paperless/settings/__init__.py:593
+#: paperless/settings/__init__.py:594
 msgid "Vietnamese"
 msgstr ""
 
-#: paperless/settings/__init__.py:594
+#: paperless/settings/__init__.py:595
 msgid "Chinese Simplified"
 msgstr ""
 
-#: paperless/settings/__init__.py:595
+#: paperless/settings/__init__.py:596
 msgid "Chinese Traditional"
 msgstr ""
 
-#: paperless/urls.py:435
+#: paperless/urls.py:438
 msgid "Paperless-ngx administration"
 msgstr ""
 

src/paperless/parsers/mail.py

@@ -22,8 +22,6 @@ from pathlib import Path
 from typing import TYPE_CHECKING
 from typing import Self
 
-from bleach import clean
-from bleach import linkify
 from django.conf import settings
 from django.utils import timezone
 from django.utils.timezone import is_naive
@@ -38,6 +36,9 @@ from humanize import naturalsize
 from imap_tools import MailAttachment
 from imap_tools import MailMessage
 from tika_client import TikaClient
+from turbohtml.clean import Linkify
+from turbohtml.clean import linkify
+from turbohtml.migration.bleach import clean
 
 from documents.parsers import ParseError
 from documents.parsers import make_thumbnail_from_pdf
@@ -58,12 +59,6 @@ _SUPPORTED_MIME_TYPES: dict[str, str] = {
     "message/rfc822": ".eml",
 }
 
-# Bleach's email-address linkifier uses a superlinear regular expression. Keep
-# email linkification for ordinary headers and short messages, but never run it
-# over an unbounded attacker-controlled field. URL linkification remains enabled
-# for longer text.
-_MAX_EMAIL_LINKIFY_LENGTH = 2048
-
 
 class MailDocumentParser:
     """Parse .eml email files for Paperless-ngx.
@@ -633,10 +628,7 @@ class MailDocumentParser:
                 text = str(text)
             text = escape(text)
             text = clean(text)
-            text = linkify(
-                text,
-                parse_email="@" in text and len(text) <= _MAX_EMAIL_LINKIFY_LENGTH,
-            )
+            text = linkify(text, Linkify(parse_email=True))
             text = text.replace("\n", "<br>")
             return text
 

src/paperless/settings/__init__.py

@@ -291,7 +291,7 @@ if _CHANNELS_BACKEND.startswith("channels_redis."):
 ###############################################################################
 
 EMAIL_HOST: Final[str] = os.getenv("PAPERLESS_EMAIL_HOST", "localhost")
-EMAIL_PORT: Final[int] = int(os.getenv("PAPERLESS_EMAIL_PORT", 25))
+EMAIL_PORT: Final[int] = get_int_from_env("PAPERLESS_EMAIL_PORT", 25)
 EMAIL_HOST_USER: Final[str] = os.getenv("PAPERLESS_EMAIL_HOST_USER", "")
 EMAIL_HOST_PASSWORD: Final[str] = os.getenv("PAPERLESS_EMAIL_HOST_PASSWORD", "")
 DEFAULT_FROM_EMAIL: Final[str] = os.getenv("PAPERLESS_EMAIL_FROM", EMAIL_HOST_USER)
@@ -378,8 +378,9 @@ ACCOUNT_SESSION_REMEMBER = get_bool_from_env(
     "True",
 )
 SESSION_EXPIRE_AT_BROWSER_CLOSE = not ACCOUNT_SESSION_REMEMBER
-SESSION_COOKIE_AGE = int(
-    os.getenv("PAPERLESS_SESSION_COOKIE_AGE", 60 * 60 * 24 * 7 * 3),
+SESSION_COOKIE_AGE = get_int_from_env(
+    "PAPERLESS_SESSION_COOKIE_AGE",
+    60 * 60 * 24 * 7 * 3,
 )
 # https://docs.djangoproject.com/en/5.1/ref/settings/#std-setting-SESSION_ENGINE
 SESSION_ENGINE = "django.contrib.sessions.backends.cached_db"
@@ -611,8 +612,8 @@ USE_TZ = True
 
 LOGGING_DIR.mkdir(parents=True, exist_ok=True)
 
-LOGROTATE_MAX_SIZE = os.getenv("PAPERLESS_LOGROTATE_MAX_SIZE", 1024 * 1024)
-LOGROTATE_MAX_BACKUPS = os.getenv("PAPERLESS_LOGROTATE_MAX_BACKUPS", 20)
+LOGROTATE_MAX_SIZE = get_int_from_env("PAPERLESS_LOGROTATE_MAX_SIZE", 1024 * 1024)
+LOGROTATE_MAX_BACKUPS = get_int_from_env("PAPERLESS_LOGROTATE_MAX_BACKUPS", 20)
 
 LOGGING = {
     "version": 1,
@@ -796,7 +797,7 @@ def default_threads_per_worker(task_workers) -> int:
         return 1
 
 
-THREADS_PER_WORKER = os.getenv(
+THREADS_PER_WORKER = get_int_from_env(
     "PAPERLESS_THREADS_PER_WORKER",
     default_threads_per_worker(CELERY_WORKER_CONCURRENCY),
 )
@@ -817,9 +818,9 @@ IGNORABLE_FILES: Final[list[str]] = [
     "Thumbs.db",
 ]
 
-CONSUMER_POLLING_INTERVAL = float(os.getenv("PAPERLESS_CONSUMER_POLLING_INTERVAL", 0))
+CONSUMER_POLLING_INTERVAL = get_float_from_env("PAPERLESS_CONSUMER_POLLING_INTERVAL", 0)
 
-CONSUMER_STABILITY_DELAY = float(os.getenv("PAPERLESS_CONSUMER_STABILITY_DELAY", 5))
+CONSUMER_STABILITY_DELAY = get_float_from_env("PAPERLESS_CONSUMER_STABILITY_DELAY", 5)
 
 CONSUMER_DELETE_DUPLICATES = get_bool_from_env("PAPERLESS_CONSUMER_DELETE_DUPLICATES")
 

src/paperless/tests/parsers/conftest.py

@@ -432,30 +432,6 @@ def tesseract_samples_dir(parser_samples_dir: Path) -> Path:
     return parser_samples_dir / "tesseract"
 
 
-@pytest.fixture(scope="session")
-def multi_page_images_pdf_file(tesseract_samples_dir: Path) -> Path:
-    """Path to a multi-page PDF with images.
-
-    Returns
-    -------
-    Path
-        Absolute path to ``tesseract/multi-page-images.pdf``.
-    """
-    return tesseract_samples_dir / "multi-page-images.pdf"
-
-
-@pytest.fixture(scope="session")
-def simple_digital_pdf_file(tesseract_samples_dir: Path) -> Path:
-    """Path to a simple digital PDF sample file.
-
-    Returns
-    -------
-    Path
-        Absolute path to ``tesseract/simple-digital.pdf``.
-    """
-    return tesseract_samples_dir / "simple-digital.pdf"
-
-
 @pytest.fixture(scope="session")
 def simple_no_dpi_png_file(tesseract_samples_dir: Path) -> Path:
     """Path to a simple PNG without DPI information.

src/paperless/tests/parsers/test_mail_parser.py

@@ -735,33 +735,24 @@ class TestParser:
 
             assert expected_html == actual_html
 
-    def test_mail_to_html_bounds_email_linkification(
+    def test_mail_to_html_linkifies_email_in_long_text(
         self,
         mail_parser: MailDocumentParser,
     ) -> None:
         mail = mock.Mock(
-            subject="sender@example.com",
+            subject="",
             from_values=None,
             to_values=[],
             cc_values=[],
             bcc_values=[],
             attachments=[],
             date=timezone.now(),
-            text=("a." * 1500) + "@example.com",
+            text=("a." * 1500) + " sender@example.com",
         )
 
-        with mock.patch(
-            "paperless.parsers.mail.linkify",
-            side_effect=lambda text, **kwargs: text,
-        ) as mock_linkify:
-            mail_parser.mail_to_html(mail)
+        html_file = mail_parser.mail_to_html(mail)
 
-        parse_email_by_text = {
-            call.args[0]: call.kwargs["parse_email"]
-            for call in mock_linkify.call_args_list
-        }
-        assert parse_email_by_text["sender@example.com"] is True
-        assert parse_email_by_text[mail.text] is False
+        assert 'href="mailto:sender@example.com"' in html_file.read_text()
 
     def test_generate_pdf_from_mail(
         self,

src/paperless/tests/parsers/test_tesseract_parser.py

@@ -160,11 +160,11 @@ class TestGetPageCount:
     def test_single_page_pdf(
         self,
         tesseract_parser: RasterisedDocumentParser,
-        tesseract_samples_dir: Path,
+        simple_digital_pdf_file: Path,
     ) -> None:
         assert (
             tesseract_parser.get_page_count(
-                tesseract_samples_dir / "simple-digital.pdf",
+                simple_digital_pdf_file,
                 "application/pdf",
             )
             == 1
@@ -187,7 +187,7 @@ class TestGetPageCount:
         self,
         mocker: MockerFixture,
         tesseract_parser: RasterisedDocumentParser,
-        tesseract_samples_dir: Path,
+        simple_digital_pdf_file: Path,
         caplog,
     ) -> None:
         """
@@ -203,7 +203,7 @@ class TestGetPageCount:
 
         with caplog.at_level(logging.WARNING):
             page_count = tesseract_parser.get_page_count(
-                tesseract_samples_dir / "simple-digital.pdf",
+                simple_digital_pdf_file,
                 "application/pdf",
             )
         assert page_count is None
@@ -272,10 +272,10 @@ class TestGetThumbnail:
     def test_thumbnail_is_file(
         self,
         tesseract_parser: RasterisedDocumentParser,
-        tesseract_samples_dir: Path,
+        simple_digital_pdf_file: Path,
     ) -> None:
         thumb = tesseract_parser.get_thumbnail(
-            tesseract_samples_dir / "simple-digital.pdf",
+            simple_digital_pdf_file,
             "application/pdf",
         )
         assert thumb.is_file()
@@ -284,7 +284,7 @@ class TestGetThumbnail:
         self,
         mocker: MockerFixture,
         tesseract_parser: RasterisedDocumentParser,
-        tesseract_samples_dir: Path,
+        simple_digital_pdf_file: Path,
     ) -> None:
         def _raise_on_pdf(input_file, output_file, **kwargs) -> None:
             if ".pdf" in str(input_file):
@@ -294,7 +294,7 @@ class TestGetThumbnail:
         mocker.patch("documents.parsers.run_convert", side_effect=_raise_on_pdf)
 
         thumb = tesseract_parser.get_thumbnail(
-            tesseract_samples_dir / "simple-digital.pdf",
+            simple_digital_pdf_file,
             "application/pdf",
         )
         assert thumb.is_file()
@@ -320,11 +320,11 @@ class TestExtractText:
     def test_extract_text_from_digital_pdf(
         self,
         tesseract_parser: RasterisedDocumentParser,
-        tesseract_samples_dir: Path,
+        simple_digital_pdf_file: Path,
     ) -> None:
         text = tesseract_parser.extract_text(
             None,
-            tesseract_samples_dir / "simple-digital.pdf",
+            simple_digital_pdf_file,
         )
         assert text is not None
         assert "This is a test document." in text.strip()
@@ -339,7 +339,7 @@ class TestParsePdf:
     def test_simple_digital_creates_archive(
         self,
         tesseract_parser: RasterisedDocumentParser,
-        tesseract_samples_dir: Path,
+        multi_page_digital_pdf_file: Path,
     ) -> None:
         """
         GIVEN:
@@ -353,7 +353,7 @@ class TestParsePdf:
             - Text is extracted
         """
         tesseract_parser.parse(
-            tesseract_samples_dir / "multi-page-digital.pdf",
+            multi_page_digital_pdf_file,
             "application/pdf",
         )
         assert tesseract_parser.archive_path is not None
@@ -368,10 +368,10 @@ class TestParsePdf:
     def test_with_form_default(
         self,
         tesseract_parser: RasterisedDocumentParser,
-        tesseract_samples_dir: Path,
+        with_form_pdf_file: Path,
     ) -> None:
         tesseract_parser.parse(
-            tesseract_samples_dir / "with-form.pdf",
+            with_form_pdf_file,
             "application/pdf",
         )
         assert tesseract_parser.archive_path is not None
@@ -384,11 +384,11 @@ class TestParsePdf:
     def test_with_form_redo_no_archive_when_not_requested(
         self,
         tesseract_parser: RasterisedDocumentParser,
-        tesseract_samples_dir: Path,
+        with_form_pdf_file: Path,
     ) -> None:
         tesseract_parser.settings.mode = ModeChoices.REDO
         tesseract_parser.parse(
-            tesseract_samples_dir / "with-form.pdf",
+            with_form_pdf_file,
             "application/pdf",
             produce_archive=False,
         )
@@ -401,11 +401,11 @@ class TestParsePdf:
     def test_with_form_force(
         self,
         tesseract_parser: RasterisedDocumentParser,
-        tesseract_samples_dir: Path,
+        with_form_pdf_file: Path,
     ) -> None:
         tesseract_parser.settings.mode = ModeChoices.FORCE
         tesseract_parser.parse(
-            tesseract_samples_dir / "with-form.pdf",
+            with_form_pdf_file,
             "application/pdf",
         )
         assert_ordered_substrings(
@@ -446,7 +446,7 @@ class TestParsePdf:
         self,
         mocker: MockerFixture,
         tesseract_parser: RasterisedDocumentParser,
-        tesseract_samples_dir: Path,
+        simple_digital_pdf_file: Path,
     ) -> None:
         mocker.patch(
             "ocrmypdf.ocr",
@@ -454,7 +454,7 @@ class TestParsePdf:
         )
         with pytest.raises(ParseError):
             tesseract_parser.parse(
-                tesseract_samples_dir / "simple-digital.pdf",
+                simple_digital_pdf_file,
                 "application/pdf",
             )
 
@@ -530,10 +530,10 @@ class TestParseMultiPage:
     def test_multi_page_digital(
         self,
         tesseract_parser: RasterisedDocumentParser,
-        tesseract_samples_dir: Path,
+        multi_page_digital_pdf_file: Path,
     ) -> None:
         tesseract_parser.parse(
-            tesseract_samples_dir / "multi-page-digital.pdf",
+            multi_page_digital_pdf_file,
             "application/pdf",
         )
         assert tesseract_parser.archive_path is not None
@@ -557,12 +557,12 @@ class TestParseMultiPage:
         self,
         mode: str,
         tesseract_parser: RasterisedDocumentParser,
-        tesseract_samples_dir: Path,
+        multi_page_digital_pdf_file: Path,
     ) -> None:
         tesseract_parser.settings.pages = 2
         tesseract_parser.settings.mode = mode
         tesseract_parser.parse(
-            tesseract_samples_dir / "multi-page-digital.pdf",
+            multi_page_digital_pdf_file,
             "application/pdf",
         )
         assert tesseract_parser.archive_path is not None
@@ -576,11 +576,11 @@ class TestParseMultiPage:
     def test_multi_page_images_skip(
         self,
         tesseract_parser: RasterisedDocumentParser,
-        tesseract_samples_dir: Path,
+        multi_page_images_pdf_file: Path,
     ) -> None:
         tesseract_parser.settings.mode = ModeChoices.AUTO
         tesseract_parser.parse(
-            tesseract_samples_dir / "multi-page-images.pdf",
+            multi_page_images_pdf_file,
             "application/pdf",
         )
         assert tesseract_parser.archive_path is not None
@@ -594,7 +594,7 @@ class TestParseMultiPage:
     def test_multi_page_images_redo_pages_2(
         self,
         tesseract_parser: RasterisedDocumentParser,
-        tesseract_samples_dir: Path,
+        multi_page_images_pdf_file: Path,
     ) -> None:
         """
         GIVEN:
@@ -609,7 +609,7 @@ class TestParseMultiPage:
         tesseract_parser.settings.pages = 2
         tesseract_parser.settings.mode = ModeChoices.REDO
         tesseract_parser.parse(
-            tesseract_samples_dir / "multi-page-images.pdf",
+            multi_page_images_pdf_file,
             "application/pdf",
         )
         assert tesseract_parser.archive_path is not None
@@ -622,7 +622,7 @@ class TestParseMultiPage:
     def test_multi_page_images_force_page_1(
         self,
         tesseract_parser: RasterisedDocumentParser,
-        tesseract_samples_dir: Path,
+        multi_page_images_pdf_file: Path,
     ) -> None:
         """
         GIVEN:
@@ -637,7 +637,7 @@ class TestParseMultiPage:
         tesseract_parser.settings.pages = 1
         tesseract_parser.settings.mode = ModeChoices.FORCE
         tesseract_parser.parse(
-            tesseract_samples_dir / "multi-page-images.pdf",
+            multi_page_images_pdf_file,
             "application/pdf",
         )
         assert tesseract_parser.archive_path is not None
@@ -733,7 +733,7 @@ class TestSkipArchive:
     def test_skip_noarchive_with_text_layer(
         self,
         tesseract_parser: RasterisedDocumentParser,
-        tesseract_samples_dir: Path,
+        multi_page_digital_pdf_file: Path,
     ) -> None:
         """
         GIVEN:
@@ -747,7 +747,7 @@ class TestSkipArchive:
         """
         tesseract_parser.settings.mode = ModeChoices.AUTO
         tesseract_parser.parse(
-            tesseract_samples_dir / "multi-page-digital.pdf",
+            multi_page_digital_pdf_file,
             "application/pdf",
             produce_archive=False,
         )
@@ -762,7 +762,7 @@ class TestSkipArchive:
     def test_skip_noarchive_image_only_creates_archive(
         self,
         tesseract_parser: RasterisedDocumentParser,
-        tesseract_samples_dir: Path,
+        multi_page_images_pdf_file: Path,
     ) -> None:
         """
         GIVEN:
@@ -775,7 +775,7 @@ class TestSkipArchive:
         """
         tesseract_parser.settings.mode = ModeChoices.AUTO
         tesseract_parser.parse(
-            tesseract_samples_dir / "multi-page-images.pdf",
+            multi_page_images_pdf_file,
             "application/pdf",
         )
         assert tesseract_parser.archive_path is not None
@@ -787,29 +787,29 @@ class TestSkipArchive:
         )
 
     @pytest.mark.parametrize(
-        ("produce_archive", "filename", "expect_archive"),
+        ("produce_archive", "sample_fixture", "expect_archive"),
         [
             pytest.param(
                 True,
-                "multi-page-digital.pdf",
+                "multi_page_digital_pdf_file",
                 True,
                 id="produce-archive-with-text",
             ),
             pytest.param(
                 True,
-                "multi-page-images.pdf",
+                "multi_page_images_pdf_file",
                 True,
                 id="produce-archive-no-text",
             ),
             pytest.param(
                 False,
-                "multi-page-digital.pdf",
+                "multi_page_digital_pdf_file",
                 False,
                 id="no-archive-with-text-layer",
             ),
             pytest.param(
                 False,
-                "multi-page-images.pdf",
+                "multi_page_images_pdf_file",
                 False,
                 id="no-archive-no-text-layer",
             ),
@@ -818,10 +818,10 @@ class TestSkipArchive:
     def test_produce_archive_flag(
         self,
         produce_archive: bool,  # noqa: FBT001
-        filename: str,
+        sample_fixture: str,
         expect_archive: bool,  # noqa: FBT001
         tesseract_parser: RasterisedDocumentParser,
-        tesseract_samples_dir: Path,
+        request: pytest.FixtureRequest,
     ) -> None:
         """
         GIVEN:
@@ -834,8 +834,9 @@ class TestSkipArchive:
             - Text is always extracted
         """
         tesseract_parser.settings.mode = ModeChoices.AUTO
+        sample = request.getfixturevalue(sample_fixture)
         tesseract_parser.parse(
-            tesseract_samples_dir / filename,
+            sample,
             "application/pdf",
             produce_archive=produce_archive,
         )
@@ -852,7 +853,7 @@ class TestSkipArchive:
         self,
         mocker: MockerFixture,
         tesseract_parser: RasterisedDocumentParser,
-        tesseract_samples_dir: Path,
+        simple_digital_pdf_file: Path,
     ) -> None:
         """
         GIVEN:
@@ -868,7 +869,7 @@ class TestSkipArchive:
         tesseract_parser.settings.mode = ModeChoices.AUTO
         mock_ocr = mocker.patch("ocrmypdf.ocr")
         tesseract_parser.parse(
-            tesseract_samples_dir / "simple-digital.pdf",
+            simple_digital_pdf_file,
             "application/pdf",
             produce_archive=False,
         )
@@ -907,7 +908,7 @@ class TestSkipArchive:
     def test_tagged_pdf_produces_pdfa_archive_without_ocr(
         self,
         tesseract_parser: RasterisedDocumentParser,
-        tesseract_samples_dir: Path,
+        simple_digital_pdf_file: Path,
     ) -> None:
         """
         GIVEN:
@@ -922,7 +923,7 @@ class TestSkipArchive:
         """
         tesseract_parser.settings.mode = ModeChoices.AUTO
         tesseract_parser.parse(
-            tesseract_samples_dir / "simple-digital.pdf",
+            simple_digital_pdf_file,
             "application/pdf",
             produce_archive=True,
         )

src/paperless/tests/samples/mail/sample.html

@@ -1,19 +0,0 @@
- <html>
-    <head>
-      <meta http-equiv="content-type" content="text/html; charset=UTF-8">
-    </head>
-    <body>
-      <p>Some Text</p>
-      <p>
-				<img src="cid:part1.pNdUSz0s.D3NqVtPg@example.de" alt="Has to be rewritten to work..">
-				<img src="http://localhost:8080/assets/logo_full_white.svg" alt="This image should not be shown.">
-			</p>
-
-      <p>and an embedded image.<br>
-      </p>
-      <p id="changeme">Paragraph unchanged.</p>
-      <scRipt>
-          document.getElementById("changeme").innerHTML = "Paragraph changed via Java Script.";
-      </script>
-    </body>
-  </html>

src/paperless/tests/test_admin_auth.py

@@ -0,0 +1,68 @@
+import time
+
+from allauth.mfa import app_settings as mfa_settings
+from allauth.mfa.totp.internal import auth as totp_auth
+from django.test import TestCase
+from django.urls import reverse
+
+from paperless_testing.factories import UserFactory
+
+
+class TestAdminAuth(TestCase):
+    def test_admin_login_redirects_to_allauth(self):
+        user = UserFactory(staff=True, password="testpassword")
+        admin_url = reverse("admin:index")
+        login_url = reverse("admin:login")
+        expected_url = f"{reverse('account_login')}?next={admin_url}"
+
+        response = self.client.get(login_url, {"next": admin_url})
+        self.assertRedirects(response, expected_url)
+
+        response = self.client.post(
+            login_url,
+            {"username": user.username, "password": "testpassword", "next": admin_url},
+        )
+        self.assertRedirects(response, expected_url)
+        self.assertNotIn("_auth_user_id", self.client.session)
+
+    def test_admin_access_requires_totp_for_enrolled_staff(self):
+        user = UserFactory(staff=True, password="testpassword")
+        secret = totp_auth.generate_totp_secret()
+        totp_auth.TOTP.activate(user, secret)
+        admin_url = reverse("admin:index")
+        mfa_url = reverse("mfa_authenticate")
+
+        response = self.client.post(
+            reverse("account_login"),
+            {"login": user.username, "password": "testpassword", "next": admin_url},
+        )
+        self.assertRedirects(response, mfa_url)
+        self.assertNotIn("_auth_user_id", self.client.session)
+        self.assertRedirects(
+            self.client.get(admin_url),
+            f"{reverse('admin:login')}?next={admin_url}",
+            fetch_redirect_response=False,
+        )
+
+        response = self.client.post(mfa_url, {"code": "invalid"})
+        self.assertEqual(response.status_code, 200)
+        self.assertNotIn("_auth_user_id", self.client.session)
+
+        code = totp_auth.format_hotp_value(
+            totp_auth.hotp_value(secret, int(time.time()) // mfa_settings.TOTP_PERIOD),
+        )
+        response = self.client.post(mfa_url, {"code": code})
+        self.assertRedirects(response, admin_url)
+        self.assertEqual(self.client.session["_auth_user_id"], str(user.pk))
+
+    def test_staff_without_totp_can_still_log_in(self):
+        user = UserFactory(staff=True, password="testpassword")
+        admin_url = reverse("admin:index")
+
+        response = self.client.post(
+            reverse("account_login"),
+            {"login": user.username, "password": "testpassword", "next": admin_url},
+        )
+
+        self.assertRedirects(response, admin_url)
+        self.assertEqual(self.client.session["_auth_user_id"], str(user.pk))

src/paperless/tests/test_parser_utils.py

@@ -16,8 +16,6 @@ from paperless.parsers.utils import read_file_handle_unicode_errors
 if TYPE_CHECKING:
     from pytest_mock import MockerFixture
 
-SAMPLES = Path(__file__).parent / "samples" / "tesseract"
-
 
 class TestReadFileHandleUnicodeErrors:
     def test_plain_utf8(self, tmp_path: Path) -> None:
@@ -55,11 +53,11 @@ class TestReadFileHandleUnicodeErrors:
 
 
 class TestIsTaggedPdf:
-    def test_tagged_pdf_returns_true(self) -> None:
-        assert is_tagged_pdf(SAMPLES / "simple-digital.pdf") is True
+    def test_tagged_pdf_returns_true(self, simple_digital_pdf_file: Path) -> None:
+        assert is_tagged_pdf(simple_digital_pdf_file) is True
 
-    def test_untagged_pdf_returns_false(self) -> None:
-        assert is_tagged_pdf(SAMPLES / "multi-page-images.pdf") is False
+    def test_untagged_pdf_returns_false(self, multi_page_images_pdf_file: Path) -> None:
+        assert is_tagged_pdf(multi_page_images_pdf_file) is False
 
     def test_nonexistent_path_returns_false(self) -> None:
         assert is_tagged_pdf(Path("/nonexistent/file.pdf")) is False

src/paperless/urls.py

@@ -1,4 +1,5 @@
 from allauth.account import views as allauth_account_views
+from allauth.account.decorators import secure_admin_login
 from allauth.mfa.base import views as allauth_mfa_views
 from allauth.socialaccount import views as allauth_social_account_views
 from allauth.urls import build_provider_urlpatterns
@@ -68,6 +69,8 @@ from paperless_mail.views import MailRuleViewSet
 from paperless_mail.views import OauthCallbackView
 from paperless_mail.views import ProcessedMailViewSet
 
+admin.site.login = secure_admin_login(admin.site.login)
+
 api_router = DefaultRouter()
 api_router.register(r"correspondents", CorrespondentViewSet)
 api_router.register(r"document_types", DocumentTypeViewSet)
@@ -297,7 +300,7 @@ urlpatterns = [
     ),
     re_path(r"^share/(?P<slug>\w+)/?$", SharedLinkView.as_view()),
     re_path(r"^favicon.ico$", FaviconView.as_view(), name="favicon"),
-    re_path(r"admin/", admin.site.urls),
+    re_path(r"^admin/", admin.site.urls),
     re_path(
         r"^fetch/",
         include(

src/paperless_mail/tests/factories.py

@@ -2,14 +2,14 @@ from __future__ import annotations
 
 import factory
 from django.utils import timezone
-from factory.django import DjangoModelFactory
 
 from paperless_mail.models import MailAccount
 from paperless_mail.models import MailRule
 from paperless_mail.models import ProcessedMail
+from paperless_testing.typed_factory import TypedModelFactory
 
 
-class MailAccountFactory(DjangoModelFactory[MailAccount]):
+class MailAccountFactory(TypedModelFactory[MailAccount]):
     class Meta:
         model = MailAccount
 
@@ -24,7 +24,7 @@ class MailAccountFactory(DjangoModelFactory[MailAccount]):
     is_token = False
 
 
-class MailRuleFactory(DjangoModelFactory[MailRule]):
+class MailRuleFactory(TypedModelFactory[MailRule]):
     class Meta:
         model = MailRule
 
@@ -44,7 +44,7 @@ class MailRuleFactory(DjangoModelFactory[MailRule]):
     stop_processing = False
 
 
-class ProcessedMailFactory(DjangoModelFactory[ProcessedMail]):
+class ProcessedMailFactory(TypedModelFactory[ProcessedMail]):
     class Meta:
         model = ProcessedMail
 

src/paperless_testing/factories.py

@@ -5,8 +5,7 @@ Factory-boy factories for documents app models.
 from __future__ import annotations
 
 import factory
-from django.contrib.auth import get_user_model
-from factory.django import DjangoModelFactory
+from django.contrib.auth.models import User
 
 from documents.models import Correspondent
 from documents.models import Document
@@ -15,11 +14,10 @@ from documents.models import MatchingModel
 from documents.models import PaperlessTask
 from documents.models import StoragePath
 from documents.models import Tag
-
-UserModelT = get_user_model()
+from paperless_testing.typed_factory import TypedModelFactory
 
 
-class CorrespondentFactory(DjangoModelFactory[Correspondent]):
+class CorrespondentFactory(TypedModelFactory[Correspondent]):
     class Meta:
         model = Correspondent
 
@@ -28,7 +26,7 @@ class CorrespondentFactory(DjangoModelFactory[Correspondent]):
     matching_algorithm = MatchingModel.MATCH_NONE
 
 
-class DocumentTypeFactory(DjangoModelFactory[DocumentType]):
+class DocumentTypeFactory(TypedModelFactory[DocumentType]):
     class Meta:
         model = DocumentType
 
@@ -37,7 +35,7 @@ class DocumentTypeFactory(DjangoModelFactory[DocumentType]):
     matching_algorithm = MatchingModel.MATCH_NONE
 
 
-class TagFactory(DjangoModelFactory[Tag]):
+class TagFactory(TypedModelFactory[Tag]):
     class Meta:
         model = Tag
 
@@ -47,7 +45,7 @@ class TagFactory(DjangoModelFactory[Tag]):
     is_inbox_tag = False
 
 
-class StoragePathFactory(DjangoModelFactory[StoragePath]):
+class StoragePathFactory(TypedModelFactory[StoragePath]):
     class Meta:
         model = StoragePath
 
@@ -59,7 +57,7 @@ class StoragePathFactory(DjangoModelFactory[StoragePath]):
     matching_algorithm = MatchingModel.MATCH_NONE
 
 
-class DocumentFactory(DjangoModelFactory[Document]):
+class DocumentFactory(TypedModelFactory[Document]):
     class Meta:
         model = Document
 
@@ -71,9 +69,9 @@ class DocumentFactory(DjangoModelFactory[Document]):
     storage_path = None
 
 
-class UserFactory(DjangoModelFactory[UserModelT]):
+class UserFactory(TypedModelFactory[User]):
     class Meta:
-        model = UserModelT
+        model = User
 
     username = factory.Sequence(lambda n: f"user{n}")
     is_staff = False
@@ -88,7 +86,7 @@ class UserFactory(DjangoModelFactory[UserModelT]):
         staff = factory.Trait(is_staff=True)
 
 
-class PaperlessTaskFactory(DjangoModelFactory[PaperlessTask]):
+class PaperlessTaskFactory(TypedModelFactory[PaperlessTask]):
     class Meta:
         model = PaperlessTask
 

src/paperless_testing/samples.py

@@ -0,0 +1,48 @@
+"""Test sample files shared across tests.
+
+A sample used by a single app stays in that app's ``tests/samples`` tree.
+Samples needed by more than one app, or stored under more than one name, live
+here exactly once.
+"""
+
+import shutil
+from pathlib import Path
+
+SHARED_SAMPLES_DIR = (Path(__file__).parent / "sample_files").resolve()
+
+SIMPLE_DIGITAL_PDF = SHARED_SAMPLES_DIR / "simple-digital.pdf"
+MULTI_PAGE_DIGITAL_PDF = SHARED_SAMPLES_DIR / "multi-page-digital.pdf"
+WITH_FORM_PDF = SHARED_SAMPLES_DIR / "with-form.pdf"
+MULTI_PAGE_IMAGES_PDF = SHARED_SAMPLES_DIR / "multi-page-images.pdf"
+THUMBNAIL_WEBP = SHARED_SAMPLES_DIR / "thumbnail.webp"
+
+# The fake media tree under documents/tests/samples/documents keeps only the
+# files unique to it. The files that duplicate a shared sample are laid back
+# down under their historical opaque names (DB rows and exporter manifests
+# refer to them) by install_document_samples().
+_DOCUMENT_SAMPLES_DIR = (
+    Path(__file__).parent.parent / "documents" / "tests" / "samples" / "documents"
+).resolve()
+
+_SHARED_AS_MEDIA = (
+    ("originals/0000001.pdf", SIMPLE_DIGITAL_PDF),
+    ("originals/0000002.pdf", MULTI_PAGE_DIGITAL_PDF),
+    ("originals/0000003.pdf", WITH_FORM_PDF),
+    ("archive/0000001.pdf", MULTI_PAGE_IMAGES_PDF),
+    ("thumbnails/0000001.webp", THUMBNAIL_WEBP),
+    ("thumbnails/0000002.webp", THUMBNAIL_WEBP),
+    ("thumbnails/0000003.webp", THUMBNAIL_WEBP),
+    ("thumbnails/0000004.webp", THUMBNAIL_WEBP),
+)
+
+
+def install_document_samples(dest: Path) -> None:
+    """Populate ``dest`` with the full fake media tree.
+
+    Replaces ``shutil.copytree(<samples>/documents, dest)`` in tests.
+    """
+    shutil.copytree(_DOCUMENT_SAMPLES_DIR, dest, dirs_exist_ok=True)
+    for relpath, source in _SHARED_AS_MEDIA:
+        target = dest / relpath
+        target.parent.mkdir(parents=True, exist_ok=True)
+        shutil.copy2(source, target)

src/paperless_testing/typed_factory.py

@@ -0,0 +1,20 @@
+"""
+A DjangoModelFactory base whose calls are typed as the model they build.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+from typing import Any
+from typing import TypeVar
+
+from factory.django import DjangoModelFactory
+
+T = TypeVar("T")
+
+
+class TypedModelFactory(DjangoModelFactory[T]):
+    if TYPE_CHECKING:
+        # factory-boy leaves Factory() unannotated, so mypy takes it to build a
+        # factory instance. At runtime it builds the model.
+        def __new__(cls, *args: Any, **kwargs: Any) -> T: ...  # type: ignore[misc]