ReportLab 导出 PDF（文档创建）
ReportLab 导出 PDF（页面布局）
ReportLab 导出 PDF（图文表格)

1. 设计目标

Platypus 是"Page Layout and Typography Using Scripts"的缩写。它是一个高水平的页面布局库， 让你可以用最少的努力以编程方式创建复杂的文档。
Platypus 的设计力求将 "高层次 "的布局决定与文档内容尽可能分开 。例如，段落使用段落样式，页面使用页面模板，目的是让数百个有数千页的文件可以按照不同的样式规格重新格式化，只需在一个包含段落样式和页面布局规格的共享文件中修改几行即可。
Platypus的整体设计可以认为有几个层次，自上而下，这些是:
• DocTemplates 作为文档的最外层容器。
• PageTemplates 作为各种页面布局的规格。
• Frames 页面中可包含流动文本或图形的区域规格。
• Flowables 对应"flowed into the document"流入文档的文本或图形元素（即图像、段落和表格等内容，但不包括页脚或固定页面图形等内容）。
pdfgen.Canvas 为最终从其他图层接收文档绘画的最低层。

上面的插图形象地说明了 DocTemplate、PageTemplate 和 Flowables 的概念 。然而，它具有欺骗性，因为每一个 PageTemplate 实际上可以指定任何数量的页面的格式（而不是像从图中推断的那样只指定一个）。
DocTemplate 包含一个或多个 PageTemplate，每个 PageTemplate 包含一个或多个Frame。
Flowables 是指可以 flowed(流入) Frame的东西，例如 Paragraph 或 Table。
要使用 platypus，你需要从 DocTemplate 类中创建一个文档，并向其 build 方法传递一个 Flowables列表。document 的 build 方法知道如何将 flowable 列表处理成合理的东西。
在内部，DocTemplate 类使用各种事件来实现页面布局和格式化。每个事件都有一个对应的处理方法，称为 handle_XXX ，其中 XXX 是事件名称。一个典型的事件是 frameBegin，它发生在机械开始第一次使用一个框架的时候。
Platypus 故事由一系列基本元素组成，这些元素被称为 Flowables，它们驱动着数据驱动的 Platypus格式化引擎。为了修改引擎的行为，一种特殊的可流式元素 ActionFlowables 告诉布局引擎，例如，跳到下一列或者换成另一个 PageTemplate。

2. 开始

考虑以下代码序列，它为 Platypus 提供了一个非常简单的 "hello world "例子。

from reportlab.platypus import SimpleDocTemplate, Paragraph, Spacer
from reportlab.lib.styles import getSampleStyleSheet
from reportlab.rl_config import defaultPageSize
from reportlab.lib.units import inch

PAGE_HEIGHT=defaultPageSize[1]
PAGE_WIDTH=defaultPageSize[0]

styles = getSampleStyleSheet()
Title = "Hello world"
pageinfo = "platypus example"

# 首页
def myFirstPage(canvas, doc):
    canvas.saveState()
    # 标题
    canvas.setFont('Times-Bold',16)
    canvas.drawCentredString(PAGE_WIDTH/2.0, PAGE_HEIGHT-108, Title)
    # 页脚 填充固定字符
    canvas.setFont('Times-Roman',9)
    canvas.drawString(inch, 0.75 * inch, "First Page / %s" % pageinfo)
    canvas.restoreState()

# 非首页
def myLaterPages(canvas, doc):
    canvas.saveState()
    # 页脚 填充页码
    canvas.setFont('Times-Roman',9)
    canvas.drawString(inch, 0.75 * inch, "Page %d %s" % (doc.page, pageinfo))
    canvas.restoreState()

def main(filename: str):
    doc = SimpleDocTemplate(filename)

    # 与标题间隔
    Story = [Spacer(1, 2*inch)]
    style = styles["Normal"]
    for i in range(100):
        bogustext = ("This is Paragraph number %s. " % i) * 5
        p = Paragraph(bogustext, style)
        Story.append(p)
        # 段落之间间隔
        Story.append(Spacer(1, 0.2*inch))
    # 添加
    doc.build(Story, onFirstPage=myFirstPage, onLaterPages=myLaterPages)

if __name__ == '__main__':
    main(filename='example.pdf')

我们创建一个"store"并构建文档。请注意，我们在这里使用的是"canned"(罐头)文档模板，它是预建的页面模板。
我们还使用了预建的段落样式 。
我们在这里只使用了两种类型的"flowables"–Spacers和Paragraphs 。第一个Spacer确保段落跳过标题字符串。

3. Flowables

Flowables 是可以被绘制的东西，它有wrap, draw和可能的split方法。Flowable 是一个抽象的基类，用于绘制事物，一个实例知道它的大小，并在它自己的坐标系中绘制(这需要基 API 在调用 Flowable.draw方法时提供一个绝对坐标系)。要获得一个实例，使用 f=Flowable()。
注意： Flowable 类是一个抽象类，通常只作为基类使用.
为了说明使用 Flowables 的一般方式，我们将展示如何在画布上使用和绘制衍生类 Paragraph。

