File: __init__.pyi | Debian Sources

File: init.pyi

package info (click to toggle)
pycairo 1.27.0-2
links: PTS, VCS
area: main
in suites: forky, sid, trixie
size: 1,984 kB
sloc: ansic: 8,873; python: 3,688; makefile: 32; sh: 4
file content (5889 lines) | stat: -rw-r--r-- 217,323 bytes
from __future__ import annotations

from typing import (Any, BinaryIO, ByteString, Callable, Generic, List, Optional,
                    Sequence, Text, Tuple, TypeVar, Union)

del annotations

HAS_ATSUI_FONT: bool = ...
HAS_FT_FONT: bool = ...
HAS_GLITZ_SURFACE: bool = ...
HAS_IMAGE_SURFACE: bool = ...
HAS_MIME_SURFACE: bool = ...
"""
.. versionadded:: 1.12.0
"""
HAS_PDF_SURFACE: bool = ...
HAS_PNG_FUNCTIONS: bool = ...
HAS_PS_SURFACE: bool = ...
HAS_QUARTZ_SURFACE: bool = ...
HAS_RECORDING_SURFACE: bool = ...
HAS_SCRIPT_SURFACE: bool = ...
"""
.. versionadded:: 1.12.0
"""
HAS_SVG_SURFACE: bool = ...
HAS_TEE_SURFACE: bool = ...
"""
.. versionadded:: 1.15.3
"""
HAS_USER_FONT: bool = ...
HAS_WIN32_FONT: bool = ...
HAS_WIN32_SURFACE: bool = ...
HAS_XCB_SURFACE: bool = ...
HAS_XLIB_SURFACE: bool = ...
HAS_DWRITE_FONT: bool = ...
"""
.. versionadded:: 1.23.0
"""

PDF_OUTLINE_ROOT: int = ...
"""
The root outline item in :meth:`PDFSurface.add_outline`

.. versionadded:: 1.18.0 Only available with cairo 1.15.10+
"""

COLOR_PALETTE_DEFAULT: int = ...
"""
The default color palette index. See :meth:`FontOptions.set_color_palette`

.. versionadded:: 1.25.0 Only available with cairo 1.17.8+
"""

version: str = ...
"""the pycairo version, as a string"""

version_info: Tuple[int, int, int] = ...
"""the pycairo version, as a tuple"""

CAIRO_VERSION: int = ...
"""
The version of cairo available at compile-time in the same format as
returned by :func:`cairo_version`

.. versionadded:: 1.18.0
"""

CAIRO_VERSION_STRING: str = ...
"""
A human-readable string literal containing the version of cairo available
at compile-time, in the form of "X.Y.Z".

.. versionadded:: 1.18.0
"""

CAIRO_VERSION_MAJOR: int = ...
"""
The major component of the version of cairo available at compile-time.

.. versionadded:: 1.18.0
"""

CAIRO_VERSION_MINOR: int = ...
"""
The minor component of the version of cairo available at compile-time.

.. versionadded:: 1.18.0
"""

CAIRO_VERSION_MICRO: int = ...
"""
The micro component of the version of cairo available at compile-time.

.. versionadded:: 1.18.0
"""

def cairo_version() -> int:
    """
    :returns: the encoded version

    Returns the version of the underlying C cairo library, encoded in a single
    integer.
    """

def cairo_version_string() -> str:
    """
    :returns: the encoded version

    Returns the version of the underlying C cairo library as a human-readable
    string of the form "X.Y.Z".
    """

class Path:
    """
    *Path* cannot be instantiated directly, it is created by calling
    :meth:`Context.copy_path` and :meth:`Context.copy_path_flat`.

    str(path) lists the path elements.

    See :class:`path attributes <cairo.PathDataType>`

    Path is an iterator.

    See examples/warpedtext.py for example usage.
    """

class Rectangle(Tuple[float, float, float, float]):
    """
    .. versionadded:: 1.15
        In prior versions a (float, float, float, float) tuple was
        used instead of :class:`Rectangle`.

    A data structure for holding a rectangle.
    """

    x: float = ...
    y: float = ...
    width: float = ...
    height: float = ...

    def __init__(self, x: float, y: float, width: float, height: float) -> None:
        """
        :param x:
            X coordinate of the left side of the rectangle
        :param y:
            Y coordinate of the the top side of the rectangle
        :param width:
            width of the rectangle
        :param height:
            height of the rectangle
        """

class _IntEnum(int):
    def __init__(self, value: int) -> None: ...

class Antialias(_IntEnum):
    """
    Specifies the type of antialiasing to do when rendering text or shapes.

    .. versionadded:: 1.13
    """

    BEST: "Antialias" = ...
    """
    Hint that the backend should render at the highest quality, sacrificing
    speed if necessary.
    """

    DEFAULT: "Antialias" = ...
    """Use the default antialiasing for the subsystem and target device"""

    FAST: "Antialias" = ...
    """
    Hint that the backend should perform some antialiasing but prefer
    speed over quality.
    """

    GOOD: "Antialias" = ...
    """The backend should balance quality against performance."""

    GRAY: "Antialias" = ...
    """
    Perform single-color antialiasing (using shades of gray for black text
    on a white background, for example).
    """

    NONE: "Antialias" = ...
    """Use a bilevel alpha mask"""

    SUBPIXEL: "Antialias" = ...
    """
    Perform antialiasing by taking advantage of the order of subpixel
    elements on devices such as LCD panels.
    """

class Content(_IntEnum):
    """
    These constants are used to describe the content that a :class:`Surface`
    will contain, whether color information, alpha information (translucence
    vs. opacity), or both.

    .. versionadded:: 1.13
    """

    ALPHA: "Content" = ...
    """The surface will hold alpha content only."""

    COLOR: "Content" = ...
    """The surface will hold color content only."""

    COLOR_ALPHA: "Content" = ...
    """The surface will hold color and alpha content."""

class FillRule(_IntEnum):
    """
    These constants are used to select how paths are filled. For both fill
    rules, whether or not a point is included in the fill is determined by
    taking a ray from that point to infinity and looking at intersections with
    the path. The ray can be in any direction, as long as it doesn't pass
    through the end point of a segment or have a tricky intersection such as
    intersecting tangent to the path. (Note that filling is not actually
    implemented in this way. This is just a description of the rule that is
    applied.)

    The default fill rule is :attr:`WINDING`.

    .. versionadded:: 1.13
    """

    EVEN_ODD: "FillRule" = ...
    """
    Counts the total number of intersections, without regard to the
    orientation of the contour. If the total number of intersections is
    odd, the point will be filled.
    """

    WINDING: "FillRule" = ...
    """
    If the path crosses the ray from left-to-right, counts +1. If the path
    crosses the ray from right to left, counts -1. (Left and right are
    determined from the perspective of looking along the ray from the
    starting point.) If the total count is non-zero, the point will be
    filled.
    """

class Format(_IntEnum):
    """
    These constants are used to identify the memory format of
    :class:`ImageSurface` data.

    New entries may be added in future versions.

    .. versionadded:: 1.13
    """

    def stride_for_width(self, width: int) -> int:
        """
        :param width: the desired width of an :class:`ImageSurface`
            to be created.
        :returns: the appropriate stride to use given the desired format and
            width, or -1 if either the format is invalid or the width too
            large.

        This method provides a stride value that will respect all alignment
        requirements of the accelerated image-rendering code within cairo.
        Typical usage will be of the form::

            format = cairo.Format.RGB24
            stride = format.stride_for_width(width)
            surface = cairo.ImageSurface.create_for_data(
                data, format, width, height, stride)

        Also available under
        :meth:`cairo.ImageSurface.format_stride_for_width`.

        .. versionadded:: 1.14
        """

    A1: "Format" = ...
    """
    each pixel is a 1-bit quantity holding an alpha value. Pixels are
    packed together into 32-bit quantities. The ordering of the bits
    matches the endianess of the platform. On a big-endian machine, the
    first pixel is in the uppermost bit, on a little-endian machine the
    first pixel is in the least-significant bit.
    """

    A8: "Format" = ...
    """
    each pixel is a 8-bit quantity holding an alpha value.
    """

    ARGB32: "Format" = ...
    """
    each pixel is a 32-bit quantity, with alpha in the upper 8 bits, then
    red, then green, then blue. The 32-bit quantities are stored
    native-endian. Pre-multiplied alpha is used. (That is, 50% transparent
    red is 0x80800000, not 0x80ff0000.)
    """

    INVALID: "Format" = ...
    """no such format exists or is supported."""

    RGB16_565: "Format" = ...
    """
    each pixel is a 16-bit quantity with red in the upper 5 bits, then
    green in the middle 6 bits, and blue in the lower 5 bits.
    """

    RGB24: "Format" = ...
    """
    each pixel is a 32-bit quantity, with the upper 8 bits unused. [#]_  Red,
    Green, and Blue are stored in the remaining 24 bits in that order.

    .. [#] Cairo operators (for example CLEAR and SRC) may overwrite unused bytes as an implementation side-effect, their values should be considered undefined.
    """

    RGB30: "Format" = ...
    """
    like :data:`RGB24` but with 10bpc.
    """

    RGB96F: "Format" = ...
    """
    3 floats, R, G, B.

    .. versionadded:: 1.23 Only available with cairo 1.17.2+
    """

    RGBA128F: "Format" = ...
    """
    4 floats, R, G, B, A.

    .. versionadded:: 1.23 Only available with cairo 1.17.2+
    """

class HintMetrics(_IntEnum):
    """
    These constants specify whether to hint font metrics; hinting font metrics
    means quantizing them so that they are integer values in device space.
    Doing this improves the consistency of letter and line spacing, however it
    also means that text will be laid out differently at different zoom
    factors.

    .. versionadded:: 1.13
    """

    DEFAULT: "HintMetrics" = ...
    """
    Hint metrics in the default manner for the font backend and target
    device
    """

    OFF: "HintMetrics" = ...
    """"Do not hint font metrics"""

    ON: "HintMetrics" = ...
    """Hint font metrics"""

class ColorMode(_IntEnum):
    """
    Specifies if color fonts are to be rendered using the color glyphs or
    outline glyphs. Glyphs that do not have a color presentation, and non-color
    fonts are not affected by this font option.

    .. versionadded:: 1.25 Only available with cairo 1.17.8+
    """

    DEFAULT: "ColorMode" = ...
    """
    Use the default color mode for font backend and target device.
    """

    NO_COLOR: "ColorMode" = ...
    """
    Disable rendering color glyphs. Glyphs are always rendered as outline glyphs
    """

    COLOR: "ColorMode" = ...
    """
    Enable rendering color glyphs. If the font contains a color presentation for
    a glyph, and when supported by the font backend, the glyph will be rendered
    in color.
    """

class Dither(_IntEnum):
    """
    Dither is an intentionally applied form of noise used to randomize
    quantization error, preventing large-scale patterns such as color banding in
    images (e.g. for gradients). Ordered dithering applies a precomputed
    threshold matrix to spread the errors smoothly.

    :class:`Dither` is modeled on pixman dithering algorithm choice. As of
    Pixman 0.40, FAST corresponds to a 8x8 ordered bayer noise and GOOD and BEST
    use an ordered 64x64 precomputed blue noise.

    .. versionadded:: 1.25 Only available with cairo 1.18.0+
    """

    NONE: "Dither" = ...
    """
    No dithering.
    """

    DEFAULT: "Dither" = ...
    """
    Default choice at cairo compile time. Currently NONE.
    """

    FAST: "Dither" = ...
    """
    Fastest dithering algorithm supported by the backend
    """

    GOOD: "Dither" = ...
    """
    An algorithm with smoother dithering than FAST
    """

    BEST: "Dither" = ...
    """
    Best algorithm available in the backend
    """

class HintStyle(_IntEnum):
    """
    These constants specify the type of hinting to do on font outlines.
    Hinting is the process of fitting outlines to the pixel grid in order to
    improve the appearance of the result. Since hinting outlines involves
    distorting them, it also reduces the faithfulness to the original outline
    shapes. Not all of the outline hinting styles are supported by all font
    backends.

    New entries may be added in future versions.

    .. versionadded:: 1.13
    """

    DEFAULT: "HintStyle" = ...
    """
    Use the default hint style for font backend and target device
    """

    FULL: "HintStyle" = ...
    """
    Hint outlines to maximize contrast
    """

    MEDIUM: "HintStyle" = ...
    """
    Hint outlines with medium strength giving a compromise between fidelity
    to the original shapes and contrast
    """

    NONE: "HintStyle" = ...
    """Do not hint outlines"""

    SLIGHT: "HintStyle" = ...
    """
    Hint outlines slightly to improve contrast while retaining good
    fidelity to the original shapes.
    """

class SubpixelOrder(_IntEnum):
    """
    The subpixel order specifies the order of color elements within each pixel
    on the display device when rendering with an antialiasing mode of
    :attr:`Antialias.SUBPIXEL`.

    .. versionadded:: 1.13
    """

    BGR: "SubpixelOrder" = ...
    """Subpixel elements are arranged horizontally with blue at the left"""

    DEFAULT: "SubpixelOrder" = ...
    """Use the default subpixel order for for the target device"""

    RGB: "SubpixelOrder" = ...
    """Subpixel elements are arranged horizontally with red at the left"""

    VBGR: "SubpixelOrder" = ...
    """Subpixel elements are arranged vertically with blue at the top"""

    VRGB: "SubpixelOrder" = ...
    """Subpixel elements are arranged vertically with red at the top"""

class LineCap(_IntEnum):
    """
    These constants specify how to render the endpoints of the path when
    stroking.

    The default line cap style is :attr:`BUTT`

    .. versionadded:: 1.13
    """

    BUTT: "LineCap" = ...
    """start(stop) the line exactly at the start(end) point"""

    ROUND: "LineCap" = ...
    """use a round ending, the center of the circle is the end point"""

    SQUARE: "LineCap" = ...
    """use squared ending, the center of the square is the end point"""

class LineJoin(_IntEnum):
    """
    These constants specify how to render the junction of two lines when
    stroking.

    The default line join style is :attr:`MITER`

    .. versionadded:: 1.13
    """

    BEVEL: "LineJoin" = ...
    """
    use a cut-off join, the join is cut off at half the line width from
    the joint point
    """

    MITER: "LineJoin" = ...
    """
    use a sharp (angled) corner, see :meth:`Context.set_miter_limit`
    """

    ROUND: "LineJoin" = ...
    """use a rounded join, the center of the circle is the joint point"""

class Filter(_IntEnum):
    """
    These constants are used to indicate what filtering should be applied when
    reading pixel values from patterns. See :meth:`Pattern.set_filter` for
    indicating the desired filter to be used with a particular pattern.

    .. versionadded:: 1.13
    """

    BEST: "Filter" = ...
    """
    The highest-quality available, performance may not be suitable for
    interactive use.
    """

    BILINEAR: "Filter" = ...
    """Linear interpolation in two dimensions"""

    FAST: "Filter" = ...
    """A high-performance filter, with quality similar *FILTER_NEAREST*"""

    GAUSSIAN: "Filter" = ...
    """
    This filter value is currently unimplemented, and should not be used
    in current code.
    """

    GOOD: "Filter" = ...
    """
    A reasonable-performance filter, with quality similar to
    *FILTER_BILINEAR*
    """

    NEAREST: "Filter" = ...
    """Nearest-neighbor filtering"""

class Operator(_IntEnum):
    """
    These constants are used to set the compositing operator for all cairo
    drawing operations.

    The default operator is :attr:`OVER`.

    The operators marked as *unbounded* modify their destination even outside
    of the mask layer (that is, their effect is not bound by the mask layer).
    However, their effect can still be limited by way of clipping.

    To keep things simple, the operator descriptions here document the
    behavior for when both source and destination are either fully transparent
    or fully opaque.  The actual implementation works for translucent layers
    too.

    For a more detailed explanation of the effects of each operator, including
    the mathematical definitions, see https://cairographics.org/operators.

    .. versionadded:: 1.13
    """

    ADD: "Operator" = ...
    """source and destination layers are accumulated"""

    ATOP: "Operator" = ...
    """draw source on top of destination content and only there"""

    CLEAR: "Operator" = ...
    """clear destination layer (bounded)"""

    COLOR_BURN: "Operator" = ...
    """darkens the destination color to reflect the source color."""

    COLOR_DODGE: "Operator" = ...
    """brightens the destination color to reflect the source color."""

    DARKEN: "Operator" = ...
    """
    replaces the destination with the source if it is darker, otherwise
    keeps the source.
    """

    DEST: "Operator" = ...
    """ignore the source"""

    DEST_ATOP: "Operator" = ...
    """leave destination on top of source content and only there (unbounded)"""

    DEST_IN: "Operator" = ...
    """leave destination only where there was source content (unbounded)"""

    DEST_OUT: "Operator" = ...
    """leave destination only where there was no source content"""

    DEST_OVER: "Operator" = ...
    """draw destination on top of source"""

    DIFFERENCE: "Operator" = ...
    """Takes the difference of the source and destination color."""

    EXCLUSION: "Operator" = ...
    """Produces an effect similar to difference, but with lower contrast."""

    HARD_LIGHT: "Operator" = ...
    """Multiplies or screens, dependent on source color."""

    HSL_COLOR: "Operator" = ...
    """
    Creates a color with the hue and saturation of the source and the
    luminosity of the target. This preserves the gray levels of the target
    and is useful for coloring monochrome images or tinting color images.
    """

    HSL_HUE: "Operator" = ...
    """
    Creates a color with the hue of the source and the saturation and
    luminosity of the target.
    """

    HSL_LUMINOSITY: "Operator" = ...
    """
    Creates a color with the luminosity of the source and the hue and
    saturation of the target. This produces an inverse effect to
    :attr:`HSL_COLOR`
    """

    HSL_SATURATION: "Operator" = ...
    """
    Creates a color with the saturation of the source and the hue and
    luminosity of the target. Painting with this mode onto a gray area
    produces no change.
    """

    IN: "Operator" = ...
    """draw source where there was destination content (unbounded)"""

    LIGHTEN: "Operator" = ...
    """
    replaces the destination with the source if it is lighter, otherwise
    keeps the source.
    """

    MULTIPLY: "Operator" = ...
    """
    source and destination layers are multiplied. This causes the result
    to be at least as dark as the darker inputs.
    """

    OUT: "Operator" = ...
    """draw source where there was no destination content (unbounded)"""

    OVER: "Operator" = ...
    """draw source layer on top of destination layer (bounded)"""

    OVERLAY: "Operator" = ...
    """
    multiplies or screens, depending on the lightness of the destination
    color.
    """

    SATURATE: "Operator" = ...
    """like over, but assuming source and dest are disjoint geometries"""

    SCREEN: "Operator" = ...
    """
    source and destination are complemented and multiplied. This causes
    the result to be at least as light as the lighter inputs.
    """

    SOFT_LIGHT: "Operator" = ...
    """Darkens or lightens, dependent on source color."""

    SOURCE: "Operator" = ...
    """replace destination layer (bounded)"""

    XOR: "Operator" = ...
    """source and destination are shown where there is only one of them"""

class Extend(_IntEnum):
    """
    These constants are used to describe how :class:`Pattern` color/alpha will
    be determined for areas "outside" the pattern's natural area, (for
    example, outside the surface bounds or outside the gradient geometry).

    The default extend mode is :attr:`NONE` for :class:`SurfacePattern` and
    :attr:`PAD` for :class:`Gradient` patterns.

    .. versionadded:: 1.13
    """

    NONE: "Extend" = ...
    """pixels outside of the source pattern are fully transparent"""

    PAD: "Extend" = ...
    """
    pixels outside of the pattern copy the closest pixel from the source
    (Since 1.2; but only implemented for surface patterns since 1.6)
    """

    REFLECT: "Extend" = ...
    """
    the pattern is tiled by reflecting at the edges (Implemented for
    surface patterns since 1.6)
    """

    REPEAT: "Extend" = ...
    """the pattern is tiled by repeating"""

class FontSlant(_IntEnum):
    """
    These constants specify variants of a :class:`FontFace` based on their
    slant.

    .. versionadded:: 1.13
    """

    ITALIC: "FontSlant" = ...
    """Italic font style"""

    NORMAL: "FontSlant" = ...
    """Upright font style"""

    OBLIQUE: "FontSlant" = ...
    """Oblique font style"""

class FontWeight(_IntEnum):
    """
    These constants specify variants of a :class:`FontFace` based on their
    weight.

    .. versionadded:: 1.13
    """

    BOLD: "FontWeight" = ...
    """Bold font weight"""

    NORMAL: "FontWeight" = ...
    """Normal font weight"""

class Status(_IntEnum):
    """
    .. versionadded:: 1.13
    """

    CLIP_NOT_REPRESENTABLE: "Status" = ...
    DEVICE_ERROR: "Status" = ...
    DEVICE_FINISHED: "Status" = ...
    DEVICE_TYPE_MISMATCH: "Status" = ...
    FILE_NOT_FOUND: "Status" = ...
    FONT_TYPE_MISMATCH: "Status" = ...
    INVALID_CLUSTERS: "Status" = ...
    INVALID_CONTENT: "Status" = ...
    INVALID_DASH: "Status" = ...
    INVALID_DSC_COMMENT: "Status" = ...
    INVALID_FORMAT: "Status" = ...
    INVALID_INDEX: "Status" = ...
    INVALID_MATRIX: "Status" = ...
    INVALID_MESH_CONSTRUCTION: "Status" = ...
    INVALID_PATH_DATA: "Status" = ...
    INVALID_POP_GROUP: "Status" = ...
    INVALID_RESTORE: "Status" = ...
    INVALID_SIZE: "Status" = ...
    INVALID_SLANT: "Status" = ...
    INVALID_STATUS: "Status" = ...
    INVALID_STRIDE: "Status" = ...
    INVALID_STRING: "Status" = ...
    INVALID_VISUAL: "Status" = ...
    INVALID_WEIGHT: "Status" = ...
    JBIG2_GLOBAL_MISSING: "Status" = ...
    """
    .. versionadded:: 1.14
    """
    LAST_STATUS: "Status" = ...
    NEGATIVE_COUNT: "Status" = ...
    NO_CURRENT_POINT: "Status" = ...
    NO_MEMORY: "Status" = ...
    NULL_POINTER: "Status" = ...
    PATTERN_TYPE_MISMATCH: "Status" = ...
    READ_ERROR: "Status" = ...
    SUCCESS: "Status" = ...
    SURFACE_FINISHED: "Status" = ...
    SURFACE_TYPE_MISMATCH: "Status" = ...
    TEMP_FILE_ERROR: "Status" = ...
    USER_FONT_ERROR: "Status" = ...
    USER_FONT_IMMUTABLE: "Status" = ...
    USER_FONT_NOT_IMPLEMENTED: "Status" = ...
    WRITE_ERROR: "Status" = ...
    TAG_ERROR: "Status" = ...
    """
    .. versionadded:: 1.18.0 Only available with cairo 1.15.10+
    """
    FREETYPE_ERROR: "Status" = ...
    """
    .. versionadded:: 1.18.0 Only available with cairo 1.15.10+
    """
    PNG_ERROR: "Status" = ...
    """
    .. versionadded:: 1.18.0 Only available with cairo 1.15.10+
    """
    WIN32_GDI_ERROR: "Status" = ...
    """
    .. versionadded:: 1.18.0 Only available with cairo 1.15.10+
    """
    DWRITE_ERROR: "Status" = ...
    """
    .. versionadded:: 1.23.0 Only available with cairo 1.17.6+
    """
    SVG_FONT_ERROR: "Status" = ...
    """
    .. versionadded:: 1.25.0 Only available with cairo 1.17.8+
    """

