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

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

140 statements  

1from __future__ import annotations 

2 

3from collections.abc import Callable, Generator, Iterable, Mapping, MutableMapping 

4from contextlib import contextmanager 

5from typing import Any, Literal, overload 

6 

7from . import helpers, presets 

8from .common import normalize_url, utils 

9from .parser_block import ParserBlock 

10from .parser_core import ParserCore 

11from .parser_inline import ParserInline 

12from .renderer import RendererHTML, RendererProtocol 

13from .rules_core.state_core import StateCore 

14from .token import Token 

15from .utils import EnvType, OptionsDict, OptionsType, PresetType 

16 

17try: 

18 import linkify_it 

19except ModuleNotFoundError: 

20 linkify_it = None 

21 

22 

23_PRESETS: dict[str, PresetType] = { 

24 "default": presets.default.make(), 

25 "js-default": presets.js_default.make(), 

26 "zero": presets.zero.make(), 

27 "commonmark": presets.commonmark.make(), 

28 "gfm-like": presets.gfm_like.make(), 

29 "gfm-like2": presets.gfm_like2.make(), 

30} 

31 

32 

33class MarkdownIt: 

34 def __init__( 

35 self, 

36 config: str | PresetType = "commonmark", 

37 options_update: Mapping[str, Any] | None = None, 

38 *, 

39 renderer_cls: Callable[[MarkdownIt], RendererProtocol] = RendererHTML, 

40 ): 

41 """Main parser class 

42 

43 :param config: name of configuration to load or a pre-defined dictionary 

44 :param options_update: dictionary that will be merged into ``config["options"]`` 

45 :param renderer_cls: the class to load as the renderer: 

46 ``self.renderer = renderer_cls(self) 

47 """ 

48 # add modules 

49 self.utils = utils 

50 self.helpers = helpers 

51 

52 # initialise classes 

53 self.inline = ParserInline() 

54 self.block = ParserBlock() 

55 self.core = ParserCore() 

56 self.renderer = renderer_cls(self) 

57 self.linkify = linkify_it.LinkifyIt() if linkify_it else None 

58 

59 # set the configuration 

60 if options_update and not isinstance(options_update, Mapping): 

61 # catch signature change where renderer_cls was not used as a key-word 

62 raise TypeError( 

63 f"options_update should be a mapping: {options_update}" 

64 "\n(Perhaps you intended this to be the renderer_cls?)" 

65 ) 

66 self.configure(config, options_update=options_update) 

67 

68 def __repr__(self) -> str: 

69 return f"{self.__class__.__module__}.{self.__class__.__name__}()" 

70 

71 @overload 

72 def __getitem__(self, name: Literal["inline"]) -> ParserInline: ... 

73 

74 @overload 

75 def __getitem__(self, name: Literal["block"]) -> ParserBlock: ... 

76 

77 @overload 

78 def __getitem__(self, name: Literal["core"]) -> ParserCore: ... 

79 

80 @overload 

81 def __getitem__(self, name: Literal["renderer"]) -> RendererProtocol: ... 

82 

83 @overload 

84 def __getitem__(self, name: str) -> Any: ... 

85 

86 def __getitem__(self, name: str) -> Any: 

87 return { 

88 "inline": self.inline, 

89 "block": self.block, 

90 "core": self.core, 

91 "renderer": self.renderer, 

92 }[name] 

93 

94 def set(self, options: OptionsType) -> None: 

95 """Set parser options (in the same format as in constructor). 

96 Probably, you will never need it, but you can change options after constructor call. 

97 

98 __Note:__ To achieve the best possible performance, don't modify a 

99 `markdown-it` instance options on the fly. If you need multiple configurations 

100 it's best to create multiple instances and initialize each with separate config. 

101 """ 

102 self.options = OptionsDict(options) 

103 

104 def configure( 

105 self, presets: str | PresetType, options_update: Mapping[str, Any] | None = None 

106 ) -> MarkdownIt: 

107 """Batch load of all options and component settings. 

108 This is an internal method, and you probably will not need it. 

109 But if you will - see available presets and data structure 

110 [here](https://github.com/markdown-it/markdown-it/tree/master/lib/presets) 

111 

112 We strongly recommend to use presets instead of direct config loads. 

113 That will give better compatibility with next versions. 

114 """ 

115 if isinstance(presets, str): 

116 if presets not in _PRESETS: 

117 raise KeyError(f"Wrong `markdown-it` preset '{presets}', check name") 

