PyPDFForm 2.4.0__py3-none-any.whl → 3.0.0__py3-none-any.whl

PyPDFForm/middleware/signature.py

@@ -1,86 +1,71 @@
 # -*- coding: utf-8 -*-
-"""Provides middleware for PDF signature field widgets.
+"""
+Module representing a signature widget.
 
-This module contains the Signature class which handles:
-- Signature image processing
-- Aspect ratio preservation
-- File path resolution
-- PDF form field integration
+This module defines the Signature class, which is a subclass of the
+Widget class. It represents a signature form field in a PDF document,
+allowing users to add their signature as an image.
 """
 
 from os.path import expanduser
-from typing import BinaryIO, Union
+from typing import Union
 
 from ..adapter import fp_or_f_obj_or_stream_to_stream
 from .base import Widget
 
 
 class Signature(Widget):
-    """Middleware for PDF signature field widgets.
-
-    Handles all aspects of signature field processing including:
-    - Signature image handling
-    - Aspect ratio control
-    - File path resolution
-    - PDF form field integration
+    """
+    Represents a signature widget.
 
-    Inherits from Widget base class and extends it with signature-specific features.
+    The Signature class provides a concrete implementation for
+    signature form fields. It inherits from the Widget class and
+    implements the schema_definition, sample_value, and stream
+    properties.
     """
 
     preserve_aspect_ratio = True
-    """Whether to preserve the original image's aspect ratio when scaling."""
-
-    def __init__(
-        self,
-        name: str,
-        value: Union[bytes, str, BinaryIO] = None,
-    ) -> None:
-        """Initializes a new signature field widget.
-
-        Args:
-            name: Field name/key for the signature
-            value: Signature image as bytes, file path, or file object (default: None)
-        """
-
-        super().__init__(name, value)
 
     @property
     def schema_definition(self) -> dict:
-        """Generates a JSON schema definition for the signature field.
+        """
+        Returns the schema definition for the signature.
+
+        The schema definition is a dictionary that describes the
+        data type and other constraints for the signature value,
+        which is expected to be a string representing the path to
+        the signature image.
 
         Returns:
-            dict: Schema properties including:
-                - type: string (file path)
-                - description (if available from base class)
+            dict: A dictionary representing the schema definition.
         """
-
-        return {"type": "string"}
+        return {"type": "string", **super().schema_definition}
 
     @property
     def sample_value(self) -> str:
-        """Generates a sample value for the signature field.
+        """
+        Returns a sample value for the signature.
 
-        Returns a default sample image path from the user's Downloads folder.
+        The sample value is used to generate example data for the
+        signature field. It returns the path to a sample image file.
 
         Returns:
-            str: Path to sample image file
+            str: A sample value for the signature.
         """
-
         return expanduser("~/Downloads/sample_image.jpg")
 
     @property
     def stream(self) -> Union[bytes, None]:
-        """Converts the signature image to a byte stream.
+        """
+        Returns the stream of the signature image.
 
-        Handles conversion of:
-        - Raw image bytes
-        - File paths
-        - File-like objects
+        This method reads the signature image from the file path
+        specified in the value attribute and returns the image data
+        as a stream of bytes.
 
         Returns:
-            Union[bytes, None]: Image data as bytes, or None if no value set
+            Union[bytes, None]: The stream of the signature image.
         """
-
         return (
             fp_or_f_obj_or_stream_to_stream(self.value)
             if self.value is not None

PyPDFForm/middleware/text.py

@@ -1,67 +1,78 @@
 # -*- coding: utf-8 -*-
-"""Provides middleware for PDF text field widgets.
-
-This module contains the Text class which handles:
-- Text field value management
-- Font properties (family, size, color)
-- Text wrapping and formatting
-- Comb field (fixed character spacing) support
-- Preview mode for form field visualization
 """
+Module representing a text field widget.
 
-from typing import Any
+This module defines the Text class, which is a subclass of the
+Widget class. It represents a text field form field in a PDF document,
+allowing users to enter text.
+"""
 
 from .base import Widget
 
 
 class Text(Widget):
