PyPDFForm 6.0.2__tar.gz → 6.1.1__tar.gz

{pypdfform-6.0.2 → pypdfform-6.1.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: PyPDFForm
-Version: 6.0.2
+Version: 6.1.1
 Summary: The Python library & CLI for PDF forms.
 Author: Jinge Li
 License-Expression: MIT
@@ -28,7 +28,7 @@ Requires-Dist: cryptography<51.0.0,>=50.0.0
 Requires-Dist: fonttools<5.0.0,>=4.63.0
 Requires-Dist: pikepdf<11.0.0,>=10.7.2
 Requires-Dist: pillow<14.0.0,>=12.2.0
-Requires-Dist: pypdf<7.0.0,>=6.12.2
+Requires-Dist: pypdf<7.0.0,>=6.19.0
 Requires-Dist: reportlab<6.0.0,>=4.5.1
 Provides-Extra: cli
 Requires-Dist: typer<1.0.0,>=0.26.1; extra == "cli"

{pypdfform-6.0.2 → pypdfform-6.1.1}/PyPDFForm/__init__.py

@@ -16,15 +16,14 @@ PyPDFForm aims to make PDF form automation straightforward whether it is used
 from Python code or from the command line.
 """
 
-__version__ = "6.0.2"
+__version__ = "6.1.1"
 
 from .lib.annotations import Annotations
 from .lib.assets.blank import BlankPage
 from .lib.middleware import Widgets
 from .lib.raw import RawElements
-from .lib.types import PdfArray
 from .lib.widgets import Fields
-from .lib.wrapper import PdfWrapper
+from .lib.wrapper import PdfArray, PdfWrapper
 
 __all__ = [
     "PdfWrapper",

{pypdfform-6.0.2 → pypdfform-6.1.1}/PyPDFForm/cli/common.py

@@ -312,6 +312,7 @@ def create_elements_from_file(
     options_param_hint: str,
     output: Path | None = None,
     element_type: str | None = None,
+    input_errors: tuple[type[Exception], ...] = (),
 ) -> None:
     """
     Creates PDF elements from a data file or command-line options.
@@ -321,7 +322,8 @@ def create_elements_from_file(
     from the additional command-line options stored in ``ctx.args``. The data
     file takes precedence when both input forms are supplied. Each definition
     is constructed after optional font registration and passed to `method_name`
-    on `PdfWrapper`.
+    on `PdfWrapper`. Errors of the `input_errors` types raised by that method
+    are reported against the input form that was used, without writing output.
 
     Args:
         pdf (Path): The path to the input PDF file.
@@ -342,6 +344,9 @@ def create_elements_from_file(
             omitted, the input PDF is overwritten. Defaults to None.
         element_type (str, optional): Element type selected for command-line
             input. Defaults to None.
+        input_errors (tuple[type[Exception], ...], optional): Exception types
+            raised by `method_name` for invalid element definitions. Defaults to
+            an empty tuple.
     """
     if data is not None:
         input_data = load_data_file(data, schema, file_param_hint)
@@ -370,4 +375,13 @@ def create_elements_from_file(
             handle_font_registration(obj, each, registered_font)
             ungrouped_input.append(element_map[k](**each))
 
-    getattr(obj, method_name)(ungrouped_input).write(output or pdf)
+    try:
+        result = getattr(obj, method_name)(ungrouped_input)
+    except input_errors as exc:
+        cli_bad_parameter(
+            str(exc),
+            param_hint=file_param_hint if data is not None else options_param_hint,
+            cause=exc,
+        )
+
+    result.write(output or pdf)

{pypdfform-6.0.2 → pypdfform-6.1.1}/PyPDFForm/cli/create.py

@@ -126,7 +126,11 @@ def extract(
     The command validates that the requested end page does not precede the
     start page, converts the 1-based CLI page numbers into the slice expected
     by `PdfWrapper.pages`, and writes the extracted pages to the required
-    output path.
+    output path. Each page is extracted separately, so links and other GoTo
+    actions to other pages are removed, and fields shared with other pages keep
+    only their widgets on each page. A `ValueError` from `PdfWrapper.pages`
+    for other references to another page's content is not converted, so the
+    command exits with an error before writing the output.
 
     Args:
         ctx (typer.Context): Typer context containing global `PdfWrapper`
@@ -332,7 +336,8 @@ def annotation(
     The command maps input groups such as `text`, `link`, and `highlight` to
     annotation classes, validates the input against the CLI annotation schema,
     creates the corresponding annotation objects, and calls
-    `PdfWrapper.annotate` before writing the modified PDF. A data file can
+    `PdfWrapper.annotate` before writing the modified PDF. A link to a page
+    outside the PDF is reported as a parameter error. A data file can
     define multiple annotations grouped by type. Without `--file`, `--type` and
     the annotation options define one annotation. The data file takes
     precedence when both input forms are supplied.
@@ -368,6 +373,7 @@ def annotation(
         options_param_hint="annotation options",
         output=output,
         element_type=element_type,
+        input_errors=(ValueError,),
     )
 
 

{pypdfform-6.0.2 → pypdfform-6.1.1}/PyPDFForm/cli/update.py

@@ -297,9 +297,10 @@ def field(
 
     The command validates the input against the field update schema, loads the
     PDF with the global CLI options stored in `ctx.obj`, resolves each field
-    name, registers any referenced fonts once per invocation, assigns the
-    requested widget properties, and writes the modified PDF to the requested
-    output path or back to the input file. A data file can update multiple
+    name, checks that each field type supports its requested properties,
+    registers any referenced fonts once per invocation, assigns the requested
+    widget properties, and writes the modified PDF to the requested output path
+    or back to the input file. A data file can update multiple
     fields. Without `--file`, `--field` and the property options update one
     field. The data file takes precedence when both input forms are supplied.
 
@@ -315,8 +316,9 @@ def field(
             Defaults to None.
 
     Raises:
-        typer.BadParameter: Raised when the input file is invalid or a requested
-            field does not exist.
+        typer.BadParameter: Raised when the input file is invalid, a requested
+            field does not exist, or a field type does not support a requested
+            property.
     """
     if data is not None:
         input_data = load_data_file(data, FIELD_SCHEMA, "--file")
@@ -337,12 +339,21 @@ def field(
         field_param_hint = "--field"
 
     obj = PdfWrapper(str(pdf), **ctx.obj)
-    registered_font = {}
+    field_widgets = {}
     for k, each in input_data.items():
         field_widget = get_widget(obj, k, field_param_hint)
+        for param in each:
+            try:
+                field_widget.check_property_supported(param)
+            except AttributeError as exc:
+                cli_bad_parameter(str(exc), param_hint=field_param_hint, cause=exc)
+        field_widgets[k] = field_widget
+
+    registered_font = {}
+    for k, each in input_data.items():
         handle_font_registration(obj, each, registered_font)
         for param, v in each.items():
-            setattr(field_widget, param, v)
+            setattr(field_widgets[k], param, v)
 
     obj.write(output or pdf)
 

{pypdfform-6.0.2 → pypdfform-6.1.1}/PyPDFForm/lib/adapter.py

@@ -10,6 +10,7 @@ forms. The module ensures that the input is properly converted into a byte
 stream before further processing.
 """
 
+from os import PathLike
 from os.path import isfile
 from typing import Any, BinaryIO
 
@@ -32,7 +33,7 @@ def readable(obj: Any) -> bool:
 
 
 def fp_or_f_obj_or_stream_to_stream(
-    fp_or_f_obj_or_stream: bytes | str | BinaryIO,
+    fp_or_f_obj_or_stream: bytes | str | PathLike | BinaryIO,
 ) -> bytes:
     """
     Adapt a file path, file object, or stream to a byte stream.
@@ -40,30 +41,37 @@ def fp_or_f_obj_or_stream_to_stream(
     This function takes a file path, a file object, or a byte stream and adapts it to a consistent byte stream.
     It handles different input types, including:
         - byte streams (bytes)
-        - file paths (str)
+        - file paths (str or PathLike)
         - file-like objects with a read() method (BinaryIO)
-    Unsupported inputs and string paths that do not point to files are treated
-    as empty input and return ``b""``.
+    Paths are opened directly, so a missing path raises ``FileNotFoundError``.
+    Empty bytes and empty readable objects are returned as ``b""``.
 
     Args:
-        fp_or_f_obj_or_stream (bytes | str | BinaryIO): The input to adapt.
-            It can be a byte stream, a file path (string), or a file object.
+        fp_or_f_obj_or_stream (bytes | str | PathLike | BinaryIO): The input to adapt.
+            It can be a byte stream, a file path, or a file object.
 
     Returns:
         bytes: The byte stream representation of the input.
-               Returns an empty byte string if the file path does not exist.
+
+    Raises:
+        OSError: If a file path cannot be opened, such as ``FileNotFoundError``
+            for a missing path.
+        TypeError: If the input is not bytes, a file path, or a readable object.
     """
     # not cached to handle writing to the same disk file
-    result = b""
     if isinstance(fp_or_f_obj_or_stream, bytes):
         result = fp_or_f_obj_or_stream
 
     elif readable(fp_or_f_obj_or_stream):
         result = fp_or_f_obj_or_stream.read()
 
-    elif isinstance(fp_or_f_obj_or_stream, str) and isfile(fp_or_f_obj_or_stream):
+    elif isinstance(fp_or_f_obj_or_stream, (str, PathLike)):
         with open(fp_or_f_obj_or_stream, "rb") as _file:
             result = _file.read()
+
+    else:
+        msg = f"Expected bytes, a file path, or a readable binary stream, got {type(fp_or_f_obj_or_stream).__name__}."
+        raise TypeError(msg)
     return result
 
 

pypdfform-6.1.1/PyPDFForm/lib/annotations/link.py

@@ -0,0 +1,98 @@
+# -*- coding: utf-8 -*-
+"""
+This module defines the class for link annotations in PyPDFForm.
+
+It provides a structure for representing and interacting with PDF link
+annotations, which allow users to click and navigate to a URI or an internal page.
+
+Classes:
+    - `LinkAnnotation`: A dataclass representing the properties of a PDF link annotation.
+"""
+
+from dataclasses import dataclass
+from typing import Optional, Sequence
+
+from pypdf.generic import (
+    ArrayObject,
+    DictionaryObject,
+    IndirectObject,
+    NameObject,
+    TextStringObject,
+)
+
+from ..constants import A, Link, S
+from .base import Annotation
+
+
+@dataclass
+class LinkAnnotation(Annotation):
+    """
+    A dataclass representing the properties of a PDF link annotation.
+
+    This class extends the `Annotation` base class to specifically handle
+    link annotations, including the target URI or an internal page.
+
+    Attributes:
+        uri (str): The URI that the link annotation points to. Takes precedence
+            over `page` when both are set. Defaults to None.
+        page (int): The 1-based page number in the same PDF that the link
+            annotation points to. Defaults to None.
+    """
+
+    _annotation_type: str = Link
+
+    uri: Optional[str] = None
+    page: Optional[int] = None
+
+    def get_specific_properties(self) -> dict:
+        """
+        Gets properties specific to the link annotation.
+
+        This method extends the base properties with a URI action. A link to
+        an internal page needs the pages of the target PDF, so its destination
+        is built separately by `get_destination`.
+
+        Returns:
+            dict: A dictionary of PDF properties specific to the link annotation.
+        """
+        result = super().get_specific_properties()
+        if self.uri is not None:
+            result[NameObject(A)] = DictionaryObject(
+                {
+                    NameObject(S): NameObject("/URI"),
+                    NameObject("/URI"): TextStringObject(self.uri),
+                }
+            )
+
+        return result
+
+    def get_destination(
+        self, page_references: Sequence[IndirectObject]
+    ) -> Optional[ArrayObject]:
+        """
+        Gets the destination of a link to an internal page.
+
+        A destination in the same PDF must refer to the target page object
+        rather than a page index, which is reserved for destinations in other
+        PDFs. The 1-based `page` is resolved against the page references of the
+        PDF that will contain the link.
+
+        Args:
+            page_references (Sequence[IndirectObject]): References to the pages
+                of the PDF that will contain the link, in page order.
+
+        Returns:
+            Optional[ArrayObject]: The destination that fits the target page in
+                the window, or None if the link has a URI or no page.
+
+        Raises:
+            ValueError: If `page` is outside the pages of the PDF.
+        """
+        if self.uri is not None or self.page is None:
+            return None
+
+        if not 1 <= self.page <= len(page_references):
+            msg = f"Link page {self.page} must satisfy 1 <= page <= {len(page_references)}."
+            raise ValueError(msg)
+
+        return ArrayObject([page_references[self.page - 1], NameObject("/Fit")])