cffi-based cairo bindings for Python

Warnings

• breaking Changed `ImageSurface.get_data()` return type from `bytearray` to `memoryview`.
  Fix: If your code expects a `bytearray`, convert the `memoryview` explicitly: `bytearray(surface.get_data())`. Using `memoryview` directly is generally more efficient.
• gotcha The Cairo C library must be installed on your system.
  Fix: cairocffi binds to the native Cairo library. On Debian/Ubuntu, install `libcairo2-dev`. On Fedora, `cairo-devel`. On macOS with Homebrew, `brew install cairo`.
• gotcha For file-based surfaces (e.g., PDFSurface, SVGSurface), `surface.finish()` is crucial to ensure all drawing operations are flushed and the file is properly closed.
  Fix: Always call `surface.finish()` on surfaces that write to files or other streams when you are done with them to prevent incomplete or corrupted output. For `ImageSurface`, it's less critical as data is held in memory, but still good practice.
• gotcha While API compatible, `cairocffi` does not provide a module named `cairo` directly. Code written for `pycairo` using `import cairo` will fail.
  Fix: Always use `import cairocffi as cairo` to maintain API compatibility while using the correct module import path.

Install

• pip install cairocffi Install cairocffi

Imports

• cairo

  import cairocffi as cairo

  While cairocffi is API compatible with pycairo, the module name is different. The common practice is to import cairocffi and alias it as cairo for consistency.
• ImageSurface

  from cairocffi import ImageSurface

  Specific Cairo classes can be imported directly from the cairocffi module.

Quickstart

This quickstart demonstrates how to create an image surface, draw text onto it, and save the result as a PNG file. It highlights the typical import pattern and basic drawing operations using the Cairo API.

import cairocffi as cairo
import os

# Create an image surface (200x100 pixels, ARGB32 format)
surface = cairo.ImageSurface(cairo.FORMAT_ARGB32, 200, 100)
ctx = cairo.Context(surface)

# Draw a light gray background
ctx.set_source_rgb(0.8, 0.8, 0.8) # R, G, B values (0.0-1.0)
ctx.paint()

# Set text color, font, and size
ctx.set_source_rgb(0, 0, 0) # Black
ctx.select_font_face('Sans', cairo.FONT_SLANT_NORMAL, cairo.FONT_WEIGHT_NORMAL)
ctx.set_font_size(24)

# Move to position and show text
ctx.move_to(10, 60) # x, y coordinates
ctx.show_text("Hello, cairocffi!")

# Define output path
output_filename = "hello_cairocffi.png"

# Write the surface content to a PNG file
surface.write_to_png(output_filename)
print(f"Generated {output_filename}")

# Clean up (optional for ImageSurface, but good practice for other surfaces like PDF/SVG)
surface.finish()