Doc: getting rid of usage examples of FPDF.set_font(font, style, size…

…) with positional arguments
py-pdf · Nov 20, 2024 · 86ce6d0 · 86ce6d0
1 parent 056a2a5
commit 86ce6d0
Show file tree

Hide file tree

Showing 56 changed files with 155 additions and 142 deletions.
diff --git a/docs/CombineWithPdfrw.md b/docs/CombineWithPdfrw.md
@@ -38,7 +38,7 @@ from pdfrw import PdfReader
 
 pdf = FPDF()
 pdf.add_page()
-pdf.set_font('times', 'B', 19)
+pdf.set_font('times', style='B', size=19)
 pdf.text(50, 10, 'Hello World!')
 
 reader = PdfReader(io.BytesIO(pdf.output()))

diff --git a/docs/CombineWithPypdf.md b/docs/CombineWithPypdf.md
@@ -29,7 +29,7 @@ from pypdf import PdfReader
 
 pdf = FPDF()
 pdf.add_page()
-pdf.set_font('times', 'B', 19)
+pdf.set_font('times', style='B', size=19)
 pdf.text(50, 10, 'Hello World!')
 
 reader = PdfReader(io.BytesIO(pdf.output()))

diff --git a/docs/FAQ.md b/docs/FAQ.md
@@ -78,13 +78,13 @@ def get_me_a_pdf():
 
     pdf = FPDF()
     pdf.add_page()
-    pdf.set_font('Times', 'B', 15)
+    pdf.set_font('Times', style='B', size=15)
     pdf.cell(w=210, h=9, text=title, border=0,
             new_x="LMARGIN", new_y="NEXT", align='C', fill=False)
-    pdf.set_font('Times', 'B', 15)
+    pdf.set_font('Times', style='B', size=15)
     pdf.cell(w=0, h=6, text=heading, border=0,
             new_x="LMARGIN", new_y="NEXT", align='L', fill=False)
-    pdf.set_font('Times', '', 12)
+    pdf.set_font('Times', style='', size=12)
     pdf.multi_cell(w=0, h=5, text=text)
     response.headers['Content-Type'] = 'application/pdf'
     return pdf.output()

diff --git a/docs/TextColumns.md b/docs/TextColumns.md
@@ -65,9 +65,9 @@ pdf.set_font("Helvetica", size=16)
 
 with pdf.text_columns(text_align="J", ncols=3, gutter=5) as cols:
     cols.write(text=LOREM_IPSUM[:600])
-    pdf.set_font("Times", "", 18)
+    pdf.set_font("Times", size=18)
     cols.write(text=LOREM_IPSUM[:500])
-    pdf.set_font("Courier", "", 20)
+    pdf.set_font("Courier", size=20)
     cols.write(text=LOREM_IPSUM[:500])
 ```
 ![Three Text Columns](tcols-three.png)
@@ -87,7 +87,7 @@ pdf.set_font("Times", size=12)
 cols = pdf.text_columns(text_align="J", ncols=3, gutter=5, balance=True)
 # fill columns with balanced text
 with cols:
-    pdf.set_font("Times", "", 14)
+    pdf.set_font("Times", size=14)
     cols.write(text=LOREM_IPSUM[:300])
 # add an image below
 img_info = pdf.image(".../fpdf2/docs/regular_polygon.png",

diff --git a/docs/TextStyling.md b/docs/TextStyling.md
@@ -35,7 +35,7 @@ The example shows the same text justified to the same width, with stretching val
 ```python
 pdf = FPDF()
 pdf.add_page()
-pdf.set_font("Helvetica", "", 8)
+pdf.set_font("Helvetica", size=8)
 pdf.set_fill_color(255, 255, 0)
 pdf.multi_cell(w=50, text=LOREM_IPSUM[:100], new_x="LEFT", fill=True)
 pdf.ln()
@@ -57,7 +57,7 @@ The example shows the same text justified to the same width, with char_spacing v
 ```python
 pdf = FPDF()
 pdf.add_page()
-pdf.set_font("Helvetica", "", 8)
+pdf.set_font("Helvetica", size=8)
 pdf.set_fill_color(255, 255, 0)
 pdf.multi_cell(w=150, text=LOREM_IPSUM[:200], new_x="LEFT", fill=True)
 pdf.ln()
@@ -109,7 +109,7 @@ The example shows the most common use cases:
 ```python
     pdf = fpdf.FPDF()
     pdf.add_page()
-    pdf.set_font("Helvetica", "", 20)
+    pdf.set_font("Helvetica", size=20)
     pdf.write(text="2")
     pdf.char_vpos = "SUP"
     pdf.write(text="56")

