PyPDFForm 2.0.1__py3-none-any.whl → 2.2.0__py3-none-any.whl

PyPDFForm/font.py

@@ -1,5 +1,13 @@
 # -*- coding: utf-8 -*-
-"""Contains helpers for font."""
+"""Provides font handling utilities for PDF forms.
+
+This module contains functions for:
+- Registering custom fonts from TTF files
+- Extracting font information from PDF text appearances
+- Calculating font sizes based on widget dimensions
+- Adjusting font sizes to fit text within fields
+- Managing font colors and properties
+"""
 
 from io import BytesIO
 from math import sqrt
@@ -20,7 +28,15 @@ from .utils import extract_widget_property
 
 
 def register_font(font_name: str, ttf_stream: bytes) -> bool:
-    """Registers a font from a ttf file stream."""
+    """Registers a TrueType font for use in PDF generation.
+
+    Args:
+        font_name: Name to register the font under
+        ttf_stream: TTF font data as bytes
+
+    Returns:
+        bool: True if registration succeeded, False if failed
+    """
 
     buff = BytesIO()
     buff.write(ttf_stream)
@@ -37,9 +53,15 @@ def register_font(font_name: str, ttf_stream: bytes) -> bool:
 
 
 def extract_font_from_text_appearance(text_appearance: str) -> Union[str, None]:
-    """
-    Uses regex to pattern match out the font from the text
-    appearance string of a text field widget.
+    """Extracts font name from PDF text appearance string.
+
+    Parses the font information embedded in PDF text field appearance strings.
+
+    Args:
+        text_appearance: PDF text appearance string (/DA field)
+
+    Returns:
+        Union[str, None]: Font name if found, None if not found
     """
 
     text_appearances = text_appearance.split(" ")
@@ -70,7 +92,16 @@ def extract_font_from_text_appearance(text_appearance: str) -> Union[str, None]:
 
 
 def auto_detect_font(widget: dict) -> str:
-    """Returns the font of the text field if it is one of the standard fonts."""
+    """Attempts to detect the font used in a PDF text field widget.
+
+    Falls back to DEFAULT_FONT if detection fails.
+
+    Args:
+        widget: PDF form widget dictionary
+
+    Returns:
+        str: Detected font name or DEFAULT_FONT
+    """
 
     text_appearance = extract_widget_property(
         widget, TEXT_FIELD_APPEARANCE_PATTERNS, None, None
@@ -83,9 +114,13 @@ def auto_detect_font(widget: dict) -> str:
 
 
 def text_field_font_size(widget: dict) -> Union[float, int]:
-    """
-    Calculates the font size it should be drawn with
-    given a text field widget.
+    """Calculates an appropriate font size based on text field dimensions.
+
+    Args:
+        widget: PDF form widget dictionary containing Rect coordinates
+
+    Returns:
+        Union[float, int]: Suggested font size in points
     """
 
     height = abs(float(widget[Rect][1]) - float(widget[Rect][3]))
@@ -94,9 +129,13 @@ def text_field_font_size(widget: dict) -> Union[float, int]:
 
 
 def checkbox_radio_font_size(widget: dict) -> Union[float, int]:
-    """
-    Calculates the font size it should be drawn with
-    given a checkbox/radio button widget.
+    """Calculates appropriate symbol size for checkbox/radio widgets.
+
+    Args:
+        widget: PDF form widget dictionary containing Rect coordinates
+
+    Returns:
+        Union[float, int]: Suggested symbol size in points
     """
 
     area = abs(float(widget[Rect][0]) - float(widget[Rect][2])) * abs(
@@ -107,7 +146,14 @@ def checkbox_radio_font_size(widget: dict) -> Union[float, int]:
 
 
 def get_text_field_font_size(widget: dict) -> Union[float, int]:
-    """Returns the font size of the text field if presented or zero."""
+    """Extracts font size from PDF text field appearance properties.
+
+    Args:
+        widget: PDF form widget dictionary
+
+    Returns:
+        Union[float, int]: Font size in points if found, otherwise 0
+    """
 
     result = 0
     text_appearance = extract_widget_property(
@@ -125,7 +171,15 @@ def get_text_field_font_size(widget: dict) -> Union[float, int]:
 def get_text_field_font_color(
     widget: dict,
 ) -> Union[Tuple[float, float, float], None]:
-    """Returns the font color tuple of the text field if presented or black."""
+    """Extracts font color from PDF text field appearance properties.
+
+    Args:
+        widget: PDF form widget dictionary
+
+    Returns:
+        Union[Tuple[float, float, float], None]: RGB color tuple (0-1 range)
+            or black by default if not specified
+    """
 
     result = (0, 0, 0)
     text_appearance = extract_widget_property(
@@ -149,7 +203,12 @@ def get_text_field_font_color(
 
 
 def adjust_paragraph_font_size(widget: dict, widget_middleware: Text) -> None:
-    """Reduces the font size of a paragraph field until texts fits."""
+    """Dynamically reduces font size until text fits in paragraph field.
+
+    Args:
+        widget: PDF form widget dictionary
+        widget_middleware: Text middleware instance containing text properties
+    """
 
     # pylint: disable=C0415, R0401
     from .template import get_paragraph_lines
@@ -167,7 +226,12 @@ def adjust_paragraph_font_size(widget: dict, widget_middleware: Text) -> None:
 
 
 def adjust_text_field_font_size(widget: dict, widget_middleware: Text) -> None:
-    """Reduces the font size of a text field until texts fits."""
+    """Dynamically reduces font size until text fits in text field.
+
+    Args:
+        widget: PDF form widget dictionary
+        widget_middleware: Text middleware instance containing text properties
+    """
 
     width = abs(float(widget[Rect][0]) - float(widget[Rect][2]))
 

PyPDFForm/image.py

@@ -1,5 +1,13 @@
 # -*- coding: utf-8 -*-
-"""Contains helpers for image."""
+"""Provides image processing utilities for PDF forms.
+
+This module contains functions for:
+- Rotating images while maintaining quality
+- Extracting image dimensions
+- Handling image streams and formats
+
+Supports common image formats including JPEG, PNG, and others supported by PIL.
+"""
 
 from io import BytesIO
 from typing import Tuple, Union
@@ -8,7 +16,18 @@ from PIL import Image
 
 
 def rotate_image(image_stream: bytes, rotation: Union[float, int]) -> bytes:
-    """Rotates an image by a rotation angle."""
+    """Rotates an image while maintaining original quality and format.
+
+    Args:
+        image_stream: Input image as bytes
+        rotation: Rotation angle in degrees (can be a float for precise angles)
+
+    Returns:
+        bytes: Rotated image as bytes in the original format
+
+    Note:
+        Automatically expands the canvas to prevent cropping during rotation.
+    """
 
     buff = BytesIO()
     buff.write(image_stream)
@@ -29,7 +48,17 @@ def rotate_image(image_stream: bytes, rotation: Union[float, int]) -> bytes:
 
 
 def get_image_dimensions(image_stream: bytes) -> Tuple[float, float]:
-    """Gets the width and height of an image."""
+    """Extracts width and height from an image stream.
+
+    Args:
+        image_stream: Input image as bytes
+
+    Returns:
+        Tuple[float, float]: (width, height) in pixels
+
+    Note:
+        Works with any image format supported by PIL (Pillow)
+    """
 
     buff = BytesIO()
     buff.write(image_stream)

PyPDFForm/middleware/base.py

@@ -1,18 +1,42 @@
 # -*- coding: utf-8 -*-
-"""Contains widget middleware."""
+"""Provides base widget middleware for PDF form elements.
+
+This module contains the Widget base class that defines common functionality
+and properties for all PDF form widgets, including:
+- Name and value management
+- Styling properties (borders, colors)
+- Schema generation
+- Basic validation
+"""
 
 from typing import Any
 
 
 class Widget:
-    """Base class for all PDF form widgets."""
+    """Abstract base class for all PDF form widget middleware.
+
+    Provides common interface and functionality for:
+    - Managing widget names and values
+    - Handling visual properties (borders, colors)
+    - Generating JSON schema definitions
+    - Providing sample values
+
+    Subclasses must implement:
+    - sample_value property
+    - Any widget-specific functionality
+    """
 
     def __init__(
         self,
         name: str,
         value: Any = None,
     ) -> None:
-        """Constructs basic attributes for the object."""
+        """Initializes a new widget with basic properties.
+
+        Args:
+            name: Field name/key for the widget
+            value: Initial value for the widget (default: None)
+        """
 
         super().__init__()
         self._name = name
@@ -28,25 +52,44 @@ class Widget:
 
     @property
     def name(self) -> str:
-        """Name of the widget."""
+        """Gets the widget's field name/key.
+
+        Returns:
+            str: The widget's name as it appears in the PDF form
+        """
 
         return self._name
 
     @property
     def value(self) -> Any:
-        """Value to fill for the widget."""
+        """Gets the widget's current value.
+
+        Returns:
+            Any: The widget's current value (type depends on widget type)
+        """
 
         return self._value
 
     @value.setter
     def value(self, value: Any) -> None:
-        """Sets value to fill for the widget."""
+        """Sets the widget's value.
+
+        Args:
+            value: New value for the widget (type depends on widget type)
+        """
 
         self._value = value
 
     @property
     def schema_definition(self) -> dict:
-        """Json schema definition of the widget."""
+        """Generates a JSON schema definition for the widget.
+
+        Returns:
+            dict: Schema properties including:
+                - description (if available)
+                - type constraints
+                - other widget-specific properties
+        """
 
         result = {}
 
@@ -57,6 +100,12 @@ class Widget:
 
     @property
     def sample_value(self) -> Any:
-        """Sample value of the widget."""
+        """Generates a sample value appropriate for the widget type.
+
+        Returns:
+            Any: A representative value demonstrating the widget's expected input
 
