Coverage for /pythoncovmergedfiles/medio/medio/usr/local/lib/python3.11/site-packages/markdown/blockparser.py: 97%

1# Python Markdown 

2 

3# A Python implementation of John Gruber's Markdown. 

4 

5# Documentation: https://python-markdown.github.io/ 

6# GitHub: https://github.com/Python-Markdown/markdown/ 

7# PyPI: https://pypi.org/project/Markdown/ 

8 

9# Started by Manfred Stienstra (http://www.dwerg.net/). 

10# Maintained for a few years by Yuri Takhteyev (http://www.freewisdom.org). 

11# Currently maintained by Waylan Limberg (https://github.com/waylan), 

12# Dmitry Shachnev (https://github.com/mitya57) and Isaac Muse (https://github.com/facelessuser). 

13 

14# Copyright 2007-2023 The Python Markdown Project (v. 1.7 and later) 

15# Copyright 2004, 2005, 2006 Yuri Takhteyev (v. 0.2-1.6b) 

16# Copyright 2004 Manfred Stienstra (the original version) 

17 

18# License: BSD (see LICENSE.md for details). 

19 

20""" 

21The block parser handles basic parsing of Markdown blocks. It doesn't concern 

22itself with inline elements such as `**bold**` or `*italics*`, but rather just 

23catches blocks, lists, quotes, etc. 

24 

25The `BlockParser` is made up of a bunch of `BlockProcessors`, each handling a 

26different type of block. Extensions may add/replace/remove `BlockProcessors` 

27as they need to alter how Markdown blocks are parsed. 

28""" 

29 

30from __future__ import annotations 

31 

32import xml.etree.ElementTree as etree 

33from typing import TYPE_CHECKING, Iterable, Any 

34from . import util 

35 

36if TYPE_CHECKING: # pragma: no cover 

37 from markdown import Markdown 

38 from .blockprocessors import BlockProcessor 

39 

40 

41class State(list): 

42 """ Track the current and nested state of the parser. 

43 

44 This utility class is used to track the state of the `BlockParser` and 

45 support multiple levels if nesting. It's just a simple API wrapped around 

46 a list. Each time a state is set, that state is appended to the end of the 

47 list. Each time a state is reset, that state is removed from the end of 

48 the list. 

49 

50 Therefore, each time a state is set for a nested block, that state must be 

51 reset when we back out of that level of nesting or the state could be 

52 corrupted. 

53 

54 While all the methods of a list object are available, only the three 

55 defined below need be used. 

56 

57 """ 

58 

59 def set(self, state: Any): 

60 """ Set a new state. """ 

61 self.append(state) 

62 

63 def reset(self) -> None: 

64 """ Step back one step in nested state. """ 

65 self.pop() 

66 

67 def isstate(self, state: Any) -> bool: 

68 """ Test that top (current) level is of given state. """ 

69 if len(self): 

70 return self[-1] == state 

71 else: 

72 return False 

73 

74 

75class BlockParser: 

76 """ Parse Markdown blocks into an `ElementTree` object. 

77 

78 A wrapper class that stitches the various `BlockProcessors` together, 

79 looping through them and creating an `ElementTree` object. 

80 

81 """ 

82 

83 def __init__(self, md: Markdown): 

84 """ Initialize the block parser. 

85 

86 Arguments: 

87 md: A Markdown instance. 

88 

89 Attributes: 

90 BlockParser.md (Markdown): A Markdown instance. 

91 BlockParser.state (State): Tracks the nesting level of current location in document being parsed. 

92 BlockParser.blockprocessors (util.Registry): A collection of 

93 [`blockprocessors`][markdown.blockprocessors]. 

94 

95 """ 

96 self.blockprocessors: util.Registry[BlockProcessor] = util.Registry() 

97 self.state = State() 

98 self.md = md 

99 

100 def parseDocument(self, lines: Iterable[str]) -> etree.ElementTree: 

101 """ Parse a Markdown document into an `ElementTree`. 

102 

103 Given a list of lines, an `ElementTree` object (not just a parent 

104 `Element`) is created and the root element is passed to the parser 

105 as the parent. The `ElementTree` object is returned. 

106 

107 This should only be called on an entire document, not pieces. 

108 

109 Arguments: 

110 lines: A list of lines (strings). 

111 

112 Returns: 

113 An element tree. 

114 """ 

115 # Create an `ElementTree` from the lines 

116 self.root = etree.Element(self.md.doc_tag) 

117 self.parseChunk(self.root, '\n'.join(lines)) 

118 return etree.ElementTree(self.root) 

119 

120 def parseChunk(self, parent: etree.Element, text: str) -> None: 

121 """ Parse a chunk of Markdown text and attach to given `etree` node. 

122 

123 While the `text` argument is generally assumed to contain multiple 

124 blocks which will be split on blank lines, it could contain only one 

125 block. Generally, this method would be called by extensions when 

126 block parsing is required. 

127 

128 The `parent` `etree` Element passed in is altered in place. 

129 Nothing is returned. 

130 

131 Arguments: 

132 parent: The parent element. 

133 text: The text to parse. 

134 

135 """ 

136 self.parseBlocks(parent, text.split('\n\n')) 

137 

138 def parseBlocks(self, parent: etree.Element, blocks: list[str]) -> None: 

139 """ Process blocks of Markdown text and attach to given `etree` node. 

140 

141 Given a list of `blocks`, each `blockprocessor` is stepped through 

142 until there are no blocks left. While an extension could potentially 

143 call this method directly, it's generally expected to be used 

144 internally. 

145 

146 This is a public method as an extension may need to add/alter 

147 additional `BlockProcessors` which call this method to recursively 

148 parse a nested block. 

149 

150 Arguments: 

151 parent: The parent element. 

152 blocks: The blocks of text to parse. 

153 

154 """ 

155 while blocks: 

156 for processor in self.blockprocessors: 

157 if processor.test(parent, blocks[0]): 

158 if processor.run(parent, blocks) is not False: 

159 # run returns True or None 

160 break