diff --git a/docs/Transparency.md b/docs/Transparency.md
@@ -5,7 +5,7 @@ can be controlled through `stroke_opacity` (for lines) & `fill_opacity` (for all
 
 ```python
 pdf = FPDF()
-pdf.set_font("Helvetica", "B", 24)
+pdf.set_font("Helvetica", style="B", size=24)
 pdf.set_line_width(1.5)
 pdf.add_page()
 

diff --git a/docs/Tutorial-bn.md b/docs/Tutorial-bn.md
@@ -36,7 +36,7 @@ pdf = FPDF(orientation="P", unit="mm", format="A4")
 নতুবা ডকুমেন্ট টা অকার্যকর হয়ে যাবে। আমরা Helvetica bold 16 পছন্দ করলামঃ 
 
 ```python
-pdf.set_font('helvetica', 'B', 16)
+pdf.set_font('Helvetica', style='B', size=16)
 ```
 
 ইটালিক সেট করতে চাইলে `I`, আন্ডারলাইন করতে চাইলে `U` অথবা একটি সাধারণ ফন্টে একটি খালি স্ট্রিং 

diff --git a/docs/Tutorial-de.md b/docs/Tutorial-de.md
@@ -32,7 +32,7 @@ Bevor wir Text hinzufügen können, müssen wir zuerst mit [`set_font`](fpdf/fpd
 Wir wählen Helvetica, fett in Schriftgröße 16 pt:
 
 ```python
-pdf.set_font('helvetica', 'B', 16)
+pdf.set_font('Helvetica', style='B', size=16)
 ```
 
 Anstelle von `B` hätten wir mit `I` kursiv , `U` unterstichen oder durch die Übergabe einer leeren Zeichenkette einen "normale" Textstil wählen können. Beliebige Kombinationen der drei Werte sind zulässig. Beachte, dass die Schriftgröße in Punkt und nicht in Millimetern (oder einer anderen durch den Benutzer bei der Erstellung mit `unit=` festgelegten Maßeinheit) angegeben wird. 

diff --git a/docs/Tutorial-es.md b/docs/Tutorial-es.md
@@ -36,7 +36,7 @@ Antes de que podamos imprimir texto, es obligatorio seleccionar una fuente con
 Elegimos helvetica en negrita 16: 
 
 ```python
-pdf.set_font('helvetica', 'B', 16)
+pdf.set_font('Helvetica', style='B', size=16)
 ```
 
 Podríamos haber especificado cursiva con `I`, subrayado con `U` o fuente regular 

diff --git a/docs/Tutorial-fr.md b/docs/Tutorial-fr.md
@@ -30,7 +30,7 @@ Avant de pouvoir afficher du texte, il faut obligatoirement choisir une police d
 Choisissons Helvetica bold 16 :
 
 ```python
-pdf.set_font('helvetica', 'B', 16)
+pdf.set_font('Helvetica', style='B', size=16)
 ```
 
 On aurait pu spécifier une police en italique avec `I`, soulignée avec `U` ou une police normale avec une chaine de caractères vide. Il est aussi possible de combiner les effets en combinant les caractères. Notez que la taille des caractères est à spécifier en points (pts), pas en millimètres (ou tout autre unité). C'est la seule exception.

diff --git a/docs/Tutorial-gr.md b/docs/Tutorial-gr.md
@@ -27,7 +27,7 @@ pdf = FPDF(orientation="P", unit="mm", format="A4")
 Πρωτού μπορέσουμε να εκτυπώσουμε κείμενο, είναι υποχρεωτικό να επιλέξουμε γραμματοσειρά με [set_font](fpdf/fpdf.html#fpdf.fpdf.FPDF.set_font), αλλιώς το αρχείο δεν θα είναι έγκυρο. Επιλέγουμε τη γραμματοσειρά Helvetica bold 16:
 
 ```python
-pdf.set_font('helvetica', 'B', 16)
+pdf.set_font('Helvetica', style='B', size=16)
 ```
 
 Μπορούμε να επιλέξουμε πλάγια γραφή με `I`, υπογράμμιση με `U` η μία απλή γραμματοσειρά με μία κενή συμβολοσειρά (ή οποιονδήποτε συνδιασμό). Αξίζει να σημειωθεί ότι το μέγεθος της γραμματοσειράς δίνεται σε σημεία, όχι χιλιοστόμετρα (ή κάποια άλλη μονάδα μέτρησης). Το παραπάνω αποτελεί τη μοναδική εξαίρεση. Οι υπόλοιπες ενσωματωμένες γραμματοσείρες είναι `Times`, `Courier`, `Symbol` and `ZapfDingbats`.

diff --git a/docs/Tutorial-he.md b/docs/Tutorial-he.md
@@ -31,7 +31,7 @@ pdf = FPDF(orientation="P", unit="mm", format="A4")
 לפני שנוכל להדפיס טקסט, חובה לבחור גופן בעזרת [set_font](fpdf/fpdf.html#fpdf.fpdf.FPDF.set_font), אחרת המסמך לא יהיה תקין. אנחנו בוחרים בגופן helvetica מודגש בגודל 16:
 
 ```python
-pdf.set_font('helvetica', 'B', 16)
+pdf.set_font('Helvetica', style='B', size=16)
 ```
 
 יכולנו לבחור הטייה עם `I`, קו תחתון עם `U`, או גופן רגיל עם מחרוזת ריקה (או כל שילוב של הנ"ל). שימו לב שגודל הגופן הוא בנקודות ולא מילימטרים או כל יחידת מידה אחרת. זה יוצא הדופן היחיד. הגופנים המובנים האחרים הם `Times`, `Courier`, `Symbol`, `ZapfDingbats`.

diff --git a/docs/Tutorial-hi.md b/docs/Tutorial-hi.md
@@ -36,7 +36,7 @@ pdf = FPDF(orientation="P", unit="mm", format="A4")
 हम Helvetica bold 16 चुनते हैं:
 
 ```python
-pdf.set_font('helvetica', 'B', 16)
+pdf.set_font('Helvetica', style='B', size=16)
 ```
 
 हम `I` के साथ इटैलिक (Italic) निर्दिष्ट कर सकते हैं, `U` के साथ रेखांकित (Underlined) निर्दिष्ट कर सकते हैं या एक नियमित फ़ॉन्ट

diff --git a/docs/Tutorial-id.md b/docs/Tutorial-id.md
@@ -36,7 +36,7 @@ Sebelum kita dapat mencetak teks, penting untuk memilih font dengan
 Kita pilih font Helvetica dengan ketebalan 16:
 
 ```python
-pdf.set_font('helvetica', 'B', 16)
+pdf.set_font('Helvetica', style='B', size=16)
 ```
 
 Kita dapat menentukan font _italic_ dengan `I`, bergaris bawah dengan `U`, atau jenis font reguler 

diff --git a/docs/Tutorial-it.md b/docs/Tutorial-it.md
@@ -33,7 +33,7 @@ Prima di poter stampare del testo, è obbligatorio selezionare un font con
 Scegliamo Helvetica bold 16:
 
 ```python
-pdf.set_font('helvetica', 'B', 16)
+pdf.set_font('Helvetica', style='B', size=16)
 ```
 
 Avremmo potuto scegliere il corsivo con `I`, sottolineato con `U` o un font regolare lasciando la stringa vuota (o ogni combinazione). Notare che la dimensione dei caratteri è specificata in punti, non millimetri (o altre unità di misura); questa è l'unica eccezione.

diff --git a/docs/Tutorial-ja.md b/docs/Tutorial-ja.md
@@ -35,7 +35,7 @@ PDFを横向き(`L`)に設定したり、他のページサイズ(`Letter`, `Leg
 フォントを選択する必要があります。今回はHelvetica bold 16 を選択します。
 
 ```python
-pdf.set_font('helvetica', 'B', 16)
+pdf.set_font('Helvetica', style='B', size=16)
 ```
 
 `I`で斜体、`U`で下線、空文字列で通常のフォント（または任意の組み合わせ）を指定することができます。

diff --git a/docs/Tutorial-km.md b/docs/Tutorial-km.md
@@ -35,7 +35,7 @@ pdf = FPDF(orientation="P", unit="mm", format="A4")
 យើងអាចរើសយកពុម្ភអក្សរ Helvetica ដាក់ bold ទំហំ 16 តាមវិធីដូចខាងក្រោមជាគំរូ:
 
 ```python
-pdf.set_font('helvetica', 'B', 16)
+pdf.set_font('Helvetica', style='B', size=16)
 ```
 
 យើងអាចកំណត់ជាទំរង់អក្សរទ្រេតដោយប្រើ `I` និង ទំរង់មានបន្ទាត់រត់ពីក្រោយដោយប្រើ `U` ឬ មិនចាំបាច់ប្រើពួកវា វានឹងបង្ហាញទំរង់ធម្មតាជាមួយនិងការប្រើអក្សរទទេ (empty string) មានន័យ (ឬ ការរួមបញ្ចូលគ្នាផ្សេងទៀត)។ ត្រូវចាំថាទំហំអក្សរត្រូវតែអោយតម្លៃខ្នាតគិតជាចុច(points)  មិនមែនគិតជាមីលីម៉ែត្រ (ឬជាខ្នាតណាមួយផ្សេងទេ) នេះជាករណីលើកលេងក្នុងការប្រើប្រាស។

diff --git a/docs/Tutorial-nl.md b/docs/Tutorial-nl.md
@@ -36,7 +36,7 @@ Voordat we tekst kunnen afdrukken, is het verplicht om een lettertype te selecte
 Wij kiezen voor Helvetica bold 16:
 
 ```python
-pdf.set_font('helvetica', 'B', 16)
+pdf.set_font('Helvetica', style='B', size=16)
 ```
 
 We hadden cursief kunnen specificeren met `I`, onderstreept met `U` of een gewoon lettertype

diff --git a/docs/Tutorial-pl.md b/docs/Tutorial-pl.md
@@ -32,7 +32,7 @@ Zanim będziemy mogli drukować tekst, konieczne jest wybranie czcionki za pomoc
 [set_font](fpdf/fpdf.html#fpdf.fpdf.FPDF.set_font), w przeciwnym razie dokument będzie nieprawidłowy. Wybieramy czcionkę Helvetica pogrubioną o rozmiarze 16:
 
 ```python
-pdf.set_font('helvetica', 'B', 16)
+pdf.set_font('Helvetica', style='B', size=16)
 ```
 
 Można było określić kursywę za pomocą `I`, podkreślenie za pomocą `U` lub zwykłą czcionkę za pomocą pustego łańcucha (lub dowolnej kombinacji). Należy pamiętać, że rozmiar czcionki jest podany w punktach, a nie w milimetrach (lub innej jednostce użytkownika); jest to jedyny wyjątek. Inne wbudowane czcionki to `Times`, `Courier`, `Symbol` i `ZapfDingbats`.

diff --git a/docs/Tutorial-pt.md b/docs/Tutorial-pt.md
@@ -34,7 +34,7 @@ Antes de imprimirmos o texto, é obrigatório selecionar uma fonte com
 Nós escolhemos Helvetica bold 16:
 
 ```python
-pdf.set_font('helvetica', 'B', 16)
+pdf.set_font('Helvetica', style='B', size=16)
 ```
 Podemos formatar em itálico com `I`, sublinhar com` U` ou uma fonte normal
 com uma string vazia (ou qualquer combinação). Observe que o tamanho da fonte é fornecido em pontos, não milímetros (ou outra unidade do utilizador); esta é a única exceção.

diff --git a/docs/Tutorial-ru.md b/docs/Tutorial-ru.md
@@ -27,7 +27,7 @@ pdf = FPDF(orientation="P", unit="mm", format="A4")
 Прежде чем мы сможем напечатать текст, обязательно нужно выбрать шрифт с помощью [set_font](fpdf/fpdf.html#fpdf.fpdf.FPDF.set_font), иначе документ будет недействительным. Мы выбираем Helvetica bold 16:
 
 ```python
-pdf.set_font('helvetica', 'B', 16)
+pdf.set_font('Helvetica', style='B', size=16)
 ```
 
 Мы можем указать курсив с помощью `I`, подчеркнутый шрифт с помощью `U` или обычный шрифт с помощью пустой строки (или использовать любую комбинацию). Обратите внимание, что размер шрифта задается в пунктах, а не в миллиметрах (или другой единице измерений); это единственное исключение. Другие встроенные шрифты: `Times`, `Courier`, `Symbol` и `ZapfDingbats`.

diff --git a/docs/Tutorial-tr.md b/docs/Tutorial-tr.md
@@ -36,7 +36,7 @@ Metni yazdırmadan önce, aşağıdaki özelliklere sahip bir yazı tipi seçmek
 Helvetica bold 16'yı seçiyoruz:
 
 ```python
-pdf.set_font('helvetica', 'B', 16)
+pdf.set_font('Helvetica', style='B', size=16)
 ```
 
 Yazı tipi stilleriyle oynayabiliriz. Örneğin, italikleri `I` ile, altı çizgili `U` ile 

diff --git a/docs/Tutorial-zh.md b/docs/Tutorial-zh.md
@@ -39,7 +39,7 @@ pdf = FPDF(orientation="P", unit="mm", format="A4")
 选择字体 Helvetica，粗体，16号：
 
 ```python
-pdf.set_font('helvetica', 'B', 16)
+pdf.set_font('Helvetica', style='B', size=16)
 ```
 
 使用 `I` 指定斜体，`U` 加下划线或空字符串指定常规字体。

diff --git a/docs/Tutorial.md b/docs/Tutorial.md
@@ -36,7 +36,7 @@ Before we can print text, it is mandatory to select a font with
 We choose Helvetica bold 16:
 
 ```python
-pdf.set_font('helvetica', 'B', 16)
+pdf.set_font('Helvetica', style='B', size=16)
 ```
 
 We could have specified italics with `I`, underlined with `U` or a regular font

diff --git a/fpdf/__init__.py b/fpdf/__init__.py
@@ -17,19 +17,20 @@
 
 import warnings, sys
 
+from .deprecation import WarnOnDeprecatedModuleAttributes
 from .enums import Align, TextMode, XPos, YPos
 from .errors import FPDFException
+from .fonts import FontFace, TextStyle
 from .fpdf import (
     FPDF,
     TitleStyle,
     FPDF_FONT_DIR as _FPDF_FONT_DIR,
     FPDF_VERSION as _FPDF_VERSION,
 )
-from .fonts import FontFace, TextStyle
 from .html import HTMLMixin, HTML2FPDF
 from .prefs import ViewerPreferences
 from .template import Template, FlexTemplate
-from .deprecation import WarnOnDeprecatedModuleAttributes
+from .util import get_scale_factor
 
 try:
     # This module only exists in PyFPDF, it has been removed in fpdf2 since v2.5.7:
@@ -82,6 +83,8 @@
     # FPDF constants:
     "FPDF_VERSION",
     "FPDF_FONT_DIR",
+    # Utility functions:
+    "get_scale_factor",
 ]
 
 __pdoc__ = {name: name.startswith("FPDF_") for name in __all__}
diff --git a/fpdf/template.py b/fpdf/template.py
@@ -718,7 +718,7 @@ def render(self, outfile=None, dest=None):
                 DeprecationWarning,
                 stacklevel=get_stack_level(),
             )
-        self.pdf.set_font("helvetica", "B", 16)
+        self.pdf.set_font("helvetica", style="B", size=16)
         self.pdf.set_auto_page_break(False, margin=0)
         super().render()
         if outfile:

diff --git a/test/fonts/test_set_font.py b/test/fonts/test_set_font.py
@@ -50,21 +50,21 @@ def test_set_builtin_font(tmp_path):
             ("",) if font_name in ("symbol", "zapfdingbats") else ("", "B", "I", "BI")
         )
         for j, style in enumerate(styles):
