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
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
1"""
2class Renderer
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"""
9from __future__ import annotations
11from collections.abc import Sequence
12import inspect
13from typing import Any, ClassVar, Protocol
15from .common.utils import MD_TRIM_RE, escapeHtml, mdTrim, unescapeAll
16from .token import Token
17from .utils import EnvType, OptionsDict
20class RendererProtocol(Protocol):
21 """The interface a renderer passed to ``MarkdownIt(renderer_cls=...)`` must have.
23 ``MarkdownIt`` creates the renderer as ``renderer_cls(md)``, and its
24 ``render`` and ``renderInline`` methods call only :meth:`render`.
25 """
27 __output__: ClassVar[str]
28 """The name of the output format, e.g. ``"html"``.
30 ``MarkdownIt.add_render_rule`` only applies rules whose ``fmt`` matches it.
31 """
33 def render(
34 self, tokens: Sequence[Token], options: OptionsDict, env: EnvType
35 ) -> Any:
36 """Render a token stream to the output format."""
39class RendererHTML(RendererProtocol):
40 """Contains render rules for tokens. Can be updated and extended.
42 Example:
44 Each rule is called as independent static function with fixed signature:
46 ::
48 class Renderer:
49 def token_type_name(self, tokens, idx, options, env) {
50 # ...
51 return renderedHTML
53 ::
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>'
61 md = MarkdownIt(renderer_cls=CustomRenderer)
63 result = md.render(...)
65 See https://github.com/markdown-it/markdown-it/blob/master/lib/renderer.js
66 for more details and examples.
67 """
69 __output__ = "html"
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 }
78 def render(
79 self, tokens: Sequence[Token], options: OptionsDict, env: EnvType
80 ) -> str:
81 """Takes token stream and generates HTML.
83 :param tokens: list on block tokens to render
84 :param options: params of parser instance
85 :param env: additional data from parsed input
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] = []
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))
103 return "".join(out)
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.
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] = []
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))
122 return "".join(out)
124 def renderToken(
125 self,
126 tokens: Sequence[Token],
127 idx: int,
128 options: OptionsDict,
129 env: EnvType,
130 ) -> str:
131 """Default token renderer.
133 Can be overridden by custom function
135 :param idx: token index to render
136 :param options: params of parser instance
137 """
138 result = ""
139 needLf = False
140 token = tokens[idx]
142 # Tight list paragraphs
143 if token.hidden:
144 return ""
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"
156 # Add token name, e.g. `<img`
157 result += ("</" if token.nesting == -1 else "<") + token.tag
159 # Encode attributes, e.g. `<img src="foo"`
160 result += self.renderAttrs(token)
162 # Add a slash for self-closing tags, e.g. `<img src="foo" /`
163 if token.nesting == 0 and options["xhtmlOut"]:
164 result += " /"
166 # Check if we need to add a newline after this tag
167 if token.block:
168 needLf = True
170 if token.nesting == 1 and (idx + 1 < len(tokens)):
171 nextToken = tokens[idx + 1]
173 if nextToken.type == "inline" or nextToken.hidden:
174 # Block-level tag containing an inline tag.
175 #
176 needLf = False
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
183 result += ">\n" if needLf else ">"
185 return result
187 @staticmethod
188 def renderAttrs(token: Token) -> str:
189 """Render token attributes to string."""
190 result = ""
192 for key, value in token.attrItems():
193 result += " " + escapeHtml(key) + '="' + escapeHtml(str(value)) + '"'
195 return result
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.
205 Don't try to use it! Spec requires to show `alt` content with stripped markup,
206 instead of simple escaping.
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] = []
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")
225 return "".join(out)
227 ###################################################
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
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 )
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]
270 return (
271 "<pre"
272 + self.renderAttrs(token)
273 + "><code>"
274 + escapeHtml(tokens[idx].content)
275 + "</code></pre>\n"
276 )
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 = ""
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]
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)
305 if highlighted.startswith("<pre"):
306 return highlighted + "\n"
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)
316 return (
317 "<pre><code"
318 + self.renderAttrs(tmpToken)
319 + ">"
320 + highlighted
321 + "</code></pre>\n"
322 )
324 return (
325 "<pre><code"
326 + self.renderAttrs(token)
327 + ">"
328 + highlighted
329 + "</code></pre>\n"
330 )
332 def image(
333 self,
334 tokens: Sequence[Token],
335 idx: int,
336 options: OptionsDict,
337 env: EnvType,
338 ) -> str:
339 token = tokens[idx]
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", "")
348 return self.renderToken(tokens, idx, options, env)
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"
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 )
362 def text(
363 self, tokens: Sequence[Token], idx: int, options: OptionsDict, env: EnvType
364 ) -> str:
365 return escapeHtml(tokens[idx].content)
367 def html_block(
368 self, tokens: Sequence[Token], idx: int, options: OptionsDict, env: EnvType
369 ) -> str:
370 return tokens[idx].content
372 def html_inline(
373 self, tokens: Sequence[Token], idx: int, options: OptionsDict, env: EnvType
374 ) -> str:
375 return tokens[idx].content