PyPDFForm 4.5.2__tar.gz → 4.6.0__tar.gz

{pypdfform-4.5.2 → pypdfform-4.6.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: PyPDFForm
-Version: 4.5.2
+Version: 4.6.0
 Summary: The Python library for PDF forms.
 Author: Jinge Li
 License-Expression: MIT

{pypdfform-4.5.2 → pypdfform-4.6.0}/PyPDFForm/__init__.py

@@ -20,7 +20,7 @@ The library supports various PDF form features, including:
 PyPDFForm aims to simplify PDF form manipulation, making it accessible to developers of all skill levels.
 """
 
-__version__ = "4.5.2"
+__version__ = "4.6.0"
 
 from .annotations import Annotations
 from .assets.blank import BlankPage

{pypdfform-4.5.2 → pypdfform-4.6.0}/PyPDFForm/annotations/__init__.py

@@ -2,7 +2,7 @@
 """
 The `annotations` package provides classes representing various types of PDF annotations.
 
-It defines `AnnotationTypes` as a Union of all supported annotation types, allowing for
+It defines `AnnotationTypes` as a collection of all supported annotation types, allowing for
 flexible type hinting when working with different annotation configurations.
 
 Classes within this package encapsulate the properties and behaviors of individual
@@ -11,9 +11,19 @@ annotations, facilitating their creation and manipulation within PDF documents.
 
 from dataclasses import dataclass
 
+from .link import LinkAnnotation
 from .text import TextAnnotation
+from .text_markup import (HighlightAnnotation, SquigglyAnnotation,
+                          StrikeOutAnnotation, UnderlineAnnotation)
 
-AnnotationTypes = TextAnnotation
+AnnotationTypes = (
+    TextAnnotation
+    | LinkAnnotation
+    | HighlightAnnotation
+    | UnderlineAnnotation
+    | SquigglyAnnotation
+    | StrikeOutAnnotation
+)
 
 
 @dataclass
@@ -26,3 +36,8 @@ class Annotations:
     """
 
     TextAnnotation = TextAnnotation
+    LinkAnnotation = LinkAnnotation
+    HighlightAnnotation = HighlightAnnotation
+    UnderlineAnnotation = UnderlineAnnotation
+    SquigglyAnnotation = SquigglyAnnotation
+    StrikeOutAnnotation = StrikeOutAnnotation

{pypdfform-4.5.2 → pypdfform-4.6.0}/PyPDFForm/annotations/base.py

@@ -36,3 +36,17 @@ class Annotation:
     width: float = 20
     height: float = 20
     contents: str = ""
+
+    def get_specific_properties(self) -> dict:
+        """
+        Gets properties specific to the annotation type.
+
+        This method should be implemented by subclasses to return a dictionary
+        containing PDF properties and their values that are unique to that
+        specific type of annotation. These properties are used when creating
+        the annotation's entry in the PDF document.
+
+        Returns:
+            dict: A dictionary of PDF properties specific to the annotation type.
+        """
+        raise NotImplementedError

pypdfform-4.6.0/PyPDFForm/annotations/link.py

@@ -0,0 +1,57 @@
+# -*- coding: utf-8 -*-
+# TODO: finish other features
+"""
+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.
+
+Classes:
+    - `LinkAnnotation`: A dataclass representing the properties of a PDF link annotation.
+"""
+
+from dataclasses import dataclass
+from typing import Optional
+
+from pypdf.generic import DictionaryObject, NameObject, TextStringObject
+
+from ..constants import A, 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.
+
+    Attributes:
+        uri (str): The URI that the link annotation points to. Defaults to None.
+    """
+
+    _annotation_type: str = "/Link"
+
+    uri: Optional[str] = None
+
+    def get_specific_properties(self) -> dict:
+        """
+        Gets properties specific to the link annotation type.
+
+        This method returns a dictionary containing PDF properties and their
+        values that are unique to a link annotation, perforated with the URI action.
+
+        Returns:
+            dict: A dictionary of PDF properties specific to the link annotation.
+        """
+        result = {}
+        if self.uri is not None:
+            result[NameObject(A)] = DictionaryObject(
+                {
+                    NameObject(S): NameObject("/URI"),
+                    NameObject("/URI"): TextStringObject(self.uri),
+                }
+            )
+
+        return result

{pypdfform-4.5.2 → pypdfform-4.6.0}/PyPDFForm/annotations/text.py

@@ -27,8 +27,6 @@ class TextAnnotation(Annotation):
 
     Attributes:
         _annotation_type (str): The PDF internal type of the annotation, which is "/Text".
-        _additional_properties (tuple): A tuple defining how specific attributes are mapped
-            to PDF dictionary keys for the annotation.
         note_icon (str): The identifier for a "Note" icon.
         comment_icon (str): The identifier for a "Comment" icon.
         help_icon (str): The identifier for a "Help" icon.
@@ -39,10 +37,6 @@ class TextAnnotation(Annotation):
     """
 
     _annotation_type: str = "/Text"
-    _additional_properties: tuple = (
-        (NameObject(T), (TextStringObject, "title")),
-        (NameObject("/Name"), (NameObject, "icon")),
-    )
 
     note_icon: str = "/Note"
     comment_icon: str = "/Comment"
@@ -52,3 +46,21 @@ class TextAnnotation(Annotation):
 
     title: Optional[str] = None
     icon: Optional[str] = None
+
+    def get_specific_properties(self) -> dict:
+        """
+        Gets properties specific to the text annotation.
+
+        This method includes the title (author) and the icon name for the
+        text annotation if they are provided.
+
+        Returns:
+            dict: A dictionary of PDF properties specific to the text annotation.
+        """
+        result = {}
+        if self.title is not None:
+            result[NameObject(T)] = TextStringObject(self.title)
+        if self.icon is not None:
+            result[NameObject("/Name")] = NameObject(self.icon)
+
+        return result

pypdfform-4.6.0/PyPDFForm/annotations/text_markup.py

@@ -0,0 +1,82 @@
+# -*- coding: utf-8 -*-
+"""
+This module defines the `TextMarkupAnnotation` class and its subclasses,
+which are used to represent text markup annotations in a PDF document.
+
+Classes:
+    - `TextMarkupAnnotation`: Base class for all text markup annotations.
+    - `HighlightAnnotation`: Represents a highlight annotation.
+    - `UnderlineAnnotation`: Represents an underline annotation.
+    - `SquigglyAnnotation`: Represents a squiggly (curly) underline annotation.
+    - `StrikeOutAnnotation`: Represents a strikeout annotation.
+"""
+
+from dataclasses import dataclass
+
+from pypdf.generic import ArrayObject, FloatObject, NameObject
+
+from .base import Annotation
+
+
+@dataclass
+class TextMarkupAnnotation(Annotation):
+    """
+    Base dataclass for all text markup annotations.
+
+    Text markup annotations appear as marks on the text of a document,
+    such as highlights, underlines, etc. They are defined by a set of
+    quadrilateral points (QuadPoints) that encompass the text being marked.
+    """
+
+    def get_specific_properties(self) -> dict:
+        """
+        Gets properties specific to the text markup annotation.
+
+        This method calculates the `QuadPoints` for the markup based on the
+        annotation's position and dimensions.
+
+        Returns:
+            dict: A dictionary containing the `/QuadPoints` property.
+        """
+        return {
+            NameObject("/QuadPoints"): ArrayObject(
+                [
+                    FloatObject(self.x),
+                    FloatObject(self.y),
+                    FloatObject(self.x + self.width),
+                    FloatObject(self.y),
+                    FloatObject(self.x),
+                    FloatObject(self.y + self.height),
+                    FloatObject(self.x + self.width),
+                    FloatObject(self.y + self.height),
+                ]
+            )
+        }
+
+
+@dataclass
+class HighlightAnnotation(TextMarkupAnnotation):
+    """Represents a highlight annotation."""
+
+    _annotation_type: str = "/Highlight"
+
+
+@dataclass
+class UnderlineAnnotation(TextMarkupAnnotation):
+    """Represents an underline annotation."""
+
+    _annotation_type: str = "/Underline"
+
+
+@dataclass
+class SquigglyAnnotation(TextMarkupAnnotation):
+    """Represents a squiggly (curly) underline annotation."""
+
+    _annotation_type: str = "/Squiggly"
+
+
+@dataclass
+class StrikeOutAnnotation(TextMarkupAnnotation):
+    """Represents a strikeout annotation."""
+
+    _annotation_type: str = "/StrikeOut"

{pypdfform-4.5.2 → pypdfform-4.6.0}/PyPDFForm/raw/__init__.py

@@ -3,7 +3,7 @@
 The `raw` package provides classes representing raw drawable elements
 (like text and images) that can be rendered directly onto a PDF document.
 
-It defines `RawTypes` as a Union of all supported raw element types, used for
+It defines `RawTypes` as a collection of all supported raw element types, used for
 type hinting in methods that handle drawing onto the PDF.
 """
 

{pypdfform-4.5.2 → pypdfform-4.6.0}/PyPDFForm/template.py

@@ -358,10 +358,7 @@ def _create_annotation_object(annotation: AnnotationTypes) -> DictionaryObject:
             NameObject(Contents): TextStringObject(annotation.contents),
         }
     )