-    """Middleware for PDF text field widgets.
-
-    Handles all aspects of text field processing including:
-    - Value conversion and validation
-    - Font styling and formatting
-    - Multiline text wrapping
-    - Comb field character spacing
-    - Preview mode rendering
-
-    Inherits from Widget base class and extends it with text-specific features.
     """
+    Represents a text field widget.
+
+    The Text class provides a concrete implementation for text field
+    form fields. It inherits from the Widget class and implements
+    the value, schema_definition, and sample_value properties. It
+    also defines a number of attributes that can be used to customize
+    the appearance and behavior of the text field, such as font,
+    font_size, font_color, comb, alignment, and multiline.
+    """
+
+    SET_ATTR_TRIGGER_HOOK_MAP = {
+        "font": "update_text_field_font",
+        "font_size": "update_text_field_font_size",
+        "font_color": "update_text_field_font_color",
+        "comb": "update_text_field_comb",
+        "alignment": "update_text_field_alignment",
+        "multiline": "update_text_field_multiline",
+    }
 
     def __init__(
         self,
         name: str,
         value: str = None,
     ) -> None:
-        """Initializes a new text field widget.
+        """
+        Initializes a text field widget.
 
         Args:
-            name: Field name/key for the text field
-            value: Initial text value (default: None)
+            name (str): The name of the text field.
+            value (str): The initial value of the text field. Defaults to None.
+
+        Attributes:
+            font (str): The font of the text field. Defaults to None.
+            font_size (int): The font size of the text field. Defaults to None.
+            font_color (str): The font color of the text field. Defaults to None.
+            comb (bool): Whether the text field is a comb field. Defaults to None.
+            alignment (str): The alignment of the text field. Defaults to None.
+            multiline (bool): Whether the text field is multiline. Defaults to None.
+            max_length (int): The maximum length of the text field. Defaults to None.
         """
-
         super().__init__(name, value)
 
         self.font = None
         self.font_size = None
         self.font_color = None
-        self.text_wrap_length = None
-        self.max_length = None
         self.comb = None
-        self.character_paddings = []
-        self.text_lines = None
-        self.text_line_x_coordinates = None
-        self.preview = False
+        self.alignment = None
+        self.multiline = None
+
+        self.max_length = None
 
     @property
-    def value(self) -> Any:
-        """Gets the text field's current value with type conversion.
+    def value(self) -> str:
+        """
+        Returns the value of the text field.
 
-        Converts numeric values to strings automatically.
+        If the value is an integer or float, it is converted to a string.
 
         Returns:
-            Any: The text value as a string (converted if numeric)
+            str: The value of the text field.
         """
-
         if isinstance(self._value, (int, float)):
             return str(self._value)
 
@@ -69,27 +80,25 @@ class Text(Widget):
 
     @value.setter
     def value(self, value: str) -> None:
-        """Sets the text field's value.
+        """
+        Sets the value of the text field.
 
         Args:
-            value: New text value (will be converted to string if numeric)
+            value (str): The value to set.
         """
-
         self._value = value
 
     @property
     def schema_definition(self) -> dict:
-        """Generates a JSON schema definition for the text field.
+        """
+        Returns the schema definition for the text field.
 
-        Includes:
-        - Type constraint (string)
-        - Max length if specified
-        - Any inherited schema properties
+        The schema definition is a dictionary that describes the
+        data type and other constraints for the text field value.
 
         Returns:
-            dict: Complete JSON schema definition
+            dict: A dictionary representing the schema definition.
         """
-
         result = {"type": "string"}
 
         if self.max_length is not None:
@@ -99,14 +108,16 @@ class Text(Widget):
 
     @property
     def sample_value(self) -> str:
-        """Generates a sample value demonstrating the text field's capacity.
+        """
+        Returns a sample value for the text field.
 
-        Uses the field name as the sample value, truncated to max_length if specified.
+        The sample value is used to generate example data for the
+        text field. It returns the name of the field, truncated to
+        the maximum length if specified.
 
         Returns:
-            str: Sample text value for demonstration purposes
+            str: A sample value for the text field.
         """
