PyPDFForm 3.4.0__py3-none-any.whl → 3.5.0__py3-none-any.whl

PyPDFForm/__init__.py

@@ -20,9 +20,10 @@ 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__ = "3.4.0"
+__version__ = "3.5.0"
 
 from .middleware.text import Text  # exposing for setting global font attrs
+from .widgets import Fields
 from .wrapper import PdfWrapper
 
-__all__ = ["PdfWrapper", "Text"]
+__all__ = ["PdfWrapper", "Text", "Fields"]

PyPDFForm/constants.py

@@ -83,6 +83,20 @@ Filter = "/Filter"
 FlateDecode = "/FlateDecode"
 Encoding = "/Encoding"
 WinAnsiEncoding = "/WinAnsiEncoding"
+Widths = "/Widths"
+FirstChar = "/FirstChar"
+LastChar = "/LastChar"
+MissingWidth = "/MissingWidth"
+FontHead = "head"
+FontCmap = "cmap"
+FontHmtx = "hmtx"
+FontNotdef = ".notdef"
+
+FIRST_CHAR_CODE = 0
+LAST_CHAR_CODE = 255
+ENCODING_TABLE_SIZE = 256
+EM_TO_PDF_FACTOR = 1000
+DEFAULT_ASSUMED_GLYPH_WIDTH = 300
 
 Resources = "/Resources"
 FONT_NAME_PREFIX = "/F"

PyPDFForm/font.py

@@ -16,16 +16,21 @@ from functools import lru_cache
 from io import BytesIO
 from zlib import compress
 
+from fontTools.ttLib import TTFont as FT_TTFont
 from pypdf import PdfReader, PdfWriter
-from pypdf.generic import (ArrayObject, DictionaryObject, NameObject,
-                           NumberObject, StreamObject)
+from pypdf.generic import (ArrayObject, DictionaryObject, FloatObject,
+                           NameObject, NumberObject, StreamObject)
 from reportlab.pdfbase.pdfmetrics import registerFont
 from reportlab.pdfbase.ttfonts import TTFError, TTFont
 
-from .constants import (DR, FONT_NAME_PREFIX, AcroForm, BaseFont, Encoding,
-                        Fields, Filter, FlateDecode, Font, FontDescriptor,
-                        FontFile2, FontName, Length, Length1, Resources,
-                        Subtype, TrueType, Type, WinAnsiEncoding)
+from .constants import (DEFAULT_ASSUMED_GLYPH_WIDTH, DR, EM_TO_PDF_FACTOR,
+                        ENCODING_TABLE_SIZE, FIRST_CHAR_CODE, FONT_NAME_PREFIX,
+                        LAST_CHAR_CODE, AcroForm, BaseFont, Encoding, Fields,
+                        Filter, FirstChar, FlateDecode, Font, FontCmap,
+                        FontDescriptor, FontFile2, FontHead, FontHmtx,
+                        FontName, FontNotdef, LastChar, Length, Length1,
+                        MissingWidth, Resources, Subtype, TrueType, Type,
+                        Widths, WinAnsiEncoding)
 from .utils import stream_to_io
 
 
@@ -83,8 +88,9 @@ def get_additional_font_params(pdf: bytes, base_font_name: str) -> tuple:
     font_descriptor_params = {}
     font_dict_params = {}
     reader = PdfReader(stream_to_io(pdf))
+    first_page = reader.get_page(0)
 
-    for font in reader.pages[0][Resources][Font].values():
+    for font in first_page[Resources][Font].values():
         if base_font_name.replace("/", "") in font[BaseFont]:
             font_descriptor_params = dict(font[FontDescriptor])
             font_dict_params = dict(font)
@@ -93,6 +99,54 @@ def get_additional_font_params(pdf: bytes, base_font_name: str) -> tuple:
     return font_descriptor_params, font_dict_params
 
 
