PyPDFForm 2.0.0__py3-none-any.whl → 2.1.0__py3-none-any.whl

PyPDFForm/middleware/signature.py

@@ -1,5 +1,12 @@
 # -*- coding: utf-8 -*-
-"""Contains signature middleware."""
+"""Provides middleware for PDF signature field widgets.
+
+This module contains the Signature class which handles:
+- Signature image processing
+- Aspect ratio preservation
+- File path resolution
+- PDF form field integration
+"""
 
 from os.path import expanduser
 from typing import BinaryIO, Union
@@ -9,34 +16,70 @@ from .base import Widget
 
 
 class Signature(Widget):
-    """A class to represent a signature field 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
+
+    Inherits from Widget base class and extends it with signature-specific features.
+    """
 
     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:
-        """Constructs all attributes for the signature field."""
+        """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:
-        """Json schema definition of the signature field."""
+        """Generates a JSON schema definition for the signature field.
+
+        Returns:
+            dict: Schema properties including:
+                - type: string (file path)
+                - description (if available from base class)
+        """
 
         return {"type": "string"}
 
     @property
     def sample_value(self) -> str:
-        """Sample value of the signature field."""
+        """Generates a sample value for the signature field.
+
+        Returns a default sample image path from the user's Downloads folder.
+
+        Returns:
+            str: Path to sample image file
+        """
 
         return expanduser("~/Downloads/sample_image.jpg")
 
     @property
     def stream(self) -> Union[bytes, None]:
-        """Converts the value of the signature field image to a stream."""
+        """Converts the signature image to a byte stream.
+
+        Handles conversion of:
+        - Raw image bytes
+        - File paths
+        - File-like objects
+
+        Returns:
+            Union[bytes, None]: Image data as bytes, or None if no value set
+        """
 
         return (
             fp_or_f_obj_or_stream_to_stream(self.value)

PyPDFForm/middleware/text.py

@@ -1,5 +1,13 @@
 # -*- coding: utf-8 -*-
-"""Contains text middleware."""
+"""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
+"""
 
 from typing import Any
 
@@ -7,14 +15,29 @@ from .base import Widget
 
 
 class Text(Widget):
-    """A class to represent a text field 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.
+    """
 
     def __init__(
         self,
         name: str,
         value: str = None,
     ) -> None:
-        """Constructs all attributes for the text field."""
+        """Initializes a new text field widget.
+
+        Args:
+            name: Field name/key for the text field
+            value: Initial text value (default: None)
+        """
 
         super().__init__(name, value)
 
@@ -31,7 +54,13 @@ class Text(Widget):
 
     @property
     def value(self) -> Any:
-        """Value to fill for the text field."""
+        """Gets the text field's current value with type conversion.
+
+        Converts numeric values to strings automatically.
+
+        Returns:
+            Any: The text value as a string (converted if numeric)
+        """
 
         if isinstance(self._value, (int, float)):
             return str(self._value)
@@ -40,13 +69,26 @@ class Text(Widget):
 
     @value.setter
     def value(self, value: str) -> None:
-        """Sets value to fill for the text field."""
+        """Sets the text field's value.
+
+        Args:
+            value: New text value (will be converted to string if numeric)
+        """
 
         self._value = value
 
     @property
     def schema_definition(self) -> dict:
-        """Json schema definition of the text field."""
+        """Generates a JSON schema definition for the text field.
+
+        Includes:
+        - Type constraint (string)
+        - Max length if specified
+        - Any inherited schema properties
+
+        Returns:
+            dict: Complete JSON schema definition
+        """
 
         result = {"type": "string"}
 
@@ -57,7 +99,13 @@ class Text(Widget):
 
     @property
     def sample_value(self) -> str:
-        """Sample value of the text field."""
+        """Generates a sample value demonstrating the text field's capacity.
+
+        Uses the field name as the sample value, truncated to max_length if specified.
+
+        Returns:
+            str: Sample text value for demonstration purposes
+        """
 
         return (
             self.name[: self.max_length] if self.max_length is not None else self.name

PyPDFForm/patterns.py

@@ -1,5 +1,19 @@
 # -*- coding: utf-8 -*-
-"""Contains patterns used for identifying properties of widgets."""
+"""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)
+
+The module also contains utility functions for common PDF form operations
+like updating field values and flattening form fields.
+"""
 
 from pypdf.generic import (DictionaryObject, NameObject, NumberObject,
                            TextStringObject)
@@ -24,10 +38,23 @@ WIDGET_TYPE_PATTERNS = [
         ({FT: Sig},),
         Signature,
     ),
+    (
+        ({Parent: {FT: Sig}},),
+        Signature,
+    ),
     (
         ({FT: Tx},),
         Text,
     ),
+    (
+        # reportlab creation pattern
+        (
+            {FT: Btn},
+            {Parent: {FT: Btn}},
+            {AS: (Yes, Off)},
+        ),
+        Radio,
+    ),
     (
         (
             {FT: Btn},
@@ -111,7 +138,16 @@ BORDER_DASH_ARRAY_PATTERNS = [{BS: {D: True}}]
 
 
 def simple_update_checkbox_value(annot: DictionaryObject, check: bool = False) -> None:
-    """Patterns to update values for checkbox annotations."""
+    """Update checkbox annotation values based on check state.
+
+    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.
+
+    Args:
+        annot: PDF annotation dictionary to modify
+        check: Whether the checkbox should be checked (True) or unchecked (False)
+    """
 
     for each in annot[AP][N]:  # noqa
         if (check and str(each) != Off) or (not check and str(each) == Off):
@@ -121,7 +157,15 @@ def simple_update_checkbox_value(annot: DictionaryObject, check: bool = False) -
 
 
 def simple_update_radio_value(annot: DictionaryObject) -> None:
-    """Patterns to update values for radio annotations."""
+    """Update radio button annotation values to selected state.
+
+    Modifies the appearance state (AS) of a radio button annotation and updates
+    the parent's value (V) to reflect the selected state. Uses the annotation's
+    appearance dictionary (AP/N) to determine valid states.
+
+    Args:
+        annot: PDF radio button annotation dictionary to modify
+    """
 
     for each in annot[AP][N]:  # noqa
         if str(each) != Off:
@@ -131,7 +175,16 @@ def simple_update_radio_value(annot: DictionaryObject) -> None:
 
 
 def simple_update_dropdown_value(annot: DictionaryObject, widget: Dropdown) -> None:
-    """Patterns to update values for dropdown annotations."""
+    """Update dropdown annotation values based on widget selection.
+
+    Modifies the value (V) and appearance (AP) of a dropdown annotation to
+    reflect the currently selected choice from the widget. Handles both
+    standalone dropdowns and those with parent annotations.
+
+    Args:
+        annot: PDF dropdown annotation dictionary to modify
+        widget: Dropdown widget containing the selected value
+    """
 
     if Parent in annot and T not in annot:
         annot[NameObject(Parent)][NameObject(V)] = TextStringObject(  # noqa
@@ -144,7 +197,16 @@ def simple_update_dropdown_value(annot: DictionaryObject, widget: Dropdown) -> N
 
 
 def simple_update_text_value(annot: DictionaryObject, widget: Text) -> None:
-    """Patterns to update values for text annotations."""
+    """Update text field annotation values based on widget 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.
+
+    Args:
+        annot: PDF text field annotation dictionary to modify
+        widget: Text widget containing the value to set
+    """
 
     if Parent in annot and T not in annot:
         annot[NameObject(Parent)][NameObject(V)] = TextStringObject(  # noqa
@@ -157,7 +219,15 @@ def simple_update_text_value(annot: DictionaryObject, widget: Text) -> None:
 
 
 def simple_flatten_radio(annot: DictionaryObject) -> None:
-    """Patterns to flatten checkbox annotations."""
+    """Flatten radio button annotation by making it read-only.
+
+    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.
+
+    Args:
+        annot: PDF radio button annotation dictionary to flatten
+    """
 
     annot[NameObject(Parent)][NameObject(Ff)] = NumberObject(  # noqa
         int(annot[NameObject(Parent)].get(NameObject(Ff), 0)) | READ_ONLY  # noqa
@@ -165,7 +235,15 @@ def simple_flatten_radio(annot: DictionaryObject) -> None:
 
 
 def simple_flatten_generic(annot: DictionaryObject) -> None:
-    """Patterns to flatten generic annotations."""
+    """Flatten generic annotation by making it read-only.
+
+    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.
+
+    Args:
+        annot: PDF annotation dictionary to flatten
+    """
 
     if Parent in annot and Ff not in annot:
         annot[NameObject(Parent)][NameObject(Ff)] = NumberObject(  # noqa
@@ -178,7 +256,15 @@ def simple_flatten_generic(annot: DictionaryObject) -> None:
 
 
 def update_annotation_name(annot: DictionaryObject, val: str) -> None:
-    """Patterns to update the name of an annotation."""
+    """Update the name/title of a PDF annotation.
+
+    Modifies the title (T) field of an annotation to set a new name.
+    Handles both standalone annotations and those with parent annotations.
+
+    Args:
+        annot: PDF annotation dictionary to modify
+        val: New name/title to set for the annotation
+    """
 
     if Parent in annot and T not in annot:
         annot[NameObject(Parent)][NameObject(T)] = TextStringObject(val)  # noqa
@@ -187,13 +273,29 @@ def update_annotation_name(annot: DictionaryObject, val: str) -> None:
 
 
 def update_created_text_field_alignment(annot: DictionaryObject, val: int) -> None:
-    """Patterns to update text alignment for text annotations created by the library."""
+    """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:
-    """Patterns to update to multiline for text annotations created by the library."""
+    """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(