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.
This commit is contained in:
stumpylog committed 2026-11-19 13:54:59 -08:00
1 parent 8f1a6d21ce
commit 246f4e53b1
4 files changed
+152 -14

No files matched your search

+37
View File
@@ -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(
+80
View File
@@ -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)
+22 -14
View File
@@ -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."""
+13
View File
@@ -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