Coverage for /pythoncovmergedfiles/medio/medio/usr/local/lib/python3.11/site-packages/markdown_it/renderer.py: 96%

Shortcuts on this page

r m x   toggle line displays

j k   next/prev highlighted chunk

0   (zero) top of page

1   (one) first highlighted chunk

124 statements  

1""" 

2class Renderer 

3 

4Generates HTML from parsed token stream. Each instance has independent 

5copy of rules. Those can be rewritten with ease. Also, you can add new 

6rules if you create plugin and adds new token types. 

7""" 

8 

9from __future__ import annotations 

10 

11from collections.abc import Sequence 

12import inspect 

13from typing import Any, ClassVar, Protocol 

14 

15from .common.utils import MD_TRIM_RE, escapeHtml, mdTrim, unescapeAll 

16from .token import Token 

17from .utils import EnvType, OptionsDict 

18 

19 

20class RendererProtocol(Protocol): 

21 """The interface a renderer passed to ``MarkdownIt(renderer_cls=...)`` must have. 

22 

23 ``MarkdownIt`` creates the renderer as ``renderer_cls(md)``, and its 

24 ``render`` and ``renderInline`` methods call only :meth:`render`. 

25 """ 

26 

27 __output__: ClassVar[str] 

28 """The name of the output format, e.g. ``"html"``. 

29 

30 ``MarkdownIt.add_render_rule`` only applies rules whose ``fmt`` matches it. 

31 """ 

32 

33 def render( 

34 self, tokens: Sequence[Token], options: OptionsDict, env: EnvType 

35 ) -> Any: 

36 """Render a token stream to the output format.""" 

37 

38 

39class RendererHTML(RendererProtocol): 

40 """Contains render rules for tokens. Can be updated and extended. 

41 

42 Example: 

43 

44 Each rule is called as independent static function with fixed signature: 

45 

46 :: 

47 

48 class Renderer: 

49 def token_type_name(self, tokens, idx, options, env) { 

50 # ... 

51 return renderedHTML 

52 

53 :: 

54 

55 class CustomRenderer(RendererHTML): 

56 def strong_open(self, tokens, idx, options, env): 

57 return '<b>' 

58 def strong_close(self, tokens, idx, options, env): 

59 return '</b>' 

60 

61 md = MarkdownIt(renderer_cls=CustomRenderer) 

62 

63 result = md.render(...) 

64 

65 See https://github.com/markdown-it/markdown-it/blob/master/lib/renderer.js 

66 for more details and examples. 

67 """ 

68 

69 __output__ = "html" 

70 

71 def __init__(self, parser: Any = None): 

72 self.rules = { 

73 k: v 

74 for k, v in inspect.getmembers(self, predicate=inspect.ismethod) 

75 if not k.startswith(("render", "_")) 

76 } 

77 

78 def render( 

79 self, tokens: Sequence[Token], options: OptionsDict, env: EnvType 

80 ) -> str: 

81 """Takes token stream and generates HTML. 

82 

83 :param tokens: list on block tokens to render 

84 :param options: params of parser instance 

85 :param env: additional data from parsed input 

86 

87 """ 

88 # Collect the fragments and join them once: repeated ``str +=`` is only 

89 # linear on interpreters that can extend a string in place (the default 

90 # CPython build), and quadratic in the output size elsewhere (e.g. PyPy, 

91 # GraalPy and free-threaded CPython 3.13). 

92 out: list[str] = [] 

93 

94 for i, token in enumerate(tokens): 

95 if token.type == "inline": 

96 if token.children: 

97 out.append(self.renderInline(token.children, options, env)) 

98 elif token.type in self.rules: 

99 out.append(self.rules[token.type](tokens, i, options, env)) 

100 else: 

101 out.append(self.renderToken(tokens, i, options, env)) 

102 

103 return "".join(out) 

104 

105 def renderInline( 

106 self, tokens: Sequence[Token], options: OptionsDict, env: EnvType 

107 ) -> str: 

108 """The same as ``render``, but for single token of `inline` type. 

109 

110 :param tokens: list on block tokens to render 

111 :param options: params of parser instance 

112 :param env: additional data from parsed input (references, for example) 

113 """ 

114 out: list[str] = [] 

115 

116 for i, token in enumerate(tokens): 