+def compute_font_glyph_widths(ttf_file: BytesIO, missing_width: float):
+    """
+    Computes the advance widths for all glyphs in a TrueType font, scaled for PDF text space.
+
+    This function utilizes the `fontTools` library to parse the provided TTF stream
+    and extract necessary metrics from the 'head', 'cmap', and 'hmtx' tables.
+    It calculates the width for each glyph based on its advance width and the font's
+    `unitsPerEm`, then scales these widths to a 1000-unit text space, which is standard
+    for PDF font metrics.
+
+    If any of the required font tables ('head', 'cmap', 'hmtx') are missing or
+    cannot be accessed, the function returns a list populated with a specified
+    `missing_width` for all expected glyphs, ensuring a fallback mechanism.
+
+    Args:
+        ttf_file (BytesIO): A BytesIO stream containing the TrueType Font (TTF) data.
+                            This stream should be seekable and readable.
+        missing_width (float): The default width to be used for all glyphs if the
+                                necessary font tables (head, cmap, hmtx) are not found
+                                within the TTF file.
+
+    Returns:
+        list[float]: A list of floats, where each float represents the scaled advance
+                     width of a glyph in PDF text space units (1000 units per EM).
+                     The list covers glyphs from `FIRST_CHAR_CODE` to `LAST_CHAR_CODE`.
+                     If font tables are missing, the list will be filled with `missing_width`.
+    """
+    font = FT_TTFont(ttf_file)
+    head_table = font.get(FontHead)
+    cmap_table = font.get(FontCmap)
+    hmtx_table = font.get(FontHmtx)
+
+    widths: list[float] = []
+    if head_table and cmap_table and hmtx_table:
+        cmap = cmap_table.getBestCmap()
+        units_per_em: int = head_table.unitsPerEm or 1
+
+        for codepoint in range(ENCODING_TABLE_SIZE):
+            glyph_name: str = cmap.get(codepoint, FontNotdef)
+            advance_width, _ = hmtx_table[glyph_name]
+            pdf_width: float = (advance_width / units_per_em) * EM_TO_PDF_FACTOR
+            widths.append(pdf_width)
+    else:
+        widths: list[float] = [missing_width] * ENCODING_TABLE_SIZE
+
+    return widths
+
+
 def register_font_acroform(pdf: bytes, ttf_stream: bytes, adobe_mode: bool) -> tuple:
     """
     Registers a TrueType font within the PDF's AcroForm dictionary.
@@ -159,7 +213,22 @@ def register_font_acroform(pdf: bytes, ttf_stream: bytes, adobe_mode: bool) -> t
             NameObject(Encoding): NameObject(WinAnsiEncoding),
         }
     )
+
     font_dict.update({k: v for k, v in font_dict_params.items() if k not in font_dict})
+
+    if font_dict and Widths in font_dict:
+        ttf_bytes_io = BytesIO(ttf_stream)
+        missing_width = font_descriptor.get(MissingWidth, DEFAULT_ASSUMED_GLYPH_WIDTH)
+        widths = compute_font_glyph_widths(ttf_bytes_io, missing_width)
+
+        font_dict.update(
+            {
+                NameObject(FirstChar): NumberObject(FIRST_CHAR_CODE),
+                NameObject(LastChar): NumberObject(LAST_CHAR_CODE),
+                NameObject(Widths): ArrayObject(FloatObject(width) for width in widths),
+            }
+        )
+
     font_dict_ref = writer._add_object(font_dict)  # type: ignore # noqa: SLF001 # # pylint: disable=W0212
 
     if AcroForm not in writer._root_object:  # type: ignore # noqa: SLF001 # # pylint: disable=W0212

PyPDFForm/widgets/__init__.py

@@ -0,0 +1,40 @@
+"""
+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
+type hinting when working with different widget configurations.
+
+Classes within this package encapsulate the properties and behaviors of individual
+form fields, facilitating their creation and manipulation within PDF documents.
+"""
+
+from dataclasses import dataclass
+from typing import Union
+
+from .checkbox import CheckBoxField
+from .dropdown import DropdownField
+from .image import ImageField
+from .radio import RadioGroup
+from .signature import SignatureField
+from .text import TextField
+
+FieldTypes = Union[
+    TextField, CheckBoxField, RadioGroup, DropdownField, SignatureField, ImageField
+]
+
+
+@dataclass
+class Fields:
+    """
+    A container class that provides convenient access to all available PDF form field types.
+
+    This class acts as a namespace for the various `Field` classes defined in the
+    `PyPDFForm.widgets` package, making it easier to reference them (e.g., `Fields.TextField`).
+    """
+
+    TextField = TextField
+    CheckBoxField = CheckBoxField
+    RadioGroup = RadioGroup
+    DropdownField = DropdownField
+    SignatureField = SignatureField
+    ImageField = ImageField

PyPDFForm/widgets/base.py

@@ -1,18 +1,24 @@
 # -*- coding: utf-8 -*-
 """
-This module defines the base class for all widgets in PyPDFForm.
+This module defines the base classes for all form fields and widgets in PyPDFForm.
 