118 config = _PRESETS[presets] 

119 else: 

120 config = presets 

121 

122 if not config: 

123 raise ValueError("Wrong `markdown-it` config, can't be empty") 

124 

125 options = config.get("options", {}) or {} 

126 if options_update: 

127 options = {**options, **options_update} # type: ignore 

128 

129 self.set(options) 

130 

131 if "components" in config: 

132 for name, component in config["components"].items(): 

133 rules = component.get("rules", None) 

134 if rules: 

135 self[name].ruler.enableOnly(rules) 

136 rules2 = component.get("rules2", None) 

137 if rules2: 

138 self[name].ruler2.enableOnly(rules2) 

139 

140 return self 

141 

142 def get_all_rules(self) -> dict[str, list[str]]: 

143 """Return the names of all active rules.""" 

144 rules = { 

145 chain: self[chain].ruler.get_all_rules() 

146 for chain in ["core", "block", "inline"] 

147 } 

148 rules["inline2"] = self.inline.ruler2.get_all_rules() 

149 return rules 

150 

151 def get_active_rules(self) -> dict[str, list[str]]: 

152 """Return the names of all active rules.""" 

153 rules = { 

154 chain: self[chain].ruler.get_active_rules() 

155 for chain in ["core", "block", "inline"] 

156 } 

157 rules["inline2"] = self.inline.ruler2.get_active_rules() 

158 return rules 

159 

160 def enable( 

161 self, names: str | Iterable[str], ignoreInvalid: bool = False 

162 ) -> MarkdownIt: 

163 """Enable list of rules. (chainable) 

164 

165 :param names: rule name or iterable of rule names to enable. 

166 :param ignoreInvalid: set `true` to ignore errors when rule not found. 

167 

168 It will automatically find appropriate components, 

169 containing rules with given names. If rule not found, and `ignoreInvalid` 

170 not set - throws exception. 

171 

172 Example:: 

173 

174 md = MarkdownIt().enable(['sub', 'sup']).disable('smartquotes') 

175 

176 """ 

177 result = [] 

178 

179 names = [names] if isinstance(names, str) else list(names) 

180 

181 for chain in ["core", "block", "inline"]: 

182 result.extend(self[chain].ruler.enable(names, True)) 

183 result.extend(self.inline.ruler2.enable(names, True)) 

184 

185 missed = [name for name in names if name not in result] 

186 if missed and not ignoreInvalid: 

187 raise ValueError(f"MarkdownIt. Failed to enable unknown rule(s): {missed}") 

188 

189 return self 

190 

191 def disable( 

192 self, names: str | Iterable[str], ignoreInvalid: bool = False 

193 ) -> MarkdownIt: 

194 """The same as [[MarkdownIt.enable]], but turn specified rules off. (chainable) 

195 

196 :param names: rule name or iterable of rule names to disable. 

197 :param ignoreInvalid: set `true` to ignore errors when rule not found. 

198 

199 """ 

200 result = [] 

201 

202 names = [names] if isinstance(names, str) else list(names) 

203 

204 for chain in ["core", "block", "inline"]: 

205 result.extend(self[chain].ruler.disable(names, True)) 

206 result.extend(self.inline.ruler2.disable(names, True)) 

207 

208 missed = [name for name in names if name not in result] 

209 if missed and not ignoreInvalid: 

210 raise ValueError(f"MarkdownIt. Failed to disable unknown rule(s): {missed}") 

211 return self 

212 

213 @contextmanager 

214 def reset_rules(self) -> Generator[None, None, None]: 

215 """A context manager, that will reset the current enabled rules on exit.""" 

216 chain_rules = self.get_active_rules() 

217 yield 

218 for chain, rules in chain_rules.items(): 

219 if chain != "inline2": 

220 self[chain].ruler.enableOnly(rules) 

221 self.inline.ruler2.enableOnly(chain_rules["inline2"]) 

222 

223 def add_render_rule( 

224 self, name: str, function: Callable[..., Any], fmt: str = "html" 

225 ) -> None: 

226 """Add a rule for rendering a particular Token type. 

227 

228 Only applied when ``renderer.__output__ == fmt`` 

229 

230 :param name: must equal the ``type`` of the token(s) this should render 

231 (e.g. ``"heading_open"``, ``"fence"``); it is not an arbitrary label. 

232 If it does not match any token type actually produced by the active 

233 rules, ``function`` will silently never be called. 

234 """ 

235 if self.renderer.__output__ == fmt: 

