ReportLab

Dieser Artikel wurde für die folgenden Ubuntu-Versionen getestet:

Zum Verständnis dieses Artikels sind folgende Seiten hilfreich:

  1. Installation von Programmen

  2. Root-Rechte, optional

  3. Archive entpacken, optional

Inhaltsverzeichnis
  1. Installation
    1. manuelle Installation
    2. Schriften installieren
  2. Benutzung
    1. PDFs generieren
    2. Flowables
    3. Platypus
    4. Diagramme generieren
    5. Dokumentation
  3. Links

Wiki/Icons/python.png ReportLab 🇬🇧 bzw. genau genommen das ReportLab Toolkit ist ein umfangreiches Python-Modul, welches zum Generieren von PDF-Dateien aus Skripten heraus dient. Das Toolkit an sich steht unter einer freien OpenSource-Lizenz, die dahinter stehende Firma ReportLab 🇬🇧 bietet zusätzlich noch darauf aufbauende Module und Programme an, die das Generieren von PDFs weiter erleichtern sollen. Das Toolkit reicht aber völlig aus, zumal es einen großen Funktionsumfang hat, der sich uneingeschränkt nutzen lässt.

Im Gegensatz zu anderen Programmen, welche PDFs z.B. via Drucktreiber generieren, erzeugt ReportLab die Dateien nach der PDF1.4 Spezifikation, d.h. sie enthalten z.B. durchsuchbaren Text und nicht nur Bilder. Weiterhin wird die Schrift vektorisiert eingebunden, so dass die Dokumente beliebig skalierbar sind.

Ab der Version 3 (erschienen im Februar 2014) funktioniert ReportLab auch mit Python 3, setzt aber mindestens die Python-Version 3.3 voraus.

Im Folgenden wird der Einfachheit halber von „ReportLab“ gesprochen, gemeint ist aber durchgehend das freie ReportLab Toolkit.

Installation

ReportLab ist in den Paketquellen enthalten und kann für Python3 über das Paket:

Paketliste zum Kopieren:

sudo apt-get install python3-reportlab 

Oder mit apturl die Pakete installieren. Link: apt://python3-reportlab

bzw. für Python 2 über das Paket

Paketliste zum Kopieren:

sudo apt-get install python-reportlab 

Oder mit apturl die Pakete installieren. Link: apt://python-reportlab

installiert werden[1].

manuelle Installation

Wer eine neuere Version als die aus den Paketquellen benötigt, kann diese via pip installieren, sowohl für Python 3 als auch für Python 2. Dabei wird auch die Python-Bibliothek Pillow 🇬🇧 mit installiert, welche wieder voraussetzt, dass die Pakete build-essential, python3-dev (für Python 3) bzw. python-dev (für Python 2), libjpeg8-dev, zlib1g-dev installiert sind.

Schriften installieren

Hinweis:

Die manuelle Installation von Schriften ist nur notwendig, wenn man Diagramme generieren möchte. Für die Erzeugung von PDFs ist dies nicht notwendig.

Leider sind in der Standardinstallation einige Schriften nicht enthalten, die man aber benötigt, wenn Diagramme erstellt werden sollen. Daher müssen diese manuell installiert werden.

Dazu lädt man die Schriften als zip-Datei von der ReportLab Seite ⮷ herunter und entpackt die Datei[3]. Die Dateien kopiert man nun - ggf. mit Root-Rechten[2] - ins Unterverzerzeichnis fonts der Reportlab Installation. Sollte fonts nicht existieren, so muss man das Verzeichnis natürlich erst anlegen.

Benutzung

Man kann ReportLab auf mehreren Ebenen nutzen, welche unterschiedlich „komfortabel“ sind bzw. unterschiedlich detaillierte Zugriffe auf das Layout zu lassen. Dies wird im Folgenden beschrieben.

PDFs generieren

Die unterste, für den Benutzer sinnvoll nutzbare Ebene bei der PDF-Generierung ist der „Canvas“. Dieser stellt eine leeres PDF-Dokument dar, welches dann mit Inhalt gefüllt werden kann:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
#!/usr/bin/env python3

from reportlab.pdfgen import canvas
from reportlab.lib.pagesizes import A4
from reportlab.lib.units import cm

#Anlegen des PDF Dokuments, Seitengröße DIN A4 Hochformat)
pdf = canvas.Canvas('mein_pdf.pdf',pagesize=A4)
#Holen der Seitenabmessung
breite, hoehe = A4
#Hinzufügen von diversen Elementen
#Der Nullpunkt des Dokuments ist unten links!
#Die Koordinaten werden nur teilweise in cm angegeben
pdf.drawString(1*cm,1*cm,'Der Text steht links unten')
pdf.setFont('Helvetica-Bold',20)
pdf.drawCentredString(breite/2,hoehe-(2*cm),'Der Text steht oben zentriert')
#und noch ein buntes Rechteck...
pdf.setStrokeColorRGB(0,1,0)
pdf.setFillColorRGB(1,0,0)
pdf.rect((breite/2)-(3*cm),(hoehe/2)-(3*cm),6*cm,6*cm,fill=1)
#PDF generieren und speichern
pdf.showPage()
pdf.save()