def main(filename):
    from reportlab.lib.styles import getSampleStyleSheet
    from reportlab.platypus import Paragraph
    from reportlab.pdfgen.canvas import Canvas
    
    styleSheet = getSampleStyleSheet()
    style = styleSheet['BodyText']
    P=Paragraph('This is a very silly example',style)
    canv = Canvas(filename)
    aW = 460 # available width and height
    aH = 800
    w,h = P.wrap(aW, aH) # find required space
    if w<=aW and h<=aH:
        P.drawOn(canv,0,aH)
        aH = aH - h # reduce the available height
        canv.save()
    else:
        raise ValueError("Not enough room")

if __name__ == '__main__':
    main(filename='example.pdf')

3.1. Flowable.draw()

这将被调用来要求 flowable 实际渲染自己。Flowable类没有实现draw。调用代码应该确保 flowable 有一个属性canv，它pdfgen.Canvas，它应该被绘制到Canvas上，并且Canvas处于一个适当的状态(就翻译、旋转等而言)。通常这个方法只在内部被drawOn方法调用，派生类必须实现这个方法。派生类必须实现这个方法。

3.2. Flowable.drawOn(canvas,x,y)

这是控制引擎用来将flowable渲染到特定画布的方法。它处理转换为画布坐标(x,y)，并确保flowable有一个canv属性，这样draw方法(在基类中没有实现)就可以在一个绝对坐标框架中渲染。

3.3. Flowable.wrap(availWidth, availHeight)

在询问对象的大小、绘制或其他什么之前，这个函数将被包围的框架调用。它返回实际使用的尺寸。

3.4. Flowable.split(self, availWidth, availheight)

当wrap失败时，更复杂的框架会调用这个函数。愚蠢的flowables应该返回[],这意味着它们无法拆分。聪明的flowables应该自己拆分并返回一个flowables列表。客户端代码要确保避免重复尝试拆分。如果空间足够，拆分方法应该返回[self]。否则，flowable应该重新排列，并返回一个按顺序考虑的flowable列表[f0,…]。实现的拆分方法应该避免改变self，因为这将允许复杂的布局机制在一个可流动的列表上进行多次递。

4. 流动定位的准则

有两种方法，默认情况下返回零，为可流动物的垂直间距提供指导。
Flowable.getSpaceAfter(self):
Flowable.getSpaceBefore(self):
这些方法会返回flowable后面或前面应该有多少空间。这些空间不属于flowable本身，也就是说，flowable的draw方法在渲染时不应该考虑它。控制程序将使用返回的值来确定上下文中特定flowable需要多少空间。
所有的flowables都有一个hAlign属性：(‘LEFT’,‘RIGHT’,‘CENTER’或’CENTRE’)。对于占满整个框架宽度的段落，这个属性没有影响。对于小于框架宽度的表格、图像或其他对象，这决定了它们的水平位置。
下面的章节将涵盖最重要的特定类型的可流动文件，段落和表格。

5. Frames

Frames是活动的容器，它本身就包含在PageTemplate中，Frames有一个位置和大小，并保持一个剩余可绘制空间的概念。如：

Frame(x1, y1, width, height, leftPadding=6, bottomPadding=6, rightPadding=6, topPadding=6, id=None, showBoundary=0)

创建一个左下角坐标为(x1,y1)的Frame实例(在使用时相对于画布)，尺寸为 width x height。Padding参数是用于减少绘画空间的正量。参数id是运行时使用的标识符，例如"LeftColumn"或"RightColumn"等。如果showBoundary参数是非零，那么框架的边界将在运行时被绘制出来（这有时很有用）。
Frames可以直接与canvases和flowables一起使用来创建文档。Frame.addFromList方法为你处理wrap 和 drawOn调用。你不需要所有的Platypus引擎来获得有用的东西到PDF中。

def main(filename): 
    from reportlab.pdfgen.canvas import Canvas
    from reportlab.lib.styles import getSampleStyleSheet
    from reportlab.lib.units import inch
    from reportlab.platypus import Paragraph, Frame
    
    styles = getSampleStyleSheet()
    styleN = styles['Normal']
    styleH = styles['Heading1']
    story = []
    #add some flowables
    story.append(Paragraph("This is a Heading",styleH))
    story.append(Paragraph("This is a paragraph in <i>Normal</i> style.",styleN))
    c = Canvas(filename)
    f = Frame(inch, inch, 6*inch, 9*inch, showBoundary=1)
    f.addFromList(story,c)
    c.save()

if __name__ == '__main__':
    main(filename='example.pdf')

5.1. Frame.addFromList(drawlist, canvas)

消耗drawlist前面的Flowables，直到帧满为止。如果不能容纳一个对象，则引发一个异常。

5.2. Frame.split(flowable,canv)

要求flowable使用可用空间进行分割，并返回flowable的列表。

