New methods added:

  cairo_in_clip
  cairo_surface_create_for_rectangle
  cairo_pdf_surface_restrict_to_version
  cairo_pdf_version_to_string

New constants added:
  cairo.PDF_VERSION_1_4
  cairo.PDF_VERSION_1_5

6 files changed, 167 insertions, 9 deletions

diff --git a/doc/reference/constants.rst b/doc/reference/constants.rst
index 19c0993..a1fef62 100644
--- a/doc/reference/constants.rst
+++ b/doc/reference/constants.rst
@@ -483,6 +483,23 @@ represented as a :class:`Path`.
    A close-path operation
 
 
+.. _constants_PDF_VERSION:
+
+cairo.PDF_VERSION
+-----------------
+These constants are used to describe the version number of the PDF
+specification that a generated PDF file will conform to. Note: the constants
+are only defined when cairo has been compiled with PDF support enabled.
+
+.. data:: CAIRO_PDF_VERSION_1_4
+
+   The version 1.4 of the PDF specification.
+
+.. data:: CAIRO_PDF_VERSION_1_5
+
+   The version 1.5 of the PDF specification.
+
+
 .. _constants_PS_LEVEL:
 
 cairo.PS_LEVEL
diff --git a/doc/reference/context.rst b/doc/reference/context.rst
index 4a2f17f..9e48113 100644
--- a/doc/reference/context.rst
+++ b/doc/reference/context.rst
@@ -557,6 +557,20 @@ safely be changed, without loosing the current state. Use
       axes will be aligned and one user-space unit will transform to one
       device-space unit.
 
+   .. method:: in_clip(x, y)
+
+      :param x: X coordinate of the point to test
+      :type x: float
+      :param y: Y coordinate of the point to test
+      :type y: float
+      :returns: True iff 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:`Context.paint` operation.
+
+      See :meth:`Context.clip`, :meth:`Context.clip_preserve`.
+
+      .. versionadded:: 1.10.2
+
    .. method:: in_fill(x, y)
 
       :param x: X coordinate of the point to test
diff --git a/doc/reference/surfaces.rst b/doc/reference/surfaces.rst
index 949b05e..8a0e13d 100644
--- a/doc/reference/surfaces.rst
+++ b/doc/reference/surfaces.rst
@@ -80,6 +80,36 @@ class Surface()
       Initially the surface contents are all 0 (transparent if contents have
       transparency, black otherwise.)
 
+   .. method:: create_for_rectangle(x, y, width, height)
+
+      :param x: the x-origin of the sub-surface from the top-left of the
+        target surface (in device-space units)
+      :type x: float
+      :param y: the y-origin of the sub-surface from the top-left of the
+        target surface (in device-space units)
+      :type y: float
+      :param width: width of the sub-surface, (in device-space units)
+      :type width: float
+      :param height: height of the sub-surface (in device-space units)
+      :type width: float
+
+      :returns: a newly allocated *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.10.2
+
    .. method:: finish()
 
       This method finishes the *Surface* and drops all references to external
@@ -354,6 +384,33 @@ multi-page vector surface backend.
 
    .. versionadded:: 1.2
 