Der obige Code zeigt nur einen kleinen Ausschnitt der Möglichkeiten, Inhalt zum Canvas hinzuzufügen. ReportLab kennt noch weitere grafische Elemente: Bilder können eingebunden werden, Text kann in der Laufweite angepasst werden und vieles mehr. Bei der Positionierung der Element ist daran zu denken, dass der Nullpunkt einer Seite unten links ist, also wie in einem Kartesischen Koordinatensystem.

Möchte man auf diese Art ein mehrseitiges PDF generieren, so muss zwischendurch pdf.showPage() aufgerufen werden (siehe folgendes Beispiel).

Der Canvas erlaubt zwar eine sehr detaillierte Layout-Kontrolle, ist aber ansonsten vergleichsweise unkomfortable („low-level“), da z.B. langer Text nicht automatisch umgebrochen wird:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
#!/usr/bin/env python3

from reportlab.pdfgen import canvas
from reportlab.lib.pagesizes import A4
from reportlab.lib.units import cm

#Anlegen des PDF Dokuments, Seitengröße DIN A4 Hochformat)
pdf = canvas.Canvas('mein_pdf2.pdf',pagesize=A4)
#der folgende Text läuft rechts aus der Seite heraus
pdf.setFont('Helvetica',72)
pdf.drawString(100,400,'Dieser Text läuft rechts aus dem Dokuments heraus')
pdf.showPage()
#etwas mehr Text für Seite 2
pdf.drawString(200,200,'Seite 2 :-)')
pdf.showPage()
pdf.save()

Wer längeren Text hinzufügen möchte, der kann die im folgenden beschriebenen „Flowables“ benutzen.

Flowables

„Flowables“ sind in ReportLab Element, welche in das Dokument „fließen“ können. Im Gegensatz zu den direkte Zeichenoperationen auf den PDF-Canvas formatieren sich Flowables in Teilen selber. So werden z.B. automatisch Zeilenumbrüche bei längeren Texten erzeugt, ebenso werden automatisch Abstände zum vorhergehenden Element eingehalten - was aber optional, wie vieles in ReportLab, manuell beeinflusst werden kann.

Es gibt Flowables u.a. für Text, Grafiken, Kombinationen daraus, Tabellen und diverse andere Elemente.

Das folgende Beispiel zeigt, wie Flowables in Kombination mit dem Canvas genutzt werden können. Durch die Definition des „Frames“ entfällt die Positionierung der Elemente, da Flowables innerhalb des Frames automatisch fortlaufend angeordnet werden.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
#!/usr/bin/env python3

from reportlab.pdfgen import canvas
from reportlab.lib.units import cm
from reportlab.lib.pagesizes import A4, landscape
from reportlab.lib.styles import getSampleStyleSheet
from reportlab.platypus import Frame, Paragraph

#Anlegen des PDFs im DIN A4 Querformat
pdf = canvas.Canvas('mein_pdf3.pdf',pagesize=landscape(A4))
#Holen der Seitenabmessung
breite, hoehe = landscape(A4)
#Definieren der Styles
style = getSampleStyleSheet()
#Anlegen einer Liste, welche den Seiteninhalt enthält
story = []
#Anlegen des Frames, in den der Inhalt eingefügt wird
f = Frame(1*cm,1*cm,breite-(2*cm),hoehe-(2*cm))
#Generieren von Inhalt
story.append(Paragraph('Überschrift 1',style['Heading1']))
story.append(Paragraph('''Das ReportLab Toolkit ist ein Python-Modul zum
Generieren von PDF Dokumenten. Es bietet zahlreiche Klassen und Funktionen
zur detaillierten Kontrolle des Inhalts und des Layouts. Weiterhin gibt es 
Klassen zur Generierung von Diagrammen. Das ReportLab Toolkit steht
unter einer freien OpenSource Lizenz.''',
style['BodyText']))
story.append(Paragraph('Überschrift 2',style['Heading2']))
#Hinzufügen des Inhalts
f.addFromList(story,pdf)
#...und abspeichern
pdf.save()

Flowables können natürlich auch mit den anderen Canvas-Elementen kombiniert werden.

Allerdings werden so immer noch keine automatischen Seitenumbrüche erzeugt. Generiert man mehr Inhalt, fließt der Text unten aus der Seite hinaus. Es gibt zwar Funktionen, die den vorhandenen Restplatz auf einer Seite bestimmen können, ebenso ist der benötigte Platz eines Flowables abrufbar. Aber es ist recht mühsam, so selber Seitenumbrüche zu erzeugen, so dass man bei längeren Texten besser zum im Folgenden beschriebenen Platypus greift.

Platypus

