models: Add validators to handle demo redacted values in PDF metadata

- Introduced `BeforeValidator` to process demo redacted values for various
  fields in `_internal.py` and `public.py`.
- Added `demo_value_sanitizers` module to centralize logic for detecting
  and replacing demo redacted values with appropriate defaults:
  - For boolean fields: replace with `True` or `False`.
  - For integer fields: replace with `0`.
  - For file IDs: replace with a placeholder UUID.
- Applied validators to metadata properties, ensuring consistent handling
  of demo data input.

Assisted-by: Codex

Author: datalogics-kam

src/pdfrest/models/_demo_value_sanitizers.py

@@ -0,0 +1,86 @@
+from __future__ import annotations
+
+import logging
+import re
+from typing import Any
+
+from pydantic import ValidationInfo
+
+LOGGER = logging.getLogger("pdfrest.models")
+
+_DEMO_UUID = "00000000-0000-4000-8000-000000000000"
+_REDACTED_X_PATTERN = re.compile(r"^[Xx-]{8,}$")
+
+
+def _field_name(info: ValidationInfo) -> str:
+    return info.field_name or "<unknown>"
+
+
+def _looks_like_demo_redaction(value: Any) -> bool:
+    if not isinstance(value, str):
+        return False
+    if _looks_like_generate_redacted_string(value):
+        return True
+    return bool(_REDACTED_X_PATTERN.fullmatch(value))
+
+
+def _looks_like_generate_redacted_string(value: str) -> bool:
+    """Detect strings redacted by PDFCloud-API generateRedactedString.
+
+    The upstream redactor preserves the first two characters and replaces all
+    non-whitespace characters after that with '*'.
+    """
+    if len(value) < 3:
+        return False
+    tail = value[2:]
+    if "*" not in tail:
+        return False
+    return all(char == "*" or char.isspace() for char in tail)
+
+
+def _log_replacement(original: Any, replacement: Any, info: ValidationInfo) -> None:
+    LOGGER.warning(
+        "Demo value %s detected in %s; replaced with %s",
+        original,
+        _field_name(info),
+        replacement,
+    )
+
+
+def _demo_bool_or_passthrough(
+    value: Any, info: ValidationInfo, *, replacement: bool
+) -> Any:
+    if value is None or isinstance(value, bool):
+        return value
+    if _looks_like_demo_redaction(value):
+        _log_replacement(value, replacement, info)
+        return replacement
+    return value
+
+
+def demo_bool_false_or_passthrough(value: Any, info: ValidationInfo) -> Any:
+    return _demo_bool_or_passthrough(value, info, replacement=False)
+
+
+def demo_bool_true_or_passthrough(value: Any, info: ValidationInfo) -> Any:
+    return _demo_bool_or_passthrough(value, info, replacement=True)
+
+
+def demo_file_id_or_passthrough(value: Any, info: ValidationInfo) -> Any:
+    if value is None:
+        return value
+    if _looks_like_demo_redaction(value):
+        replacement = _DEMO_UUID
+        _log_replacement(value, replacement, info)
+        return replacement
+    return value
+
+
+def demo_int_or_passthrough(value: Any, info: ValidationInfo) -> Any:
+    if value is None or isinstance(value, int):
+        return value
+    if _looks_like_demo_redaction(value):
+        replacement = 0
+        _log_replacement(value, replacement, info)
+        return replacement
+    return value

src/pdfrest/models/_internal.py

@@ -45,6 +45,7 @@
     WatermarkHorizontalAlignment,
     WatermarkVerticalAlignment,
 )
+from ._demo_value_sanitizers import demo_file_id_or_passthrough
 from .public import PdfRestFile, PdfRestFileID
 
 PdfConvertColorProfile = PdfPresetColorProfile | Literal["custom"]