class PDFVersion(_IntEnum):
    """
    These constants are used to describe the version number of the PDF
    specification that a generated PDF file will conform to.

    .. versionadded:: 1.13
    """

    VERSION_1_4: "PDFVersion" = ...
    """The version 1.4 of the PDF specification."""

    VERSION_1_5: "PDFVersion" = ...
    """The version 1.5 of the PDF specification."""

    VERSION_1_6: "PDFVersion" = ...
    """
    The version 1.6 of the PDF specification.

    .. versionadded:: 1.23.0 Only available with cairo 1.17.6+
    """

    VERSION_1_7: "PDFVersion" = ...
    """
    The version 1.7 of the PDF specification.

    .. versionadded:: 1.23.0 Only available with cairo 1.17.6+
    """

class PSLevel(_IntEnum):
    """
    These constants are used to describe the language level of the PostScript
    Language Reference that a generated PostScript file will conform to.
    Note: the constants are only defined when cairo has been compiled with PS
    support enabled.

    .. versionadded:: 1.13
    """

    LEVEL_2: "PSLevel" = ...
    """The language level 2 of the PostScript specification."""

    LEVEL_3: "PSLevel" = ...
    """The language level 3 of the PostScript specification."""

class PathDataType(_IntEnum):
    """
    These constants are used to describe the type of one portion of a path
    when represented as a :class:`Path`.

    .. versionadded:: 1.13
    """

    CLOSE_PATH: "PathDataType" = ...
    """A close-path operation"""

    CURVE_TO: "PathDataType" = ...
    """A curve-to operation"""

    LINE_TO: "PathDataType" = ...
    """ A line-to operation"""

    MOVE_TO: "PathDataType" = ...
    """A move-to operation"""

class RegionOverlap(_IntEnum):
    """
    .. versionadded:: 1.13
    """

    IN: "RegionOverlap" = ...
    """The contents are entirely inside the region."""

    OUT: "RegionOverlap" = ...
    """The contents are entirely outside the region."""

    PART: "RegionOverlap" = ...
    """The contents are partially inside and partially outside the region."""

class SVGVersion(_IntEnum):
    """
    These constants are used to describe the version number of the SVG
    specification that a generated SVG file will conform to.

    .. versionadded:: 1.13
    """

    VERSION_1_1: "SVGVersion" = ...
    """The version 1.1 of the SVG specification."""

    VERSION_1_2: "SVGVersion" = ...
    """The version 1.2 of the SVG specification."""

class SVGUnit(_IntEnum):
    """
    :class:`SVGUnit` is used to describe the units valid for coordinates and
    lengths in the SVG specification.

    See also:

    * https://www.w3.org/TR/SVG/coords.htmlUnits
    * https://www.w3.org/TR/SVG/types.htmlDataTypeLength
    * https://www.w3.org/TR/css-values-3/lengths

    .. versionadded:: 1.18.0 Only available with cairo 1.15.10+
    """

    USER: "SVGUnit" = ...
    """
    User unit, a value in the current coordinate system. If used in the
    root element for the initial coordinate systems it corresponds to
    pixels.
    """

    EM: "SVGUnit" = ...
    """The size of the element's font."""

    EX: "SVGUnit" = ...
    """The x-height of the element’s font."""

    PX: "SVGUnit" = ...
    """Pixels (1px = 1/96th of 1in)."""

    IN: "SVGUnit" = ...
    """Inches (1in = 2.54cm = 96px)"""

    CM: "SVGUnit" = ...
    """Centimeters (1cm = 96px/2.54)."""

    MM: "SVGUnit" = ...
    """Millimeters (1mm = 1/10th of 1cm)."""

    PT: "SVGUnit" = ...
    """Points (1pt = 1/72th of 1in)."""

    PC: "SVGUnit" = ...
    """Picas (1pc = 1/6th of 1in)."""

    PERCENT: "SVGUnit" = ...
    """Percent, a value that is some fraction of another reference value."""

class PDFMetadata(_IntEnum):
    """
    :class:`PDFMetadata` is used by the :meth:`PDFSurface.set_metadata` method
    to specify the metadata to set.

    .. versionadded:: 1.18.0 Only available with cairo 1.15.10+
    """

    TITLE: "PDFMetadata" = ...
    """The document title"""

    AUTHOR: "PDFMetadata" = ...
    """The document author"""

    SUBJECT: "PDFMetadata" = ...
    """The document subject"""

    KEYWORDS: "PDFMetadata" = ...
    """The document keywords"""

    CREATOR: "PDFMetadata" = ...
    """The document creator"""

    CREATE_DATE: "PDFMetadata" = ...
    """The document creation date"""

    MOD_DATE: "PDFMetadata" = ...
    """The document modification date"""

class PDFOutlineFlags(_IntEnum):
    """
    :class:`PDFOutlineFlags` is used by the :meth:`PDFSurface.add_outline`
    method to specify the attributes of an outline item. These flags may be
    bitwise-or'd to produce any combination of flags.

    .. versionadded:: 1.18.0 Only available with cairo 1.15.10+
    """

    OPEN: "PDFOutlineFlags" = ...
    """The outline item defaults to open in the PDF viewer"""

    BOLD: "PDFOutlineFlags" = ...
    """The outline item is displayed by the viewer in bold text"""

    ITALIC: "PDFOutlineFlags" = ...
    """The outline item is displayed by the viewer in italic text"""

class ScriptMode(_IntEnum):
    """
    A set of script output variants.

    .. versionadded:: 1.14
    """

    ASCII: "ScriptMode" = ...
    """the output will be in readable text (default)"""

    BINARY: "ScriptMode" = ...
    """the output will use byte codes."""

class Matrix:
    """
    *Matrix* is used throughout cairo to convert between different coordinate
    spaces.  A *Matrix* holds an affine transformation, such as a scale,
    rotation, shear, or a combination of these.  The transformation of a point
    (x,y) is given by::

        x_new = xx * x + xy * y + x0
        y_new = yx * x + yy * y + y0

    The current transformation matrix of a :class:`Context`, represented as a
    *Matrix*, defines the transformation from user-space coordinates to
    device-space coordinates.

    Some standard Python operators can be used with matrices:

    To read the values from a *Matrix*::

        xx, yx, xy, yy, x0, y0 = matrix

    To multiply two matrices::

        matrix3 = matrix1.multiply(matrix2)
        # or equivalently
        matrix3 = matrix1 * matrix2

    To compare two matrices::

        matrix1 == matrix2
        matrix1 != matrix2

    For more information on matrix transformation see
    https://www.cairographics.org/cookbook/matrix_transform/
    """

    def __init__(self, xx: float = 1.0, yx: float = 0.0, xy: float = 0.0, yy: float = 1.0, x0: float = 0.0, y0: float = 0.0) -> None:
        """
        :param xx: xx component of the affine transformation
        :param yx: yx component of the affine transformation
        :param xy: xy component of the affine transformation
        :param yy: yy component of the affine transformation
        :param x0: X translation component of the affine transformation
        :param y0: Y translation component of the affine transformation

        Create a new *Matrix* with the affine transformation given by *xx, yx,
        xy, yy, x0, y0*. The transformation is given by::

            x_new = xx * x + xy * y + x0
            y_new = yx * x + yy * y + y0

        To create a new identity matrix::

            matrix = cairo.Matrix()

        To create a matrix with a transformation which translates by tx and ty
        in the X and Y dimensions, respectively::

            matrix = cairo.Matrix(x0=tx, y0=ty)

        To create a matrix with a transformation that scales by sx and sy in the
        X and Y dimensions, respectively::

            matrix = cairo.Matrix(xx=sy, yy=sy)
        """

    @classmethod
    def init_rotate(cls, radians: float) -> "Matrix":
        """
        :param radians: angle of rotation, in radians. The direction of rotation
            is defined such that positive angles rotate in the direction from the
            positive X axis toward the positive Y axis. With the default axis
            orientation of cairo, positive angles rotate in a clockwise direction.
        :returns: a new *Matrix* set to a transformation that rotates by *radians*.
        """

    def invert(self) -> Optional["Matrix"]:
        """
        :returns: If *Matrix* has an inverse, modifies *Matrix* to be the
            inverse matrix and returns *None*
        :raises: :exc:`cairo.Error` if the *Matrix* as no inverse

        Changes *Matrix* to be the inverse of it's original value. Not all
        transformation matrices have inverses; if the matrix collapses points
        together (it is *degenerate*), then it has no inverse and this function
        will fail.
        """

    def multiply(self, matrix2: "Matrix") -> "Matrix":
        """
        :param matrix2: a second matrix
        :returns: a new *Matrix*

        Multiplies the affine transformations in *Matrix* and *matrix2*
        together. The effect of the resulting transformation is to first apply
        the transformation in *Matrix* to the coordinates and then apply the
        transformation in *matrix2* to the coordinates.

        It is allowable for result to be identical to either *Matrix* or *matrix2*.
        """

    def rotate(self, radians: float) -> None:
        """
        :param radians: angle of rotation, in radians. The direction of rotation
            is defined such that positive angles rotate in the direction from the
            positive X axis toward the positive Y axis. With the default axis
            orientation of cairo, positive angles rotate in a clockwise direction.

        Initialize *Matrix* to a transformation that rotates by *radians*.
        """

    def scale(self, sx: float, sy: float) -> None:
        """
        :param sx: scale factor in the X direction
        :param sy: scale factor in the Y direction

        Applies scaling by *sx, sy* to the transformation in *Matrix*. The
        effect of the new transformation is to first scale the coordinates by
        *sx* and *sy*, then apply the original transformation to the
        coordinates.
        """

    def transform_distance(self, dx: float, dy: float) -> Tuple[float, float]:
        """
        :param dx: X component of a distance vector.
        :param dy: Y component of a distance vector.
        :returns: the transformed distance vector (dx,dy), both float

        Transforms the distance vector *(dx,dy)* by *Matrix*. This is similar to
        :meth:`.transform_point` except that the translation components of
        the transformation are ignored. The calculation of the returned vector
        is as follows::

            dx2 = dx1 * a + dy1 * c
            dy2 = dx1 * b + dy1 * d

        Affine transformations are position invariant, so the same vector always
        transforms to the same vector. If *(x1,y1)* transforms to *(x2,y2)* then
        *(x1+dx1,y1+dy1)* will transform to *(x1+dx2,y1+dy2)* for all values
        of *x1* and *x2*.
        """

    def transform_point(self, x: float, y: float) -> Tuple[float, float]:
        """
        :param x: X position.
        :param y: Y position.
        :returns: the transformed point (x,y), both float

        Transforms the point *(x, y)* by *Matrix*.
        """

    def translate(self, tx: float, ty: float) -> None:
        """
        :param tx: amount to translate in the X direction
        :param ty: amount to translate in the Y direction

        Applies a transformation by *tx, ty* to the transformation in
        *Matrix*. The effect of the new transformation is to first translate the
        coordinates by *tx* and *ty*, then apply the original transformation to the
        coordinates.
        """

    xx: float = ...
    """
    xx component of the affine transformation

    .. versionadded:: 1.12.0
    """

    yx: float = ...
    """
    yx component of the affine transformation

    .. versionadded:: 1.12.0
    """

    xy: float = ...
    """
    xy component of the affine transformation

    .. versionadded:: 1.12.0
    """

    yy: float = ...
    """
    yy component of the affine transformation

    .. versionadded:: 1.12.0
    """

    x0: float = ...
    """
    X translation component of the affine transformation

    .. versionadded:: 1.12.0
    """

    y0: float = ...
    """
    Y translation component of the affine transformation

    .. versionadded:: 1.12.0
    """

class Pattern:
    """
    *Pattern* is the abstract base class from which all the other pattern classes
    derive. It cannot be instantiated directly.
    """

    def get_extend(self) -> Extend:
        """
        :returns: the current extend strategy used for drawing the *Pattern*.

        Gets the current extend mode for the *Pattern*. See
        :class:`cairo.Extend` attributes for details on the semantics of each
        extend strategy.
        """

    def get_matrix(self) -> Matrix:
        """
        :returns: a new :class:`Matrix` which stores a copy of the *Pattern's*
            transformation matrix
        """

    def get_filter(self) -> Filter:
        """
        :returns: the current filter used for
            resizing the pattern.

        .. versionadded:: 1.12.0

            Used to be a method of :class:`SurfacePattern` before
        """

    def set_filter(self, filter: Filter) -> None:
        """
        :param filter: a filter describing the filter
            to use for resizing the pattern

        Note that you might want to control filtering even when you do not have
        an explicit *Pattern* object, (for example when using
        :meth:`Context.set_source_surface`). In these cases, it is convenient to
        use :meth:`Context.get_source` to get access to the pattern that cairo
        creates implicitly. For example::

            context.set_source_surface(image, x, y)
            context.get_source().set_filter(cairo.FILTER_NEAREST)

        .. versionadded:: 1.12.0

            Used to be a method of :class:`SurfacePattern` before
        """

    def set_extend(self, extend: Extend) -> None:
        """
        :param extend: an extend describing how the
            area outside of the *Pattern* will be drawn

        Sets the mode to be used for drawing outside the area of a *Pattern*.

        The default extend mode is :attr:`cairo.Extend.NONE` for
        :class:`SurfacePattern` and :attr:`cairo.Extend.PAD` for
        :class:`Gradient` Patterns.
        """

    def set_matrix(self, matrix: Matrix) -> None:
        """
        :param matrix: a :class:`Matrix`

        Sets the *Pattern's* transformation matrix to *matrix*. This matrix is a
        transformation from user space to pattern space.

        When a *Pattern* is first created it always has the identity matrix for
        its transformation matrix, which means that pattern space is initially
        identical to user space.

        Important: Please note that the direction of this transformation matrix
        is from user space to pattern space. This means that if you imagine the
        flow from a *Pattern* to user space (and on to device space), then
        coordinates in that flow will be transformed by the inverse of the
        *Pattern* matrix.

        For example, if you want to make a *Pattern* appear twice as large as it
        does by default the correct code to use is::

            matrix = cairo.Matrix(xx=0.5,yy=0.5)
            pattern.set_matrix(matrix)

        Meanwhile, using values of 2.0 rather than 0.5 in the code above would
        cause the *Pattern* to appear at half of its default size.

        Also, please note the discussion of the user-space locking semantics of
        :class:`Context.set_source`.
        """

    def get_dither(self) -> Dither:
        """
        :returns: the current dithering mode.

        Gets the current dithering mode, as set by :meth:`Pattern.set_dither`.

        .. versionadded:: 1.25.0 Only available with cairo 1.18.0+
        """

    def set_dither(self, dither: Dither) -> None:
        """
        :param dither: a :class:`Dither` describing the new dithering mode

        Set the dithering mode of the rasterizer used for drawing shapes. This
        value is a hint, and a particular backend may or may not support a
        particular value.  At the current time, only pixman is supported.

        .. versionadded:: 1.25.0 Only available with cairo 1.18.0+
        """

class Glyph(Tuple[int, float, float]):
    """
    The :class:`Glyph` holds information about a single glyph when drawing or
    measuring text. A font is (in simple terms) a collection of shapes used to
    draw text. A glyph is one of these shapes. There can be multiple glyphs
    for a single character (alternates to be used in different contexts, for
    example), or a glyph can be a ligature of multiple characters. Cairo
    doesn't expose any way of converting input text into glyphs, so in order
    to use the Cairo interfaces that take arrays of glyphs, you must directly
    access the appropriate underlying font system.

    Note that the offsets given by x and y are not cumulative. When drawing or
    measuring text, each glyph is individually positioned with respect to the
    overall origin

    .. versionadded:: 1.15
        In prior versions a (int, float, float) tuple was used instead
        of :class:`Glyph`.
    """

    index: int = ... # type: ignore
    x: float = ...
    y: float = ...

    def __init__(self, index: int, x: float, y: float) -> None:
        """
        :param index:
            glyph index in the font. The exact interpretation of the glyph index
            depends on the font technology being used.
        :param x:
            the offset in the X direction between the origin used for drawing or
            measuring the string and the origin of this glyph.
        :param y:
            the offset in the Y direction between the origin used for drawing or
            measuring the string and the origin of this glyph.
        """

class TextCluster(Tuple[int, int]):
    """
    .. versionadded:: 1.15

    The :class:`TextCluster` structure holds information about a single text
    cluster. A text cluster is a minimal mapping of some glyphs corresponding
    to some UTF-8 text.

    For a cluster to be valid, both ``num_bytes`` and ``num_glyphs`` should be
    non-negative, and at least one should be non-zero. Note that clusters with
    zero glyphs are not as well supported as normal clusters. For example, PDF
    rendering applications typically ignore those clusters when PDF text is
    being selected.

    See :meth:`Context.show_text_glyphs` for how clusters are used in advanced
    text operations.
    """
    num_bytes: int = ...
    num_glyphs: int = ...
    def __init__(self, num_bytes: int, num_glyphs: int) -> None:
        """
        :param num_bytes:
            the number of bytes of UTF-8 text covered by cluster
        :param num_glyphs:
            the number of glyphs covered by cluster
        """

class TextClusterFlags(_IntEnum):
    """
    Specifies properties of a text cluster mapping.

    .. versionadded:: 1.14
    """

    BACKWARD: "TextClusterFlags" = ...
    """
    The clusters in the cluster array map to glyphs in the glyph array
    from end to start.
    """

class TextExtents(Tuple[float, float, float, float, float, float]):
    """
    .. versionadded:: 1.15
        In prior versions a (float, float, float, float, float, float) tuple
        was used instead of :class:`TextExtents`.

    The :class:`TextExtents` class stores the extents of a single glyph or a
    string of glyphs in user-space coordinates. Because text extents are in
    user-space coordinates, they are mostly, but not entirely, independent of
    the current transformation matrix. If you call ``context.scale(2.0,
    2.0)``, text will be drawn twice as big, but the reported text extents
    will not be doubled. They will change slightly due to hinting (so you
    can't assume that metrics are independent of the transformation matrix),
    but otherwise will remain unchanged.
    """
    x_bearing: float = ...
    y_bearing: float = ...
    width: float = ...
    height: float = ...
    x_advance: float = ...
    y_advance: float = ...
    def __init__(self, x_bearing: float, y_bearing: float, width: float, height: float, x_advance: float, y_advance: float) -> None:
        """
        :param x_bearing:
            the horizontal distance from the origin to the leftmost part of the
            glyphs as drawn. Positive if the glyphs lie entirely to the right of
            the origin.
        :param y_bearing:
            the vertical distance from the origin to the topmost part of the
            glyphs as drawn. Positive only if the glyphs lie completely below the
            origin; will usually be negative.
        :param width:
            width of the glyphs as drawn
        :param height:
            height of the glyphs as drawn
        :param x_advance:
            distance to advance in the X direction after drawing these glyphs
        :param y_advance:
            distance to advance in the Y direction after drawing these glyphs.
            Will typically be zero except for vertical text layout as found in
            East-Asian languages.
        """

class RectangleInt:
    """
    RectangleInt is a data structure for holding a rectangle with integer coordinates.

    .. versionadded:: 1.11.0
    """

    height: int = ...
    width: int = ...
    x: int = ...
    y: int = ...

    def __init__(self, x: int=0, y: int=0, width: int=0, height: int=0) -> None:
        """
        :param x:
            X coordinate of the left side of the rectangle.
        :param y:
            Y coordinate of the top side of the rectangle.
        :param width:
            Width of the rectangle.
        :param height:
            Height of the rectangle.

        Allocates a new RectangleInt object.
        """


class FontFace:
    """
    A *cairo.FontFace* specifies all aspects of a font other than the size or font
    matrix (a font matrix is used to distort a font by sheering it or scaling it
    unequally in the two directions). A *FontFace* can be set on a
    :class:`Context` by using :meth:`Context.set_font_face` the size and font
    matrix are set with :meth:`Context.set_font_size` and
    :meth:`Context.set_font_matrix`.

    There are various types of *FontFace*, depending on the font backend they
    use.

    .. note:: This class cannot be instantiated directly, it is returned by
        :meth:`Context.get_font_face`.
    """

class FontOptions:
    """
    An opaque structure holding all options that are used when rendering fonts.

    Individual features of a *FontOptions* can be set or accessed using functions
    named *FontOptions.set_<feature_name>* and
    *FontOptions.get_<feature_name>*,  like :meth:`FontOptions.set_antialias`
    and :meth:`FontOptions.get_antialias`.

    New features may be added to a *FontOptions* in the future. For this reason,
    :meth:`FontOptions.copy()`, :meth:`FontOptions.equal()`,
    :meth:`FontOptions.merge()`, and :meth:`FontOptions.hash()` should be used to
    copy, check for equality, merge, or compute a hash value of FontOptions
    objects.

    Implements `__eq__` and `__ne__` using `equal()` since 1.12.0.
    """

    def __init__(self) -> None:
        """
        Allocates a new FontOptions object with all options initialized to default
        values.
        """

    def get_antialias(self) -> Antialias:
        """
        :returns: the antialias mode for the *FontOptions* object
        """

    def get_hint_style(self) -> HintStyle:
        """
        :returns: the hint style for the *FontOptions* object
        """

    def get_subpixel_order(self) -> SubpixelOrder:
        """
        :returns: the subpixel order for the *FontOptions* object
        """

    def set_antialias(self, antialias: Antialias) -> None:
        """
        :param antialias: the antialias mode

        This specifies the type of antialiasing to do when rendering text.
        """

    def set_hint_metrics(self, hint_metrics: HintMetrics) -> None:
        """
        :param hint_metrics: the hint metrics mode

        This controls whether metrics are quantized to integer values in device
        units.
        """

    def set_hint_style(self, hint_style: HintStyle) -> None:
        """
        :param hint_style: the hint style

        This controls whether to fit font outlines to the pixel grid, and if so,
        whether to optimize for fidelity or contrast.
        """

    def merge(self, other: "FontOptions") -> None:
        """
        :param FontOptions other: another :class:`FontOptions`

        Merges non-default options from other into options , replacing existing
        values. This operation can be thought of as somewhat similar to
        compositing other onto options with the operation of
        :attr:`Operator.OVER`.

        .. versionadded:: 1.12.0
        """

    def copy(self) -> "FontOptions":
        """
        :returns: a new :class:`FontOptions`

        Returns a new font options object copying the option values from
        original.

        .. versionadded:: 1.12.0
        """

    def hash(self) -> int:
        """
        :returns: the hash value for the font options object

        Compute a hash for the font options object; this value will be useful
        when storing an object containing a :class:`FontOptions` in a hash
        table.

        .. versionadded:: 1.12.0
        """

    def equal(self, other: "FontOptions") -> bool:
        """
        :param other: another :class:`FontOptions`
        :returns: :obj:`True` if all fields of the two font options objects
            match. Note that this function will return :obj:`False` if either
            object is in error.

        Compares two font options objects for equality.

        .. versionadded:: 1.12.0
        """

    def set_variations(self, variations: Optional[str]) -> None:
        """
        :param variations: the new font variations, or :obj:`None`

        Sets the OpenType font variations for the font options object. Font
        variations are specified as a string with a format that is similar to
        the CSS font-variation-settings. The string contains a comma-separated
        list of axis assignments, which each assignment consists of a
        4-character axis name and a value, separated by whitespace and
        optional equals sign.

        Examples:

        * wght=200,wdth=140.5
        * wght 200 , wdth 140.5

        .. versionadded:: 1.18.0 Only available with cairo 1.15.12+
        """

    def get_variations(self) -> str:
        """
        :returns:
            the font variations for the font options object. The returned
            string belongs to the options and must not be modified. It is
            valid until either the font options object is destroyed or the
            font variations in this object is modified with
            :meth:`set_variations`.

        Gets the OpenType font variations for the font options object. See
        :meth:`set_variations` for details about the string format.

        .. versionadded:: 1.18.0 Only available with cairo 1.15.12+
        """

    def get_hint_metrics(self) -> HintMetrics:
        """
        :returns: the hint metrics mode for the *FontOptions* object
        """

    def set_subpixel_order(self, subpixel_order: SubpixelOrder) -> None:
        """
        :param subpixel_order: the subpixel order

        The subpixel order specifies the order of color elements within each
        pixel on the display device when rendering with an antialiasing mode of
        :attr:`cairo.Antialias.SUBPIXEL`.
        """

    def set_color_mode(self, color_mode: ColorMode) -> None:
        """
        :param color_mode: the new color mode

        Sets the color mode for the font options object. This controls whether
        color fonts are to be rendered in color or as outlines. See the
        documentation for :class:`ColorMode` for full details.

        .. versionadded:: 1.25.0 Only available with cairo 1.17.8+
        """

    def get_color_mode(self) -> ColorMode:
        """
        :returns: the color mode for the font options object

        Gets the color mode for the font options object. See the documentation
        for :class:`ColorMode` for full details.

        .. versionadded:: 1.25.0 Only available with cairo 1.17.8+
        """

    def set_color_palette(self, palette_index: int) -> None:
        """
        :param palette_index: the palette index in the CPAL table

        Sets the OpenType font color palette for the font options object.
        OpenType color fonts with a CPAL table may contain multiple palettes.
        The default color palette index is :data:`COLOR_PALETTE_DEFAULT`. If
        palette_index is invalid, the default palette is used.

        .. versionadded:: 1.25.0 Only available with cairo 1.17.8+
        """

    def get_color_palette(self) -> int:
        """
        :returns: the palette index

        Gets the OpenType color font palette for the font options object.

        .. versionadded:: 1.25.0 Only available with cairo 1.17.8+
        """

    def set_custom_palette_color(self, index: int, red: float, green: float, blue: float, alpha: float) -> None:
        """
        :param index: the index of the color to set
        :param red: red component of color
        :param green: green component of color
        :param blue: blue component of color
        :param alpha: alpha component of color

        Sets a custom palette color for the font options object. This overrides
        the palette color at the specified color index. This override is
        independent of the selected palette index and will remain in place even
        if :meth:`FontOptions.set_color_palette` is called to change the palette
        index.

        It is only possible to override color indexes already in the font
        palette.

        .. versionadded:: 1.25.0 Only available with cairo 1.17.8+
        """

    def get_custom_palette_color(self, index: int) -> Tuple[float, float, float, float]:
        """
        :param index: the index of the color to get
        :returns: a (red, green, blue, alpha) tuple of float
        :raises Error: if no custom color exists for the color index.

        Gets the custom palette color for the color index for the font options
        object.

        .. versionadded:: 1.25.0 Only available with cairo 1.17.8+
        """