117 if token.type in self.rules: 

118 out.append(self.rules[token.type](tokens, i, options, env)) 

119 else: 

120 out.append(self.renderToken(tokens, i, options, env)) 

121 

122 return "".join(out) 

123 

124 def renderToken( 

125 self, 

126 tokens: Sequence[Token], 

127 idx: int, 

128 options: OptionsDict, 

129 env: EnvType, 

130 ) -> str: 

131 """Default token renderer. 

132 

133 Can be overridden by custom function 

134 

135 :param idx: token index to render 

136 :param options: params of parser instance 

137 """ 

138 result = "" 

139 needLf = False 

140 token = tokens[idx] 

141 

142 # Tight list paragraphs 

143 if token.hidden: 

144 return "" 

145 

146 # Insert a newline between hidden paragraph and subsequent opening 

147 # block-level tag. 

148 # 

149 # For example, here we should insert a newline before blockquote: 

150 # - a 

151 # > 

152 # 

153 if token.block and token.nesting != -1 and idx and tokens[idx - 1].hidden: 

154 result += "\n" 

155 

156 # Add token name, e.g. `<img` 

157 result += ("</" if token.nesting == -1 else "<") + token.tag 

158 

159 # Encode attributes, e.g. `<img src="foo"` 

160 result += self.renderAttrs(token) 

161 

162 # Add a slash for self-closing tags, e.g. `<img src="foo" /` 

163 if token.nesting == 0 and options["xhtmlOut"]: 

164 result += " /" 

165 

166 # Check if we need to add a newline after this tag 

167 if token.block: 

168 needLf = True 

169 

170 if token.nesting == 1 and (idx + 1 < len(tokens)): 

171 nextToken = tokens[idx + 1] 

172 

173 if nextToken.type == "inline" or nextToken.hidden: 

174 # Block-level tag containing an inline tag. 

175 # 

176 needLf = False 

177 

178 elif nextToken.nesting == -1 and nextToken.tag == token.tag: 

179 # Opening tag + closing tag of the same type. E.g. `<li></li>`. 

180 # 

181 needLf = False 

182 

183 result += ">\n" if needLf else ">" 

184 

185 return result 

186 

187 @staticmethod 

188 def renderAttrs(token: Token) -> str: 

189 """Render token attributes to string.""" 

190 result = "" 

191 

192 for key, value in token.attrItems(): 

193 result += " " + escapeHtml(key) + '="' + escapeHtml(str(value)) + '"' 

194 

195 return result 

196 

197 def renderInlineAsText( 

198 self, 

199 tokens: Sequence[Token] | None, 

200 options: OptionsDict, 

201 env: EnvType, 

202 ) -> str: 

203 """Special kludge for image `alt` attributes to conform CommonMark spec. 

204 

205 Don't try to use it! Spec requires to show `alt` content with stripped markup, 

206 instead of simple escaping. 

207 

208 :param tokens: list on block tokens to render 

209 :param options: params of parser instance 

210 :param env: additional data from parsed input 

211 """ 

212 out: list[str] = [] 

213 

214 for token in tokens or []: 

215 if token.type in ("text", "code_inline"): 

216 out.append(token.content) 

217 elif token.type == "image": 

218 if token.children: 

219 out.append(self.renderInlineAsText(token.children, options, env)) 

220 elif token.type in ("html_inline", "html_block"): 

221 out.append(token.content) 

222 elif token.type in ("softbreak", "hardbreak"): 

223 out.append("\n") 

224 

225 return "".join(out) 

226 

227 ################################################### 

228 

229 def list_item_open( 

230 self, 

231 tokens: Sequence[Token], 

232 idx: int, 

233 options: OptionsDict, 

234 env: EnvType, 

235 ) -> str: 

236 token = tokens[idx] 

237 result = self.renderToken(tokens, idx, options, env) 

238 if token.meta and "checked" in token.meta: 

239 checked_attr = ' checked=""' if token.meta["checked"] else "" 

240 disabled_attr = ( 

241 "" if options.get("tasklists_editable", False) else ' disabled=""' 

242 ) 

243 result += ( 

244 '<input class="task-list-item-checkbox"' 

245 f'{disabled_attr} type="checkbox"{checked_attr}> ' 

246 ) 

247 return result 

248 

