rlpycairo

Warnings

• gotcha Installation of `pycairo` (a core dependency) often fails if the underlying Cairo graphics library and its development headers are not installed on the system (e.g., via `apt-get`, `brew`). `pip install pycairo` alone is frequently insufficient.
  Fix: Ensure system-level Cairo development packages are installed (e.g., `sudo apt-get install libcairo2-dev` on Debian/Ubuntu, `brew install cairo` on macOS).
• gotcha The `rlPyCairo` backend is noted in its documentation to be inferior to the original `_renderPM` C extension in two specific areas: rendering scaled images and the speed of drawing text.
  Fix: Be aware of potential performance or quality differences if your application heavily relies on scaled images or complex text rendering. Consider alternative backends or optimizations if these issues arise.
• gotcha Currently, `rlPyCairo` does not fully utilize advanced `PyCairo` capabilities such as transparency or patterns, despite Cairo's underlying support for these features.
  Fix: Do not expect advanced Cairo features like transparency or complex patterns to be automatically supported or exposed through `rlPyCairo` at this time. Use ReportLab's native features or other rendering backends for such requirements.
• gotcha A `ModuleNotFoundError: No module named 'rlPyCairo'` can occur if the package is not correctly installed in the active environment, or if `reportlab.rl_config.renderPMBackend` is not set to `'rlPyCairo'` before rendering operations.
  Fix: Verify `rlpycairo` is installed (`pip show rlpycairo`). Ensure `reportlab.rl_config.renderPMBackend = 'rlPyCairo'` is executed at an appropriate point in your application startup before any `reportlab.graphics.renderPM` calls.
• breaking The package is currently marked with a '2 - Pre-Alpha' development status on PyPI. This implies that its API may not be stable, and breaking changes could occur in minor or patch releases, though none are explicitly documented as of 0.4.0.
  Fix: Pin the exact version in your `requirements.txt` to mitigate unexpected changes (`rlpycairo==0.4.0`). Monitor project updates closely if upgrading to new pre-1.0.0 versions.

Install

• pip install rlpycairo Install rlpycairo

Imports

• renderPMBackend

  import reportlab.rl_config
  reportlab.rl_config.renderPMBackend = 'rlPyCairo'

  rlpycairo is enabled by configuring ReportLab's rendering backend, rather than direct class/function imports from the rlpycairo package itself.

Quickstart

This quickstart demonstrates how to configure ReportLab to use `rlpycairo` as its rendering backend and then generate a simple PNG image using ReportLab's graphics module. This verifies the `rlpycairo` plugin is active and functional.

from reportlab.lib.pagesizes import A4
from reportlab.lib.units import inch
from reportlab.graphics.shapes import Drawing, String
from reportlab.graphics import renderPM
import reportlab.rl_config
import os

# Enable rlPyCairo backend
reportlab.rl_config.renderPMBackend = 'rlPyCairo'

# Create a simple ReportLab drawing
d = Drawing(200, 100)
d.add(String(50, 50, "Hello, rlPyCairo!", fillColor='red'))

output_filename = 'hello_rlpycairo.png'
# Render the drawing to a PNG file using the configured backend
renderPM.drawToFile(d, output_filename, 'PNG')

print(f"Generated '{output_filename}' using rlPyCairo backend.")
print(f"File path: {os.path.abspath(output_filename)}")