class ScaledFont:
    """
    A *ScaledFont* is a font scaled to a particular size and device resolution. A
    *ScaledFont* is most useful for low-level font usage where a library or
    application wants to cache a reference to a scaled font to speed up the
    computation of metrics.

    There are various types of scaled fonts, depending on the font backend they
    use.
    """

    def __init__(self, font_face: FontFace, font_matrix: Matrix, ctm: Matrix, options: FontOptions) -> None:
        """
            :param font_face: a :class:`FontFace` instance
            :param font_matrix: font space to user space transformation :class:`Matrix`
                for the font. In the simplest case of a N point font, this matrix is just
                a scale by N, but it can also be used to shear the font or stretch it
                unequally along the two axes. See :meth:`Context.set_font_matrix`.
            :param ctm: user to device transformation :class:`Matrix` with which the
                font will be used.
            :param options: a :class:`FontOptions` instance to use when getting metrics
                for the font and rendering with it.

            Creates a *ScaledFont* object from a *FontFace* and matrices that describe
            the size of the font and the environment in which it will be used.
        """

    def extents(self) -> Tuple[float, float, float, float, float]:
        """
        Gets the metrics for a *ScaledFont*.
        """

    def get_ctm(self) -> Matrix:
        """
            :returns: the CTM

            Returns the CTM with which scaled_font was created into ctm. Note that
            the translation offsets (x0, y0) of the CTM are ignored by
            :func:`ScaledFont`. So, the matrix this function returns always has 0,
            0 as x0, y0.

            .. versionadded:: 1.12.0
        """

    def get_font_face(self) -> FontFace:
        """
            :returns: the :class:`FontFace` that this *ScaledFont* was created for.

            .. versionadded:: 1.2
        """

    def get_font_matrix(self) -> Matrix:
        """
            :returns: the matrix

            Returns the font matrix with which scaled_font was created.
        """

    def get_font_options(self) -> FontOptions:
        """
            :returns: font options

            Returns the font options with which scaled_font was created.

            .. versionadded:: 1.12.0
        """

    def get_scale_matrix(self) -> Matrix:
        """
            :returns: the scale :class:`Matrix`

            The scale matrix is product of the font matrix and the ctm associated
            with the scaled font, and hence is the matrix mapping from font space to
            device space.

            .. versionadded:: 1.8
        """

    def glyph_extents(self, glyphs: Sequence[Glyph]) -> TextExtents:
        """
            :param glyphs: glyphs, a sequence of :class:`Glyph`

            .. versionadded:: 1.15

            Gets the extents for a list of glyphs. The extents describe a user-space
            rectangle that encloses the "inked" portion of the glyphs, (as they
            would be drawn by :meth:`Context.show_glyphs` if the cairo graphics
            state were set to the same font_face, font_matrix, ctm, and font_options
            as scaled_font ). Additionally, the x_advance and y_advance values
            indicate the amount by which the current point would be advanced by
            cairo_show_glyphs().

            Note that whitespace glyphs do not contribute to the size of the
            rectangle (extents.width and extents.height).
        """

    def text_extents(self, text: str) -> TextExtents:
        """
            :param text: text

            Gets the extents for a string of text. The extents describe a user-space
            rectangle that encloses the "inked" portion of the text drawn at the
            origin (0,0) (as it would be drawn by :meth:`Context.show_text` if the
            cairo graphics state were set to the same font_face, font_matrix, ctm,
            and font_options as *ScaledFont*).  Additionally, the x_advance and
            y_advance values indicate the amount by which the current point would be
            advanced by :meth:`Context.show_text`.

            Note that whitespace characters do not directly contribute to the size
            of the rectangle (width and height). They do contribute indirectly by
            changing the position of non-whitespace characters. In particular,
            trailing whitespace characters are likely to not affect the size of the
            rectangle, though they will affect the x_advance and y_advance values.

            .. versionadded:: 1.2
        """

    def text_to_glyphs(self, x: float, y: float, utf8: str, with_clusters: bool = True) -> Union[Tuple[List[Glyph], List["TextCluster"], TextClusterFlags], List[Glyph]]:
        """
            :param x: X position to place first glyph
            :param y: Y position to place first glyph
            :param utf8: a string of text
            :param with_clusters:
                If :obj:`False` only the glyph list will computed and returned
            :returns:
                a tuple of ([:class:`Glyph`], [:class:`TextCluster`],
                :class:`TextClusterFlags`)
            :raises Error:

            .. versionadded:: 1.15

            Converts UTF-8 text to a list of glyphs, with cluster mapping, that can
            be used to render later.

            For details of how clusters, and cluster_flags map input UTF-8 text to
            the output glyphs see :meth:`Context.show_text_glyphs`.

            The output values can be readily passed to
            :meth:`Context.show_text_glyphs` :meth:`Context.show_glyphs`, or related
            functions, assuming that the exact same scaled font is used for the
            operation.
        """

_SomeDevice = TypeVar("_SomeDevice", bound="Device")

class Device:
    """
    A :class:`Device` represents the driver interface for drawing operations
    to a :class:`Surface`.

    .. versionadded:: 1.14

    .. note::

        .. versionadded:: 1.17.0

            :class:`cairo.Device` can be used as a context manager:

        .. code:: python

            # device.finish() will be called on __exit__
            with cairo.ScriptDevice(f) as device:
                pass
    """

    def finish(self) -> None:
        """
        This function finishes the device and drops all references to external
        resources. All surfaces, fonts and other objects created for this
        device will be finished, too. Further operations on the device will
        not affect the device but will instead trigger a
        :attr:`Status.DEVICE_FINISHED` error.

        This function may acquire devices.

        .. versionadded:: 1.14
        """

    def flush(self) -> None:
        """
        Finish any pending operations for the device and also restore any
        temporary modifications cairo has made to the device's state. This
        function must be called before switching from using the device with
        Cairo to operating on it directly with native APIs. If the device
        doesn't support direct access, then this function does nothing.

        This function may acquire devices.

        .. versionadded:: 1.14
        """

    def acquire(self) -> None:
        """
        :raises cairo.Error:
            If the device is in an error state and could not be acquired.

        Acquires the device for the current thread. This function will block
        until no other thread has acquired the device.

        If the does not raise, you successfully acquired the device. From now
        on your thread owns the device and no other thread will be able to
        acquire it until a matching call to :meth:`release`. It is allowed to
        recursively acquire the device multiple times from the same thread.

        After a successful call to :meth:`acquire`, a matching call to
        :meth:`release` is required.

        .. note::

            You must never acquire two different devices at the same time
            unless this is explicitly allowed. Otherwise the possibility of
            deadlocks exist. As various Cairo functions can acquire devices
            when called, these functions may also cause deadlocks when you
            call them with an acquired device. So you must not have a device
            acquired when calling them. These functions are marked in the
            documentation.

        .. versionadded:: 1.14
        """

    def release(self) -> None:
        """
        Releases a device previously acquired using :meth:`acquire`. See that
        function for details.

        .. versionadded:: 1.14
        """

    def __enter__(self: _SomeDevice) -> _SomeDevice: ...
    __exit__: Any = ...

_PathLike = Union[Text, ByteString]
_FileLike = BinaryIO
_SomeSurface = TypeVar("_SomeSurface", bound="Surface")

class Surface:
    """
    cairo.Surface is the abstract type representing all different drawing targets
    that cairo can render to. The actual drawings are performed using a
    :class:`Context`.

    A cairo.Surface is created by using backend-specific constructors
    of the form cairo.<XXX>Surface().

    *Surface* is the abstract base class from which all the other surface
    classes derive. It cannot be instantiated directly.

    .. note::

        .. versionadded:: 1.17.0

            :class:`cairo.Surface` can be used as a context manager:

        .. code:: python

            # surface.finish() will be called on __exit__
            with cairo.SVGSurface("example.svg", 200, 200) as surface:
                pass

            # surface.unmap_image(image_surface) will be called on __exit__
            with surface.map_to_image(None) as image_surface:
                pass
    """

    def copy_page(self) -> None:
        """
        Emits the current page for backends that support multiple pages, but
        doesn't clear it, so that the contents of the current page will be
        retained for the next page.  Use :meth:`.show_page` if you want to get an
        empty page after the emission.

        :meth:`Context.copy_page` is a convenience function for this.

        .. versionadded:: 1.6
        """

    def create_for_rectangle(self, x: float, y: float, width: float, height: float) -> "Surface":
        """
        :param x: the x-origin of the sub-surface from the top-left of the
            target surface (in device-space units)
        :param y: the y-origin of the sub-surface from the top-left of the
            target surface (in device-space units)
        :param width: width of the sub-surface (in device-space units)
        :param height: height of the sub-surface (in device-space units)
        :returns: a new surface

        Create a new surface that is a rectangle within the target surface. All
        operations drawn to this surface are then clipped and translated onto
        the target surface. Nothing drawn via this sub-surface outside of its
        bounds is drawn onto the target surface, making this a useful method for
        passing constrained child surfaces to library routines that draw
        directly onto the parent surface, i.e. with no further backend
        allocations, double buffering or copies.

        .. note::

            The semantics of subsurfaces have not been finalized yet unless the
            rectangle is in full device units, is contained within the extents of
            the target surface, and the target or subsurface's device transforms
            are not changed.

        .. versionadded:: 1.12.0
        """

    def create_similar(self, content: Content, width: int, height: int) -> "Surface":
        """
        :param content: the content for the new
            surface
        :param width: width of the new surface, (in device-space units)
        :param height: height of the new surface (in device-space units)

        :returns: a newly allocated *Surface*.

        Create a *Surface* that is as compatible as possible with the existing
        surface. For example the new surface will have the same fallback
        resolution and :class:`FontOptions`. Generally, the new surface will
        also use the same backend, unless that is not possible for some
        reason.

        Initially the surface contents are all 0 (transparent if contents have
        transparency, black otherwise.)
        """

    def create_similar_image(self, format: Format, width: int, height: int) -> "ImageSurface":
        """
        :param cairo.Format format: the format for the new surface
        :param width: width of the new surface, (in device-space units)
        :param height: height of the new surface, (in device-space units)
        :returns: a new image surface

        Create a new image surface that is as compatible as possible for
        uploading to and the use in conjunction with an existing surface.
        However, this surface can still be used like any normal image surface.

        Initially the surface contents are all 0 (transparent if contents have
        transparency, black otherwise.)

        .. versionadded:: 1.12.0
        """

    def finish(self) -> None:
        """
        This method finishes the Surface and drops all references to external
        resources. For example, for the Xlib backend it means that cairo will no
        longer access the drawable, which can be freed. After calling finish()
        the only valid operations on a Surface are flushing and finishing it.
        Further drawing to the surface will not affect the surface but will
        instead trigger a `cairo.Error` exception.
        """

    def flush(self) -> None:
        """
        Do any pending drawing for the *Surface* and also restore any temporary
        modification's cairo has made to the *Surface's* state. This method
        must be called before switching from drawing on the *Surface* with cairo
        to drawing on it directly with native APIs. If the *Surface* doesn't
        support direct access, then this function does nothing.
        """

    def get_content(self) -> Content:
        """
        :returns: The content type of *Surface*,
            which indicates whether the *Surface* contains color and/or alpha
            information.

        .. versionadded:: 1.2
        """

    def get_device(self) -> Optional["Device"]:
        """
        :returns: the device or :obj:`None` if the surface does not have an
            associated device

        This function returns the device for a surface.

        .. versionadded:: 1.14.0
        """

    def get_device_offset(self) -> Tuple[float, float]:
        """
        :returns: (x_offset, y_offset) a tuple of float

            * x_offset: the offset in the X direction, in device units
            * y_offset: the offset in the Y direction, in device units

        This method returns the previous device offset set by
        :meth:`.set_device_offset`.

        .. versionadded:: 1.2
        """

    def get_device_scale(self) -> Tuple[float, float]:
        """
        :returns: (x_scale,y_scale) a 2-tuple of float

        This function returns the previous device offset set by
        :meth:`Surface.set_device_scale`.

        .. versionadded:: 1.14.0
        """

    def get_fallback_resolution(self) -> Tuple[float, float]:
        """
        :returns: (x_pixels_per_inch, y_pixels_per_inch) a tuple of float

            * x_pixels_per_inch: horizontal pixels per inch
            * y_pixels_per_inch: vertical pixels per inch

        This method returns the previous fallback resolution set by
        :meth:`.set_fallback_resolution`, or default fallback resolution if
        never set.

        .. versionadded:: 1.8
        """

    def get_font_options(self) -> FontOptions:
        """
        :returns: a :class:`FontOptions`

        Retrieves the default font rendering options for the *Surface*. This
        allows display surfaces to report the correct subpixel order for
        rendering on them, print surfaces to disable hinting of metrics and so
        forth. The result can then be used with :class:`ScaledFont`.
        """

    def get_mime_data(self, mime_type: str) -> Optional[bytes]:
        """
        :param mime_type: the MIME type of the image data
            (:ref:`constants_MIME_TYPE`)
        :returns: :class:`bytes` or :obj:`None`

        Return mime data previously attached to surface
        with :meth:`set_mime_data` using the specified mime type.
        If no data has been attached with the given mime type,
        :obj:`None` is returned.

        .. versionadded:: 1.12.0
        """

    def has_show_text_glyphs(self) -> bool:
        """
        :returns: :obj:`True` if surface supports
            :meth:`Context.show_text_glyphs`, :obj:`False` otherwise

        Returns whether the surface supports sophisticated
        :meth:`Context.show_text_glyphs` operations. That is, whether it
        actually uses the provided text and cluster data to a
        :meth:`Context.show_text_glyphs` call.

        Note: Even if this function returns :obj:`False`, a
        :meth:`Context.show_text_glyphs` operation targeted at surface will
        still succeed. It just will act like a :meth:`Context.show_glyphs`
        operation. Users can use this function to avoid computing UTF-8 text and
        cluster mapping if the target surface does not use it.

        .. versionadded:: 1.12.0
        """

    def map_to_image(self, extents: Optional[RectangleInt]) -> "ImageSurface":
        """
        :param extents: limit the extraction to an rectangular
            region or :obj:`None` for the whole surface

        :returns: newly allocated image surface
        :raises Error:

        Returns an image surface that is the most efficient mechanism for
        modifying the backing store of the target surface.

        Note, the use of the original surface as a target or source whilst it is
        mapped is undefined. The result of mapping the surface multiple times is
        undefined. Calling :meth:`Surface.finish` on the resulting image surface
        results in undefined behavior. Changing the device transform of the
        image surface or of surface before the image surface is unmapped results
        in undefined behavior.

        The caller must use :meth:`Surface.unmap_image` to destroy this image
        surface.

        .. versionadded:: 1.15.0
        """

    def mark_dirty(self) -> None:
        """
        Tells cairo that drawing has been done to *Surface* using means other
        than cairo, and that cairo should reread any cached areas. Note that you
        must call :meth:`.flush` before doing such drawing.
        """

    def mark_dirty_rectangle(self, x: int, y: int, width: int, height: int) -> None:
        """
        :param x: X coordinate of dirty rectangle
        :param y: Y coordinate of dirty rectangle
        :param width: width of dirty rectangle
        :param height: height of dirty rectangle

        Like :meth:`.mark_dirty`, but drawing has been done only to the
        specified rectangle, so that cairo can retain cached contents for other
        parts of the surface.

        Any cached clip set on the *Surface* will be reset by this function, to
        make sure that future cairo calls have the clip set that they expect.
        """

    def set_device_offset(self, x_offset: float, y_offset: float) -> None:
        """
        :param x_offset: the offset in the X direction, in device units
        :param y_offset: the offset in the Y direction, in device units

        Sets an offset that is added to the device coordinates determined by the
        CTM when drawing to *Surface*. One use case for this function is when we
        want to create a *Surface* that redirects drawing for a portion of an
        onscreen surface to an offscreen surface in a way that is completely
        invisible to the user of the cairo API. Setting a transformation via
        :meth:`Context.translate` isn't sufficient to do this, since functions
        like :meth:`Context.device_to_user` will expose the hidden offset.

        Note that the offset affects drawing to the surface as well as using the
        surface in a source pattern.
        """

    def set_device_scale(self, x_scale: float, y_scale: float) -> None:
        """
        :param x_scale: a scale factor in the X direction
        :param y_scale: a scale factor in the Y direction

        Sets a scale that is multiplied to the device coordinates determined by
        the CTM when drawing to surface . One common use for this is to render
        to very high resolution display devices at a scale factor, so that code
        that assumes 1 pixel will be a certain size will still work. Setting a
        transformation via :meth:`Context.translate` isn't sufficient to do
        this, since functions like :meth:`Context.device_to_user` will expose
        the hidden scale.

        .. versionadded:: 1.14.0
        """

    def set_fallback_resolution(self, x_pixels_per_inch: float, y_pixels_per_inch: float) -> None:
        """
        :param x_pixels_per_inch: horizontal setting for pixels per inch
        :param y_pixels_per_inch: vertical setting for pixels per inch

        Set the horizontal and vertical resolution for image fallbacks.

        When certain operations aren't supported natively by a backend, cairo
        will fallback by rendering operations to an image and then overlaying
        that image onto the output. For backends that are natively
        vector-oriented, this function can be used to set the resolution used
        for these image fallbacks, (larger values will result in more detailed
        images, but also larger file sizes).

        Some examples of natively vector-oriented backends are the ps, pdf, and
        svg backends.

        For backends that are natively raster-oriented, image fallbacks are
        still possible, but they are always performed at the native device
        resolution. So this function has no effect on those backends.

        Note: The fallback resolution only takes effect at the time of
        completing a page (with :meth:`Context.show_page` or
        :meth:`Context.copy_page`) so there is currently no way to have more
        than one fallback resolution in effect on a single page.

        The default fallback resoultion is 300 pixels per inch in both
        dimensions.

        .. versionadded:: 1.2
        """

    def set_mime_data(self, mime_type: str, data: bytes) -> None:
        """
        :param mime_type: the MIME type of the image data
            (:ref:`constants_MIME_TYPE`)
        :param data: the image data to attach to the surface

        Attach an image in the format ``mime_type`` to *Surface*.
        To remove the data from a surface,
        call this function with same mime type and :obj:`None` for data.

        The attached image (or filename) data can later be used
        by backends which support it
        (currently: PDF, PS, SVG and Win32 Printing surfaces)
        to emit this data instead of making a snapshot of the surface.
        This approach tends to be faster and requires less memory and disk space.

        The recognized MIME types are listed under :ref:`constants_MIME_TYPE`.

        See corresponding backend surface docs for details
        about which MIME types it can handle.
        Caution: the associated MIME data will be discarded
        if you draw on the surface afterwards.
        Use this function with care.

        .. versionadded:: 1.12.0
        """

    def show_page(self) -> None:
        """
        Emits and clears the current page for backends that support multiple
        pages. Use :meth:`.copy_page` if you don't want to clear the page.

        There is a convenience function for this that takes a
        :meth:`Context.show_page`.

        .. versionadded:: 1.6
        """

    def supports_mime_type(self, mime_type: str) -> bool:
        """
        :param mime_type: the mime type (:ref:`constants_MIME_TYPE`)
        :returns: :obj:`True` if surface supports mime_type, :obj:`False`
            otherwise

        Return whether surface supports ``mime_type``.

        .. versionadded:: 1.12.0
        """

    def write_to_png(self, fobj: Union[_FileLike, _PathLike]) -> None:
        """
        :param fobj: a filename or writable file object
        :raises: :exc:`MemoryError` if memory could not be allocated for the operation

                :exc:`IOError` if an I/O error occurs while attempting to write
                the file

        Writes the contents of *Surface* to *fobj* as a PNG image. *fobj* can either be
        a filename or a file object opened in binary mode.
        """

    def unmap_image(self, image: "ImageSurface") -> None:
        """
        :param image: the currently mapped image

        Unmaps the image surface as returned from :meth:`Surface.map_to_image`.

        The content of the image will be uploaded to the target surface.
        Afterwards, the image is destroyed.

        Using an image surface which wasn't returned by
        :meth:`Surface.map_to_image` results in undefined behavior.

        .. versionadded:: 1.15.0
        """

    def __enter__(self: _SomeSurface) -> _SomeSurface: ...
    __exit__: Any = ...

