A community-supported supercharged document management system: scan, index and archive all your documents
Python aiangulararchivingdjangodmsdocument-managementdocument-management-systemllmmachine-learningocroptical-character-recognitionpdf
Fix: correct doc version filename handling (#12223)
shamoondf03207eef9f
diff --git a/docs/advanced_usage.md b/docs/advanced_usage.mdindex a293eb91d..13194fe87 100644--- a/docs/advanced_usage.md+++ b/docs/advanced_usage.md@@ -262,6 +262,10 @@ your files differently, you can do that by adjusting theor using [storage paths (see below)](#storage-paths). Paperless adds thecorrect file extension e.g. `.pdf`, `.jpg` automatically.+When a document has file versions, each version uses the same naming rules and+storage path resolution as any other document file, with an added version suffix+such as `_v1`, `_v2`, etc.+This variable allows you to configure the filename (folders are allowed)using placeholders. For example, configuring this to@@ -353,6 +357,8 @@ If paperless detects that two documents share the same filename,paperless will automatically append `_01`, `_02`, etc to the filename.This happens if all the placeholders in a filename evaluate to the samevalue.+For versioned files, this counter is appended after the version suffix+(for example `statement_v2_01.pdf`).If there are any errors in the placeholders included in `PAPERLESS_FILENAME_FORMAT`,paperless will fall back to using the default naming scheme instead.diff --git a/docs/usage.md b/docs/usage.mdindex bcaf7df7a..b56401351 100644--- a/docs/usage.md+++ b/docs/usage.md@@ -95,6 +95,7 @@ Think of versions as **file history** for a document.- Versions track the underlying file and extracted text content (OCR/text).- Metadata such as tags, correspondent, document type, storage path and custom fields stay on the "root" document.+- Version files follow normal filename formatting (including storage paths) and add a `_vN` suffix (for example `_v1`, `_v2`).- By default, search and document content use the latest version.- In document detail, selecting a version switches the preview, file metadata and content (and download etc buttons) to that version.- Deleting a non-root version keeps metadata and falls back to the latest remaining version.diff --git a/src/documents/consumer.py b/src/documents/consumer.pyindex b00c4aee3..3f1ffc9d1 100644--- a/src/documents/consumer.py+++ b/src/documents/consumer.py@@ -11,6 +11,7 @@ import magicfrom django.conf import settingsfrom django.contrib.auth.models import Userfrom django.db import transaction+from django.db.models import Maxfrom django.db.models import Qfrom django.utils import timezonefrom filelock import FileLock@@ -124,22 +125,6 @@ class ConsumerPluginMixin:self.filename = self.metadata.filename or self.input_doc.original_file.name- if input_doc.root_document_id:- self.log.debug(- f"Document root document id: {input_doc.root_document_id}",- )- root_document = Document.objects.get(pk=input_doc.root_document_id)- version_index = Document.objects.filter(root_document=root_document).count()- filename_path = Path(self.filename)- if filename_path.suffix:- self.filename = str(- filename_path.with_name(- f"{filename_path.stem}_v{version_index}{filename_path.suffix}",- ),- )- else:- self.filename = f"{self.filename}_v{version_index}"-def _send_progress(self,current_progress: int,@@ -194,9 +179,19 @@ class ConsumerPlugin(mime_type: str,) -> Document:self.log.debug("Saving record for updated version to database")- version_doc = Document.objects.get(pk=root_doc.pk)+ root_doc_frozen = Document.objects.select_for_update().get(pk=root_doc.pk)+ next_version_index = (+ Document.global_objects.filter(+ root_document_id=root_doc_frozen.pk,+ ).aggregate(+ max_index=Max("version_index"),+ )["max_index"]+ or 0+ )+ version_doc = Document.objects.get(pk=root_doc_frozen.pk)setattr(version_doc, "pk", None)- version_doc.root_document = root_doc+ version_doc.root_document = root_doc_frozen+ version_doc.version_index = next_version_index + 1file_for_checksum = (self.unmodified_originalif self.unmodified_original is not None@@ -209,7 +204,6 @@ class ConsumerPlugin(version_doc.page_count = page_countversion_doc.mime_type = mime_typeversion_doc.original_filename = self.filename- version_doc.storage_path = root_doc.storage_path# Clear unique file path fields so they can be generated uniquely laterversion_doc.filename = Noneversion_doc.archive_filename = Nonediff --git a/src/documents/file_handling.py b/src/documents/file_handling.pyindex 17ae84d9b..7f59d4557 100644--- a/src/documents/file_handling.py+++ b/src/documents/file_handling.py@@ -129,12 +129,19 @@ def generate_filename(archive_filename=False,use_format=True,) -> Path:+ # version docs use the root document for formatting, just with a suffix+ context_doc = doc if doc.root_document_id is None else doc.root_document+ version_suffix = (+ f"_v{doc.version_index}"+ if doc.root_document_id is not None and doc.version_index is not None+ else ""+ )base_path: Path | None = None# Determine the source of the format stringif use_format:- if doc.storage_path is not None:- filename_format = doc.storage_path.path+ if context_doc.storage_path is not None:+ filename_format = context_doc.storage_path.pathelif settings.FILENAME_FORMAT is not None:# Maybe convert old to new stylefilename_format = convert_format_str_to_template_format(@@ -147,7 +154,7 @@ def generate_filename(# If we have one, render itif filename_format is not None:- rendered_path: str | None = format_filename(doc, filename_format)+ rendered_path: str | None = format_filename(context_doc, filename_format)if rendered_path:base_path = Path(rendered_path)@@ -161,7 +168,7 @@ def generate_filename(base_filename = base_path.name# Build the final filename with counter and filetype- final_filename = f"{base_filename}{counter_str}{filetype_str}"+ final_filename = f"{base_filename}{version_suffix}{counter_str}{filetype_str}"# If we have a directory component, include itif str(directory) != ".":@@ -170,7 +177,9 @@ def generate_filename(full_path = Path(final_filename)else:# No template, use document ID- final_filename = f"{doc.pk:07}{counter_str}{filetype_str}"+ final_filename = (+ f"{context_doc.pk:07}{version_suffix}{counter_str}{filetype_str}"+ )full_path = Path(final_filename)return full_pathdiff --git a/src/documents/migrations/0016_document_version_index_and_more.py b/src/documents/migrations/0016_document_version_index_and_more.pynew file mode 100644index 000000000..9c85b05d3--- /dev/null+++ b/src/documents/migrations/0016_document_version_index_and_more.py@@ -0,0 +1,37 @@+# Generated by Django 5.2.11 on 2026-03-02 17:48++from django.conf import settings+from django.db import migrations+from django.db import models+++class Migration(migrations.Migration):+ dependencies = [+ ("documents", "0015_savedview_visibility_to_ui_settings"),+ migrations.swappable_dependency(settings.AUTH_USER_MODEL),+ ]++ operations = [+ migrations.AddField(+ model_name="document",+ name="version_index",+ field=models.PositiveIntegerField(+ blank=True,+ db_index=True,+ help_text="Index of this version within the root document.",+ null=True,+ verbose_name="version index",+ ),+ ),+ migrations.AddConstraint(+ model_name="document",+ constraint=models.UniqueConstraint(+ condition=models.Q(+ ("root_document__isnull", False),+ ("version_index__isnull", False),+ ),+ fields=("root_document", "version_index"),+ name="documents_document_root_version_index_uniq",+ ),+ ),+ ]diff --git a/src/documents/models.py b/src/documents/models.pyindex f0191b47f..b1b914069 100644--- a/src/documents/models.py+++ b/src/documents/models.py@@ -319,6 +319,14 @@ class Document(SoftDeleteModel, ModelWithOwner): # type: ignore[django-manager-verbose_name=_("root document for this version"),)+ version_index = models.PositiveIntegerField(+ _("version index"),+ blank=True,+ null=True,+ db_index=True,+ help_text=_("Index of this version within the root document."),+ )+version_label = models.CharField(_("version label"),max_length=64,@@ -331,6 +339,16 @@ class Document(SoftDeleteModel, ModelWithOwner): # type: ignore[django-manager-ordering = ("-created",)verbose_name = _("document")verbose_name_plural = _("documents")+ constraints = [+ models.UniqueConstraint(+ fields=["root_document", "version_index"],+ condition=models.Q(+ root_document__isnull=False,+ version_index__isnull=False,+ ),+ name="documents_document_root_version_index_uniq",+ ),+ ]def __str__(self) -> str:created = self.created.isoformat()diff --git a/src/documents/signals/handlers.py b/src/documents/signals/handlers.pyindex e2f1e7bc2..81dd3ddd9 100644--- a/src/documents/signals/handlers.py+++ b/src/documents/signals/handlers.py@@ -620,6 +620,16 @@ def update_filename_and_move_files(root=settings.ARCHIVE_DIR,)+ # Keep version files in sync with root+ if instance.root_document_id is None:+ for version_doc in Document.objects.filter(root_document_id=instance.pk).only(+ "pk",+ ):+ update_filename_and_move_files(+ Document,+ version_doc,+ )+@shared_taskdef process_cf_select_update(custom_field: CustomField) -> None:diff --git a/src/documents/tests/test_consumer.py b/src/documents/tests/test_consumer.pyindex d0ce5ff8c..121717f08 100644--- a/src/documents/tests/test_consumer.py+++ b/src/documents/tests/test_consumer.py@@ -726,6 +726,13 @@ class TestConsumer(self.assertIsNotNone(root_doc)assert root_doc is not None+ root_storage_path = StoragePath.objects.create(+ name="version-root-path",+ path="root/{{title}}",+ )+ root_doc.storage_path = root_storage_path+ root_doc.save()+actor = User.objects.create_user(username="actor",email="[email protected]",@@ -762,7 +769,7 @@ class TestConsumer()consumer.setup()try:- self.assertTrue(consumer.filename.endswith("_v0.pdf"))+ self.assertEqual(consumer.filename, version_file.name)consumer.run()finally:consumer.cleanup()@@ -772,8 +779,9 @@ class TestConsumer(version = versions.first()assert version is not Noneassert version.original_filename is not None+ self.assertEqual(version.version_index, 1)self.assertEqual(version.version_label, "v2")- self.assertTrue(version.original_filename.endswith("_v0.pdf"))+ self.assertEqual(version.original_filename, version_file.name)self.assertTrue(bool(version.content))@override_settings(AUDIT_LOG_ENABLED=True)@@ -822,7 +830,7 @@ class TestConsumer()consumer.setup()try:- self.assertEqual(consumer.filename, "valid_pdf_version-upload_v0")+ self.assertEqual(consumer.filename, "valid_pdf_version-upload")consumer.run()finally:consumer.cleanup()@@ -832,9 +840,67 @@ class TestConsumer()self.assertIsNotNone(version)assert version is not None- self.assertEqual(version.original_filename, "valid_pdf_version-upload_v0")+ self.assertEqual(version.version_index, 1)+ self.assertEqual(version.original_filename, "valid_pdf_version-upload")self.assertTrue(bool(version.content))+ @override_settings(AUDIT_LOG_ENABLED=True)+ @mock.patch("documents.consumer.load_classifier")+ def test_consume_version_index_monotonic_after_version_deletion(self, m) -> None:+ m.return_value = MagicMock()++ with self.get_consumer(self.get_test_file()) as consumer:+ consumer.run()++ root_doc = Document.objects.first()+ self.assertIsNotNone(root_doc)+ assert root_doc is not None++ def consume_version(version_file: Path) -> Document:+ status = DummyProgressManager(version_file.name, None)+ overrides = DocumentMetadataOverrides()+ doc = ConsumableDocument(+ DocumentSource.ApiUpload,+ original_file=version_file,+ root_document_id=root_doc.pk,+ )+ preflight = ConsumerPreflightPlugin(+ doc,+ overrides,+ status, # type: ignore[arg-type]+ self.dirs.scratch_dir,+ "task-id",+ )+ preflight.setup()+ preflight.run()++ consumer = ConsumerPlugin(+ doc,+ overrides,+ status, # type: ignore[arg-type]+ self.dirs.scratch_dir,+ "task-id",+ )+ consumer.setup()+ try:+ consumer.run()+ finally:+ consumer.cleanup()++ version = (+ Document.objects.filter(root_document=root_doc).order_by("-id").first()+ )+ assert version is not None+ return version++ v1 = consume_version(self.get_test_file2())+ self.assertEqual(v1.version_index, 1)+ v1.delete()++ # The next version should have version_index 2, even though version_index 1 was deleted+ v2 = consume_version(self.get_test_file())+ self.assertEqual(v2.version_index, 2)+@mock.patch("documents.consumer.load_classifier")def testClassifyDocument(self, m) -> None:correspondent = Correspondent.objects.create(diff --git a/src/documents/tests/test_file_handling.py b/src/documents/tests/test_file_handling.pyindex 8417c4ce7..0cd34e939 100644--- a/src/documents/tests/test_file_handling.py+++ b/src/documents/tests/test_file_handling.py@@ -77,6 +77,58 @@ class TestFileHandling(DirectoriesMixin, FileSystemAssertsMixin, TestCase):settings.ORIGINALS_DIR / "test" / "test.pdf",)+ @override_settings(FILENAME_FORMAT=None)+ def test_root_storage_path_change_updates_version_files(self) -> None:+ old_storage_path = StoragePath.objects.create(+ name="old-path",+ path="old/{{title}}",+ )+ new_storage_path = StoragePath.objects.create(+ name="new-path",+ path="new/{{title}}",+ )++ root_doc = Document.objects.create(+ title="rootdoc",+ mime_type="application/pdf",+ checksum="root-checksum",+ storage_path=old_storage_path,+ )+ version_doc = Document.objects.create(+ title="version-title",+ mime_type="application/pdf",+ checksum="version-checksum",+ root_document=root_doc,+ version_index=1,+ )++ Document.objects.filter(pk=root_doc.pk).update(+ filename=generate_filename(root_doc),+ )+ Document.objects.filter(pk=version_doc.pk).update(+ filename=generate_filename(version_doc),+ )+ root_doc.refresh_from_db()+ version_doc.refresh_from_db()++ create_source_path_directory(root_doc.source_path)+ Path(root_doc.source_path).touch()+ create_source_path_directory(version_doc.source_path)+ Path(version_doc.source_path).touch()++ root_doc.storage_path = new_storage_path+ root_doc.save()++ root_doc.refresh_from_db()+ version_doc.refresh_from_db()++ self.assertEqual(root_doc.filename, "new/rootdoc.pdf")+ self.assertEqual(version_doc.filename, "new/rootdoc_v1.pdf")+ self.assertIsFile(root_doc.source_path)+ self.assertIsFile(version_doc.source_path)+ self.assertIsNotFile(settings.ORIGINALS_DIR / "old" / "rootdoc.pdf")+ self.assertIsNotFile(settings.ORIGINALS_DIR / "old" / "rootdoc_v1.pdf")+@override_settings(FILENAME_FORMAT="{correspondent}/{correspondent}")def test_file_renaming_missing_permissions(self) -> None:document = Document()@@ -1226,6 +1278,94 @@ class TestFilenameGeneration(DirectoriesMixin, TestCase):Path("logs.pdf"),)+ @override_settings(FILENAME_FORMAT="{title}")+ def test_version_index_suffix_for_template_filename(self) -> None:+ root_doc = Document.objects.create(+ title="the_doc",+ mime_type="application/pdf",+ checksum="root-checksum",+ )+ version_doc = Document.objects.create(+ title="the_doc",+ mime_type="application/pdf",+ checksum="version-checksum",+ root_document=root_doc,+ version_index=1,+ )++ self.assertEqual(generate_filename(version_doc), Path("the_doc_v1.pdf"))+ self.assertEqual(+ generate_filename(version_doc, counter=1),+ Path("the_doc_v1_01.pdf"),+ )++ @override_settings(FILENAME_FORMAT=None)+ def test_version_index_suffix_for_default_filename(self) -> None:+ root_doc = Document.objects.create(+ title="root",+ mime_type="text/plain",+ checksum="root-checksum",+ )+ version_doc = Document.objects.create(+ title="root",+ mime_type="text/plain",+ checksum="version-checksum",+ root_document=root_doc,+ version_index=2,+ )++ self.assertEqual(+ generate_filename(version_doc),+ Path(f"{root_doc.pk:07d}_v2.txt"),+ )+ self.assertEqual(+ generate_filename(version_doc, archive_filename=True),+ Path(f"{root_doc.pk:07d}_v2.pdf"),+ )++ @override_settings(FILENAME_FORMAT="{original_name}")+ def test_version_index_suffix_with_original_name_placeholder(self) -> None:+ root_doc = Document.objects.create(+ title="root",+ mime_type="application/pdf",+ checksum="root-checksum",+ original_filename="root-upload.pdf",+ )+ version_doc = Document.objects.create(+ title="root",+ mime_type="application/pdf",+ checksum="version-checksum",+ root_document=root_doc,+ version_index=1,+ original_filename="version-upload.pdf",+ )++ self.assertEqual(generate_filename(version_doc), Path("root-upload_v1.pdf"))++ def test_version_index_suffix_with_storage_path(self) -> None:+ storage_path = StoragePath.objects.create(+ name="vtest",+ path="folder/{{title}}",+ )+ root_doc = Document.objects.create(+ title="storage_doc",+ mime_type="application/pdf",+ checksum="root-checksum",+ storage_path=storage_path,+ )+ version_doc = Document.objects.create(+ title="version_title_should_not_be_used",+ mime_type="application/pdf",+ checksum="version-checksum",+ root_document=root_doc,+ version_index=3,+ )++ self.assertEqual(+ generate_filename(version_doc),+ Path("folder/storage_doc_v3.pdf"),+ )+@override_settings(FILENAME_FORMAT="XX{correspondent}/{title}",FILENAME_FORMAT_REMOVE_NONE=True,