PyPDFForm 3.5.3__py3-none-any.whl → 4.2.0__py3-none-any.whl

PyPDFForm/hooks.py

@@ -8,22 +8,21 @@ of checkbox and radio button widgets. It also provides functions for flattening
 generic and radio button widgets. These hooks are triggered during the PDF form
 filling process, allowing for customization of the form's appearance and behavior.
 """
-# TODO: In `trigger_widget_hooks`, the PDF is read and written in each call. If this function is part of a larger workflow, consider passing `PdfReader` and `PdfWriter` objects to avoid redundant parsing and writing, allowing modifications to be accumulated and written once.
-# TODO: String manipulations (split/join) in `update_text_field_font`, `update_text_field_font_size`, and `update_text_field_font_color` could be optimized for very long `DA` strings, potentially using more efficient string manipulation techniques or regex if the structure is consistent.
-# TODO: The `get_widget_key` function is called in a loop within `trigger_widget_hooks`. If its internal logic is complex, consider caching its results or optimizing its implementation to avoid redundant computations.
-# TODO: In `flatten_radio` and `flatten_generic`, `annot.get(NameObject(Ff), 0)` is called twice within the conditional. Store this value in a local variable to avoid redundant dictionary lookups.
 
 import sys
 from io import BytesIO
-from typing import cast
+from typing import TextIO, Union, cast
 
 from pypdf import PdfReader, PdfWriter
 from pypdf.generic import (ArrayObject, DictionaryObject, FloatObject,
                            NameObject, NumberObject, TextStringObject)
 
-from .constants import (COMB, DA, FONT_COLOR_IDENTIFIER, FONT_SIZE_IDENTIFIER,
-                        MULTILINE, READ_ONLY, REQUIRED, TU, Annots, Ff, MaxLen,
-                        Opt, Parent, Q, Rect)
+from .adapter import fp_or_f_obj_or_f_content_to_content
+from .constants import (AA, COMB, DA, FONT_COLOR_IDENTIFIER,
+                        FONT_SIZE_IDENTIFIER, JS, MULTILINE, READ_ONLY,
+                        REQUIRED, TU, Action, Annots, Bl, D, E, Ff, Fo,
+                        JavaScript, MaxLen, Opt, Parent, Q, Rect, S, Type, U,
+                        X)
 from .template import get_widget_key
 from .utils import stream_to_io
 
@@ -216,9 +215,7 @@ def update_text_field_multiline(annot: DictionaryObject, val: bool) -> None:
         val (bool): True to enable multiline, False to disable.
     """
     if val:
-        # TODO: investigate this more
-        # may need to change everywhere how feature flags precedence work
-        # https://github.com/chinapandaman/PyPDFForm/issues/1162#issuecomment-3326233842
+        # Ff in annot[Parent] only in hooks.py, or when editing instead of retrieving
         if Parent in annot and Ff in annot[Parent]:
             annot[NameObject(Parent)][NameObject(Ff)] = NumberObject(
                 int(
@@ -247,7 +244,7 @@ def update_text_field_comb(annot: DictionaryObject, val: bool) -> None:
         val (bool): True to enable comb, False to disable.
     """
     if val:
-        if Parent in annot and Ff not in annot:
+        if Parent in annot and Ff in annot[Parent]:
             annot[NameObject(Parent)][NameObject(Ff)] = NumberObject(
                 int(
                     annot[NameObject(Parent)][NameObject(Ff)]
@@ -367,12 +364,12 @@ def flatten_generic(annot: DictionaryObject, val: bool) -> None:
         annot (DictionaryObject): The annotation dictionary.
         val (bool): True to flatten (make read-only), False to unflatten (make editable).
     """
-    if Parent in annot and Ff not in annot:
+    if Parent in annot and (Ff in annot[Parent] or Ff not in annot):
         annot[NameObject(Parent)][NameObject(Ff)] = NumberObject(
             (
-                int(annot.get(NameObject(Ff), 0)) | READ_ONLY
+                int(annot[NameObject(Parent)].get(NameObject(Ff), 0)) | READ_ONLY
                 if val
-                else int(annot.get(NameObject(Ff), 0)) & ~READ_ONLY
+                else int(annot[NameObject(Parent)].get(NameObject(Ff), 0)) & ~READ_ONLY
             )
         )
     else:
@@ -412,20 +409,146 @@ def update_field_required(annot: DictionaryObject, val: bool) -> None:
         annot (DictionaryObject): The annotation dictionary for the form field.
         val (bool): True to set the field as required, False to make it optional.
     """
-    # TODO: add a test case when supporting edit required
-    # if Parent in annot and Ff not in annot:
-    #     annot[NameObject(Parent)][NameObject(Ff)] = NumberObject(
-    #         (
-    #             int(annot.get(NameObject(Ff), 0)) | REQUIRED
-    #             if val
-    #             else int(annot.get(NameObject(Ff), 0)) & ~REQUIRED
-    #         )
-    #     )
-    # else:
-    annot[NameObject(Ff)] = NumberObject(
-        (
-            int(annot.get(NameObject(Ff), 0)) | REQUIRED
-            if val
-            else int(annot.get(NameObject(Ff), 0)) & ~REQUIRED
+    if Parent in annot and Ff in annot[Parent]:
+        annot[NameObject(Parent)][NameObject(Ff)] = NumberObject(
+            (
+                int(annot[NameObject(Parent)].get(NameObject(Ff), 0)) | REQUIRED
+                if val
+                else int(annot[NameObject(Parent)].get(NameObject(Ff), 0)) & ~REQUIRED
+            )
         )
+    else:
+        annot[NameObject(Ff)] = NumberObject(
+            (
+                int(annot.get(NameObject(Ff), 0)) | REQUIRED
+                if val
+                else int(annot.get(NameObject(Ff), 0)) & ~REQUIRED
+            )
+        )
+
+
+def _update_field_javascript(
+    annot: DictionaryObject, trigger_event: str, val: Union[str, TextIO]
+) -> None:
+    """
+    Updates a specific JavaScript action for a form field annotation.
+
+    This internal helper function adds or updates a JavaScript action in the
+    annotation's additional actions dictionary (AA) for a specific trigger event.
+
+    Args:
+        annot (DictionaryObject): The annotation dictionary for the form field.
+        trigger_event (str): The event that triggers the JavaScript action
+            (e.g., E for enter, X for exit, D for down, U for up, Fo for focus, Bl for blur).
+        val (Union[str, TextIO]): The JavaScript code to execute. Can be a string
+            containing the code or a file-like object/path to a file containing the code.
+    """
+    if AA not in annot:
+        annot[NameObject(AA)] = DictionaryObject()
+
+    annot[NameObject(AA)][NameObject(trigger_event)] = DictionaryObject()
+    annot[NameObject(AA)][NameObject(trigger_event)][NameObject(Type)] = NameObject(
+        Action
     )
+    annot[NameObject(AA)][NameObject(trigger_event)][NameObject(S)] = NameObject(
+        JavaScript
+    )
+    annot[NameObject(AA)][NameObject(trigger_event)][NameObject(JS)] = TextStringObject(
+        fp_or_f_obj_or_f_content_to_content(val)
+    )
+
+
+def update_field_on_hovered_over_javascript(
+    annot: DictionaryObject, val: Union[str, TextIO]
+) -> None:
+    """
+    Updates the JavaScript action triggered when the mouse enters the field area.
+
+    This function sets the 'E' (Enter) entry in the annotation's additional actions
+    dictionary, specifying JavaScript code to execute when the cursor enters the field.
+
+    Args:
+        annot (DictionaryObject): The annotation dictionary for the form field.
+        val (Union[str, TextIO]): The JavaScript code to execute.
+    """
+    _update_field_javascript(annot, E, val)
+
+
+def update_field_on_hovered_off_javascript(
+    annot: DictionaryObject, val: Union[str, TextIO]
+) -> None:
+    """
+    Updates the JavaScript action triggered when the mouse exits the field area.
+
+    This function sets the 'X' (Exit) entry in the annotation's additional actions
+    dictionary, specifying JavaScript code to execute when the cursor leaves the field.
+
+    Args:
+        annot (DictionaryObject): The annotation dictionary for the form field.
+        val (Union[str, TextIO]): The JavaScript code to execute.
+    """
+    _update_field_javascript(annot, X, val)
+
+
+def update_field_on_mouse_pressed_javascript(
+    annot: DictionaryObject, val: Union[str, TextIO]
+) -> None:
+    """
+    Updates the JavaScript action triggered when the mouse button is pressed down inside the field.
+
+    This function sets the 'D' (Down) entry in the annotation's additional actions
+    dictionary, specifying JavaScript code to execute when the mouse button is pressed.
+
+    Args:
+        annot (DictionaryObject): The annotation dictionary for the form field.
+        val (Union[str, TextIO]): The JavaScript code to execute.
+    """
+    _update_field_javascript(annot, D, val)
+
+
+def update_field_on_mouse_released_javascript(
+    annot: DictionaryObject, val: Union[str, TextIO]
+) -> None:
+    """
+    Updates the JavaScript action triggered when the mouse button is released inside the field.
+
+    This function sets the 'U' (Up) entry in the annotation's additional actions
+    dictionary, specifying JavaScript code to execute when the mouse button is released.
+
+    Args:
+        annot (DictionaryObject): The annotation dictionary for the form field.
+        val (Union[str, TextIO]): The JavaScript code to execute.
+    """
+    _update_field_javascript(annot, U, val)
+
+
+def update_field_on_focused_javascript(
+    annot: DictionaryObject, val: Union[str, TextIO]
+) -> None:
+    """
+    Updates the JavaScript action triggered when the field receives input focus.
+
+    This function sets the 'Fo' (Focus) entry in the annotation's additional actions
+    dictionary, specifying JavaScript code to execute when the field gains focus.
+
+    Args:
+        annot (DictionaryObject): The annotation dictionary for the form field.
+        val (Union[str, TextIO]): The JavaScript code to execute.
+    """
+    _update_field_javascript(annot, Fo, val)
+
+
+def update_field_on_blurred_javascript(
+    annot: DictionaryObject, val: Union[str, TextIO]
+) -> None:
+    """
+    Updates the JavaScript action triggered when the field loses input focus.
+
+    This function sets the 'Bl' (Blur) entry in the annotation's additional actions
+    dictionary, specifying JavaScript code to execute when the field loses focus.
+
+    Args:
+        annot (DictionaryObject): The annotation dictionary for the form field.
+        val (Union[str, TextIO]): The JavaScript code to execute.
+    """
+    _update_field_javascript(annot, Bl, val)

PyPDFForm/image.py

@@ -6,9 +6,6 @@ It includes functions for rotating images, retrieving image dimensions, and
 calculating the resolutions for drawing an image on a PDF page, taking into
 account whether to preserve the aspect ratio.
 """
-# TODO: In `rotate_image` and `get_image_dimensions`, `BytesIO` is used to wrap the image stream. While necessary for PIL, consider if the `image_stream` is already a file-like object in some calling contexts, which could avoid redundant copying to `BytesIO`.
-# TODO: The `rotate_image` function creates a new `BytesIO` object and saves the image to it. For multiple rotations or image manipulations, consider keeping the `PIL.Image.Image` object in memory and performing operations on it directly before a final save to bytes, to avoid repeated I/O operations.
-# TODO: The `get_image_dimensions` function opens the image to get its size. If image dimensions are frequently needed for the same image, consider caching the dimensions to avoid re-opening and re-parsing the image data.
 
 from io import BytesIO
 from typing import Tuple, Union

PyPDFForm/middleware/__init__.py

@@ -0,0 +1,35 @@
+# -*- coding: utf-8 -*-
+"""
+The `middleware` package provides intermediate classes used internally
+to manage and manipulate PDF form widgets, abstracting away some of the
+low-level PDF details.
+
+These classes are typically used during the filling process to represent
+the state and attributes of various form field types within the PDF.
+"""
+
+from dataclasses import dataclass
+
+from .checkbox import Checkbox
+from .dropdown import Dropdown
+from .image import Image
+from .radio import Radio
+from .signature import Signature
+from .text import Text
+
+
+@dataclass
+class Widgets:
+    """
+    A container class that provides convenient access to all available middleware widget classes.
+
+    This class acts as a namespace for the various middleware classes defined in the
+    `PyPDFForm.middleware` package, making it easier to reference them (e.g., `Widgets.Text`).
+    """
+
+    Text = Text
+    Checkbox = Checkbox
+    Radio = Radio
+    Dropdown = Dropdown
+    Signature = Signature
+    Image = Image

PyPDFForm/middleware/base.py

@@ -8,7 +8,7 @@ common attributes and methods for all form widgets, such as name, value,
 and schema definition.
 """
 
-from typing import Any
+from typing import Any, List, TextIO, Union
 
 
 class Widget:
@@ -25,6 +25,12 @@ class Widget:
         "readonly": "flatten_generic",
         "required": "update_field_required",
         "tooltip": "update_field_tooltip",
+        "on_hovered_over_javascript": "update_field_on_hovered_over_javascript",
+        "on_hovered_off_javascript": "update_field_on_hovered_off_javascript",
+        "on_mouse_pressed_javascript": "update_field_on_mouse_pressed_javascript",
+        "on_mouse_released_javascript": "update_field_on_mouse_released_javascript",
+        "on_focused_javascript": "update_field_on_focused_javascript",
+        "on_blurred_javascript": "update_field_on_blurred_javascript",
     }
 
     def __init__(
@@ -42,12 +48,25 @@ class Widget:
         super().__init__()
         self._name = name
         self._value = value
-        self.desc: str = None
-        self.tooltip: str = None  # TODO: sync tooltip and desc
+        self.tooltip: str = None
         self.readonly: bool = None
         self.required: bool = None
         self.hooks_to_trigger: list = []
 
+        # coordinate & dimension
+        self.x: Union[float, List[float]] = None
+        self.y: Union[float, List[float]] = None
+        self.width: Union[float, List[float]] = None
+        self.height: Union[float, List[float]] = None
+
+        # javascript
+        self.on_hovered_over_javascript: Union[str, TextIO] = None
+        self.on_hovered_off_javascript: Union[str, TextIO] = None
+        self.on_mouse_pressed_javascript: Union[str, TextIO] = None
+        self.on_mouse_released_javascript: Union[str, TextIO] = None
+        self.on_focused_javascript: Union[str, TextIO] = None
+        self.on_blurred_javascript: Union[str, TextIO] = None
+
     def __setattr__(self, name: str, value: Any) -> None:
         """
         Set an attribute on the widget.
@@ -107,8 +126,8 @@ class Widget:
         """
         result = {}
 
-        if self.desc is not None:
-            result["description"] = self.desc
+        if self.tooltip is not None:
+            result["description"] = self.tooltip
 
         return result
 

PyPDFForm/middleware/checkbox.py

@@ -6,7 +6,7 @@ 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
+from typing import Any, Union
 
 from .base import Widget
 
@@ -44,6 +44,23 @@ class Checkbox(Widget):
 
         self.size: float = None
 
+    def __setattr__(self, name: str, value: Any) -> None:
+        """
+        Custom attribute setter for the Checkbox class.
+
+        If the attribute being set is 'size', it sets both 'width' and 'height'
+        attributes of the widget to the given value, ensuring the checkbox remains
+        square. For all other attributes, it defers to the parent class's setter.
+
+        Args:
+            name (str): The name of the attribute to set.
+            value (Any): The value to set for the attribute.
+        """
+        if name == "size":
+            super().__setattr__("width", value)
+            super().__setattr__("height", value)
+        super().__setattr__(name, value)
+
     @property
     def schema_definition(self) -> dict:
         """

PyPDFForm/middleware/signature.py

@@ -6,7 +6,6 @@ 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.
 """
-# TODO: In the `stream` property, `fp_or_f_obj_or_stream_to_stream` is called every time the property is accessed. If the signature image is large or the property is accessed frequently, consider caching the result of `fp_or_f_obj_or_stream_to_stream` to avoid redundant file reads.
 
 from os.path import expanduser
 from typing import Union

PyPDFForm/patterns.py

@@ -7,19 +7,15 @@ checkboxes, radio buttons, dropdowns, images, and signatures) based on their
 properties in the PDF's annotation dictionary. It also provides utility functions
 for updating these widgets.
 """
-# TODO: The `WIDGET_TYPE_PATTERNS` list is iterated through to determine widget types. For very large numbers of annotations or complex pattern matching, consider optimizing this lookup, perhaps by pre-compiling regexes or using a more efficient data structure if the patterns allow.
-# TODO: In `update_checkbox_value` and `update_radio_value`, iterating through `annot[AP][N]` to find the correct appearance state might be slow if `N` contains many entries. If possible, a direct lookup or a more optimized search could improve performance.
-# TODO: In `update_dropdown_value`, the list comprehension for `ArrayObject` can be computationally intensive for dropdowns with many choices, as it creates new `TextStringObject` and `ArrayObject` instances for each choice. Consider optimizing this if dropdowns have a very large number of options.
-# TODO: The `get_checkbox_value` and `get_radio_value` functions involve dictionary lookups and comparisons. While generally fast, repeated calls in a tight loop for many widgets could accumulate overhead.
 
-from typing import Union
+from typing import Tuple, Union
 
 from pypdf.generic import (ArrayObject, DictionaryObject, NameObject,
                            NumberObject, TextStringObject)
 
 from .constants import (AP, AS, DV, FT, IMAGE_FIELD_IDENTIFIER, JS, MULTILINE,
-                        SLASH, TU, A, Btn, Ch, Ff, I, N, Off, Opt, Parent, Sig,
-                        T, Tx, V, Yes)
+                        SLASH, TU, A, Btn, Ch, Ff, I, N, Off, Opt, Parent,
+                        Rect, Sig, T, Tx, V, Yes)
 from .middleware.checkbox import Checkbox
 from .middleware.dropdown import Dropdown
 from .middleware.image import Image
@@ -179,7 +175,9 @@ def get_radio_value(annot: DictionaryObject) -> bool:
     return False
 
 
-def update_dropdown_value(annot: DictionaryObject, widget: Dropdown) -> None:
+def update_dropdown_value(
+    annot: DictionaryObject, widget: Dropdown, need_appearances: bool
+) -> None:
     """
     Updates the value of a dropdown annotation, selecting an option from the list.
 
@@ -190,17 +188,21 @@ def update_dropdown_value(annot: DictionaryObject, widget: Dropdown) -> None:
     Args:
         annot (DictionaryObject): The dropdown annotation dictionary.
         widget (Dropdown): The Dropdown widget object containing the selected value.
+        need_appearances (bool): If True, skips updating the appearance stream (AP) to
+            maintain compatibility with Adobe Reader's behavior for certain fields.
     """
     choices = widget.choices or []
     if Parent in annot and T not in annot:
         annot[NameObject(Parent)][NameObject(V)] = TextStringObject(
             choices[widget.value]
         )
-        annot[NameObject(AP)] = TextStringObject(choices[widget.value])
+        if not need_appearances:
+            annot[NameObject(AP)] = TextStringObject(choices[widget.value])
     else:
         annot[NameObject(V)] = TextStringObject(choices[widget.value])
-        annot[NameObject(AP)] = TextStringObject(choices[widget.value])
         annot[NameObject(I)] = ArrayObject([NumberObject(widget.value)])
+        if not need_appearances:
+            annot[NameObject(AP)] = TextStringObject(choices[widget.value])
 
 
 def get_dropdown_value(annot: DictionaryObject, widget: Dropdown) -> None:
@@ -226,7 +228,9 @@ def get_dropdown_value(annot: DictionaryObject, widget: Dropdown) -> None:
             widget.value = i or None  # set None when 0
 
 
-def update_text_value(annot: DictionaryObject, widget: Text) -> None:
+def update_text_value(
+    annot: DictionaryObject, widget: Text, need_appearances: bool
+) -> None:
     """
     Updates the value of a text annotation, setting the text content.
 
@@ -236,13 +240,17 @@ def update_text_value(annot: DictionaryObject, widget: Text) -> None:
     Args:
         annot (DictionaryObject): The text annotation dictionary.
         widget (Text): The Text widget object containing the text value.
+        need_appearances (bool): If True, skips updating the appearance stream (AP) to
+            maintain compatibility with Adobe Reader's behavior for certain fields.
     """
     if Parent in annot and T not in annot:
         annot[NameObject(Parent)][NameObject(V)] = TextStringObject(widget.value)
-        annot[NameObject(AP)] = TextStringObject(widget.value)
+        if not need_appearances:
+            annot[NameObject(AP)] = TextStringObject(widget.value)
     else:
         annot[NameObject(V)] = TextStringObject(widget.value)
-        annot[NameObject(AP)] = TextStringObject(widget.value)
+        if not need_appearances:
+            annot[NameObject(AP)] = TextStringObject(widget.value)
 
 
 def get_text_value(annot: DictionaryObject, widget: Text) -> None:
@@ -304,3 +312,26 @@ def get_text_field_multiline(annot: DictionaryObject) -> bool:
             & MULTILINE
         )
     return bool(int(annot[NameObject(Ff)] if Ff in annot else 0) & MULTILINE)