class ImageSurface(Surface):
    """
    A *cairo.ImageSurface* provides the ability to render to memory buffers
    either allocated by cairo or by the calling code. The supported image
    formats are those defined in :class:`cairo.Format`.
    """

    def __init__(self, format: Format, width: int, height: int) -> None:
        """
        :param format: format of pixels in the surface to create
        :param width: width of the surface, in pixels
        :param height: height of the surface, in pixels
        :returns: a new *ImageSurface*

        Creates an *ImageSurface* of the specified format and dimensions. Initially
        the surface contents are all 0. (Specifically, within each pixel, each
        color or alpha channel belonging to format will be 0. The contents of bits
        within a pixel, but not belonging to the given format are undefined).
        """

    @classmethod
    def create_for_data(cls, data: memoryview, format: Format, width: int, height: int, stride: int = ...) -> "ImageSurface":
        """
        :param data: a writable Python buffer/memoryview object
        :param format: the format of pixels in the
            buffer
        :param width: the width of the image to be stored in the buffer
        :param height: the height of the image to be stored in the buffer
        :param stride: the number of bytes between the start of rows in the
            buffer as allocated. If not given the value from
            :meth:`cairo.Format.stride_for_width` is used.
        :returns: a new *ImageSurface*
        :raises: :exc:`MemoryError` in case of no memory.

                :exc:`cairo.Error` in case of invalid *stride* value.

        Creates an *ImageSurface* for the provided pixel data. The initial
        contents of buffer will be used as the initial image contents; you must
        explicitly clear the buffer, using, for example, cairo_rectangle() and
        cairo_fill() if you want it cleared.

        Note that the *stride* may be larger than width*bytes_per_pixel to
        provide proper alignment for each pixel and row. This alignment is
        required to allow high-performance rendering within cairo. The correct
        way to obtain a legal stride value is to call
        :meth:`cairo.Format.stride_for_width` with the desired format and
        maximum image width value, and use the resulting stride value to
        allocate the data and to create the :class:`ImageSurface`. See
        :meth:`cairo.Format.stride_for_width` for example code.
        """

    @classmethod
    def create_from_png(cls, fobj: Union[_PathLike, _FileLike]) -> "ImageSurface":
        """
        :param fobj:
            a :obj:`_PathLike`, file, or file-like object of the PNG to load.
        :returns: a new *ImageSurface* initialized the contents to the given PNG
            file.

        Creates a new image surface and initializes the contents to the given
        PNG file. *fobj* can either be a filename or a file object opened in
        binary mode.
        """

    format_stride_for_width = Format.stride_for_width
    """
    See :meth:`cairo.Format.stride_for_width`.

    .. versionadded:: 1.6
    """

    def get_data(self) -> memoryview:
        """
        :returns: a Python buffer object for the data of the *ImageSurface*, for
            direct inspection or modification. On Python 3 a memoryview object is
            returned.

        .. versionadded:: 1.2
        """

    def get_format(self) -> Format:
        """
        :returns: the format of the *ImageSurface*.
        :rtype: cairo.Format

        .. versionadded:: 1.2
        """

    def get_height(self) -> int:
        """
        :returns: the height of the *ImageSurface* in pixels.
        """

    def get_stride(self) -> int:
        """
        :returns: the stride of the *ImageSurface* in bytes. The stride is the
            distance in bytes from the beginning of one row of the image data to
            the beginning of the next row.
        """

    def get_width(self) -> int:
        """
        :returns: the width of the *ImageSurface* in pixels.
        """

class SurfacePattern(Pattern):

    def __init__(self, surface: Surface) -> None:
        """
        :param surface: a cairo :class:`Surface`
        """

    def get_surface(self) -> Surface:
        """
        :returns: the :class:`Surface` of the *SurfacePattern*.

        .. versionadded:: 1.4
        """