5.3. Frame.drawBoundary(canvas)

将框架边界画成一个矩形（主要用于调试）。

6. 文档和模板

BaseDocTemplate类
实现了文档格式化的基本机制。该类的一个实例包含了一个或多个PageTemplate的列表，这些PageTemplate可用于描述单页信息的布局。build方法可用于处理Flowables列表，以生成一个PDF文档。

from reportlab.lib.pagesizes import A4
from reportlab.platypus import BaseDocTemplate
from reportlab.lib.units import inch

BaseDocTemplate(filename,
                pagesize=A4,
                pageTemplates=[],
                showBoundary=0,		# 控制是否绘制Frame的边界，这对于调试来说是很有用的
                leftMargin=inch,
                rightMargin=inch,
                topMargin=inch,
                bottomMargin=inch,
                allowSplitting=1,	# allowSplitting参数决定了内置方法是否应该尝试split单个Flowables跨越Frame
                title=None,
                author=None,
                _pageBreakQuick=1,	# 参数决定了在结束页面之前，是否应该尝试结束页面上的所有框架
                encrypt=None		# encrypt 参数决定了是否对文档进行加密，以及如何加密
                )

创建一个适合创建基本文档的文档模板。它带有相当多的内部机制，但没有默认的页面模板。所需的filename可以是一个字符串，一个用于接收创建的PDF文档的文件名；也可以是一个有write方法的对象，如 BytesIO 或 file 或 socket。
showBoundary控制是否绘制Frame的边界，这对于调试来说是很有用的。
allowSplitting参数决定了内置方法是否应该尝试split单个Flowables跨越Frame。
_pageBreakQuick参数决定了在结束页面之前，是否应该尝试结束页面上的所有框架。
encrypt 参数决定了是否对文档进行加密，以及如何加密。默认情况下，文档是不加密的。如果encrypt是一个字符串对象，那么它将作为pdf的用户密码。如果encrypt是一个reportlab.lib.pdfencrypt.StandardEncryption的实例，那么这个对象就被用来加密pdf。这允许对加密设置进行更精细的控制。

PageTemplate类
是一个语义相当简单的容器类。每个实例都包含一个Frames的列表，并且有一些方法应该在每个页面的开始和结束时被调用。

PageTemplate(id=None, frames=[], onPage=_doNothing, onPageEnd=_doNothing)

用于初始化一个实例，frames参数应该是一个Frames的列表，而可选的onPage和onPageEnd参数是可调用的，它们的签名应该是 def XXX(canvas,document)，其中canvas和document是正在绘制的画布和文档。这些例程的目的是用来绘制页面的非流动（即标准）部分。
这些属性函数与纯虚拟方法 PageTemplate.beforPage 和 PageTemplate.afterPage完全平行，这两个方法的签名是 beforPage(self,canvas,document)。这些方法允许使用类派生来定义标准行为，而属性则允许改变实例。在运行时，id 参数用于执行 PageTemplate 的切换，所以 id=‘FirstPage’ 或 id='TwoColumns’是典型的。

6.1. BaseDocTemplate.addPageTemplates(self,pageTemplates)

此方法用于在现有文档中添加一个或一系列PageTemplate。

6.2. BaseDocTemplate.build(self, flowables, filename=None,canvasmaker=canvas.Canvas)

这是应用程序程序员感兴趣的主要方法。假设文档实例被正确设置，build方法将story以flowables
列表的形式接收（flowables参数），并在列表中循环，将flowables列表一次一个地强制通过格式化
机制。实际上，这使得BaseDocTemplate实例发出对实例handle_XXX方法的调用来处理各种事件。

6.3. BaseDocTemplate.afterInit(self)

这个方法在基类初始化后被调用；派生类可以覆盖该方法来添加默认的PageTemplates。

6.4. BaseDocTemplate.afterPage(self)

这是在页面处理后，紧接着当前页面模板的afterDrawPage方法被调用。一个派生类可以使用这个方
法来做一些依赖于页面信息的事情，比如字典页面上的首字和尾字。

6.5. BaseDocTemplate.beforeDocument(self)

在对文档进行任何处理之前，但在处理机制准备好之后，就会调用这个函数，因此它可以用来对实
例的pdfgen.canvas等进行处理。因此，它可以用来对实例的pdfgen.canvas等进行操作。

6.6. BaseDocTemplate.beforePage(self)

这是在页面处理开始时，在当前页面模板的beforeDrawPage方法之前调用的。它可以用来重置页面
特定的信息持有者。

6.7. BaseDocTemplate.filterFlowables(self,flowables)

在主 handle_flowable 方法开始时，调用这个函数来过滤flowables。在返回时，如果flowables[0]
被设置为None，则会被丢弃，主方法立即返回。

6.8. BaseDocTemplate.afterFlowable(self, flowable)

在flowable被渲染后调用。有兴趣的类可以使用这个钩子来收集特定页面或框架上存在的信息。