From ebdae2e503d05e1b142bc404bbc9de97bbe623b8 Mon Sep 17 00:00:00 2001 From: Waylan Limberg Date: Wed, 12 Mar 2008 19:52:57 +0000 Subject: Added docstrings to pre/post processors and misc aux functions. --- markdown.py | 78 ++++++++++++++++++++++++++++++++++++++++++++++--------------- 1 file changed, 59 insertions(+), 19 deletions(-) diff --git a/markdown.py b/markdown.py index 1a14432..3a48745 100644 --- a/markdown.py +++ b/markdown.py @@ -462,7 +462,7 @@ There are two types of preprocessors: TextPreprocessor and Preprocessor. class TextPreprocessor: - ''' + """ TextPreprocessors are run before the text is broken into lines. Each TextPreprocessor implements a "run" method that takes a pointer to a @@ -471,14 +471,20 @@ class TextPreprocessor: TextPreprocessors must extend markdown.TextPreprocessor. - ''' + """ def run(self, text): + """ + Each subclass of TextPreprocessor should override the `run` method, + which takes the document text as a single string and returns the + (possibly modified) document as a single string. + + """ pass class Preprocessor: - ''' + """ Preprocessors are run after the text is broken into lines. Each preprocessor implements a "run" method that takes a pointer to a @@ -487,14 +493,22 @@ class Preprocessor: Preprocessors must extend markdown.Preprocessor. - ''' + """ def run(self, lines): + """ + Each subclass of Preprocessor should override the `run` method, which + takes the document as a list of strings split by newlines and returns + the (possibly modified) list of lines. + + """ pass class HtmlBlockPreprocessor(TextPreprocessor): - """Removes html blocks from the source text and stores it.""" + """ + Remove html blocks from the source text and store them for later retrieval. + """ def _get_left_tag(self, block): return block[1:].replace(">", " ", 1).split()[0].lower() @@ -522,6 +536,7 @@ class HtmlBlockPreprocessor(TextPreprocessor): def run(self, text): + """ Find and remove raw html from text. """ new_blocks = [] text = text.split("\n\n") @@ -594,11 +609,12 @@ HTML_BLOCK_PREPROCESSOR = HtmlBlockPreprocessor() class HeaderPreprocessor(Preprocessor): """ - Replaces underlined headers with hashed headers to avoid + Replace underlined headers with hashed headers to avoid the nead for lookahead later. """ def run (self, lines): + """ Find and replace underlined headers. """ i = -1 while i+1 < len(lines): @@ -628,11 +644,17 @@ HEADER_PREPROCESSOR = HeaderPreprocessor() class LinePreprocessor(Preprocessor): - """Deals with HR lines (needs to be done before processing lists)""" + """ + Convert HR lines to raw html and store (needs to be done before + processing lists). + + """ blockquote_re = re.compile(r'^(> )+') def run (self, lines): + """ Find a store HR lines. """ + for i in range(len(lines)): prefix = '' m = self.blockquote_re.search(lines[i]) @@ -642,7 +664,8 @@ class LinePreprocessor(Preprocessor): return lines def _isLine(self, block): - """Determines if a block should be replaced with an
""" + """Determine if a block should be replaced with an
""" + if block.startswith(" "): return 0 # a code block text = "".join([x for x in block if not x.isspace()]) if len(text) <= 2: @@ -658,12 +681,13 @@ LINE_PREPROCESSOR = LinePreprocessor() class ReferencePreprocessor(Preprocessor): - ''' - Removes reference definitions from the text and stores them for later use. - ''' + """ + Remove reference definitions from the text and store them for later use. + + """ def run (self, lines): - + """ Remove and store reference defs. """ new_text = []; for line in lines: m = RE.regExp['reference-def'].match(line) @@ -977,7 +1001,7 @@ There are two types of post-processors: Postprocessor and TextPostprocessor class Postprocessor: - ''' + """ Postprocessors are run before the dom it converted back into text. Each Postprocessor implements a "run" method that takes a pointer to a @@ -989,15 +1013,21 @@ class Postprocessor: There are currently no standard post-processors, but the footnote extension uses one. - ''' + """ def run(self, dom): + """ + Subclasses of Postprocessor should implement a `run` method, which + takes a NanoDOm document and returns a (possably modified) NanoDom + document. + + """ pass class TextPostprocessor: - ''' + """ TextPostprocessors are run after the dom it converted back into text. Each TextPostprocessor implements a "run" method that takes a pointer to a @@ -1005,18 +1035,26 @@ class TextPostprocessor: TextPostprocessors must extend markdown.TextPostprocessor. - ''' + """ def run(self, text): + """ + Subclasses of TextPostprocessor should implement a `run` method, which + takes the html document as a single text string and returns a + (possably modified) string. + + """ pass class RawHtmlTextPostprocessor(TextPostprocessor): - + """ Restore raw html to the document. """ def __init__(self): pass def run(self, text): + """ Iterate over html stash and restore "safe" html. """ + for i in range(self.stash.html_counter): html, safe = self.stash.rawHtmlBlocks[i] if self.safeMode and not safe: @@ -1033,7 +1071,7 @@ class RawHtmlTextPostprocessor(TextPostprocessor): return text def escape(self, html): - ''' Basic html escaping ''' + """ Basic html escaping """ html = html.replace('&', '&') html = html.replace('<', '<') html = html.replace('>', '>') @@ -1054,6 +1092,7 @@ class HtmlStash: """ def __init__ (self): + """ Create a HtmlStash. """ self.html_counter = 0 # for counting inline html segments self.rawHtmlBlocks=[] @@ -1078,6 +1117,7 @@ class HtmlStash: class BlockGuru: + """ Parse document for block level constructs (paragraphs, lists, etc.).""" def _findHead(self, lines, fn, allowBlank=0): @@ -1155,7 +1195,7 @@ class BlockGuru: def detectTabbed(self, lines): - + """ Find indented text and remove indent before further proccesing. """ return self._findHead(lines, self.detabbed_fn, allowBlank = 1) -- cgit v1.2.3