Make sure only one cairo binding is ever used; fix docs.

138ba5850d184a0cd080bb6c8bc2cf1a2f9d0516
commit 138ba5850d184a0cd080bb6c8bc2cf1a2f9d0516
diff --git a/lib/matplotlib/backends/backend_cairo.py b/lib/matplotlib/backends/backend_cairo.py
@@ -18,26 +18,30 @@
 
 import numpy as np
 
-try:
-    import cairocffi as cairo
-except ImportError:
+# In order to make it possible to pick the binding, use whichever has already
+# been imported, if any.  (The intermediate call to iter is just to placate
+# Python2.)
+cairo = next(
+    (mod for mod in (
+        sys.modules.get(name) for name in ["cairocffi", "cairo"]) if mod),
+    None)
+if cairo is None:
     try:
-        import cairo
+        import cairocffi as cairo
     except ImportError:
-        raise ImportError("Cairo backend requires that cairocffi or pycairo "
-                          "is installed.")
-    else:
-        HAS_CAIRO_CFFI = False
-else:
-    HAS_CAIRO_CFFI = True
-
-_version_required = (1, 2, 0)
-if cairo.version_info < _version_required:
-    raise ImportError("Pycairo %d.%d.%d is installed\n"
-                      "Pycairo %d.%d.%d or later is required"
-                      % (cairo.version_info + _version_required))
+        try:
+            import cairo
+        except ImportError:
+            raise ImportError(
+                "The cairo backend requires cairocffi or pycairo")
+# cairocffi can install itself as cairo (`install_as_pycairo`) -- don't get
+# fooled!
+HAS_CAIRO_CFFI = cairo.__name__ == "cairocffi"
+
+if cairo.version_info < (1, 2, 0):
+    raise ImportError("cairo {} is installed; "
+                      "cairo>=1.2.0 is required".format(cairo.version))
 backend_version = cairo.version
-del _version_required
 
 from matplotlib.backend_bases import (
     _Backend, FigureCanvasBase, FigureManagerBase, GraphicsContextBase,

diff --git a/tutorials/introductory/usage.py b/tutorials/introductory/usage.py
@@ -432,23 +432,23 @@ def my_plotter(ax, data1, data2, param_dict):
 #           ``%matplotlib notebook``.
 # WebAgg    On ``show()`` will start a tornado server with an interactive
 #           figure.
-# Qt5Cairo  Cairo rendering in a :term:`Qt5` canvas (requires PyQt5_ and
-#           cairocffi_).
+# Qt5Cairo  Cairo rendering in a :term:`Qt5` canvas (requires PyQt5_, and
+#           pycairo_ or cairocffi_).
 # GTK3Cairo Cairo rendering to a :term:`GTK` 3.x canvas (requires PyGObject_,
 #           and pycairo_ or cairocffi_).
 # Qt4Agg    Agg rendering to a :term:`Qt4` canvas (requires PyQt4_ or
 #           ``pyside``).  This backend can be activated in IPython with
 #           ``%matplotlib qt4``.
-# Qt4Cairo  Cairo rendering in a :term:`Qt5` canvas (requires PyQt5_ and
-#           cairocffi_).
+# Qt4Cairo  Cairo rendering in a :term:`Qt4` canvas (requires PyQt4_, and
+#           pycairo_ or cairocffi_).
 # GTKAgg    Agg rendering to a :term:`GTK` 2.x canvas (requires PyGTK_, and
 #           pycairo_ or cairocffi_; Python2 only).  This backend can be
 #           activated in IPython with ``%matplotlib gtk``.
 # GTKCairo  Cairo rendering to a :term:`GTK` 2.x canvas (requires PyGTK_,
 #           and pycairo_ or cairocffi_; Python2 only).
 # WXAgg     Agg rendering to a :term:`wxWidgets` canvas (requires wxPython_;
 #           v4.0 (in beta) is required for Python3). This backend can be
-#           activated in IPython with ``%matplotlib wx``.
+#           activated in IPython with ``%matplotlib wx``.#
 # ========= ================================================================
 #
 # .. _`Anti-Grain Geometry`: http://antigrain.com/