-It provides a common interface for interacting with different types of form fields,
-such as text fields, checkboxes, and radio buttons. The Widget class handles
-basic properties like name, page number, and coordinates, and provides methods
-for rendering the widget on a PDF page.
+It provides a foundational structure for representing and interacting with
+different types of PDF form elements, such as text fields, checkboxes,
+and radio buttons.
+
+Classes:
+    - `Field`: A dataclass representing the common properties of a PDF form field.
+    - `Widget`: A base class for all widget implementations, providing core
+      functionality for rendering and manipulation.
 """
+
 # TODO: In `watermarks`, `PdfReader(stream_to_io(stream))` is called, which re-parses the PDF for each widget. If multiple widgets are being processed, consider passing the `PdfReader` object directly to avoid redundant parsing.
 # TODO: In `watermarks`, the list comprehension `[watermark.read() if i == self.page_number - 1 else b"" for i in range(page_count)]` creates a new `BytesIO` object and reads from it for each widget. If many widgets are created, this could be optimized by creating the `BytesIO` object once and passing it around, or by directly returning the watermark bytes and its page number.
 
+from dataclasses import dataclass
 from inspect import signature
 from io import BytesIO
-from typing import List, Union
+from typing import List, Optional, Union
 
 from pypdf import PdfReader
 from reportlab.lib.colors import Color
@@ -22,6 +28,35 @@ from ..constants import fieldFlags, required
 from ..utils import stream_to_io
 
 
+@dataclass
+class Field:
+    """
+    Base dataclass for all PDF form fields.
+
+    This class defines the common properties that all types of form fields
+    (e.g., text fields, checkboxes, radio buttons) share. Specific field types
+    will extend this class to add their unique attributes.
+
+    Attributes:
+        name (str): The name of the form field. This is used to identify the
+            field within the PDF document.
+        page_number (int): The 1-based page number on which the field is located.
+        x (float): The x-coordinate of the field's position on the page.
+        y (float): The y-coordinate of the field's position on the page.
+        required (Optional[bool]): Indicates whether the field is required to be
+            filled by the user. Defaults to None, meaning not explicitly set.
+        tooltip (Optional[str]): A tooltip message that appears when the user
+            hovers over the field. Defaults to None.
+    """
+
+    name: str
+    page_number: int
+    x: float
+    y: float
+    required: Optional[bool] = None
+    tooltip: Optional[str] = None
+
+
 class Widget:
     """
     Base class for all widgets in PyPDFForm.

PyPDFForm/widgets/checkbox.py

@@ -1,10 +1,48 @@
 # -*- coding: utf-8 -*-
 """
-This module defines the CheckBoxWidget class, which is a subclass of the
-Widget class. It represents a checkbox form field in a PDF document.
+This module defines the `CheckBoxField` and `CheckBoxWidget` classes, which are
+used to represent and manipulate checkbox form fields within PDF documents.
+
+The `CheckBoxField` class is a dataclass that encapsulates the properties of a
+checkbox field, such as its size, style, and colors.
+
+The `CheckBoxWidget` class extends the base `Widget` class to provide specific
+functionality for interacting with checkbox form fields in PDFs.
 """
 
-from .base import Widget
+from dataclasses import dataclass
+from typing import Optional, Tuple
+
+from .base import Field, Widget
+
+
+@dataclass
+class CheckBoxField(Field):
+    """
+    Represents a checkbox field in a PDF document.
+
+    This dataclass extends the `Field` base class and defines the specific
+    attributes that can be configured for a checkbox field.
+
+    Attributes:
+        _field_type (str): The type of the field, fixed as "checkbox".
+        size (Optional[float]): The size of the checkbox.
+        button_style (Optional[str]): The visual style of the checkbox button
+            (e.g., "check", "circle", "cross").
+        tick_color (Optional[Tuple[float, ...]]): The color of the checkmark or tick.
+        bg_color (Optional[Tuple[float, ...]]): The background color of the checkbox.
+        border_color (Optional[Tuple[float, ...]]): The color of the checkbox's border.
+        border_width (Optional[float]): The width of the checkbox's border.
+    """
+
+    _field_type: str = "checkbox"
+
+    size: Optional[float] = None
+    button_style: Optional[str] = None
+    tick_color: Optional[Tuple[float, ...]] = None
+    bg_color: Optional[Tuple[float, ...]] = None
+    border_color: Optional[Tuple[float, ...]] = None
+    border_width: Optional[float] = None
 
 
 class CheckBoxWidget(Widget):

PyPDFForm/widgets/dropdown.py

