Merge pull request #4680 from dbarbeau/minimal-pandoc

Minimal pandoc version warning

IPython/nbconvert/utils/tests/test_pandoc.py

@@ -0,0 +1,62 b''
+"""Test Pandoc module"""
+#-----------------------------------------------------------------------------
+#  Copyright (C) 2014 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 IPython.testing import decorators as dec
+
+from IPython.nbconvert.tests.base import TestsBase
+from .. import pandoc
+
+#-----------------------------------------------------------------------------
+# 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 that pandoc functions raise PandocMissing as documented """
+        pandoc.clean_cache()
+
+        os.environ["PATH"] = ""
+        assert pandoc_function_raised_missing(pandoc.get_pandoc_version) == True
+        assert pandoc_function_raised_missing(pandoc.check_pandoc_version) == True
+        assert pandoc_function_raised_missing(pandoc.pandoc, "", "markdown", "html") == True
+
+        # original_env["PATH"] should contain pandoc
+        os.environ["PATH"] = self.original_env["PATH"]
+        assert pandoc_function_raised_missing(pandoc.get_pandoc_version) == False
+        assert pandoc_function_raised_missing(pandoc.check_pandoc_version) == False
+        assert pandoc_function_raised_missing(pandoc.pandoc, "", "markdown", "html") == 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()
+
+
+def pandoc_function_raised_missing(f, *args, **kwargs):
+    try:
+        f(*args, **kwargs)
+    except pandoc.PandocMissing:
+        return True
+    else:
+        return False

docs/source/whatsnew/pr/minimal-pandoc.rst

@@ -0,0 +1,3 b''
+* PandocMissing exceptions will be raised if Pandoc is unavailable
+* Recommended Pandoc version for use with nbconvert is 1.12.1
+* warnings will be printed if the version is not good.

IPython/nbconvert/utils/pandoc.py

@@ -1,6 +1,6 b''
 """Utility for calling pandoc"""
 #-----------------------------------------------------------------------------
-# Copyright (c) 2013 the IPython Development Team.
+# Copyright (c) 2014 the IPython Development Team.
 #
 # Distributed under the terms of the Modified BSD License.
 #
@@ -10,33 +10,29 b''
 #-----------------------------------------------------------------------------
 # Imports
 #-----------------------------------------------------------------------------
-
 from __future__ import print_function
 
 # Stdlib imports
 import subprocess
+import re
+import warnings
 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 is_cmd_found, FindCmdError
 
 from .exceptions import ConversionException
 
 #-----------------------------------------------------------------------------
 # Classes and functions
 #-----------------------------------------------------------------------------
-
-class PandocMissing(ConversionException):
-    """Exception raised when Pandoc is missing. """
-    pass
-
+_minimal_version = "1.12.1"
 
 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 an error if pandoc is not installed.
-    Any error messages generated by pandoc are printed to stderr.
-
     Parameters
     ----------
     source : string
@@ -50,21 +46,83 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.
+
     """
-    command = ['pandoc', '-f', fmt, '-t', to]
+    cmd = ['pandoc', '-f', fmt, '-t', to]
     if extra_args:
-        command.extend(extra_args)
-    try:
-        p = subprocess.Popen(command,
-                             stdin=subprocess.PIPE, stdout=subprocess.PIPE
-        )
-    except OSError as e:
-        raise PandocMissing(
-            "The command '%s' returned an error: %s.\n" %(" ".join(command), e) +
-            "Please check that pandoc is installed:\n" +
-            "http://johnmacfarlane.net/pandoc/installing.html"
-        )
+        cmd.extend(extra_args)
+
+    # this will raise an exception that will pop us out of here
+    check_pandoc_version()
+    
+    # we can safely continue
+    p = subprocess.Popen(cmd, stdin=subprocess.PIPE, stdout=subprocess.PIPE)
     out, _ = p.communicate(cast_bytes(source, encoding))
     out = TextIOWrapper(BytesIO(out), encoding, 'replace').read()
     return out.rstrip('\n')
 
+
+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.
+    """
+    global __version
+
+    if __version is None:
+        if not is_cmd_found('pandoc'):
+            raise PandocMissing()
+
+        out = subprocess.check_output( ['pandoc', '-v'], universal_newlines=True)
+        pv_re = re.compile(r'(\d{0,3}\.\d{0,3}\.\d{0,3})')
+        __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.
+    """
+    v = get_pandoc_version()
+    ok = check_version(v , _minimal_version )
+    if not ok:
+        warnings.warn( "You are using an old version of pandoc (%s)\n" % v + 
+                       "Recommended version is %s.\nTry updating." % _minimal_version + 
+                       "http://johnmacfarlane.net/pandoc/installing.html.\nContinuing with doubts...",
+                       RuntimeWarning, stacklevel=2)
+    return ok
+
+#-----------------------------------------------------------------------------
+# Exception handling
+#-----------------------------------------------------------------------------
+class PandocMissing(ConversionException):
+    """Exception raised when Pandoc is missing. """
+    def __init__(self, *args, **kwargs):
+        super(PandocMissing, self).__init__( "Pandoc wasn't found.\n" +
+                                             "Please check that pandoc is installed:\n" +
+                                             "http://johnmacfarlane.net/pandoc/installing.html" )
+
+#-----------------------------------------------------------------------------
+# Internal state management
+#-----------------------------------------------------------------------------
+def clean_cache():
+    global __version
+    __version = None
+
+__version = None