ساخت PDF با ReportLab در پایتون: راهنمای جامع

ReportLab یک کتابخانه قدرتمند پایتون برای تولید فایل‌های PDF است. این کتابخانه به شما امکان می‌دهد تا اسناد پیچیده با متن، تصاویر، جداول و گرافیک‌های برداری ایجاد کنید. ReportLab به دلیل انعطاف‌پذیری و کنترل دقیقی که بر روی عناصر PDF ارائه می‌دهد، در بسیاری از کاربردها از جمله تولید گزارش‌ها، فاکتورها، رسیدها و اسناد حقوقی مورد استفاده قرار می‌گیرد. این مقاله به بررسی جامع ReportLab، مفاهیم کلیدی، و نحوه استفاده از آن برای ساخت PDF در پایتون می‌پردازد.

مقدمه‌ای بر ReportLab

ReportLab یک کتابخانه متن‌باز است که به شما امکان می‌دهد اسناد PDF را به صورت برنامه‌نویسی ایجاد کنید. برخلاف برخی از کتابخانه‌های دیگر که بر اساس تبدیل HTML به PDF کار می‌کنند، ReportLab به شما کنترل کاملی بر روی عناصر PDF می‌دهد. این کنترل به شما امکان می‌دهد تا اسناد با کیفیت بالا و با طراحی دقیق ایجاد کنید. ReportLab از دو رابط اصلی برای ایجاد PDF پشتیبانی می‌کند: رابط سطح پایین (Canvas) و رابط سطح بالا (Platypus).

رابط Canvas (سطح پایین)

Canvas یک رابط سطح پایین است که به شما امکان می‌دهد تا عناصر PDF را به صورت مستقیم و با استفاده از مختصات و دستورات گرافیکی ایجاد کنید. این رابط برای ایجاد اسناد ساده و سفارشی مناسب است، اما می‌تواند برای اسناد پیچیده زمان‌بر و دشوار باشد.

رابط Platypus (سطح بالا)

Platypus یک رابط سطح بالا است که به شما امکان می‌دهد تا اسناد PDF را با استفاده از عناصر از پیش تعریف شده مانند پاراگراف‌ها، جداول، تصاویر و لیست‌ها ایجاد کنید. این رابط برای ایجاد اسناد پیچیده و با ساختار مناسب است و به شما امکان می‌دهد تا به سرعت و به آسانی اسناد PDF ایجاد کنید.

نصب ReportLab

برای نصب ReportLab، می‌توانید از pip استفاده کنید:

pip install reportlab

ایجاد یک PDF ساده با Canvas

در این بخش، یک PDF ساده با استفاده از رابط Canvas ایجاد می‌کنیم:

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

c = canvas.Canvas("hello.pdf", pagesize=letter)
c.drawString(100, 750, "Hello, ReportLab!")
c.save()

این کد یک فایل PDF به نام “hello.pdf” ایجاد می‌کند و متن “Hello, ReportLab!” را در مختصات (100, 750) صفحه قرار می‌دهد. تابع `drawString` متن را در مختصات مشخص شده رسم می‌کند. تابع `save` فایل PDF را ذخیره می‌کند.

ایجاد یک PDF با Platypus

در این بخش، یک PDF با استفاده از رابط Platypus ایجاد می‌کنیم. Platypus از مفاهیمی مانند Frame، Paragraph، Table و Image برای ساخت سند استفاده می‌کند.

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

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

story.append(Paragraph("This is a simple example using Platypus.", styles['Normal']))
story.append(Spacer(1, 12))
story.append(Paragraph("Platypus makes it easy to create complex documents.", styles['Normal']))

doc.build(story)

این کد یک فایل PDF به نام “platypus_example.pdf” ایجاد می‌کند و دو پاراگراف متن را با استفاده از رابط Platypus به آن اضافه می‌کند. `SimpleDocTemplate` یک سند PDF جدید ایجاد می‌کند. `getSampleStyleSheet` یک مجموعه از سبک‌های پیش‌فرض را برای پاراگراف‌ها و سایر عناصر فراهم می‌کند. `story` یک لیست از عناصر است که در سند PDF قرار می‌گیرند. `build` سند PDF را بر اساس لیست `story` ایجاد می‌کند.

کار با متن و فونت‌ها

ReportLab به شما امکان می‌دهد تا متن را با فونت‌ها، اندازه‌ها و رنگ‌های مختلف در PDF خود قرار دهید. می‌توانید از فونت‌های پیش‌فرض ReportLab استفاده کنید یا فونت‌های سفارشی را بارگذاری کنید.