@@ -2584,7 +2585,11 @@ class PdfRestRawUploadedFile(BaseModel):
     """
 
     name: Annotated[str, Field(description="The name of the file")]
-    id: Annotated[PdfRestFileID, Field(description="The id of the file")]
+    id: Annotated[
+        PdfRestFileID,
+        BeforeValidator(demo_file_id_or_passthrough),
+        Field(description="The id of the file"),
+    ]
     output_url: Annotated[
         list[HttpUrl] | HttpUrl | None,
         Field(description="The url of the unzipped file", alias="outputUrl"),

src/pdfrest/models/public.py

@@ -11,6 +11,7 @@
     AliasChoices,
     AwareDatetime,
     BaseModel,
+    BeforeValidator,
     ConfigDict,
     Field,
     HttpUrl,
@@ -20,6 +21,12 @@
 from pydantic_core import CoreSchema
 from typing_extensions import override
 
+from ._demo_value_sanitizers import (
+    demo_bool_false_or_passthrough,
+    demo_bool_true_or_passthrough,
+    demo_int_or_passthrough,
+)
+
 __all__ = (
     "ExtractTextResponse",
     "ExtractedTextDocument",
@@ -851,6 +858,7 @@ class PdfRestInfoResponse(BaseModel):
 
     tagged: Annotated[
         bool | None,
+        BeforeValidator(demo_bool_false_or_passthrough),
         Field(
             description="Indicates whether structure tags are present in the PDF "
             "document. The result is true or false."
@@ -860,6 +868,7 @@ class PdfRestInfoResponse(BaseModel):
 
     image_only: Annotated[
         bool | None,
+        BeforeValidator(demo_bool_false_or_passthrough),
         Field(
             description=(
                 "Indicates whether the document is 'image only,' meaning it consists "
@@ -995,6 +1004,7 @@ class PdfRestInfoResponse(BaseModel):
 
     contains_annotations: Annotated[
         bool | None,
+        BeforeValidator(demo_bool_false_or_passthrough),
         Field(
             description=(
                 "Indicates whether the PDF document contains annotations such as "
@@ -1007,6 +1017,7 @@ class PdfRestInfoResponse(BaseModel):
 
     contains_signature: Annotated[
         bool | None,
+        BeforeValidator(demo_bool_false_or_passthrough),
         Field(
             description="Indicates whether the PDF contains any digital signatures. "
             "The result is true or false."
@@ -1028,6 +1039,7 @@ class PdfRestInfoResponse(BaseModel):
 
     file_size: Annotated[
         int | None,
+        BeforeValidator(demo_int_or_passthrough),
         Field(
             description="The size of the PDF file in bytes. The result is an integer."
         ),
@@ -1042,6 +1054,7 @@ class PdfRestInfoResponse(BaseModel):
 
     restrict_permissions_set: Annotated[
         bool | None,
+        BeforeValidator(demo_bool_false_or_passthrough),
         Field(
             description=(
                 "Indicates whether the PDF file has restricted permissions, such as "
@@ -1054,6 +1067,7 @@ class PdfRestInfoResponse(BaseModel):
 
     contains_xfa: Annotated[
         bool | None,
+        BeforeValidator(demo_bool_false_or_passthrough),
         Field(
             description="Indicates whether the PDF contains XFA forms. The result is "
             "true or false."
@@ -1063,6 +1077,7 @@ class PdfRestInfoResponse(BaseModel):
 
     contains_acroforms: Annotated[
         bool | None,
+        BeforeValidator(demo_bool_false_or_passthrough),
         Field(
             description="Indicates whether the PDF contains Acroforms. The result is "
             "true or false."
@@ -1072,6 +1087,7 @@ class PdfRestInfoResponse(BaseModel):
 
     contains_javascript: Annotated[
         bool | None,
+        BeforeValidator(demo_bool_false_or_passthrough),
         Field(
             description="Indicates whether the PDF contains JavaScript. The result is "
             "true or false."
@@ -1081,6 +1097,7 @@ class PdfRestInfoResponse(BaseModel):
 
     contains_transparency: Annotated[
         bool | None,
+        BeforeValidator(demo_bool_false_or_passthrough),
         Field(
             description="Indicates whether the PDF contains transparent objects. The "
             "result is true or false."
@@ -1090,6 +1107,7 @@ class PdfRestInfoResponse(BaseModel):
 
     contains_embedded_file: Annotated[
         bool | None,
+        BeforeValidator(demo_bool_false_or_passthrough),
         Field(
             description="Indicates whether the PDF contains one or more embedded "
             "files. The result is true or false."
@@ -1099,6 +1117,7 @@ class PdfRestInfoResponse(BaseModel):
 
     uses_embedded_fonts: Annotated[
         bool | None,
+        BeforeValidator(demo_bool_false_or_passthrough),
         Field(
             description="Indicates whether the PDF contains fully embedded fonts. "
             "The result is true or false."
@@ -1108,6 +1127,7 @@ class PdfRestInfoResponse(BaseModel):
 
     uses_nonembedded_fonts: Annotated[
         bool | None,
+        BeforeValidator(demo_bool_false_or_passthrough),
         Field(
             description="Indicates whether the PDF contains non-embedded fonts. The "
             "result is true or false."
@@ -1117,6 +1137,7 @@ class PdfRestInfoResponse(BaseModel):
 
     pdfa: Annotated[
         bool | None,
+        BeforeValidator(demo_bool_false_or_passthrough),
         Field(
             description="Indicates whether the document conforms to the PDF/A "
             "standard. The result is true or false."
@@ -1126,6 +1147,7 @@ class PdfRestInfoResponse(BaseModel):
 
     pdfua_claim: Annotated[
         bool | None,
+        BeforeValidator(demo_bool_false_or_passthrough),
         Field(
             description="Indicates whether the document claims to conform to the "
             "PDF/UA standard. The result is true or false."
@@ -1135,6 +1157,7 @@ class PdfRestInfoResponse(BaseModel):
 
     pdfe_claim: Annotated[
         bool | None,
+        BeforeValidator(demo_bool_false_or_passthrough),
         Field(
             description="Indicates whether the document claims to conform to the "
             "PDF/E standard. The result is true or false."
@@ -1144,6 +1167,7 @@ class PdfRestInfoResponse(BaseModel):
 
     pdfx_claim: Annotated[
         bool | None,
+        BeforeValidator(demo_bool_false_or_passthrough),
         Field(
             description="Indicates whether the document claims to conform to the "
             "PDF/X standard. The result is true or false."
@@ -1153,6 +1177,7 @@ class PdfRestInfoResponse(BaseModel):
 
     requires_password_to_open: Annotated[
         bool | None,
+        BeforeValidator(demo_bool_false_or_passthrough),
         Field(
             description=(
                 "Indicates whether the PDF requires a password to open. The result "
@@ -1165,6 +1190,7 @@ class PdfRestInfoResponse(BaseModel):
 
     all_queries_processed: Annotated[
         bool,
+        BeforeValidator(demo_bool_true_or_passthrough),
         Field(
             validation_alias=AliasChoices(
                 "all_queries_processed", "allQueriesProcessed"