Add Add Text methods

Assisted-by: Codex

Author: datalogics-cgreen

src/pdfrest/client.py

@@ -83,6 +83,7 @@
     OcrPdfPayload,
     PdfAddAttachmentPayload,
     PdfAddImagePayload,
+    PdfAddTextPayload,
     PdfCompressPayload,
     PdfFlattenAnnotationsPayload,
     PdfFlattenFormsPayload,
@@ -117,6 +118,7 @@
     GraphicSmoothing,
     JpegColorModel,
     OcrLanguage,
+    PdfAddTextObject,
     PdfAType,
     PdfInfoQuery,
     PdfMergeInput,
@@ -2501,6 +2503,36 @@ def apply_redactions(
             timeout=timeout,
         )
 
+    def add_text_to_pdf(
+        self,
+        file: PdfRestFile | Sequence[PdfRestFile],
+        *,
+        text_objects: PdfAddTextObject | Sequence[PdfAddTextObject],
+        output: str | None = None,
+        extra_query: Query | None = None,
+        extra_headers: AnyMapping | None = None,
+        extra_body: Body | None = None,
+        timeout: TimeoutTypes | None = None,
+    ) -> PdfRestFileBasedResponse:
+        """Insert one or more text blocks into a PDF."""
+
+        payload: dict[str, Any] = {
+            "files": file,
+            "text_objects": text_objects,
+        }
+        if output is not None:
+            payload["output"] = output
+
+        return self._post_file_operation(
+            endpoint="/pdf-with-added-text",
+            payload=payload,
+            payload_model=PdfAddTextPayload,
+            extra_query=extra_query,
+            extra_headers=extra_headers,
+            extra_body=extra_body,
+            timeout=timeout,
+        )
+
     def add_image_to_pdf(
         self,
         file: PdfRestFile | Sequence[PdfRestFile],
@@ -3564,6 +3596,36 @@ async def apply_redactions(
             timeout=timeout,
         )
 
+    async def add_text_to_pdf(
+        self,
+        file: PdfRestFile | Sequence[PdfRestFile],
+        *,
+        text_objects: PdfAddTextObject | Sequence[PdfAddTextObject],
+        output: str | None = None,
+        extra_query: Query | None = None,
+        extra_headers: AnyMapping | None = None,
+        extra_body: Body | None = None,
+        timeout: TimeoutTypes | None = None,
+    ) -> PdfRestFileBasedResponse:
+        """Asynchronously insert text blocks into a PDF."""
+
+        payload: dict[str, Any] = {
+            "files": file,
+            "text_objects": text_objects,
+        }
+        if output is not None:
+            payload["output"] = output
+
+        return await self._post_file_operation(
+            endpoint="/pdf-with-added-text",
+            payload=payload,
+            payload_model=PdfAddTextPayload,
+            extra_query=extra_query,
+            extra_headers=extra_headers,
+            extra_body=extra_body,
+            timeout=timeout,
+        )
+
     async def add_image_to_pdf(
         self,
         file: PdfRestFile | Sequence[PdfRestFile],

src/pdfrest/models/_internal.py

@@ -148,6 +148,11 @@ def _serialize_redactions(value: list[_PdfRedactionVariant]) -> str:
     return json.dumps(payload, separators=(",", ":"))
 
 
+def _serialize_text_objects(value: list[BaseModel]) -> str:
+    payload = [entry.model_dump(mode="json", exclude_none=True) for entry in value]
+    return json.dumps(payload, separators=(",", ":"))
+
+
 def _allowed_mime_types(
     allowed_mime_types: str, *more_allowed_mime_types: str, error_msg: str | None
 ) -> Callable[[Any], Any]:
@@ -563,6 +568,64 @@ class ExtractImagesPayload(BaseModel):
 
 
 RgbChannel = Annotated[int, Field(ge=0, le=255)]
+CmykChannel = Annotated[int, Field(ge=0, le=100)]
+
+
+def _validate_rgb_values(value: list[Any] | tuple[Any, ...] | None) -> list[int] | None:
+    if value is None:
+        return None
+    if len(value) != 3:
+        msg = "text_color_rgb must have exactly 3 values."
+        raise ValueError(msg)
+    channels: list[int] = []
+    for channel in value:
+        try:
+            numeric = int(channel)
+        except (TypeError, ValueError) as exc:
+            msg = "text_color_rgb values must be integers."
+            raise ValueError(msg) from exc
+        if not 0 <= numeric <= 255:
+            msg = "text_color_rgb values must be between 0 and 255."
+            raise ValueError(msg)
+        channels.append(numeric)
+    return channels
+
+
+def _validate_cmyk_values(
+    value: list[Any] | tuple[Any, ...] | None,
+) -> list[int] | None:
+    if value is None:
+        return None
+    if len(value) != 4:
+        msg = "text_color_cmyk must have exactly 4 values."
+        raise ValueError(msg)
+    channels: list[int] = []
+    for channel in value:
+        try:
+            numeric = int(channel)
+        except (TypeError, ValueError) as exc:
+            msg = "text_color_cmyk values must be integers."
+            raise ValueError(msg) from exc
+        if not 0 <= numeric <= 100:
+            msg = "text_color_cmyk values must be between 0 and 100."
+            raise ValueError(msg)
+        channels.append(numeric)
+    return channels
+
+
+def _validate_add_text_page(value: str | int) -> str | int:
+    if isinstance(value, str):
+        if value.lower() == "all":
+            return "all"
+        if value.isdigit():
+            numeric_page = int(value)
+            if numeric_page >= 1:
+                return numeric_page
+    else:
+        if value >= 1:
+            return value
+    msg = 'page must be a positive integer or "all".'
+    raise ValueError(msg)
 
 
 class PdfLiteralRedactionModel(BaseModel):
@@ -1021,6 +1084,94 @@ def _validate_profile_dependency(self) -> PdfCompressPayload:
         return self
 
 
+class PdfAddTextObjectModel(BaseModel):
+    """Adapt caller text options for insertion into a PDF."""
+
+    font: Annotated[str, Field(min_length=1, serialization_alias="font")]
+    max_width: Annotated[
+        float,
+        Field(serialization_alias="max_width", gt=0),
+    ]
+    opacity: Annotated[
+        float,
+        Field(serialization_alias="opacity", ge=0.0, le=1.0),
+    ]
+    page: Annotated[
+        str | int,
+        Field(serialization_alias="page"),
+        AfterValidator(_validate_add_text_page),
+    ]
+    rotation: Annotated[float, Field(serialization_alias="rotation")]
+    text: Annotated[str, Field(min_length=1, serialization_alias="text")]
+    text_color_rgb: Annotated[
+        list[int] | tuple[int, ...] | None,
+        Field(serialization_alias="text_color_rgb", default=None),
+        BeforeValidator(_split_comma_string),
+        AfterValidator(_validate_rgb_values),
+        PlainSerializer(_serialize_as_comma_separated_string),
+    ] = None
+    text_color_cmyk: Annotated[
+        list[int] | tuple[int, ...] | None,
+        Field(serialization_alias="text_color_cmyk", default=None),
+        BeforeValidator(_split_comma_string),
+        AfterValidator(_validate_cmyk_values),
+        PlainSerializer(_serialize_as_comma_separated_string),
+    ] = None
+    text_size: Annotated[
+        float,
+        Field(serialization_alias="text_size", ge=5, le=100),
+    ]
+    x: Annotated[float, Field(serialization_alias="x")]
+    y: Annotated[float, Field(serialization_alias="y")]
+    is_rtl: Annotated[
+        bool | None,
+        Field(serialization_alias="is_rtl", default=None),
+    ] = None
+
+    @model_validator(mode="after")
+    def _ensure_single_color_option(self) -> PdfAddTextObjectModel:
+        if self.text_color_rgb is None and self.text_color_cmyk is None:
+            msg = "Either text_color_rgb or text_color_cmyk must be provided."
+            raise ValueError(msg)
+        if self.text_color_rgb is not None and self.text_color_cmyk is not None:
+            msg = "Provide only one of text_color_rgb or text_color_cmyk."
+            raise ValueError(msg)
+        return self
+
+
+class PdfAddTextPayload(BaseModel):
+    """Adapt caller options into a pdfRest-ready add-text request payload."""
+
+    files: Annotated[
+        list[PdfRestFile],
+        Field(
+            min_length=1,
+            max_length=1,
+            validation_alias=AliasChoices("file", "files"),
+            serialization_alias="id",
+        ),
+        BeforeValidator(_ensure_list),
+        AfterValidator(
+            _allowed_mime_types("application/pdf", error_msg="Must be a PDF file")
+        ),
+        PlainSerializer(_serialize_as_first_file_id),
+    ]
+    text_objects: Annotated[
+        list[PdfAddTextObjectModel],
+        Field(
+            serialization_alias="text_objects",
+            min_length=1,
+        ),
+        BeforeValidator(_ensure_list),
+        PlainSerializer(_serialize_text_objects),
+    ]
+    output: Annotated[
+        str | None,
+        Field(serialization_alias="output", min_length=1, default=None),
+        AfterValidator(_validate_output_prefix),
+    ] = None
+
+
 class PdfAddImagePayload(BaseModel):
     """Adapt caller options into a pdfRest-ready add-image request payload."""
 

src/pdfrest/types/__init__.py

@@ -11,7 +11,9 @@
     GraphicSmoothing,
     JpegColorModel,
     OcrLanguage,
+    PdfAddTextObject,
     PdfAType,
+    PdfCmykColor,
     PdfInfoQuery,
     PdfMergeInput,
     PdfMergeSource,
@@ -41,6 +43,8 @@
     "JpegColorModel",
     "OcrLanguage",
     "PdfAType",
+    "PdfAddTextObject",
+    "PdfCmykColor",
     "PdfInfoQuery",
     "PdfMergeInput",
     "PdfMergeSource",

src/pdfrest/types/public.py

@@ -24,6 +24,8 @@
     "JpegColorModel",
     "OcrLanguage",
     "PdfAType",
+    "PdfAddTextObject",
+    "PdfCmykColor",
     "PdfInfoQuery",
     "PdfMergeInput",
     "PdfMergeSource",
@@ -104,6 +106,24 @@ class PdfRedactionInstruction(TypedDict):
 
 PdfRGBColor = tuple[int, int, int]
 
+PdfCmykColor = tuple[int, int, int, int]
+
+
+class PdfAddTextObject(TypedDict, total=False):
+    font: Required[str]
+    max_width: Required[float | int | str]
+    opacity: Required[float | int | str]
+    page: Required[int | str]
+    rotation: Required[float | int | str]
+    text: Required[str]
+    text_color_rgb: PdfRGBColor
+    text_color_cmyk: PdfCmykColor
+    text_size: Required[float | int | str]
+    x: Required[float | int | str]
+    y: Required[float | int | str]
+    is_rtl: bool
+
+
 PdfPageSelection = str | int | Sequence[str | int]