249 def code_inline( 

250 self, tokens: Sequence[Token], idx: int, options: OptionsDict, env: EnvType 

251 ) -> str: 

252 token = tokens[idx] 

253 return ( 

254 "<code" 

255 + self.renderAttrs(token) 

256 + ">" 

257 + escapeHtml(tokens[idx].content) 

258 + "</code>" 

259 ) 

260 

261 def code_block( 

262 self, 

263 tokens: Sequence[Token], 

264 idx: int, 

265 options: OptionsDict, 

266 env: EnvType, 

267 ) -> str: 

268 token = tokens[idx] 

269 

270 return ( 

271 "<pre" 

272 + self.renderAttrs(token) 

273 + "><code>" 

274 + escapeHtml(tokens[idx].content) 

275 + "</code></pre>\n" 

276 ) 

277 

278 def fence( 

279 self, 

280 tokens: Sequence[Token], 

281 idx: int, 

282 options: OptionsDict, 

283 env: EnvType, 

284 ) -> str: 

285 token = tokens[idx] 

286 info = mdTrim(unescapeAll(token.info)) if token.info else "" 

287 langName = "" 

288 langAttrs = "" 

289 

290 if info: 

291 # Not ``str.split()``: it splits on the Python whitespace set, 

292 # which is wider than the one upstream uses here. 

293 arr = MD_TRIM_RE.split(info, maxsplit=1) 

294 langName = arr[0] 

295 if len(arr) == 2: 

296 langAttrs = arr[1] 

297 

298 if options.highlight: 

299 highlighted = options.highlight( 

300 token.content, langName, langAttrs 

301 ) or escapeHtml(token.content) 

302 else: 

303 highlighted = escapeHtml(token.content) 

304 

305 if highlighted.startswith("<pre"): 

306 return highlighted + "\n" 

307 

308 # If language exists, inject class gently, without modifying original token. 

309 # May be, one day we will add .deepClone() for token and simplify this part, but 

310 # now we prefer to keep things local. 

311 if info: 

312 # Fake token just to render attributes 

313 tmpToken = Token(type="", tag="", nesting=0, attrs=token.attrs.copy()) 

314 tmpToken.attrJoin("class", options.langPrefix + langName) 

315 

316 return ( 

317 "<pre><code" 

318 + self.renderAttrs(tmpToken) 

319 + ">" 

320 + highlighted 

321 + "</code></pre>\n" 

322 ) 

323 

324 return ( 

325 "<pre><code" 

326 + self.renderAttrs(token) 

327 + ">" 

328 + highlighted 

329 + "</code></pre>\n" 

330 ) 

331 

332 def image( 

333 self, 

334 tokens: Sequence[Token], 

335 idx: int, 

336 options: OptionsDict, 

337 env: EnvType, 

338 ) -> str: 

339 token = tokens[idx] 

340 

341 # "alt" attr MUST be set, even if empty. Because it's mandatory and 

342 # should be placed on proper position for tests. 

343 if token.children: 

344 token.attrSet("alt", self.renderInlineAsText(token.children, options, env)) 

345 else: 

346 token.attrSet("alt", "") 

347 

348 return self.renderToken(tokens, idx, options, env) 

349 

350 def hardbreak( 

351 self, tokens: Sequence[Token], idx: int, options: OptionsDict, env: EnvType 

352 ) -> str: 

353 return "<br />\n" if options.xhtmlOut else "<br>\n" 

354 

355 def softbreak( 

356 self, tokens: Sequence[Token], idx: int, options: OptionsDict, env: EnvType 

357 ) -> str: 

358 return ( 

359 ("<br />\n" if options.xhtmlOut else "<br>\n") if options.breaks else "\n" 

360 ) 

361 

362 def text( 

363 self, tokens: Sequence[Token], idx: int, options: OptionsDict, env: EnvType 

364 ) -> str: 

365 return escapeHtml(tokens[idx].content) 

366 

367 def html_block( 

368 self, tokens: Sequence[Token], idx: int, options: OptionsDict, env: EnvType 

369 ) -> str: 

370 return tokens[idx].content 

371 

372 def html_inline( 

373 self, tokens: Sequence[Token], idx: int, options: OptionsDict, env: EnvType 

374 ) -> str: 

375 return tokens[idx].content