from reportlab.pdfgen import canvas
from reportlab.lib.pagesizes import letter
from reportlab.lib.colors import blue

c = canvas.Canvas("text_example.pdf", pagesize=letter)
c.setFont("Helvetica", 16)
c.setFillColor(blue)
c.drawString(100, 750, "This is some text with a custom font and color.")
c.save()

در این مثال، فونت “Helvetica” با اندازه 16 و رنگ آبی برای متن استفاده شده است. `setFont` فونت و اندازه آن را تنظیم می‌کند. `setFillColor` رنگ متن را تنظیم می‌کند.

اضافه کردن تصاویر

ReportLab به شما امکان می‌دهد تا تصاویر را به PDF خود اضافه کنید. می‌توانید از فرمت‌های مختلف تصویر مانند JPEG، PNG و GIF استفاده کنید.

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

c = canvas.Canvas("image_example.pdf", pagesize=letter)
c.drawImage("image.jpg", 100, 500, width=200, height=100)
c.save()

این کد یک تصویر به نام “image.jpg” را در مختصات (100, 500) صفحه قرار می‌دهد و عرض و ارتفاع آن را به ترتیب 200 و 100 پیکسل تنظیم می‌کند. `drawImage` تصویر را در مختصات مشخص شده رسم می‌کند.

ایجاد جداول

ReportLab به شما امکان می‌دهد تا جداول را به PDF خود اضافه کنید. می‌توانید تعداد ردیف‌ها و ستون‌ها، عرض ستون‌ها و سبک سلول‌ها را تنظیم کنید.

from reportlab.lib.pagesizes import letter
from reportlab.platypus import SimpleDocTemplate, Table, TableStyle
from reportlab.lib import colors

data = [
    ['Name', 'Age', 'City'],
    ['Alice', '25', 'New York'],
    ['Bob', '30', 'London'],
    ['Charlie', '28', 'Paris']
]

doc = SimpleDocTemplate("table_example.pdf", pagesize=letter)
table = Table(data)
style = TableStyle([
    ('BACKGROUND', (0, 0), (-1, 0), colors.grey80),
    ('TEXTCOLOR', (0, 0), (-1, 0), colors.black),
    ('ALIGN', (0, 0), (-1, -1), 'CENTER')
])
table.setStyle(style)
doc.build([table])

این کد یک جدول با سه ستون و چهار ردیف ایجاد می‌کند. `Table` داده‌های جدول را می‌گیرد. `TableStyle` سبک جدول را تنظیم می‌کند. `build` سند PDF را با جدول ایجاد شده ایجاد می‌کند.

استفاده از Frame ها برای چیدمان پیچیده

Frame ها به شما امکان می‌دهند تا مناطق مشخصی را در صفحه تعریف کنید و عناصر PDF را در داخل آنها قرار دهید. این برای ایجاد چیدمان‌های پیچیده و سازمان‌یافته بسیار مفید است.

from reportlab.lib.pagesizes import letter
from reportlab.platypus import SimpleDocTemplate, Frame, Paragraph
from reportlab.lib.styles import getSampleStyleSheet

doc = SimpleDocTemplate("frame_example.pdf", pagesize=letter)
styles = getSampleStyleSheet()
frame = Frame(50, 50, 500, 700, showBoundary=0) # x, y, width, height

story = [Paragraph("This is a paragraph inside a frame.", styles['Normal'])]
doc.build([frame], story)

در این مثال، یک Frame در مختصات (50, 50) با عرض 500 و ارتفاع 700 ایجاد شده است. پاراگراف “This is a paragraph inside a frame.” در داخل این Frame قرار می‌گیرد. `showBoundary=0` باعث می‌شود که مرز Frame در PDF نمایش داده نشود.

نتیجه‌گیری

ReportLab یک کتابخانه قدرتمند و انعطاف‌پذیر برای تولید فایل‌های PDF در پایتون است. با استفاده از رابط‌های Canvas و Platypus، می‌توانید اسناد PDF با کیفیت بالا و با طراحی دقیق ایجاد کنید. این مقاله به بررسی مفاهیم کلیدی ReportLab و نحوه استفاده از آن برای ساخت PDF در پایتون پرداخت. با تمرین و آزمایش، می‌توانید از ReportLab برای ایجاد اسناد PDF پیچیده و سفارشی برای نیازهای خود استفاده کنید.