C API Reference¶
This manual documents the API used by C and C++ programmers who want to write extension modules that use pycairo.
Pycairo Compiler Flags¶
To compile a Python extension using Pycairo you need to know where Pycairo and cairo are located and what flags to pass to the compiler and linker.
Variant:
Only available since version 1.16.0.
While Pycairo installs a pkg-config file, in case of virtualenvs, installation to the user directory or when using wheels/eggs, pkg-config will not be able to locate the .pc file. The
get_include()
function should work in all cases, as long as Pycairo is in your Python search path.- Compiler Flags:
python -c "import cairo; print(cairo.get_include())"
pkg-config --cflags cairo
- Linker Flags:
pkg-config --libs cairo
Variant:
This works with older versions, but with the limitations mentioned above. Use it as a fallback if you want to support older versions or if your module does not require virtualenv/pip support.
- Compiler Flags:
pkg-config --cflags pycairo
orpkg-config --cflags py3cairo
- Linker Flags:
pkg-config --libs pycairo
orpkg-config --libs py3cairo
To access the Pycairo C API under Python 3¶
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>
...
New 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¶
-
PyTypeObject *
PycairoContext_Type
¶
-
PycairoContext_GET
(obj)¶ Parameters: - obj (PycairoContext) –
Returns: cairo_t
[transfer none]Get the
cairo_t
object out of thePycairoContext
.
-
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
-
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
-
PycairoFontFace
PycairoToyFontFace
¶
-
PyTypeObject *
PycairoToyFontFace_Type
¶
Cairo Font Options¶
-
cairo_font_options_t*
PycairoFontOptions.font_options
¶
-
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
¶
-
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
¶
-
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
¶
-
PyTypeObject *
PycairoPattern_Type
¶
-
PycairoPattern
PycairoSolidPattern
¶
-
PyTypeObject *
PycairoSolidPattern_Type
¶
-
PycairoPattern
PycairoSurfacePattern
¶
-
PyTypeObject *
PycairoSurfacePattern_Type
¶
-
PycairoPattern
PycairoGradient
¶
-
PyTypeObject *
PycairoGradient_Type
¶
-
PycairoGradient
PycairoLinearGradient
¶
-
PyTypeObject *
PycairoLinearGradient_Type
¶
-
PycairoGradient
PycairoRadialGradient
¶
-
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
¶
-
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
¶
-
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
¶
-
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
¶
-
PyTypeObject *
PycairoSurface_Type
¶
-
PycairoSurface
PycairoImageSurface
¶
-
PyTypeObject *
PycairoImageSurface_Type
¶
-
PycairoSurface
PycairoPDFSurface
¶
-
PyTypeObject *
PycairoPDFSurface_Type
¶
-
PycairoSurface
PycairoPSSurface
¶
-
PyTypeObject *
PycairoPSSurface_Type
¶
-
PycairoSurface
PycairoRecordingSurface
¶
-
PyTypeObject *
PycairoRecordingSurface_Type
¶
-
PycairoSurface
PycairoSVGSurface
¶
-
PyTypeObject *
PycairoSVGSurface_Type
¶
-
PycairoSurface
PycairoWin32Surface
¶
-
PyTypeObject *
PycairoWin32Surface_Type
¶
-
PycairoSurface
PycairoXCBSurface
¶
-
PyTypeObject *
PycairoXCBSurface_Type
¶
-
PycairoSurface
PycairoXlibSurface
¶
-
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.