@@ -1,12 +1,59 @@
 # -*- coding: utf-8 -*-
 """
-This module defines the DropdownWidget class, which is a subclass of the
-TextWidget class. It represents a dropdown form field in a PDF document.
+This module defines the `DropdownField` and `DropdownWidget` classes, which are
+used to represent and manipulate dropdown form fields within PDF documents.
+
+The `DropdownField` class is a dataclass that encapsulates the properties of a
+dropdown field, such as its options, dimensions, and styling.
+
+The `DropdownWidget` class extends the base `TextWidget` class to provide
+specific functionality for interacting with dropdown form fields in PDFs.
 """
 
+from dataclasses import dataclass
+from typing import List, Optional, Tuple, Union
+
+from .base import Field
 from .text import TextWidget
 
 
+@dataclass
+class DropdownField(Field):
+    """
+    Represents a dropdown field in a PDF document.
+
+    This dataclass extends the `Field` base class and defines the specific
+    attributes that can be configured for a dropdown selection field.
+
+    Attributes:
+        _field_type (str): The type of the field, fixed as "dropdown".
+        options (Optional[List[Union[str, Tuple[str, str]]]]): A list of options
+            available in the dropdown. Each option can be a string (display value)
+            or a tuple of strings (display value, export value).
+        width (Optional[float]): The width of the dropdown field.
+        height (Optional[float]): The height of the dropdown field.
+        font (Optional[str]): The font to use for the dropdown text.
+        font_size (Optional[float]): The font size for the dropdown text.
+        font_color (Optional[Tuple[float, ...]]): The color of the font as an RGB or RGBA tuple.
+        bg_color (Optional[Tuple[float, ...]]): The background color of the dropdown field.
+        border_color (Optional[Tuple[float, ...]]): The color of the dropdown's border.
+        border_width (Optional[float]): The width of the dropdown's border.
+    """
+
+    _field_type: str = "dropdown"
+
+    options: Optional[List[Union[str, Tuple[str, str]]]] = None
+    width: Optional[float] = None
+    height: Optional[float] = None
+    # pylint: disable=R0801
+    font: Optional[str] = None
+    font_size: Optional[float] = None
+    font_color: Optional[Tuple[float, ...]] = None
+    bg_color: Optional[Tuple[float, ...]] = None
+    border_color: Optional[Tuple[float, ...]] = None
+    border_width: Optional[float] = None
+
+
 class DropdownWidget(TextWidget):
     """
     Represents a dropdown widget in a PDF form.

PyPDFForm/widgets/image.py

@@ -1,12 +1,35 @@
 # -*- coding: utf-8 -*-
 """
-This module defines the ImageWidget class, which is a subclass of the
-SignatureWidget class. It represents an image field in a PDF document.
-The ImageWidget leverages the SignatureWidget's functionality to handle
-image insertion into PDF forms.
+This module defines the `ImageField` and `ImageWidget` classes, which are used
+to represent and manipulate image form fields within PDF documents.
+
+The `ImageField` class is a dataclass that encapsulates the properties of an
+image field, inheriting from `SignatureField` for its dimensional attributes.
+
+The `ImageWidget` class extends the base `SignatureWidget` class to provide
+specific functionality for interacting with image form fields in PDFs,
+leveraging the existing infrastructure for positioning and rendering.
 """
 
-from .signature import SignatureWidget
+from dataclasses import dataclass
+
+from .signature import SignatureField, SignatureWidget
+
+
+@dataclass
+class ImageField(SignatureField):
+    """
+    Represents an image field in a PDF document.
+
+    This dataclass extends the `SignatureField` base class and defines the
+    specific attributes for an image input field. It inherits `width` and
+    `height` from `SignatureField` as images also have dimensions.
+
+    Attributes:
+        _field_type (str): The type of the field, fixed as "image".
+    """
+
+    _field_type: str = "image"
 
 
 class ImageWidget(SignatureWidget):

PyPDFForm/widgets/radio.py

@@ -1,16 +1,48 @@
 # -*- coding: utf-8 -*-
 """
