35@dataclasses.dataclass(frozen=True, kw_only=True, slots=True)
36class Alias(_LabelPathABC):
37    """Alias."""
38
39    name: str
40    """The name of the alias."""
41
42    label_path: tuple[str, ...]
43    """The label path of the alias."""
44
45    def __repr__(self) -> str:
46        return (
47            f"{type(self).__name__}"
48            f"(#{self.name:s} -> {self.joined_label_path!r:s})"
49        )

72@dataclasses.dataclass(kw_only=True, slots=True)
73class CrossReference(_LabelPathABC):
74    """Cross Reference."""
75
76    id: int
77    """The id of the cross reference."""
78
79    type: CrossReferenceType
80    """The type of the cross reference."""
81
82    label_path: tuple[str, ...]
83    """The label path the cross reference points to."""
84
85    location: LinkLocation | None = dataclasses.field(default=None, init=False)
86    """The (link) location in the document the cross reference is set at."""
87
88    def __str__(self) -> str:
89        return f"{self.type.capitalize():s} {self.joined_label_path:s}"
90
91    def __repr__(self) -> str:
92        return f"{type(self).__name__}('{self!s:s}')"
93
94    @property
95    def link(self) -> str:
96        """The link in the document that must be set in the text index to lead
97        from the text to the text index.
98        """
99        return f"{const.INDEX_ID_PREFIX:s}{self.id:d}"

102class CrossReferenceType(str, enum.Enum):
103    """Cross Reference Type."""
104
105    NONE = "none"
106    """No cross reference."""
107
108    SEE = "see"
109    """SEE-cross reference."""
110
111    ALSO = "see also"
112    """SEE ALSO-cross reference."""
113
114    def __str__(self) -> str:
115        return self.value
116
117    @classmethod
118    def _missing_(cls, value: Any) -> Self | None:  # noqa: ANN401
119        if value is None:
120            return cls.NONE
121        if isinstance(value, str):
122            return cls(value.upper())
123        return None

 52class FPDF(fpdf.FPDF):
 53    """PDF Generation Class."""
 54
 55    if TYPE_CHECKING:
 56        _index_allow_page_insertion: bool
 57        _index_links: dict[str, int]
 58        _index_parser: TextIndexParser
 59        index_placeholder: IndexPlaceholder | None
 60
 61    CONCORDANCE_FILE: os.PathLike[str] | str | None = None
 62    """The path to a concordance file. Defaults to `None`."""
 63
 64    STRICT_INDEX_MODE: bool = True
 65    """If `True` and an entry has a normal reference (locator) and a SEE-cross
 66    reference, a `ValueError` will be raised. Else, it will just be a warning.
 67    Defaults to `True`.
 68    """
 69
 70    def __init__(
 71        self,
 72        orientation: PageOrientation | str = PageOrientation.PORTRAIT,
 73        unit: str | float = "mm",
 74        format: str | tuple[float, float] = "A4",
 75        font_cache_dir: Literal["DEPRECATED"] = "DEPRECATED",
 76        *,
 77        enforce_compliance: DocumentCompliance | str | None = None,
 78    ) -> None:
 79        """Initializes the :py:class:`FPDF`.
 80
 81        Args:
 82            orientation: Page orientation. Possible values are `"portrait"` (can
 83                be abbreviated `"P"`) or `"landscape"` (can be abbreviated
 84                `"L"`). Defaults to `"portrait"`.
 85            unit: Possible values are `"pt"`, `"mm"`, `"cm"`, `"in"`, or a
 86                number. A point equals 1/72 of an inch, that is to say about
 87                0.35 mm (an inch being 2.54 cm). This is a very common unit in
 88                typography; font sizes are expressed in this unit.
 89                If given a number, then it will be treated as the number of
 90                points per unit (eg. 72 = 1 in). Default to `"mm"`.
 91            format: Page format. Possible values are `"a3"`, `"a4"`, `"a5"`,
 92                `"letter"`, `"legal"` or a tuple `(width, height)` expressed in
 93                the given unit. Default to `"a4"`.
 94            font_cache_dir: [**DEPRECATED since v2.5.1**] unused.
 95            enforce_compliance: When enforce compliance is set, :py:class:`FPDF`
 96                actively prevents non-compliant operations and will raise errors
 97                if you try something forbidden for the selected profile.
 98                Defaults to `None`.
 99        """
