[[Vorlage(getestet, focal, bionic)]] {{{#!vorlage Wissen [:Pakete installieren: Installation von Programmen] [:mit Root-Rechten arbeiten:] (optional) [:Packprogramme: Archive entpacken] (optional) }}} [[Inhaltsverzeichnis()]] [[Bild(Wiki/Icons/python.png, 48, align=left)]] [http://www.reportlab.com/software/opensource/ ReportLab] {en} 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 [http://www.reportlab.com ReportLab] {en} 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 [wikipedia_en:Portable_Document_Format#Adobe.27s_versions: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. 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: {{{#!vorlage Paketinstallation python3-reportlab }}} installiert werden[1]. == manuelle Installation == Wer eine neuere bzw. die aktuelle Version als die aus den Paketquellen benötigt, kann diese via [:pip:] installierenDabei wird auch die Python-Bibliothek [https://pypi.python.org/pypi/Pillow Pillow] {en} mit installiert, welche wieder voraussetzt, dass die Pakete '''build-essential''', '''python3-dev''', '''libjpeg8-dev''', '''zlib1g-dev''' installiert sind. == Schriften installieren == {{{#!vorlage Hinweis Die manuelle Installation von Schriften ist nur notwendig, wenn man [#Diagramme-generieren 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 [http://www.reportlab.com/ftp/fonts/pfbfer.zip ReportLab Seite] {dl} 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: {{{#!code python #!/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 [wikipedia:Kartesisches_Koordinatensystem: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: {{{#!code python #!/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. {{{#!code python #!/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: {{{#!code python #!/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: {{{#!code python #!/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 [http://www.reportlab.com/software/opensource/rl-toolkit/guide/ offizielle Dokumentation] {en} empfohlen, welche als PDF-Dokument heruntergeladen werden kann. Alternativ kann man sich auch die Dokumentation über die Paketverwaltung installieren: {{{#!vorlage Paketinstallation python3-reportlab-doc }}} = Links = * [http://www.reportlab.com/apis/reportlab/ API-Referenz] {en} * [http://www.reportlab.com/snippets/ Code-Schnipsel] {en}: nützliche Beispiele für die Nutzung von ReportLab * [http://rst2pdf.ralsina.me/stories/index.html rst2pdf] {en}: Textsatzsystem für die Umwandlung von [wikipedia:reStructuredText:] über ReportLab in druckfertige PDFs #tag: Programmierung, Python, PDF