reportlab

ReportLab による PDF 生成

概要

ReportLab は、プログラムから PDF を生成するための強力な Python ライブラリです。シンプルな文書から、表、グラフ、画像、インタラクティブフォームを含む複雑なレポートまで作成できます。

主なアプローチは 2 つあります：

• Canvas API（低レベル）：座標ベースで位置を指定して直接描画します。精密なレイアウトに適しています
• Platypus（高レベル）：ページ区切りを自動で行う、流し込み型の文書レイアウトです。複数ページの文書に適しています

主な機能：

• 豊富な書式設定とカスタムフォントを使ったテキスト
• 複雑なスタイル設定やセル結合に対応した表
• グラフ（棒、折れ線、円、面、散布図）
• バーコードと QR コード（Code128、EAN、QR など）
• 透過画像
• PDF 機能（リンク、ブックマーク、フォーム、暗号化）

適切なアプローチの選び方

Canvas API を使う場合：

• ラベル、名刺、証明書を作成する
• 正確な位置指定（x、y 座標）が重要である
• 単一ページの文書やシンプルなレイアウトを作成する
• グラフィック、図形、カスタムデザインを描画する
• 特定の位置にバーコードや QR コードを追加する

Platypus を使う場合：

• 複数ページの文書（レポート、記事、書籍）を作成する
• コンテンツをページ間で自動的に流し込む必要がある
• 各ページに繰り返し表示するヘッダー／フッターが必要である
• ページをまたいで分割できる段落を扱う
• 目次を含む複雑な文書を作成する

両方を使う場合：

• 複雑なレポートで、流し込み型のコンテンツと精密な位置指定の両方が必要である
• Platypus 文書にヘッダー／フッターを追加する（Canvas の onPage コールバックを使用）
• 流し込み型の文書（Platypus）にカスタムグラフィック（Canvas）を埋め込む

クイックスタートの例

シンプルな Canvas 文書

from reportlab.pdfgen import canvas
from reportlab.lib.pagesizes import letter
from reportlab.lib.units import inch

c = canvas.Canvas("output.pdf", pagesize=letter)
width, height = letter

# Draw text
c.setFont("Helvetica-Bold", 24)
c.drawString(inch, height - inch, "Hello ReportLab!")

# Draw a rectangle
c.setFillColorRGB(0.2, 0.4, 0.8)
c.rect(inch, 5*inch, 4*inch, 2*inch, fill=1)

# Save
c.showPage()
c.save()

シンプルな Platypus 文書

from reportlab.lib.pagesizes import letter
from reportlab.platypus import SimpleDocTemplate, Paragraph, Spacer
from reportlab.lib.styles import getSampleStyleSheet
from reportlab.lib.units import inch

doc = SimpleDocTemplate("output.pdf", pagesize=letter)
story = []
styles = getSampleStyleSheet()

# Add content
story.append(Paragraph("Document Title", styles['Title']))
story.append(Spacer(1, 0.2*inch))
story.append(Paragraph("This is body text with <b>bold</b> and <i>italic</i>.", styles['BodyText']))

# Build PDF
doc.build(story)

よくあるタスク

表の作成

表は Canvas（Drawing 経由）と Platypus（Flowable として）の両方で使用できます：

from reportlab.platypus import Table, TableStyle
from reportlab.lib import colors
from reportlab.lib.units import inch

# Define data
data = [
    ['Product', 'Q1', 'Q2', 'Q3', 'Q4'],
    ['Widget A', '100', '150', '130', '180'],
    ['Widget B', '80', '120', '110', '160'],
]

# Create table
table = Table(data, colWidths=[2*inch, 1*inch, 1*inch, 1*inch, 1*inch])

# Apply styling
style = TableStyle([
    # Header row
    ('BACKGROUND', (0, 0), (-1, 0), colors.darkblue),
    ('TEXTCOLOR', (0, 0), (-1, 0), colors.whitesmoke),
    ('FONTNAME', (0, 0), (-1, 0), 'Helvetica-Bold'),
    ('ALIGN', (0, 0), (-1, -1), 'CENTER'),

    # Data rows
    ('ROWBACKGROUNDS', (0, 1), (-1, -1), [colors.white, colors.lightgrey]),
    ('GRID', (0, 0), (-1, -1), 1, colors.black),
])

table.setStyle(style)

# Add to Platypus story
story.append(table)

# Or draw on Canvas
table.wrapOn(c, width, height)
table.drawOn(c, x, y)

表の詳細リファレンス： セル結合、罫線、配置、高度なスタイル設定については、references/tables_reference.md を参照してください。

グラフの作成

グラフはグラフィックスフレームワークを使用し、Canvas と Platypus の両方に追加できます：

