# 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

typedef PyObject PycairoContext

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_t` object 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

typedef PyObject PycairoFontFace

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

typedef PyObject PycairoFontOptions

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

typedef PyObject PycairoMatrix

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

typedef PyObject PycairoPath

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

typedef PyObject PycairoPattern

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

typedef PyObject PycairoRegion

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

typedef PyObject PycairoRectangleInt

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

typedef PyObject PycairoScaledFont

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

typedef PyObject PycairoSurface

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.

type cairo_t
type cairo_status_t
type cairo_surface_t
type cairo_scaled_font_t
type cairo_rectangle_int_t
type cairo_region_t
type cairo_pattern_t
type cairo_matrix_t
type cairo_font_options_t
type cairo_path_t
type cairo_font_face_t

## CPython Types

type PyObject

type PyTypeObject