+        Raises:
+            NotImplementedError: Must be implemented by subclasses
+        """
         raise NotImplementedError

PyPDFForm/middleware/checkbox.py

@@ -1,5 +1,12 @@
 # -*- coding: utf-8 -*-
-"""Contains checkbox middleware."""
+"""Provides middleware for PDF checkbox widgets.
+
+This module contains the Checkbox class which handles:
+- Checkbox state management (checked/unchecked)
+- Button style customization
+- Value validation and conversion
+- Schema generation for form validation
+"""
 
 from typing import Union
 
@@ -7,7 +14,16 @@ from .base import Widget
 
 
 class Checkbox(Widget):
-    """A class to represent a checkbox widget."""
+    """Middleware for PDF checkbox widgets.
+
+    Handles all aspects of checkbox processing including:
+    - State management (checked/unchecked)
+    - Button style customization (check, cross, circle)
+    - Value validation
+    - PDF form field integration
+
+    Inherits from Widget base class and extends it with checkbox-specific features.
+    """
 
     BUTTON_STYLE_MAPPING = {
         "check": "4",
@@ -20,7 +36,12 @@ class Checkbox(Widget):
         name: str,
         value: bool = None,
     ) -> None:
-        """Constructs all attributes for the checkbox."""
+        """Initializes a new checkbox widget.
+
+        Args:
+            name: Field name/key for the checkbox
+            value: Initial checked state (default: None)
+        """
 
         super().__init__(name, value)
 
@@ -29,25 +50,46 @@ class Checkbox(Widget):
 
     @property
     def schema_definition(self) -> dict:
-        """Json schema definition of the checkbox."""
+        """Generates a JSON schema definition for the checkbox.
+
+        Returns:
+            dict: Schema properties including:
+                - type: boolean
+                - description (if available from base class)
+        """
 
         return {"type": "boolean", **super().schema_definition}
 
     @property
     def sample_value(self) -> Union[bool, int]:
-        """Sample value of the checkbox."""
+        """Generates a sample value for the checkbox.
+
+        Returns:
+            Union[bool, int]: Always returns True as the sample checked state
+        """
 
         return True
 
     @property
     def button_style(self) -> Union[str, None]:
-        """Shape of the tick for the checkbox."""
+        """Gets the current button style identifier.
+
+        Returns:
+            Union[str, None]: The button style code used in PDF form fields
+        """
 
         return self._button_style
 
     @button_style.setter
     def button_style(self, value) -> None:
-        """Converts user specified button styles to acroform values."""
+        """Sets the button style for the checkbox.
+
+        Accepts either style names ('check', 'cross', 'circle') or
+        direct PDF button style codes ('4', '5', 'l').
+
+        Args:
+            value: Button style name or code to set
+        """
 
         if value in self.BUTTON_STYLE_MAPPING:
             self._button_style = self.BUTTON_STYLE_MAPPING[value]

PyPDFForm/middleware/dropdown.py

@@ -1,18 +1,39 @@
 # -*- coding: utf-8 -*-
-"""Contains dropdown middleware."""
+"""Provides middleware for PDF dropdown/combobox widgets.
+
+This module contains the Dropdown class which handles:
+- Dropdown option management
+- Selection index tracking
+- Value validation
+- Schema generation for form validation
+"""
 
 from .base import Widget
 
 
 class Dropdown(Widget):
-    """A class to represent a dropdown widget."""
+    """Middleware for PDF dropdown/combobox widgets.
+
+    Handles all aspects of dropdown processing including:
+    - Option list management
+    - Selection index validation
+    - Value conversion
+    - PDF form field integration
+
+    Inherits from Widget base class and extends it with dropdown-specific features.
+    """
 
     def __init__(
         self,
         name: str,
         value: int = None,
     ) -> None:
-        """Constructs all attributes for the dropdown."""
+        """Initializes a new dropdown widget.
+
+        Args:
+            name: Field name/key for the dropdown
+            value: Initial selected option index (default: None)
+        """
 
         super().__init__(name, value)
 
@@ -21,7 +42,16 @@ class Dropdown(Widget):
 
     @property
     def schema_definition(self) -> dict:
-        """Json schema definition of the dropdown."""
+        """Generates a JSON schema definition for the dropdown.
+
+        Includes:
+        - Type constraint (integer)
+        - Maximum valid option index
+        - Any inherited schema properties
+
+        Returns:
+            dict: Complete JSON schema definition
+        """
 
         return {
             "type": "integer",
@@ -31,6 +61,12 @@ class Dropdown(Widget):
 
     @property
     def sample_value(self) -> int:
-        """Sample value of the dropdown."""
+        """Generates a sample value for the dropdown.
+
+        Returns the index of the last option by default.
+
+        Returns:
+            int: Index of the last option in the dropdown
+        """
 
         return len(self.choices) - 1

PyPDFForm/middleware/image.py

@@ -1,10 +1,34 @@
 # -*- coding: utf-8 -*-
-"""Contains image field middleware."""
+"""Provides middleware for PDF image field widgets.
+
+This module contains the Image class which handles:
+- Image field processing for common formats (JPEG, PNG)
+- Aspect ratio preservation when scaling
+- PDF form field integration
+- Image rotation and positioning
+
+Supports image data from:
+- Raw bytes
+- File paths
+- File-like objects
+
+Note: Inherits core functionality from Signature middleware since
+PDF image fields are technically signature fields with images.
+"""
 
 from .signature import Signature
 
 
 class Image(Signature):
-    """A class to represent an image field widget."""
+    """Middleware for PDF image field widgets.
+
+    Handles all aspects of image field processing including:
+    - Image data handling
+    - Aspect ratio control
+    - PDF form field integration
+
+    Inherits from Signature class and extends it with image-specific features.
+    """
 
     preserve_aspect_ratio = False
+    """Whether to preserve the original image's aspect ratio when scaling."""