-
         return (
             self.name[: self.max_length] if self.max_length is not None else self.name
         )

PyPDFForm/patterns.py

@@ -1,27 +1,19 @@
 # -*- coding: utf-8 -*-
-"""Pattern matching utilities for PDF form widgets.
-
-This module provides:
-- Pattern definitions for identifying widget types and properties
-- Functions for updating widget states and appearances
-- Support for common PDF form operations like flattening fields
-
-Patterns are used throughout PyPDFForm to:
-- Classify widget types (text, checkbox, radio, etc.)
-- Extract widget properties (alignment, colors, flags)
-- Modify widget states (values, appearances, flags)
+"""
+This module defines patterns and utility functions for interacting with PDF form fields.
 
-The module also contains utility functions for common PDF form operations
-like updating field values and flattening form fields.
+It includes patterns for identifying different types of widgets (e.g., text fields,
+checkboxes, radio buttons, dropdowns, images, and signatures) based on their
+properties in the PDF's annotation dictionary. It also provides utility functions
+for updating and flattening these widgets.
 """
 
 from pypdf.generic import (ArrayObject, DictionaryObject, NameObject,
                            NumberObject, TextStringObject)
 
-from .constants import (AP, AS, BC, BG, BS, CA, DA, DV, FT,
-                        IMAGE_FIELD_IDENTIFIER, JS, MK, MULTILINE, READ_ONLY,
-                        TU, A, Btn, Ch, D, Ff, I, N, Off, Opt, Parent, Q, S,
-                        Sig, T, Tx, V, W, Yes)
+from .constants import (AP, AS, DV, FT, IMAGE_FIELD_IDENTIFIER, JS, READ_ONLY,
+                        TU, A, Btn, Ch, Ff, I, N, Off, Opt, Parent, Sig, T, Tx,
+                        V, Yes)
 from .middleware.checkbox import Checkbox
 from .middleware.dropdown import Dropdown
 from .middleware.image import Image
@@ -103,52 +95,18 @@ DROPDOWN_CHOICE_PATTERNS = [
     {Parent: {Opt: True}},
 ]
 
-WIDGET_ALIGNMENT_PATTERNS = [
-    {Q: True},
-    {Parent: {Q: True}},
-]
-
-TEXT_FIELD_FLAG_PATTERNS = [
-    {Ff: True},
-    {Parent: {Ff: True}},
-]
-
-TEXT_FIELD_APPEARANCE_PATTERNS = [
-    {DA: True},
-    {Parent: {DA: True}},
-]
-
-BUTTON_STYLE_PATTERNS = [
-    {MK: {CA: True}},
-]
-
-BORDER_COLOR_PATTERNS = [
-    {MK: {BC: True}},
-]
-
-BACKGROUND_COLOR_PATTERNS = [
-    {MK: {BG: True}},
-]
-
-BORDER_WIDTH_PATTERNS = [{BS: {W: True}}]
-
-BORDER_STYLE_PATTERNS = [{BS: {S: True}}]
-
-BORDER_DASH_ARRAY_PATTERNS = [{BS: {D: True}}]
-
 
-def simple_update_checkbox_value(annot: DictionaryObject, check: bool = False) -> None:
-    """Update checkbox annotation values based on check state.
+def update_checkbox_value(annot: DictionaryObject, check: bool = False) -> None:
+    """
+    Updates the value of a checkbox annotation, setting it to checked or unchecked.
 
-    Modifies the appearance state (AS) and value (V) of a checkbox annotation
-    to reflect the desired checked/unchecked state. Uses the annotation's
-    appearance dictionary (AP/N) to determine valid states.
+    This function modifies the appearance state (AS) and value (V) of the checkbox
+    annotation to reflect the desired state (checked or unchecked).
 
     Args:
-        annot: PDF annotation dictionary to modify
-        check: Whether the checkbox should be checked (True) or unchecked (False)
+        annot (DictionaryObject): The checkbox annotation dictionary.
+        check (bool): True to check the checkbox, False to uncheck it. Defaults to False.
     """
-
     for each in annot[AP][N]:
         if (check and str(each) != Off) or (not check and str(each) == Off):
             annot[NameObject(AS)] = NameObject(each)