+   .. staticmethod:: pdf_version_to_string(level)
+
+      :param level: a :ref:`PDF_VERSION <constants_PDF_VERSION>`
+      :returns: the string associated to given version.
+      :rtype: str
+      :raises: :exc:`cairo.Error` if *version* isn't valid.
+
+      Get the string representation of the given *version*. See
+      :meth:`.pdf_get_versions` for a way to get the list of valid level
+      ids.
+
+      .. versionadded:: 1.10.2
+
+   .. method:: restrict_to_version(version)
+
+      :param version: a :ref:`PDF_VERSION <constants_PDF_VERSION>`
+
+      Restricts the generated PDF file to *version*. See
+      :meth:`.pdf_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.10.2
+
    .. method:: set_size()
 
       :param width_in_points: new surface width, in points
diff --git a/src/cairomodule.c b/src/cairomodule.c
index 886c6d5..3a15d44 100644
--- a/src/cairomodule.c
+++ b/src/cairomodule.c
@@ -24,6 +24,11 @@
 #include "config.h"
 #include "private.h"
 
+/* to read CAIRO_PDF_VERSION_* constants */
+#ifdef CAIRO_HAS_PDF_SURFACE
+#  include <cairo-pdf.h>
+#endif
+
 /* to read CAIRO_PS_LEVEL_* constants */
 #ifdef CAIRO_HAS_PS_SURFACE
 #  include <cairo-ps.h>
@@ -535,6 +540,11 @@ PyInit__cairo(void)
   CONSTANT(PATH_CURVE_TO);
   CONSTANT(PATH_CLOSE_PATH);
 
+#ifdef CAIRO_HAS_PDF_SURFACE
+  CONSTANT(PDF_VERSION_1_4);
+  CONSTANT(PDF_VERSION_1_5);
+#endif
+
 #ifdef CAIRO_HAS_PS_SURFACE
   CONSTANT(PS_LEVEL_2);
   CONSTANT(PS_LEVEL_3);
diff --git a/src/context.c b/src/context.c
index 9bee5d4..984cdfc 100644
--- a/src/context.c
+++ b/src/context.c
@@ -530,6 +530,20 @@ pycairo_identity_matrix (PycairoContext *o) {
 }
 
 static PyObject *
+pycairo_in_clip (PycairoContext *o, PyObject *args) {
+  double x, y;
+  PyObject *result;
+
+  if (!PyArg_ParseTuple (args, "dd:Context.in_clip", &x, &y))
+    return NULL;
+
+  result = cairo_in_clip (o->ctx, x, y) ? Py_True : Py_False;
+  RETURN_NULL_IF_CAIRO_CONTEXT_ERROR(o->ctx);
+  Py_INCREF(result);
+  return result;
+}
+
+static PyObject *
 pycairo_in_fill (PycairoContext *o, PyObject *args) {
   double x, y;
   PyObject *result;
@@ -1266,6 +1280,7 @@ static PyMethodDef pycairo_methods[] = {
   {"glyph_path",      (PyCFunction)pycairo_glyph_path,       METH_VARARGS},
   {"has_current_point",(PyCFunction)pycairo_has_current_point, METH_NOARGS},
   {"identity_matrix", (PyCFunction)pycairo_identity_matrix,  METH_NOARGS},
+  {"in_clip",         (PyCFunction)pycairo_in_clip,          METH_VARARGS},
   {"in_fill",         (PyCFunction)pycairo_in_fill,          METH_VARARGS},
   {"in_stroke",       (PyCFunction)pycairo_in_stroke,        METH_VARARGS},
   {"line_to",         (PyCFunction)pycairo_line_to,          METH_VARARGS},
diff --git a/src/surface.c b/src/surface.c
index 4701a4b..1589a70 100644
--- a/src/surface.c
+++ b/src/surface.c
@@ -202,6 +202,20 @@ surface_create_similar (PycairoSurface *o, PyObject *args) {
 }
 
 static PyObject *
+surface_create_for_rectangle (PycairoSurface *o, PyObject *args) {
+  double x, y, width, height;
+
+  if (!PyArg_ParseTuple (args, "dddd:Surface.create_for_rectangle",
+			 &x, &y, &width, &height))
+
+    return NULL;
+  return PycairoSurface_FromSurface (
+	     cairo_surface_create_for_rectangle (o->surface,
+						 x, y, width, height),
+	     NULL);
+}
+
+static PyObject *
 surface_finish (PycairoSurface *o) {
   cairo_surface_finish (o->surface);
   Py_CLEAR(o->base);
@@ -352,6 +366,8 @@ static PyMethodDef surface_methods[] = {
    */
   {"copy_page",      (PyCFunction)surface_copy_page,          METH_NOARGS},
   {"create_similar", (PyCFunction)surface_create_similar,     METH_VARARGS},
+  {"create_for_rectangle", (PyCFunction)surface_create_for_rectangle,
+                                                              METH_VARARGS},
   {"finish",         (PyCFunction)surface_finish,             METH_NOARGS},
   {"flush",          (PyCFunction)surface_flush,              METH_NOARGS},
   {"get_content",    (PyCFunction)surface_get_content,        METH_NOARGS},
@@ -742,6 +758,17 @@ pdf_surface_new (PyTypeObject *type, PyObject *args, PyObject *kwds) {
 }
 
 static PyObject *
+pdf_surface_restrict_to_version (PycairoPDFSurface *o, PyObject *args) {
+  int version;
+
+  if (!PyArg_ParseTuple(args, "i:PDFSurface.restrict_to_version", &version))
+    return NULL;
+  cairo_pdf_surface_restrict_to_version (o->surface, version);
+  RETURN_NULL_IF_CAIRO_SURFACE_ERROR(o->surface);
+  Py_RETURN_NONE;
+}
+
+static PyObject *
 pdf_surface_set_size (PycairoPDFSurface *o, PyObject *args) {
   double width_in_points, height_in_points;
 
@@ -753,8 +780,28 @@ pdf_surface_set_size (PycairoPDFSurface *o, PyObject *args) {
   Py_RETURN_NONE;
 }
 
+/* METH_STATIC */
+static PyObject *
+pdf_surface_pdf_version_to_string (PyObject *self, PyObject *args) {
+  int version;
+  if (!PyArg_ParseTuple(args, "i:pdf_version_to_string", &version))
+    return NULL;
+  const char *s = cairo_pdf_version_to_string (version);
+  if (s == NULL){
+    PyErr_SetString(CairoError, "pdf_version_to_string: "
+		    "invalid level argument");
+    return NULL;
+  }
+  return PyUnicode_DecodeASCII(s, strlen(s), NULL);
+}
+
 static PyMethodDef pdf_surface_methods[] = {
-  {"set_size", (PyCFunction)pdf_surface_set_size,    METH_VARARGS },
+  {"restrict_to_version", (PyCFunction)pdf_surface_restrict_to_version,
+                                                              METH_VARARGS },
+  {"set_size", (PyCFunction)pdf_surface_set_size,             METH_VARARGS },
+  /* pdf_get_levels - not implemented yet */
+  {"pdf_version_to_string", (PyCFunction)pdf_surface_pdf_version_to_string,
+                                                 METH_VARARGS | METH_STATIC},
   {NULL, NULL, 0, NULL},
 };
 
@@ -902,11 +949,9 @@ ps_surface_ps_level_to_string (PyObject *self, PyObject *args) {
     return NULL;
   const char *s = cairo_ps_level_to_string (level);
   if (s == NULL){
-    PyErr_SetString(CairoError, "ps_level_to_string: "
-		    "invalid level argument");
+    PyErr_SetString(CairoError, "ps_level_to_string: invalid level argument");
     return NULL;
   }
-  //return PyUnicode_FromString(s);
   return PyUnicode_DecodeASCII(s, strlen(s), NULL);
 }
 
@@ -944,16 +989,16 @@ ps_surface_set_size (PycairoPSSurface *o, PyObject *args) {
 }
 
 static PyMethodDef ps_surface_methods[] = {
-  {"dsc_begin_page_setup",
-   (PyCFunction)ps_surface_dsc_begin_page_setup, METH_NOARGS },
+  {"dsc_begin_page_setup", (PyCFunction)ps_surface_dsc_begin_page_setup,
+                                                               METH_NOARGS },
   {"dsc_begin_setup", (PyCFunction)ps_surface_dsc_begin_setup, METH_NOARGS },
   {"dsc_comment", (PyCFunction)ps_surface_dsc_comment,        METH_VARARGS },
   {"get_eps", (PyCFunction)ps_surface_get_eps,                 METH_NOARGS },
-  /* ps_get_levels - not implemented yet*/
+  /* ps_get_levels - not implemented yet */
   {"ps_level_to_string", (PyCFunction)ps_surface_ps_level_to_string,
-   METH_VARARGS | METH_STATIC},
+                                                 METH_VARARGS | METH_STATIC},
   {"restrict_to_level", (PyCFunction)ps_surface_restrict_to_level,
-   METH_VARARGS },
+                                                              METH_VARARGS },
   {"set_eps", (PyCFunction)ps_surface_set_eps,                METH_VARARGS },
   {"set_size", (PyCFunction)ps_surface_set_size,              METH_VARARGS },
   {NULL, NULL, 0, NULL},