+
+
+def get_field_rect(annot: DictionaryObject) -> Tuple[float, float, float, float]:
+    """
+    Retrieves the normalized rectangular bounding box of a field annotation.
+
+    The PDF 'Rect' entry contains [llx, lly, urx, ury] (lower-left x, y, upper-right x, y).
+    This function converts it to a normalized tuple of (x, y, width, height) in float format.
+
+    Args:
+        annot (DictionaryObject): The annotation dictionary containing the 'Rect' key.
+
+    Returns:
+        tuple: A tuple (x, y, width, height) representing the field's bounding box.
+    """
+    rect = annot[Rect]
+
+    return (
+        float(rect[0]),
+        float(rect[1]),
+        float(abs(rect[2] - rect[0])),
+        float(abs(rect[3] - rect[1])),
+    )

PyPDFForm/raw/__init__.py

@@ -0,0 +1,37 @@
+# -*- coding: utf-8 -*-
+"""
+The `raw` package provides classes representing raw drawable elements
+(like text and images) that can be rendered directly onto a PDF document.
+
+It defines `RawTypes` as a Union of all supported raw element types, used for
+type hinting in methods that handle drawing onto the PDF.
+"""
+
+from dataclasses import dataclass
+from typing import Union
+
+from .circle import RawCircle
+from .ellipse import RawEllipse
+from .image import RawImage
+from .line import RawLine
+from .rect import RawRectangle
+from .text import RawText
+
+RawTypes = Union[RawText, RawImage, RawLine, RawRectangle, RawCircle, RawEllipse]
+
+
+@dataclass
+class RawElements:
+    """
+    A container class that provides convenient access to all available raw drawable elements.
+
+    This class acts as a namespace for the various `Raw` classes defined in the
+    `PyPDFForm.raw` package, making it easier to reference them (e.g., `RawElements.RawText`).
+    """
+
+    RawText = RawText
+    RawImage = RawImage
+    RawLine = RawLine
+    RawRectangle = RawRectangle
+    RawCircle = RawCircle
+    RawEllipse = RawEllipse

