aboutsummaryrefslogtreecommitdiffstats
path: root/markdown.py
diff options
context:
space:
mode:
authorWaylan Limberg <waylan@gmail.com>2008-03-10 03:56:33 +0000
committerWaylan Limberg <waylan@gmail.com>2008-03-10 03:56:33 +0000
commit16b98682e6ee2771ae2df748e50146684115fcb3 (patch)
tree4275e53da68e95b5b86792568afb0a39bac2b649 /markdown.py
parentc33ffe7dcd587b6f174d9f40049f43e628926b91 (diff)
downloadmarkdown-16b98682e6ee2771ae2df748e50146684115fcb3.tar.gz
markdown-16b98682e6ee2771ae2df748e50146684115fcb3.tar.bz2
markdown-16b98682e6ee2771ae2df748e50146684115fcb3.zip
Edited existing docstrings to more closely conform to PEP 257 and to contain markdown formatting. Still a lot of documentation improvments to go.
Diffstat (limited to 'markdown.py')
-rw-r--r--markdown.py286
1 files changed, 180 insertions, 106 deletions
diff --git a/markdown.py b/markdown.py
index 3dc8f00..b63c9fe 100644
--- a/markdown.py
+++ b/markdown.py
@@ -1,9 +1,4 @@
-#!/usr/bin/env python
-
-version = "1.7"
-version_info = (1,7,0,"rc-2")
-__revision__ = "$Rev$"
-
+#!/usr/bin/python
"""
Python-Markdown
===============
@@ -23,13 +18,20 @@ Started by [Manfred Stienstra](http://www.dwerg.net/). Continued and
maintained by [Yuri Takhteyev](http://www.freewisdom.org) and [Waylan
Limberg](http://achinghead.com/).
-Contact: yuri [at] freewisdom.org
- waylan [at] gmail.com
+Contact:
-License: GPL 2 (http://www.gnu.org/copyleft/gpl.html) or BSD
+* <yuri@freewisdom.org>
+* <waylan@gmail.com>
+
+License: [GPL 2](http://www.gnu.org/copyleft/gpl.html) or BSD
"""
+version = "1.7"
+version_info = (1,7,0,"rc-2")
+__revision__ = "$Rev$"
+
+
import re, sys, codecs
@@ -419,6 +421,7 @@ class TextPreprocessor:
either the same pointer or a pointer to a new string.
TextPreprocessors must extend markdown.TextPreprocessor.
+
'''
def run(self, text):
@@ -434,6 +437,7 @@ class Preprocessor:
either the same pointer or a pointer to a new list.
Preprocessors must extend markdown.Preprocessor.
+
'''
def run(self, lines):
@@ -541,8 +545,8 @@ HTML_BLOCK_PREPROCESSOR = HtmlBlockPreprocessor()
class HeaderPreprocessor(Preprocessor):
"""
- Replaces underlined headers with hashed headers to avoid
- the nead for lookahead later.
+ Replaces underlined headers with hashed headers to avoid
+ the nead for lookahead later.
"""
def run (self, lines):
@@ -935,6 +939,7 @@ class Postprocessor:
There are currently no standard post-processors, but the footnote
extension uses one.
+
'''
def run(self, dom):
@@ -950,6 +955,7 @@ class TextPostprocessor:
text string, modifies it as necessary and returns a text string.
TextPostprocessors must extend markdown.TextPostprocessor.
+
'''
def run(self, text):
@@ -993,22 +999,29 @@ RAWHTMLTEXTPOSTPROCESSOR = RawHtmlTextPostprocessor()
"""
class HtmlStash:
- """This class is used for stashing HTML objects that we extract
- in the beginning and replace with place-holders."""
+ """
+ This class is used for stashing HTML objects that we extract
+ in the beginning and replace with place-holders.
+ """
def __init__ (self):
self.html_counter = 0 # for counting inline html segments
self.rawHtmlBlocks=[]
def store(self, html, safe=False):
- """Saves an HTML segment for later reinsertion. Returns a
- placeholder string that needs to be inserted into the
- document.
-
- @param html: an html segment
- @param safe: label an html segment as safe for safemode
- @param inline: label a segmant as inline html
- @returns : a placeholder string """
+ """
+ Saves an HTML segment for later reinsertion. Returns a
+ placeholder string that needs to be inserted into the
+ document.
+
+ Keyword arguments:
+
+ * html: an html segment
+ * safe: label an html segment as safe for safemode
+
+ Returns : a placeholder string
+
+ """
self.rawHtmlBlocks.append((html, safe))
placeholder = HTML_PLACEHOLDER % self.html_counter
self.html_counter += 1
@@ -1019,16 +1032,22 @@ class BlockGuru:
def _findHead(self, lines, fn, allowBlank=0):
- """Functional magic to help determine boundaries of indented
- blocks.
+ """
+ Functional magic to help determine boundaries of indented
+ blocks.
- @param lines: an array of strings
- @param fn: a function that returns a substring of a string
- if the string matches the necessary criteria
- @param allowBlank: specifies whether it's ok to have blank
- lines between matching functions
- @returns: a list of post processes items and the unused
- remainder of the original list"""
+ Keyword arguments:
+
+ * lines: an array of strings
+ * fn: a function that returns a substring of a string
+ if the string matches the necessary criteria
+ * allowBlank: specifies whether it's ok to have blank
+ lines between matching functions
+
+ Returns: a list of post processes items and the unused
+ remainder of the original list
+
+ """
items = []
item = -1
@@ -1116,8 +1135,9 @@ inline patterns or a combination of the three.
"""
class CorePatterns:
- """This class is scheduled for removal as part of a refactoring
- effort."""
+ """
+ This class is scheduled for removal as part of a refactoring effort.
+ """
patterns = {
'header': r'(#*)([^#]*)(#*)', # # A title
@@ -1146,24 +1166,29 @@ RE = CorePatterns()
class Markdown:
- """ Markdown formatter class for creating an html document from
- Markdown text """
+ """
+ Markdown formatter class for creating an html document from Markdown text.
+ """
def __init__(self, source=None, # depreciated
extensions=[],
extension_configs={},
safe_mode = False):
- """Creates a new Markdown instance.
+ """
+ Creates a new Markdown instance.
- @param source: The text in Markdown format. Depreciated!
- @param extensions: A list of extensions.
- If they are of type string, the module
- mdx_name.py will be loaded
- If they are a subclass of markdown.Extension,
- they will be used as-is
- @param extension-configs: Configuration setting for extensions.
- @param safe_mode: Disallow raw html. """
+ Keyword arguments:
+
+ * source: The text in Markdown format. Depreciated!
+ * extensions: A list of extensions.
+ If they are of type string, the module mdx_name.py will be loaded.
+ If they are a subclass of markdown.Extension, they will be used
+ as-is.
+ * extension-configs: Configuration setting for extensions.
+ * safe_mode: Disallow raw html.
+
+ """
self.source = source
if source is not None:
@@ -1224,13 +1249,16 @@ class Markdown:
def registerExtensions(self, extensions, configs):
- """ Register extensions with this instance of Markdown.
+ """
+ Register extensions with this instance of Markdown.
- @param extensions A list of extensions, which can either
- be strings or objects. See the docstring
- on Markdown.
- @param configs A dictionary mapping module names to config
- options. """
+ Keyword aurguments:
+
+ * extensions: A list of extensions, which can either
+ be strings or objects. See the docstring on Markdown.
+ * configs: A dictionary mapping module names to config options.
+
+ """
for ext in extensions:
if isinstance(ext, basestring):
@@ -1250,8 +1278,9 @@ class Markdown:
self.registeredExtensions.append(extension)
def reset(self):
- """Resets all state variables so that we can start
- with a new text."""
+ """
+ Resets all state variables so that we can start with a new text.
+ """
self.references={}
self.htmlStash = HtmlStash()
@@ -1272,7 +1301,9 @@ class Markdown:
def _transform(self):
"""Transforms the Markdown text into a XHTML body document
- @returns: A NanoDom Document """
+ Returns: A NanoDom Document
+
+ """
# Setup the document
@@ -1317,18 +1348,22 @@ class Markdown:
def _processSection(self, parent_elem, lines,
inList = 0, looseList = 0):
+ """
+ Process a section of a source document, looking for high
+ level structural elements like lists, block quotes, code
+ segments, html blocks, etc. Some those then get stripped
+ of their high level markup (e.g. get unindented) and the
+ lower-level markup is processed recursively.
- """Process a section of a source document, looking for high
- level structural elements like lists, block quotes, code
- segments, html blocks, etc. Some those then get stripped
- of their high level markup (e.g. get unindented) and the
- lower-level markup is processed recursively.
-
- @param parent_elem: A NanoDom element to which the content
- will be added
- @param lines: a list of lines
- @param inList: a level
- @returns: None"""
+ Keyword arguments:
+
+ * parent_elem: A NanoDom element to which the content will be added.
+ * lines: a list of lines
+ * inList: a level
+
+ Returns: None
+
+ """
# Loop through lines until none left.
while lines:
@@ -1430,14 +1465,20 @@ class Markdown:
def _processList(self, parent_elem, lines, inList, listexpr, tag):
- """Given a list of document lines starting with a list item,
- finds the end of the list, breaks it up, and recursively
- processes each list item and the remainder of the text file.
+ """
+ Given a list of document lines starting with a list item,
+ finds the end of the list, breaks it up, and recursively
+ processes each list item and the remainder of the text file.
- @param parent_elem: A dom element to which the content will be added
- @param lines: a list of lines
- @param inList: a level
- @returns: None"""
+ Keyword arguments:
+
+ * parent_elem: A dom element to which the content will be added
+ * lines: a list of lines
+ * inList: a level
+
+ Returns: None
+
+ """
ul = self.doc.createElement(tag) # ul might actually be '<ol>'
parent_elem.appendChild(ul)
@@ -1515,10 +1556,12 @@ class Markdown:
def _linesUntil(self, lines, condition):
- """ A utility function to break a list of lines upon the
- first line that satisfied a condition. The condition
- argument should be a predicate function.
- """
+ """
+ A utility function to break a list of lines upon the
+ first line that satisfied a condition. The condition
+ argument should be a predicate function.
+
+ """
i = -1
for line in lines:
@@ -1529,15 +1572,21 @@ class Markdown:
return lines[:i], lines[i:]
def _processQuote(self, parent_elem, lines, inList):
- """Given a list of document lines starting with a quote finds
- the end of the quote, unindents it and recursively
- processes the body of the quote and the remainder of the
- text file.
+ """
+ Given a list of document lines starting with a quote finds
+ the end of the quote, unindents it and recursively
+ processes the body of the quote and the remainder of the
+ text file.
- @param parent_elem: DOM element to which the content will be added
- @param lines: a list of lines
- @param inList: a level
- @returns: None """
+ Keyword arguments:
+
+ * parent_elem: DOM element to which the content will be added
+ * lines: a list of lines
+ * inList: a level
+
+ Returns: None
+
+ """
dequoted = []
i = 0
@@ -1568,15 +1617,21 @@ class Markdown:
def _processCodeBlock(self, parent_elem, lines, inList):
- """Given a list of document lines starting with a code block
- finds the end of the block, puts it into the dom verbatim
- wrapped in ("<pre><code>") and recursively processes the
- the remainder of the text file.
+ """
+ Given a list of document lines starting with a code block
+ finds the end of the block, puts it into the dom verbatim
+ wrapped in ("<pre><code>") and recursively processes the
+ the remainder of the text file.
- @param parent_elem: DOM element to which the content will be added
- @param lines: a list of lines
- @param inList: a level
- @returns: None"""
+ Keyword arguments:
+
+ * parent_elem: DOM element to which the content will be added
+ * lines: a list of lines
+ * inList: a level
+
+ Returns: None
+
+ """
detabbed, theRest = self.blockGuru.detectTabbed(lines)
@@ -1592,15 +1647,21 @@ class Markdown:
def _handleInline (self, line, patternIndex=0):
- """Transform a Markdown line with inline elements to an XHTML
+ """
+ Transform a Markdown line with inline elements to an XHTML
fragment.
This function uses auxiliary objects called inline patterns.
See notes on inline patterns above.
- @param line: A line of Markdown text
- @param patternIndex: The index of the inlinePattern to start with
- @return: A list of NanoDom nodes """
+ Keyword arguments:
+
+ * line: A line of Markdown text
+ * patternIndex: The index of the inlinePattern to start with
+
+ Return: A list of NanoDom nodes
+
+ """
parts = [line]
@@ -1637,15 +1698,18 @@ class Markdown:
def _applyPattern(self, line, pattern, patternIndex):
- """ Given a pattern name, this function checks if the line
+ """
+ Given a pattern name, this function checks if the line
fits the pattern, creates the necessary elements, and returns
back a list consisting of NanoDom elements and/or strings.
- @param line: the text to be processed
- @param pattern: the pattern to be checked
+ Keyword arguments:
+
+ * line: the text to be processed
+ * pattern: the pattern to be checked
- @returns: the appropriate newly created NanoDom element if the
- pattern matches, None otherwise.
+ Returns: The appropriate newly created NanoDom element if the
+ pattern matches, None otherwise.
"""
# match the line to pattern's pre-compiled reg exp.
@@ -1704,10 +1768,17 @@ class Markdown:
else:
return None
- def convert (self, source = None):
- """Return the document in XHTML format.
+ def convert (self, source=None):
+ """
+ Return the document in XHTML format.
+
+ Keyword arguments:
+
+ * source: An ascii or unicode string of Markdown formated text.
- @returns: A serialized XHTML body."""
+ Returns: A serialized XHTML body.
+
+ """
if source is not None: #Allow blank string
self.source = source
@@ -1825,9 +1896,12 @@ class Extension:
def load_extension(ext_name, configs = []):
- """ Load extention by name, then return the module.
- The name may contain arguments.
- Print an error message and exit on failure. """
+ """
+ Load extention by name, then return the module.
+ The name may contain arguments.
+ Print an error message and exit on failure.
+
+ """
# I am making the assumption that the order of config options
# does not matter.
@@ -1892,7 +1966,7 @@ def parse_options():
help="print info messages")
parser.add_option("-s", "--safe", dest="safe", default=False,
metavar="SAFE_MODE",
- help="same mode ('replace', 'remove' or 'escape' user's HTML tag)")
+ help="safe mode ('replace', 'remove' or 'escape' user's HTML tag)")
parser.add_option("--noisy",
action="store_const", const=DEBUG, dest="verbose",