class Context(Generic[_SomeSurface]):
    """
    *Context* is the main object used when drawing with cairo. To draw with cairo,
    you create a *Context*, set the target surface, and drawing options for the
    *Context*, create shapes with functions like :meth:`Context.move_to` and
    :meth:`Context.line_to`, and then draw shapes with :meth:`Context.stroke` or
    :meth:`Context.fill`.

    *Contexts* can be pushed to a stack via :meth:`Context.save`. They may then
    safely be changed, without losing the current state. Use
    :meth:`Context.restore` to restore to the saved state.
    """

    def __init__(self, target: _SomeSurface) -> None:
        """
        :param target: target :class:`Surface` for the context
        :raises: :exc:`MemoryError` in case of no memory

        Creates a new *Context* with all graphics state parameters set to default
        values and with *target* as a target surface. The target surface should be
        constructed with a backend-specific function such as :class:`ImageSurface`
        (or any other cairo backend surface create variant).
        """

    def append_path(self, path: Path) -> None:
        """
        :param path: :class:`Path` to be appended

        Append the *path* onto the current path. The *path* may be either the
        return value from one of :meth:`Context.copy_path` or
        :meth:`Context.copy_path_flat` or it may be constructed manually (in C).
        """

    def arc(self, xc: float, yc: float, radius: float, angle1: float, angle2: float) -> None:
        """
        :param xc: X position of the center of the arc
        :param yc: Y position of the center of the arc
        :param radius: the radius of the arc
        :param angle1: the start angle, in radians
        :param angle2: the end angle, in radians

        Adds a circular arc of the given *radius* to the current path.  The arc
        is centered at (*xc, yc*), begins at *angle1* and proceeds in the
        direction of increasing angles to end at *angle2*. If *angle2* is less
        than *angle1* it will be progressively increased by 2*PI until it is
        greater than *angle1*.

        If there is a current point, an initial line segment will be added to
        the path to connect the current point to the beginning of the arc. If
        this initial line is undesired, it can be avoided by calling
        :meth:`Context.new_sub_path` before calling :meth:`Context.arc`.

        Angles are measured in radians. An angle of 0.0 is in the direction of
        the positive X axis (in user space). An angle of PI/2.0 radians (90
        degrees) is in the direction of the positive Y axis (in user
        space). Angles increase in the direction from the positive X axis toward
        the positive Y axis. So with the default transformation matrix, angles
        increase in a clockwise direction.

        To convert from degrees to radians, use ``degrees * (math.pi / 180)``.

        This function gives the arc in the direction of increasing angles; see
        :meth:`Context.arc_negative` to get the arc in the direction of
        decreasing angles.

        The arc is circular in user space. To achieve an elliptical arc,
        you can scale the current transformation matrix by different
        amounts in the X and Y directions. For example, to draw an ellipse
        in the box given by *x, y, width, height*::

            ctx.save()
            ctx.translate(x + width / 2., y + height / 2.)
            ctx.scale(width / 2., height / 2.)
            ctx.arc(0., 0., 1., 0., 2 * math.pi)
            ctx.restore()
        """

    def arc_negative(self, xc: float, yc: float, radius: float, angle1: float, angle2: float) -> None:
        """
        :param xc: X position of the center of the arc
        :param yc: Y position of the center of the arc
        :param radius: the radius of the arc
        :param angle1: the start angle, in radians
        :param angle2: the end angle, in radians

        Adds a circular arc of the given *radius* to the current path. The arc
        is centered at (*xc, yc*), begins at *angle1* and proceeds in the
        direction of decreasing angles to end at *angle2*. If *angle2* is
        greater than *angle1* it will be progressively decreased by 2*PI until
        it is less than *angle1*.

        See :meth:`Context.arc` for more details. This function differs only in
        the direction of the arc between the two angles.
        """

    def clip(self) -> None:
        """
        Establishes a new clip region by intersecting the current clip region
        with the current path as it would be filled by :meth:`Context.fill` and
        according to the current :class:`fill rule <cairo.FillRule>` (see
        :meth:`Context.set_fill_rule`).

        After :meth:`.clip`, the current path will be cleared from the
        :class:`Context`.

        The current clip region affects all drawing operations by effectively
        masking out any changes to the surface that are outside the current clip
        region.

        Calling :meth:`.clip` can only make the clip region smaller, never
        larger. But the current clip is part of the graphics state, so a
        temporary restriction of the clip region can be achieved by calling
        :meth:`.clip` within a :meth:`Context.save`/:meth:`Context.restore`
        pair. The only other means of increasing the size of the clip region is
        :meth:`Context.reset_clip`.
        """

    def clip_extents(self) -> Tuple[float, float, float, float]:
        """
        :returns: (x1, y1, x2, y2), all float

        * *x1*: left of the resulting extents
        * *y1*: top of the resulting extents
        * *x2*: right of the resulting extents
        * *y2*: bottom of the resulting extents

        Computes a bounding box in user coordinates covering the area inside the
        current clip.

        .. versionadded:: 1.4
        """

    def clip_preserve(self) -> None:
        """
        Establishes a new clip region by intersecting the current clip region
        with the current path as it would be filled by :meth:`Context.fill` and
        according to the current :class:`fill rule <cairo.FillRule>` (see
        :meth:`Context.set_fill_rule`).

        Unlike :meth:`Context.clip`, :meth:`.clip_preserve` preserves the path
        within the :class:`Context`.

        The current clip region affects all drawing operations by effectively
        masking out any changes to the surface that are outside the current clip
        region.

        Calling :meth:`.clip_preserve` can only make the clip region smaller,
        never larger. But the current clip is part of the graphics state, so a
        temporary restriction of the clip region can be achieved by calling
        :meth:`.clip_preserve` within a
        :meth:`Context.save`/:meth:`Context.restore` pair. The only other means
        of increasing the size of the clip region is :meth:`Context.reset_clip`.
        """

    def close_path(self) -> None:
        """
        Adds a line segment to the path from the current point to the beginning
        of the current sub-path, (the most recent point passed to
        :meth:`Context.move_to`), and closes this sub-path. After this call the
        current point will be at the joined endpoint of the sub-path.

        The behavior of :meth:`.close_path` is distinct from simply calling
        :meth:`Context.line_to` with the equivalent coordinate in the case of
        stroking. When a closed sub-path is stroked, there are no caps on the
        ends of the sub-path. Instead, there is a line join connecting the final
        and initial segments of the sub-path.

        If there is no current point before the call to :meth:`.close_path`,
        this function will have no effect.

        Note: As of cairo version 1.2.4 any call to :meth:`.close_path` will
        place an explicit MOVE_TO element into the path immediately after the
        CLOSE_PATH element, (which can be seen in :meth:`Context.copy_path` for
        example). This can simplify path processing in some cases as it may not
        be necessary to save the "last move_to point" during processing as the
        MOVE_TO immediately after the CLOSE_PATH will provide that point.
        """

    def copy_clip_rectangle_list(self) -> List[Rectangle]:
        """
        :returns: the current clip region as a list of rectangles in user
            coordinates. Returns a list of :class:`Rectangle`

        .. versionadded:: 1.4
        """

    def copy_page(self) -> None:
        """
        Emits the current page for backends that support multiple pages, but
        doesn't clear it, so, the contents of the current page will be retained
        for the next page too.  Use :meth:`Context.show_page` if you want to get
        an empty page after the emission.

        This is a convenience function that simply calls
        :meth:`Surface.copy_page` on *Context's* target.
        """

    def copy_path(self) -> Path:
        """
        :returns: :class:`Path`
        :raises: :exc:`MemoryError` in case of no memory

        Creates a copy of the current path and returns it to the user as a
        :class:`Path`.
        """

    def copy_path_flat(self) -> Path:
        """
        :returns: :class:`Path`
        :raises: :exc:`MemoryError` in case of no memory

        Gets a flattened copy of the current path and returns it to the
        user as a :class:`Path`.

        This function is like :meth:`Context.copy_path` except that any curves
        in the path will be approximated with piecewise-linear approximations,
        (accurate to within the current tolerance value). That is, the result is
        guaranteed to not have any elements of type CAIRO_PATH_CURVE_TO which
        will instead be replaced by a series of CAIRO_PATH_LINE_TO elements.
        """

    def curve_to(self, x1: float, y1: float, x2: float, y2: float, x3: float, y3: float) -> None:
        """
        :param x1: the X coordinate of the first control point
        :param y1: the Y coordinate of the first control point
        :param x2: the X coordinate of the second control point
        :param y2: the Y coordinate of the second control point
        :param x3: the X coordinate of the end of the curve
        :param y3: the Y coordinate of the end of the curve

        Adds a cubic Bézier spline to the path from the current point to
        position *(x3, y3)* in user-space coordinates, using *(x1, y1)* and
        *(x2, y2)* as the control points. After this call the current point will
        be *(x3, y3)*.

        If there is no current point before the call to :meth:`.curve_to`
        this function will behave as if preceded by a call to
        ``ctx.move_to(x1, y1)``.
        """

    def device_to_user(self, x: float, y: float) -> Tuple[float, float]:
        """
        :param x: X value of coordinate
        :param y: Y value of coordinate
        :returns: (x, y), both float

        Transform a coordinate from device space to user space by multiplying
        the given point by the inverse of the current transformation matrix
        (CTM).
        """

    def device_to_user_distance(self, dx: float, dy: float) -> Tuple[float, float]:
        """
        :param dx: X component of a distance vector
        :param dy: Y component of a distance vector
        :returns: (dx, dy), both float

        Transform a distance vector from device space to user space. This
        function is similar to :meth:`Context.device_to_user` except that the
        translation components of the inverse CTM will be ignored when
        transforming *(dx,dy)*.
        """

    def fill(self) -> None:
        """
        A drawing operator that fills the current path according to the current
        :class:`fill rule <cairo.FillRule>`, (each sub-path is implicitly
        closed before being filled). After :meth:`.fill`, the current path will
        be cleared from the :class:`Context`. See :meth:`Context.set_fill_rule`
        and :meth:`Context.fill_preserve`.
        """

    def fill_extents(self) -> Tuple[float, float, float, float]:
        """
        :returns: (x1, y1, x2, y2), all float

        * *x1*: left of the resulting extents
        * *y1*: top of the resulting extents
        * *x2*: right of the resulting extents
        * *y2*: bottom of the resulting extents

        Computes a bounding box in user coordinates covering the area that would
        be affected, (the "inked" area), by a :meth:`Context.fill` operation
        given the current path and fill parameters. If the current path is
        empty, returns an empty rectangle (0,0,0,0). Surface dimensions and
        clipping are not taken into account.

        Contrast with :meth:`Context.path_extents`, which is similar, but returns
        non-zero extents for some paths with no inked area, (such as a
        simple line segment).

        Note that :meth:`.fill_extents` must necessarily do more work to compute
        the precise inked areas in light of the fill rule, so
        :meth:`Context.path_extents` may be more desirable for sake of
        performance if the non-inked path extents are desired.

        See :meth:`Context.fill`, :meth:`Context.set_fill_rule` and
        :meth:`Context.fill_preserve`.
        """

    def fill_preserve(self) -> None:
        """
        A drawing operator that fills the current path according to the current
        :class:`fill rule <cairo.FillRule>`, (each sub-path is implicitly
        closed before being filled). Unlike :meth:`Context.fill`,
        :meth:`.fill_preserve` preserves the path within the :class:`Context`.

        See :meth:`Context.set_fill_rule` and :meth:`Context.fill`.
        """

    def font_extents(self) -> Tuple[float, float, float, float, float]:
        """
        :returns: (ascent, descent, height, max_x_advance, max_y_advance),
            all float

        Gets the font extents for the currently selected font.
        """

    def get_antialias(self) -> Antialias:
        """
        :returns: the current antialias mode,
            as set by :meth:`Context.set_antialias`.
        """

    def get_current_point(self) -> Tuple[float, float]:
        """
        :returns: (x, y), both float

        * *x*: X coordinate of the current point
        * *y*: Y coordinate of the current point

        Gets the current point of the current path, which is conceptually the
        final point reached by the path so far.

        The current point is returned in the user-space coordinate system. If
        there is no defined current point or if :class:`Context` is in an error
        status, *x* and *y* will both be set to 0.0. It is possible to check this
        in advance with :meth:`Context.has_current_point`.

        Most path construction functions alter the current point. See the
        following for details on how they affect the current point:
        :meth:`Context.new_path`, :meth:`Context.new_sub_path`,
        :meth:`Context.append_path`, :meth:`Context.close_path`,
        :meth:`Context.move_to`, :meth:`Context.line_to`,
        :meth:`Context.curve_to`, :meth:`Context.rel_move_to`,
        :meth:`Context.rel_line_to`, :meth:`Context.rel_curve_to`,
        :meth:`Context.arc`, :meth:`Context.arc_negative`,
        :meth:`Context.rectangle`, :meth:`Context.text_path`,
        :meth:`Context.glyph_path`.

        Some functions use and alter the current point but do not otherwise
        change current path:
        :meth:`Context.show_text`.

        Some functions unset the current path and as a result, current point:
        :meth:`Context.fill`, :meth:`Context.stroke`.
        """

    def get_dash(self) -> Tuple[List[float], float]:
        """
        :returns: (dashes, offset)

        * *dashes*: return value as a tuple for the dash array
        * *offset*: return value as float for the current dash offset

        Gets the current dash array.

        .. versionadded:: 1.4
        """

    def get_dash_count(self) -> int:
        """
        :returns: the length of the dash array, or 0 if no dash array set.

        See also :meth:`Context.set_dash` and :meth:`Context.get_dash`.

        .. versionadded:: 1.4
        """

    def get_fill_rule(self) -> FillRule:
        """
        :returns: the current fill rule, as
            set by :meth:`Context.set_fill_rule`.
        """

    def get_font_face(self) -> FontFace:
        """
        :returns: the current :class:`FontFace` for the :class:`Context`.
        """

    def get_font_matrix(self) -> Matrix:
        """
        :returns: the current :class:`Matrix` for the :class:`Context`.

        See :meth:`Context.set_font_matrix`.
        """

    def get_font_options(self) -> FontOptions:
        """
        :returns: the current :class:`FontOptions` for the :class:`Context`.

        Retrieves font rendering options set via
        :meth:`Context.set_font_options`. Note that the returned options do not
        include any options derived from the underlying surface; they are
        literally the options passed to :meth:`Context.set_font_options`.
        """

    def get_group_target(self) -> Surface:
        """
        :returns: the target :class:`Surface`.

        Gets the current destination :class:`Surface` for the
        :class:`Context`. This is either the original target surface as passed
        to :class:`Context` or the target surface for the current group as
        started by the most recent call to :meth:`Context.push_group` or
        :meth:`Context.push_group_with_content`.

        .. versionadded:: 1.2
        """

    def get_hairline(self) -> bool:
        """
        :returns: whether hairline mode is set.

        Returns whether or not hairline mode is set, as set by
        :meth:`Context.set_hairline`.

        .. versionadded:: 1.23 Only available with cairo 1.17.6+
        """

    def get_line_cap(self) -> LineCap:
        """
        :returns: the current line cap style, as
            set by :meth:`Context.set_line_cap`.
        """

    def get_line_join(self) -> LineJoin:
        """
        :returns: the current line join style, as
            set by :meth:`Context.set_line_join`.
        """

    def get_line_width(self) -> float:
        """
        :returns: the current line width

        This function returns the current line width value exactly as set by
        :meth:`Context.set_line_width`. Note that the value is unchanged even if
        the CTM has changed between the calls to :meth:`Context.set_line_width`
        and :meth:`.get_line_width`.
        """

    def get_matrix(self) -> Matrix:
        """
        :returns: the current transformation :class:`Matrix` (CTM)
        """

    def get_miter_limit(self) -> float:
        """
        :returns: the current miter limit, as set by
            :meth:`Context.set_miter_limit`.
        """

    def get_operator(self) -> Operator:
        """
        :returns: the current compositing operator
            for a :class:`Context`.
        """

    def get_scaled_font(self) -> ScaledFont:
        """
        :returns: the current :class:`ScaledFont` for a :class:`Context`.

        .. versionadded:: 1.4
        """

    def get_source(self) -> Pattern:
        """
        :returns: the current source :class:`Pattern` for  a :class:`Context`.
        """

    def get_target(self) -> _SomeSurface:
        """
        :returns: the target :class:`Surface` for the :class:`Context`
        """

    def get_tolerance(self) -> float:
        """
        :returns: the current tolerance value, as set by
            :meth:`Context.set_tolerance`
        """

    def glyph_extents(self, glyphs: Sequence[Glyph]) -> TextExtents:
        """
        :param glyphs: glyphs, a sequence of :class:`Glyph`

        Gets the extents for an array of glyphs. The extents describe a
        user-space rectangle that encloses the "inked" portion of the glyphs,
        (as they would be drawn by :meth:`Context.show_glyphs`). Additionally,
        the x_advance and y_advance values indicate the amount by which the
        current point would be advanced by :meth:`Context.show_glyphs`.

        Note that whitespace glyphs do not contribute to the size of the
        rectangle (extents.width and extents.height).
        """

    def glyph_path(self, glyphs: Sequence[Glyph]) -> None:
        """
        :param glyphs: glyphs to show, a sequence of :class:`Glyph`

        Adds closed paths for the glyphs to the current path. The generated path
        if filled, achieves an effect similar to that of
        :meth:`Context.show_glyphs`.
        """

    def has_current_point(self) -> bool:
        """
        :returns: True iff a current point is defined on the current path.
            See :meth:`Context.get_current_point` for details on the current point.

        .. versionadded:: 1.6
        """

    def identity_matrix(self) -> None:
        """
        Resets the current transformation :class:`Matrix` (CTM) by setting it
        equal to the identity matrix. That is, the user-space and device-space
        axes will be aligned and one user-space unit will transform to one
        device-space unit.
        """

    def in_clip(self, x: float, y: float) -> bool:
        """
        :param x: X coordinate of the point to test
        :param y: Y coordinate of the point to test
        :returns: :obj:`True` if the point is inside, or :obj:`False` if outside.

        Tests whether the given point is inside the area that would be visible
        through the current clip, i.e. the area that would be filled by a
        :meth:`paint` operation.

        See :meth:`clip`, and :meth:`clip_preserve`.

        .. versionadded:: 1.12.0
        """

    def in_fill(self, x: float, y: float) -> bool:
        """
        :param x: X coordinate of the point to test
        :param y: Y coordinate of the point to test
        :returns: True iff the point is inside the area that would be affected
            by a :meth:`Context.fill` operation given the current path and filling
            parameters. Surface dimensions and clipping are not taken into account.

        See :meth:`Context.fill`, :meth:`Context.set_fill_rule` and
        :meth:`Context.fill_preserve`.
        """

    def in_stroke(self, x: float, y: float) -> bool:
        """
        :param x: X coordinate of the point to test
        :param y: Y coordinate of the point to test

        :returns: True iff the point is inside the area that would be affected
            by a :meth:`Context.stroke` operation given the current path and
            stroking parameters. Surface dimensions and clipping are not taken
            into account.

        See :meth:`Context.stroke`, :meth:`Context.set_line_width`,
        :meth:`Context.set_line_join`, :meth:`Context.set_line_cap`,
        :meth:`Context.set_dash`, and :meth:`Context.stroke_preserve`.
        """

    def line_to(self, x: float, y: float) -> None:
        """
        :param x: the X coordinate of the end of the new line
        :param y: the Y coordinate of the end of the new line

        Adds a line to the path from the current point to position *(x, y)* in
        user-space coordinates. After this call the current point will be *(x,
        y)*.

        If there is no current point before the call to :meth:`.line_to`
        this function will behave as ``ctx.move_to(x, y)``.
        """

    def mask(self, pattern: Pattern) -> None:
        """
        :param pattern: a :class:`Pattern`

        A drawing operator that paints the current source using the alpha
        channel of *pattern* as a mask. (Opaque areas of *pattern* are painted
        with the source, transparent areas are not painted.)
        """

    def mask_surface(self, surface: Surface, x: float = 0.0, y: float = 0.0) -> None:
        """
        :param surface: a :class:`Surface`
        :param x: X coordinate at which to place the origin of *surface*
        :param y: Y coordinate at which to place the origin of *surface*

        A drawing operator that paints the current source using the alpha
        channel of *surface* as a mask. (Opaque areas of *surface* are painted
        with the source, transparent areas are not painted.)
        """

    def move_to(self, x: float, y: float) -> None:
        """
        :param x: the X coordinate of the new position
        :param y: the Y coordinate of the new position

        Begin a new sub-path. After this call the current point will be *(x,
        y)*.
        """

    def new_path(self) -> None:
        """
        Clears the current path. After this call there will be no path and no
        current point.
        """

    def new_sub_path(self) -> None:
        """
        Begin a new sub-path. Note that the existing path is not affected. After
        this call there will be no current point.

        In many cases, this call is not needed since new sub-paths are
        frequently started with :meth:`Context.move_to`.

        A call to :meth:`.new_sub_path` is particularly useful when beginning a
        new sub-path with one of the :meth:`Context.arc` calls. This makes
        things easier as it is no longer necessary to manually compute the arc's
        initial coordinates for a call to :meth:`Context.move_to`.

        .. versionadded:: 1.6
        """

    def paint(self) -> None:
        """
        A drawing operator that paints the current source everywhere within the
        current clip region.
        """

    def paint_with_alpha(self, alpha: float) -> None:
        """
        :param alpha: alpha value, between 0 (transparent) and 1 (opaque)

        A drawing operator that paints the current source everywhere within the
        current clip region using a mask of constant alpha value *alpha*. The
        effect is similar to :meth:`Context.paint`, but the drawing is faded out
        using the alpha value.
        """

    def path_extents(self) -> Tuple[float, float, float, float]:
        """
        :returns: (x1, y1, x2, y2), all float

        * *x1*: left of the resulting extents
        * *y1*: top of the resulting extents
        * *x2*: right of the resulting extents
        * *y2*: bottom of the resulting extents

        Computes a bounding box in user-space coordinates covering the points on
        the current path. If the current path is empty, returns an empty
        rectangle (0, 0, 0, 0). Stroke parameters, fill rule, surface
        dimensions and clipping are not taken into account.

        Contrast with :meth:`Context.fill_extents` and
        :meth:`Context.stroke_extents` which return the extents of only the area
        that would be "inked" by the corresponding drawing operations.

        The result of :meth:`.path_extents` is defined as equivalent to the
        limit of :meth:`Context.stroke_extents` with cairo.LINE_CAP_ROUND as the
        line width approaches 0.0, (but never reaching the empty-rectangle
        returned by :meth:`Context.stroke_extents` for a line width of 0.0).

        Specifically, this means that zero-area sub-paths such as
        :meth:`Context.move_to`; :meth:`Context.line_to` segments, (even
        degenerate cases where the coordinates to both calls are identical),
        will be considered as contributing to the extents. However, a lone
        :meth:`Context.move_to` will not contribute to the results of
        :meth:`Context.path_extents`.

        .. versionadded:: 1.6
        """

    def pop_group(self) -> SurfacePattern:
        """
        :returns: a newly created :class:`SurfacePattern` containing the results
            of all drawing operations performed to the group.

        Terminates the redirection begun by a call to :meth:`Context.push_group`
        or :meth:`Context.push_group_with_content` and returns a new pattern
        containing the results of all drawing operations performed to the group.

        The :meth:`.pop_group` function calls :meth:`Context.restore`,
        (balancing a call to :meth:`Context.save` by the
        :meth:`Context.push_group` function), so that any changes to the graphics
        state will not be visible outside the group.

        .. versionadded:: 1.2
        """

    def pop_group_to_source(self) -> None:
        """
        Terminates the redirection begun by a call to :meth:`Context.push_group`
        or :meth:`Context.push_group_with_content` and installs the resulting
        pattern as the source :class:`Pattern` in the given :class:`Context`.

        The behavior of this function is equivalent to the sequence of
        operations::

            group = cairo_pop_group()
            ctx.set_source(group)

        but is more convenient as their is no need for a variable to store
        the short-lived pointer to the pattern.

        The :meth:`Context.pop_group` function calls :meth:`Context.restore`,
        (balancing a call to :meth:`Context.save` by the
        :meth:`Context.push_group` function), so that any changes to the graphics
        state will not be visible outside the group.

        .. versionadded:: 1.2
        """

    def push_group(self) -> None:
        """
        Temporarily redirects drawing to an intermediate surface known as a
        group. The redirection lasts until the group is completed by a call to
        :meth:`Context.pop_group` or :meth:`Context.pop_group_to_source`. These
        calls provide the result of any drawing to the group as a pattern,
        (either as an explicit object, or set as the source pattern).

        This group functionality can be convenient for performing intermediate
        compositing. One common use of a group is to render objects as opaque
        within the group, (so that they occlude each other), and then blend the
        result with translucence onto the destination.

        Groups can be nested arbitrarily deep by making balanced calls to
        :meth:`Context.push_group`/:meth:`Context.pop_group`. Each call
        pushes/pops the new target group onto/from a stack.

        The :meth:`.push_group` function calls :meth:`Context.save` so that any
        changes to the graphics state will not be visible outside the group,
        (the pop_group functions call :meth:`Context.restore`).

        By default the intermediate group will have a :class:`cairo.Content`
        type of :attr:`cairo.Content.COLOR_ALPHA`. Other content types can be
        chosen for the group by using :meth:`Context.push_group_with_content`
        instead.

        As an example, here is how one might fill and stroke a path with
        translucence, but without any portion of the fill being visible
        under the stroke::

            ctx.push_group()
            ctx.set_source(fill_pattern)
            ctx.fill_preserve()
            ctx.set_source(stroke_pattern)
            ctx.stroke()
            ctx.pop_group_to_source()
            ctx.paint_with_alpha(alpha)

        .. versionadded:: 1.2
        """

    def push_group_with_content(self, content: Content) -> None:
        """
        :param cairo.Content content: a content indicating the
            type of group that will be created

        Temporarily redirects drawing to an intermediate surface known as a
        group. The redirection lasts until the group is completed by a call to
        :meth:`Context.pop_group` or :meth:`Context.pop_group_to_source`. These
        calls provide the result of any drawing to the group as a pattern,
        (either as an explicit object, or set as the source pattern).

        The group will have a content type of *content*. The ability to control
        this content type is the only distinction between this function and
        :meth:`Context.push_group` which you should see for a more detailed
        description of group rendering.

        .. versionadded:: 1.2
        """

    def rectangle(self, x: float, y: float, width: float, height: float) -> None:
        """
        :param x: the X coordinate of the top left corner of the rectangle
        :param y: the Y coordinate to the top left corner of the rectangle
        :param width: the width of the rectangle
        :param height: the height of the rectangle

        Adds a closed sub-path rectangle of the given size to the current path
        at position *(x, y)* in user-space coordinates.

        This function is logically equivalent to::

            ctx.move_to(x, y)
            ctx.rel_line_to(width, 0)
            ctx.rel_line_to(0, height)
            ctx.rel_line_to(-width, 0)
            ctx.close_path()
        """

    def rel_curve_to(self, dx1: float, dy1: float, dx2: float, dy2: float, dx3: float, dy3: float) -> None:
        """
        :param dx1: the X offset to the first control point
        :param dy1: the Y offset to the first control point
        :param dx2: the X offset to the second control point
        :param dy2: the Y offset to the second control point
        :param dx3: the X offset to the end of the curve
        :param dy3: the Y offset to the end of the curve
        :raises: :exc:`cairo.Error` if called with no current point.

        Relative-coordinate version of :meth:`Context.curve_to`. All
        offsets are relative to the current point. Adds a cubic Bézier spline to
        the path from the current point to a point offset from the current point
        by *(dx3, dy3)*, using points offset by *(dx1, dy1)* and *(dx2, dy2)* as
        the control points. After this call the current point will be offset by
        *(dx3, dy3)*.

        Given a current point of (x, y), ``ctx.rel_curve_to(dx1, dy1, dx2, dy2,
        dx3, dy3)`` is logically equivalent to ``ctx.curve_to(x+dx1, y+dy1,
        x+dx2, y+dy2, x+dx3, y+dy3)``.
        """

    def rel_line_to(self, dx: float, dy: float) -> None:
        """
        :param dx: the X offset to the end of the new line
        :param dy: the Y offset to the end of the new line
        :raises: :exc:`cairo.Error` if called with no current point.

        Relative-coordinate version of :meth:`Context.line_to`. Adds a line to
        the path from the current point to a point that is offset from the
        current point by *(dx, dy)* in user space. After this call the current
        point will be offset by *(dx, dy)*.

        Given a current point of (x, y), ``ctx.rel_line_to(dx, dy)`` is logically
        equivalent to ``ctx.line_to(x + dx, y + dy)``.
        """

    def rel_move_to(self, dx: float, dy: float) -> None:
        """
        :param dx: the X offset
        :param dy: the Y offset
        :raises: :exc:`cairo.Error` if called with no current point.

        Begin a new sub-path. After this call the current point will offset by
        *(dx, dy)*.

        Given a current point of (x, y), ``ctx.rel_move_to(dx, dy)`` is logically
        equivalent to ``ctx.(x + dx, y + dy)``.
        """

    def reset_clip(self) -> None:
        """
        Reset the current clip region to its original, unrestricted state. That
        is, set the clip region to an infinitely large shape containing the
        target surface. Equivalently, if infinity is too hard to grasp, one can
        imagine the clip region being reset to the exact bounds of the target
        surface.

        Note that code meant to be reusable should not call :meth:`.reset_clip`
        as it will cause results unexpected by higher-level code which calls
        :meth:`.clip`. Consider using :meth:`.save` and :meth:`.restore` around
        :meth:`.clip` as a more robust means of temporarily restricting the clip
        region.
        """

    def restore(self) -> None:
        """
        Restores :class:`Context` to the state saved by a preceding call to
        :meth:`.save` and removes that state from the stack of saved states.
        """

    def rotate(self, angle: float) -> None:
        """
        :param angle: angle (in radians) by which the user-space axes will be
            rotated

        Modifies the current transformation matrix (CTM) by rotating the
        user-space axes by *angle* radians. The rotation of the axes takes places
        after any existing transformation of user space. The rotation direction
        for positive angles is from the positive X axis toward the positive Y
        axis.
        """

    def save(self) -> None:
        """
        Makes a copy of the current state of :class:`Context` and saves it on an
        internal stack of saved states. When :meth:`.restore` is called,
        :class:`Context` will be restored to the saved state. Multiple calls to
        :meth:`.save` and :meth:`.restore` can be nested; each call to
        :meth:`.restore` restores the state from the matching paired
        :meth:`.save`.
        """

    def scale(self, sx: float, sy: float) -> None:
        """
        :param sx: scale factor for the X dimension
        :param sy: scale factor for the Y dimension

        Modifies the current transformation matrix (CTM) by scaling the X and Y
        user-space axes by *sx* and *sy* respectively. The scaling of the axes
        takes place after any existing transformation of user space.
        """

    def select_font_face(self, family: str, slant: FontSlant = FontSlant.NORMAL, weight: FontWeight = FontWeight.NORMAL) -> None:
        """
        :param family: a font family name
        :param slant: the font slant of the font,
            defaults to :attr:`cairo.FontSlant.NORMAL`.
        :param weight: the font weight of the
            font, defaults to :attr:`cairo.FontWeight.NORMAL`.

        Note: The :meth:`.select_font_face` function call is part of what the
        cairo designers call the "toy" text API. It is convenient for short
        demos and simple programs, but it is not expected to be adequate for
        serious text-using applications.

        Selects a family and style of font from a simplified description as a
        family name, slant and weight. Cairo provides no operation to list
        available family names on the system (this is a "toy", remember), but
        the standard CSS2 generic family names, ("serif", "sans-serif",
        "cursive", "fantasy", "monospace"), are likely to work as expected.

        For "real" font selection, see the font-backend-specific
        font_face_create functions for the font backend you are using. (For
        example, if you are using the freetype-based cairo-ft font backend, see
        cairo_ft_font_face_create_for_ft_face() or
        cairo_ft_font_face_create_for_pattern().) The resulting font face could
        then be used with cairo_scaled_font_create() and
        cairo_set_scaled_font().

        Similarly, when using the "real" font support, you can call directly
        into the underlying font system, (such as fontconfig or freetype), for
        operations such as listing available fonts, etc.

        It is expected that most applications will need to use a more
        comprehensive font handling and text layout library, (for example,
        pango), in conjunction with cairo.

        If text is drawn without a call to :meth:`.select_font_face`, (nor
        :meth:`.set_font_face` nor :meth:`.set_scaled_font`), the default family
        is platform-specific, but is essentially "sans-serif".  Default slant is
        :attr:`cairo.FontSlant.NORMAL`, and default weight is
        :attr:`cairo.FontWeight.NORMAL`.

        This function is equivalent to a call to :class:`ToyFontFace`
        followed by :meth:`.set_font_face`.
        """

    def set_antialias(self, antialias: Antialias) -> None:
        """
        :param antialias: the new antialias mode

        Set the antialiasing mode of the rasterizer used for drawing shapes.
        This value is a hint, and a particular backend may or may not support a
        particular value.  At the current time, no backend supports
        :attr:`cairo.Antialias.SUBPIXEL` when drawing shapes.

        Note that this option does not affect text rendering, instead see
        :meth:`FontOptions.set_antialias`.
        """

    def set_dash(self, dashes: Sequence[float], offset: float = 0) -> None:
        """
        :param dashes: a sequence specifying alternate lengths of on and off
            stroke portions as float.
        :param offset: an offset into the dash pattern at which the stroke
            should start, defaults to 0.
        :raises: :exc:`cairo.Error` if any value in *dashes* is negative, or if
            all values are 0.

        Sets the dash pattern to be used by :meth:`.stroke`. A dash pattern is
        specified by *dashes* - a sequence of positive values. Each value
        provides the length of alternate "on" and "off" portions of the
        stroke. The *offset* specifies an offset into the pattern at which the
        stroke begins.

        Each "on" segment will have caps applied as if the segment were a
        separate sub-path. In particular, it is valid to use an "on" length of
        0.0 with :attr:`cairo.LineCap.ROUND` or :attr:`cairo.LineCap.SQUARE`
        in order to distributed dots or squares along a path.

        Note: The length values are in user-space units as evaluated at the time
        of stroking. This is not necessarily the same as the user space at the
        time of :meth:`.set_dash`.

        If the number of dashes is 0 dashing is disabled.

        If the number of dashes is 1 a symmetric pattern is assumed with
        alternating on and off portions of the size specified by the single
        value in *dashes*.
        """

    def set_fill_rule(self, fill_rule: FillRule) -> None:
        """
        :param fill_rule: a fill rule to set the
            within the cairo context. The fill rule is used to determine which
            regions are inside or outside a complex (potentially
            self-intersecting) path. The current fill rule affects both
            :meth:`.fill` and :meth:`.clip`.

        The default fill rule is :attr:`cairo.FillRule.WINDING`.
        """

    def set_font_face(self, font_face: Optional[FontFace]) -> None:
        """
        :param font_face: a :class:`FontFace`, or None to restore to the
            default :class:`FontFace`

        Replaces the current :class:`FontFace` object in the :class:`Context`
        with *font_face*.
        """

    def set_font_matrix(self, matrix: Matrix) -> None:
        """
        :param matrix: a :class:`Matrix` describing a transform to be applied to
            the current font.

        Sets the current font matrix to *matrix*. The font matrix gives a
        transformation from the design space of the font (in this space, the
        em-square is 1 unit by 1 unit) to user space. Normally, a simple scale
        is used (see :meth:`.set_font_size`), but a more complex font matrix can
        be used to shear the font or stretch it unequally along the two axes
        """

    def set_font_options(self, options: FontOptions) -> None:
        """
        :param options: :class:`FontOptions` to use

        Sets a set of custom font rendering options for the :class:`Context`.
        Rendering options are derived by merging these options with the options
        derived from underlying surface; if the value in *options* has a default
        value (like :attr:`cairo.Antialias.DEFAULT`), then the value from the
        surface is used.
        """

    def set_font_size(self, size: float) -> None:
        """
        :param size: the new font size, in user space units

        Sets the current font matrix to a scale by a factor of *size*, replacing
        any font matrix previously set with :meth:`.set_font_size` or
        :meth:`.set_font_matrix`. This results in a font size of *size* user
        space units. (More precisely, this matrix will result in the font's
        em-square being a *size* by *size* square in user space.)

        If text is drawn without a call to :meth:`.set_font_size`, (nor
        :meth:`.set_font_matrix` nor :meth:`.set_scaled_font`), the default font
        size is 10.0.
        """

    def set_hairline(self, set_hairline: bool) -> None:
        """
        :param set_hairline: whether or not to set hairline mode

        Sets lines within the cairo context to be hairlines. Hairlines are
        logically zero-width lines that are drawn at the thinnest renderable
        width possible in the current context. On surfaces with native hairline
        support, the native hairline functionality will be used. Surfaces that
        support hairlines include:

        - pdf/ps: Encoded as 0-width line.
        - win32_printing: Rendered with PS_COSMETIC pen.
        - svg: Encoded as 1px non-scaling-stroke.
        - script: Encoded with set-hairline function.

        Cairo will always render hairlines at 1 device unit wide, even if an
        anisotropic scaling was applied to the stroke width. In the wild,
        handling of this situation is not well-defined. Some PDF, PS, and SVG
        renderers match Cairo's output, but some very popular implementations
        (Acrobat, Chrome, rsvg) will scale the hairline unevenly. As such, best
        practice is to reset any anisotropic scaling before calling
        :meth:`.stroke`. See https://cairographics.org/cookbook/ellipses/ for an
        example.

        .. versionadded:: 1.23 Only available with cairo 1.17.6+
        """

    def set_line_cap(self, line_cap: LineCap) -> None:
        """
        :param line_cap: a line cap style

        Sets the current line cap style within the :class:`Context`.

        As with the other stroke parameters, the current line cap style is
        examined by :meth:`.stroke` and :meth:`.stroke_extents`, but does not
        have any effect during path construction.

        The default line cap style is :attr:`cairo.LineCap.BUTT`.
        """

    def set_line_join(self, line_join: LineJoin) -> None:
        """
        :param line_join: a line join style

        Sets the current line join style within the :class:`Context`.

        As with the other stroke parameters, the current line join style is
        examined by :meth:`.stroke` and :meth:`.stroke_extents`, but does not
        have any effect during path construction.

        The default line join style is :attr:`cairo.LineJoin.MITER`.
        """

    def set_line_width(self, width: float) -> None:
        """
        :param width: a line width

        Sets the current line width within the :class:`Context`. The line width
        value specifies the diameter of a pen that is circular in user space,
        (though device-space pen may be an ellipse in general due to
        scaling/shear/rotation of the CTM).

        Note: When the description above refers to user space and CTM it refers
        to the user space and CTM in effect at the time of the stroking
        operation, not the user space and CTM in effect at the time of the call
        to :meth:`.set_line_width`. The simplest usage makes both of these
        spaces identical. That is, if there is no change to the CTM between a
        call to :meth:`.set_line_width` and the stroking operation, then one can
        just pass user-space values to :meth:`.set_line_width` and ignore this
        note.

        As with the other stroke parameters, the current line width is examined
        by :meth:`.stroke` and :meth:`.stroke_extents`, but does not have any
        effect during path construction.

        The default line width value is 2.0.
        """

    def set_matrix(self, matrix: Matrix) -> None:
        """
        :param matrix: a transformation :class:`Matrix` from user space to
            device space.

        Modifies the current transformation matrix (CTM) by setting it equal to
        *matrix*.
        """

    def set_miter_limit(self, limit: float) -> None:
        """
        :param limit: miter limit to set

        Sets the current miter limit within the :class:`Context`.

        If the current line join style is set to :attr:`cairo.LineJoin.MITER`
        (see :meth:`.set_line_join`), the miter limit is used to determine
        whether the lines should be joined with a bevel instead of a miter.
        Cairo divides the length of the miter by the line width. If the result
        is greater than the miter limit, the style is converted to a bevel.

        As with the other stroke parameters, the current line miter limit is
        examined by :meth:`.stroke` and :meth:`.stroke_extents`, but does not
        have any effect during path construction.

        The default miter limit value is 10.0, which will convert joins with
        interior angles less than 11 degrees to bevels instead of miters. For
        reference, a miter limit of 2.0 makes the miter cutoff at 60 degrees,
        and a miter limit of 1.414 makes the cutoff at 90 degrees.

        A miter limit for a desired angle can be computed as::

            miter limit = 1/math.sin(angle/2)
        """

    def set_operator(self, op: Operator) -> None:
        """
        :param op: the compositing operator to set
            for use in all drawing operations.

        The default operator is :attr:`cairo.Operator.OVER`.
        """

    def set_scaled_font(self, scaled_font: ScaledFont) -> None:
        """
        :param scaled_font: a :class:`ScaledFont`

        Replaces the current font face, font matrix, and font options in the
        :class:`Context` with those of the :class:`ScaledFont`. Except for some
        translation, the current CTM of the :class:`Context` should be the same
        as that of the :class:`ScaledFont`, which can be accessed using
        :meth:`ScaledFont.get_ctm`.

        .. versionadded:: 1.2
        """

    def set_source(self, source: Pattern) -> None:
        """
        :param source: a :class:`Pattern` to be used as the source for
            subsequent drawing operations.

        Sets the source pattern within :class:`Context` to *source*. This
        pattern will then be used for any subsequent drawing operation until a
        new source pattern is set.

        Note: The pattern's transformation matrix will be locked to the user
        space in effect at the time of :meth:`.set_source`. This means that
        further modifications of the current transformation matrix will not
        affect the source pattern. See :meth:`Pattern.set_matrix`.

        The default source pattern is a solid pattern that is opaque black,
        (that is, it is equivalent to ``set_source_rgb(0.0, 0.0, 0.0)``.
        """

    def set_source_rgb(self, red: float, green: float, blue: float) -> None:
        """
        :param red: red component of color
        :param green: green component of color
        :param blue: blue component of color

        Sets the source pattern within :class:`Context` to an opaque color. This
        opaque color will then be used for any subsequent drawing operation
        until a new source pattern is set.

        The color components are floating point numbers in the range 0 to
        1. If the values passed in are outside that range, they will be
        clamped.

        The default source pattern is opaque black, (that is, it is
        equivalent to ``set_source_rgb(0.0, 0.0, 0.0)``.
        """

    def set_source_rgba(self, red: float, green: float, blue: float, alpha: float = 1.0) -> None:
        """
        :param red: red component of color
        :param green: green component of color
        :param blue: blue component of color
        :param alpha: alpha component of color

        Sets the source pattern within :class:`Context` to a translucent
        color. This color will then be used for any subsequent drawing operation
        until a new source pattern is set.

        The color and alpha components are floating point numbers in the range 0
        to 1. If the values passed in are outside that range, they will be
        clamped.

        The default source pattern is opaque black, (that is, it is
        equivalent to ``set_source_rgba(0.0, 0.0, 0.0, 1.0)``.
        """

    def set_source_surface(self, surface: Surface, x: float = 0.0, y: float = 0.0) -> None:
        """
        :param surface: a :class:`Surface` to be used to set the source pattern
        :param x: User-space X coordinate for surface origin
        :param y: User-space Y coordinate for surface origin

        This is a convenience function for creating a pattern from a
        :class:`Surface` and setting it as the source in :class:`Context` with
        :meth:`.set_source`.

        The *x* and *y* parameters give the user-space coordinate at which the
        surface origin should appear. (The surface origin is its upper-left
        corner before any transformation has been applied.) The *x* and *y*
        patterns are negated and then set as translation values in the pattern
        matrix.

        Other than the initial translation pattern matrix, as described above,
        all other pattern attributes, (such as its extend mode), are set to the
        default values as in :class:`SurfacePattern`.  The resulting pattern can
        be queried with :meth:`.get_source` so that these attributes can be
        modified if desired, (eg. to create a repeating pattern with
        :meth:`.Pattern.set_extend`).
        """

    def set_tolerance(self, tolerance: float) -> None:
        """
        :param tolerance: the tolerance, in device units (typically pixels)

        Sets the tolerance used when converting paths into trapezoids.  Curved
        segments of the path will be subdivided until the maximum deviation
        between the original path and the polygonal approximation is less than
        *tolerance*. The default value is 0.1. A larger value will give better
        performance, a smaller value, better appearance. (Reducing the value
        from the default value of 0.1 is unlikely to improve appearance
        significantly.)  The accuracy of paths within Cairo is limited by the
        precision of its internal arithmetic, and the prescribed *tolerance* is
        restricted to the smallest representable internal value.
        """

    def show_glyphs(self, glyphs: Sequence[Glyph]) -> None:
        """
        :param glyphs: glyphs to show as a sequence of :class:`Glyph`

        A drawing operator that generates the shape from an array of glyphs,
        rendered according to the current font face, font size (font matrix),
        and font options.
        """

    def show_page(self) -> None:
        """
        Emits and clears the current page for backends that support multiple
        pages. Use :meth:`.copy_page` if you don't want to clear the page.

        This is a convenience function that simply calls
        ``ctx.get_target() . show_page()``
        """

    def show_text(self, text: str) -> None:
        """
        :param text: text

        A drawing operator that generates the shape from a string of text,
        rendered according to the current font_face, font_size (font_matrix),
        and font_options.

        This function first computes a set of glyphs for the string of text. The
        first glyph is placed so that its origin is at the current point. The
        origin of each subsequent glyph is offset from that of the previous
        glyph by the advance values of the previous glyph.

        After this call the current point is moved to the origin of where the
        next glyph would be placed in this same progression. That is, the
        current point will be at the origin of the final glyph offset by its
        advance values. This allows for easy display of a single logical string
        with multiple calls to :meth:`.show_text`.

        Note: The :meth:`.show_text` function call is part of what the cairo
        designers call the "toy" text API. It is convenient for short demos
        and simple programs, but it is not expected to be adequate for
        serious text-using applications. See :meth:`.show_glyphs` for the
        "real" text display API in cairo.
        """

    def show_text_glyphs(self, utf8: str, glyphs: List["Glyph"], clusters: List[TextCluster], cluster_flags: TextClusterFlags) -> None:
        """
        :param utf8: a string of text
        :param glyphs: list of glyphs to show
        :param clusters: list of cluster mapping information
        :param cluster_flags: cluster mapping flags
        :raises Error:

        .. versionadded:: 1.15

        This operation has rendering effects similar to
        :meth:`Context.show_glyphs` but, if the target surface supports it, uses
        the provided text and cluster mapping to embed the text for the glyphs
        shown in the output. If the target does not support the extended
        attributes, this function acts like the basic
        :meth:`Context.show_glyphs` as if it had been passed ``glyphs`` .

        The mapping between utf8 and glyphs is provided by a list of clusters.
        Each cluster covers a number of text bytes and glyphs, and neighboring
        clusters cover neighboring areas of utf8 and glyphs . The clusters
        should collectively cover utf8 and glyphs in entirety.

        The first cluster always covers bytes from the beginning of utf8 . If
        ``cluster_flags`` do not have the :attr:`TextClusterFlags.BACKWARD` set,
        the first cluster also covers the beginning of glyphs , otherwise it
        covers the end of the glyphs array and following clusters move backward.

        See :class:`TextCluster` for constraints on valid clusters.
        """

    def stroke(self) -> None:
        """
        A drawing operator that strokes the current path according to the
        current line width, line join, line cap, and dash settings. After
        :meth:`.stroke`, the current path will be cleared from the cairo
        context. See :meth:`.set_line_width`, :meth:`.set_line_join`,
        :meth:`.set_line_cap`, :meth:`.set_dash`, and :meth:`.stroke_preserve`.

        Note: Degenerate segments and sub-paths are treated specially and
        provide a useful result. These can result in two different situations:

        1. Zero-length "on" segments set in :meth:`.set_dash`. If the cap
        style is :attr:`cairo.LineCap.ROUND` or :attr:`cairo.LineCap.SQUARE`
        then these segments will be drawn as circular dots or squares
        respectively. In the case of :attr:`cairo.LineCap.SQUARE`, the
        orientation of the squares is determined by the direction of the
        underlying path.

        2. A sub-path created by :meth:`.move_to` followed by either a
        :meth:`.close_path` or one or more calls to :meth:`.line_to` to the same
        coordinate as the :meth:`.move_to`. If the cap style is
        :attr:`cairo.LineCap.ROUND` then these sub-paths will be drawn as
        circular dots. Note that in the case of :attr:`cairo.LineCap.SQUARE` a
        degenerate sub-path will not be drawn at all, (since the correct
        orientation is indeterminate).

        In no case will a cap style of :attr:`cairo.LineCap.BUTT` cause anything
        to be drawn in the case of either degenerate segments or sub-paths.
        """

    def stroke_extents(self) -> Tuple[float, float, float, float]:
        """
        :returns: (x1, y1, x2, y2), all float

        * *x1*: left of the resulting extents
        * *y1*: top of the resulting extents
        * *x2*: right of the resulting extents
        * *y2*: bottom of the resulting extents

        Computes a bounding box in user coordinates covering the area that would
        be affected, (the "inked" area), by a :meth:`.stroke` operation given
        the current path and stroke parameters. If the current path is empty,
        returns an empty rectangle (0, 0, 0, 0). Surface dimensions and
        clipping are not taken into account.

        Note that if the line width is set to exactly zero, then
        :meth:`.stroke_extents` will return an empty rectangle. Contrast with
        :meth:`.path_extents` which can be used to compute the non-empty bounds
        as the line width approaches zero.

        Note that :meth:`.stroke_extents` must necessarily do more work to
        compute the precise inked areas in light of the stroke parameters, so
        :meth:`.path_extents` may be more desirable for sake of performance if
        non-inked path extents are desired.

        See :meth:`.stroke`, :meth:`.set_line_width`, :meth:`.set_line_join`,
        :meth:`.set_line_cap`, :meth:`.set_dash`, and :meth:`.stroke_preserve`.
        """

    def stroke_preserve(self) -> None:
        """
        A drawing operator that strokes the current path according to the
        current line width, line join, line cap, and dash settings. Unlike
        :meth:`.stroke`, :meth:`.stroke_preserve` preserves the path within the
        cairo context.

        See :meth:`.set_line_width`, :meth:`.set_line_join`,
        :meth:`.set_line_cap`, :meth:`.set_dash`, and :meth:`.stroke_preserve`.
        """

    def tag_begin(self, tag_name: str, attributes: str) -> None:
        """
        :param tag_name: tag name
        :param attributes: tag attributes

        Marks the beginning of the tag_name structure. Call :meth:`tag_end`
        with the same tag_name to mark the end of the structure.

        The attributes string is of the form "key1=value2 key2=value2 ...".
        Values may be boolean (true/false or 1/0), integer, float, string, or
        an array.

        String values are enclosed in single quotes ('). Single quotes and
        backslashes inside the string should be escaped with a backslash.

        Boolean values may be set to true by only specifying the key. eg the
        attribute string "key" is the equivalent to "key=true".

        Arrays are enclosed in '[]'. eg "rect=[1.2 4.3 2.0 3.0]".

        If no attributes are required, attributes can be an empty string.

        See `Tags and Links Description
        <https://www.cairographics.org/manual/cairo-Tags-and-Links.html#cairo-Tags-and-Links.description>`__
        for the list of tags and attributes.

        Invalid nesting of tags or invalid attributes will cause the context
        to shutdown with a status of :attr:`Status.TAG_ERROR`.

        See :meth:`tag_end`.

        .. versionadded:: 1.18.0 Only available with cairo 1.15.10+
        """

    def tag_end(self, tag_name: str) -> None:
        """
        :param tag_name: tag name

        Marks the end of the tag_name structure.

        Invalid nesting of tags will cause the context to shutdown with a
        status of :attr:`Status.TAG_ERROR`.

        See :meth:`tag_begin`.

        .. versionadded:: 1.18.0 Only available with cairo 1.15.10+
        """

    def text_extents(self, text: str) -> TextExtents:
        """
        :param text: text to get extents for

        Gets the extents for a string of text. The extents describe a user-space
        rectangle that encloses the "inked" portion of the text, (as it would be
        drawn by :meth:`Context.show_text`). Additionally, the x_advance and
        y_advance values indicate the amount by which the current point would be
        advanced by :meth:`Context.show_text`.

        Note that whitespace characters do not directly contribute to the size
        of the rectangle (extents.width and extents.height). They do contribute
        indirectly by changing the position of non-whitespace characters. In
        particular, trailing whitespace characters are likely to not affect the
        size of the rectangle, though they will affect the x_advance and
        y_advance values.
        """

    def text_path(self, text: str) -> None:
        """
        :param text: text

        Adds closed paths for text to the current path. The generated path if
        filled, achieves an effect similar to that of :meth:`Context.show_text`.

        Text conversion and positioning is done similar to
        :meth:`Context.show_text`.

        Like :meth:`Context.show_text`, After this call the current point is
        moved to the origin of where the next glyph would be placed in this same
        progression. That is, the current point will be at the origin of the
        final glyph offset by its advance values.  This allows for chaining
        multiple calls to to :meth:`Context.text_path` without having to set
        current point in between.

        Note: The :meth:`.text_path` function call is part of what the cairo
        designers call the "toy" text API. It is convenient for short demos and
        simple programs, but it is not expected to be adequate for serious
        text-using applications. See :meth:`Context.glyph_path` for the "real"
        text path API in cairo.
        """

    def transform(self, matrix: Matrix) -> None:
        """
        :param matrix: a transformation :class:`Matrix` to be applied to the
            user-space axes

        Modifies the current transformation matrix (CTM) by applying *matrix* as
        an additional transformation. The new transformation of user space takes
        place after any existing transformation.
        """

    def translate(self, tx: float, ty: float) -> None:
        """
        :param tx: amount to translate in the X direction
        :param ty: amount to translate in the Y direction

        Modifies the current transformation matrix (CTM) by translating the
        user-space origin by *(tx, ty)*. This offset is interpreted as a
        user-space coordinate according to the CTM in place before the new call
        to :meth:`.translate`. In other words, the translation of the user-space
        origin takes place after any existing transformation.
        """

    def user_to_device(self, x: float, y: float) -> Tuple[float, float]:
        """
        :param x: X value of coordinate
        :param y: Y value of coordinate
        :returns: (x, y), both float

        * *x*: X value of coordinate
        * *y*: Y value of coordinate

        Transform a coordinate from user space to device space by multiplying
        the given point by the current transformation matrix (CTM).
        """

    def user_to_device_distance(self, dx: float, dy: float) -> Tuple[float, float]:
        """
        :param dx: X value of a distance vector
        :param dy: Y value of a distance vector
        :returns: (dx, dy), both float

        * *dx*: X value of a distance vector
        * *dy*: Y value of a distance vector

        Transform a distance vector from user space to device space. This
        function is similar to :meth:`Context.user_to_device` except that the
        translation components of the CTM will be ignored when transforming
        *(dx,dy)*.
        """

