Define and reuse text styles, e.g. for various title levels

[jxrossel]

Hi,

I'd like to define document-level styles for various text parts (titles, sub-titles, paragraphs, legends, ...) and use these styles consistently across the document, a bit like CSS classes in HTML.

I've seen that a class TextStyle is available to specify everything that I need for that. Is it possible to use such a TextStyle in a context manager to apply a pre-defined style only within it? Something like:

with pdf_doc.local_context(textstyle=MyTitle1Style):
    pdf_doc.cell("My title")

-- edit ---

I guess an alternative would be to not use a TextStyle, but to define a doc method, adding the local_context to what is illustrated in the tutorial (https://py-pdf.github.io/fpdf2/Tutorial.html#tuto-3-line-breaks-and-colors):

...
def chapter_title(self, num, label):
    with self.local_context():
        self.set_font("helvetica", size=12)
        self.set_fill_color(200, 220, 255)
        self.cell(
            0,
            6,
            f"Chapter {num} : {label}",
            new_x="LMARGIN",
            new_y="NEXT",
            align="L",
            fill=True,
        )
        # Performing a line break:
        self.ln(4)

Would that be the recommended approach?

Any help appreciated!

[yhay81]

local_context(textstyle=...) is not supported directly. local_context() accepts graphics-state keyword arguments such as font_family, font_style, font_size_pt, text_color, and fill_color; an unknown textstyle argument raises ValueError: Unsupported setting (API and accepted settings).

TextStyle is mainly used by the HTML/paragraph rendering APIs. For example, it is natively reusable with:

pdf.write_html(html, tag_styles={
    "h1": MyTitle1Style,
    "h2": MyTitle2Style,
})

For normal cell()/multi_cell() calls, you can make a small adapter for the font/color subset:

from fpdf import TextStyle

TITLE_1 = TextStyle(
    font_family="helvetica",
    font_style="B",
    font_size_pt=18,
    color="#203040",
    fill_color="#c8dcff",
)

def use_text_style(pdf, style: TextStyle):
    return pdf.local_context(
        font_family=style.family,
        font_style=(
            None if style.emphasis is None else style.emphasis.style
        ),
        font_size_pt=style.size_pt,
        text_color=style.color,
        fill_color=style.fill_color,
    )

with use_text_style(pdf_doc, TITLE_1):
    pdf_doc.cell(
        0, 8, "My title",
        fill=True,
        new_x="LMARGIN", new_y="NEXT",
    )

This mapping is necessary because the names on TextStyle are family, emphasis, size_pt, and color, while the corresponding local-context names are different. The class definitions are visible in fpdf/fonts.py.

There is one limitation: TextStyle.t_margin, l_margin, and b_margin are layout/paragraph properties, not PDF graphics-state properties, so the adapter above cannot apply them. Cell height, alignment, line breaks, and margins also describe how to render a title, not just its font.

For that reason, your edited chapter_title() method is the approach I would recommend for document-level semantic styles. Keep local_context() inside it so state cannot leak, and let the method own both styling and layout:

class Report(FPDF):
    def chapter_title(self, num, label):
        with self.local_context(
            font_family="helvetica",
            font_style="B",
            font_size_pt=12,
            fill_color=(200, 220, 255),
        ):
            self.cell(
                0, 6, f"Chapter {num}: {label}",
                new_x="LMARGIN", new_y="NEXT",
                align="L", fill=True,
            )
            self.ln(4)

So: use tag_styles when generating HTML, use a small adapter if you specifically want a reusable TextStyle for plain cells, and prefer semantic methods such as chapter_title() when spacing/layout are part of the style.

[jxrossel]

Thanks for the clarification and complete answer!