Write() refactor to use new line wrapping code

CHANGELOG.md

@@ -9,11 +9,12 @@ and [PEP 440](https://www.python.org/dev/peps/pep-0440/).
 
 ## [2.5.1] - not released yet
 ### Added
-- support for soft-hyphen (`\u00ad`) break in `cell()` & `multi_cell()` calls - thanks @oleksii-shyman & @gmischler!
+- support for soft-hyphen (`\u00ad`) break in `write()`, `cell()` & `multi_cell()` calls - thanks @oleksii-shyman & @gmischler!
 - new documentation page on [Emojis, Symbols & Dingbats](https://pyfpdf.github.io/fpdf2/EmojisSymbolsDingbats.html)
 - documentation on combining `borb` & `fpdf2`: [Creating a borb.pdf.document.Document from a FPDF instance](https://pyfpdf.github.io/fpdf2/ExistingPDFs.html)
 
 ### Changed
+- `write()` now supports soft hyphen characters, thanks to @gmischler
 - `fname` is now a required parameter for `FPDF.add_font()`
 - `image()` method now insert `.svg` images as PDF paths
 - the [defusedxml](https://pypi.org/project/defusedxml/) package was added as dependency in order to make SVG parsing safer

docs/PageBreaks.md

@@ -1,7 +1,8 @@
 # Page breaks #
 
-By default, `fpdf2` will automatically perform page breaks whenever a cell is rendered at the bottom of a page
-with a height greater than the page bottom margin.
+By default, `fpdf2` will automatically perform page breaks whenever a cell or
+the text from a `write()` is rendered at the bottom of a page with a height
+greater than the page bottom margin.
 
 This behaviour can be controlled using the
 [`set_auto_page_break`](fpdf/fpdf.html#fpdf.fpdf.FPDF.set_auto_page_break)

docs/Tutorial.md

@@ -144,10 +144,10 @@ to 1 mm (against 0.2 by default) with
 [set_line_width](fpdf/fpdf.html#fpdf.fpdf.FPDF.set_line_width). Finally, we output the cell (the
 last parameter to true indicates that the background must be filled).
 
-The method used to print the paragraphs is [multi_cell](fpdf/fpdf.html#fpdf.fpdf.FPDF.multi_cell).
+The method used to print the paragraphs is [multi_cell](fpdf/fpdf.html#fpdf.fpdf.FPDF.multi_cell). Text is justified by default.
 Each time a line reaches the right extremity of the cell or a carriage return
 character is met, a line break is issued and a new cell automatically created
-under the current one. Text is justified by default.
+under the current one. An automatic break is performed at the location of the nearest space or soft-hyphen (\u00ad) character before the right limit. A soft-hyphen will be replaced by a normal hyphen when triggering a line break, and ignored otherwise.
 
 Two document properties are defined: the title 
 ([set_title](fpdf/fpdf.html#fpdf.fpdf.FPDF.set_title)) and the author 

fpdf/__init__.py

@@ -3,6 +3,8 @@
 
 from .fpdf import (
     FPDF,
+    XPos,
+    YPos,
     FPDFException,
     TitleStyle,
     FPDF_FONT_DIR as _FPDF_FONT_DIR,
@@ -39,6 +41,8 @@
     "__license__",
     # Classes
     "FPDF",
+    "XPos",
+    "YPos",
     "Template",
     "FlexTemplate",
     "TitleStyle",

fpdf/line_break.py

@@ -1,4 +1,4 @@
-from collections import namedtuple
+from typing import NamedTuple, Any, Union, Sequence
 
 SOFT_HYPHEN = "\u00ad"
 HYPHEN = "\u002d"
@@ -7,61 +7,68 @@
 
 
 class Fragment:
-    def __init__(self, style, underlined, characters=None):
+    def __init__(self, style: str, underlined: bool, characters: str = None):
         self.characters = [] if characters is None else characters
         self.style = style
         self.underline = underlined
 
     @classmethod
-    def from_string(cls, string, style, underlined):
+    def from_string(cls, string: str, style: str, underlined: bool):
         return cls(style, underlined, list(string))
 
-    def trim(self, index):
+    def trim(self, index: int):
         self.characters = self.characters[:index]
 
     @property
     def string(self):
         return "".join(self.characters)
 
-    def __eq__(self, other):
+    def __eq__(self, other: Any):
         return (
             self.characters == other.characters
             and self.style == other.style
             and self.underline == other.underline
         )
 
 
-TextLine = namedtuple(
-    "TextLine",
-    ("fragments", "text_width", "number_of_spaces_between_words", "justify"),
-)
-
-SpaceHint = namedtuple(
-    "SpaceHint",
-    (
-        "original_fragment_index",
-        "original_character_index",
-        "current_line_fragment_index",
-        "current_line_character_index",
-        "width",
-        "number_of_spaces",
-    ),
-)
-
-HyphenHint = namedtuple(
-    "HyphenHint",
-    SpaceHint._fields
-    + (
-        "character_to_append",
-        "character_to_append_width",
-        "character_to_append_style",
-        "character_to_append_underline",
-    ),
-)
+class TextLine(NamedTuple):
+    fragments: tuple
+    text_width: float
+    number_of_spaces_between_words: int
+    justify: bool
+
+
+class SpaceHint(NamedTuple):
+    original_fragment_index: int
+    original_character_index: int
+    current_line_fragment_index: int
+    current_line_character_index: int
+    width: float
+    number_of_spaces: int
+
+
+class HyphenHint(NamedTuple):
+    original_fragment_index: int
+    original_character_index: int
+    current_line_fragment_index: int
+    current_line_character_index: int
+    width: float
+    number_of_spaces: int
+    character_to_append: str
+    character_to_append_width: float
+    character_to_append_style: str
+    character_to_append_underline: bool
 
 
 class CurrentLine:
-    def __init__(self):
+    def __init__(self, print_sh: bool = False):
+        """
+        Per-line text fragment management for use by MultiLineBreak.
+            Args:
+                print_sh (bool): If true, a soft-hyphen will be rendered
+                    normally, instead of triggering a line break. Default: False
+        """
+        self.print_sh = print_sh
         self.fragments = []
         self.width = 0
         self.number_of_spaces = 0
@@ -82,12 +89,12 @@ def __init__(self):
 
     def add_character(
         self,
-        character,
-        character_width,
-        style,
-        underline,
-        original_fragment_index,
-        original_character_index,
+        character: str,
+        character_width: float,
+        style: str,
+        underline: bool,
+        original_fragment_index: int,
+        original_character_index: int,
     ):
         assert character != NEWLINE
 
@@ -115,7 +122,7 @@ def add_character(
                 self.number_of_spaces,
             )
             self.number_of_spaces += 1
-        elif character == SOFT_HYPHEN:
+        elif character == SOFT_HYPHEN and not self.print_sh:
             self.hyphen_break_hint = HyphenHint(
                 original_fragment_index,
                 original_character_index,
@@ -129,11 +136,11 @@ def add_character(
                 underline,
             )
 
-        if character != SOFT_HYPHEN:
+        if character != SOFT_HYPHEN or self.print_sh:
             self.width += character_width
             active_fragment.characters.append(character)
 
-    def _apply_automatic_hint(self, break_hint):
+    def _apply_automatic_hint(self, break_hint: Union[SpaceHint, HyphenHint]):
         """
         This function mutates the current_line, applying one of the states
         observed in the past and stored in
@@ -145,7 +152,7 @@ def _apply_automatic_hint(self, break_hint):
         self.number_of_spaces = break_hint.number_of_spaces
         self.width = break_hint.width
 
-    def manual_break(self, justify=False):
+    def manual_break(self, justify: bool = False):
         return TextLine(
             fragments=self.fragments,
             text_width=self.width,
@@ -156,7 +163,7 @@ def manual_break(self, justify=False):
     def automatic_break_possible(self):
         return self.hyphen_break_hint is not None or self.space_break_hint is not None
 
-    def automatic_break(self, justify):
+    def automatic_break(self, justify: bool):
         assert self.automatic_break_possible()
         if self.hyphen_break_hint is not None and (
             self.space_break_hint is None
@@ -185,28 +192,37 @@ def automatic_break(self, justify):
 
 
 class MultiLineBreak:
-    def __init__(self, styled_text_fragments, size_by_style, justify=False):
-
+    def __init__(
+        self,
+        styled_text_fragments: Sequence,
+        size_by_style: Sequence,
+        justify: bool = False,
+        print_sh: bool = False,
+    ):
         self.styled_text_fragments = styled_text_fragments
-
         self.size_by_style = size_by_style
         self.justify = justify
-
+        self.print_sh = print_sh
         self.fragment_index = 0
         self.character_index = 0
 
-    def _get_character_width(self, character, style=""):
-        if character == SOFT_HYPHEN:
+    def _get_character_width(self, character: str, style: str = ""):
+        if character == SOFT_HYPHEN and not self.print_sh:
             # HYPHEN is inserted instead of SOFT_HYPHEN
             character = HYPHEN
         return self.size_by_style(character, style)
 
-    def get_line_of_given_width(self, maximum_width):
+    # pylint: disable=too-many-return-statements
+    def get_line_of_given_width(self, maximum_width: float, wordsplit: bool = True):
 
         if self.fragment_index == len(self.styled_text_fragments):
             return None
 
-        current_line = CurrentLine()
+        last_fragment_index = self.fragment_index
+        last_character_index = self.character_index
+        line_full = False
+
+        current_line = CurrentLine(print_sh=self.print_sh)
         while self.fragment_index < len(self.styled_text_fragments):
 
             current_fragment = self.styled_text_fragments[self.fragment_index]
@@ -237,7 +253,10 @@ def get_line_of_given_width(self, maximum_width):
                     ) = current_line.automatic_break(self.justify)
                     self.character_index += 1
                     return line
-                return current_line.manual_break()
+                if not wordsplit:
+                    line_full = True
+                    break
+                return current_line.manual_break(self.justify)
 
             current_line.add_character(
                 character,
@@ -250,5 +269,11 @@ def get_line_of_given_width(self, maximum_width):
 
             self.character_index += 1
 
+        if line_full and not wordsplit:
+            # roll back and return empty line to trigger continuation
+            # on the next line.
+            self.fragment_index = last_fragment_index
+            self.character_index = last_character_index
+            return CurrentLine().manual_break(self.justify)
         if current_line.width:
             return current_line.manual_break()

test/end_to_end_legacy/charmap/test_charmap.py

@@ -56,7 +56,7 @@ def test_first_999_chars(font_filename, tmp_path):
 
     # Create a PDF with the first 999 charters defined in the font:
     for counter, character in enumerate(ttf.saveChar, 0):
-        pdf.write(8, f"{counter:03}) {character:03x} - {character:c}")
+        pdf.write(8, f"{counter:03}) {character:03x} - {character:c}", print_sh=True)
         pdf.ln()
         if counter >= 999:
             break

test/cells/test_cell.py → test/text/test_cell.py

@@ -155,7 +155,10 @@ def test_cell_missing_text_or_width(tmp_path):
     pdf.set_font("Times", size=16)
     with pytest.raises(ValueError) as error:
         pdf.cell()
-    assert str(error.value) == "A 'txt' parameter must be provided if 'w' is None"
+    assert (
+        str(error.value)
+        == "A 'text_line' parameter with fragments must be provided if 'w' is None"
+    )
 
 
 def test_cell_centering(tmp_path):