@@ -156,18 +114,16 @@ def simple_update_checkbox_value(annot: DictionaryObject, check: bool = False) -
             break
 
 
-def simple_update_radio_value(annot: DictionaryObject) -> None:
-    """Update radio button annotation values to selected state.
+def update_radio_value(annot: DictionaryObject) -> None:
+    """
+    Updates the value of a radio button annotation, selecting it.
 
-    Modifies the appearance state (AS) of a radio button annotation and updates
-    the parent's value (V) to reflect the selected state. Removes 'Opt' entry
-    from parent dictionary if present. Uses the annotation's appearance
-    dictionary (AP/N) to determine valid states.
+    This function modifies the appearance state (AS) and value (V) of the radio button's
+    parent dictionary to reflect the selected state.
 
     Args:
-        annot: PDF radio button annotation dictionary to modify
+        annot (DictionaryObject): The radio button annotation dictionary.
     """
-
     if Opt in annot[Parent]:
         del annot[Parent][Opt]
 
@@ -178,41 +134,41 @@ def simple_update_radio_value(annot: DictionaryObject) -> None:
             break
 
 
-def simple_update_dropdown_value(annot: DictionaryObject, widget: Dropdown) -> None:
-    """Update dropdown annotation values based on widget selection.
+def update_dropdown_value(annot: DictionaryObject, widget: Dropdown) -> None:
+    """
+    Updates the value of a dropdown annotation, selecting an option from the list.
 
-    Modifies the value (V), appearance (AP), and index (I) of a dropdown
-    annotation to reflect the currently selected choice from the widget.
-    Handles both standalone dropdowns and those with parent annotations.
+    This function modifies the value (V) and appearance (AP) of the dropdown
+    annotation to reflect the selected option. It also updates the index (I)
+    of the selected option.
 
     Args:
-        annot: PDF dropdown annotation dictionary to modify
-        widget: Dropdown widget containing the selected value
+        annot (DictionaryObject): The dropdown annotation dictionary.
+        widget (Dropdown): The Dropdown widget object containing the selected value.
     """
-
+    choices = widget.choices or []
     if Parent in annot and T not in annot:
         annot[NameObject(Parent)][NameObject(V)] = TextStringObject(
-            widget.choices[widget.value]
+            choices[widget.value]
         )
-        annot[NameObject(AP)] = TextStringObject(widget.choices[widget.value])
+        annot[NameObject(AP)] = TextStringObject(choices[widget.value])
     else:
-        annot[NameObject(V)] = TextStringObject(widget.choices[widget.value])
-        annot[NameObject(AP)] = TextStringObject(widget.choices[widget.value])
+        annot[NameObject(V)] = TextStringObject(choices[widget.value])
+        annot[NameObject(AP)] = TextStringObject(choices[widget.value])
         annot[NameObject(I)] = ArrayObject([NumberObject(widget.value)])
 
 
-def simple_update_text_value(annot: DictionaryObject, widget: Text) -> None:
-    """Update text field annotation values based on widget content.
+def update_text_value(annot: DictionaryObject, widget: Text) -> None:
+    """
+    Updates the value of a text annotation, setting the text content.
 
-    Modifies the value (V) and appearance (AP) of a text field annotation to
-    reflect the current value from the text widget. Handles both standalone
-    text fields and those with parent annotations.
+    This function modifies the value (V) and appearance (AP) of the text
+    annotation to reflect the new text content.
 
     Args:
