pandoc.py
135 lines
| 4.4 KiB
| text/x-python
|
PythonLexer
|
r11267 | """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 | ||||
|
r14759 | import re | ||
import warnings | ||||
|
r12523 | from io import TextIOWrapper, BytesIO | ||
|
r11267 | |||
# IPython imports | ||||
from IPython.utils.py3compat import cast_bytes | ||||
|
r14763 | from IPython.utils.version import check_version | ||
|
r14768 | from IPython.utils.process import is_cmd_found, FindCmdError | ||
|
r14763 | |||
|
r11267 | |||
|
r11703 | from .exceptions import ConversionException | ||
|
r11267 | #----------------------------------------------------------------------------- | ||
# Classes and functions | ||||
#----------------------------------------------------------------------------- | ||||
|
r14768 | _minimal_version = "1.12.1" | ||
|
r11702 | |||
|
r11293 | def pandoc(source, fmt, to, extra_args=None, encoding='utf-8'): | ||
|
r11267 | """Convert an input string in format `from` to format `to` via pandoc. | ||
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. | ||||
|
r14766 | |||
Exceptions | ||||
---------- | ||||
This function will raise PandocMissing if pandoc is not installed. | ||||
Any error messages generated by pandoc are printed to stderr. | ||||
|
r11267 | """ | ||
|
r14760 | cmd = ['pandoc', '-f', fmt, '-t', to] | ||
|
r11293 | if extra_args: | ||
|
r14760 | cmd.extend(extra_args) | ||
|
r14765 | # this will raise an exception that will pop us out of here | ||
|
r14763 | check_pandoc_version() | ||
|
r14760 | |||
# we can safely continue | ||||
p = subprocess.Popen(cmd, stdin=subprocess.PIPE, stdout=subprocess.PIPE) | ||||
|
r11267 | out, _ = p.communicate(cast_bytes(source, encoding)) | ||
|
r12523 | out = TextIOWrapper(BytesIO(out), encoding, 'replace').read() | ||
return out.rstrip('\n') | ||||
|
r11267 | |||
|
r14759 | |||
def get_pandoc_version(): | ||||
|
r14763 | """Gets the Pandoc version if Pandoc is installed. | ||
|
r14766 | |||
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 | ||||
---------- | ||||
|
r14763 | PandocMissing will be raised if pandoc is unavailable. | ||
""" | ||||
|
r14768 | global __version | ||
|
r14766 | |||
|
r14768 | if __version is not None: | ||
return __version | ||||
|
r14766 | else: | ||
|
r14768 | if not is_cmd_found('pandoc'): | ||
raise PandocMissing() | ||||
out = subprocess.check_output( ['pandoc', '-v'], universal_newlines=True) | ||||
|
r14760 | pv_re = re.compile(r'(\d{0,3}\.\d{0,3}\.\d{0,3})') | ||
|
r14768 | __version = pv_re.search(out).group(0) | ||
return __version | ||||
|
r14766 | |||
|
r14759 | |||
def check_pandoc_version(): | ||||
|
r14763 | """Returns True if minimal pandoc version is met. | ||
|
r14766 | |||
Exceptions | ||||
---------- | ||||
|
r14763 | PandocMissing will be raised if pandoc is unavailable. | ||
""" | ||||
|
r14768 | v = get_pandoc_version() | ||
ok = check_version(v , _minimal_version ) | ||||
|
r14766 | if not ok: | ||
|
r14768 | 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 | ||||
|
r14766 | |||
|
r14767 | #----------------------------------------------------------------------------- | ||
# Exception handling | ||||
#----------------------------------------------------------------------------- | ||||
class PandocMissing(ConversionException): | ||||
"""Exception raised when Pandoc is missing. """ | ||||
|
r14768 | def __init__(self, *args, **kwargs): | ||
super(PandocMissing, self).__init__( "Pandoc wasn't found.\n" + | ||||
|
r14767 | "Please check that pandoc is installed:\n" + | ||
"http://johnmacfarlane.net/pandoc/installing.html" ) | ||||
#----------------------------------------------------------------------------- | ||||
# Internal state management | ||||
#----------------------------------------------------------------------------- | ||||
|
r14768 | def clean_cache(): | ||
global __version | ||||
__version = None | ||||
|
r14767 | |||
|
r14768 | __version = None | ||
|
r14767 | |||
|
r14766 | |||