From 246f4e53b175a4d85f72de174ea231c12a7dd395 Mon Sep 17 00:00:00 2001 From: stumpylog <797416+stumpylog@users.noreply.github.com> Date: Thu, 19 Nov 2026 13:54:59 -0800 Subject: [PATCH] Chore: describe the zone OCR responses in the API schema The run status and skip reason were string literals, and the test zone and 404 bodies had no schema. Add enums and response serializers for them. The JSON is unchanged. --- src/documents/serialisers.py | 37 +++++++++++++ src/documents/tests/test_zone_ocr.py | 80 ++++++++++++++++++++++++++++ src/documents/views.py | 36 ++++++++----- src/documents/zone_ocr.py | 13 +++++ 4 files changed, 152 insertions(+), 14 deletions(-) diff --git a/src/documents/serialisers.py b/src/documents/serialisers.py index f8089f499a..b5781a2e9d 100644 --- a/src/documents/serialisers.py +++ b/src/documents/serialisers.py @@ -101,6 +101,8 @@ from documents.versioning import has_prefetched_effective_content from documents.versioning import sort_versions_newest_first from documents.zone_ocr import ZoneOcrReason from documents.zone_ocr import ZoneOcrResult +from documents.zone_ocr import ZoneOcrRunStatus +from documents.zone_ocr import ZoneOcrSkipReason from documents.zone_ocr import field_key if TYPE_CHECKING: @@ -1853,6 +1855,28 @@ class ZoneOcrResultSerializer(serializers.Serializer[ZoneOcrResult]): ) +class RunZoneOcrResponseSerializer(serializers.Serializer[dict[str, Any]]): + """The response of running zone OCR on one document.""" + + status = serializers.ChoiceField( + choices=[status.value for status in ZoneOcrRunStatus], + read_only=True, + ) + reason = serializers.ChoiceField( + choices=[reason.value for reason in ZoneOcrSkipReason], + read_only=True, + required=False, + help_text="Present only when the run was skipped.", + ) + results = ZoneOcrResultSerializer(many=True, read_only=True) + + +class OcrErrorSerializer(serializers.Serializer[dict[str, Any]]): + """The body of an error response from the OCR template actions.""" + + error = serializers.CharField(read_only=True) + + class RunZoneOcrDocumentsSerializer(DocumentSelectionSerializer, RunZoneOcrSerializer): from_webui = serializers.BooleanField(required=False, default=False) @@ -3944,6 +3968,19 @@ class OcrTemplateTestSerializer(serializers.Serializer[dict[str, Any]]): ) +class OcrTemplateTestResultSerializer(serializers.Serializer[dict[str, Any]]): + """The extraction preview returned for an ad-hoc zone.""" + + raw_text = serializers.CharField(read_only=True, allow_null=True) + value = serializers.CharField(read_only=True, allow_null=True) + regex = serializers.CharField(read_only=True, allow_null=True) + regex_match = serializers.BooleanField( + read_only=True, + allow_null=True, + help_text="Whether the value fully matches the regex, or null when not checked.", + ) + + class OcrTemplateSerializer(MatchRuleSerializer, OwnedObjectSerializer): zones = OcrTemplateZoneSerializer(many=True, required=False) combine_formats = serializers.DictField( diff --git a/src/documents/tests/test_zone_ocr.py b/src/documents/tests/test_zone_ocr.py index a86ca49362..40d83fc410 100644 --- a/src/documents/tests/test_zone_ocr.py +++ b/src/documents/tests/test_zone_ocr.py @@ -25,11 +25,15 @@ from documents.models import MatchingModel from documents.models import OcrTemplate from documents.models import OcrTemplateZone from documents.parsers import ParseError +from documents.serialisers import OcrTemplateTestResultSerializer +from documents.serialisers import RunZoneOcrResponseSerializer from documents.serialisers import ZoneOcrResultSerializer from documents.zone_ocr import MAX_PARSED_TEXT_LENGTH from documents.zone_ocr import ZoneExtraction from documents.zone_ocr import ZoneOcrReason from documents.zone_ocr import ZoneOcrResult +from documents.zone_ocr import ZoneOcrRunStatus +from documents.zone_ocr import ZoneOcrSkipReason from documents.zone_ocr import ZoneValue from documents.zone_ocr import _apply_transform from documents.zone_ocr import _combine_field_value @@ -3863,3 +3867,79 @@ class TestZoneOcrResultSerializer: assert JSONRenderer().render( ZoneOcrResultSerializer(result).data, ) == JSONRenderer().render(asdict(result)) + + +class TestRunZoneOcrResponseSerializer: + @pytest.mark.parametrize( + "body", + [ + pytest.param( + { + "status": ZoneOcrRunStatus.SKIPPED, + "reason": ZoneOcrSkipReason.NO_TEMPLATE, + "results": [], + }, + id="skipped", + ), + pytest.param( + { + "status": ZoneOcrRunStatus.COMPLETED, + "results": [ + { + "template": "Template", + "zone": "Zone", + "custom_field": "Title", + "value": "text", + "reason": None, + }, + ], + }, + id="completed", + ), + ], + ) + def test_renders_body_unchanged(self, body: dict[str, Any]) -> None: + """ + GIVEN: + - A response body with the run status and results fields + WHEN: + - The body is rendered through the response serializer as JSON + THEN: + - The JSON equals the body rendered directly + """ + assert JSONRenderer().render( + RunZoneOcrResponseSerializer(body).data, + ) == JSONRenderer().render(body) + + +class TestOcrTemplateTestResultSerializer: + @pytest.mark.parametrize( + "body", + [ + pytest.param( + { + "raw_text": "abc", + "value": "abc", + "regex": "a.*", + "regex_match": True, + }, + id="matched", + ), + pytest.param( + {"raw_text": None, "value": None, "regex": None, "regex_match": None}, + id="all-null", + ), + ], + ) + def test_renders_body_unchanged(self, body: dict[str, Any]) -> None: + """ + GIVEN: + - A response body with the OCR template test result fields + WHEN: + - The body is rendered through the result serializer as JSON + THEN: + - The JSON equals the body rendered directly + """ + assert JSONRenderer().render( + OcrTemplateTestResultSerializer(body).data, + ) == JSONRenderer().render(body) diff --git a/src/documents/views.py b/src/documents/views.py index c1591873f3..bc135fd563 100644 --- a/src/documents/views.py +++ b/src/documents/views.py @@ -220,7 +220,9 @@ from documents.serialisers import MergeDocumentsAsVersionsSerializer from documents.serialisers import MergeDocumentsSerializer from documents.serialisers import NoteCreateSerializer from documents.serialisers import NotesSerializer +from documents.serialisers import OcrErrorSerializer from documents.serialisers import OcrTemplateSerializer +from documents.serialisers import OcrTemplateTestResultSerializer from documents.serialisers import OcrTemplateTestSerializer from documents.serialisers import PostDocumentSerializer from documents.serialisers import RemovePasswordDocumentsSerializer @@ -228,6 +230,7 @@ from documents.serialisers import ReprocessDocumentsSerializer from documents.serialisers import RotateDocumentsSerializer from documents.serialisers import RunTaskSerializer from documents.serialisers import RunZoneOcrDocumentsSerializer +from documents.serialisers import RunZoneOcrResponseSerializer from documents.serialisers import RunZoneOcrSerializer from documents.serialisers import SavedViewSerializer from documents.serialisers import SearchResultSerializer @@ -2284,17 +2287,10 @@ class DocumentViewSet( ), ], request=RunZoneOcrSerializer, - responses=inline_serializer( - name="RunZoneOcrResult", - fields={ - "status": serializers.ChoiceField(choices=["completed", "skipped"]), - "reason": serializers.ChoiceField( - choices=["no_template"], - required=False, - ), - "results": ZoneOcrResultSerializer(many=True), - }, - ), + responses={ + (200, "application/json"): RunZoneOcrResponseSerializer, + (404, "application/json"): OcrErrorSerializer, + }, ) @action( methods=["post"], @@ -2324,6 +2320,8 @@ class DocumentViewSet( ) or not has_perms_owner_aware(user, "change_document", document): return HttpResponseForbidden("Insufficient permissions") + from documents.zone_ocr import ZoneOcrRunStatus + from documents.zone_ocr import ZoneOcrSkipReason from documents.zone_ocr import get_templates_for_document from documents.zone_ocr import run_zone_extraction @@ -2341,7 +2339,11 @@ class DocumentViewSet( ) if not templates: return Response( - {"status": "skipped", "reason": "no_template", "results": []}, + { + "status": ZoneOcrRunStatus.SKIPPED, + "reason": ZoneOcrSkipReason.NO_TEMPLATE, + "results": [], + }, ) doc_path = file_document.archive_path or file_document.source_path @@ -2354,7 +2356,7 @@ class DocumentViewSet( results = run_zone_extraction(file_document, templates=templates, reindex=True) return Response( { - "status": "completed", + "status": ZoneOcrRunStatus.COMPLETED, "results": ZoneOcrResultSerializer(results, many=True).data, }, ) @@ -5903,7 +5905,13 @@ class OcrTemplateViewSet(BulkPermissionMixin, PassUserMixin, ModelViewSet[OcrTem return HttpResponse(content, content_type="image/png") - @extend_schema(request=OcrTemplateTestSerializer) + @extend_schema( + request=OcrTemplateTestSerializer, + responses={ + (200, "application/json"): OcrTemplateTestResultSerializer, + (404, "application/json"): OcrErrorSerializer, + }, + ) @action(detail=False, methods=["post"], url_path="test-zone") def test_zone(self, request: Request) -> HttpResponse: """Extract an ad-hoc zone without changing the document.""" diff --git a/src/documents/zone_ocr.py b/src/documents/zone_ocr.py index 2ea120ff45..31c87be12e 100644 --- a/src/documents/zone_ocr.py +++ b/src/documents/zone_ocr.py @@ -125,6 +125,19 @@ class ZoneOcrReason(StrEnum): TEMPLATE_FAILED = "template_failed" +class ZoneOcrRunStatus(StrEnum): + """The overall outcome of a zone OCR run on one document.""" + + COMPLETED = "completed" + SKIPPED = "skipped" + + +class ZoneOcrSkipReason(StrEnum): + """Why a zone OCR run on one document was skipped.""" + + NO_TEMPLATE = "no_template" + + @dataclass(kw_only=True, slots=True) class ZoneOcrResult: template: str