class Error(Exception):
    """This exception is raised when a cairo object returns an error status."""
    status: Status = ...

CairoError = Error
"""
An alias for :exc:`Error`

.. versionadded:: 1.12.0
"""

class Gradient(Pattern):
    """
    *Gradient* is an abstract base class from which other *Pattern* classes
    derive. It cannot be instantiated directly.
    """

    def add_color_stop_rgb(self, offset: float, red: float, green: float, blue: float) -> None:
        """
        :param offset: an offset in the range [0.0 .. 1.0]
        :param red: red component of color
        :param green: green component of color
        :param blue: blue component of color

        Adds an opaque color stop to a *Gradient* pattern. The offset specifies
        the location along the gradient's control vector. For example, a
        *LinearGradient's* control vector is from (x0,y0) to (x1,y1) while a
        *RadialGradient's* control vector is from any point on the start circle
        to the corresponding point on the end circle.

        The color is specified in the same way as in :meth:`Context.set_source_rgb`.

        If two (or more) stops are specified with identical offset values, they
        will be sorted according to the order in which the stops are added,
        (stops added earlier will compare less than stops added later). This can
        be useful for reliably making sharp color transitions instead of the
        typical blend.
        """

    def add_color_stop_rgba(self, offset: float, red: float, green: float, blue: float, alpha: float) -> None:
        """
        :param offset: an offset in the range [0.0 .. 1.0]
        :param red: red component of color
        :param green: green component of color
        :param blue: blue component of color
        :param alpha: alpha component of color

        Adds an opaque color stop to a *Gradient* pattern. The offset specifies
        the location along the gradient's control vector. For example, a
        *LinearGradient's* control vector is from (x0,y0) to (x1,y1) while a
        *RadialGradient's* control vector is from any point on the start circle
        to the corresponding point on the end circle.

        The color is specified in the same way as in :meth:`Context.set_source_rgb`.

        If two (or more) stops are specified with identical offset values, they
        will be sorted according to the order in which the stops are added,
        (stops added earlier will compare less than stops added later). This can
        be useful for reliably making sharp color transitions instead of the
        typical blend.
        """

    def get_color_stops_rgba(self) -> List[Tuple[float, float, float, float, float]]:
        """
        :returns: a list of (offset, red, green, blue, alpha) tuples of float

        Gets the color and offset information for all color stops specified in
        the given gradient pattern.

        .. versionadded:: 1.14
        """

class LinearGradient(Gradient):
    def __init__(self, x0: float, y0: float, x1: float, y1: float) -> None:
        """
        :param x0: x coordinate of the start point
        :param y0: y coordinate of the start point
        :param x1: x coordinate of the end point
        :param y1: y coordinate of the end point

        Create a new *LinearGradient* along the line defined by (x0, y0) and (x1,
        y1).  Before using the *Gradient* pattern, a number of color stops should
        be defined using :meth:`Gradient.add_color_stop_rgb` or
        :meth:`Gradient.add_color_stop_rgba`

        Note: The coordinates here are in pattern space. For a new *Pattern*,
        pattern space is identical to user space, but the relationship between the
        spaces can be changed with :meth:`Pattern.set_matrix`
        """

    def get_linear_points(self) -> Tuple[float, float, float, float]:
        """
        :returns: (x0, y0, x1, y1) - a tuple of float

            * x0: return value for the x coordinate of the first point
            * y0: return value for the y coordinate of the first point
            * x1: return value for the x coordinate of the second point
            * y1: return value for the y coordinate of the second point

        Gets the gradient endpoints for a *LinearGradient*.

        .. versionadded:: 1.4
        """

class MeshPattern(Pattern):
    """
    Mesh patterns are tensor-product patch meshes (type 7 shadings in PDF).
    Mesh patterns may also be used to create other types of shadings that are
    special cases of tensor-product patch meshes such as Coons patch meshes
    (type 6 shading in PDF) and Gouraud-shaded triangle meshes (type 4 and 5
    shadings in PDF).

    Mesh patterns consist of one or more tensor-product patches, which should
    be defined before using the mesh pattern. Using a mesh pattern with a
    partially defined patch as source or mask will put the context in an error
    status with a status of :attr:`cairo.Status.INVALID_MESH_CONSTRUCTION`.

    A tensor-product patch is defined by 4 Bézier curves (side 0, 1, 2, 3) and
    by 4 additional control points (P0, P1, P2, P3) that provide further
    control over the patch and complete the definition of the tensor-product
    patch. The corner C0 is the first point of the patch.

    Degenerate sides are permitted so straight lines may be used. A zero
    length line on one side may be used to create 3 sided patches.

    ::

              C1     Side 1       C2
               +---------------+
               |               |
               |  P1       P2  |
               |               |
        Side 0 |               | Side 2
               |               |
               |               |
               |  P0       P3  |
               |               |
               +---------------+
             C0     Side 3        C3

    Each patch is constructed by first calling :meth:`begin_patch`, then
    :meth:`move_to` to specify the first point in the patch (C0). Then the
    sides are specified with calls to :meth:`curve_to` and :meth:`line_to`.

    The four additional control points (P0, P1, P2, P3) in a patch can be
    specified with :meth:`set_control_point`.

    At each corner of the patch (C0, C1, C2, C3) a color may be specified with
    :meth:`set_corner_color_rgb` or :meth:`set_corner_color_rgba`. Any corner
    whose color is not explicitly specified defaults to transparent black.

    A Coons patch is a special case of the tensor-product patch where the
    control points are implicitly defined by the sides of the patch. The
    default value for any control point not specified is the implicit value
    for a Coons patch, i.e. if no control points are specified the patch is a
    Coons patch.

    A triangle is a special case of the tensor-product patch where the control
    points are implicitly defined by the sides of the patch, all the sides are
    lines and one of them has length 0, i.e. if the patch is specified using
    just 3 lines, it is a triangle. If the corners connected by the 0-length
    side have the same color, the patch is a Gouraud-shaded triangle.

    Patches may be oriented differently to the above diagram. For example the
    first point could be at the top left. The diagram only shows the
    relationship between the sides, corners and control points. Regardless of
    where the first point is located, when specifying colors, corner 0 will
    always be the first point, corner 1 the point between side 0 and side 1
    etc.

    Calling :meth:`end_patch` completes the current patch. If less than 4
    sides have been defined, the first missing side is defined as a line from
    the current point to the first point of the patch (C0) and the other sides
    are degenerate lines from C0 to C0. The corners between the added sides
    will all be coincident with C0 of the patch and their color will be set to
    be the same as the color of C0.

    Additional patches may be added with additional calls to
    :meth:`begin_patch`/:meth:`end_patch`.

    ::

        # Add a Coons patch
        pattern = cairo.MeshPattern()
        pattern.begin_patch()
        pattern.move_to(0, 0)
        pattern.curve_to(30, -30, 60, 30, 100, 0)
        pattern.curve_to(60, 30, 130, 60, 100, 100)
        pattern.curve_to(60, 70, 30, 130, 0, 100)
        pattern.curve_to(30, 70, -30, 30, 0, 0)
        pattern.set_corner_color_rgb(0, 1, 0, 0)
        pattern.set_corner_color_rgb(1, 0, 1, 0)
        pattern.set_corner_color_rgb(2, 0, 0, 1)
        pattern.set_corner_color_rgb(3, 1, 1, 0)
        pattern.end_patch()

        # Add a Gouraud-shaded triangle
        pattern = cairo.MeshPattern()
        pattern.begin_patch()
        pattern.move_to(100, 100)
        pattern.line_to(130, 130)
        pattern.line_to(130, 70)
        pattern.set_corner_color_rgb(0, 1, 0, 0)
        pattern.set_corner_color_rgb(1, 0, 1, 0)
        pattern.set_corner_color_rgb(2, 0, 0, 1)
        pattern.end_patch()

    When two patches overlap, the last one that has been added is drawn over
    the first one.

    When a patch folds over itself, points are sorted depending on their
    parameter coordinates inside the patch. The v coordinate ranges from 0 to
    1 when moving from side 3 to side 1; the u coordinate ranges from 0 to 1
    when going from side 0 to side

    Points with higher v coordinate hide points with lower v coordinate. When
    two points have the same v coordinate, the one with higher u coordinate is
    above. This means that points nearer to side 1 are above points nearer to
    side 3; when this is not sufficient to decide which point is above (for
    example when both points belong to side 1 or side 3) points nearer to side
    2 are above points nearer to side 0.

    For a complete definition of tensor-product patches, see the PDF
    specification (ISO32000), which describes the parametrization in detail.

    Note: The coordinates are always in pattern space. For a new pattern,
    pattern space is identical to user space, but the relationship between the
    spaces can be changed with :meth:`Pattern.set_matrix`.

    .. versionadded:: 1.14
    """

    def __init__(self) -> None:
        """
        Create a new mesh pattern.

        .. versionadded:: 1.14
        """

    def begin_patch(self) -> None:
        """
        :raises Error:

        Begin a patch in a mesh pattern.

        After calling this function, the patch shape should be defined with
        :meth:`move_to`, :meth:`line_to` and :meth:`curve_to`.

        After defining the patch, :meth:`end_patch` must be called before
        using pattern as a source or mask.
        """

    def curve_to(self, x1: float, y1: float, x2: float, y2: float, x3: float, y3: float) -> None:
        """
        :param x1: the X coordinate of the first control point
        :param y1: the Y coordinate of the first control point
        :param x2: the X coordinate of the second control point
        :param y2: the Y coordinate of the second control point
        :param x3: the X coordinate of the end of the curve
        :param y3: the Y coordinate of the end of the curve
        :raises Error:

        Adds a cubic Bézier spline to the current patch from the current point
        to position (x3 , y3 ) in pattern-space coordinates, using (x1 , y1 )
        and (x2 , y2 ) as the control points.

        If the current patch has no current point before the call to
        :meth:`curve_to`, this function will behave as if
        preceded by a call to ``pattern.move_to(x1, y1)``.

        After this call the current point will be (x3 , y3 ).
        """

    def end_patch(self) -> None:
        """
        :raises Error:

        Indicates the end of the current patch in a mesh pattern.

        If the current patch has less than 4 sides, it is closed with a
        straight line from the current point to the first point of the patch
        as if :meth:`line_to` was used.
        """

    def get_control_point(self, patch_num: int, point_num: int) -> Tuple[float, float]:
        """
        :param patch_num: the patch number to return data for
        :param point_num: he control point number to return data for
        :returns: a (x, y) tuple of float - coordinates of the control point
        :raises Error:

        Gets the control point point_num of patch patch_num for a mesh
        pattern.

        ``patch_num`` can range from 0 to n-1 where n is the number returned
        by :meth:`get_patch_count`.

        Valid values for ``point_num`` are from 0 to 3 and identify the control
        points as explained in :class:`MeshPattern`.
        """

    def get_corner_color_rgba(self, patch_num: int, corner_num: int) -> Tuple[float, float, float, float]:
        """
        :param patch_num: the patch number to return data for
        :param corner_num: the corner number to return data for
        :returns: a (red, green, blue, alpha) tuple of float
        :raises Error:

        Gets the color information in corner ``corner_num`` of patch
        ``patch_num`` for a mesh pattern.

        ``patch_num`` can range from 0 to n-1 where n is the number returned
        by :meth:`get_patch_count`.

        Valid values for ``corner_num`` are from 0 to 3 and identify the
        corners as explained in :class:`MeshPattern`.
        """

    def get_patch_count(self) -> int:
        """
        :returns: number of patches

        Gets the number of patches specified in the given mesh pattern.

        The number only includes patches which have been finished by calling
        :meth:`end_patch`. For example it will be 0 during the definition of
        the first patch.
        """

    def line_to(self, x: float, y: float) -> None:
        """
        :param x: the X coordinate of the end of the new line
        :param y: the Y coordinate of the end of the new line
        :raises Error:

        Adds a line to the current patch from the current point to position (x
        , y ) in pattern-space coordinates.

        If there is no current point before the call to :meth:`line_to` this
        function will behave as ``pattern.move_to(x ,y)``.

        After this call the current point will be (x , y ).
        """

    def move_to(self, x: float, y: float) -> None:
        """
        :param x: the X coordinate of the new position
        :param y: the Y coordinate of the new position
        :raises Error:

        Define the first point of the current patch in a mesh pattern.

        After this call the current point will be (x , y ).
        """

    def set_control_point(self, point_num: int, x: float, y: float) -> None:
        """
        :param point_num: the control point to set the position for
        :param x: the X coordinate of the control point
        :param y: the Y coordinate of the control point
        :raises Error:

        Set an internal control point of the current patch.

        Valid values for point_num are from 0 to 3 and identify the control
        points as explained in :class:`MeshPattern`.
        """

    def set_corner_color_rgb(self, corner_num: int, red: float, green: float, blue: float) -> None:
        """
        :param corner_num: the corner to set the color for
        :param red: red component of color
        :param green: green component of color
        :param blue: blue component of color
        :raises Error:

        Sets the color of a corner of the current patch in a mesh pattern.

        The color is specified in the same way as in
        :meth:`Context.set_source_rgb`.

        Valid values for corner_num are from 0 to 3 and identify the corners
        as explained in :class:`MeshPattern`.
        """

    def set_corner_color_rgba(self, corner_num: int, red: float, green: float, blue: float, alpha: float) -> None:
        """
        :param corner_num: the corner to set the color for
        :param red: red component of color
        :param green: green component of color
        :param blue: blue component of color
        :param alpha: alpha component of color
        :raises Error:

        Sets the color of a corner of the current patch in a mesh pattern.

        The color is specified in the same way as in
        :meth:`Context.set_source_rgba`.

        Valid values for corner_num are from 0 to 3 and identify the corners
        as explained in :class:`MeshPattern`.
        """

    def get_path(self, patch_num: int) -> Path:
        """
        :param patch_num: the patch number to return data for
        :returns: the path defining the patch
        :raises Error:

        Gets path defining the patch ``patch_num`` for a mesh pattern.

        ``patch_num`` can range from 0 to n-1 where n is the number returned
        by :meth:`get_patch_count`.
        """

