Coverage for /pythoncovmergedfiles/medio/medio/usr/local/lib/python3.8/site-packages/nbconvert/utils/pandoc.py: 35%

1"""Utility for calling pandoc""" 

2# Copyright (c) IPython Development Team. 

3# Distributed under the terms of the Modified BSD License. 

4 

5 

6import re 

7import shutil 

8import subprocess 

9import warnings 

10from io import BytesIO, TextIOWrapper 

11 

12from nbconvert.utils.version import check_version 

13 

14from .exceptions import ConversionException 

15 

16_minimal_version = "2.14.2" 

17_maximal_version = "4.0.0" 

18 

19 

20def pandoc(source, fmt, to, extra_args=None, encoding="utf-8"): 

21 """Convert an input string using pandoc. 

22 

23 Pandoc converts an input string `from` a format `to` a target format. 

24 

25 Parameters 

26 ---------- 

27 source : string 

28 Input string, assumed to be valid format `from`. 

29 fmt : string 

30 The name of the input format (markdown, etc.) 

31 to : string 

32 The name of the output format (html, etc.) 

33 

34 Returns 

35 ------- 

36 out : unicode 

37 Output as returned by pandoc. 

38 

39 Raises 

40 ------ 

41 PandocMissing 

42 If pandoc is not installed. 

43 Any error messages generated by pandoc are printed to stderr. 

44 

45 """ 

46 cmd = ["pandoc", "-f", fmt, "-t", to] 

47 if extra_args: 

48 cmd.extend(extra_args) 

49 

50 # this will raise an exception that will pop us out of here 

51 check_pandoc_version() 

52 

53 # we can safely continue 

54 p = subprocess.Popen(cmd, stdin=subprocess.PIPE, stdout=subprocess.PIPE) # noqa 

55 out, _ = p.communicate(source.encode()) 

56 out_str = TextIOWrapper(BytesIO(out), encoding, "replace").read() 

57 return out_str.rstrip("\n") 

58 

59 

60def get_pandoc_version(): 

61 """Gets the Pandoc version if Pandoc is installed. 

62 

63 If the minimal version is not met, it will probe Pandoc for its version, cache it and return that value. 

64 If the minimal version is met, it will return the cached version and stop probing Pandoc 

65 (unless `clean_cache()` is called). 

66 

67 Raises 

68 ------ 

69 PandocMissing 

70 If pandoc is unavailable. 

71 """ 

72 global __version # noqa 

73 

74 if __version is None: 

75 if not shutil.which("pandoc"): 

76 raise PandocMissing() 

77 

78 out = subprocess.check_output(["pandoc", "-v"]) # noqa 

79 out_lines = out.splitlines() 

80 version_pattern = re.compile(r"^\d+(\.\d+){1,}$") 

81 for tok in out_lines[0].decode("ascii", "replace").split(): 

82 if version_pattern.match(tok): 

83 __version = tok # type:ignore 

84 break 

85 return __version 

86 

87 

88def check_pandoc_version(): 

89 """Returns True if pandoc's version meets at least minimal version. 

90 

91 Raises 

92 ------ 

93 PandocMissing 

94 If pandoc is unavailable. 

95 """ 

96 if check_pandoc_version._cached is not None: # type:ignore 

97 return check_pandoc_version._cached # type:ignore 

98 

99 v = get_pandoc_version() 

100 if v is None: 

101 warnings.warn( 

102 "Sorry, we cannot determine the version of pandoc.\n" 

103 "Please consider reporting this issue and include the" 

104 "output of pandoc --version.\nContinuing...", 

105 RuntimeWarning, 

106 stacklevel=2, 

107 ) 

108 return False 

109 ok = check_version(v, _minimal_version, max_v=_maximal_version) 

110 check_pandoc_version._cached = ok # type:ignore 

111 if not ok: 

112 warnings.warn( 

113 "You are using an unsupported version of pandoc (%s).\n" % v 

114 + "Your version must be at least (%s) " % _minimal_version 

115 + "but less than (%s).\n" % _maximal_version 

116 + "Refer to https://pandoc.org/installing.html.\nContinuing with doubts...", 

117 RuntimeWarning, 

118 stacklevel=2, 

119 ) 

120 return ok 

121 

122 

123check_pandoc_version._cached = None # type:ignore 

124 

125# ----------------------------------------------------------------------------- 

126# Exception handling 

127# ----------------------------------------------------------------------------- 

128 

129 

130class PandocMissing(ConversionException): 

131 """Exception raised when Pandoc is missing.""" 

132 

133 def __init__(self, *args, **kwargs): 

134 """Initialize the exception.""" 

135 super().__init__( 

136 "Pandoc wasn't found.\n" 

137 "Please check that pandoc is installed:\n" 

138 "https://pandoc.org/installing.html" 

139 ) 

140 

141 

142# ----------------------------------------------------------------------------- 

143# Internal state management 

144# ----------------------------------------------------------------------------- 

145def clean_cache(): 

146 """Clean the internal cache.""" 

147 global __version # noqa 

148 __version = None 

149 

150 

151__version = None