Coverage for /pythoncovmergedfiles/medio/medio/usr/local/lib/python3.11/site-packages/mistune/__init__.py: 76%

1""" 

2mistune 

3~~~~~~~ 

4 

5A fast yet powerful Python Markdown parser with renderers and 

6plugins, compatible with CommonMark 0.31.2. 

7 

8Documentation: https://mistune.lepture.com/ 

9""" 

10 

11from functools import lru_cache 

12from typing import Any, Dict, Iterable, List, Literal, Optional, Tuple, Union 

13 

14from .block_parser import BlockParser 

15from .core import BaseRenderer, BlockState, InlineState 

16from .inline_parser import InlineParser 

17from .markdown import Markdown 

18from .plugins import Plugin, PluginRef, import_plugin 

19from .renderers.html import HTMLRenderer 

20from .util import escape, escape_url, safe_entity, unikey 

21 

22RendererRef = Union[Literal["html", "ast"], BaseRenderer] 

23 

24 

25def create_markdown( 

26 escape: Optional[bool] = None, 

27 hard_wrap: bool = False, 

28 renderer: Optional[RendererRef] = "html", 

29 plugins: Optional[Iterable[PluginRef]] = None, 

30) -> Markdown: 

31 """Create a Markdown instance based on the given condition. 

32 

33 :param escape: Boolean. If using html renderer, escape html. When it is 

34 ``None``, the renderer keeps its own escape setting. 

35 :param hard_wrap: Boolean. Break every new line into ``<br>``. 

36 :param renderer: renderer instance, default is HTMLRenderer. 

37 :param plugins: List of plugins. 

38 

39 This method is used when you want to re-use a Markdown instance:: 

40 

41 markdown = create_markdown( 

42 escape=False, 

43 hard_wrap=True, 

44 ) 

45 # re-use markdown function 

46 markdown('.... your text ...') 

47 """ 

48 if renderer == "ast": 

49 # explicit and more similar to 2.x's API 

50 renderer = None 

51 elif renderer == "html": 

52 renderer = HTMLRenderer(escape=True if escape is None else escape) 

53 elif escape is not None and isinstance(renderer, HTMLRenderer): 

54 # a renderer instance was given, honor the explicit escape flag 

55 renderer.escape_enabled = escape 

56 

57 inline = InlineParser(hard_wrap=hard_wrap) 

58 real_plugins: Optional[Iterable[Plugin]] = None 

59 if plugins is not None: 

60 real_plugins = [import_plugin(n) for n in plugins if n != "speedup"] 

61 return Markdown(renderer=renderer, inline=inline, plugins=real_plugins) 

62 

63 

64html: Markdown = create_markdown(escape=False, plugins=["strikethrough", "footnotes", "table"]) 

65 

66 

67_BuiltinRendererRef = Optional[Literal["html", "ast"]] 

68 

69 

70@lru_cache(maxsize=128) 

71def _cached_markdown(escape: bool, renderer: _BuiltinRendererRef, plugins: Tuple[str, ...]) -> Markdown: 

72 return create_markdown(escape=escape, renderer=renderer, plugins=plugins) 

73 

74 

75def markdown( 

76 text: str, 

77 escape: bool = True, 

78 renderer: Optional[RendererRef] = "html", 

79 plugins: Optional[Iterable[Any]] = None, 

80) -> Union[str, List[Dict[str, Any]]]: 

81 plugin_refs = tuple(plugins) if plugins is not None else () 

82 if (renderer is None or (isinstance(renderer, str) and renderer in ("html", "ast"))) and all( 

83 isinstance(plugin, str) for plugin in plugin_refs 

84 ): 

85 md = _cached_markdown(escape, renderer, plugin_refs) 

86 else: 

87 md = create_markdown(escape=escape, renderer=renderer, plugins=plugin_refs) 

88 return md(text) 

89 

90 

91__all__ = [ 

92 "Markdown", 

93 "HTMLRenderer", 

94 "BlockParser", 

95 "BlockState", 

96 "BaseRenderer", 

97 "InlineParser", 

98 "InlineState", 

99 "escape", 

100 "escape_url", 

101 "safe_entity", 

102 "unikey", 

103 "html", 

104 "create_markdown", 

105 "markdown", 

106] 

107 

108__version__ = "3.4.0" 

109__homepage__ = "https://mistune.lepture.com/"