C API Reference
Example showing how to import the pycairo API:
#include "py3cairo.h"
PyMODINIT_FUNC
PyInit_client(void)
{
  PyObject *m;
  m = PyModule_Create(&clientmodule);
  if (m == NULL)
      return NULL;
  if (import_cairo() < 0)
      return NULL;
  /* additional initialization can happen here */
  return m;
}
In case you want to use the API from another compilation unit:
#define PYCAIRO_NO_IMPORT
#include <py3cairo.h>
...
Added in version 1.17.0: The PYCAIRO_NO_IMPORT macro is used since 1.17.0
Misc Functions
- 
int Pycairo_Check_Status(cairo_status_t status)
- Parameters:
- status (cairo_status_t) 
 
- Returns:
- -1 in case of an error, otherwise 0. Sets an exception in case of an error. 
 - Takes a status value and converts it to an exception if it represents an error status. 
Cairo Context
- 
cairo_t *PycairoContext.ctx
- The wrapped - cairo_t
- 
typedef PyTypeObject *PycairoContext_Type
- 
PycairoContext_GET(obj)
- Parameters:
- obj (PycairoContext) 
 
- Returns:
- cairo_t[transfer none]
 - Get the - cairo_tobject out of the- PycairoContext.
- 
PyObject *PycairoContext_FromContext(cairo_t *ctx, PyTypeObject *type, PyObject *base)
- Parameters:
- ctx (cairo_t) – a cairo_t to ‘wrap’ into a Python object. It is unreferenced if the PycairoContext creation fails, or if the cairo_t has an error status. [transfer full] 
- type (PyTypeObject) – a pointer to the type to instantiate. It can be &PycairoContext_Type, or a PycairoContext_Type subtype. (cairo.Context or a cairo.Context subclass) [transfer none] 
- base (PyObject) – the base object used to create the context, or NULL. it is referenced to keep it alive while the cairo_t is being used [transfer none] 
 
- Returns:
- New reference or NULL on failure and sets an exception [transfer full] 
 - Create a new PycairoContext from a - cairo_t
Cairo Font Face
- 
cairo_font_face_t *PycairoFontFace.font_face
The wrapped cairo_font_face_t
- 
typedef PyTypeObject *PycairoFontFace_Type
- 
PyObject *PycairoFontFace_FromFontFace(cairo_font_face_t *font_face)
- Parameters:
- font_face (cairo_font_face_t) – a cairo_font_face_t to ‘wrap’ into a Python object. it is unreferenced if the PycairoFontFace creation fails [transfer full] 
 
- Returns:
- New reference or NULL on failure and sets an exception [transfer full] 
 - Create a new PycairoFontFace from a cairo_font_face_t 
- 
typedef PycairoFontFace PycairoToyFontFace
- 
typedef PyTypeObject *PycairoToyFontFace_Type
Cairo Font Options
- 
cairo_font_options_t *PycairoFontOptions.font_options
- 
typedef PyTypeObject *PycairoFontOptions_Type
- 
PyObject *PycairoFontOptions_FromFontOptions(cairo_font_options_t *font_options)
- Parameters:
- font_options (cairo_font_options_t) – a cairo_font_options_t to ‘wrap’ into a Python object. it is unreferenced if the PycairoFontOptions creation fails [transfer full] 
 
- Returns:
- New reference or NULL on failure and sets an exception [transfer full] 
 - Create a new PycairoFontOptions from a cairo_font_options_t 
Cairo Matrix
- 
cairo_matrix_t PycairoMatrix.matrix
- 
typedef PyTypeObject *PycairoMatrix_Type
- 
PyObject *PycairoMatrix_FromMatrix(const cairo_matrix_t *matrix)
- Parameters:
- matrix (cairo_matrix_t) – a cairo_matrix_t to ‘wrap’ into a Python object. the cairo_matrix_t values are copied. [transfer none] 
 
- Returns:
- New reference or NULL on failure and sets an exception [transfer full] 
 - Create a new PycairoMatrix from a cairo_matrix_t 
Cairo Path
- 
cairo_path_t *PycairoPath.path
- 
typedef PyTypeObject *PycairoPath_Type
- 
PyObject *PycairoPath_FromPath(cairo_path_t *path)
- Parameters:
- path (cairo_path_t) – a cairo_path_t to ‘wrap’ into a Python object. path is unreferenced if the PycairoPath creation fails, or if path is in an error status. [transfer full] 
 
- Returns:
- New reference or NULL on failure and sets an exception [transfer full] 
 - Create a new PycairoPath from a cairo_path_t 