from reportlab.graphics.shapes import Drawing
from reportlab.graphics.charts.barcharts import VerticalBarChart
from reportlab.lib import colors

# Create drawing
drawing = Drawing(400, 200)

# Create chart
chart = VerticalBarChart()
chart.x = 50
chart.y = 50
chart.width = 300
chart.height = 125

# Set data
chart.data = [[100, 150, 130, 180, 140]]
chart.categoryAxis.categoryNames = ['Q1', 'Q2', 'Q3', 'Q4', 'Q5']

# Style
chart.bars[0].fillColor = colors.blue
chart.valueAxis.valueMin = 0
chart.valueAxis.valueMax = 200

# Add to drawing
drawing.add(chart)

# Use in Platypus
story.append(drawing)

# Or render directly to PDF
from reportlab.graphics import renderPDF
renderPDF.drawToFile(drawing, 'chart.pdf', 'Chart Title')

使用可能なグラフの種類： 棒（縦／横）、折れ線、円、面、散布図 グラフの詳細リファレンス： すべてのグラフの種類、スタイル設定、凡例、カスタマイズについては、references/charts_reference.md を参照してください。

バーコードと QR コードの追加

from reportlab.graphics.barcode import code128
from reportlab.graphics.barcode.qr import QrCodeWidget
from reportlab.graphics.shapes import Drawing
from reportlab.graphics import renderPDF

# Code128 barcode (general purpose)
barcode = code128.Code128("ABC123456789", barHeight=0.5*inch)

# On Canvas
barcode.drawOn(c, x, y)

# QR Code
qr = QrCodeWidget("https://example.com")
qr.barWidth = 2*inch
qr.barHeight = 2*inch

# Wrap in Drawing for Platypus
d = Drawing()
d.add(qr)
story.append(d)

対応形式： Code128、Code39、EAN-13、EAN-8、UPC-A、ISBN、QR、Data Matrix など、ほか 20 種類以上 バーコードの詳細リファレンス： すべての形式と使用例については、references/barcodes_reference.md を参照してください。

テキストとフォントの操作

from reportlab.platypus import Paragraph
from reportlab.lib.styles import ParagraphStyle
from reportlab.lib.enums import TA_JUSTIFY

# Create custom style
custom_style = ParagraphStyle(
    'CustomStyle',
    fontSize=12,
    leading=14,           # Line spacing
    alignment=TA_JUSTIFY,
    spaceAfter=10,
    textColor=colors.black,
)

# Paragraph with inline formatting
text = """
This paragraph has <b>bold</b>, <i>italic</i>, and <u>underlined</u> text.
You can also use <font color="blue">colors</font> and <font size="14">different sizes</font>.
Chemical formula: H<sub>2</sub>O, Einstein: E=mc<sup>2</sup>
"""

para = Paragraph(text, custom_style)
story.append(para)

カスタムフォントの使用：

from reportlab.pdfbase import pdfmetrics
from reportlab.pdfbase.ttfonts import TTFont

# Register TrueType font
pdfmetrics.registerFont(TTFont('CustomFont', 'CustomFont.ttf'))

# Use in Canvas
c.setFont('CustomFont', 12)

# Use in Paragraph style
style = ParagraphStyle('Custom', fontName='CustomFont', fontSize=12)

テキストの詳細リファレンス： 段落スタイル、フォントファミリー、アジア言語、ギリシャ文字、書式設定については、references/text_and_fonts.md を参照してください。

画像の追加

from reportlab.platypus import Image
from reportlab.lib.units import inch

# In Platypus
img = Image('photo.jpg', width=4*inch, height=3*inch)
story.append(img)

# Maintain aspect ratio
img = Image('photo.jpg', width=4*inch, height=3*inch, kind='proportional')

# In Canvas
c.drawImage('photo.jpg', x, y, width=4*inch, height=3*inch)

# With transparency (mask white background)
c.drawImage('logo.png', x, y, mask=[255,255,255,255,255,255])

フォームの作成

from reportlab.pdfgen import canvas
from reportlab.lib.colors import black, white, lightgrey

c = canvas.Canvas("form.pdf")

# Text field
c.acroForm.textfield(
    name="name",
    tooltip="Enter your name",
    x=100, y=700,
    width=200, height=20,
    borderColor=black,
    fillColor=lightgrey,
    forceBorder=True
)

# Checkbox
c.acroForm.checkbox(
    name="agree",
    x=100, y=650,
    size=20,
    buttonStyle='check',
    checked=False
)

# Dropdown
c.acroForm.choice(
    name="country",
    x=100, y=600,
    width=150, height=20,
    options=[("United States", "US"), ("Canada", "CA")],
    forceBorder=True
)

c.save()

