Tutorial¶
Documentation complète des méthodes : fpdf.FPDF API doc
Tuto 1 - Exemple minimal¶
Commençons par un exemple classique :
from fpdf import FPDF
pdf = FPDF()
pdf.add_page()
pdf.set_font("helvetica", "B", 16)
pdf.cell(40, 10, "Hello World!")
pdf.output("tuto1.pdf")
Après avoir inclus la librairie, on crée un objet FPDF. Le constructeur FPDF est utilisé avec ses valeurs par défaut : les pages sont en format portrait A4 et l'unité de mesure est le millimètre. Cela peut également être spéficié de cette manière :
pdf = FPDF(orientation="P", unit="mm", format="A4")
Il est possible de créer un PDF en format paysage (L) ou encore d'utiliser d'autres formats (par exemple Letter et Legal) et unités de mesure (pt, cm, in).
Il n'y a pas encore de page, il faut donc en créer une avec add_page. Le coin en haut à gauche correspond à l'origine, et le curseur (c'est-à-dire la position actuelle où l'on va afficher un élément) est placé par défaut à 1 cm des bords. Les marges peuvent être modifiées avec set_margins.
Avant de pouvoir afficher du texte, il faut obligatoirement choisir une police de caractères avec set_font. Choisissons Helvetica bold 16 :
pdf.set_font('helvetica', 'B', 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. Les autres polices fournies par défaut sont Times, Courier, Symbol et ZapfDingbats.
On peut maintenant afficher une cellule avec cell. Une cellule est une zone rectangulaire, avec ou sans cadre, qui contient du texte. Elle est affichée à la position actuelle du curseur. On spécifie ses dimensions, le texte (centré ou aligné), s'il y a une bordure ou non, ainsi que la position du curseur après avoir affiché la cellule (s'il se déplace à droite, vers le bas ou au début de la ligne suivante). Pour ajouter un cadre, on utilise ceci :
pdf.cell(40, 10, 'Hello World!', 1)
Pour ajouter une nouvelle cellule avec un texte centré et déplacer le curseur à la ligne suivante, on utilise cela :
pdf.cell(60, 10, 'Powered by FPDF.', new_x="LMARGIN", new_y="NEXT", align='C')
Remarque : le saut de ligne peut aussi être fait avec ln. Cette méthode permet de spécifier la hauteur du saut.
Enfin, le document est sauvegardé à l'endroit spécifié en utilisant output. Sans aucun paramètre, output() retourne le buffer bytearray du PDF.
Tuto 2 - En-tête, bas de page, saut de page et image¶
Voici un exemple contenant deux pages avec un en-tête, un bas de page et un logo :
from fpdf import FPDF
class PDF(FPDF):
def header(self):
# Rendering logo:
self.image("../docs/fpdf2-logo.png", 10, 8, 33)
# Setting font: helvetica bold 15
self.set_font("helvetica", "B", 15)
# Moving cursor to the right:
self.cell(80)
# Printing title:
self.cell(30, 10, "Title", border=1, align="C")
# Performing a line break:
self.ln(20)
def footer(self):
# Position cursor at 1.5 cm from bottom:
self.set_y(-15)
# Setting font: helvetica italic 8
self.set_font("helvetica", "I", 8)
# Printing page number:
self.cell(0, 10, f"Page {self.page_no()}/{{nb}}", align="C")
# Instantiation of inherited class
pdf = PDF()
pdf.add_page()
pdf.set_font("Times", size=12)
for i in range(1, 41):
pdf.cell(0, 10, f"Printing line number {i}", new_x="LMARGIN", new_y="NEXT")
pdf.output("new-tuto2.pdf")
Cet exemple utilise les méthodes header et footer pour générer des en-têtes et des bas de page. Elles sont appelées automatiquement. Elles existent déjà dans la classe FPDF mais elles ne font rien, il faut donc les redéfinir dans une classe fille.
Le logo est affiché avec la méthode image en spécifiant la position du coin supérieur gauche et la largeur de l'image. La hauteur est calculée automatiquement pour garder les proportions de l'image.
Pour centrer le numéro de page dans le bas de page, il faut passer la valeur nulle à la place de la largeur de la cellule. Cela fait prendre toute la largeur de la page à la cellule, ce qui permet de centrer le texte. Le numéro de page actuel est obtenu avec la méthode page_no. Le nombre total de pages est obtenu avec la variable {nb} qui prend sa valeur quand le document est fermé (la méthode alias_nb_pages permet de définir un autre nom de variable pour cette valeur). La méthode set_y permet de spécifier une position dans la page relative au haut ou bas de page.
Une autre fonctionnalité intéressante est utilisée ici : les sauts de page automatiques. Si une cellule dépasse la limite du contenu de la page (par défaut à 2 centimètres du bas), un saut de page est inséré à la place et la police de caractères est restaurée. C'est-à-dire, bien que l'en-tête et le bas de page utilisent la police helvetica, le corps du texte garde la police Times. Ce mécanisme de restauration automatique s'applique également à la couleur et l'épaisseur des lignes. La limite du contenu qui déclenche le saut de page peut être spécifiée avec set_auto_page_break.
Tuto 3 - Saut de ligne et couleur¶
Continuons avec un exemple qui affiche des paragraphes avec du texte justifié. Cet exemple montre également l'utilisation de couleurs.
from fpdf import FPDF
class PDF(FPDF):
def header(self):
# Setting font: helvetica bold 15
self.set_font("helvetica", "B", 15)
# Calculating width of title and setting cursor position:
width = self.get_string_width(self.title) + 6
self.set_x((210 - width) / 2)
# Setting colors for frame, background and text:
self.set_draw_color(0, 80, 180)
self.set_fill_color(230, 230, 0)
self.set_text_color(220, 50, 50)
# Setting thickness of the frame (1 mm)
self.set_line_width(1)
# Printing title:
self.cell(
width,
9,
self.title,
border=1,
new_x="LMARGIN",
new_y="NEXT",
align="C",
fill=True,
)
# Performing a line break:
self.ln(10)
def footer(self):
# Setting position at 1.5 cm from bottom:
self.set_y(-15)
# Setting font: helvetica italic 8
self.set_font("helvetica", "I", 8)
# Setting text color to gray:
self.set_text_color(128)
# Printing page number
self.cell(0, 10, f"Page {self.page_no()}", align="C")
def chapter_title(self, num, label):
# Setting font: helvetica 12
self.set_font("helvetica", "", 12)
# Setting background color
self.set_fill_color(200, 220, 255)
# Printing chapter name:
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)
def chapter_body(self, filepath):
# Reading text file:
with open(filepath, "rb") as fh:
txt = fh.read().decode("latin-1")
# Setting font: Times 12
self.set_font("Times", size=12)
# Printing justified text:
self.multi_cell(0, 5, txt)
# Performing a line break:
self.ln()
# Final mention in italics:
self.set_font(style="I")
self.cell(0, 5, "(end of excerpt)")
def print_chapter(self, num, title, filepath):
self.add_page()
self.chapter_title(num, title)
self.chapter_body(filepath)
pdf = PDF()
pdf.set_title("20000 Leagues Under the Seas")
pdf.set_author("Jules Verne")
pdf.print_chapter(1, "A RUNAWAY REEF", "20k_c1.txt")
pdf.print_chapter(2, "THE PROS AND CONS", "20k_c1.txt")
pdf.output("tuto3.pdf")
La méthode get_string_width permet de déterminer la largeur d'un texte utilisant la police actuelle, ce qui permet de calculer la position et la largeur du cadre autour du titre. Ensuite les couleurs sont spécifiées (avec set_draw_color, set_fill_color et set_text_color) et on spécifie l'épaisseur de la bordure du cadre à 1 mm (contre 0.2 par défaut) avec set_line_width. Enfin, on affiche la cellule (le dernier paramètre "true" indique que le fond doit être rempli).
La méthode multi_cell est utilisée pour afficher les paragraphes. Chaque fois qu'une ligne atteint le bord d'une cellule ou qu'un caractère de retour à la ligne est présent, un saut de ligne est inséré et une nouvelle cellule est créée automatiquement sous la cellule actuelle. Le texte est justifié par défaut.
Deux propriétés sont définies pour le document : le titre (set_title) et l'auteur (set_author). Les propriétés peuvent être trouvées en ouvrant le document PDF avec Acrobat Reader. Elles sont alors visibles dans le menu Fichier -> Propriétés du document.
Tuto 4 - Colonnes multiples¶
Cet exemple est une variante du précédent qui montre comment répartir le texte sur plusieurs colonnes.
from fpdf import FPDF
class PDF(FPDF):
def __init__(self):
super().__init__()
self.col = 0 # Current column
self.y0 = 0 # Ordinate of column start
def header(self):
self.set_font("helvetica", "B", 15)
width = self.get_string_width(self.title) + 6
self.set_x((210 - width) / 2)
self.set_draw_color(0, 80, 180)
self.set_fill_color(230, 230, 0)
self.set_text_color(220, 50, 50)
self.set_line_width(1)
self.cell(
width,
9,
self.title,
border=1,
new_x="LMARGIN",
new_y="NEXT",
align="C",
fill=True,
)
self.ln(10)
# Saving ordinate position:
self.y0 = self.get_y()
def footer(self):
self.set_y(-15)
self.set_font("helvetica", "I", 8)
self.set_text_color(128)
self.cell(0, 10, f"Page {self.page_no()}", align="C")
def set_col(self, col):
# Set column position:
self.col = col
x = 10 + col * 65
self.set_left_margin(x)
self.set_x(x)
@property
def accept_page_break(self):
if self.col < 2:
# Go to next column:
self.set_col(self.col + 1)
# Set ordinate to top:
self.set_y(self.y0)
# Stay on the same page:
return False
# Go back to first column:
self.set_col(0)
# Trigger a page break:
return True
def chapter_title(self, num, label):
self.set_font("helvetica", "", 12)
self.set_fill_color(200, 220, 255)
self.cell(
0,
6,
f"Chapter {num} : {label}",
new_x="LMARGIN",
new_y="NEXT",
border="L",
fill=True,
)
self.ln(4)
# Saving ordinate position:
self.y0 = self.get_y()
def chapter_body(self, name):
# Reading text file:
with open(name, "rb") as fh:
txt = fh.read().decode("latin-1")
# Setting font: Times 12
self.set_font("Times", size=12)
# Printing text in a 6cm width column:
self.multi_cell(60, 5, txt)
self.ln()
# Final mention in italics:
self.set_font(style="I")
self.cell(0, 5, "(end of excerpt)")
# Start back at first column:
self.set_col(0)
def print_chapter(self, num, title, name):
self.add_page()
self.chapter_title(num, title)
self.chapter_body(name)
pdf = PDF()
pdf.set_title("20000 Leagues Under the Seas")
pdf.set_author("Jules Verne")
pdf.print_chapter(1, "A RUNAWAY REEF", "20k_c1.txt")
pdf.print_chapter(2, "THE PROS AND CONS", "20k_c1.txt")
pdf.output("tuto4.pdf")
La principale différence avec le tutoriel précédent est l'utilisation des méthodes accept_page_break et set_col().
En utilisant la méthode accept_page_break, une fois que la cellule franchit la limite inférieure de la page, elle vérifie le numéro de la colonne actuelle. Si celui-ci est inférieur à 2 (nous avons choisi de diviser la page en trois colonnes), il appelle la méthode set_col(), en augmentant le numéro de la colonne et en modifiant la position de la colonne suivante pour que le texte puisse s'y poursuivre.
Une fois que la limite inférieure de la troisième colonne est atteinte, la méthode accept_page_break sera réinitialisée et retournera à la première colonne. Cela déclenchera un saut de page.
Tuto 5 - Créer des tables¶
Ce tutoriel explique comment créer facilement des tableaux.
Le code créera trois tableaux différents pour expliquer ce qui peut être réalisé avec quelques modifications.
import csv
from fpdf import FPDF
class PDF(FPDF):
def basic_table(self, headings, rows):
for heading in headings:
self.cell(40, 7, heading, 1)
self.ln()
for row in rows:
for col in row:
self.cell(40, 6, col, 1)
self.ln()
def improved_table(self, headings, rows, col_widths=(42, 39, 35, 40)):
for col_width, heading in zip(col_widths, headings):
self.cell(col_width, 7, heading, border=1, align="C")
self.ln()
for row in rows:
self.cell(col_widths[0], 6, row[0], border="LR")
self.cell(col_widths[1], 6, row[1], border="LR")
self.cell(col_widths[2], 6, row[2], border="LR", align="R")
self.cell(col_widths[3], 6, row[3], border="LR", align="R")
self.ln()
# Closure line:
self.cell(sum(col_widths), 0, "", border="T")
def colored_table(self, headings, rows, col_widths=(42, 39, 35, 42)):
# Colors, line width and bold font:
self.set_fill_color(255, 100, 0)
self.set_text_color(255)
self.set_draw_color(255, 0, 0)
self.set_line_width(0.3)
self.set_font(style="B")
for col_width, heading in zip(col_widths, headings):
self.cell(col_width, 7, heading, border=1, align="C", fill=True)
self.ln()
# Color and font restoration:
self.set_fill_color(224, 235, 255)
self.set_text_color(0)
self.set_font()
fill = False
for row in rows:
self.cell(col_widths[0], 6, row[0], border="LR", align="L", fill=fill)
self.cell(col_widths[1], 6, row[1], border="LR", align="L", fill=fill)
self.cell(col_widths[2], 6, row[2], border="LR", align="R", fill=fill)
self.cell(col_widths[3], 6, row[3], border="LR", align="R", fill=fill)
self.ln()
fill = not fill
self.cell(sum(col_widths), 0, "", "T")
def load_data_from_csv(csv_filepath):
headings, rows = [], []
with open(csv_filepath, encoding="utf8") as csv_file:
for row in csv.reader(csv_file, delimiter=","):
if not headings: # extracting column names from first row:
headings = row
else:
rows.append(row)
return headings, rows
col_names, data = load_data_from_csv("countries.txt")
pdf = PDF()
pdf.set_font("helvetica", size=14)
pdf.add_page()
pdf.basic_table(col_names, data)
pdf.add_page()
pdf.improved_table(col_names, data)
pdf.add_page()
pdf.colored_table(col_names, data)
pdf.output("tuto5.pdf")
Comme un tableau n'est qu'une collection de cellules, il est naturel d'en construire un à partir de celles-ci.
Le premier exemple est réalisé de la manière la plus basique qui soit : de simples cellules encadrées, toutes de même taille et alignées à gauche. Le résultat est rudimentaire mais très rapide à obtenir.
Le deuxième tableau apporte quelques améliorations : chaque colonne possède sa propre largeur, les titres sont centrés et les chiffres alignés à droite. De plus, les lignes horizontales ont été supprimées. C'est fait grâce au paramètre border de la méthode .cell() qui spécifie quels côtés de la cellule doivent être dessinés. Ici, nous voulons les côtés gauche (L) et droit (R). Il ne reste plus que le problème de la ligne horizontale pour terminer le tableau. Il y a deux possibilités pour le résoudre : vérifier la dernière ligne dans la boucle (dans ce cas nous utilisons LRB pour le paramètre de bordure) ou, comme fait ici, ajouter la ligne une fois la boucle terminée.
Le troisième tableau est similaire au deuxième mais utilise des couleurs. Les couleurs de remplissage, de texte et de ligne sont simplement spécifiées. Une coloration alternative pour les lignes est obtenue en utilisant des cellules alternativement transparentes et remplies.
Tuto 6 - Créer des liens et mélanger différents styles de textes¶
Ce tutoriel explique plusieurs façons d'insérer des liens à l'intérieur d'un document pdf, ainsi que l'ajout de liens vers des sources externes.
Il montrera également plusieurs façons d'utiliser différents styles de texte (gras, italique, souligné) dans un même texte.
from fpdf import FPDF
pdf = FPDF()
# First page:
pdf.add_page()
pdf.set_font("helvetica", size=20)
pdf.write(5, "To find out what's new in self tutorial, click ")
pdf.set_font(style="U")
link = pdf.add_link(page=2)
pdf.write(5, "here", link)
pdf.set_font()
# Second page:
pdf.add_page()
pdf.image(
"../docs/fpdf2-logo.png", 10, 10, 50, 0, "", "https://pyfpdf.github.io/fpdf2/"
)
pdf.set_left_margin(60)
pdf.set_font_size(18)
pdf.write_html(
"""You can print text mixing different styles using HTML tags: <b>bold</b>, <i>italic</i>,
<u>underlined</u>, or <b><i><u>all at once</u></i></b>!
<br><br>You can also insert links on text, such as <a href="https://pyfpdf.github.io/fpdf2/">https://pyfpdf.github.io/fpdf2/</a>,
or on an image: the logo is clickable!"""
)
pdf.output("tuto6.pdf")
PDF créé dans ce tutoriel - fpdf2-logo
La nouvelle méthode présentée ici pour imprimer du texte est write(). Elle est très similaire à multi_cell(). Les principales différences sont les suivantes :
- La fin de la ligne se trouve dans la marge de droite et la ligne suivante commence dans la marge de gauche.
- La position actuelle se déplace à la fin du texte.
Cette méthode nous permet donc d'écrire un morceau de texte, de modifier le style de police et de reprendre exactement là où nous nous sommes arrêtés. En revanche, son principal inconvénient est que nous ne pouvons pas justifier le texte comme nous le faisons avec la méthode multi_cell().
Dans la première page de l'exemple, nous avons utilisé write() à cette fin. Le début de la phrase est écrit en style normal, puis en utilisant la méthode set_font(), nous sommes passés au soulignement et avons terminé la phrase.
Pour ajouter un lien interne pointant vers la deuxième page, nous avons utilisé la méthode add_link(), qui crée une zone cliquable que nous avons nommée link et qui dirige vers une autre page du document.
Pour créer le lien externe à l'aide d'une image, nous avons utilisé image(). Cette méthode a la possibilité de transmettre un lien comme l'un de ses arguments. Le lien peut être interne ou externe.
Comme alternative, une autre option pour changer le style de police et ajouter des liens est d'utiliser la méthode write_html(). Celle-ci permet de lire du HTML pour produire du texte, changer le style de police ou encore ajouter des liens.