-This module defines the RadioWidget class, which is a subclass of the
-CheckBoxWidget class. It represents a radio button form field in a PDF
-document.
+This module defines the `RadioGroup` and `RadioWidget` classes, which are used
+to represent and manipulate radio button groups within PDF documents.
+
+The `RadioGroup` class is a dataclass that encapsulates the properties of a
+radio button group, such as its coordinates and shape.
+
+The `RadioWidget` class extends the base `CheckBoxWidget` class to provide
+specific functionality for interacting with radio button form fields in PDFs.
 """
+
 # TODO: In `canvas_operations`, `self.acro_form_params.copy()` creates a shallow copy of the dictionary in each iteration of the loop. For a large number of radio buttons, this repeated copying can be inefficient. Consider modifying the dictionary in place and then reverting changes if necessary, or restructuring the data to avoid repeated copying.
 
-from typing import List
+from dataclasses import dataclass
+from typing import List, Optional
 
 from reportlab.pdfgen.canvas import Canvas
 
-from .checkbox import CheckBoxWidget
+from .checkbox import CheckBoxField, CheckBoxWidget
+
+
+@dataclass
+class RadioGroup(CheckBoxField):
+    """
+    Represents a group of radio buttons in a PDF document.
+
+    This dataclass extends the `CheckBoxField` base class and defines the specific
+    attributes that can be configured for a radio button group. Unlike a single
+    checkbox, a radio group allows for multiple positions (x, y coordinates)
+    where individual radio buttons can be placed, but only one can be selected.
+
+    Attributes:
+        _field_type (str): The type of the field, fixed as "radio".
+        x (List[float]): A list of x-coordinates for each radio button in the group.
+        y (List[float]): A list of y-coordinates for each radio button in the group.
+        shape (Optional[str]): The shape of the radio button. Valid values are
+            "circle" or "square". Defaults to None, which typically means a default circle shape.
+    """
+
+    _field_type: str = "radio"
+
+    x: List[float]
+    y: List[float]
+    shape: Optional[str] = None
 
 
 class RadioWidget(CheckBoxWidget):

PyPDFForm/widgets/signature.py

@@ -1,16 +1,23 @@
 # -*- coding: utf-8 -*-
 """
-This module defines the SignatureWidget class, which is responsible for
-representing signature fields in a PDF form. It handles the creation and
-rendering of signature widgets, as well as the integration of signatures
-into the PDF document.
+This module defines the `SignatureField` and `SignatureWidget` classes, which are
+used to represent and manipulate signature form fields within PDF documents.
+
+The `SignatureField` class is a dataclass that encapsulates the properties of a
+signature field, such as its dimensions.
+
+The `SignatureWidget` class provides specific functionality for interacting with
+signature form fields in PDFs, including handling their creation, rendering, and
+integration into the document.
 """
+
 # TODO: In `watermarks`, `PdfReader(stream_to_io(BEDROCK_PDF))` is called every time the method is invoked. If `BEDROCK_PDF` is static, consider parsing it once and caching the `PdfReader` object to avoid redundant I/O and parsing.
 # TODO: In `watermarks`, the list comprehension `[f.read() if i == self.page_number - 1 else b"" for i in range(page_count)]` reads the entire `BytesIO` object `f` multiple times if `page_count` is large. Read `f` once into a variable and then use that variable in the list comprehension.
 # TODO: The `input_pdf` is created in `watermarks` but only its page count is used. If the `PdfReader` object is not needed for other operations, consider a lighter way to get the page count or pass the `PdfReader` object from the caller if it's already available.
 
+from dataclasses import dataclass
 from io import BytesIO
-from typing import List
+from typing import List, Optional
 
 from pypdf import PdfReader, PdfWriter
 from pypdf.generic import (ArrayObject, FloatObject, NameObject,
@@ -19,9 +26,30 @@ from pypdf.generic import (ArrayObject, FloatObject, NameObject,
 from ..constants import Annots, Rect, T
 from ..template import get_widget_key
 from ..utils import stream_to_io
+from .base import Field
 from .bedrock import BEDROCK_PDF
 
 
+@dataclass
+class SignatureField(Field):
+    """
+    Represents a signature field in a PDF document.
+
+    This dataclass extends the `Field` base class and defines the specific
+    attributes that can be configured for a signature input field.
+
+    Attributes:
+        _field_type (str): The type of the field, fixed as "signature".
+        width (Optional[float]): The width of the signature field.
+        height (Optional[float]): The height of the signature field.
+    """
+
+    _field_type: str = "signature"
+
+    width: Optional[float] = None
+    height: Optional[float] = None
+
+
 class SignatureWidget:
     """
     Represents a signature widget in a PDF form.

PyPDFForm/widgets/text.py

@@ -1,10 +1,60 @@
 # -*- coding: utf-8 -*-
 """
-This module defines the TextWidget class, which is a subclass of the
-Widget class. It represents a text field in a PDF document.
+This module defines the `TextField` and `TextWidget` classes, which are used to
+represent and manipulate text fields within PDF documents.
+
+The `TextField` class is a dataclass that encapsulates the properties of a text
+field, such as its dimensions, styling, and behavior.
+
+The `TextWidget` class extends the base `Widget` class to provide specific
+functionality for interacting with text form fields in PDFs.
 """
 
