src/ tests/ docs/: fix Annot.get_textpage() <clip> arg.

The <clip> arg was previously ignored.

Also added documentation for Annot.get_textpage().

Author: julian-smith-artifex-com

docs/annot.rst

@@ -22,6 +22,7 @@ There is a parent-child relationship between an annotation and its page. If the
 :meth:`Annot.get_sound`            get the sound of an audio annotation
 :meth:`Annot.get_text`             extract annotation text
 :meth:`Annot.get_textbox`          extract annotation text
+:meth:`Annot.get_textpage`         create a TextPage for the annotation
 :meth:`Annot.set_border`           set annotation's border properties
 :meth:`Annot.set_blendmode`        set annotation's blend mode
 :meth:`Annot.set_colors`           set annotation's colors
@@ -134,6 +135,22 @@ There is a parent-child relationship between an annotation and its page. If the
       :arg rect-like rect: the area to consider, defaults to :attr:`Annot.rect`.
 
 
+   .. method:: get_textpage(clip=None, flags=3)
+
+      Create a :ref:`TextPage` for the annotation.
+
+      :arg int flags: indicator bits controlling the content available for subsequent text extractions and searches -- see the parameter of :meth:`Annot.get_text`.
+
+      :arg rect-like clip: restrict extracted text to this area.
+
+      :returns: :ref:`TextPage`
+
+      |history_begin|
+
+      * v1.25.5: fixed `clip` arg.
+
+      |history_end|
+
    .. method:: set_info(info=None, content=None, title=None, creationDate=None, modDate=None, subject=None)
 
       * Changed in version 1.16.10

src/__init__.py

@@ -1022,8 +1022,11 @@ def get_sound(self):
     def get_textpage(self, clip=None, flags=0):
         """Make annotation TextPage."""
         CheckParent(self)
-        options = mupdf.FzStextOptions()
-        options.flags = flags
+        options = mupdf.FzStextOptions(flags)
+        if clip:
+            clip2 = JM_rect_from_py(clip)
+            options.clip = clip2.internal()
+            options.flags |= mupdf.FZ_STEXT_CLIP_RECT
         annot = self.this
         stextpage = mupdf.FzStextPage(annot, options)
         ret = TextPage(stextpage)

tests/test_annots.py

@@ -276,6 +276,7 @@ def test_2270():
         for page_number, page in enumerate(document):
             for textBox in page.annots(types=(pymupdf.PDF_ANNOT_FREE_TEXT,pymupdf.PDF_ANNOT_TEXT)):
                 print("textBox.type :", textBox.type)
+                print(f"{textBox.rect=}")
                 print("textBox.get_text('words') : ", textBox.get_text('words'))
                 print("textBox.get_text('text') : ", textBox.get_text('text'))
                 print("textBox.get_textbox(textBox.rect) : ", textBox.get_textbox(textBox.rect))
@@ -296,6 +297,15 @@ def test_2270():
                     text = page.get_text(textpage=textpage)
                     print(f'{text=}')
                     print(f'{getattr(textpage, "parent")=}')
+                    
+                    # Check Annotation.get_textpage()'s <clip> arg.
+                    clip = textBox.rect
+                    clip.x1 = clip.x0 + (clip.x1 - clip.x0) / 3
+                    textpage2 = textBox.get_textpage(clip=clip)
+                    text = textpage2.extractText()
+                    print(f'With {clip=}: {text=}')
+                    assert text == 'ab\n'
+                    
 
 def test_2934_add_redact_annot():
     '''