PyPDFForm/middleware/radio.py

@@ -1,18 +1,39 @@
 # -*- coding: utf-8 -*-
-"""Contains radio middleware."""
+"""Provides middleware for PDF radio button widgets.
+
+This module contains the Radio class which handles:
+- Radio button group state management
+- Option selection tracking
+- Value validation and conversion
+- Schema generation for form validation
+"""
 
 from .checkbox import Checkbox
 
 
 class Radio(Checkbox):
-    """A class to represent a radiobutton widget."""
+    """Middleware for PDF radio button widgets.
+
+    Handles all aspects of radio button processing including:
+    - Group selection management
+    - Option counting and validation
+    - Button style customization
+    - PDF form field integration
+
+    Inherits from Checkbox class and extends it with radio-specific features.
+    """
 
     def __init__(
         self,
         name: str,
         value: int = None,
     ) -> None:
-        """Constructs all attributes for the radiobutton."""
+        """Initializes a new radio button widget.
+
+        Args:
+            name: Field name/key for the radio button group
+            value: Initial selected option index (default: None)
+        """
 
         super().__init__(name, value)
 
@@ -22,7 +43,16 @@ class Radio(Checkbox):
 
     @property
     def schema_definition(self) -> dict:
-        """Json schema definition of the radiobutton."""
+        """Generates a JSON schema definition for the radio button group.
+
+        Includes:
+        - Type constraint (integer)
+        - Maximum valid option index
+        - Any inherited schema properties
+
+        Returns:
+            dict: Complete JSON schema definition
+        """
 
         return {
             "maximum": self.number_of_options - 1,
@@ -32,6 +62,12 @@ class Radio(Checkbox):
 
     @property
     def sample_value(self) -> int:
-        """Sample value of the radiobutton."""
+        """Generates a sample value for the radio button group.
+
+        Returns the index of the last option by default.
+
+        Returns:
+            int: Index of the last option in the group
+        """
 
         return self.number_of_options - 1