Chore: give OCR templates their own matching fields

Templates are never assigned to documents, so the classifier-based Automatic
matching inherited from MatchingModel could never work. Declare the matching
fields with the workflow trigger choices instead. Also keep zones when their
custom field is deleted, allow longer OCR language lists, fix help texts,
and regenerate the unreleased migration.
This commit is contained in:
stumpylog committed 2026-11-19 10:04:31 -08:00
1 parent 8e07452604
commit 4c2df48795
6 files changed
+91 -36

No files matched your search

+6 -2
View File
@@ -14,6 +14,7 @@ from documents.models import Correspondent
from documents.models import Document
from documents.models import DocumentType
from documents.models import MatchingModel
from documents.models import OcrTemplate
from documents.models import StoragePath
from documents.models import Tag
from documents.models import Workflow
@@ -30,7 +31,7 @@ logger = logging.getLogger("paperless.matching")
def log_reason(
matching_model: MatchingModel | WorkflowTrigger,
matching_model: MatchingModel | WorkflowTrigger | OcrTemplate,
document: Document,
reason: str,
) -> None:
@@ -161,7 +162,10 @@ def match_storage_paths(document: Document, classifier: DocumentClassifier, user
)
def matches(matching_model: MatchingModel, document: Document):
def matches(
matching_model: MatchingModel | WorkflowTrigger | OcrTemplate,
document: Document,
):
search_flags = 0
document_content = document.get_effective_content() or ""
@@ -1,4 +1,4 @@
# Generated by Django 5.2.17 on 2026-10-20 20:29
# Generated by Django 5.2.18 on 2026-11-19 17:29
import django.core.validators
import django.db.models.deletion
@@ -42,7 +42,6 @@ class Migration(migrations.Migration):
(3, "Exact match"),
(4, "Regular expression"),
(5, "Fuzzy word"),
(6, "Automatic"),
],
default=1,
verbose_name="matching algorithm",
@@ -161,7 +160,7 @@ class Migration(migrations.Migration):
"page",
models.IntegerField(
blank=True,
help_text="Page (1 = first, -1 = last; blank uses the template default)",
help_text="Page (1 = first, -1 = last; blank = first page)",
null=True,
verbose_name="page",
),
@@ -219,7 +218,7 @@ class Migration(migrations.Migration):
models.CharField(
default="eng",
help_text="Tesseract language code(s), e.g. 'deu+eng'",
max_length=20,
max_length=32,
verbose_name="OCR language",
),
),
@@ -259,7 +258,7 @@ class Migration(migrations.Migration):
models.CharField(
blank=True,
default="",
help_text="Optional regex pattern — extracted text is only accepted if it matches",
help_text="Optional regex pattern. Extracted text is only accepted if it fully matches.",
max_length=256,
verbose_name="validation regex",
),
@@ -271,7 +270,7 @@ class Migration(migrations.Migration):
blank=True,
help_text="Target custom field (only used when target is 'custom_field')",
null=True,
on_delete=django.db.models.deletion.CASCADE,
on_delete=django.db.models.deletion.SET_NULL,
related_name="ocr_zones",
to="documents.customfield",
verbose_name="custom field",
+35 -6
View File
@@ -2218,9 +2218,22 @@ class WorkflowRun(SoftDeleteModel):
return f"WorkflowRun of {self.workflow} at {self.run_at} on {self.document}"
class OcrTemplate(MatchingModel):
class OcrTemplate(ModelWithOwner):
"""Matching rules and extraction zones for documents with a common layout."""
name = models.CharField(_("name"), max_length=128)
match = models.CharField(_("match"), max_length=256, blank=True)
# Templates are never assigned by the classifier, so there is no auto matching.
matching_algorithm = models.PositiveSmallIntegerField(
_("matching algorithm"),
choices=WorkflowTrigger.WorkflowTriggerMatching.choices,
default=MatchingModel.MATCH_ANY,
)
is_insensitive = models.BooleanField(_("is insensitive"), default=True)
source_width = models.PositiveIntegerField(
_("source width"),
validators=[MinValueValidator(1)],
@@ -2268,9 +2281,25 @@ class OcrTemplate(MatchingModel):
auto_now=True,
)
class Meta(MatchingModel.Meta):
class Meta(ModelWithOwner.Meta):
abstract = False
verbose_name = _("OCR template")
verbose_name_plural = _("OCR templates")
ordering = ("name",)
constraints = [
models.UniqueConstraint(
fields=["name", "owner"],
name="%(app_label)s_%(class)s_unique_name_owner",
),
models.UniqueConstraint(
name="%(app_label)s_%(class)s_name_uniq",
fields=["name"],
condition=models.Q(owner__isnull=True),
),
]
def __str__(self) -> str:
return self.name
class OcrTemplateZone(models.Model):
@@ -2308,7 +2337,7 @@ class OcrTemplateZone(models.Model):
custom_field = models.ForeignKey(
"documents.CustomField",
on_delete=models.CASCADE,
on_delete=models.SET_NULL,
related_name="ocr_zones",
verbose_name=_("custom field"),
null=True,
@@ -2320,7 +2349,7 @@ class OcrTemplateZone(models.Model):
_("page"),
null=True,
blank=True,
help_text=_("Page (1 = first, -1 = last; blank uses the template default)"),
help_text=_("Page (1 = first, -1 = last; blank = first page)"),
)
x = models.PositiveIntegerField(_("x"), help_text=_("Left edge (px)"))
@@ -2358,7 +2387,7 @@ class OcrTemplateZone(models.Model):
ocr_language = models.CharField(
_("OCR language"),
max_length=20,
max_length=32,
default="eng",
help_text=_("Tesseract language code(s), e.g. 'deu+eng'"),
)
@@ -2400,7 +2429,7 @@ class OcrTemplateZone(models.Model):
blank=True,
default="",
help_text=_(
"Optional regex pattern — extracted text is only accepted if it matches",
"Optional regex pattern. Extracted text is only accepted if it fully matches.",
),
)
+16 -21
View File
@@ -171,14 +171,10 @@ class DocumentUpdateFieldsModelSerializer(DynamicFieldsModelSerializer):
return instance
class MatchingModelSerializer(serializers.ModelSerializer[Any]):
document_count = serializers.IntegerField(read_only=True)
def get_slug(self, obj) -> str:
return slugify(obj.name)
slug = SerializerMethodField()
# Name and owner uniqueness and match regex validation for models with a name,
# an owner and match rules. A comment, not a docstring, so it stays out of the
# API schema descriptions of every serializer built on it.
class MatchRuleSerializer(serializers.ModelSerializer[Any]):
def validate(self, data):
# TODO: remove pending https://github.com/encode/django-rest-framework/issues/7173
name = data.get(
@@ -217,6 +213,15 @@ class MatchingModelSerializer(serializers.ModelSerializer[Any]):
return match
class MatchingModelSerializer(MatchRuleSerializer):
document_count = serializers.IntegerField(read_only=True)
def get_slug(self, obj) -> str:
return slugify(obj.name)
slug = SerializerMethodField()
class SetPermissionsMixin:
def _validate_user_ids(self, user_ids):
users = User.objects.none()
@@ -3827,7 +3832,8 @@ class OcrTemplateZoneSerializer(serializers.ModelSerializer):
{name: field.error_messages["required"]},
)
# A custom field target may be left unassigned, as the editor creates new
# zones; built-in targets never use a custom field.
# zones, and a zone is left unassigned when its custom field is deleted;
# built-in targets never use a custom field.
if (
data.get("target", OcrTemplateZone.TargetType.CUSTOM_FIELD)
!= OcrTemplateZone.TargetType.CUSTOM_FIELD
@@ -3897,17 +3903,13 @@ def _zone_field_key(zone: dict[str, Any]) -> str:
return target
class OcrTemplateSerializer(MatchingModelSerializer, OwnedObjectSerializer):
class OcrTemplateSerializer(MatchRuleSerializer, OwnedObjectSerializer):
zones = OcrTemplateZoneSerializer(many=True, required=False)
combine_formats = serializers.DictField(
child=serializers.CharField(allow_blank=True, trim_whitespace=False),
required=False,
)
# Templates are never assigned to documents
slug = None
document_count = None
def __init__(self, *args: Any, **kwargs: Any) -> None:
super().__init__(*args, **kwargs)
# Writes accept documents the user can view, plus the sample document
@@ -3947,13 +3949,6 @@ class OcrTemplateSerializer(MatchingModelSerializer, OwnedObjectSerializer):
]
read_only_fields = ["created", "updated"]
def validate_matching_algorithm(self, value):
if value == MatchingModel.MATCH_AUTO:
raise serializers.ValidationError(
"Automatic matching is not supported for OCR templates.",
)
return value
def validate(self, data):
data = super().validate(data)
if "zones" in data:
+28 -1
View File
@@ -1680,6 +1680,33 @@ class TestOcrTemplateDelete:
assert OcrTemplate.objects.count() == 0
assert OcrTemplateZone.objects.count() == 0
def test_deleting_a_custom_field_keeps_its_zones(
self,
text_field: CustomField,
) -> None:
"""
GIVEN:
- A template with a zone targeting a custom field
WHEN:
- The custom field is deleted
THEN:
- The zone is kept with no custom field assigned
"""
template = OcrTemplateFactory(name="Keeps Zones", match="Northwind")
zone = OcrTemplateZoneFactory(
template=template,
name="Zone",
target=OcrTemplateZone.TargetType.CUSTOM_FIELD,
custom_field=text_field,
height=100,
)
text_field.delete()
zone.refresh_from_db()
assert zone.custom_field is None
assert OcrTemplate.objects.filter(pk=template.pk).exists()
def test_nonexistent_returns_404(self, admin_client: APIClient) -> None:
"""
GIVEN:
@@ -2585,7 +2612,7 @@ class TestZonePreview:
pytest.param({"page": 0}, id="page-zero"),
pytest.param({"page": -2}, id="page-below-last"),
pytest.param({"transform": "invalid"}, id="unknown-transform"),
pytest.param({"ocr_language": "x" * 21}, id="language-too-long"),
pytest.param({"ocr_language": "x" * 33}, id="language-too-long"),
pytest.param(
{"zone_source_width": "invalid"},
id="non-numeric-source-width",
+1
View File
@@ -227,6 +227,7 @@ SPECTACULAR_SETTINGS = {
},
"ENUM_NAME_OVERRIDES": {
"MatchingAlgorithm": "documents.models.MatchingModel.MATCHING_ALGORITHMS",
"WorkflowTriggerMatchingAlgorithmEnum": "documents.models.WorkflowTrigger.WorkflowTriggerMatching",
"BarcodeFormatEnum": "documents.models.DocumentBarcode.Format",
"NoteFormatEnum": "documents.models.Note.Format",
},