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

PyPDFForm/middleware/checkbox.py

@@ -1,11 +1,9 @@
 # -*- coding: utf-8 -*-
-"""Provides middleware for PDF checkbox widgets.
+"""
+Module representing a checkbox widget.
 
-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
+This module defines the Checkbox class, which is a subclass of the
+Widget class. It represents a checkbox form field in a PDF document.
 """
 
 from typing import Union
@@ -14,88 +12,59 @@ from .base import Widget
 
 
 class 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
+    """
+    Represents a checkbox widget.
 
-    Inherits from Widget base class and extends it with checkbox-specific features.
+    The Checkbox class provides a concrete implementation for
+    checkbox form fields. It inherits from the Widget class and
+    implements the schema_definition and sample_value properties.
     """
 
     SET_ATTR_TRIGGER_HOOK_MAP = {
         "size": "update_check_radio_size",
     }
 
-    BUTTON_STYLE_MAPPING = {
-        "check": "4",
-        "cross": "5",
-        "circle": "l",
-    }
-
     def __init__(
         self,
         name: str,
         value: bool = None,
     ) -> None:
-        """Initializes a new checkbox widget.
+        """
+        Initializes a checkbox widget.
 
         Args:
-            name: Field name/key for the checkbox
-            value: Initial checked state (default: None)
-        """
+            name (str): The name of the checkbox.
+            value (bool): The initial value of the checkbox. Defaults to None.
 
+        Attributes:
+            size (int): The size of the checkbox. Defaults to None.
+        """
         super().__init__(name, value)
 
         self.size = None
-        self._button_style = self.BUTTON_STYLE_MAPPING["check"]
 
     @property
     def schema_definition(self) -> dict:
-        """Generates a JSON schema definition for the checkbox.
+        """
+        Returns the schema definition for the checkbox.
+
+        The schema definition is a dictionary that describes the
+        data type and other constraints for the checkbox value.
 
         Returns:
-            dict: Schema properties including:
-                - type: boolean
-                - description (if available from base class)
+            dict: A dictionary representing the schema definition.
         """
-
         return {"type": "boolean", **super().schema_definition}
 
     @property
     def sample_value(self) -> Union[bool, int]:
-        """Generates a sample value for the checkbox.
-
-        Returns:
-            Union[bool, int]: Always returns True as the sample checked state
         """
+        Returns a sample value for the checkbox.
 
-        return True
-
-    @property
-    def button_style(self) -> Union[str, None]:
-        """Gets the current button style identifier.
+        The sample value is used to generate example data for the
+        checkbox field.
 
         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:
-        """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
+            Union[bool, int]: A sample value for the checkbox.
         """
-
-        if value in self.BUTTON_STYLE_MAPPING:
-            self._button_style = self.BUTTON_STYLE_MAPPING[value]
-        elif value in self.BUTTON_STYLE_MAPPING.values():
-            self._button_style = value
+        return True

PyPDFForm/middleware/dropdown.py

@@ -1,58 +1,68 @@
 # -*- coding: utf-8 -*-
-"""Provides middleware for PDF dropdown/combobox widgets.
+"""
+Module representing a dropdown widget.
 
-This module contains the Dropdown class which handles:
-- Dropdown option management
-- Selection index tracking
-- Value validation
-- Schema generation for form validation
+This module defines the Dropdown class, which is a subclass of the
+Widget class. It represents a dropdown form field in a PDF document.
 """
 
 from .base import Widget
 
 
 class Dropdown(Widget):
-    """Middleware for PDF dropdown/combobox widgets.
+    """
+    Represents a dropdown widget in a PDF form.
+
+    Inherits from the Widget class and provides specific functionality
+    for handling dropdown form fields.
 
-    Handles all aspects of dropdown processing including:
-    - Option list management
-    - Selection index validation
-    - Value conversion
-    - PDF form field integration
+    Key attributes:
+        font (str): The font of the dropdown field.
+        choices (List[str]): The list of available options in the dropdown.
+        value (int): The index of the selected choice in the choices list.
 
-    Inherits from Widget base class and extends it with dropdown-specific features.
+    Methods:
+        schema_definition: Returns a schema definition for the dropdown's value.
+        sample_value: Returns a sample value for the dropdown.
     """
 
+    SET_ATTR_TRIGGER_HOOK_MAP = {
+        "font": "update_text_field_font",
+        "choices": "update_dropdown_choices",
+    }
+
     def __init__(
         self,
         name: str,
         value: int = None,
     ) -> None:
-        """Initializes a new dropdown widget.
+        """
+        Initializes a dropdown widget.
 
         Args:
-            name: Field name/key for the dropdown
-            value: Initial selected option index (default: None)
-        """
+            name (str): The name of the dropdown.
+            value (int): The initial value of the dropdown. Defaults to None.
 
