python-pptx2 2.13.0__py3-none-any.whl

pptx2/text/layout.py

@@ -0,0 +1,374 @@
+"""Objects related to layout of rendered text, such as TextFitter."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from PIL import ImageFont
+
+if TYPE_CHECKING:
+    from pptx2.util import Length
+
+
+class TextFitter(tuple):
+    """Value object that knows how to fit text into given rectangular extents."""
+
+    def __new__(cls, line_source, extents, font_file):
+        width, height = extents
+        return tuple.__new__(cls, (line_source, width, height, font_file))
+
+    @classmethod
+    def best_fit_font_size(
+        cls, text: str, extents: tuple[Length, Length], max_size: int, font_file: str | None
+    ) -> int | None:
+        """Return whole-number best fit point size less than or equal to `max_size`.
+
+        The return value is the largest whole-number point size less than or equal to
+        `max_size` that allows `text` to fit completely within `extents` when rendered
+        using font defined in `font_file`.  Returns ``None`` when even 1pt overflows the
+        extents — callers are expected to surface that as an error (see
+        :meth:`TextFrame._best_fit_font_size`).
+        """
+        line_source = _LineSource(text)
+        text_fitter = cls(line_source, extents, font_file)
+        return text_fitter._best_fit_font_size(max_size)
+
+    def _best_fit_font_size(self, max_size: int) -> int | None:
+        """
+        Return the largest whole-number point size less than or equal to
+        *max_size* that this fitter can fit, or ``None`` when no size fits.
+        """
+        predicate = self._fits_inside_predicate
+        sizes = _BinarySearchTree.from_ordered_sequence(range(1, int(max_size) + 1))
+        return sizes.find_max(predicate)
+
+    def _break_line(self, line_source, point_size):
+        """
+        Return a (line, remainder) pair where *line* is the longest line in
+        *line_source* that will fit in this fitter's width and *remainder* is
+        a |_LineSource| object containing the text following the break point.
+        """
+        lines = _BinarySearchTree.from_ordered_sequence(line_source)
+        predicate = self._fits_in_width_predicate(point_size)
+        return lines.find_max(predicate)
+
+    def _fits_in_width_predicate(self, point_size):
+        """
+        Return a function taking a text string value and returns |True| if
+        that text fits in this fitter when rendered at *point_size*. Used as
+        predicate for _break_line()
+        """
+
+        def predicate(line):
+            """
+            Return |True| if *line* fits in this fitter when rendered at
+            *point_size*.
+            """
+            cx = _rendered_size(line.text, point_size, self._font_file)[0]
+            return cx <= self._width
+
+        return predicate
+
+    @property
+    def _fits_inside_predicate(self):
+        """Return  function taking an integer point size argument.
+
+        The function returns |True| if the text in this fitter can be wrapped to fit
+        entirely within its extents when rendered at that point size.
+        """
+
+        def predicate(point_size):
+            """Return |True| when text in `line_source` can be wrapped to fit.
+
+            Fit means text can be broken into lines that fit entirely within `extents`
+            when rendered at `point_size` using the font defined in `font_file`.
+            """
+            text_lines = self._wrap_lines(self._line_source, point_size)
+            if text_lines is None:
+                # No whole word fits in the available width at this point
+                # size; treat as "doesn't fit" so the search continues to
+                # smaller sizes rather than crashing.  Returning ``None``
+                # is the explicit no-fit signal from ``_wrap_lines`` /
+                # ``_break_line``.
+                return False
+            # Use the bigger of (Pillow ink-box height) and (1.2× the
+            # point-size baseline) per line.  Pillow's getbbox on ``"Ty"``
+            # returns the *ink box* — descenders and ascender margins
+            # included, but not line leading — which under-estimates the
+            # vertical space a wrapped line actually occupies in
+            # PowerPoint / LibreOffice (where leading bumps each line to
+            # roughly 1.2× the point size).  The pre-fix predicate
+            # accepted 72pt wrapping to 2 lines inside a 2-inch box
+            # because 2 × ink-box ≈ 1.6 inches; the rendered layout
+            # actually consumed 2.4 inches and overflowed.  See
+            # IMPROVEMENTS item 7.
+            ink_cy = _rendered_size("Ty", point_size, self._font_file)[1]
+            leading_cy = int(point_size * 1.2 * 914400 / 72.0)
+            cy = max(ink_cy, leading_cy)
+            return (cy * len(text_lines)) <= self._height
+
+        return predicate
+
+    @property
+    def _font_file(self):
+        return self[3]
+
+    @property
+    def _height(self):
+        return self[2]
+
+    @property
+    def _line_source(self):
+        return self[0]
+
+    @property
+    def _width(self):
+        return self[1]
+
+    def _wrap_lines(self, line_source, point_size):
+        """
+        Return a sequence of str values representing the text in
+        *line_source* wrapped within this fitter when rendered at
+        *point_size*.
+
+        Returns ``None`` when no whole word from *line_source* fits in
+        the available width at *point_size* (``_break_line`` returns
+        ``None``), signalling "no-fit" to callers without raising.
+        """
+        result = self._break_line(line_source, point_size)
+        if result is None:
+            return None
+        text, remainder = result
+        lines = [text]
+        if remainder:
+            sub = self._wrap_lines(remainder, point_size)
+            if sub is None:
+                return None
+            lines.extend(sub)
+        return lines
+
+
+class _BinarySearchTree(object):
+    """
+    A node in a binary search tree. Uniform for root, subtree root, and leaf
+    nodes.
+    """
+
+    def __init__(self, value):
+        self._value = value
+        self._lesser = None
+        self._greater = None
+
+    def find_max(self, predicate, max_=None):
+        """
+        Return the largest item in or under this node that satisfies
+        *predicate*.
+        """
+        if predicate(self.value):
+            max_ = self.value
+            next_node = self._greater
+        else:
+            next_node = self._lesser
+        if next_node is None:
+            return max_
+        return next_node.find_max(predicate, max_)
+
+    @classmethod
+    def from_ordered_sequence(cls, iseq):
+        """
+        Return the root of a balanced binary search tree populated with the
+        values in iterable *iseq*.
+        """
+        seq = list(iseq)
+        # optimize for usually all fits by making longest first
+        bst = cls(seq.pop())
+        bst._insert_from_ordered_sequence(seq)
+        return bst
+
+    def insert(self, value):
+        """
+        Insert a new node containing *value* into this tree such that its
+        structure as a binary search tree is preserved.
+        """
+        side = "_lesser" if value < self.value else "_greater"
+        child = getattr(self, side)
+        if child is None:
+            setattr(self, side, _BinarySearchTree(value))
+        else:
+            child.insert(value)
+
+    def tree(self, level=0, prefix=""):
+        """
+        A string representation of the tree rooted in this node, useful for
+        debugging purposes.
+        """
+        text = "%s%s\n" % (prefix, self.value.text)
+        prefix = "%s└── " % ("    " * level)
+        if self._lesser:
+            text += self._lesser.tree(level + 1, prefix)
+        if self._greater:
+            text += self._greater.tree(level + 1, prefix)
+        return text
+
+    @property
+    def value(self):
+        """
+        The value object contained in this node.
+        """
+        return self._value
+
+    @staticmethod
+    def _bisect(seq):
+        """
+        Return a (medial_value, greater_values, lesser_values) 3-tuple
+        obtained by bisecting sequence *seq*.
+        """
+        if len(seq) == 0:
+            return [], None, []
+        mid_idx = int(len(seq) / 2)
+        mid = seq[mid_idx]
+        greater = seq[mid_idx + 1 :]
+        lesser = seq[:mid_idx]
+        return mid, greater, lesser
+
+    def _insert_from_ordered_sequence(self, seq):
+        """
+        Insert the new values contained in *seq* into this tree such that
+        a balanced tree is produced.
+        """
+        if len(seq) == 0:
+            return
+        mid, greater, lesser = self._bisect(seq)
+        self.insert(mid)
+        self._insert_from_ordered_sequence(greater)
+        self._insert_from_ordered_sequence(lesser)
+
+
+class _LineSource(object):
+    """
+    Generates all the possible even-word line breaks in a string of text,
+    each in the form of a (line, remainder) 2-tuple where *line* contains the
+    text before the break and *remainder* the text after as a |_LineSource|
+    object. Its boolean value is |True| when it contains text, |False| when
+    its text is the empty string or whitespace only.
+    """
+
+    def __init__(self, text):
+        self._text = text
+
+    def __bool__(self):
+        """
+        Gives this object boolean behaviors (in Python 3). bool(line_source)
+        is False if it contains the empty string or whitespace only.
+        """
+        return self._text.strip() != ""
+
+    def __eq__(self, other):
+        return self._text == other._text
+
+    def __iter__(self):
+        """
+        Generate a (text, remainder) pair for each possible even-word line
+        break in this line source, where *text* is a str value and remainder
+        is a |_LineSource| value.
+        """
+        words = self._text.split()
+        for idx in range(1, len(words) + 1):
+            line_text = " ".join(words[:idx])
+            remainder_text = " ".join(words[idx:])
+            remainder = _LineSource(remainder_text)
+            yield _Line(line_text, remainder)
+
+    def __nonzero__(self):
+        """
+        Gives this object boolean behaviors (in Python 2). bool(line_source)
+        is False if it contains the empty string or whitespace only.
+        """
+        return self._text.strip() != ""
+
+    def __repr__(self):
+        return "<_LineSource('%s')>" % self._text
+
+
+class _Line(tuple):
+    """
+    A candidate line broken at an even word boundary from a string of text,
+    and a |_LineSource| value containing the text that remains after the line
+    is broken at this spot.
+    """
+
+    def __new__(cls, text, remainder):
+        return tuple.__new__(cls, (text, remainder))
+
+    def __gt__(self, other):
+        return len(self.text) > len(other.text)
+
+    def __lt__(self, other):
+        return not self.__gt__(other)
+
+    def __len__(self):
+        return len(self.text)
+
+    def __repr__(self):
+        return "'%s' => '%s'" % (self.text, self.remainder)
+
+    @property
+    def remainder(self):
+        return self[1]
+
+    @property
+    def text(self):
+        return self[0]
+
+
+class _Fonts(object):
+    """
+    A memoizing cache for ImageFont objects.
+    """
+
+    fonts = {}
+
+    @classmethod
+    def font(cls, font_path, point_size):
+        key = (font_path, point_size)
+        if key not in cls.fonts:
+            cls.fonts[key] = cls._load(font_path, point_size)
+        return cls.fonts[key]
+
+    @staticmethod
+    def _load(font_path, point_size):
+        if font_path is None:
+            # `font_path=None` opts in to Pillow's bundled default font; this
+            # is the fallback when no matching system font can be located, so
+            # `TextFrame.fit_text` works on platforms without the requested
+            # family installed (notably most Linux runtimes).
+            try:
+                return ImageFont.load_default(size=point_size)
+            except TypeError:
+                # Pillow < 10.1 does not accept a `size` argument; fall back
+                # to the unsized bitmap default. Less accurate but at least
+                # never blows up.
+                return ImageFont.load_default()
+        return ImageFont.truetype(font_path, point_size)
+
+
+def _rendered_size(text, point_size, font_file):
+    """
+    Return a (width, height) pair representing the size of *text* in English
+    Metric Units (EMU) when rendered at *point_size* in the font defined in
+    *font_file*.
+    """
+    emu_per_inch = 914400
+    px_per_inch = 72.0
+
+    font = _Fonts.font(font_file, point_size)
+    try:
+        px_width, px_height = font.getsize(text)
+    except AttributeError:
+        left, top, right, bottom = font.getbbox(text)
+        px_width, px_height = right - left, bottom - top
+
+    emu_width = int(px_width / px_per_inch * emu_per_inch)
+    emu_height = int(px_height / px_per_inch * emu_per_inch)
+
+    return emu_width, emu_height