From 9d212a8b0eff35ba3b961ae6cc8cbc649352812b Mon Sep 17 00:00:00 2001 From: Julian Smith Date: Thu, 12 Mar 2026 14:15:55 +0000 Subject: [PATCH] docs/ src/__init__.py: improve docs for insert_textbox() methods. src/__init__.py: In Page.insert_textbox() and Shape.insert_textbox(), sort args to simplify comparison. docs/shape.rst::insert_textbox(): Use sorted multiple lines for args to simplify comparison. docs/page.rst:insert_textbox(): Use sorted multiple lines for args to simplify comparison. Describe explicitly because not in Shape.insert_textbox(). Fixed args to match the code: * Removed . * Removed . * Added . * Added . --- docs/page.rst | 31 ++++++++++++++++++++++++++++--- docs/shape.rst | 35 +++++++++++++++++++++++++++++------ src/__init__.py | 46 +++++++++++++++++++++++----------------------- 3 files changed, 80 insertions(+), 32 deletions(-) diff --git a/docs/page.rst b/docs/page.rst index b5e63d8f6..57069b81d 100644 --- a/docs/page.rst +++ b/docs/page.rst @@ -783,9 +783,34 @@ In a nutshell, this is what you can do with PyMuPDF: pair: fill_opacity; insert_textbox pair: oc; insert_textbox - .. method:: insert_textbox(rect, buffer, *, fontsize=11, fontname="helv", fontfile=None, idx=0, color=None, fill=None, render_mode=0, miter_limit=1, border_width=1, encoding=TEXT_ENCODING_LATIN, expandtabs=8, align=TEXT_ALIGN_LEFT, charwidths=None, rotate=0, morph=None, stroke_opacity=1, fill_opacity=1, oc=0, overlay=True) - - PDF only: Insert text into the specified :data:`rect_like` *rect*. See :meth:`Shape.insert_textbox`. + .. method:: insert_textbox(rect, buffer, \ + *, \ + align=TEXT_ALIGN_LEFT, \ + border_width=1, \ + color=None, \ + encoding=TEXT_ENCODING_LATIN, \ + expandtabs=8, \ + fill=None, \ + fill_opacity=1, \ + fontfile=None, \ + fontname="helv", \ + fontsize=11, \ + lineheight=None, \ + miter_limit=1, \ + morph=None, \ + oc=0, \ + overlay=True, \ + render_mode=0, \ + rotate=0, \ + set_simple=False, \ + stroke_opacity=1, \ + ) + + PDF only: Insert text into the specified :data:`rect_like` *rect*. + + :arg overlay: see :meth:`Shape.commit`. + + For other args, see `Shape.insert_textbox`. |history_begin| diff --git a/docs/shape.rst b/docs/shape.rst index c3a3cb585..c394ff294 100644 --- a/docs/shape.rst +++ b/docs/shape.rst @@ -333,8 +333,30 @@ Several draw methods can be executed in a row and each one of them will contribu pair: rotate; insert_textbox pair: oc; insert_textbox - .. method:: insert_textbox(rect, buffer, *, fontsize=11, fontname="helv", fontfile=None, set_simple=False, encoding=TEXT_ENCODING_LATIN, color=None, fill=None, render_mode=0, miter_limit=1, border_width=1, expandtabs=8, align=TEXT_ALIGN_LEFT, rotate=0, lineheight=None, morph=None, stroke_opacity=1, fill_opacity=1, oc=0) - + .. method:: insert_textbox( \ + rect, \ + buffer, \ + *, \ + align=TEXT_ALIGN_LEFT, \ + border_width=1, \ + color=None, \ + encoding=TEXT_ENCODING_LATIN, \ + expandtabs=8, \ + fill=None, \ + fill_opacity=1, \ + fontfile=None, \ + fontname="helv", \ + fontsize=11, \ + lineheight=None, \ + miter_limit=1, \ + morph=None, \ + oc=0, \ + render_mode=0, \ + rotate=0, \ + set_simple=False, \ + stroke_opacity=1, \ + ) + PDF only: Insert text into the specified rectangle. The text will be split into lines and words and then filled into the available space, starting from one of the four rectangle corners, which depends on `rotate`. Line feeds and multiple space will be respected. :arg rect_like rect: the area to use. It must be finite and not empty. @@ -343,17 +365,18 @@ Several draw methods can be executed in a row and each one of them will contribu :arg int align: align each text line. Default is 0 (left). Centered, right and justified are the other supported options, see :ref:`TextAlign`. Please note that the effect of parameter value *TEXT_ALIGN_JUSTIFY* is only achievable with "simple" (single-byte) fonts (including the :ref:`Base-14-Fonts`). - :arg float lineheight: a factor to override the line height calculated from font properties. If not `None`, a line height of `fontsize * lineheight` will be used. - :arg int expandtabs: controls handling of tab characters ``\t`` using the `string.expandtabs()` method **per each line**. - :arg float stroke_opacity: *(new in v1.18.1)* set transparency for stroke colors. Negative values and values > 1 will be ignored. Default is 1 (intransparent). :arg float fill_opacity: *(new in v1.18.1)* set transparency for fill colors. Default is 1 (intransparent). Use this value to control transparency of the text color. Stroke opacity **only** affects the border line of characters. - :arg int rotate: requests text to be rotated in the rectangle. This value must be a multiple of 90 degrees. Default is 0 (no rotation). Effectively, the four values `0`, `90`, `180` and `270` (= `-90`) are processed, each causing the text to start in a different rectangle corner. Bottom-left is `90`, bottom-right is `180`, and `-90 / 270` is top-right. See the example how text is filled in a rectangle. This argument takes precedence over morphing. See the second example, which shows text first rotated left by `90` degrees and then the whole rectangle rotated clockwise around is lower left corner. + :arg float lineheight: a factor to override the line height calculated from font properties. If not `None`, a line height of `fontsize * lineheight` will be used. :arg int oc: *(new in v1.18.4)* the :data:`xref` number of an :data:`OCG` or :data:`OCMD` to make this text conditionally displayable. + :arg int rotate: requests text to be rotated in the rectangle. This value must be a multiple of 90 degrees. Default is 0 (no rotation). Effectively, the four values `0`, `90`, `180` and `270` (= `-90`) are processed, each causing the text to start in a different rectangle corner. Bottom-left is `90`, bottom-right is `180`, and `-90 / 270` is top-right. See the example how text is filled in a rectangle. This argument takes precedence over morphing. See the second example, which shows text first rotated left by `90` degrees and then the whole rectangle rotated clockwise around is lower left corner. + + :arg float stroke_opacity: *(new in v1.18.1)* set transparency for stroke colors. Negative values and values > 1 will be ignored. Default is 1 (intransparent). + :rtype: float :returns: **If positive or zero**: successful execution. The value returned is the unused rectangle line space in pixels. This may safely be ignored -- or be used to optimize the rectangle, position subsequent items, etc. diff --git a/src/__init__.py b/src/__init__.py index 2bda40ff7..8b756ccfe 100644 --- a/src/__init__.py +++ b/src/__init__.py @@ -12620,25 +12620,25 @@ def insert_textbox( rect: rect_like, buffer: typing.Union[str, list], *, - fontname: str = "helv", - fontfile: OptStr = None, - set_simple: int = 0, + align: int = 0, + border_width: float = 0.05, + color: OptSeq = None, encoding: int = 0, + expandtabs: int = 1, + fill_opacity: float = 1, + fill: OptSeq = None, + fontfile: OptStr = None, + fontname: str = "helv", fontsize: float = 11, lineheight: OptFloat = None, - color: OptSeq = None, - fill: OptSeq = None, - expandtabs: int = 1, - align: int = 0, - rotate: int = 0, - render_mode: int = 0, miter_limit: float = 1, - border_width: float = 0.05, morph: OptSeq = None, + oc: int = 0, overlay: bool = True, + render_mode: int = 0, + rotate: int = 0, + set_simple: int = 0, stroke_opacity: float = 1, - fill_opacity: float = 1, - oc: int = 0, ) -> float: """Insert text into a given rectangle. @@ -15390,24 +15390,24 @@ def insert_textbox( rect: rect_like, buffer: typing.Union[str, list], *, - fontname: OptStr = "helv", + align: int = 0, + border_width: float = 0.05, + color: OptSeq = None, + encoding: int = 0, + expandtabs: int = 1, + fill_opacity: float = 1, + fill: OptSeq = None, fontfile: OptStr = None, + fontname: OptStr = "helv", fontsize: float = 11, lineheight: OptFloat = None, - set_simple: bool = 0, - encoding: int = 0, - color: OptSeq = None, - fill: OptSeq = None, - expandtabs: int = 1, - border_width: float = 0.05, miter_limit: float = 1, - align: int = 0, + morph: OptSeq = None, + oc: int = 0, render_mode: int = 0, rotate: int = 0, - morph: OptSeq = None, + set_simple: bool = 0, stroke_opacity: float = 1, - fill_opacity: float = 1, - oc: int = 0, ) -> float: """Insert text into a given rectangle.