+        Attributes:
+            font (str): The font of the dropdown field.
+            choices (List[str]): The list of choices for the dropdown.
+        """
         super().__init__(name, value)
 
-        self.choices = []
-        self.desc = None
+        self.font = None
+        self.choices = None
 
     @property
     def schema_definition(self) -> dict:
-        """Generates a JSON schema definition for the dropdown.
+        """
+        Returns the schema definition for the dropdown.
 
-        Includes:
-        - Type constraint (integer)
-        - Maximum valid option index
-        - Any inherited schema properties
+        The schema definition is a dictionary that describes the
+        data type and other constraints for the dropdown value.
 
         Returns:
-            dict: Complete JSON schema definition
+            dict: A dictionary representing the schema definition.
         """
-
         return {
             "type": "integer",
             "maximum": len(self.choices) - 1,
@@ -61,12 +71,13 @@ class Dropdown(Widget):
 
     @property
     def sample_value(self) -> int:
-        """Generates a sample value for the dropdown.
+        """
+        Returns a sample value for the dropdown.
 
-        Returns the index of the last option by default.
+        The sample value is used to generate example data for the
+        dropdown field.
 
         Returns:
-            int: Index of the last option in the dropdown
+            int: A sample value for the dropdown.
         """
-
         return len(self.choices) - 1

PyPDFForm/middleware/image.py

@@ -1,34 +1,22 @@
 # -*- coding: utf-8 -*-
-"""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
+"""
+Module representing an image widget.
 
-Note: Inherits core functionality from Signature middleware since
-PDF image fields are technically signature fields with images.
+This module defines the Image class, which is a subclass of the
+Signature class. It represents an image form field in a PDF document,
+allowing users to add images to the form.
 """
 
 from .signature import Signature
 
 
 class Image(Signature):
-    """Middleware for PDF image field widgets.
-
-    Handles all aspects of image field processing including:
-    - Image data handling
-    - Aspect ratio control
-    - PDF form field integration
+    """
+    Represents an image widget.
 
-    Inherits from Signature class and extends it with image-specific features.
+    The Image class provides a concrete implementation for
+    image form fields. It inherits from the Signature class and
+    sets the preserve_aspect_ratio attribute to False by default.
     """
 
     preserve_aspect_ratio = False
-    """Whether to preserve the original image's aspect ratio when scaling."""

PyPDFForm/middleware/radio.py

@@ -1,26 +1,22 @@
 # -*- coding: utf-8 -*-
-"""Provides middleware for PDF radio button widgets.
+"""
+Module representing a radio button widget.
 
-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
+This module defines the Radio class, which is a subclass of the
+Checkbox class. It represents a radio button form field in a PDF
+document, allowing users to select one option from a group of choices.
 """
 
 from .checkbox import Checkbox
 
 
 class Radio(Checkbox):
-    """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
+    """
+    Represents a radio button widget.
 
-    Inherits from Checkbox class and extends it with radio-specific features.
+    The Radio class provides a concrete implementation for radio button
+    form fields. It inherits from the Checkbox class and implements
+    the schema_definition and sample_value properties.
     """
 
     def __init__(
@@ -28,32 +24,33 @@ class Radio(Checkbox):
         name: str,
         value: int = None,
     ) -> None:
-        """Initializes a new radio button widget.
+        """
+        Initializes a radio button widget.
 
         Args:
-            name: Field name/key for the radio button group
-            value: Initial selected option index (default: None)
-        """
+            name (str): The name of the radio button.
+            value (int): The initial value of the radio button. Defaults to None.
 
+        Attributes:
+            number_of_options (int): The number of options for the radio button.
+        """
         super().__init__(name, value)
 
-        self.size = None
         self.number_of_options = 0
-        self._button_style = self.BUTTON_STYLE_MAPPING["circle"]
 
     @property
     def schema_definition(self) -> dict:
-        """Generates a JSON schema definition for the radio button group.
+        """
+        Returns the schema definition for the radio button.
 
-        Includes:
-        - Type constraint (integer)
-        - Maximum valid option index
-        - Any inherited schema properties
+        The schema definition is a dictionary that describes the
+        data type and other constraints for the radio button value,
+        which is expected to be an integer representing the index
+        of the selected option.
 
         Returns:
-            dict: Complete JSON schema definition
+            dict: A dictionary representing the schema definition.
         """
-
         return {
             "maximum": self.number_of_options - 1,
             **super().schema_definition,
@@ -62,12 +59,14 @@ class Radio(Checkbox):
 
     @property
     def sample_value(self) -> int:
-        """Generates a sample value for the radio button group.
+        """
+        Returns a sample value for the radio button.
 
-        Returns the index of the last option by default.
+        The sample value is used to generate example data for the
+        radio button field. It returns the index of the last option
+        in the group.
 
         Returns:
-            int: Index of the last option in the group
+            int: A sample value for the radio button.
         """
-
         return self.number_of_options - 1

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