File size: 4,580 Bytes
d1ceb73 |
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 |
"""Utility for calling pandoc"""
# Copyright (c) IPython Development Team.
# Distributed under the terms of the Modified BSD License.
import re
import shutil
import subprocess
import warnings
from io import BytesIO, TextIOWrapper
from nbconvert.utils.version import check_version
from .exceptions import ConversionException
_minimal_version = "2.9.2"
_maximal_version = "4.0.0"
def pandoc(source, fmt, to, extra_args=None, encoding="utf-8"):
"""Convert an input string using pandoc.
Pandoc converts an input string `from` a format `to` a target format.
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.
Raises
------
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:
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) # noqa: S603
out, _ = p.communicate(source.encode())
out_str = TextIOWrapper(BytesIO(out), encoding, "replace").read()
return out_str.rstrip("\n")
def get_pandoc_version():
"""Gets the Pandoc version if Pandoc is installed.
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).
Raises
------
PandocMissing
If pandoc is unavailable.
"""
global __version # noqa: PLW0603
if __version is None:
if not shutil.which("pandoc"):
raise PandocMissing()
out = subprocess.check_output(["pandoc", "-v"]) # noqa: S607, S603
out_lines = out.splitlines()
version_pattern = re.compile(r"^\d+(\.\d+){1,}$")
for tok in out_lines[0].decode("ascii", "replace").split():
if version_pattern.match(tok):
__version = tok # type:ignore[assignment]
break
return __version
def check_pandoc_version():
"""Returns True if pandoc's version meets at least minimal version.
Raises
------
PandocMissing
If pandoc is unavailable.
"""
if check_pandoc_version._cached is not None: # type:ignore[attr-defined]
return check_pandoc_version._cached # type:ignore[attr-defined]
v = get_pandoc_version()
if v is None:
warnings.warn(
"Sorry, we cannot determine the version of pandoc.\n"
"Please consider reporting this issue and include the"
"output of pandoc --version.\nContinuing...",
RuntimeWarning,
stacklevel=2,
)
return False
ok = check_version(v, _minimal_version, max_v=_maximal_version)
check_pandoc_version._cached = ok # type:ignore[attr-defined]
if not ok:
warnings.warn(
"You are using an unsupported version of pandoc (%s).\n" % v
+ "Your version must be at least (%s) " % _minimal_version
+ "but less than (%s).\n" % _maximal_version
+ "Refer to https://pandoc.org/installing.html.\nContinuing with doubts...",
RuntimeWarning,
stacklevel=2,
)
return ok
check_pandoc_version._cached = None # type:ignore[attr-defined]
# -----------------------------------------------------------------------------
# Exception handling
# -----------------------------------------------------------------------------
class PandocMissing(ConversionException):
"""Exception raised when Pandoc is missing."""
def __init__(self, *args, **kwargs):
"""Initialize the exception."""
super().__init__(
"Pandoc wasn't found.\n"
"Please check that pandoc is installed:\n"
"https://pandoc.org/installing.html"
)
# -----------------------------------------------------------------------------
# Internal state management
# -----------------------------------------------------------------------------
def clean_cache():
"""Clean the internal cache."""
global __version # noqa: PLW0603
__version = None
__version = None
|