PyPDFForm/raw/circle.py

@@ -0,0 +1,65 @@
+# -*- coding: utf-8 -*-
+"""
+Contains the RawCircle class, which represents a circle that can be drawn
+directly onto a PDF page at specified coordinates and radius.
+"""
+
+from ..constants import DEFAULT_FONT_COLOR
+
+
+class RawCircle:
+    """
+    Represents a circle object intended for direct drawing onto a specific page
+    of a PDF document at specified coordinates and radius.
+
+    This class encapsulates the necessary information (center position, radius,
+    color, and fill color) to render a circle on a PDF page.
+    """
+
+    def __init__(
+        self,
+        page_number: int,
+        center_x: float,
+        center_y: float,
+        radius: float,
+        color: tuple = DEFAULT_FONT_COLOR,
+        fill_color: tuple = None,
+    ) -> None:
+        """
+        Initializes a raw circle object for drawing.
+
+        Args:
+            page_number: The 1-based index of the page where the circle should be drawn.
+            center_x: The x-coordinate (horizontal position) of the center of the circle.
+            center_y: The y-coordinate (vertical position) of the center of the circle.
+            radius: The radius of the circle.
+            color: The color of the circle's outline as an RGB tuple (0-1 for each channel).
+            fill_color: The fill color of the circle as an RGB tuple (0-1 for each channel).
+        """
+        super().__init__()
+
+        self.page_number = page_number
+        self.center_x = center_x
+        self.center_y = center_y
+        self.radius = radius
+        self.color = color
+        self.fill_color = fill_color
+
+    @property
+    def to_draw(self) -> dict:
+        """
+        Converts the raw circle object into a dictionary format ready for drawing.
+
+        Returns:
+            A dictionary containing drawing parameters: page number, object type ("circle"),
+            center coordinates, radius, outline color, and fill color.
+        """
+        return {
+            "page_number": self.page_number,
+            "type": "circle",
+            "center_x": self.center_x,
+            "center_y": self.center_y,
+            "radius": self.radius,
+            "color": self.color,
+            "fill_color": self.fill_color,
+        }

