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