-from .base import Widget
+from dataclasses import dataclass
+from typing import Optional, Tuple
+
+from .base import Field, Widget
+
+
+@dataclass
+class TextField(Field):
+    """
+    Represents a text field in a PDF document.
+
+    This dataclass extends the `Field` base class and defines the specific
+    attributes that can be configured for a text input field.
+
+    Attributes:
+        _field_type (str): The type of the field, fixed as "text".
+        width (Optional[float]): The width of the text field.
+        height (Optional[float]): The height of the text field.
+        max_length (Optional[int]): The maximum number of characters allowed in the text field.
+        comb (Optional[bool]): If True, the text field will display characters
+            individually in a row of boxes.
+        font (Optional[str]): The font to use for the text field.
+        font_size (Optional[float]): The font size for the text.
+        font_color (Optional[Tuple[float, ...]]): The color of the font as an RGB or RGBA tuple.
+        bg_color (Optional[Tuple[float, ...]]): The background color of the text field.
+        border_color (Optional[Tuple[float, ...]]): The color of the text field's border.
+        border_width (Optional[float]): The width of the text field's border.
+        alignment (Optional[int]): The text alignment within the field (e.g., 0 for left, 1 for center, 2 for right).
+        multiline (Optional[bool]): If True, the text field can display multiple lines of text.
+    """
+
+    _field_type: str = "text"
+
+    width: Optional[float] = None
+    height: Optional[float] = None
+    max_length: Optional[int] = None
+    comb: Optional[bool] = None
+    font: Optional[str] = None
+    font_size: Optional[float] = None
+    font_color: Optional[Tuple[float, ...]] = None
+    bg_color: Optional[Tuple[float, ...]] = None
+    border_color: Optional[Tuple[float, ...]] = None
+    border_width: Optional[float] = None
+    alignment: Optional[int] = None
+    multiline: Optional[bool] = None
 
 
 class TextWidget(Widget):

PyPDFForm/wrapper.py

@@ -29,12 +29,15 @@ underlying PDF manipulation.
 
 from __future__ import annotations
 
+from dataclasses import asdict
 from functools import cached_property