PyPDFForm/raw/ellipse.py

@@ -0,0 +1,69 @@
+# -*- coding: utf-8 -*-
+"""
+Contains the RawEllipse class, which represents an ellipse that can be drawn
+directly onto a PDF page defined by its bounding box.
+"""
+
+from ..constants import DEFAULT_FONT_COLOR
+
+
+class RawEllipse:
+    """
+    Represents an ellipse object intended for direct drawing onto a specific page
+    of a PDF document defined by its bounding box coordinates.
+
+    This class encapsulates the necessary information (bounding box corners,
+    page number, color, and fill color) to render an ellipse on a PDF page.
+    """
+
+    def __init__(
+        self,
+        page_number: int,
+        x1: float,
+        y1: float,
+        x2: float,
+        y2: float,
+        color: tuple = DEFAULT_FONT_COLOR,
+        fill_color: tuple = None,
+    ) -> None:
+        """
+        Initializes a raw ellipse object for drawing.
+
+        Args:
+            page_number: The 1-based index of the page where the ellipse should be drawn.
+            x1: The x-coordinate of the first corner of the bounding box.
+            y1: The y-coordinate of the first corner of the bounding box.
+            x2: The x-coordinate of the second corner of the bounding box.
+            y2: The y-coordinate of the second corner of the bounding box.
+            color: The color of the ellipse's outline as an RGB tuple (0-1 for each channel).
+            fill_color: The fill color of the ellipse as an RGB tuple (0-1 for each channel).
+        """
+        super().__init__()
+
+        self.page_number = page_number
+        self.x1 = x1
+        self.y1 = y1
+        self.x2 = x2
+        self.y2 = y2
+        self.color = color
+        self.fill_color = fill_color
+
+    @property
+    def to_draw(self) -> dict:
+        """
+        Converts the raw ellipse object into a dictionary format ready for drawing.
+
+        Returns:
+            A dictionary containing drawing parameters: page number, object type ("ellipse"),
+            bounding box coordinates, outline color, and fill color.
+        """
+        return {
+            "page_number": self.page_number,
+            "type": "ellipse",
+            "x1": self.x1,
+            "y1": self.y1,
+            "x2": self.x2,
+            "y2": self.y2,
+            "color": self.color,
+            "fill_color": self.fill_color,
+        }