PDF 機能の詳細リファレンス： フォーム、リンク、ブックマーク、暗号化、メタデータについては、references/pdf_features.md を参照してください。

ヘッダーとフッター

Platypus 文書では、ページコールバックを使用します：

from reportlab.platypus import BaseDocTemplate, PageTemplate, Frame

def add_header_footer(canvas, doc):
    """Called on each page"""
    canvas.saveState()

    # Header
    canvas.setFont('Helvetica', 9)
    canvas.drawString(inch, height - 0.5*inch, "Document Title")

    # Footer
    canvas.drawRightString(width - inch, 0.5*inch, f"Page {doc.page}")

    canvas.restoreState()

# Set up document
doc = BaseDocTemplate("output.pdf")
frame = Frame(doc.leftMargin, doc.bottomMargin, doc.width, doc.height, id='normal')
template = PageTemplate(id='normal', frames=[frame], onPage=add_header_footer)
doc.addPageTemplates([template])

# Build with story
doc.build(story)

ヘルパースクリプト

このスキルには、よくあるタスク向けのヘルパースクリプトが含まれています：

クイック文書ジェネレーター

文書をすばやく作成するには、scripts/quick_document.py を使用します：

from scripts.quick_document import create_simple_document, create_styled_table

# Simple document from content blocks
content = [
    {'type': 'heading', 'content': 'Introduction'},
    {'type': 'paragraph', 'content': 'Your text here...'},
    {'type': 'bullet', 'content': 'Bullet point'},
]

create_simple_document("output.pdf", "My Document", content_blocks=content)

# Styled tables with presets
data = [['Header1', 'Header2'], ['Data1', 'Data2']]
table = create_styled_table(data, style_name='striped')  # 'default', 'striped', 'minimal', 'report'

テンプレートの例

assets/ に、すぐに動作する完全な例があります：

請求書テンプレート

assets/invoice_template.py - 以下を含む、プロフェッショナルな請求書です：

• 会社およびクライアント情報
• 計算機能付きの明細表
• 税額と合計
• 利用条件と注記
• ロゴの配置

from assets.invoice_template import create_invoice

create_invoice(
    filename="invoice.pdf",
    invoice_number="INV-2024-001",
    invoice_date="January 15, 2024",
    due_date="February 15, 2024",
    company_info={'name': 'Acme Corp', 'address': '...', 'phone': '...', 'email': '...'},
    client_info={'name': 'Client Name', ...},
    items=[
        {'description': 'Service', 'quantity': 1, 'unit_price': 500.00},
        ...
    ],
    tax_rate=0.08,
    notes="Thank you for your business!",
)

レポートテンプレート

assets/report_template.py - 以下を含む、複数ページのビジネスレポートです：

• 表紙
• 目次
• サブセクションを含む複数のセクション
• グラフと表
• ヘッダーとフッター

from assets.report_template import create_report

report_data = {
    'title': 'Quarterly Report',
    'subtitle': 'Q4 2023',
    'author': 'Analytics Team',
    'sections': [
        {
            'title': 'Executive Summary',
            'content': 'Report content...',
            'table_data': {...},
            'chart_data': {...}
        },
        ...
    ]
}

create_report("report.pdf", report_data)

リファレンスドキュメント

機能別に整理された包括的な API リファレンスです。

• references/canvas_api.md - 低レベルの Canvas：描画プリミティブ、座標、変換、状態管理、画像、パス
• references/platypus_guide.md - 高レベルの Platypus：ドキュメントテンプレート、フレーム、フローアブル、ページレイアウト、目次
• references/text_and_fonts.md - テキスト書式設定：段落スタイル、インラインマークアップ、カスタムフォント、アジア言語、箇条書き、シーケンス
• references/tables_reference.md - 表：作成、スタイル設定、セル結合、罫線、配置、色、グラデーション
• references/charts_reference.md - グラフ：すべてのグラフの種類、データ処理、軸、凡例、色、レンダリング
• references/barcodes_reference.md - バーコード：Code128、QR コード、EAN、UPC、郵便番号、その他 20 種類以上の形式
• references/pdf_features.md - PDF 機能：リンク、ブックマーク、フォーム、暗号化、メタデータ、ページ遷移

ベストプラクティス

座標系（Canvas）

• 原点 (0, 0) は左下隅です（左上ではありません）
• Y 軸は上向きです
• 単位はポイントです（72 ポイント = 1 インチ）
• ページサイズは必ず明示的に指定してください

from reportlab.lib.pagesizes import letter
from reportlab.lib.units import inch

width, height = letter
margin = inch

# Top of page
y_top = height - margin

# Bottom of page
y_bottom = margin

ページサイズの選択

from reportlab.lib.pagesizes import letter, A4, landscape

# US Letter (8.5" x 11")
pagesize=letter

