Deprecating txt= arg in favor of text=

py-pdf · Oct 11, 2023 · aec15d2 · aec15d2
1 parent e918119
commit aec15d2
Show file tree

Hide file tree

Showing 64 changed files with 591 additions and 508 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -18,6 +18,7 @@ This can also be enabled programmatically with `warnings.simplefilter('default',
 
 ## [2.7.6] - Not released yet
 This release is the first performed from the [@py-pdf GitHub org](https://github.com/py-pdf), where `fpdf2` migrated.
+This release also marks the arrival of two new maintainers: Georg Mischler ([@gmischler](https://github.com/gmischler)) and Anderson Herzogenrath da Costa ([@andersonhc](https://github.com/andersonhc)).
 ### Added
 * The new experimental method `text_columns()` allows to render text within a single or multiple columns, including height balancing: [documentation](https://py-pdf.github.io/fpdf2/TextColumns.html)
 * [`FPDF.write_html()`](https://py-pdf.github.io/fpdf2/fpdf/fpdf.html#fpdf.fpdf.FPDF.write_html) now supports heading colors defined as attributes (_e.g._ `<h2 color="#00ff00">...`)
@@ -42,6 +43,8 @@ This change was made for consistency between row-height governed by text or imag
 * [`FPDF.table()`](https://py-pdf.github.io/fpdf2/fpdf/fpdf.html#fpdf.fpdf.FPDF.table): images no longer overlap with cell borders - _cf._ issue [#892](https://github.com/py-pdf/fpdf2/issues/892)
 * Encryption of strings containing non-latin characters - _cf._ issue [#933](https://github.com/py-pdf/fpdf2/issues/933)
 * Handling of fragments with zero-length - _cf._ issue [#902](https://github.com/py-pdf/fpdf2/issues/902)
+### Deprecated
+* to improve naming consistency, the `txt` parameters of `FPDF.cell()`, `FPDF.multi_cell()`, `FPDF.text()` & `FPDF.write()` have been renamed to `text`
 
 ## [2.7.5] - 2023-08-04
 ### Added

diff --git a/docs/Annotations.md b/docs/Annotations.md
@@ -15,7 +15,7 @@ from fpdf import FPDF
 pdf = FPDF()
 pdf.add_page()
 pdf.set_font("Helvetica", size=24)
-pdf.text(x=60, y=140, txt="Some text.")
+pdf.text(x=60, y=140, text="Some text.")
 pdf.text_annotation(
     x=100,
     y=130,
@@ -38,8 +38,8 @@ pdf.set_font("Helvetica", size=24)
 with pdf.highlight("Highlight comment"):
     pdf.text(50, 50, "Line 1")
     pdf.set_y(50)
-    pdf.multi_cell(w=30, txt="Line 2")
-pdf.cell(w=60, txt="Not highlighted", border=1)
+    pdf.multi_cell(w=30, text="Line 2")
+pdf.cell(w=60, text="Not highlighted", border=1)
 pdf.output("highlighted.pdf")
 ```
 
@@ -87,11 +87,11 @@ from fpdf.actions import NamedAction
 pdf = FPDF()
 pdf.set_font("Helvetica", size=24)
 pdf.add_page()
-pdf.text(x=80, y=140, txt="First page")
+pdf.text(x=80, y=140, text="First page")
 pdf.add_page()
 pdf.underline = True
 for x, y, named_action in ((40, 80, "NextPage"), (120, 80, "PrevPage"), (40, 200, "FirstPage"), (120, 200, "LastPage")):