-from typing import BinaryIO, Dict, List, Sequence, Tuple, Union
+from typing import TYPE_CHECKING, BinaryIO, Dict, List, Sequence, Tuple, Union
+from warnings import warn
 
 from .adapter import fp_or_f_obj_or_stream_to_stream
 from .constants import (DEFAULT_FONT, DEFAULT_FONT_COLOR, DEFAULT_FONT_SIZE,
-                        VERSION_IDENTIFIER_PREFIX, VERSION_IDENTIFIERS)
+                        DEPRECATION_NOTICE, VERSION_IDENTIFIER_PREFIX,
+                        VERSION_IDENTIFIERS)
 from .coordinate import generate_coordinate_grid
 from .filler import fill
 from .font import (get_all_available_fonts, register_font,
@@ -56,6 +59,9 @@ from .widgets.radio import RadioWidget
 from .widgets.signature import SignatureWidget
 from .widgets.text import TextWidget
 
+if TYPE_CHECKING:
+    from .widgets import FieldTypes
+
 
 class PdfWrapper:
     """
@@ -456,6 +462,42 @@ class PdfWrapper:
 
         return self
 
+    def create_field(
+        self,
+        field: FieldTypes,
+    ) -> PdfWrapper:
+        """
+        Creates a new form field (widget) on the PDF using a `FieldTypes` object.
+
+        This method simplifies widget creation by taking a `FieldTypes` object,
+        extracting its properties, and then delegating to the `create_widget` method.
+
+        Args:
+            field (FieldTypes): An object representing the field to create.
+                This object encapsulates all necessary properties like name,
+                page number, coordinates, and type of the field.
+
+        Returns:
+            PdfWrapper: The `PdfWrapper` object, allowing for method chaining.
+        """
+
+        field_dict = asdict(field)
+        widget_type = field_dict.pop("_field_type")
+        name = field_dict.pop("name")
+        page_number = field_dict.pop("page_number")
+        x = field_dict.pop("x")
+        y = field_dict.pop("y")
+
+        field_dict["suppress_deprecation_notice"] = True
+        return self.create_widget(
+            widget_type,
+            name,
+            page_number,
+            x,
+            y,
+            **{k: v for k, v in field_dict.items() if v is not None},
+        )
+
     def create_widget(
         self,
         widget_type: str,
@@ -488,6 +530,16 @@ class PdfWrapper:
             PdfWrapper: The `PdfWrapper` object, allowing for method chaining.
         """
 
+        if not kwargs.get("suppress_deprecation_notice"):
+            warn(
+                DEPRECATION_NOTICE.format(
+                    f"{self.__class__.__name__}.create_widget()",
+                    f"{self.__class__.__name__}.create_field()",
+                ),
+                DeprecationWarning,  # noqa: PT030
+                stacklevel=2,
+            )
+
         _class = None
         if widget_type == "text":
             _class = TextWidget

{pypdfform-3.4.0.dist-info → pypdfform-3.5.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: PyPDFForm
-Version: 3.4.0
+Version: 3.5.0
 Summary: The Python library for PDF forms.
 Author: Jinge Li
 License-Expression: MIT
@@ -21,6 +21,7 @@ Requires-Python: >=3.9
 Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: cryptography
+Requires-Dist: fonttools
 Requires-Dist: pillow
 Requires-Dist: pypdf
 Requires-Dist: reportlab

{pypdfform-3.4.0.dist-info → pypdfform-3.5.0.dist-info}/RECORD

@@ -1,16 +1,16 @@
-PyPDFForm/__init__.py,sha256=SV7z1wBkJS8IDuoQvsqd9oYq5u8DtiRxg-zA86EWz2Y,925
+PyPDFForm/__init__.py,sha256=TBcOLWb7xcC0r6Qo7teHtwcQA97qsTX5gUay7Vfq3LY,963
 PyPDFForm/adapter.py,sha256=LBxHth0qJFB6rdByRJbsn4x0dftCOAolKVutZeFZm9E,2634
-PyPDFForm/constants.py,sha256=rxE9KyygdMkuPfpO6PRV6DasvIta0sZqadVPtX9Q_1U,2616
+PyPDFForm/constants.py,sha256=tFtomm4bSsghxRqKaMP6Tln7ug9W_72e-AAU3sEU_no,2917
 PyPDFForm/coordinate.py,sha256=veYOlRyFKIvzLISYA_f-drNBiKOzFwr0EIFCaUAzGgo,4428
 PyPDFForm/filler.py,sha256=fqGIxT3FR3cWo3SMTDYud6Ocs9SZBmSpFv5yg1v19Wk,8450
-PyPDFForm/font.py,sha256=opZjAacsIRFcERXWegPXkOSpmnRrv4y_50yD0_BjWPM,10273
+PyPDFForm/font.py,sha256=TkiGPHIf4NxDiDzkrlXIr1r-DZC1V4aYrQAzGFxBlLI,13423
 PyPDFForm/hooks.py,sha256=tW4VGAFZupSMhtHWoGsoljOciGT2yBBuoqNCuyGsKzM,15697
 PyPDFForm/image.py,sha256=P1P3Ejm8PVPQwpJFGAesjtwS5hxnVItrj75TE3WnFhM,4607
 PyPDFForm/patterns.py,sha256=HbTqzFllQ1cW3CqyNEfVh0qUMeFerbvOd0-HQnkifQQ,9765
 PyPDFForm/template.py,sha256=mmy4kVMe1plHxKtxFLbajBT1Mrv9g_oNCyzTUCWEyVw,11101
 PyPDFForm/utils.py,sha256=JavhAO4HmYRdujlsPXcZWGXTf7wDXzj4uU1XGRFsAaA,13257
 PyPDFForm/watermark.py,sha256=BJ8NeZLKf-MuJ2XusHiALaQpoqE8j6hHGbWcNhpjxN0,11299
-PyPDFForm/wrapper.py,sha256=KTFou6cXrHtLHVKwngoIr4Pwu4vOfjXY0cWRNNDlW0U,28866
+PyPDFForm/wrapper.py,sha256=_KKE2jUBcXxnkMzL8T43JjMmf8fvuJ-TTmYEy_h7h-c,30603
 PyPDFForm/middleware/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 PyPDFForm/middleware/base.py,sha256=ZmJFh3nSxj6PFjqBqsLih0pXKtcm1o-ctJVWn0v6bbI,3278
 PyPDFForm/middleware/checkbox.py,sha256=OCSZEFD8wQG_Y9qO7Os6VXTaxJCpkRYTxI4wDgG0GZc,1870
@@ -19,17 +19,17 @@ PyPDFForm/middleware/image.py,sha256=eKM7anU56jbaECnK6rq0jGsBRY3HW_fM86fgA3hq7xA
 PyPDFForm/middleware/radio.py,sha256=PuGDJ8RN1C-MkL9Jf14ABWYV67cN18R66dI4nR-03DU,2211
 PyPDFForm/middleware/signature.py,sha256=P6Mg9AZP5jML7GawsteVZjDaunKb9Yazu5iy0qF60bo,2432
 PyPDFForm/middleware/text.py,sha256=WLK6Ae9zT3uUu1AzcWUhR-hs5rm0z9Ydz-fL8Qu-44o,3997
-PyPDFForm/widgets/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-PyPDFForm/widgets/base.py,sha256=iWsZ4LDtFVmrVUwvG_ORnH8fd614saI6wfNN4LrgOjQ,7230
+PyPDFForm/widgets/__init__.py,sha256=TvMMWGtrTC4xRPRokr4Pl8ZtvfYXRPUDgfHd3pnbPE8,1304
+PyPDFForm/widgets/base.py,sha256=Y8cf8mR7VMdH2L3pmI43NWxm7M9FLHgHMBAf6wb549c,8486
 PyPDFForm/widgets/bedrock.py,sha256=j6beU04kaQzpAIFZHI5VJLaDT5RVAAa6LzkU1luJpN8,137660
-PyPDFForm/widgets/checkbox.py,sha256=gqqulFdjrLd6Ry-BM4sHwGu0QogfKnG_6v3RcYLeYMo,1347
-PyPDFForm/widgets/dropdown.py,sha256=6zZwt6eU9Hgwl-57QfyT3G6c37FkQTJ-XSsXGluWevs,1459
-PyPDFForm/widgets/image.py,sha256=aSD-3MEZFIRL7HYVuO6Os8irfSUOLHA_rHGkqcEIPPA,855
-PyPDFForm/widgets/radio.py,sha256=oFw8Um4g414UH93QJv6dZHRxpq0yuYog09B2W3eE8wo,2612
-PyPDFForm/widgets/signature.py,sha256=L4Et6pxtrEh7U-lnnLZrnvb_dKwGNpI6TZ11HCD0lvY,5147
-PyPDFForm/widgets/text.py,sha256=rmI0EYUTVf06AKsnxsVqewdTjt_mhBASEHyj5nAvYjE,1606
-pypdfform-3.4.0.dist-info/licenses/LICENSE,sha256=43awmYkI6opyTpg19me731iO1WfXZwViqb67oWtCsFY,1065
-pypdfform-3.4.0.dist-info/METADATA,sha256=uOBdsdX7B1B9QU8KoIIem38mkRDS38t31g22gB8IQzY,4242
-pypdfform-3.4.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-pypdfform-3.4.0.dist-info/top_level.txt,sha256=GQQKuWqPUjT9YZqwK95NlAQzxjwoQrsxQ8ureM8lWOY,10
-pypdfform-3.4.0.dist-info/RECORD,,
+PyPDFForm/widgets/checkbox.py,sha256=IwQvw2W6HuSLyZFv-qGvdvCHp8uAp2KjOAt7-Y73Y74,2870
+PyPDFForm/widgets/dropdown.py,sha256=7yPxx-uWyZe8wxxVqYVXvomPHp_5CAygAEMldibe6eg,3528
+PyPDFForm/widgets/image.py,sha256=SegpzNjTXPuWX4hk_20yKk_IDaOrc81X9b9B4qK-kME,1628
+PyPDFForm/widgets/radio.py,sha256=pSOAgOakGAoi-190pFklMmLClFdPCWMDYWW1Ce6q__g,3933
+PyPDFForm/widgets/signature.py,sha256=yye_CLYpgurLJ_rt7Td3xaY28uSAHc1YlqL1gmWqPqw,6034
+PyPDFForm/widgets/text.py,sha256=EG2mR-POHGWt9I-t3QVsTFIiDB5yqKPDBTKkAytQGp8,3836
+pypdfform-3.5.0.dist-info/licenses/LICENSE,sha256=43awmYkI6opyTpg19me731iO1WfXZwViqb67oWtCsFY,1065
+pypdfform-3.5.0.dist-info/METADATA,sha256=ojZtGj142xTZFvkwQN1iI7QFwjQFpoHxxYa-cctXQlA,4267
+pypdfform-3.5.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+pypdfform-3.5.0.dist-info/top_level.txt,sha256=GQQKuWqPUjT9YZqwK95NlAQzxjwoQrsxQ8ureM8lWOY,10
+pypdfform-3.5.0.dist-info/RECORD,,