# ISO A4 (210mm x 297mm)
pagesize=A4

# Landscape
pagesize=landscape(letter)

# Custom
pagesize=(6*inch, 9*inch)

パフォーマンスのヒント

1. drawInlineImage() ではなく drawImage() を使います - 画像をキャッシュして再利用できます
2. 大きなファイルでは圧縮を有効にします： canvas.Canvas("file.pdf", pageCompression=1)
3. スタイルを再利用します - 一度作成し、ドキュメント全体で使用します
4. 繰り返し使用するグラフィックには Forms/XObjects を使います

よく使われるパターン

Canvas 上でテキストを中央揃えにする：

text = "Centered Text"
text_width = c.stringWidth(text, "Helvetica", 12)
x = (width - text_width) / 2
c.drawString(x, y, text)

# Or use built-in
c.drawCentredString(width/2, y, text)

Platypus で改ページする：

from reportlab.platypus import PageBreak

story.append(PageBreak())

コンテンツを分割せずにまとめる：

from reportlab.platypus import KeepTogether

story.append(KeepTogether([
    heading,
    paragraph1,
    paragraph2,
]))

行の色を交互にする：

style = TableStyle([
    ('ROWBACKGROUNDS', (0, 1), (-1, -1), [colors.white, colors.lightgrey]),
])

トラブルシューティング

テキストが重なったり、表示されなかったりする場合：

• Y 座標を確認してください。原点は左下です
• テキストがページの範囲内に収まっていることを確認してください
• leading（行間）が fontSize より大きいことを確認してください

表がページに収まらない場合：

• 列幅を狭くしてください
• フォントサイズを小さくしてください
• 横向きのページを使用してください
• repeatRows で表の分割を有効にしてください

バーコードを読み取れない場合：

• barHeight を大きくしてください（最低でも 0.5 インチを試してください）
• クワイエットゾーンには quiet=1 を設定してください
• 印刷品質を確認してください（300 DPI 以上を推奨）
• バーコードの種類に応じたデータ形式を検証してください

フォントが見つからない場合：

• pdfmetrics.registerFont() で TrueType フォントを登録してください
• 登録時と同じフォントファミリー名を使用してください
• フォントファイルのパスが正しいことを確認してください

画像に白い背景がある場合：

• mask パラメーターを使って白を透明にしてください
• マスクする RGB 範囲を指定してください：mask=[255,255,255,255,255,255]
• または、アルファチャンネル付きの PNG を使用してください

ワークフローの例

請求書の作成

1. assets/invoice_template.py の請求書テンプレートを使用します
2. 会社情報とロゴのパスをカスタマイズします
3. 説明、数量、価格を添えて項目を追加します
4. 該当する場合は税率を設定します
5. 備考と支払い条件を追加します
6. PDF を生成します

レポートの作成

1. assets/report_template.py のレポートテンプレートを使用します
2. タイトルと内容を含むセクションを定義します
3. create_styled_table() を使ってデータ用の表を追加します
4. グラフィックスフレームワークを使ってグラフを追加します
5. 目次を作成するには doc.multiBuild(story) でビルドします

証明書の作成

1. 正確な配置には Canvas API を使用します
2. 優雅なタイポグラフィにはカスタムフォントを読み込みます
3. 罫線のグラフィックまたは背景画像を追加します
4. テキスト要素（氏名、日付、実績）を配置します
5. 任意：検証用に QR コードを追加します

バーコード付きラベルの作成

1. カスタムページサイズ（ラベルの寸法）で Canvas を使用します
2. 1 ページに複数のラベルを配置するためのグリッド位置を計算します
3. ラベルの内容（テキスト、画像）を描画します
4. 指定位置にバーコードを追加します
5. ラベルまたはグリッドの間で showPage() を使用します

インストール

uv pip install reportlab

# For image support
uv pip install pillow

# For charts
uv pip install reportlab[renderPM]

# For barcode support (included in reportlab)
# QR codes require: uv pip install qrcode

このスキルを使用する場面

このスキルは、次の場合に使用してください。

• プログラムで PDF ドキュメントを生成する
• 請求書、領収書、請求関連ドキュメントを作成する
• 表やチャートを含むレポートを作成する
• 証明書、バッジ、資格証明書を生成する
• バーコード付きの配送ラベルや商品ラベルを作成する
• フォームや入力可能な PDF をデザインする
• 一貫した書式で複数ページのドキュメントを作成する
• 保存や配布のためにデータを PDF 形式に変換する
• 正確な配置が必要なカスタムレイアウトを作成する

このスキルでは、シンプルなドキュメントから、チャート、表、インタラクティブ要素を含む複雑な複数ページのレポートまで、ReportLab のすべての機能について包括的なガイダンスを提供します。