Platypus steht für „Page Layout and Typography Using Scripts“, was frei übersetzt so viel wie „automatisches Layout per Skript“ bedeutet. Hier wird ebenfalls auf Flowables als Inhaltselemente zurückgegriffen, zusätzlich wird aber noch eine Dokumentenvorlage definiert, welche das Gesamtlayout bestimmt.

Im folgenden Beispiel wird dies mit Hilfe der vordefinierter Vorlage „SimpleDocTemplate“ realisiert:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
#!/usr/bin/env python3

from reportlab.lib.pagesizes import A4
from reportlab.lib.styles import getSampleStyleSheet
from reportlab.platypus import Paragraph, SimpleDocTemplate, PageBreak

#Definieren der Styles
style = getSampleStyleSheet()
#Anlegen einer Liste, welche den Seiteninhalt enthält
story = []
#Generieren von Inhalt
story.append(Paragraph('Überschrift 1',style['Heading1']))
story.append(Paragraph('''Das ReportLab Toolkit ist ein Python-Modul zum
generieren von PDF Dokumenten. Es bietet zahlreiche Klassen und Funktionen
zur detaillierten Kontrolle des Inhalts und des Layouts. Weiterhin gibt es 
Klassen zur Generierung von Diagrammen.''',style['BodyText']))
story.append(PageBreak())
story.append(Paragraph('Überschrift 2',style['Heading2']))
story.append(Paragraph(''' Das ReportLab Toolkit steht unter einer freien 
OpenSource Lizenz.''',style['BodyText']))
#Anlegen des PDFs
pdf = SimpleDocTemplate('mein_pdf4.pdf',pagesize=A4)
pdf.build(story)

Dies ist, wie gesagt, der einfachste Fall, da im SimpleDocTemplate bereits alle wichtigen Dinge vorkonfiguriert sind.

Eine wesentlich detaillierte Kontrolle lässt die Verwendung des „BaseDocTemplate“ zu. Hier können innerhalb eines Dokuments beliebige und beliebig viele Seitenvorlagen angelegt werden. Die Seitenvorlagen können wiederum beliebig definierte Frames enthalten. Somit sind auch komplexere Layouts mit mehreren Spalten, Wechsel zwischen Hoch- und Querformat innerhalb eines Dokuments, unterschiedlichen Rändern für linke und rechte Seiten und vieles mehr möglich. Außerdem kann eine feste Kopf- und Fußzeile pro Seite definiert werden, welche immer automatisch hinzugefügt wird.

Diagramme generieren

Neben den oben vorgestellten Möglichkeiten zum generieren von PDFs bietet ReportLab auch Module an, mit welchen sich Diagramme generieren lassen. Diese lassen sich dann entweder als Bild- oder Vektordatei speichern oder direkt in ein mit ReportLab erzeugtes PDF einbauen. Es werden alle gängigen Arten wie Linie-, Balken und Tortendiagramm angeboten.

Das folgende Beispiel erstellt ein einfaches Balkendiagramm:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
#!/usr/bin/env python3

from reportlab.graphics.shapes import Drawing
from reportlab.graphics.charts.barcharts import VerticalBarChart
from reportlab.graphics import renderPM

#Festlegen der Gesamtgröße in Pixel
d = Drawing(400,300)
#Daten für das Diagramm
daten = [(10,6,8),(4,12,7)]
#Anlegen des Diagramms
diagramm = VerticalBarChart()
#Positionierung und Größe des Diagramms
diagramm.x = 50
diagramm.y = 50
diagramm.height = 200
diagramm.width = 300
#Hinzufügen der Daten
diagramm.data = daten
#Y-Achse (in ReportLab „valueAxis“) formatieren
diagramm.valueAxis.valueMin = 0
diagramm.valueAxis.valueMax = 16
diagramm.valueAxis.valueStep = 2
#X-Achse (in ReportLab „categoryAxis“) formatieren
diagramm.categoryAxis.categoryNames = ['A','B','C']
#Diagramm zeichnen
d.add(diagramm)
#... und speichernhttp://www.reportlab.com/software/opensource/rl-toolkit/guide/
renderPM.drawToFile(d, 'diagramm1.png', 'PNG')

Als Ausgabeformat wurde PNG gewählt, möglich sind aber u.a. auch JPG, PDF oder SVG.

ReportLab bietet weitreichende Formatierungsmöglichkeiten, sowohl die Daten, die Achsen als auch die Legende. Weitere Informationen findet man z.B. in der Dokumentation.

Dokumentation

Wie weiter oben bereits erwähnt zeigen alle Beispiele nur einen kleine Ausschnitt der Möglichkeiten des ReportLab Toolkits. Wer sich näher damit beschäftigen möchte, dem sei die offizielle Dokumentation 🇬🇧 empfohlen, welche als PDF-Dokument heruntergeladen werden kann.

Alternativ kann man sich auch die Dokumentation über die Paketverwaltung installieren:

Paketliste zum Kopieren:

sudo apt-get install python-reportlab-doc 

Oder mit apturl die Pakete installieren. Link: apt://python-reportlab-doc