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¶

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.

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:

• python-reportlab-doc

mit apturl

sudo apt-get install python-reportlab-doc 

sudo aptitude install python-reportlab-doc