-            pdf.set_font(font_name.capitalize(), style, 36)
-            pdf.set_font(font_name.lower(), style, 36)
+            pdf.set_font(font_name.capitalize(), style, size=36)
+            pdf.set_font(font_name.lower(), style, size=36)
             pdf.text(0, 10 + 40 * i + 10 * j, "Hello World!")
     assert_pdf_equal(pdf, HERE / "fonts_set_builtin_font.pdf", tmp_path)
 
 
 def test_issue_66(tmp_path):
     pdf = FPDF()
     pdf.add_page()
-    pdf.set_font("Times", "B", 14)
+    pdf.set_font("Times", style="B", size=14)
     pdf.cell(text="ABC")
     pdf.set_font("Times", size=10)
     pdf.cell(text="DEF")
     # Setting the font to an already used one used to remove the text!
-    pdf.set_font("Times", "B", 14)
+    pdf.set_font("Times", style="B", size=14)
     assert_pdf_equal(pdf, HERE / "fonts_issue_66.pdf", tmp_path)
 
 

diff --git a/test/html/test_html.py b/test/html/test_html.py
@@ -1007,7 +1007,7 @@ def test_bulleted_paragraphs():
             "bullet_r_margin": -3,
         },
     ]
-    pdf.set_font("helvetica", "B", 16)
+    pdf.set_font("helvetica", style="B", size=16)
     for case in cases:
         try:
             text_columns.paragraph(

diff --git a/test/layout/test_page_background.py b/test/layout/test_page_background.py
@@ -96,7 +96,7 @@ def test_page_background(tmp_path):
     by printing another two pages with a background color and image
     """
     pdf = FPDF()
-    pdf.set_font("Helvetica", "B", 30)
+    pdf.set_font("Helvetica", style="B", size=30)
     add_pages_with_rgb_tuple_background(pdf)
     _add_pages_with_image_background(pdf)
     add_page_with_DeviceRGB_background(pdf)