PPF-1707: Add a __repr__ method to the Widget base class

PyPDFForm/lib/middleware/base.py

@@ -104,6 +104,15 @@ def __setattr__(self, name: str, value: Any) -> None:
 
         super().__setattr__(name, value)
 
+    def __repr__(self) -> str:
+        _internal = {"SET_ATTR_TRIGGER_HOOK_MAP", "attr_set_tracker", "hooks_to_trigger"}
+        parts = [f"name={self._name!r}", f"value={self._value!r}"]
+        for k, v in self.__dict__.items():
+            if k.startswith("_") or k in _internal or v is None:
+                continue
+            parts.append(f"{k}={v!r}")
+        return f"{self.__class__.__name__}({', '.join(parts)})"
+
     @property
     def name(self) -> str:
         """

docs/index.md

@@ -40,6 +40,8 @@ Here's a quick look at how PyPDFForm works:
     from pprint import pprint
 
     pprint(pdf.schema)
+
+    pprint(pdf.widgets)
     ```
 === "Style"
     ```python

docs/inspect.md

@@ -69,6 +69,31 @@ To inspect the current filled data of a PDF form, use the `.data` attribute. For
     'test_3': 'test3'}
     ```
 
+## Inspect individual form field widgets
+
+The `.widgets` attribute gives you a dictionary mapping each field name to its widget object. Each widget exposes properties such as `name`, `value`, `page_number`, `x`, `y`,`width`,`height`,`tooltip`,`readonly`,`required`, and`hidden`.
+
+You can iterate over all widgets to see their types and current state:
+
+=== "Code"
+    ```python
+    from pprint import pprint
+    from PyPDFForm import PdfWrapper
+
+    pdf = PdfWrapper("sample_template.pdf")
+
+    pprint(pdf.widgets)
+    ```
+=== "Output"
+    ```sh
+   {'check': Checkbox(name='check', value=None, readonly=False, required=False, hidden=False, page_number=1, x=358.874, y=664.717, width=18.47999999999996, height=18.480000000000018),
+ 'check_2': Checkbox(name='check_2', value=None, readonly=False, required=False, hidden=False, page_number=2, x=349.637, y=673.954, width=18.478999999999985, height=18.480000000000018),
+ 'check_3': Checkbox(name='check_3', value=None, readonly=False, required=False, hidden=False, page_number=3, x=349.305, y=667.344, width=18.480000000000018, height=18.479999999999905),
+ 'test': Text(name='test', value=None, readonly=False, required=False, hidden=False, page_number=1, x=73.3365, y=662.692, width=232.4235, height=21.067999999999984, comb=False, multiline=False),
+ 'test_2': Text(name='test_2', value=None, readonly=False, required=False, hidden=False, page_number=2, x=71.4095, y=671.626, width=232.42350000000005, height=21.067999999999984, comb=False, multiline=False),
+ 'test_3': Text(name='test_3', value=None, readonly=False, required=False, hidden=False, page_number=3, x=70.5919, y=665.349, width=232.42309999999998, height=21.067999999999984, comb=False, multiline=False)}
+    ```
+
 ## Generate sample data
 
 PyPDFForm can also generate sample data for filling a PDF form:

tests/doc_examples/lib/test_inspect.py

@@ -23,6 +23,14 @@ def test_schema(static_pdfs):
     }
 
 
+def test_widgets(static_pdfs):
+    pdf_widgets =repr(PdfWrapper(
+        os.path.join(static_pdfs, "sample_template.pdf")
+    ).widgets)
+
+    assert pdf_widgets ==  "{'test': Text(name='test', value=None, readonly=False, required=False, hidden=False, page_number=1, x=73.3365, y=662.692, width=232.4235, height=21.067999999999984, comb=False, multiline=False), 'check': Checkbox(name='check', value=None, readonly=False, required=False, hidden=False, page_number=1, x=358.874, y=664.717, width=18.47999999999996, height=18.480000000000018), 'test_2': Text(name='test_2', value=None, readonly=False, required=False, hidden=False, page_number=2, x=71.4095, y=671.626, width=232.42350000000005, height=21.067999999999984, comb=False, multiline=False), 'check_2': Checkbox(name='check_2', value=None, readonly=False, required=False, hidden=False, page_number=2, x=349.637, y=673.954, width=18.478999999999985, height=18.480000000000018), 'test_3': Text(name='test_3', value=None, readonly=False, required=False, hidden=False, page_number=3, x=70.5919, y=665.349, width=232.42309999999998, height=21.067999999999984, comb=False, multiline=False), 'check_3': Checkbox(name='check_3', value=None, readonly=False, required=False, hidden=False, page_number=3, x=349.305, y=667.344, width=18.480000000000018, height=18.479999999999905)}"
+
+
 def test_data(static_pdfs):
     assert PdfWrapper(os.path.join(static_pdfs, "sample_template_filled.pdf")).data == {
         "check": True,

tests/test_extract_middleware_attributes.py

@@ -3,6 +3,8 @@
 import os
 
 from PyPDFForm import PdfWrapper
+from PyPDFForm.lib.middleware.checkbox import Checkbox
+from PyPDFForm.lib.middleware.text import Text
 
 
 def test_text_check_values(pdf_samples, data_dict):
@@ -157,6 +159,82 @@ def test_text_field_comb(max_length_expected_directory):
     assert obj.widgets["LastName"].comb
 
 
+def test_widget_repr_text(template_stream):
+    obj = PdfWrapper(template_stream)
+    widget = obj.widgets["test"]
+    result = repr(widget)
+
+    assert result.startswith("Text(")
+    assert "comb=False" in result
+    assert "height=" in result
+    assert "hidden=False" in result
+    assert "multiline=False" in result
+    assert "name='test'" in result
+    assert "page_number=1" in result
+    assert "readonly=False" in result
+    assert "required=False" in result
+    assert "value=None" in result
+    assert "width=" in result
+    assert "x=" in result
+    assert "y=" in result
+
+    # None-valued optional attributes should be omitted
+    assert "font=" not in result
+    assert "font_size=" not in result
+    # internal attrs should be omitted
+    assert "SET_ATTR_TRIGGER_HOOK_MAP" not in result
+    assert "attr_set_tracker" not in result
+    assert "hooks_to_trigger" not in result
+
+
+def test_widget_repr_checkbox(template_stream):
+    obj = PdfWrapper(template_stream)
+    widget = obj.widgets["check"]
+    result = repr(widget)
+
+    assert result.startswith("Checkbox(")
+    assert "name='check'" in result
+    assert "value=None" in result
+    assert "SET_ATTR_TRIGGER_HOOK_MAP" not in result
+
+
+def test_widget_repr_includes_non_none_attrs():
+    widget = Text("my_field")
+    widget.font_size = 12.0
+    widget.readonly = True
+    result = repr(widget)
+
+    assert "font_size=12.0" in result
+    assert "readonly=True" in result
+    assert "font=" not in result
+
+
+def test_widget_repr_checkbox_includes_size():
+    widget = Checkbox("my_check")
+    widget.size = 20.0
+    result = repr(widget)
+
+    assert result.startswith("Checkbox(")
+    assert "width=20.0" in result
+    assert "height=20.0" in result
+
+
+def test_widget_repr_value_shown_when_set():
+    widget = Text("field_name", value="hello")
+    result = repr(widget)
+
+    assert "name='field_name'" in result
+    assert "value='hello'" in result
+
+
+def test_widget_repr_all_fields_in_widgets(template_stream):
+    obj = PdfWrapper(template_stream)
+    for name, widget in obj.widgets.items():
+        result = repr(widget)
+        assert f"name={name!r}" in result
+        assert "value=" in result
+
+
 def test_text_field_comb_sejda(pdf_samples):
     obj = PdfWrapper(
         os.path.join(