nbconvert.utils.pandoc:

 - reduce code duplication
 - remove obscure parameters from pandoc_available
 - use find_cmd to locate binaries
 - group runtime cached values in a private dicitonnary (easier to manipulate)

Add pandoc unittests.

IPython/nbconvert/tests/test_pandoc.py

@@ -0,0 +1,65 b''
+"""Test Pandoc module"""
+
+#-----------------------------------------------------------------------------
+#  Copyright (C) 2013 The IPython Development Team
+#
+#  Distributed under the terms of the BSD License.  The full license is in
+#  the file COPYING, distributed as part of this software.
+#-----------------------------------------------------------------------------
+
+#-----------------------------------------------------------------------------
+# Imports
+#-----------------------------------------------------------------------------
+
+import os
+
+from .base import TestsBase
+from ..utils import pandoc
+
+from IPython.testing import decorators as dec
+
+#-----------------------------------------------------------------------------
+# Constants
+#-----------------------------------------------------------------------------
+
+
+#-----------------------------------------------------------------------------
+# Classes and functions
+#-----------------------------------------------------------------------------
+
+class TestPandoc(TestsBase):
+    """Collection of Pandoc tests"""
+
+    def __init__(self, *args, **kwargs):
+        super(TestPandoc, self).__init__(*args, **kwargs)
+        self.original_env = os.environ.copy()
+
+    @dec.onlyif_cmds_exist('pandoc')
+    def test_pandoc_available(self):
+        """ Test behaviour of pandoc_available() """
+        os.environ["PATH"] = ""
+        assert not pandoc.pandoc_available()
+        try:
+            pandoc.pandoc_available(failmode="raise")
+        except pandoc.PandocMissing:
+            assert True
+
+        os.environ["PATH"] = self.original_env["PATH"]
+        assert pandoc.pandoc_available()
+        try:
+            pandoc.pandoc_available(failmode="raise")
+        except pandoc.PandocMissing:
+            assert False
+        
+    @dec.onlyif_cmds_exist('pandoc')        
+    def test_minimal_version(self):
+        original_minversion = pandoc.minimal_version
+
+        pandoc.minimal_version = "120.0"
+        assert not pandoc.check_pandoc_version()
+
+        pandoc.minimal_version = pandoc.get_pandoc_version()
+        assert pandoc.check_pandoc_version()
+        
+
+        

IPython/nbconvert/utils/pandoc.py

@@ -22,6 +22,7 b' from io import TextIOWrapper, BytesIO'
 # IPython imports
 from IPython.utils.py3compat import cast_bytes
 from IPython.utils.version import check_version
+from IPython.utils.process import find_cmd, FindCmdError
 
 
 from .exceptions import ConversionException
@@ -33,14 +34,25 b' from .exceptions import ConversionException'
 # module root level so that the import of this module is not fatal. 
 #----------------------------------------------------------------------------
 
+# command line to make pandoc print it's version. It is also the
+# easiest way to make pandoc return at all.
+__pandoc_version_call = ['pandoc', '-v']
+
 class PandocMissing(ConversionException):
     """Exception raised when Pandoc is missing. """
     def __init__(self, cmd, exc, *args, **kwargs):
         super(PandocMissing, self).__init__( "The command '%s' returned an error: %s.\n" %(" ".join(cmd), exc) +
                                              "Please check that pandoc is installed:\n" +
                                              "http://johnmacfarlane.net/pandoc/installing.html" )
+        self.exc = exc
+
+    def __bool__(self):
+        return False
+
+    __nonzero__ = __bool__
+    
 
-def pandoc_available(failmode="return", warn=False, alt=None):
+def pandoc_available(failmode="return", warn=False):
     """Is pandoc available. Only tries to call Pandoc
     and inform you that it succeeded or failed. 
     
@@ -52,49 +64,57 b' def pandoc_available(failmode="return", warn=False, alt=None):'
         the exception returned by subprocess.check_call.
      - warn : bool
         issue a user warning if pandoc is not available.
-     - alt: list of strings
-        command to print in the error (not used as actual call)
 
     Return
     ------
     out : (Bool, Exception)
-        On success will return (True, None). On failure and failmode=="return" 
-        will return (False, OSError instance)
+        On success will return True. On failure and failmode=="return" 
+        will return False-valued PandocMissing instance
     """
     
-    cmd  = ["pandoc", "-v"]
-
     try:
-        out = subprocess.check_output(cmd, universal_newlines=True)
-        return True, None
-    except OSError as e:
+        find_cmd("pandoc")
+        return True
+    except FindCmdError as e:
         if warn:
             warnings.warn(
-                "Pandoc cannot be found (calling %s failed).\n" % " ".join(alt or cmd) +
+                "Pandoc cannot be found (calling %s failed).\n" % " ".join(alt or __pandoc_version_call) +
                 "Please check that pandoc is installed:\n" +
                 "http://johnmacfarlane.net/pandoc/installing.html"
             )
 
+        exc = PandocMissing("pandoc", e)
         if failmode == "return":
-            return False, e
+            return exc
         else:
-            raise PandocMissing(alt or cmd, e)
+            raise exc
             
 
 #-----------------------------------------------------------------------------
 # Classes and functions
 #-----------------------------------------------------------------------------
+minimal_version = "1.12.1"
 
+# The following holds cached values about the pandoc executable.
+def clean_cache(new=False):
+    if new:
+        global __cache
+        cache = {}
+        __cache = cache
+    else:
+        cache = __cache
+        cache.clear()
+    
+    cache['version_ok'] = False
+    cache['version'] = None
+    return cache
+
+__cache = clean_cache(new=True)
 
-minimal_version = "1.12.1"
-minimal_version_ok = False
 
 def pandoc(source, fmt, to, extra_args=None, encoding='utf-8'):
     """Convert an input string in format `from` to format `to` via pandoc.
 
-    This function will raise PandocMissing if pandoc is not installed.
-    Any error messages generated by pandoc are printed to stderr.
-
     Parameters
     ----------
     source : string
@@ -108,6 +128,12 b" def pandoc(source, fmt, to, extra_args=None, encoding='utf-8'):"
     -------
     out : unicode
       Output as returned by pandoc.
+
+    Exceptions
+    ----------
+    This function will raise PandocMissing if pandoc is not installed.
+    Any error messages generated by pandoc are printed to stderr.
+
     """
     cmd = ['pandoc', '-f', fmt, '-t', to]
     if extra_args:
@@ -125,32 +151,43 b" def pandoc(source, fmt, to, extra_args=None, encoding='utf-8'):"
 
 def get_pandoc_version():
     """Gets the Pandoc version if Pandoc is installed.
+    
+    Return
+    ------
+    If the minimal version is not met, it will probe Pandoc for its version, cache it and return that value.
+    If the minimal version is met, it will return the cached version and stop probing Pandoc 
+    (unless `clean_cache()` is called).
+
+    Exceptions
+    ----------
     PandocMissing will be raised if pandoc is unavailable.
     """
-    try:
-        if not minimal_version_ok:
-            raise AttributeError()
-        else:
-            return pandoc.version
-    except AttributeError:
-        # if pandoc is missing let the exception bubble us out of here
-        pandoc_available(failmode="raise")        
-        cmd = ["pandoc", "-v"]
-        out = subprocess.check_output(cmd, universal_newlines=True)
+
+    if __cache['version_ok'] and __cache['version']:
+        return __cache['version']
+    else:
+        pandoc_available(failmode="raise")
+        out = subprocess.check_output(__pandoc_version_call, universal_newlines=True)
         pv_re = re.compile(r'(\d{0,3}\.\d{0,3}\.\d{0,3})')
-        pandoc.version = pv_re.search(out).group(0)
-        return pandoc.version
+        __cache['version'] = version = pv_re.search(out).group(0)
+        return version
+
 
 def check_pandoc_version():
     """Returns True if minimal pandoc version is met.
+
+    Exceptions
+    ----------
     PandocMissing will be raised if pandoc is unavailable.
     """
-    global minimal_version_ok
-    if not minimal_version_ok:
-        minimal_version_ok = check_version( get_pandoc_version(), minimal_version )
-        if not minimal_version_ok:
-            warnings.warn( "You are using an old version of pandoc (%s)\n" % pandoc.version + 
+    ok = __cache['version_ok']
+    if not ok:
+        __cache['version_ok'] = ok = check_version( get_pandoc_version(), minimal_version )
+        if not ok:
+            warnings.warn( "You are using an old version of pandoc (%s)\n" % __cache['version'] + 
                            "Recommended version is %s.\nTry updating." % minimal_version + 
                            "http://johnmacfarlane.net/pandoc/installing.html.\nContinuing with doubts...",
                            RuntimeWarning, stacklevel=2)
-    return minimal_version_ok
+    return __cache['version_ok']
+
+