Cairo Pattern
- 
cairo_pattern_t *PycairoPattern.pattern
- 
typedef PyTypeObject *PycairoPattern_Type
- 
typedef PycairoPattern PycairoSolidPattern
- 
typedef PyTypeObject *PycairoSolidPattern_Type
- 
typedef PycairoPattern PycairoSurfacePattern
- 
typedef PyTypeObject *PycairoSurfacePattern_Type
- 
typedef PycairoPattern PycairoGradient
- 
typedef PyTypeObject *PycairoGradient_Type
- 
typedef PycairoGradient PycairoLinearGradient
- 
typedef PyTypeObject *PycairoLinearGradient_Type
- 
typedef PycairoGradient PycairoRadialGradient
- 
typedef PyTypeObject *PycairoRadialGradient_Type
- 
PyObject *PycairoPattern_FromPattern(cairo_pattern_t *pattern, PyObject *base)
- Parameters:
- pattern (cairo_pattern_t) – a cairo_pattern_t to ‘wrap’ into a Python object. It is unreferenced if the PycairoPattern creation fails, or if the pattern has an error status. [transfer full] 
- base (PyObject) – the base object used to create the pattern, or NULL. It is referenced to keep it alive while the cairo_pattern_t is being used. [transfer none] 
 
- Returns:
- New reference or NULL on failure and sets an exception [transfer full] 
 - Create a new PycairoSolidPattern, PycairoSurfacePattern, PycairoLinearGradient, or PycairoRadialGradient from a cairo_pattern_t. 
Cairo Region
- 
cairo_region_t *PycairoRegion.region
- 
typedef PyTypeObject *PycairoRegion_Type
- 
PyObject *PycairoRegion_FromRegion(cairo_region_t *region)
- Parameters:
- region (cairo_region_t) – a cairo_region_t to ‘wrap’ into a Python object. region is unreferenced if the PycairoRegion creation fails, or if region is in an error status. 
 
- Returns:
- New reference or NULL on failure and sets an exception [transfer full] 
 - Create a new PycairoRegion from a cairo_region_t 
Cairo RectangleInt
- 
cairo_rectangle_int_t *PycairoRectangleInt.rectangle_int
- 
typedef PyTypeObject *PycairoRectangleInt_Type
- 
PyObject *PycairoRectangleInt_FromRectangleInt(const cairo_rectangle_int_t *rectangle_int)
- Parameters:
- rectangle_int (cairo_rectangle_int_t) – a cairo_rectangle_int_t to ‘wrap’ into a Python object. rectangle_int is unreferenced if the PycairoRectangleInt creation fails. [transfer none] 
 
- Returns:
- New reference or NULL on failure and sets an exception [transfer full] 
 - Create a new PycairoRectangleInt from a cairo_rectangle_int_t 
Scaled Font
- 
cairo_scaled_font_t *PycairoScaledFont.scaled_font
- 
typedef PyTypeObject *PycairoScaledFont_Type
- 
PyObject *PycairoScaledFont_FromScaledFont(cairo_scaled_font_t *scaled_font)
- Parameters:
- scaled_font (cairo_scaled_font_t) – a cairo_scaled_font_t to ‘wrap’ into a Python object. it is unreferenced if the PycairoScaledFont creation fails [transfer full] 
 
- Returns:
- New reference or NULL on failure and sets an exception [transfer full] 
 - Create a new PycairoScaledFont from a cairo_scaled_font_t 
Cairo Surface
- 
cairo_surface_t *PycairoSurface.surface
- 
typedef PyTypeObject *PycairoSurface_Type
- 
typedef PycairoSurface PycairoImageSurface
- 
typedef PyTypeObject *PycairoImageSurface_Type
- 
typedef PycairoSurface PycairoPDFSurface
- 
typedef PyTypeObject *PycairoPDFSurface_Type
- 
typedef PycairoSurface PycairoPSSurface
- 
typedef PyTypeObject *PycairoPSSurface_Type
- 
typedef PycairoSurface PycairoRecordingSurface
- 
typedef PyTypeObject *PycairoRecordingSurface_Type
- 
typedef PycairoSurface PycairoSVGSurface
- 
typedef PyTypeObject *PycairoSVGSurface_Type
- 
typedef PycairoSurface PycairoWin32Surface
- 
typedef PyTypeObject *PycairoWin32Surface_Type
- 
typedef PycairoSurface PycairoXCBSurface
- 
typedef PyTypeObject *PycairoXCBSurface_Type
- 
typedef PycairoSurface PycairoXlibSurface
- 
typedef PyTypeObject *PycairoXlibSurface_Type
- 
PyObject *PycairoSurface_FromSurface(cairo_surface_t *surface, PyObject *base)
- Parameters:
- surface (cairo_surface_t) – a cairo_surface_t to ‘wrap’ into a Python object. It is unreferenced if the PycairoSurface creation fails, or if the cairo_surface_t has an error status. [transfer full] 
- base (PyObject) – the base object used to create the surface, or NULL. It is referenced to keep it alive while the cairo_surface_t is being used. [transfer none] 
 
- Returns:
- New reference or NULL on failure and sets an exception [transfer full] 
 - Create a new PycairoImageSurface, PycairoPDFSurface, PycairoPSSurface, PycairoRecordingSurface, PycairoSVGSurface, PycairoWin32Surface, PycairoWin32PrintingSurface, PycairoXCBSurface, or PycairoXlibSurface from a cairo_surface_t. 
Cairo Types
These are only listed here so they can be referenced in the documentation.
See https://www.cairographics.org/manual/ for details.
CPython Types
- 
type PyObject
- 
type PyTypeObject