class PDFSurface(Surface):
    """
    The PDFSurface is used to render cairo graphics to Adobe PDF files and is a
    multi-page vector surface backend.

    .. versionadded:: 1.2
    """

    def __init__(self, fobj: Union[_PathLike, _FileLike], width_in_points: float, height_in_points: float) -> None:
        """
        :param fobj: a filename or writable file object. None may be used to
            specify no output. This will generate a *PDFSurface* that may be
            queried and used as a source, without generating a temporary file.
        :param width_in_points: width of the surface, in points (1 point ==
            1/72.0 inch)
        :param height_in_points: height of the surface, in points (1 point ==
            1/72.0 inch)
        :returns: a new *PDFSurface* of the specified size in points to be
            written to *fobj*.

        .. versionadded:: 1.2
        """

    def set_custom_metadata(self, name: str, value: Optional[str]) -> None:
        """
        :param name: The name of the custom metadata item to set.
        :param value: The value of the metadata.

        Set custom document metadata. *name* may be any string except for the
        following names reserved by PDF: "Title", "Author", "Subject",
        "Keywords", "Creator", "Producer", "CreationDate", "ModDate", "Trapped".

        If *value* is :obj:`None` or an empty string, the *name* metadata will
        not be set.

        For example::

            surface.set_custom_metadata("ISBN", "978-0123456789")

        .. versionadded:: 1.23.0 Only available with cairo 1.17.6+
        """

    def set_size(self, width_in_points: float, height_in_points: float) -> None:
        """
        :param width_in_points: new surface width, in points
            (1 point == 1/72.0 inch)
        :param height_in_points: new surface height, in points
            (1 point == 1/72.0 inch)

        Changes the size of a *PDFSurface* for the current (and subsequent) pages.

        This function should only be called before any drawing operations have
        been performed on the current page. The simplest way to do this is to
        call this function immediately after creating the surface or immediately
        after completing a page with either :meth:`Context.show_page` or
        :meth:`Context.copy_page`.

        .. versionadded:: 1.2
        """

    def restrict_to_version(self, version: PDFVersion) -> None:
        """
        :param version: PDF version

        Restricts the generated PDF file to version . See :meth:`get_versions`
        for a list of available version values that can be used here.

        This function should only be called before any drawing operations have
        been performed on the given surface. The simplest way to do this is to
        call this function immediately after creating the surface.

        .. versionadded:: 1.12.0
        """

    @staticmethod
    def get_versions() -> List[PDFVersion]:
        """
        :returns: supported version list

        Retrieve the list of supported versions. See
        :meth:`restrict_to_version`.

        .. versionadded:: 1.12.0
        """

    @staticmethod
    def version_to_string(version: PDFVersion) -> str:
        """
        :param version: PDF version
        :returns: the string associated to the given version
        :raises ValueError: if version isn't valid

        Get the string representation of the given version id. See
        :meth:`get_versions` for a way to get the list of valid version ids.

        .. versionadded:: 1.12.0
        """

    def add_outline(self, parent_id: int, utf8: str, link_attribs: str, flags: PDFOutlineFlags) -> int:
        """
        :param parent_id:
            the id of the parent item or :data:`PDF_OUTLINE_ROOT` if this is a top
            level item.
        :param utf8:
            the name of the outline
        :param link_attribs:
            the link attributes specifying where this outline links to
        :param flags:
            outline item flags
        :returns: the id for the added item.

        .. versionadded:: 1.18.0 Only available with cairo 1.15.10+
        """

    def set_metadata(self, metadata: PDFMetadata, utf8: str) -> None:
        """
        :param metadata: The metadata item to set.
        :param utf8: metadata value

        Set document metadata. The :attr:`PDFMetadata.CREATE_DATE` and
        :attr:`PDFMetadata.MOD_DATE` values must be in ISO-8601 format:
        YYYY-MM-DDThh:mm:ss. An optional timezone of the form "[+/-]hh:mm" or
        "Z" for UTC time can be appended. All other metadata values can be any
        UTF-8 string.

        .. versionadded:: 1.18.0 Only available with cairo 1.15.10+
        """

    def set_page_label(self, utf8: str) -> None:
        """
        :param utf8: metadata value

        Set page label for the current page.

        .. versionadded:: 1.18.0 Only available with cairo 1.15.10+
        """

    def set_thumbnail_size(self, width: int, height: int) -> None:
        """
        :param width: Thumbnail width.
        :param height: Thumbnail height

        Set the thumbnail image size for the current and all subsequent pages.
        Setting a width or height of 0 disables thumbnails for the current and
        subsequent pages.

        .. versionadded:: 1.18.0 Only available with cairo 1.15.10+
        """

class PSSurface(Surface):
    """
    The *PSSurface* is used to render cairo graphics to Adobe PostScript files and
    is a multi-page vector surface backend.
    """

    def __init__(self, fobj: Union[_FileLike, _PathLike], width_in_points: float, height_in_points: float) -> None:
        """
        :param fobj: a filename or writable file object. None may be used to specify no output. This will generate a *PSSurface* that may be queried and used as a source, without generating a temporary file.
        :param width_in_points: width of the surface, in points
            (1 point == 1/72.0 inch)
        :param height_in_points: height of the surface, in points
            (1 point == 1/72.0 inch)
        :returns: a new *PDFSurface* of the specified size in points to be written
            to *fobj*.
        :raises: :exc:`MemoryError` in case of no memory

        Note that the size of individual pages of the PostScript output can
        vary. See :meth:`.set_size`.
        """

    def dsc_begin_page_setup(self) -> None:
        """
        This method indicates that subsequent calls to
        :meth:`.dsc_comment` should direct comments to the PageSetup
        section of the PostScript output.

        This method call is only needed for the first page of a surface. It
        should be called after any call to :meth:`.dsc_begin_setup` and
        before any drawing is performed to the surface.

        See :meth:`.dsc_comment` for more details.

        .. versionadded:: 1.2
        """

    def dsc_begin_setup(self) -> None:
        """
        This function indicates that subsequent calls to :meth:`.dsc_comment`
        should direct comments to the Setup section of the PostScript output.

        This function should be called at most once per surface, and must be
        called before any call to :meth:`.dsc_begin_page_setup` and before any
        drawing is performed to the surface.

        See :meth:`.dsc_comment` for more details.

        .. versionadded:: 1.2
        """

    def dsc_comment(self, comment: str) -> None:
        """
        :param comment: a comment string to be emitted into the PostScript output

        Emit a comment into the PostScript output for the given surface.

        The comment is expected to conform to the PostScript Language
        Document Structuring Conventions (DSC). Please see that manual for
        details on the available comments and their meanings. In
        particular, the %%IncludeFeature comment allows a
        device-independent means of controlling printer device features. So
        the PostScript Printer Description Files Specification will also be
        a useful reference.

        The comment string must begin with a percent character (%) and the
        total length of the string (including any initial percent
        characters) must not exceed 255 characters. Violating either of
        these conditions will place *PSSurface* into an error state. But
        beyond these two conditions, this function will not enforce
        conformance of the comment with any particular specification.

        The comment string should not have a trailing newline.

        The DSC specifies different sections in which particular comments
        can appear. This function provides for comments to be emitted
        within three sections: the header, the Setup section, and the
        PageSetup section.  Comments appearing in the first two sections
        apply to the entire document while comments in the BeginPageSetup
        section apply only to a single page.

        For comments to appear in the header section, this function should
        be called after the surface is created, but before a call to
        :meth:`.dsc_begin_setup`.

        For comments to appear in the Setup section, this function should be
        called after a call to :meth:`.dsc_begin_setup` but before a call to
        :meth:`.dsc_begin_page_setup`.

        For comments to appear in the PageSetup section, this function should be
        called after a call to :meth:`.dsc_begin_page_setup`.

        Note that it is only necessary to call :meth:`.dsc_begin_page_setup` for
        the first page of any surface. After a call to :meth:`Context.show_page`
        or :meth:`Context.copy_page` comments are unambiguously directed to the
        PageSetup section of the current page. But it doesn't hurt to call this
        function at the beginning of every page as that consistency may make the
        calling code simpler.

        As a final note, cairo automatically generates several comments on
        its own. As such, applications must not manually generate any of
        the following comments:

        Header section: %!PS-Adobe-3.0, %Creator, %CreationDate, %Pages,
        %BoundingBox, %DocumentData, %LanguageLevel, %EndComments.

        Setup section: %BeginSetup, %EndSetup

        PageSetup section: %BeginPageSetup, %PageBoundingBox,
        %EndPageSetup.

        Other sections: %BeginProlog, %EndProlog, %Page, %Trailer, %EOF

        Here is an example sequence showing how this function might be used::

            surface = PSSurface (filename, width, height)
            ...
            surface.dsc_comment (surface, "%%Title: My excellent document")
            surface.dsc_comment (surface, "%%Copyright: Copyright (C) 2006 Cairo Lover")
            ...
            surface.dsc_begin_setup (surface)
            surface.dsc_comment (surface, "%%IncludeFeature: *MediaColor White")
            ...
            surface.dsc_begin_page_setup (surface)
            surface.dsc_comment (surface, "%%IncludeFeature: *PageSize A3")
            surface.dsc_comment (surface, "%%IncludeFeature: *InputSlot LargeCapacity")
            surface.dsc_comment (surface, "%%IncludeFeature: *MediaType Glossy")
            surface.dsc_comment (surface, "%%IncludeFeature: *MediaColor Blue")
            ... draw to first page here ..
            ctx.show_page (cr)
            ...
            surface.dsc_comment (surface, "%%IncludeFeature:  PageSize A5");
            ...

        .. versionadded:: 1.2
        """

    def get_eps(self) -> bool:
        """
        :returns: True iff the *PSSurface* will output Encapsulated PostScript.

        .. versionadded:: 1.6
        """

    @staticmethod
    def level_to_string(level: PSLevel) -> str:
        """
        :param level: a PS level
        :returns: the string associated to given level.

        Get the string representation of the given *level*.  See
        :meth:`get_levels` for a way to get the list of valid level
        ids.

        .. note:: Prior to 1.12 this was available under
            :meth:`ps_level_to_string`

        .. versionadded:: 1.12.0
        """

    ps_level_to_string = level_to_string
    """
    Alias for :meth:`level_to_string`

    .. versionadded:: 1.6
    """

    def restrict_to_level(self, level: PSLevel) -> None:
        """
        :param level: a PS level

        Restricts the generated PostSript file to *level*. See
        :meth:`get_levels` for a list of available level values that
        can be used here.

        This function should only be called before any drawing operations have
        been performed on the given surface. The simplest way to do this is to
        call this function immediately after creating the surface.

        .. versionadded:: 1.6
        """

    def set_eps(self, eps: bool) -> None:
        """
        :param eps: True to output EPS format PostScript

        If *eps* is True, the PostScript surface will output Encapsulated
        PostScript.

        This function should only be called before any drawing operations have
        been performed on the current page. The simplest way to do this is to
        call this function immediately after creating the surface. An
        Encapsulated PostScript file should never contain more than one page.

        .. versionadded:: 1.6
        """

    def set_size(self, width_in_points: float, height_in_points: float) -> None:
        """
        :param width_in_points: new surface width, in points (1 point == 1/72.0 inch)
        :param height_in_points: new surface height, in points (1 point == 1/72.0 inch)

        Changes the size of a PostScript surface for the current (and
        subsequent) pages.

        This function should only be called before any drawing operations
        have been performed on the current page. The simplest way to do
        this is to call this function immediately after creating the
        surface or immediately after completing a page with either
        :meth:`Context.show_page` or :meth:`Context.copy_page`.

        .. versionadded:: 1.2
        """

    @staticmethod
    def get_levels() -> List[PSLevel]:
        """
        :returns: supported level list

        Retrieve the list of supported levels. See
        :meth:`restrict_to_level`.

        .. versionadded:: 1.12.0
        """

class SVGSurface(Surface):
    """
    The *SVGSurface* is used to render cairo graphics to SVG files and is a
    multi-page vector surface backend
    """

    def __init__(self, fobj: "Union[_PathLike, _FileLike]", width_in_points: float, height_in_points: float) -> None:
        """
        :param fobj: a filename or writable file object. None may be used to specify no output. This will generate a *SVGSurface* that may be queried and used as a source, without generating a temporary file.
        :param width_in_points: width of the surface, in points (1 point == 1/72.0 inch)
        :param height_in_points: height of the surface, in points (1 point == 1/72.0 inch)
        """

    def restrict_to_version(self, version: SVGVersion) -> None:
        """
        :param version: SVG version

        Restricts the generated SVG file to version . See :meth:`get_versions`
        for a list of available version values that can be used here.

        This function should only be called before any drawing operations have
        been performed on the given surface. The simplest way to do this is to
        call this function immediately after creating the surface.

        .. versionadded:: 1.12.0
        """

    @staticmethod
    def get_versions() -> List[SVGVersion]:
        """
        :returns: supported version list

        Retrieve the list of supported versions. See
        :meth:`restrict_to_version`.

        .. versionadded:: 1.12.0
        """

    @staticmethod
    def version_to_string(version: SVGVersion) -> str:
        """
        :param version: SVG version
        :returns: the string associated to the given version
        :raises ValueError: if version isn't valid

        Get the string representation of the given version id. See
        :meth:`get_versions` for a way to get the list of valid version ids.

        .. versionadded:: 1.12.0
        """

    def get_document_unit(self) -> SVGUnit:
        """
        :returns: the SVG unit of the SVG surface.
        :rtype: SVGUnit

        Get the unit of the SVG surface.

        .. versionadded:: 1.18.0 Only available with cairo 1.15.10+
        """

    def set_document_unit(self, unit: SVGUnit) -> None:
        """
        :param SVGUnit unit: SVG unit

        Use the specified unit for the width and height of the generated SVG
        file. See :class:`SVGUnit` for a list of available unit values that can
        be used here.

        This function can be called at any time before generating the SVG file.

        However to minimize the risk of ambiguities it's recommended to call it
        before any drawing operations have been performed on the given surface,
        to make it clearer what the unit used in the drawing operations is.

        The simplest way to do this is to call this function immediately after
        creating the SVG surface.

        Note if this function is never called, the default unit for SVG
        documents generated by cairo will be "pt". This is for historical
        reasons.

        .. versionadded:: 1.18.0 Only available with cairo 1.15.10+
        """

class RadialGradient(Gradient):

    def __init__(self, cx0: float, cy0: float, radius0: float, cx1: float, cy1: float, radius1: float) -> None:
        """
        :param cx0: x coordinate for the center of the start circle
        :param cy0: y coordinate for the center of the start circle
        :param radius0: radius of the start circle
        :param cx1: x coordinate for the center of the end circle
        :param cy1: y coordinate for the center of the end circle
        :param radius1: radius of the end circle

        Creates a new *RadialGradient* pattern between the two circles defined by
        (cx0, cy0, radius0) and (cx1, cy1, radius1).  Before using the gradient
        pattern, a number of color stops should be defined using
        :meth:`Gradient.add_color_stop_rgb` or :meth:`Gradient.add_color_stop_rgba`.

        Note: The coordinates here are in pattern space. For a new pattern, pattern
        space is identical to user space, but the relationship between the spaces
        can be changed with :meth:`Pattern.set_matrix`.
        """

    def get_radial_circles(self) -> Tuple[float, float, float, float, float, float]:
        """
        :returns: (x0, y0, r0, x1, y1, r1) - a tuple of float

            * x0: return value for the x coordinate of the center of the first circle
            * y0: return value for the y coordinate of the center of the first circle
            * r0: return value for the radius of the first circle
            * x1: return value for the x coordinate of the center of the second circle
            * y1: return value for the y coordinate of the center of the second circle
            * r1: return value for the radius of the second circle

        Gets the *Gradient* endpoint circles for a *RadialGradient*, each
        specified as a center coordinate and a radius.

        .. versionadded:: 1.4
        """

_AcquireCallback = Callable[[Surface, RectangleInt], Surface]
_ReleaseCallback = Callable[[Surface], None]

class RasterSourcePattern(Pattern):
    """
    The raster source provides the ability to supply arbitrary pixel data whilst
    rendering. The pixels are queried at the time of rasterisation by means of
    user callback functions, allowing for the ultimate flexibility. For example,
    in handling compressed image sources, you may keep a MRU cache of decompressed
    images and decompress sources on the fly and discard old ones to conserve
    memory.

    For the raster source to be effective, you must at least specify the acquire
    and release callbacks which are used to retrieve the pixel data for the region
    of interest and demark when it can be freed afterwards. Other callbacks are
    provided for when the pattern is copied temporarily during rasterisation, or
    more permanently as a snapshot in order to keep the pixel data available for
    printing.

    .. versionadded:: 1.15
    """

    def __init__(self, content: Content, width: int, height: int) -> None:
        """
        :param content:
            content type for the pixel data that will be returned. Knowing the
            content type ahead of time is used for analysing the operation and
            picking the appropriate rendering path.
        :param width:
            maximum size of the sample area
        :param height:
            maximum size of the sample area

        Creates a new user pattern for providing pixel data.

        Use the setter functions to associate callbacks with the returned pattern.

        .. versionadded:: 1.15
        """

    def set_acquire(self, acquire: Optional[_AcquireCallback], release: Optional[_ReleaseCallback]) -> None:
        """
        :param acquire:
            acquire callback or :obj:`None` to unset it
        :type acquire: :obj:`callable`
        :param release:
            (optional) release callback or :obj:`None`
        :type release: :obj:`callable`
        :raises Error:

        Specifies the callbacks used to generate the image surface for a
        rendering operation (acquire) and the function used to cleanup that
        surface afterwards.

        The acquire callback should create a surface (preferably an image
        surface created to match the target using
        :meth:`Surface.create_similar_image`) that defines at least the region
        of interest specified by extents. The surface is allowed to be the
        entire sample area, but if it does contain a subsection of the sample
        area, the surface extents should be provided by setting the device
        offset (along with its width and height) using
        :meth:`Surface.set_device_offset`.

        .. function:: acquire(target, extents)

            :param Surface target:
                the rendering target surface
            :param RectangleInt extents:
                rectangular region of interest in pixels in sample space
            :rtype: Surface

            This function is called when a pattern is being rendered from. It
            should create a surface that provides the pixel data for the
            region of interest as defined by extents, though the surface
            itself does not have to be limited to that area. For convenience
            the surface should probably be of image type, created with
            :meth:`Surface.create_similar_image` for the target (which enables
            the number of copies to be reduced during transfer to the device).
            Another option, might be to return a similar surface to the target
            for explicit handling by the application of a set of cached
            sources on the device. The region of sample data provided should
            be defined using :meth:`Surface.set_device_offset` to specify the
            top-left corner of the sample data (along with width and height of
            the surface).

        .. function:: release(surface)

            :param Surface surface:
                the surface created during acquire

            This function is called when the pixel data is no longer being
            accessed by the pattern for the rendering operation.

        .. versionadded:: 1.15
        """

    def get_acquire(self) -> Tuple[Optional[_AcquireCallback], Optional[_ReleaseCallback]]:
        """
        :returns: a (acquire, release) tuple of callables or None as set
            through :meth:`set_acquire`

        Queries the current acquire and release callbacks.

        .. versionadded:: 1.15
        """

class RecordingSurface(Surface):
    """
    A *RecordingSurface* is a surface that records all drawing operations at the
    highest level of the surface backend interface, (that is, the level of paint,
    mask, stroke, fill, and show_text_glyphs). The recording surface can then be
    "replayed" against any target surface by using it as a source surface.

    If you want to replay a surface so that the results in target will be
    identical to the results that would have been obtained if the original
    operations applied to the recording surface had instead been applied to the
    target surface, you can use code like this::

        cr = cairo.Context(target)
        cr.set_source_surface(recording_surface, 0.0, 0.0)
        cr.paint()

    A *RecordingSurface* is logically unbounded, i.e. it has no implicit
    constraint on the size of the drawing surface. However, in practice this is
    rarely useful as you wish to replay against a particular target surface with
    known bounds. For this case, it is more efficient to specify the target
    extents to the recording surface upon creation.

    The recording phase of the recording surface is careful to snapshot all
    necessary objects (paths, patterns, etc.), in order to achieve accurate
    replay.

    .. versionadded:: 1.11.0
    """

    def __init__(self, content: Content, rectangle: Rectangle) -> None:
        """
        :param content: the content for the new  surface
        :param rectangle: or None to record unbounded operations.

        Creates a *RecordingSurface* which can be used to record all drawing
        operations at the highest level (that is, the level of paint, mask, stroke,
        fill and show_text_glyphs). The *RecordingSurface* can then be "replayed"
        against any target surface by using it as a source to drawing operations.

        The recording phase of the *RecordingSurface* is careful to snapshot all
        necessary objects (paths, patterns, etc.), in order to achieve accurate
        replay.

        .. versionadded:: 1.11.0
        """

    def ink_extents(self) -> Tuple[float, float, float, float]:
        """
        * x0: the x-coordinate of the top-left of the ink bounding box
        * y0: the y-coordinate of the top-left of the ink bounding box
        * width: the width of the ink bounding box
        * height: the height of the ink bounding box

        Measures the extents of the operations stored within the
        *RecordingSurface*. This is useful to compute the required size of an
        *ImageSurface* (or equivalent) into which to replay the full sequence of
        drawing operations.

        .. versionadded:: 1.11.0
        """

    def get_extents(self) -> Optional[Rectangle]:
        """
        :returns: a rectangle or :obj:`None` if the surface is unbounded.

        Get the extents of the recording-surface.

        .. versionadded:: 1.12.0
        """

class Region:
    """
    Region is a simple graphical data type representing an area of
    integer-aligned rectangles. They are often used on raster surfaces to track
    areas of interest, such as change or clip areas.

    .. versionadded:: 1.11.0
    """

    def __init__(self, rectangle: Union[RectangleInt, List[RectangleInt]]) -> None:
        """
        :param rectangle_int: a rectangle or a list of rectangle

        Allocates a new empty region object or a region object with the
        containing rectangle(s).
        """

    def copy(self) -> "Region":
        """
        :returns: A newly allocated :class:`Region`.

        Allocates a new *Region* object copying the area from original.
        """

    def get_extents(self) -> RectangleInt:
        """
        :returns: The bounding rectangle of region
        """

    def num_rectangles(self) -> int:
        """
        :returns: The number of rectangles contained in region
        """

    def get_rectangle(self, nth: int) -> RectangleInt:
        """
        :param nth: a number indicating which rectangle should be returned
        :returns: The *nth* rectangle from the region
        """

    def is_empty(self) -> bool:
        """
        :returns: Whether region is empty
        """

    def contains_point(self, x: int, y: int) -> bool:
        """
        :param x: The x coordinate of a point
        :param y: The y coordinate of a point
        :returns: Whether (x , y) is contained in the region
        """

    def contains_rectangle(self, rectangle: RectangleInt) -> RegionOverlap:
        """
        :param rectangle: a region
        :returns: region overlap

        Checks whether rectangle is inside, outside or partially contained in
        region
        """

    def equal(self, region: "Region") -> bool:
        """
        :param region: a region
        :returns: Whether both regions contained the same coverage
        """

    def translate(self, dx: int, dy: int) -> None:
        """
        :param dx: Amount to translate in the x direction
        :param dy: Amount to translate in the y direction

        Translates region by (dx , dy ).
        """

    def intersect(self, other: "Union[Region, RectangleInt]") -> "Region":
        """
        :param other: region or rectangle
        :returns: The intersection of the region and the passed region or
            rectangle
        """

    def subtract(self, other: "Union[Region, RectangleInt]") -> "Region":
        """
        :param other: region or rectangle
        :returns: The result of the subtraction of the region and the passed
            region or rectangle
        """

    def union(self, other: "Union[Region, RectangleInt]") -> "Region":
        """
        :param other: region or rectangle
        :returns: The union of the region and the passed region or rectangle
        """

    def xor(self, other: "Union[Region, RectangleInt]") -> "Region":
        """
        :param other: region or rectangle
        :returns: The exclusive difference of the region and the passed region
            or rectangle
        """