-        annot: PDF text field annotation dictionary to modify
-        widget: Text widget containing the value to set
+        annot (DictionaryObject): The text annotation dictionary.
+        widget (Text): The Text widget object containing the text value.
     """
-
     if Parent in annot and T not in annot:
         annot[NameObject(Parent)][NameObject(V)] = TextStringObject(widget.value)
         annot[NameObject(AP)] = TextStringObject(widget.value)
@@ -221,33 +177,32 @@ def simple_update_text_value(annot: DictionaryObject, widget: Text) -> None:
         annot[NameObject(AP)] = TextStringObject(widget.value)
 
 
-def simple_flatten_radio(annot: DictionaryObject) -> None:
-    """Flatten radio button annotation by making it read-only.
+def flatten_radio(annot: DictionaryObject) -> None:
+    """
+    Flattens a radio button annotation by setting the ReadOnly flag, making it non-editable.
 
-    Modifies the field flags (Ff) of a radio button's parent annotation
-    to set the read-only flag, effectively flattening the field and
-    preventing further user interaction.
+    This function modifies the Ff (flags) entry in the radio button's parent
+    dictionary to set the ReadOnly flag, preventing the user from changing the
+    selected option.
 
     Args:
-        annot: PDF radio button annotation dictionary to flatten
+        annot (DictionaryObject): The radio button annotation dictionary.
     """
-
     annot[NameObject(Parent)][NameObject(Ff)] = NumberObject(
         int(annot[NameObject(Parent)].get(NameObject(Ff), 0)) | READ_ONLY
     )
 
 
-def simple_flatten_generic(annot: DictionaryObject) -> None:
-    """Flatten generic annotation by making it read-only.
+def flatten_generic(annot: DictionaryObject) -> None:
+    """
+    Flattens a generic annotation by setting the ReadOnly flag, making it non-editable.
 
-    Modifies the field flags (Ff) of an annotation to set the read-only flag,
-    effectively flattening the field and preventing further user interaction.
-    Handles both standalone annotations and those with parent annotations.
+    This function modifies the Ff (flags) entry in the annotation dictionary to
+    set the ReadOnly flag, preventing the user from interacting with the form field.
 
     Args:
-        annot: PDF annotation dictionary to flatten
+        annot (DictionaryObject): The annotation dictionary.
     """
-
     if Parent in annot and Ff not in annot:
         annot[NameObject(Parent)][NameObject(Ff)] = NumberObject(
             int(annot.get(NameObject(Ff), 0)) | READ_ONLY
@@ -259,52 +214,17 @@ def simple_flatten_generic(annot: DictionaryObject) -> None:
 
 
 def update_annotation_name(annot: DictionaryObject, val: str) -> None:
-    """Update the name/title of a PDF annotation.
+    """
+    Updates the name of an annotation, setting the T (title) entry.
 
-    Modifies the title (T) field of an annotation to set a new name.
-    Handles both standalone annotations and those with parent annotations.
+    This function modifies the T (title) entry in the annotation dictionary to
+    change the name or title of the annotation.
 
     Args:
-        annot: PDF annotation dictionary to modify
-        val: New name/title to set for the annotation
+        annot (DictionaryObject): The annotation dictionary.
+        val (str): The new name for the annotation.
     """
-
     if Parent in annot and T not in annot:
         annot[NameObject(Parent)][NameObject(T)] = TextStringObject(val)
     else:
         annot[NameObject(T)] = TextStringObject(val)
-
-
-def update_created_text_field_alignment(annot: DictionaryObject, val: int) -> None:
-    """Update text alignment for created text field annotations.
-
-    Modifies the alignment (Q) field of a text field annotation created
-    by the library to set the specified text alignment.
-
-    Args:
-        annot: PDF text field annotation dictionary to modify
-        val: Alignment value to set (typically 0=left, 1=center, 2=right)
-    """
-
-    annot[NameObject(Q)] = NumberObject(val)
-
-
-def update_created_text_field_multiline(annot: DictionaryObject, val: bool) -> None:
-    """Update multiline flag for created text field annotations.
-
-    Modifies the field flags (Ff) of a text field annotation created by
-    the library to set or clear the multiline flag based on the input value.
-
-    Args:
-        annot: PDF text field annotation dictionary to modify
-        val: Whether to enable multiline (True) or disable (False)
-    """
-
-    if val:
-        annot[NameObject(Ff)] = NumberObject(int(annot[NameObject(Ff)]) | MULTILINE)
-
-
-NON_ACRO_FORM_PARAM_TO_FUNC = {
-    ("TextWidget", "alignment"): update_created_text_field_alignment,
-    ("TextWidget", "multiline"): update_created_text_field_multiline,
-}