-    pdf.text(x=x, y=y, txt=named_action)
+    pdf.text(x=x, y=y, text=named_action)
     pdf.add_action(
         NamedAction(named_action),
         x=x,
@@ -101,7 +101,7 @@ for x, y, named_action in ((40, 80, "NextPage"), (120, 80, "PrevPage"), (40, 200
     )
 pdf.underline = False
 pdf.add_page()
-pdf.text(x=80, y=140, txt="Last page")
+pdf.text(x=80, y=140, text="Last page")
 pdf.output("named_actions.pdf")
 ```
 
@@ -118,7 +118,7 @@ pdf = FPDF()
 pdf.set_font("Helvetica", size=24)
 pdf.add_page()
 x, y, text = 80, 140, "Launch action"
-pdf.text(x=x, y=y, txt=text)
+pdf.text(x=x, y=y, text=text)
 pdf.add_action(
     LaunchAction("another_file_in_same_directory.pdf"),
     x=x,

diff --git a/docs/CombineWithBorb.md b/docs/CombineWithBorb.md
@@ -20,7 +20,7 @@ pdf = FPDF()
 pdf.set_title('Initiating a borb doc from a FPDF instance')
 pdf.set_font('helvetica', size=12)
 pdf.add_page()
-pdf.cell(txt="Hello world!")
+pdf.cell(text="Hello world!")
 
 doc = PDF.loads(BytesIO(pdf.output()))
 print(doc.get_document_info().get_title())

diff --git a/docs/DatabaseStorage.md b/docs/DatabaseStorage.md
@@ -24,7 +24,7 @@ Base.metadata.create_all(engine)
 pdf = FPDF()
 pdf.add_page()
 pdf.set_font("Helvetica", size=24)
-pdf.cell(txt="My name is Bobby")
+pdf.cell(text="My name is Bobby")
 new_user = User(name="Bobby", pdf=pdf.output())
 
 Session = sessionmaker(bind=engine)

diff --git a/docs/DocumentOutlineAndTableOfContents.md b/docs/DocumentOutlineAndTableOfContents.md
@@ -39,9 +39,9 @@ from fpdf import FPDF, HTML2FPDF
 
 class CustomHTML2FPDF(HTML2FPDF):
     def render_toc(self, pdf, outline):
-        pdf.cell(txt='Table of contents:', new_x="LMARGIN", new_y="NEXT")
+        pdf.cell(text='Table of contents:', new_x="LMARGIN", new_y="NEXT")
         for section in outline:
-            pdf.cell(txt=f'* {section.name} (page {section.page_number})', new_x="LMARGIN", new_y="NEXT")
+            pdf.cell(text=f'* {section.name} (page {section.page_number})', new_x="LMARGIN", new_y="NEXT")
 
 class PDF(FPDF):
     HTML2FPDF_CLASS = CustomHTML2FPDF

diff --git a/docs/EmojisSymbolsDingbats.md b/docs/EmojisSymbolsDingbats.md
@@ -14,7 +14,7 @@ pdf = fpdf.FPDF()
 pdf.add_font(fname="DejaVuSans.ttf")
 pdf.set_font("DejaVuSans", size=64)
 pdf.add_page()
-pdf.multi_cell(0, txt="".join([chr(0x1F600 + x) for x in range(68)]))
+pdf.multi_cell(0, text="".join([chr(0x1F600 + x) for x in range(68)]))
 pdf.set_font_size(32)
 pdf.text(10, 270, "".join([chr(0x1F0A0 + x) for x in range(15)]))
 pdf.output("fonts_emoji_glyph.pdf")
@@ -35,11 +35,11 @@ import fpdf
 pdf = fpdf.FPDF()
 pdf.add_page()
 pdf.set_font("symbol", size=36)
-pdf.cell(h=16, txt="\u0022 \u0068 \u0024 \u0065 \u00ce \u00c2, \u0068/\u0065 \u0040 \u00a5",
+pdf.cell(h=16, text="\u0022 \u0068 \u0024 \u0065 \u00ce \u00c2, \u0068/\u0065 \u0040 \u00a5",
         new_x="LMARGIN", new_y="NEXT")
-pdf.cell(h=16, txt="\u0044 \u0046 \u0053 \u0057 \u0059 \u0061 \u0062 \u0063",
+pdf.cell(h=16, text="\u0044 \u0046 \u0053 \u0057 \u0059 \u0061 \u0062 \u0063",
         new_x="LMARGIN", new_y="NEXT")
-pdf.cell(h=16, txt="\u00a0 \u00a7 \u00a8 \u00a9 \u00aa \u00ab \u00ac \u00ad \u00ae \u00af \u00db \u00dc \u00de",
+pdf.cell(h=16, text="\u00a0 \u00a7 \u00a8 \u00a9 \u00aa \u00ab \u00ac \u00ad \u00ae \u00af \u00db \u00dc \u00de",
         new_x="LMARGIN", new_y="NEXT")
 pdf.output("symbol.pdf")
 ```
@@ -61,7 +61,7 @@ import fpdf
 pdf = fpdf.FPDF()
 pdf.add_page()
 pdf.set_font("zapfdingbats", size=36)
-pdf.cell(txt="+ 3 8 A r \u00a6 } \u00a8 \u00a9 \u00aa \u00ab ~")
+pdf.cell(text="+ 3 8 A r \u00a6 } \u00a8 \u00a9 \u00aa \u00ab ~")
 pdf.output("zapfdingbat.pdf")
 ```
 

diff --git a/docs/Encryption.md b/docs/Encryption.md
@@ -58,7 +58,7 @@ from fpdf.enums import AccessPermission
 pdf = FPDF()
 pdf.add_page()
 pdf.set_font("helvetica", size=12)
-pdf.cell(txt="hello world")
+pdf.cell(text="hello world")
 
 pdf.set_encryption(
     owner_password="98765421",
@@ -102,7 +102,7 @@ from fpdf.enums import AccessPermission, EncryptionMethod
 pdf = FPDF()
 pdf.add_page()
 pdf.set_font("helvetica", size=12)
-pdf.cell(txt="hello world")
+pdf.cell(text="hello world")
 
 pdf.set_encryption(
     owner_password="123",

diff --git a/docs/FAQ.md b/docs/FAQ.md
@@ -79,13 +79,13 @@ def get_me_a_pdf():
     pdf = FPDF()
     pdf.add_page()
     pdf.set_font('Times', 'B', 15)
-    pdf.cell(w=210, h=9, txt=title, border=0,
+    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.cell(w=0, h=6, txt=heading, border=0,
+    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.multi_cell(w=0, h=5, txt=text)
+    pdf.multi_cell(w=0, h=5, text=text)
     response.headers['Content-Type'] = 'application/pdf'
     return pdf.output()
 ```

diff --git a/docs/History.md b/docs/History.md
@@ -25,7 +25,7 @@ On 2020, the first PRs were merged from external contributors.
 At the end of the year, Lucas Cimon ([@Lucas-C](https://github.com/Lucas-C/)) started contributing several improvements, in order to use `fpdf2` for his [Undying Dusk](https://lucas-c.itch.io/undying-dusk) project.
 [Version **2.1.0** was released](https://github.com/py-pdf/fpdf2/blob/master/CHANGELOG.md#210---2020-12-07) and on 2021/01/10 `fpdf2` was moved to a dedicated `PyFPDF` GitHub organization, and `@Lucas-C` became another maintainer of the project.
 
-On 2023/08/04, `fpdf2` moved to the `py-pdf` organization: <https://github.com/py-pdf/fpdf2>. The context for this move can be found there: <https://github.com/py-pdf/fpdf2/discussions/752>. On this date, the `PyFPDF` GitHub organization has been **archived**.
+On 2023/08/04, `fpdf2` moved to the `py-pdf` organization: <https://github.com/py-pdf/fpdf2>. The context for this move can be found there: [discussion #752](https://github.com/py-pdf/fpdf2/discussions/752). On this date, the `PyFPDF` GitHub organization has been **archived**.
 The same month, Georg Mischler ([@gmischler](https://github.com/gmischler)) and Anderson Herzogenrath da Costa ([@andersonhc](https://github.com/andersonhc)) joined the project as new maintainers.
 
 ## Compatibility between PyFPDF & fpdf2 ##

diff --git a/docs/Images.md b/docs/Images.md
@@ -219,7 +219,7 @@ from fpdf import FPDF
 pdf = FPDF()
 pdf.allow_images_transparency = False
 pdf.set_font("Helvetica", size=15)
-pdf.cell(w=pdf.epw, h=30, txt="Text behind. " * 6)
+pdf.cell(w=pdf.epw, h=30, text="Text behind. " * 6)
 pdf.image("docs/fpdf2-logo.png", x=0)
 pdf.output("pdf-including-image-without-transparency.pdf")
 ```

diff --git a/docs/Links.md b/docs/Links.md
@@ -14,7 +14,7 @@ from fpdf import FPDF
 pdf = FPDF()
 pdf.add_page()
 pdf.set_font("helvetica", size=24)
-pdf.cell(txt="Cell link", border=1, center=True,
+pdf.cell(text="Cell link", border=1, center=True,
          link="https://github.com/py-pdf/fpdf2")
 pdf.output("hyperlink.pdf")
 ```
@@ -30,7 +30,7 @@ pdf.set_font("helvetica", size=24)
 pdf.add_page()
 pdf.multi_cell(
     pdf.epw,
-    txt="**Website:** [fpdf2](https://py-pdf.github.io/fpdf2/) __Go visit it!__",
+    text="**Website:** [fpdf2](https://py-pdf.github.io/fpdf2/) __Go visit it!__",
     markdown=True,
 )
 pdf.output("hyperlink.pdf")
@@ -55,7 +55,7 @@ pdf.add_page()
 pdf.set_font("helvetica", size=36)
 line_height = 10
 text = "Text link"
-pdf.text(x=0, y=line_height, txt=text)
+pdf.text(x=0, y=line_height, text=text)
 width = pdf.get_string_width(text)
 pdf.link(x=0, y=0, w=width, h=line_height, link="https://github.com/py-pdf/fpdf2")
 pdf.output("hyperlink.pdf")
@@ -91,10 +91,10 @@ from fpdf import FPDF
 pdf = FPDF()
 pdf.set_font("helvetica", size=24)
 pdf.add_page()
-pdf.cell(txt="Welcome on first page!", align="C", center=True)
+pdf.cell(text="Welcome on first page!", align="C", center=True)
 pdf.add_page()
 link = pdf.add_link(page=1)
-pdf.cell(txt="Internal link to first page", border=1, link=link)
+pdf.cell(text="Internal link to first page", border=1, link=link)
 pdf.output("internal_link.pdf")
 ```
 
@@ -117,7 +117,7 @@ from fpdf import FPDF
 pdf = FPDF()
 pdf.set_font("helvetica", size=24)
 pdf.add_page()
-pdf.cell(txt="Link to other_doc.pdf", border=1, link="other_doc.pdf")
+pdf.cell(text="Link to other_doc.pdf", border=1, link="other_doc.pdf")
 pdf.output("link_to_other_doc.pdf")
 ```
 

diff --git a/docs/PageBreaks.md b/docs/PageBreaks.md
@@ -62,7 +62,7 @@ if dummy.page_break_triggered:
     # We trigger a page break manually beforehand:
     pdf.add_page()
     # We duplicate the section header:
-    pdf.cell(txt="Appendix C")
+    pdf.cell(text="Appendix C")
 # Now performing our rendering for real:
 pdf.multi_cell(...)
 ```
diff --git a/docs/PageFormatAndOrientation.md b/docs/PageFormatAndOrientation.md
@@ -27,10 +27,10 @@ for i in range(9):
     if i == 6:
         pdf.set_page_background('image_path.png')
     pdf.add_page(format=(210 * (1 - i/10), 297 * (1 - i/10)))
-    pdf.cell(txt=str(i))
+    pdf.cell(text=str(i))
 pdf.set_page_background(None)
 pdf.add_page(same=True)
-pdf.cell(txt="9")
+pdf.cell(text="9")
 pdf.output("varying_format.pdf")
 ```
 
@@ -51,9 +51,9 @@ pdf = FPDF()
 pdf.set_display_mode(zoom="default", layout="TWO_COLUMN_LEFT")
 pdf.set_font("helvetica", size=30)
 pdf.add_page()
-pdf.cell(txt="page 1")
+pdf.cell(text="page 1")
 pdf.add_page()
-pdf.cell(txt="page 2")
+pdf.cell(text="page 2")
 pdf.output("two-column.pdf")
 ```
 
@@ -74,9 +74,9 @@ pdf.viewer_preferences = ViewerPreferences(
 )
 pdf.set_font("helvetica", size=30)
 pdf.add_page()
-pdf.cell(txt="page 1")
+pdf.cell(text="page 1")
 pdf.add_page()
-pdf.cell(txt="page 2")
+pdf.cell(text="page 2")
 pdf.output("viewer-prefs.pdf")
 ```
 

diff --git a/docs/Presentations.md b/docs/Presentations.md
@@ -16,12 +16,12 @@ from fpdf import FPDF
 pdf = fpdf.FPDF()
 pdf.set_font("Helvetica", size=120)
 pdf.add_page(duration=3)
-pdf.cell(txt="Page 1")
+pdf.cell(text="Page 1")
 pdf.page_duration = .5
 pdf.add_page()
-pdf.cell(txt="Page 2")
+pdf.cell(text="Page 2")
 pdf.add_page()
-pdf.cell(txt="Page 3")
+pdf.cell(text="Page 3")
 pdf.output("presentation.pdf")
 ```
 
@@ -39,29 +39,29 @@ from fpdf.transitions import *
 pdf = fpdf.FPDF()
 pdf.set_font("Helvetica", size=120)
 pdf.add_page()
-pdf.text(x=40, y=150, txt="Page 0")
+pdf.text(x=40, y=150, text="Page 0")
 pdf.add_page(transition=SplitTransition("V", "O"))
-pdf.text(x=40, y=150, txt="Page 1")
+pdf.text(x=40, y=150, text="Page 1")
 pdf.add_page(transition=BlindsTransition("H"))
-pdf.text(x=40, y=150, txt="Page 2")
+pdf.text(x=40, y=150, text="Page 2")
 pdf.add_page(transition=BoxTransition("I"))
-pdf.text(x=40, y=150, txt="Page 3")
+pdf.text(x=40, y=150, text="Page 3")
 pdf.add_page(transition=WipeTransition(90))
-pdf.text(x=40, y=150, txt="Page 4")
+pdf.text(x=40, y=150, text="Page 4")
 pdf.add_page(transition=DissolveTransition())
-pdf.text(x=40, y=150, txt="Page 5")
+pdf.text(x=40, y=150, text="Page 5")
 pdf.add_page(transition=GlitterTransition(315))
-pdf.text(x=40, y=150, txt="Page 6")
+pdf.text(x=40, y=150, text="Page 6")
 pdf.add_page(transition=FlyTransition("H"))
-pdf.text(x=40, y=150, txt="Page 7")
+pdf.text(x=40, y=150, text="Page 7")
 pdf.add_page(transition=PushTransition(270))
-pdf.text(x=40, y=150, txt="Page 8")
+pdf.text(x=40, y=150, text="Page 8")
 pdf.add_page(transition=CoverTransition(270))
-pdf.text(x=40, y=150, txt="Page 9")
+pdf.text(x=40, y=150, text="Page 9")
 pdf.add_page(transition=UncoverTransition(270))
-pdf.text(x=40, y=150, txt="Page 10")
+pdf.text(x=40, y=150, text="Page 10")
 pdf.add_page(transition=FadeTransition())
-pdf.text(x=40, y=150, txt="Page 11")
+pdf.text(x=40, y=150, text="Page 11")
 pdf.output("transitions.pdf")
 ```
 

diff --git a/docs/TextShaping.md b/docs/TextShaping.md
@@ -56,7 +56,7 @@ pdf.add_page()
 pdf.add_font(family="ViaodaLibre", fname=HERE / "ViaodaLibre-Regular.ttf")
 pdf.set_font("ViaodaLibre", size=40)
 pdf.set_text_shaping(True)
-pdf.cell(txt="final soft stuff")
+pdf.cell(text="final soft stuff")
 pdf.output("Example.pdf")
 ```