100        super().__init__(
101            orientation=orientation,
102            unit=unit,
103            format=format,
104            font_cache_dir=font_cache_dir,
105            enforce_compliance=enforce_compliance,
106        )
107        self._concordance_list = None
108        if self.CONCORDANCE_FILE is not None:
109            self._concordance_list = ConcordanceList.from_file(
110                self.CONCORDANCE_FILE
111            )
112        self._index_allow_page_insertion = False
113        self._index_links = {}
114        self._index_parser = TextIndexParser(strict=self.STRICT_INDEX_MODE)
115        self.index_placeholder: IndexPlaceholder | None = None
116        """Index placeholder. Defaults to ``None``."""
117
118    def _set_index_link_locations(self) -> None:
119        link_locations = {}
120
121        # Collect index locations
122        for page_num, pdf_page in self.pages.items():
123            if pdf_page.annots is None:
124                continue
125
126            h_page = pdf_page.dimensions()[1] / self.k
127            for a in pdf_page.annots:
128                link_name = str(a.dest)
129                if not (
130                    link_name.startswith(const.INDEX_ID_PREFIX)
131                    or link_name.startswith(const.ENTRY_ID_PREFIX)
132                ):
133                    continue
134                assert a.rect.startswith("[") and a.rect.endswith("]"), a.rect
135                x, y_h, x_w, y = map(
136                    lambda x: float(x) / self.k,
137                    a.rect[1:-1].split(" ", maxsplit=3),
138                )
139                w = x_w - x
140                h = y - y_h
141                y = h_page - y
142                link_locations[link_name] = LinkLocation(
143                    page=page_num, x=x, y=y, w=w, h=h
144                )
145
146        # Add link locations to entries
147        for entry in self._index_parser.entries:
148            for ref in entry.references:
149                ref.start_location = link_locations[ref.start_link]
150                if ref.end_link:
151                    ref.end_location = link_locations[ref.end_link]
152            for cross_ref in entry.cross_references:
153                cross_ref.location = link_locations[cross_ref.link]
154
155    def _insert_index(self) -> None:
156        # NOTE: Text Index reuses functionality of ToC
157
158        # Collect links locations and add them to entries
159        self._set_index_link_locations()
160
161        # Doc has been closed but we want to write to self.pages[self.page]
162        # instead of self.buffer:
163        indexp = self.index_placeholder
164        assert indexp is not None
165        prev_page, prev_y = self.page, self.y
166        prev_toc_placeholder = self.toc_placeholder
167        prev_toc_allow_page_insertion = self._toc_allow_page_insertion
168
169        self.page, self.y = indexp.start_page, indexp.y
170        self.toc_placeholder = fpdf.fpdf.ToCPlaceholder(
171            lambda pdf, outlines: None,
172            indexp.start_page,
173            indexp.y,
174            indexp.page_orientation,
175            pages=indexp.pages,
176            reset_page_indices=indexp.reset_page_indices,
177        )
178        self._toc_allow_page_insertion = self._index_allow_page_insertion
179        # flag rendering ToC for page breaking function
180        self.in_toc_rendering = True
181        # Reset toc inserted counter to 0
182        self._toc_inserted_pages = 0
183        self._set_orientation(indexp.page_orientation, self.dw_pt, self.dh_pt)
184        indexp.render_function(self, self._index_parser.entries)
185        self.in_toc_rendering = False  # set ToC rendering flag off
186        expected_final_page = indexp.start_page + indexp.pages - 1
187        if (
188            self.page != expected_final_page
189            and not self._index_allow_page_insertion
190        ):
191            too = "many" if self.page > expected_final_page else "few"
192            error_msg = (
193                f"The rendering function passed to "
194                f"'FPDF.insert_index_placeholder' triggered too {too:s} page "
195                f"breaks: ToC ended on page {self.page:d} while it was "
196                f"expected to span exactly {indexp.pages:d} pages"
197            )
198            raise fpdf.errors.FPDFException(error_msg)
199        if self._toc_inserted_pages:
200            # Generating final page footer after more pages were inserted:
201            self._render_footer()
202            # We need to reorder the pages, because some new pages have been
203            # inserted in the Index, but they have been inserted at the end of
204            # self.pages:
205            new_pages = [
206                self.pages.pop(len(self.pages))
207                for _ in range(self._toc_inserted_pages)
208            ]
209            new_pages = list(reversed(new_pages))
210            indices_remap: dict[int, int] = {}
211            for page_index in range(
212                indexp.start_page + 1, self.pages_count + len(new_pages) + 1
213            ):
214                if page_index in self.pages:
215                    new_pages.append(self.pages.pop(page_index))
216                page = self.pages[page_index] = new_pages.pop(0)
217                # Fix page indices:
218                indices_remap[page.index()] = page_index
219                page.set_index(page_index)
220                # Fix page labels:
221                if indexp.reset_page_indices is False:
222                    page.get_page_label().st = page_index  # type: ignore[union-attr]
223            assert len(new_pages) == 0, f"#new_pages: {len(new_pages)}"
224            # Fix links:
225            for dest in self.links.values():
226                assert dest.page_number is not None
227                new_index = indices_remap.get(dest.page_number)
228                if new_index is not None:
229                    dest.page_number = new_index
230            # Fix outline:
231            for section in self._outline:
232                new_index = indices_remap.get(section.page_number)
233                if new_index is not None:
234                    section.dest = section.dest.replace(page=new_index)
235                    section.page_number = new_index
236                    if section.struct_elem:
237                        # pylint: disable=protected-access
238                        section.struct_elem._page_number = (  # pyright: ignore[reportPrivateUsage]
239                            new_index
240                        )
241            # Fix resource catalog:
242            resources_per_page = self._resource_catalog.resources_per_page
243            new_resources_per_page: dict[
244                tuple[int, PDFResourceType], set[ResourceTypes]
245            ] = defaultdict(set)
246            for (
247                page_number,
248                resource_type,
249            ), resource in resources_per_page.items():
250                key = (
251                    indices_remap.get(page_number, page_number),
252                    resource_type,
253                )
254                new_resources_per_page[key] = resource
255            self._resource_catalog.resources_per_page = new_resources_per_page
256
257        self._toc_allow_page_insertion = prev_toc_allow_page_insertion
258        self._toc_inserted_pages = 0
259        self.toc_placeholder = prev_toc_placeholder
260        self.page, self.y = prev_page, prev_y
261
262    def _preload_font_styles(
263        self,
264        text: str | None,
265        markdown: bool,
266    ) -> Sequence[Fragment]:
267        """Preloads the font styles by markdown parsing.
268
269        When Markdown styling is enabled, we require secondary fonts to
270        render text in bold & italics. This function ensure that those fonts are
271        available. It needs to perform Markdown parsing, so we return the
272        resulting `styled_txt_frags` tuple to avoid repeating this processing
273        later on.
274
275        Args:
276            text: The text to parse the markdown of.
277            markdown: Whether markdown is enabled.
278
279        Returns:
280            The preloaded text fragments.
281        """
282        if not self.in_toc_rendering and text and markdown:
283            # Load concordance list if not done in init
284            if (
285                self.CONCORDANCE_FILE is not None
286                and self._concordance_list is None
287            ):
288                self._concordance_list = ConcordanceList.from_file(
289                    self.CONCORDANCE_FILE
290                )
291            # Replace concordance entries by entry annotations
292            if self._concordance_list:
293                text = self._concordance_list.parse_text(text)
294            # Replace entry annotations by markdown link
295            first_id = self._index_parser.last_directive_id + 1
296            text = self._index_parser.parse_text(text)
297            last_id = self._index_parser.last_directive_id + 1
298            # Reserve the links (named destinations)
299            for text_to_index_id in range(first_id, last_id):
300                link_name = f"{const.INDEX_ID_PREFIX:s}{text_to_index_id:d}"
301                link_idx = self.add_link(name=link_name)
302                self._index_links[link_name] = link_idx
303        return super()._preload_font_styles(text, markdown)
304
305    @property
306    def index_entries(self) -> list[TextIndexEntry]:
307        """The (so far parsed) index entries."""
308        return self._index_parser.entries
309
310    def add_index_entry(
311        self,
312        label_path: Iterable[str],
313        sort_key: str | None = None,
314    ) -> TextIndexEntry:
315        """Adds manually a text index entry.
316
317        Note: References (locators) to pages cannot be added manually, only
318            cross references.
319
320        Args:
321            label_path: The label path of the entry.
322            sort_key: The sort key of the entry. Defaults to `None`.
323
324        Returns:
325            The text index entry.
326        """
327        entry = self._index_parser.entry_at_label_path(label_path, create=True)
328        assert isinstance(entry, TextIndexEntry)
329        entry.sort_key = sort_key
330        return entry
331
332    @fpdf.fpdf.check_page
333    def insert_index_placeholder(
334        self,
335        render_index_function: Callable[["FPDF", list[TextIndexEntry]], None],
336        *,
337        pages: int = 1,
338        allow_extra_pages: bool = False,
339        reset_page_indices: bool = True,
340    ) -> None:
341        """Configures Text Index rendering at the end of the document
342        generation, and reserves some vertical space right now in order to
343        insert it. At least one page break is triggered by this method.
344
345        Args:
346            render_index_function: A function that will be invoked to  render
347                the Index. This function will receive 2 parameters:
348                    `pdf`: an instance of :py:class:`fpdf2_textindex.pdf.FPDF`;
349                    `entries`: a list of
350                        :py:class:`fpdf2_textindex.interface.TextIndexEntry`s.
351            pages: The number of pages that the Index will span, including the
352                current one. As many page breaks as the value of this argument
353                will occur immediately after calling this method. Defaults to
354                `1`.
355            allow_extra_pages: If set to `True`, allows for an unlimited
356                number of extra pages in the Text Index, which may cause
357                discrepancies with pre-rendered page numbers.
358                For consistent numbering, using page labels to create a separate
359                numbering style for the Index is recommended. Defaults to
360                `False`.
361            reset_page_indices : Whether to reset the pages indices after the
362                Text Index. Defaults to `True`.
363
364        Raises:
365            FPDFException: If an index placeholder has been inserted before.
366            TypeError: If `render_index_function` is not callable.
367            ValueError: If ``pages`` is less than `1`.
368        """
369        if not callable(render_index_function):
370            msg = (
371                f"The first argument must be a callable, got: "
372                f"{type(render_index_function)!s:s}"
373            )
374            raise TypeError(msg)
375        if pages < 1:
376            msg = (
377                f"'pages' parameter must be equal or greater than 1: {pages:d}"
378            )
379            raise ValueError(msg)
380        if self.index_placeholder:
381            msg = (
382                "A placeholder for the index has already been defined on page "
383                f"{self.index_placeholder.start_page}"
384            )
385            raise fpdf.errors.FPDFException(msg)
386        self.index_placeholder = IndexPlaceholder(
387            render_index_function,
388            self.page,
389            self.y,
390            self.cur_orientation,
391            pages,
392            reset_page_indices,
393        )
394        self._index_allow_page_insertion = allow_extra_pages
395        for _ in range(pages):
396            self._perform_page_break()
397
398    @fpdf.fpdf.check_page
399    @fpdf.deprecation.support_deprecated_txt_arg
400    def multi_cell(
401        self,
402        w: float,
403        h: float | None = None,
404        text: str = "",
405        border: Literal[0, 1] | str = 0,
406        align: Align | str = Align.J,
407        fill: bool = False,
408        split_only: bool = False,  # DEPRECATED
409        link: int | str | None = None,
410        ln: Literal["DEPRECATED"] = "DEPRECATED",
411        max_line_height: float | None = None,
412        markdown: bool = False,
413        print_sh: bool = False,
414        new_x: XPos | str = XPos.RIGHT,
415        new_y: YPos | str = YPos.NEXT,
416        wrapmode: WrapMode = WrapMode.WORD,
417        dry_run: bool = False,
418        output: MethodReturnValue | str = MethodReturnValue.PAGE_BREAK,
419        center: bool = False,
420        padding: Padding | Sequence[int] | int = 0,
421        first_line_indent: float = 0,
422    ) -> fpdf.FPDF.MultiCellResult:
423        r"""This method allows printing text with line breaks.
424
425        They can be automatic (breaking at the most recent space or soft-hyphen
426        character) as soon as the text reaches the right border of the cell, or
427        explicit (via the `"\\n"` character). As many cells as necessary are
428        stacked, one below the other. Text can be aligned, centered or
429        justified. The cell block can be framed and the background painted. A
430        cell has an horizontal padding, on the left & right sides, defined by
431        the
432        [:py:attr:`fpdf.FPDF.c_margin`](https://py-pdf.github.io/fpdf2/fpdf/fpdf.html)-property.
433
434        Note:
435            Using
436            `new_x=XPos.RIGHT, new_y=XPos.TOP, maximum height=pdf.font_size`
437            is useful to build tables with multiline text in cells.
438
439        Args:
440            w: Cell width. If `0`, they extend up to the right margin of the
441                page.
442            h: Height of a single line of text. Defaults to `None`, meaning to
443                use the current font size.
444            text: Text to print.
445            border: Indicates if borders must be drawn around the cell.
446                The value can be either a number (`0`: no border; `1`:
447                frame) or a string containing some or all of the following
448                characters (in any order):
449                `"L"`: left,
450                `"T"`: top,
451                `"R"`: right,
452                `"B"`: bottom.
453                Defaults to `0`.
454            align: Sets the text alignment inside the cell.
455                Possible values are:
456                `"J"`: justify (default value),
457                `"L"` / `""`: left align,
458                `"C"`: center,
459                `"X"`: center around current x-position, or
460                `"R"`: right align.
461            fill: Indicates if the cell background must be painted (`True`)
462                or transparent (`False`). Defaults to `False`.
463            split_only: **DEPRECATED since 2.7.4**: Use `dry_run=True` and
464                `output=("LINES",)` instead.
465            link: Optional link to add on the cell, internal (identifier
466                returned by [:py:meth:`fpdf.FPDF.add_link`](https://py-pdf.github.io/fpdf2/fpdf/fpdf.html#fpdf.fpdf.FPDF.add_link)
467                or external URL.
468            new_x: New current position in x after the call. Defaults to
469                [:py:attr:`fpdf.XPos.RIGHT`](https://py-pdf.github.io/fpdf2/fpdf/enums.html#fpdf.enums.XPos).
470            new_y: New current position in y after the call. Defaults to
471                [:py:attr:`fpdf.YPos.NEXT`](https://py-pdf.github.io/fpdf2/fpdf/enums.html#fpdf.enums.YPos).
472            ln: **DEPRECATED since 2.5.1**: Use `new_x` and `new_y` instead.
473            max_line_height: Optional maximum height of each sub-cell generated.
474                Defaults to `None`.
475            markdown: Enables minimal markdown-like markup to render part
476                of text as bold / italics / strikethrough / underlined.
477                Supports `"\\"` as escape character. Defaults to `False`.
478            print_sh: Treat a soft-hyphen (`"\\u00ad"`) as a normal printable
479                character, instead of a line breaking opportunity. Defaults to
480                `False`.
481            wrapmode: [:py:attr:`fpdf.enums.WrapMode.WORD`](https://py-pdf.github.io/fpdf2/fpdf/enums.html#fpdf.enums.WrapMode)
482                for word based line wrapping (default) or
483                [:py:attr:`fpdf.enums.WrapMode.CHAR`](https://py-pdf.github.io/fpdf2/fpdf/enums.html#fpdf.enums.WrapMode)
484                for character based line wrapping.
485            dry_run: If `True`, does not output anything in the document.
486                Can be useful when combined with `output`. Defaults to
487                `False`.
488            output: Defines what this method returns. If several enum values are
489                joined, the result will be a tuple.
490            txt: [**DEPRECATED since v2.7.6**] string to print.
491            center: Center the cell horizontally on the page. Defaults to
492                `False`.
493            padding: Padding to apply around the text. Defaults to `0`.
494                When one value is specified, it applies the same padding to all
495                four sides.
496                When two values are specified, the first padding applies to the
497                top and bottom, the second to the left and right.
498                When three values are specified, the first padding applies to
499                the top, the second to the right and left, the third to the
500                bottom.
501                When four values are specified, the paddings apply to the top,
502                right, bottom, and left in that order (clockwise)
503                If padding for left or right ends up being non-zero then the
504                respective [:py:attr:`fpdf.FPDF.c_margin`](https://py-pdf.github.io/fpdf2/fpdf/fpdf.html)
505                is ignored. Center overrides values for horizontal padding.
506            first_line_indent: The indent of the first line. Defaults to `0`.
507
508        Returns:
509            A single value or a tuple, depending on the `output` parameter
510            value.
511
512        Raises:
513            FPDFException: If no font has been set before.
514            ValueError: If `w` or `h` is a string.
515        """  # noqa: DOC102
516        padding = Padding.new(padding)
517        wrapmode = WrapMode.coerce(wrapmode)
518
519        if split_only:
520            warnings.warn(
521                (
522                    'The parameter "split_only" is deprecated since v2.7.4.'
523                    ' Use instead dry_run=True and output="LINES".'
524                ),
525                DeprecationWarning,
526                stacklevel=fpdf.deprecation.get_stack_level(),
527            )
528        if dry_run or split_only:
529            with self._disable_writing():
530                return self.multi_cell(
531                    w=w,
532                    h=h,
533                    text=text,
534                    border=border,
535                    align=align,
536                    fill=fill,
537                    link=link,
538                    ln=ln,
539                    max_line_height=max_line_height,
540                    markdown=markdown,
541                    print_sh=print_sh,
542                    new_x=new_x,
543                    new_y=new_y,
544                    wrapmode=wrapmode,
545                    dry_run=False,
546                    split_only=False,
547                    output=MethodReturnValue.LINES if split_only else output,
548                    center=center,
549                    padding=padding,
550                    # CHANGE
551                    first_line_indent=first_line_indent,
552                )
553        if not self.font_family:
554            raise fpdf.errors.FPDFException(
555                "No font set, you need to call set_font() beforehand"
556            )
557        if isinstance(w, str) or isinstance(h, str):
558            raise ValueError(
559                "Parameter 'w' and 'h' must be numbers, not strings."
560                " You can omit them by passing string content with text="
561            )
562        new_x = XPos.coerce(new_x)
563        new_y = YPos.coerce(new_y)
564        if ln != "DEPRECATED":
565            # For backwards compatibility, if "ln" is used we overwrite
566            # "new_[xy]".
567            if ln == 0:
568                new_x = XPos.RIGHT
569                new_y = YPos.NEXT
570            elif ln == 1:
571                new_x = XPos.LMARGIN
572                new_y = YPos.NEXT
573            elif ln == 2:
574                new_x = XPos.LEFT
575                new_y = YPos.NEXT
576            elif ln == 3:
577                new_x = XPos.RIGHT
578                new_y = YPos.TOP
579            else:
580                raise ValueError(
581                    f'Invalid value for parameter "ln" ({ln}),'
582                    " must be an int between 0 and 3."
583                )
584            warnings.warn(
585                (
586                    f'The parameter "ln" is deprecated since v2.5.2.'
587                    f" Instead of ln={ln} use new_x=XPos.{new_x.name}, "
588                    f"new_y=YPos.{new_y.name}."
589                ),
590                DeprecationWarning,
591                stacklevel=fpdf.errors.get_stack_level(),
592            )
593        align = Align.coerce(align)
594
595        page_break_triggered = False
596
597        if h is None:
598            h = self.font_size
599
600        # If width is 0, set width to available width between margins
601        if w == 0:
602            w = self.w - self.r_margin - self.x
603
604        # Store the starting position before applying padding
605        prev_x, prev_y = self.x, self.y
606
607        # Apply padding to contents
608        # decrease maximum allowed width by padding
609        # shift the starting point by padding
610        maximum_allowed_width = w = w - padding.right - padding.left
611        clearance_margins: list[float] = []
612        # If we don't have padding on either side, we need a clearance margin.
613        if not padding.left:
614            clearance_margins.append(self.c_margin)
615        if not padding.right:
616            clearance_margins.append(self.c_margin)
617        if align != Align.X:
618            self.x += padding.left
619        self.y += padding.top
620
621        # Center overrides padding
622        if center:
623            self.x = (
624                self.w / 2
625                if align == Align.X
626                else self.l_margin + (self.epw - w) / 2
627            )
628            prev_x = self.x
629
630        # Calculate text length
631        text = self.normalize_text(text)
632        normalized_string = text.replace("\r", "")
633        styled_text_fragments = (
634            self._preload_bidirectional_text(normalized_string, markdown)
635            if self.text_shaping
636            else self._preload_font_styles(normalized_string, markdown)
637        )
638
639        prev_current_font = self.current_font
640        prev_font_style = self.font_style
641        prev_underline = self.underline
642        total_height: float = 0
643
644        text_lines: list[TextLine] = []
645        multi_line_break = MultiLineBreak(
646            styled_text_fragments,
647            maximum_allowed_width,
648            clearance_margins,
649            align=align,
650            print_sh=print_sh,
651            wrapmode=wrapmode,
652            # CHANGE
653            first_line_indent=first_line_indent,
654        )
655        text_line = multi_line_break.get_line()
656        while (text_line) is not None:
657            text_lines.append(text_line)
658            text_line = multi_line_break.get_line()
659
660        if (
661            not text_lines
662        ):  # ensure we display at least one cell - cf. issue #349
663            text_lines = [
664                TextLine(
665                    [],
666                    text_width=0,
667                    number_of_spaces=0,
668                    align=align,
669                    height=h,
670                    max_width=w,
671                    trailing_nl=False,
672                )
673            ]
674
675        if max_line_height is None or len(text_lines) == 1:
676            line_height = h
677        else:
678            line_height = min(h, max_line_height)
679
680        box_required = fill or border
681        page_break_triggered = False
682
683        for text_line_index, text_line in enumerate(text_lines):
684            start_of_new_page = self._perform_page_break_if_need_be(
685                h + padding.bottom
686            )
687            if start_of_new_page:
688                page_break_triggered = True
689                self.y += padding.top
690            # CHANGE
691            if text_line_index == 0:
692                self.x += first_line_indent
693            # END CHANGE
694
695            if box_required and (text_line_index == 0 or start_of_new_page):
696                # estimate how many cells can fit on this page
697                top_gap = self.y  # Top padding has already been added
698                bottom_gap = padding.bottom + self.b_margin
699                lines_before_break = int(
700                    (self.h - top_gap - bottom_gap) // line_height
701                )
702                # check how many cells should be rendered
703                num_lines = min(
704                    lines_before_break, len(text_lines) - text_line_index
705                )
706                box_height = max(
707                    h - text_line_index * line_height, num_lines * line_height
708                )
709                # render the box
710                x = self.x - (w / 2 if align == Align.X else 0)
711                draw_box_borders(
712                    self,
713                    x - padding.left,
714                    self.y - padding.top,
715                    # CHANGE
716                    x + w + padding.right + max(0, -first_line_indent),
717                    # END CHANGE
718                    self.y + box_height + padding.bottom,
719                    border,
720                    self.fill_color if fill else None,
721                )
722            is_last_line = text_line_index == len(text_lines) - 1
723            self._render_styled_text_line(
724                text_line,
725                h=line_height,
726                new_x=new_x if is_last_line else XPos.LEFT,
727                new_y=new_y if is_last_line else YPos.NEXT,
728                border=0,  # already rendered
729                fill=False,  # already rendered
730                link=link,
731                padding=Padding(0, padding.right, 0, padding.left),
732                prevent_font_change=markdown,
733            )
734            total_height += line_height
735            if not is_last_line and align == Align.X:
736                # prevent cumulative shift to the left
737                self.x = prev_x
738            # CHANGE
739            if text_line_index == 0:
740                self.x -= first_line_indent
741            # END CHANGE
742
743        if total_height < h:
744            # Move to the bottom of the multi_cell
745            if new_y == YPos.NEXT:
746                self.y += h - total_height
747            total_height = h
748
749        if page_break_triggered and new_y == YPos.TOP:
750            # When a page jump is performed and the requested y is TOP,
751            # pretend we started at the top of the text block on the new page.
752            # cf. test_multi_cell_table_with_automatic_page_break
753            prev_y = self.y
754
755        last_line = text_lines[-1]
756        if (
757            last_line
758            and last_line.trailing_nl
759            and new_y in (YPos.LAST, YPos.NEXT)
760        ):
761            # The line renderer can't handle trailing newlines in the text.
762            self.ln()
763
764        if new_y == YPos.TOP:  # We may have jumped a few lines -> reset
765            self.y = prev_y
766        elif new_y == YPos.NEXT:  # move down by bottom padding
767            self.y += padding.bottom
768
769        if markdown:
770            self.font_style = prev_font_style
771            self.current_font = prev_current_font
772            self.underline = prev_underline
773
774        if (
775            new_x == XPos.RIGHT
776        ):  # move right by right padding to align outer RHS edge
777            self.x += padding.right
778        elif (
779            new_x == XPos.LEFT
780        ):  # move left by left padding to align outer LHS edge
781            self.x -= padding.left
782
783        output = MethodReturnValue.coerce(output)
784        return_value = ()
785        if output & MethodReturnValue.PAGE_BREAK:
786            return_value += (page_break_triggered,)  # type: ignore[assignment]
787        if output & MethodReturnValue.LINES:
788            output_lines: list[str] = []
789            for text_line in text_lines:
790                characters: list[str] = []
791                for frag in text_line.fragments:
792                    characters.extend(frag.characters)
793                output_lines.append("".join(characters))
794            return_value += (output_lines,)  # type: ignore[assignment]
795        if output & MethodReturnValue.HEIGHT:
796            return_value += (total_height + padding.top + padding.bottom,)  # type: ignore[assignment]
797        if len(return_value) == 1:
798            return return_value[0]
799        return return_value  # type: ignore[return-value]
800
801    @overload
802    def output(  # type: ignore[overload-overlap]
803        self,
804        name: Literal[""] | None = "",
805        *,
806        linearize: bool = False,
807        output_producer_class: type[OutputProducer] = OutputProducer,
808    ) -> bytearray: ...
809
810    @overload
811    def output(
812        self,
813        name: os.PathLike[str] | str | BinaryIO,
814        *,
815        linearize: bool = False,
816        output_producer_class: type[OutputProducer] = OutputProducer,
817    ) -> None: ...
818
819    def output(
820        self,
821        name: os.PathLike[str] | BinaryIO | str | Literal[""] | None = "",
822        *,
823        linearize: bool = False,
824        output_producer_class: type[OutputProducer] = OutputProducer,
825    ) -> bytearray | None:
826        """Output PDF to some destination.
827
828        By default the bytearray buffer is returned.
829        If a `name` is given, the PDF is written to a new file.
830
831        Args:
832            name: Optional file object or file path where to save the PDF under.
833                Defaults to `""`.
834            linearize: Whether to use the
835                :py:class:`fpdf.output.LinearizedOutputProducer`. Defaults to
836                `False`.
837            output_producer_class: Use a custom class for PDF file generation.
838                Defaults to :py:class:`fpdf.output.OutputProducer`.
839
840        Returns:
841            If a `name` is given, the PDF will be written to a new file and
842            `None` will be returned. Else, a bytearray buffer is returned,
843            comprising the PDF.
844
845        Raises:
846            PDFAComplianceError: If the compliance requires at least one
847                embedded file.
848        """
849        # Clear cache of cached functions to free up memory after output
850        get_unicode_script.cache_clear()
851        # Finish document if necessary:
852        if not self.buffer:
853            if self.page == 0:
854                self.add_page()
855            # Generating final page footer:
856            self._render_footer()
857            # Generating .buffer based on .pages:
858            if self.toc_placeholder:
859                self._insert_table_of_contents()
860            # CHANGE
861            if self.index_placeholder:
862                self._insert_index()
863            # CHANGE
864            if self.str_alias_nb_pages:
865                for page in self.pages.values():
866                    for substitution_item in page.get_text_substitutions():
867                        page.contents = page.contents.replace(  # type: ignore[union-attr]
868                            substitution_item.get_placeholder_string().encode(
869                                "latin-1"
870                            ),
871                            substitution_item.render_text_substitution(
872                                str(self.pages_count)
873                            ).encode("latin-1"),
874                        )
875            for _, font in self.fonts.items():
876                if isinstance(font, TTFFont) and font.color_font:
877                    font.color_font.load_glyphs()
878            if self._compliance and self._compliance.profile == "PDFA":
879                if len(self._output_intents) == 0:
880                    self.add_output_intent(
881                        OutputIntentSubType.PDFA,
882                        output_condition_identifier="sRGB",
883                        output_condition="IEC 61966-2-1:1999",
884                        registry_name="http://www.color.org",
885                        dest_output_profile=PDFICCProfile(
886                            contents=builtin_srgb2014_bytes(),
887                            n=3,
888                            alternate="DeviceRGB",
889                        ),
890                        info="sRGB2014 (v2)",
891                    )
892                if (
893                    self._compliance.part == 4
894                    and self._compliance.conformance == "F"
895                    and len(self.embedded_files) == 0
896                ):
897                    msg = (
898                        f"{self._compliance.label} requires at least one "
899                        "embedded file"
900                    )
901                    raise fpdf.errors.PDFAComplianceError(msg)
902            if linearize:
903                output_producer_class = LinearizedOutputProducer
904            output_producer = output_producer_class(self)
905            self.buffer = output_producer.bufferize()
906        if name:
907            if isinstance(name, (str, os.PathLike)):
908                pathlib.Path(name).write_bytes(self.buffer)
909            else:
910                name.write(self.buffer)
911            return None
912        return self.buffer