class ScriptDevice(Device):
    """
    .. versionadded:: 1.14
    """

    def __init__(self, fobj: Union[_FileLike, _PathLike]) -> None:
        """
        :param fobj: a filename or writable file object.

        Creates a output device for emitting the script, used when creating the
        individual surfaces.
        """

    def set_mode(self, mode: ScriptMode) -> None:
        """
        :param mode: the new mode

        Change the output mode of the script
        """

    def get_mode(self) -> ScriptMode:
        """
        :returns: the current output mode of the script

        Queries the script for its current output mode.
        """

    def write_comment(self, comment: str) -> None:
        """
        :param comment: the string to emit

        Emit a string verbatim into the script.
        """

    def from_recording_surface(self, recording_surface: RecordingSurface) -> None:
        """
        :param recording_surface:
            the recording surface to replay
        :raises cairo.Error:

        Converts the record operations in recording_surface into a script.
        """

class ScriptSurface(Surface):
    """
    The script surface provides the ability to render to a native script that
    matches the cairo drawing model. The scripts can be replayed using tools
    under the util/cairo-script directory, or with cairo-perf-trace.

    .. versionadded:: 1.14
    """

    def __init__(self, script: ScriptDevice, content: Content, width: float, height: float) -> None:
        """
        :param script: the script (output device)
        :param content: the content of the surface
        :param width: width in pixels
        :param height: height in pixels
        :raises cairo.Error:

        Create a new surface that will emit its rendering through ``script``.
        """

    @classmethod
    def create_for_target(cls, script: ScriptDevice, target: Surface) -> "ScriptSurface":
        """
        :param script: the script (output device)
        :param target: a target surface to wrap
        :raises cairo.Error:

        Create a proxy surface that will render to ``target`` and record the
        operations to ``device``.

        .. versionadded:: 1.14
        """

class Win32Surface(Surface):
    """
    The Microsoft Windows surface is used to render cairo graphics to Microsoft
    Windows windows, bitmaps, and printing device contexts.
    """

    def __init__(self, hdc: int) -> None:
        """
        :param hdc: the DC to create a surface for
        :type hdc: int

        Creates a cairo surface that targets the given DC. The DC will be
        queried for its initial clip extents, and this will be used as the size
        of the cairo surface. The resulting surface will always be of format
        cairo.FORMAT_RGB24, see :class:`cairo.Format`.
        """

class Win32PrintingSurface(Surface):
    """
    The Win32PrintingSurface is a multi-page vector surface type.
    """

    def __init__(self, hdc: int) -> None:
        """
        :param hdc: the DC to create a surface for
        :returns: the newly created surface

        Creates a cairo surface that targets the given DC. The DC will be queried
        for its initial clip extents, and this will be used as the size of the
        cairo surface. The DC should be a printing DC; antialiasing will be
        ignored, and GDI will be used as much as possible to draw to the surface.

        The returned surface will be wrapped using the paginated surface to provide
        correct complex rendering behaviour; :meth:`cairo.Surface.show_page` and
        associated methods must be used for correct output.
        """

class SolidPattern(Pattern):

    def __init__(self, red: float, green: float, blue: float, alpha: float=1.0) -> None:
        """
        :param red: red component of the color
        :param green: green component of the color
        :param blue: blue component of the color
        :param alpha: alpha component of the color

        Creates a new *SolidPattern* corresponding to a translucent color. The
        color components are floating point numbers in the range 0 to 1. If the
        values passed in are outside that range, they will be clamped.
        """

    def get_rgba(self) -> Tuple[float, float, float, float]:
        """
        :returns: (red, green, blue, alpha) a tuple of float

        Gets the solid color for a *SolidPattern*.

        .. versionadded:: 1.4
        """

class SurfaceObserverMode(_IntEnum):
    """
    Whether operations should be recorded.

    .. versionadded:: 1.14
    """

    NORMAL: "SurfaceObserverMode" = ...
    """no recording is done"""

    RECORD_OPERATIONS: "SurfaceObserverMode" = ...
    """operations are recorded"""

class TeeSurface(Surface):
    """
    This surface supports redirecting all its input to multiple surfaces.

    .. versionadded:: 1.14
    """

    def __init__(self, master: Surface) -> None: ...

    def add(self, target: Surface) -> None:
        """
        :param target:
        :raises cairo.Error:

        Add the surface

        .. versionadded:: 1.14
        """

    def remove(self, target: Surface) -> None:
        """
        :param target:
        :raises cairo.Error:

        Remove the surface

        .. versionadded:: 1.14
        """

    def index(self, index: int) -> Surface:
        """
        :param index:
        :raises cairo.Error:

        Returns the surface at index ``index``. The master surface is
        at index 0.

        .. versionadded:: 1.14
        """

class ToyFontFace(FontFace):
    """
    The *cairo.ToyFontFace* class can be used instead of :meth:`Context.select_font_face` to create a toy font independently of a context.

    .. versionadded:: 1.8.4
    """

    def __init__(self, family: str, slant: FontSlant=..., weight: FontWeight=...) -> None:
        """
        :param family: a font family name
        :param slant: the font slant of the font,
            defaults to :attr:`cairo.FontSlant.NORMAL`.
        :param weight: the font weight of the font,
            defaults to :attr:`cairo.FontWeight.NORMAL`.

        Creates a *ToyFontFace* from a triplet of family, slant, and weight. These
        font faces are used in implementation of the the "toy" font API.

        If family is the zero-length string "", the platform-specific default
        family is assumed. The default family then can be queried using
        :meth:`.get_family`.

        The :meth:`Context.select_font_face` method uses this to create font
        faces. See that function for limitations of toy font faces.
        """

    def get_family(self) -> str:
        """
            :returns: the family name of a toy font

            .. versionadded:: 1.8.4
        """

    def get_slant(self) -> FontSlant:
        """
            :returns: the font slant value

            .. versionadded:: 1.8.4
        """

    def get_weight(self) -> FontWeight:
        """
            :returns: the font weight value

            .. versionadded:: 1.8.4
        """

class XCBSurface(Surface):
    """
    The XCB surface is used to render cairo graphics to X Window System windows
    and pixmaps using the XCB library.

    Note that the XCB surface automatically takes advantage of the X render
    extension if it is available.
    """

    def __init__(self, connection: Any, drawable: Any, visualtype: Any, width: int, height: int) -> None:
        """
        :param connection: an XCB connection
        :param drawable: a X drawable
        :param visualtype: a X visualtype
        :param width: The surface width
        :param height: The surface height

        Creates a cairo surface that targets the given drawable (pixmap or window).

        .. note:: This type isn't implemented. Please file a bug if you need it.
        """

    def set_size(self, width: int, height: int) -> None:
        """
        :param width: The width of the surface
        :param height: The height of the surface

        Informs cairo of the new size of the X Drawable underlying the surface.
        For a surface created for a Window (rather than a Pixmap), this function
        must be called each time the size of the window changes. (For a
        subwindow, you are normally resizing the window yourself, but for a
        toplevel window, it is necessary to listen for ConfigureNotify events.)

        A Pixmap can never change size, so it is never necessary to call this
        function on a surface created for a Pixmap.
        """

class XlibSurface(Surface):
    """
    The XLib surface is used to render cairo graphics to X Window System windows
    and pixmaps using the XLib library.

    Note that the XLib surface automatically takes advantage of X render
    extension if it is available.

    .. note:: *XlibSurface* cannot be instantiated directly because Python
      interaction with Xlib would require open source Python bindings to Xlib
      which provided a C API.
      However, an *XlibSurface* instance can be returned from a function call
      when using pygtk http://www.pygtk.org/.
    """

    def get_depth(self) -> int:
        """
        :returns: the number of bits used to represent each pixel value.

        .. versionadded:: 1.2
        """

    def get_height(self) -> int:
        """
        :returns: the height of the X Drawable underlying the surface in pixels.

        .. versionadded:: 1.2
        """

    def get_width(self) -> int:
        """
        :returns: the width of the X Drawable underlying the surface in pixels.

        .. versionadded:: 1.2
        """

def get_include() -> str:
    """
    :returns: a path to the directory containing the C header files

    Gives the include path which should be passed to the compiler.

    .. versionadded:: 1.16.0
    """

MIME_TYPE_JP2: str = ...
"""
The Joint Photographic Experts Group (JPEG) 2000 image coding standard
(ISO/IEC 15444-1).

.. versionadded:: 1.12.0
"""

MIME_TYPE_JPEG: str = ...
"""
The Joint Photographic Experts Group (JPEG) image coding standard (ISO/IEC
10918-1).

.. versionadded:: 1.12.0
"""

MIME_TYPE_PNG: str = ...
"""
The Portable Network Graphics image file format (ISO/IEC 15948).

.. versionadded:: 1.12.0
"""

MIME_TYPE_URI: str = ...
"""
URI for an image file (unofficial MIME type).

.. versionadded:: 1.12.0
"""

MIME_TYPE_UNIQUE_ID: str = ...
"""
Unique identifier for a surface (cairo specific MIME type). All surfaces
with the same unique identifier will only be embedded once.

.. versionadded:: 1.12.0
"""

MIME_TYPE_CCITT_FAX: str = ...
"""
Group 3 or Group 4 CCITT facsimile encoding (International
Telecommunication Union, Recommendations T.4 and T.6.)

.. versionadded:: 1.18.0 Only available with cairo 1.15.10+
"""

MIME_TYPE_CCITT_FAX_PARAMS: str = ...
"""
Decode parameters for Group 3 or Group 4 CCITT facsimile encoding. See
`CCITT Fax Images
<https://cairographics.org/manual/cairo-PDF-Surfaces.html#ccitt>`__.

.. versionadded:: 1.18.0 Only available with cairo 1.15.10+
"""

MIME_TYPE_EPS: str = ...
"""
Encapsulated PostScript file. Encapsulated PostScript File Format
Specification

.. versionadded:: 1.18.0 Only available with cairo 1.15.10+
"""

MIME_TYPE_EPS_PARAMS: str = ...
"""
Embedding parameters Encapsulated PostScript data. See Embedding EPS files.

.. versionadded:: 1.18.0 Only available with cairo 1.15.10+
"""

MIME_TYPE_JBIG2: str = ...
"""
Joint Bi-level Image Experts Group image coding standard (ISO/IEC 11544).

.. versionadded:: 1.18.0
"""

MIME_TYPE_JBIG2_GLOBAL: str = ...
"""
Joint Bi-level Image Experts Group image coding standard (ISO/IEC 11544)
global segment.

.. versionadded:: 1.18.0
"""

MIME_TYPE_JBIG2_GLOBAL_ID: str = ...
"""
An unique identifier shared by a JBIG2 global segment and all JBIG2 images
that depend on the global segment.

.. versionadded:: 1.18.0
"""

TAG_DEST: str = ...
"""
Create a destination for a hyperlink. Destination tag attributes are
detailed at Destinations.

.. versionadded:: 1.18.0 Only available with cairo 1.15.10+
"""

TAG_LINK: str = ...
"""
Create hyperlink. Link tag attributes are detailed at Links.

.. versionadded:: 1.18.0 Only available with cairo 1.15.10+
"""

TAG_CONTENT: str = ...
"""
Create a content tag.

.. versionadded:: 1.25.0 Only available with cairo 1.18.0+
"""

TAG_CONTENT_REF: str = ...
"""
Create a content reference tag.

.. versionadded:: 1.25.0 Only available with cairo 1.18.0+
"""

CAPI: Any = ...

ANTIALIAS_BEST = Antialias.BEST
ANTIALIAS_DEFAULT = Antialias.DEFAULT
ANTIALIAS_FAST = Antialias.FAST
ANTIALIAS_GOOD = Antialias.GOOD
ANTIALIAS_GRAY = Antialias.GRAY
ANTIALIAS_NONE = Antialias.NONE
ANTIALIAS_SUBPIXEL = Antialias.SUBPIXEL
CONTENT_ALPHA = Content.ALPHA
CONTENT_COLOR = Content.COLOR
CONTENT_COLOR_ALPHA = Content.COLOR_ALPHA
EXTEND_NONE = Extend.NONE
EXTEND_PAD = Extend.PAD
EXTEND_REFLECT = Extend.REFLECT
EXTEND_REPEAT = Extend.REPEAT
FILL_RULE_EVEN_ODD = FillRule.EVEN_ODD
FILL_RULE_WINDING = FillRule.WINDING
FILTER_BEST = Filter.BEST
FILTER_BILINEAR = Filter.BILINEAR
FILTER_FAST = Filter.FAST
FILTER_GAUSSIAN = Filter.GAUSSIAN
FILTER_GOOD = Filter.GOOD
FILTER_NEAREST = Filter.NEAREST
FONT_SLANT_ITALIC = FontSlant.ITALIC
FONT_SLANT_NORMAL = FontSlant.NORMAL
FONT_SLANT_OBLIQUE = FontSlant.OBLIQUE
FONT_WEIGHT_BOLD = FontWeight.BOLD
FONT_WEIGHT_NORMAL = FontWeight.NORMAL
FORMAT_A1 = Format.A1
FORMAT_A8 = Format.A8
FORMAT_ARGB32 = Format.ARGB32
FORMAT_INVALID = Format.INVALID
FORMAT_RGB16_565 = Format.RGB16_565
FORMAT_RGB24 = Format.RGB24
FORMAT_RGB30 = Format.RGB30
FORMAT_RGB96F = Format.RGB96F
FORMAT_RGBA128F = Format.RGBA128F
HINT_METRICS_DEFAULT = HintMetrics.DEFAULT
HINT_METRICS_OFF = HintMetrics.OFF
HINT_METRICS_ON = HintMetrics.ON
HINT_STYLE_DEFAULT = HintStyle.DEFAULT
HINT_STYLE_FULL = HintStyle.FULL
HINT_STYLE_MEDIUM = HintStyle.MEDIUM
HINT_STYLE_NONE = HintStyle.NONE
HINT_STYLE_SLIGHT = HintStyle.SLIGHT
LINE_CAP_BUTT = LineCap.BUTT
LINE_CAP_ROUND = LineCap.ROUND
LINE_CAP_SQUARE = LineCap.SQUARE
LINE_JOIN_BEVEL = LineJoin.BEVEL
LINE_JOIN_MITER = LineJoin.MITER
LINE_JOIN_ROUND = LineJoin.ROUND
OPERATOR_ADD = Operator.ADD
OPERATOR_ATOP = Operator.ATOP
OPERATOR_CLEAR = Operator.CLEAR
OPERATOR_COLOR_BURN = Operator.COLOR_BURN
OPERATOR_COLOR_DODGE = Operator.COLOR_DODGE
OPERATOR_DARKEN = Operator.DARKEN
OPERATOR_DEST = Operator.DEST
OPERATOR_DEST_ATOP = Operator.DEST_ATOP
OPERATOR_DEST_IN = Operator.DEST_IN
OPERATOR_DEST_OUT = Operator.DEST_OUT
OPERATOR_DEST_OVER = Operator.DEST_OVER
OPERATOR_DIFFERENCE = Operator.DIFFERENCE
OPERATOR_EXCLUSION = Operator.EXCLUSION
OPERATOR_HARD_LIGHT = Operator.HARD_LIGHT
OPERATOR_HSL_COLOR = Operator.HSL_COLOR
OPERATOR_HSL_HUE = Operator.HSL_HUE
OPERATOR_HSL_LUMINOSITY = Operator.HSL_LUMINOSITY
OPERATOR_HSL_SATURATION = Operator.HSL_SATURATION
OPERATOR_IN = Operator.IN
OPERATOR_LIGHTEN = Operator.LIGHTEN
OPERATOR_MULTIPLY = Operator.MULTIPLY
OPERATOR_OUT = Operator.OUT
OPERATOR_OVER = Operator.OVER
OPERATOR_OVERLAY = Operator.OVERLAY
OPERATOR_SATURATE = Operator.SATURATE
OPERATOR_SCREEN = Operator.SCREEN
OPERATOR_SOFT_LIGHT = Operator.SOFT_LIGHT
OPERATOR_SOURCE = Operator.SOURCE
OPERATOR_XOR = Operator.XOR
PATH_CLOSE_PATH = PathDataType.CLOSE_PATH
PATH_CURVE_TO = PathDataType.CURVE_TO
PATH_LINE_TO = PathDataType.LINE_TO
PATH_MOVE_TO = PathDataType.MOVE_TO
PDF_VERSION_1_4 = PDFVersion.VERSION_1_4
PDF_VERSION_1_5 = PDFVersion.VERSION_1_5
PDF_VERSION_1_6 = PDFVersion.VERSION_1_6
PDF_VERSION_1_7 = PDFVersion.VERSION_1_7
PS_LEVEL_2 = PSLevel.LEVEL_2
PS_LEVEL_3 = PSLevel.LEVEL_3
REGION_OVERLAP_IN = RegionOverlap.IN
REGION_OVERLAP_OUT = RegionOverlap.OUT
REGION_OVERLAP_PART = RegionOverlap.PART
SCRIPT_MODE_ASCII = ScriptMode.ASCII
SCRIPT_MODE_BINARY = ScriptMode.BINARY
STATUS_CLIP_NOT_REPRESENTABLE = Status.CLIP_NOT_REPRESENTABLE
STATUS_DEVICE_ERROR = Status.DEVICE_ERROR
STATUS_DEVICE_FINISHED = Status.DEVICE_FINISHED
STATUS_DEVICE_TYPE_MISMATCH = Status.DEVICE_TYPE_MISMATCH
STATUS_FILE_NOT_FOUND = Status.FILE_NOT_FOUND
STATUS_FONT_TYPE_MISMATCH = Status.FONT_TYPE_MISMATCH
STATUS_INVALID_CLUSTERS = Status.INVALID_CLUSTERS
STATUS_INVALID_CONTENT = Status.INVALID_CONTENT
STATUS_INVALID_DASH = Status.INVALID_DASH
STATUS_INVALID_DSC_COMMENT = Status.INVALID_DSC_COMMENT
STATUS_INVALID_FORMAT = Status.INVALID_FORMAT
STATUS_INVALID_INDEX = Status.INVALID_INDEX
STATUS_INVALID_MATRIX = Status.INVALID_MATRIX
STATUS_INVALID_MESH_CONSTRUCTION = Status.INVALID_MESH_CONSTRUCTION
STATUS_INVALID_PATH_DATA = Status.INVALID_PATH_DATA
STATUS_INVALID_POP_GROUP = Status.INVALID_POP_GROUP
STATUS_INVALID_RESTORE = Status.INVALID_RESTORE
STATUS_INVALID_SIZE = Status.INVALID_SIZE
STATUS_INVALID_SLANT = Status.INVALID_SLANT
STATUS_INVALID_STATUS = Status.INVALID_STATUS
STATUS_INVALID_STRIDE = Status.INVALID_STRIDE
STATUS_INVALID_STRING = Status.INVALID_STRING
STATUS_INVALID_VISUAL = Status.INVALID_VISUAL
STATUS_INVALID_WEIGHT = Status.INVALID_WEIGHT
STATUS_JBIG2_GLOBAL_MISSING = Status.JBIG2_GLOBAL_MISSING
STATUS_LAST_STATUS = Status.LAST_STATUS
STATUS_NEGATIVE_COUNT = Status.NEGATIVE_COUNT
STATUS_NO_CURRENT_POINT = Status.NO_CURRENT_POINT
STATUS_NO_MEMORY = Status.NO_MEMORY
STATUS_NULL_POINTER = Status.NULL_POINTER
STATUS_PATTERN_TYPE_MISMATCH = Status.PATTERN_TYPE_MISMATCH
STATUS_READ_ERROR = Status.READ_ERROR
STATUS_SUCCESS = Status.SUCCESS
STATUS_SURFACE_FINISHED = Status.SURFACE_FINISHED
STATUS_SURFACE_TYPE_MISMATCH = Status.SURFACE_TYPE_MISMATCH
STATUS_TEMP_FILE_ERROR = Status.TEMP_FILE_ERROR
STATUS_USER_FONT_ERROR = Status.USER_FONT_ERROR
STATUS_USER_FONT_IMMUTABLE = Status.USER_FONT_IMMUTABLE
STATUS_USER_FONT_NOT_IMPLEMENTED = Status.USER_FONT_NOT_IMPLEMENTED
STATUS_WRITE_ERROR = Status.WRITE_ERROR
SUBPIXEL_ORDER_BGR = SubpixelOrder.BGR
SUBPIXEL_ORDER_DEFAULT = SubpixelOrder.DEFAULT
SUBPIXEL_ORDER_RGB = SubpixelOrder.RGB
SUBPIXEL_ORDER_VBGR = SubpixelOrder. VBGR
SUBPIXEL_ORDER_VRGB = SubpixelOrder.VRGB
SURFACE_OBSERVER_NORMAL = SurfaceObserverMode.NORMAL
SURFACE_OBSERVER_RECORD_OPERATIONS = SurfaceObserverMode.RECORD_OPERATIONS
SVG_VERSION_1_1 = SVGVersion.VERSION_1_1
SVG_VERSION_1_2 = SVGVersion.VERSION_1_2
TEXT_CLUSTER_FLAG_BACKWARD = TextClusterFlags.BACKWARD
PDF_METADATA_TITLE = PDFMetadata.TITLE
PDF_METADATA_AUTHOR = PDFMetadata.AUTHOR
PDF_METADATA_SUBJECT = PDFMetadata.SUBJECT
PDF_METADATA_KEYWORDS = PDFMetadata.KEYWORDS
PDF_METADATA_CREATOR = PDFMetadata.CREATOR
PDF_METADATA_CREATE_DATE = PDFMetadata.CREATE_DATE
PDF_METADATA_MOD_DATE = PDFMetadata.MOD_DATE
SVG_UNIT_USER = SVGUnit.USER
SVG_UNIT_EM = SVGUnit.EM
SVG_UNIT_EX = SVGUnit.EX
SVG_UNIT_PX = SVGUnit.PX
SVG_UNIT_IN = SVGUnit.IN
SVG_UNIT_CM = SVGUnit.CM
SVG_UNIT_MM = SVGUnit.MM
SVG_UNIT_PT = SVGUnit.PT
SVG_UNIT_PC = SVGUnit.PC
SVG_UNIT_PERCENT = SVGUnit.PERCENT
STATUS_TAG_ERROR = Status.TAG_ERROR
STATUS_FREETYPE_ERROR = Status.FREETYPE_ERROR
STATUS_WIN32_GDI_ERROR = Status.WIN32_GDI_ERROR
STATUS_PNG_ERROR = Status.PNG_ERROR
STATUS_DWRITE_ERROR = Status.DWRITE_ERROR
STATUS_SVG_FONT_ERROR = Status.SVG_FONT_ERROR
PDF_OUTLINE_FLAG_OPEN = PDFOutlineFlags.OPEN
PDF_OUTLINE_FLAG_BOLD = PDFOutlineFlags.BOLD
PDF_OUTLINE_FLAG_ITALIC = PDFOutlineFlags.ITALIC
COLOR_MODE_DEFAULT = ColorMode.DEFAULT
COLOR_MODE_NO_COLOR = ColorMode.NO_COLOR
COLOR_MODE_COLOR = ColorMode.COLOR
DITHER_NONE = Dither.NONE
DITHER_DEFAULT = Dither.DEFAULT
DITHER_FAST = Dither.FAST
DITHER_GOOD = Dither.GOOD
DITHER_BEST = Dither.BEST