236 self.renderer.rules[name] = function.__get__(self.renderer) # type: ignore 

237 

238 def use( 

239 self, plugin: Callable[..., None], *params: Any, **options: Any 

240 ) -> MarkdownIt: 

241 """Load specified plugin with given params into current parser instance. (chainable) 

242 

243 It's just a sugar to call `plugin(md, params)` with curring. 

244 

245 Example:: 

246 

247 def func(tokens, idx): 

248 tokens[idx].content = tokens[idx].content.replace('foo', 'bar') 

249 md = MarkdownIt().use(plugin, 'foo_replace', 'text', func) 

250 

251 """ 

252 plugin(self, *params, **options) 

253 return self 

254 

255 def parse(self, src: str, env: EnvType | None = None) -> list[Token]: 

256 """Parse the source string to a token stream 

257 

258 :param src: source string 

259 :param env: environment sandbox 

260 

261 Parse input string and return list of block tokens (special token type 

262 "inline" will contain list of inline tokens). 

263 

264 `env` is used to pass data between "distributed" rules and return additional 

265 metadata like reference info, needed for the renderer. It also can be used to 

266 inject data in specific cases. Usually, you will be ok to pass `{}`, 

267 and then pass updated object to renderer. 

268 """ 

269 env = {} if env is None else env 

270 if not isinstance(env, MutableMapping): 

271 raise TypeError(f"Input data should be a MutableMapping, not {type(env)}") 

272 if not isinstance(src, str): 

273 raise TypeError(f"Input data should be a string, not {type(src)}") 

274 state = StateCore(src, self, env) 

275 self.core.process(state) 

276 return state.tokens 

277 

278 def render(self, src: str, env: EnvType | None = None) -> Any: 

279 """Render markdown string into html. It does all magic for you :). 

280 

281 :param src: source string 

282 :param env: environment sandbox 

283 :returns: The output of the loaded renderer 

284 

285 `env` can be used to inject additional metadata (`{}` by default). 

286 But you will not need it with high probability. See also comment 

287 in [[MarkdownIt.parse]]. 

288 """ 

289 env = {} if env is None else env 

290 return self.renderer.render(self.parse(src, env), self.options, env) 

291 

292 def parseInline(self, src: str, env: EnvType | None = None) -> list[Token]: 

293 """The same as [[MarkdownIt.parse]] but skip all block rules. 

294 

295 :param src: source string 

296 :param env: environment sandbox 

297 

298 It returns the 

299 block tokens list with the single `inline` element, containing parsed inline 

300 tokens in `children` property. Also updates `env` object. 

301 """ 

302 env = {} if env is None else env 

303 if not isinstance(env, MutableMapping): 

304 raise TypeError(f"Input data should be an MutableMapping, not {type(env)}") 

305 if not isinstance(src, str): 

306 raise TypeError(f"Input data should be a string, not {type(src)}") 

307 state = StateCore(src, self, env) 

308 state.inlineMode = True 

309 self.core.process(state) 

310 return state.tokens 

311 

312 def renderInline(self, src: str, env: EnvType | None = None) -> Any: 

313 """Similar to [[MarkdownIt.render]] but for single paragraph content. 

314 

315 :param src: source string 

316 :param env: environment sandbox 

317 

318 Similar to [[MarkdownIt.render]] but for single paragraph content. Result 

319 will NOT be wrapped into `<p>` tags. 

320 """ 

321 env = {} if env is None else env 

322 return self.renderer.render(self.parseInline(src, env), self.options, env) 

323 

324 # link methods 

325 

326 def validateLink(self, url: str) -> bool: 

327 """Validate if the URL link is allowed in output. 

328 

329 This validator can prohibit more than really needed to prevent XSS. 

330 It's a tradeoff to keep code simple and to be secure by default. 

331 

332 Note: the url should be normalized at this point, and existing entities decoded. 

333 """ 

334 return normalize_url.validateLink(url) 

335 

336 def normalizeLink(self, url: str) -> str: 

337 """Normalize destination URLs in links 

338 

339 :: 

340 

341 [label]: destination 'title' 

342 ^^^^^^^^^^^ 

343 """ 

344 return normalize_url.normalizeLink(url) 

345 

346 def normalizeLinkText(self, link: str) -> str: 

347 """Normalize autolink content 

348 

349 :: 

350 

351 <destination> 

352 ~~~~~~~~~~~ 

353 """ 

354 return normalize_url.normalizeLinkText(link)