A community-supported supercharged document management system: scan, index and archive all your documents
Python aiangulararchivingdjangodmsdocument-managementdocument-management-systemllmmachine-learningocroptical-character-recognitionpdf
Fix: keep counter and extension when shortening long public filenames (#14472)
Trenton H183cfd2da4fd
diff --git a/src/documents/management/commands/document_exporter.py b/src/documents/management/commands/document_exporter.pyindex ea92f4e59..10b929679 100644--- a/src/documents/management/commands/document_exporter.py+++ b/src/documents/management/commands/document_exporter.py@@ -3,6 +3,7 @@ from itertools import islicefrom pathlib import Pathfrom typing import TYPE_CHECKINGfrom typing import Any+from typing import Finalfrom allauth.mfa.models import Authenticatorfrom allauth.socialaccount.models import SocialAccount@@ -70,6 +71,15 @@ from paperless.models import ApplicationConfigurationfrom paperless_mail.models import MailAccountfrom paperless_mail.models import MailRule+# Derived names replace the original's extension with these suffixes+THUMBNAIL_SUFFIX: Final[str] = "-thumbnail.webp"+ARCHIVE_SUFFIX: Final[str] = "-archive.pdf"+# Leave room for the longest derived suffix, which replaces the original's extension+MAX_BASE_NAME_BYTES: Final[int] = Document.MAX_PUBLIC_FILENAME_BYTES - max(+ len(THUMBNAIL_SUFFIX),+ len(ARCHIVE_SUFFIX),+)+def serialize_queryset_batched(queryset: "QuerySet[Any]",@@ -512,7 +522,10 @@ class Command(CryptMixin, PaperlessCommand):counter=filename_counter,)else:- base_name = document.get_public_filename(counter=filename_counter)+ base_name = document.get_public_filename(+ counter=filename_counter,+ max_bytes=MAX_BASE_NAME_BYTES,+ )# The thumbnail and archive names are derived from the stem, so# uniqueness must hold without the original's extension@@ -541,7 +554,7 @@ class Command(CryptMixin, PaperlessCommand):document_dict[EXPORTER_FILE_NAME] = original_arcif not self.no_thumbnail:- thumbnail_name = base_name.parent / (base_name.stem + "-thumbnail.webp")+ thumbnail_name = base_name.parent / (base_name.stem + THUMBNAIL_SUFFIX)if self.use_folder_prefix:thumbnail_name = Path("thumbnails") / thumbnail_namethumbnail_arc = thumbnail_name.as_posix()@@ -550,7 +563,7 @@ class Command(CryptMixin, PaperlessCommand):thumbnail_arc = Noneif not self.no_archive and document.has_archive_version:- archive_name = base_name.parent / (base_name.stem + "-archive.pdf")+ archive_name = base_name.parent / (base_name.stem + ARCHIVE_SUFFIX)if self.use_folder_prefix:archive_name = Path("archive") / archive_namearchive_arc = archive_name.as_posix()diff --git a/src/documents/models.py b/src/documents/models.pyindex ff8632b12..f5a9f6ddd 100644--- a/src/documents/models.py+++ b/src/documents/models.py@@ -157,6 +157,8 @@ class StoragePath(MatchingModel):class Document(SoftDeleteModel, ModelWithOwner): # type: ignore[django-manager-missing]MAX_STORED_FILENAME_LENGTH: Final[int] = 1024+ # Per-component limit of common filesystems (ext4, XFS, btrfs, ZFS, APFS)+ MAX_PUBLIC_FILENAME_BYTES: Final[int] = 255correspondent = models.ForeignKey(Correspondent,@@ -484,28 +486,37 @@ class Document(SoftDeleteModel, ModelWithOwner): # type: ignore[django-manager-def archive_file(self):return Path(self.archive_path).open("rb")- def get_public_filename(self, *, archive=False, counter=0, suffix=None) -> str:+ def get_public_filename(+ self,+ *,+ archive: bool = False,+ counter: int = 0,+ max_bytes: int = MAX_PUBLIC_FILENAME_BYTES,+ ) -> str:"""Returns a sanitized filename for the document, not including any paths.++ The name fits in max_bytes (UTF-8). A long title is shortened before+ the counter and extension are appended, because sanitize_filename+ truncates from the end. The tail is cut only when max_bytes is+ smaller than the tail itself."""# Root owns metadata for all versionscontext_document = (self.root_document if self.root_document_id is not None else self)- result = str(context_document)- if counter:- result += f"_{counter:02}"+ extension = ".pdf" if archive else self.file_type+ tail = f"_{counter:02}{extension}" if counter else extension- if suffix:- result += suffix+ head_bytes = max(0, max_bytes - len(tail.encode()))+ head = str(context_document).encode()[:head_bytes].decode(errors="ignore")- if archive:- result += ".pdf"- else:- result += self.file_type-- return pathvalidate.sanitize_filename(result, replacement_text="-")+ return pathvalidate.sanitize_filename(+ head + tail,+ replacement_text="-",+ max_len=max_bytes,+ )@propertydef file_type(self):diff --git a/src/documents/tests/test_document_model.py b/src/documents/tests/test_document_model.pyindex a6fb0b3f6..3ff51711e 100644--- a/src/documents/tests/test_document_model.py+++ b/src/documents/tests/test_document_model.py@@ -4,13 +4,16 @@ from datetime import datefrom pathlib import Pathfrom unittest import mock+import pytestfrom django.test import TestCasefrom django.test import override_settingsfrom faker import Faker+from pytest_mock import MockerFixturefrom documents.models import Correspondentfrom documents.models import Documentfrom documents.tasks import empty_trash+from paperless_testing.factories import DocumentFactoryclass TestDocument(TestCase):@@ -257,3 +260,72 @@ def test_suggestion_content() -> None:)doc.content = content_over_limitassert doc.suggestion_content == expected_cropped_content+++class TestPublicFilenameLength:+ @pytest.fixture(autouse=True)+ def _no_parser_registry(self, mocker: MockerFixture) -> None:+ # The parser registry reads ApplicationConfiguration from the database+ extensions = {"application/pdf": ".pdf", "image/jpeg": ".jpg"}+ mocker.patch(+ "documents.models.get_default_file_extension",+ side_effect=extensions.__getitem__,+ )++ LIMIT = Document.MAX_PUBLIC_FILENAME_BYTES++ @pytest.mark.parametrize(+ ("title", "archive", "counter", "max_bytes", "tail"),+ [+ pytest.param("a" * 300, False, 0, LIMIT, ".jpg", id="ascii"),+ pytest.param("a" * 300, True, 0, LIMIT, ".pdf", id="archive"),+ pytest.param("ä" * 200, False, 0, LIMIT, ".jpg", id="umlaut"),+ pytest.param("ä" * 200, False, 1, LIMIT, "_01.jpg", id="count"),+ pytest.param("a" * 300, False, 1, 100, "_01.jpg", id="max"),+ ],+ )+ def test_long_title_keeps_tail_within_limit(+ self,+ title: str,+ *,+ archive: bool,+ counter: int,+ max_bytes: int,+ tail: str,+ ) -> None:+ """+ GIVEN:+ - A document whose title alone is longer than the byte limit+ WHEN:+ - The public file name is generated+ THEN:+ - The name ends with the counter and extension+ - The name fits in the limit+ """+ name = DocumentFactory.build(+ title=title,+ mime_type="image/jpeg",+ ).get_public_filename(+ archive=archive,+ counter=counter,+ max_bytes=max_bytes,+ )++ assert name.endswith(tail)+ assert len(name.encode()) <= max_bytes++ def test_long_title_counters_give_distinct_names(self) -> None:+ """+ GIVEN:+ - A document whose title alone is longer than the byte limit+ WHEN:+ - Public file names are generated with increasing counters+ THEN:+ - Each counter produces a distinct name+ """+ doc = DocumentFactory.build(title="ä" * 200, mime_type="application/pdf")++ names = [doc.get_public_filename(counter=counter) for counter in range(3)]++ assert len(set(names)) == 3+ assert all(len(n.encode()) <= self.LIMIT for n in names)diff --git a/src/documents/tests/test_management_exporter.py b/src/documents/tests/test_management_exporter.pyindex 9a2c95e9e..3bfc909c8 100644--- a/src/documents/tests/test_management_exporter.py+++ b/src/documents/tests/test_management_exporter.py@@ -1537,3 +1537,70 @@ class TestExportDerivedFileNameCollisions:assert (target / record[EXPORTER_ARCHIVE_NAME]).read_text() == f"archive {pk}"++ def test_long_titles_export_within_file_name_limit(+ self,+ paperless_dirs: PaperlessDirs,+ tmp_path: Path,+ ) -> None:+ """+ GIVEN:+ - Two documents with the same created date and the same title+ - The title alone is longer than 255 bytes and contains umlauts+ WHEN:+ - The exporter runs+ THEN:+ - The export finishes with distinct original, thumbnail and archive names+ - Every exported file name fits in the byte limit+ - Each exported file holds its own document's content+ """+ for pk in (1, 2):+ (paperless_dirs.originals_dir / f"{pk:07}.pdf").write_bytes(+ f"original {pk}".encode(),+ )+ (paperless_dirs.archive_dir / f"{pk:07}.pdf").write_bytes(+ f"archive {pk}".encode(),+ )+ (paperless_dirs.thumbnail_dir / f"{pk:07}.webp").write_bytes(+ f"thumbnail {pk}".encode(),+ )+ DocumentFactory(+ pk=pk,+ title="Bestellbestätigung " * 15,+ created=date(2026, 10, 15),+ filename=f"{pk:07}.pdf",+ archive_filename=f"{pk:07}.pdf",+ mime_type="application/pdf",+ )++ target = tmp_path / "export"+ target.mkdir()+ call_command(+ "document_exporter",+ str(target),+ "--no-progress-bar",+ skip_checks=True,+ )++ manifest = json.loads((target / "manifest.json").read_text())+ records = {r["pk"]: r for r in manifest if r["model"] == "documents.document"}++ for key in (+ EXPORTER_FILE_NAME,+ EXPORTER_THUMBNAIL_NAME,+ EXPORTER_ARCHIVE_NAME,+ ):+ assert records[1][key] != records[2][key]++ for pk in (1, 2):+ record = records[pk]+ for key, content in (+ (EXPORTER_FILE_NAME, f"original {pk}"),+ (EXPORTER_THUMBNAIL_NAME, f"thumbnail {pk}"),+ (EXPORTER_ARCHIVE_NAME, f"archive {pk}"),+ ):+ assert (+ len(Path(record[key]).name.encode())+ <= Document.MAX_PUBLIC_FILENAME_BYTES+ )+ assert (target / record[key]).read_text() == content