-    for k, v in getattr(annotation, "_additional_properties", ()):
-        val = getattr(annotation, v[1])
-        if val is not None:
-            annot[k] = v[0](val)
+    annot.update(**annotation.get_specific_properties())
     return annot
 
 

{pypdfform-4.5.2 → pypdfform-4.6.0}/PyPDFForm/widgets/__init__.py

@@ -2,7 +2,7 @@
 """
 The `widgets` package provides a collection of classes representing various types of PDF form fields (widgets).
 
-It defines `FieldTypes` as a Union of all supported field types, allowing for flexible
+It defines `FieldTypes` as a collection of all supported field types, allowing for flexible
 type hinting when working with different widget configurations.
 
 Classes within this package encapsulate the properties and behaviors of individual

{pypdfform-4.5.2 → pypdfform-4.6.0}/PyPDFForm.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: PyPDFForm
-Version: 4.5.2
+Version: 4.6.0
 Summary: The Python library for PDF forms.
 Author: Jinge Li
 License-Expression: MIT

{pypdfform-4.5.2 → pypdfform-4.6.0}/PyPDFForm.egg-info/SOURCES.txt

@@ -24,7 +24,9 @@ PyPDFForm.egg-info/requires.txt
 PyPDFForm.egg-info/top_level.txt
 PyPDFForm/annotations/__init__.py
 PyPDFForm/annotations/base.py
+PyPDFForm/annotations/link.py
 PyPDFForm/annotations/text.py
+PyPDFForm/annotations/text_markup.py
 PyPDFForm/assets/__init__.py
 PyPDFForm/assets/bedrock.py
 PyPDFForm/assets/blank.py

{pypdfform-4.5.2 → pypdfform-4.6.0}/pyproject.toml

@@ -105,6 +105,7 @@ select = [
     "TCH",
     "YTT",
     "W",
+    "UP007",
 ]
 ignore = ["B009", "E501", "N999", "Q000", "TC006", "N816"]
 

{pypdfform-4.5.2 → pypdfform-4.6.0}/tests/test_functional.py

@@ -7,6 +7,7 @@ import pytest
 from jsonschema import ValidationError, validate
 
 from PyPDFForm import Annotations, BlankPage, Fields, PdfArray, PdfWrapper
+from PyPDFForm.annotations.base import Annotation
 from PyPDFForm.constants import DA, UNIQUE_SUFFIX_LENGTH, T, V
 from PyPDFForm.deprecation import deprecation_notice
 from PyPDFForm.middleware.base import Widget
@@ -788,6 +789,17 @@ def test_merge(template_stream):
                 assert field[V] == f"test_3_{int(page / 3 - 0.5)}"
 
 
+def test_base_annotation_get_specific_properties_not_implemented():
+    annotation = Annotation(1, 100, 100)
+    try:
+        annotation.get_specific_properties()
+        pytest.fail(
+            reason="base annotation shouldn't have get_specific_properties implemented."
+        )
+    except NotImplementedError:
+        pass
+
+
 def test_annotate(template_stream, pdf_samples, request):
     expected_path = os.path.join(pdf_samples, "test_annotate.pdf")
     with open(expected_path, "rb+") as f:

{pypdfform-4.5.2 → pypdfform-4.6.0}/tests/test_generate_appearance_streams.py

@@ -5,7 +5,8 @@ import os
 
 import pytest
 
-from PyPDFForm import Fields, PdfWrapper
+from PyPDFForm import PdfWrapper
+from tests.test_need_appearances import run_sample_template_library_test
 
 
 def test_fill(template_stream, pdf_samples, data_dict, request):
@@ -106,96 +107,10 @@ def test_issue_613(pdf_samples, request):
 def test_sample_template_library(
     pdf_samples, image_samples, sample_font_stream, request
 ):
-    expected_path = os.path.join(
-        pdf_samples, "generate_appearance_streams", "test_sample_template_library.pdf"
+    run_sample_template_library_test(
+        pdf_samples,
+        image_samples,
+        sample_font_stream,
+        request,
+        generate_appearance_streams=True,
     )
-
-    with open(expected_path, "rb+") as f:
-        obj = (
-            PdfWrapper(
-                os.path.join(pdf_samples, "dummy.pdf"), generate_appearance_streams=True
-            )
-            .register_font("new_font", sample_font_stream)
-            .create_field(
-                Fields.TextField(
-                    name="new_text_field_widget",
-                    page_number=1,
-                    x=60,
-                    y=710,
-                )
-            )
-            .create_field(
-                Fields.CheckBoxField(
-                    name="new_checkbox_widget",
-                    page_number=1,
-                    x=100,
-                    y=600,
-                )
-            )
-            .create_field(
-                Fields.RadioGroup(
-                    name="new_radio_group",
-                    page_number=1,
-                    x=[50, 100, 150],
-                    y=[50, 100, 150],
-                )
-            )
-            .create_field(
-                Fields.DropdownField(
-                    name="new_dropdown_widget",
-                    page_number=1,
-                    x=300,
-                    y=710,
-                    options=[
-                        "foo",
-                        "bar",
-                        "foobar",
-                    ],
-                    font="new_font",
-                )
-            )
-            .create_field(
-                Fields.ImageField(
-                    name="new_image_widget",
-                    page_number=1,
-                    x=300,
-                    y=200,
-                )
-            )
-            .create_field(
-                Fields.SignatureField(
-                    name="new_signature_wiget",
-                    page_number=1,
-                    x=300,
-                    y=400,
-                )
-            )
-            .fill(
-                {
-                    "new_text_field_widget": "test text",
-                    "new_checkbox_widget": True,
-                    "new_radio_group": 1,
-                    "new_dropdown_widget": "barfoo",
-                    "new_image_widget": os.path.join(image_samples, "sample_image.jpg"),
-                    "new_signature_wiget": os.path.join(
-                        image_samples, "sample_signature.png"
-                    ),
-                },
-            )
-        )
-
-        obj.widgets["new_text_field_widget"].font = "new_font"
-        obj.widgets["new_text_field_widget"].font_color = (1, 0, 0)
-        obj.widgets["new_text_field_widget"].alignment = (
-            2  # TODO: why is alignment not rendered right in the appearance stream?
-        )
-        obj.widgets["new_checkbox_widget"].size = 40
-        obj.widgets["new_radio_group"].size = 50
-
-        request.config.results["expected_path"] = expected_path
-        request.config.results["stream"] = obj.read()
-
-        expected = f.read()
-
-        assert len(obj.read()) == len(expected)
-        request.config.results["skip_regenerate"] = len(obj.read()) == len(expected)

{pypdfform-4.5.2 → pypdfform-4.6.0}/tests/test_need_appearances.py

@@ -7,6 +7,119 @@ import pytest
 from PyPDFForm import Fields, PdfWrapper
 
 
+def run_sample_template_library_test(
+    pdf_samples,
+    image_samples,
+    sample_font_stream,
+    request,
+    generate_appearance_streams=False,
+    need_appearances=False,
+):
+    subdir = (
+        "generate_appearance_streams"
+        if generate_appearance_streams
+        else "need_appearances"
+    )
+    expected_path = os.path.join(
+        pdf_samples, subdir, "test_sample_template_library.pdf"
+    )
+
+    with open(expected_path, "rb+") as f:
+        obj = (
+            PdfWrapper(
+                os.path.join(pdf_samples, "dummy.pdf"),
+                generate_appearance_streams=generate_appearance_streams,
+                need_appearances=need_appearances,
+            )
+            .register_font("new_font", sample_font_stream)
+            .create_field(
+                Fields.TextField(
+                    name="new_text_field_widget",
+                    page_number=1,
+                    x=60,
+                    y=710,
+                )
+            )
+            .create_field(
+                Fields.CheckBoxField(
+                    name="new_checkbox_widget",
+                    page_number=1,
+                    x=100,
+                    y=600,
+                )
+            )
+            .create_field(
+                Fields.RadioGroup(
+                    name="new_radio_group",
+                    page_number=1,
+                    x=[50, 100, 150],
+                    y=[50, 100, 150],
+                )
+            )
+            .create_field(
+                Fields.DropdownField(
+                    name="new_dropdown_widget",
+                    page_number=1,
+                    x=300,
+                    y=710,
+                    options=[
+                        "foo",
+                        "bar",
+                        "foobar",
+                    ],
+                    font="new_font",
+                )
+            )
+            .create_field(
+                Fields.ImageField(
+                    name="new_image_widget",
+                    page_number=1,
+                    x=300,
+                    y=200,
+                )
+            )
+            .create_field(
+                Fields.SignatureField(
+                    name="new_signature_wiget",
+                    page_number=1,
+                    x=300,
+                    y=400,
+                )
+            )
+            .fill(
+                {
+                    "new_text_field_widget": "test text",
+                    "new_checkbox_widget": True,
+                    "new_radio_group": 1,
+                    "new_dropdown_widget": "barfoo",
+                    "new_image_widget": os.path.join(image_samples, "sample_image.jpg"),
+                    "new_signature_wiget": os.path.join(
+                        image_samples, "sample_signature.png"
+                    ),
+                },
+            )
+        )
+
+        obj.widgets["new_text_field_widget"].font = "new_font"
+        obj.widgets["new_text_field_widget"].font_color = (1, 0, 0)
+        # TODO: why is alignment not rendered right in the appearance stream?
+        obj.widgets["new_text_field_widget"].alignment = 2
+
+        obj.widgets["new_checkbox_widget"].size = 40
+        obj.widgets["new_radio_group"].size = 50
+
+        request.config.results["expected_path"] = expected_path
+        request.config.results["stream"] = obj.read()
+
+        expected = f.read()
+
+        assert len(obj.read()) == len(expected)
+        if generate_appearance_streams:
+            request.config.results["skip_regenerate"] = len(obj.read()) == len(expected)
+        else:
+            assert obj.read() == expected
+
+
 def test_fill(template_stream, pdf_samples, data_dict, request):
     expected_path = os.path.join(pdf_samples, "need_appearances", "sample_filled.pdf")
     with open(expected_path, "rb+") as f:
@@ -98,92 +211,10 @@ def test_issue_613(pdf_samples, request):
 def test_sample_template_library(
     pdf_samples, image_samples, sample_font_stream, request
 ):
-    expected_path = os.path.join(
-        pdf_samples, "need_appearances", "test_sample_template_library.pdf"
+    run_sample_template_library_test(
+        pdf_samples,
+        image_samples,
+        sample_font_stream,
+        request,
+        need_appearances=True,
     )
-
-    with open(expected_path, "rb+") as f:
-        obj = (
-            PdfWrapper(os.path.join(pdf_samples, "dummy.pdf"), need_appearances=True)
-            .register_font("new_font", sample_font_stream)
-            .create_field(
-                Fields.TextField(
-                    name="new_text_field_widget",
-                    page_number=1,
-                    x=60,
-                    y=710,
-                )
-            )
-            .create_field(
-                Fields.CheckBoxField(
-                    name="new_checkbox_widget",
-                    page_number=1,
-                    x=100,
-                    y=600,
-                )
-            )
-            .create_field(
-                Fields.RadioGroup(
-                    name="new_radio_group",
-                    page_number=1,
-                    x=[50, 100, 150],
-                    y=[50, 100, 150],
-                )
-            )
-            .create_field(
-                Fields.DropdownField(
-                    name="new_dropdown_widget",
-                    page_number=1,
-                    x=300,
-                    y=710,
-                    options=[
-                        "foo",
-                        "bar",
-                        "foobar",
-                    ],
-                    font="new_font",
-                )
-            )
-            .create_field(
-                Fields.ImageField(
-                    name="new_image_widget",
-                    page_number=1,
-                    x=300,
-                    y=200,
-                )
-            )
-            .create_field(
-                Fields.SignatureField(
-                    name="new_signature_wiget",
-                    page_number=1,
-                    x=300,
-                    y=400,
-                )
-            )
-            .fill(
-                {
-                    "new_text_field_widget": "test text",
-                    "new_checkbox_widget": True,
-                    "new_radio_group": 1,
-                    "new_dropdown_widget": "barfoo",
-                    "new_image_widget": os.path.join(image_samples, "sample_image.jpg"),
-                    "new_signature_wiget": os.path.join(
-                        image_samples, "sample_signature.png"
-                    ),
-                },
-            )
-        )
-
-        obj.widgets["new_text_field_widget"].font = "new_font"
-        obj.widgets["new_text_field_widget"].font_color = (1, 0, 0)
-        obj.widgets["new_text_field_widget"].alignment = 2
-        obj.widgets["new_checkbox_widget"].size = 40
-        obj.widgets["new_radio_group"].size = 50
-
-        request.config.results["expected_path"] = expected_path
-        request.config.results["stream"] = obj.read()
-
-        expected = f.read()
-
-        assert len(obj.read()) == len(expected)
-        assert obj.read() == expected