IPython/nbconvert/utils/pandoc.py

"""Utility for calling pandoc"""
#-----------------------------------------------------------------------------
# Copyright (c) 2013 the IPython Development Team.
#
# Distributed under the terms of the Modified BSD License.
#
# The full license is in the file COPYING.txt, distributed with this software.
#-----------------------------------------------------------------------------

#-----------------------------------------------------------------------------
# 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 .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
      Input string, assumed to be valid format `from`.
    fmt : string
      The name of the input format (markdown, etc.)
    to : string
      The name of the output format (html, etc.)

    Returns
    -------
    out : unicode
      Output as returned by pandoc.
    """
    command = ['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"
        )
    out, _ = p.communicate(cast_bytes(source, encoding))
    out = TextIOWrapper(BytesIO(out), encoding, 'replace').read()
    return out.rstrip('\n')


pv_re = re.compile(r'(\d{0,3}\.\d{0,3}\.\d{0,3})')
def get_pandoc_version():
    out = subprocess.check_output(['pandoc', '--version'], universal_newlines=True)
    return pv_re.search(out).group(0)


pandoc.version = get_pandoc_version()

def check_pandoc_version():
    return pandoc.version >= minimal_version

if(not check_pandoc_version()):
    warnings.warn( "You are using an old version of pandoc (%s)\n"%pandoc.version + 
                   "Recommended version is %s.\nTry updating."%minimal_version + 
                   "http://johnmacfarlane.net/pandoc/installing.html.\nContinuing with doubts...",
                   RuntimeWarning, 
                   stacklevel=2)