Home       Trees       Index       Help   

epydoc 3.0alpha2

Package epydoc :: Package markup :: Module epytext
[hide private]
[frames] | no frames]

Module epytext
source code

Parser for epytext strings. Epytext is a lightweight markup whose primary intended application is Python documentation strings. This parser converts Epytext strings to a XML/DOM representation. Epytext strings can contain the following structural blocks: Additionally, the following inline regions may be used within para blocks: The returned DOM tree will conform to the the following Document Type Description: 
  <!ENTITY % colorized '(code | math | index | italic |
                         bold | uri | link | symbol)*'>

  <!ELEMENT epytext ((para | literalblock | doctestblock |
                     section | ulist | olist)*, fieldlist?)>

  <!ELEMENT para (#PCDATA | %colorized;)*>

  <!ELEMENT section (para | listblock | doctestblock |
                     section | ulist | olist)+>

  <!ELEMENT fieldlist (field+)>
  <!ELEMENT field (tag, arg?, (para | listblock | doctestblock)
                               ulist | olist)+)>
  <!ELEMENT tag (#PCDATA)>
  <!ELEMENT arg (#PCDATA)>
  
  <!ELEMENT literalblock (#PCDATA)>
  <!ELEMENT doctestblock (#PCDATA)>

  <!ELEMENT ulist (li+)>
  <!ELEMENT olist (li+)>
  <!ELEMENT li (para | literalblock | doctestblock | ulist | olist)+>
  <!ATTLIST li bullet NMTOKEN #IMPLIED>
  <!ATTLIST olist start NMTOKEN #IMPLIED>

  <!ELEMENT uri     (name, target)>
  <!ELEMENT link    (name, target)>
  <!ELEMENT name    (#PCDATA | %colorized;)*>
  <!ELEMENT target  (#PCDATA)>
  
  <!ELEMENT code    (#PCDATA | %colorized;)*>
  <!ELEMENT math    (#PCDATA | %colorized;)*>
  <!ELEMENT italic  (#PCDATA | %colorized;)*>
  <!ELEMENT bold    (#PCDATA | %colorized;)*>
  <!ELEMENT indexed (#PCDATA | %colorized;)>

  <!ELEMENT symbol (#PCDATA)>


Classes [hide private]
Token Tokens are an intermediate data structure used while constructing the structuring DOM tree for a formatted docstring.
TokenizationError An error generated while tokenizing a formatted documentation string.
StructuringError An error generated while structuring a formatted documentation string.
ColorizingError An error generated while colorizing a paragraph.
ParsedEpytextDocstring  

Functions [hide private]
xml.dom.minidom.Document parse(str, errors=None)
Return a DOM tree encoding the contents of an epytext string.
  _pop_completed_blocks(token, stack, indent_stack)
Pop any completed blocks off the stack.
  _add_para(doc, para_token, stack, indent_stack, errors)
Colorize the given paragraph, and add it to the DOM tree.
  _add_section(doc, heading_token, stack, indent_stack, errors)
Add a new section to the DOM tree, with the given heading.
  _add_list(doc, bullet_token, stack, indent_stack, errors)
Add a new list item or field to the DOM tree, with the given bullet or field tag.
int _tokenize_doctest(lines, start, block_indent, tokens, errors)
Construct a Token containing the doctest block starting at lines[start], and append it to tokens.
int _tokenize_literal(lines, start, block_indent, tokens, errors)
Construct a Token containing the literal block starting at lines[start], and append it to tokens.
int _tokenize_listart(lines, start, bullet_indent, tokens, errors)
Construct Tokens for the bullet and the first paragraph of the list item (or field) starting at lines[start], and append them to tokens.
int _tokenize_para(lines, start, para_indent, tokens, errors)
Construct a Token containing the paragraph starting at lines[start], and append it to tokens.
list of Token _tokenize(str, errors)
Split a given formatted docstring into an ordered list of Tokens, according to the epytext markup rules.
Element _colorize(doc, token, errors, tagName='para')
Given a string containing the contents of a paragraph, produce a DOM Element encoding that paragraph.
  _colorize_graph(doc, graph, token, end, errors)
Eg:
  _colorize_link(doc, link, token, end, errors)
string to_epytext(tree, indent=0, seclevel=0)
Convert a DOM document encoding epytext back to an epytext string.
string to_plaintext(tree, indent=0, seclevel=0)
Convert a DOM document encoding epytext to a string representation.
string to_debug(tree, indent=4, seclevel=0)
Convert a DOM document encoding epytext back to an epytext string, annotated with extra debugging information.
xml.dom.minidom.Document pparse(str, show_warnings=1, show_errors=1, stream=sys.stderr)
Pretty-parse the string.
xml.dom.minidom.Document parse_as_literal(str)
Return a DOM document matching the epytext DTD, containing a single literal block.
xml.dom.minidom.Document parse_as_para(str)
Return a DOM document matching the epytext DTD, containing a single paragraph.
ParsedDocstring parse_docstring(docstring, errors, **options)
Parse the given docstring, which is formatted using epytext; and return a ParsedDocstring representation of its contents.

Variables [hide private]
_HEADING_CHARS  
_ESCAPES  
SYMBOLS A list of the of escape symbols that are supported by epydoc.
_SYMBOLS  
__doc__  
_COLORIZING_TAGS  
_LINK_COLORIZING_TAGS  
_BULLET_RE  
_LIST_BULLET_RE  
_FIELD_BULLET_RE  
_BRACE_RE  
_TARGET_RE  
GRAPH_TYPES  

Function Details [hide private]

parse(str, errors=None)

source code 
call graph 
Return a DOM tree encoding the contents of an epytext string. Any errors generated during parsing will be stored in errors.
Parameters:
  • str (string) - The epytext string to parse.
  • errors (list of ParseError) - A list where any errors generated during parsing will be stored. If no list is specified, then fatal errors will generate exceptions, and non-fatal errors will be ignored.
Returns: xml.dom.minidom.Document
a DOM tree encoding the contents of an epytext string.
Raises:
  • ParseError - If errors is None and an error is encountered while parsing.

_pop_completed_blocks(token, stack, indent_stack)

source code 
call graph 
Pop any completed blocks off the stack. This includes any blocks that we have dedented past, as well as any list item blocks that we've dedented to. The top element on the stack should only be a list if we're about to start a new list item (i.e., if the next token is a bullet).

_add_para(doc, para_token, stack, indent_stack, errors)

source code 
call graph 
Colorize the given paragraph, and add it to the DOM tree.

_add_section(doc, heading_token, stack, indent_stack, errors)

source code 
call graph 
Add a new section to the DOM tree, with the given heading.

_add_list(doc, bullet_token, stack, indent_stack, errors)

source code 
call graph 
Add a new list item or field to the DOM tree, with the given bullet or field tag. When necessary, create the associated list.

_tokenize_doctest(lines, start, block_indent, tokens, errors)

source code 
call graph 
Construct a Token containing the doctest block starting at lines[start], and append it to tokens. block_indent should be the indentation of the doctest block. Any errors generated while tokenizing the doctest block will be appended to errors.
Parameters:
  • lines (list of string) - The list of lines to be tokenized
  • start (int) - The index into lines of the first line of the doctest block to be tokenized.
  • block_indent (int) - The indentation of lines[start]. This is the indentation of the doctest block.
  • errors (list of ParseError) - A list where any errors generated during parsing will be stored. If no list is specified, then errors will generate exceptions.
Returns: int
The line number of the first line following the doctest block.

_tokenize_literal(lines, start, block_indent, tokens, errors)

source code 
call graph 
Construct a Token containing the literal block starting at lines[start], and append it to tokens. block_indent should be the indentation of the literal block. Any errors generated while tokenizing the literal block will be appended to errors.
Parameters:
  • lines (list of string) - The list of lines to be tokenized
  • start (int) - The index into lines of the first line of the literal block to be tokenized.
  • block_indent (int) - The indentation of lines[start]. This is the indentation of the literal block.
  • errors (list of ParseError) - A list of the errors generated by parsing. Any new errors generated while will tokenizing this paragraph will be appended to this list.
Returns: int
The line number of the first line following the literal block.

_tokenize_listart(lines, start, bullet_indent, tokens, errors)

source code 
call graph 
Construct Tokens for the bullet and the first paragraph of the list item (or field) starting at lines[start], and append them to tokens. bullet_indent should be the indentation of the list item. Any errors generated while tokenizing will be appended to errors.
Parameters:
  • lines (list of string) - The list of lines to be tokenized
  • start (int) - The index into lines of the first line of the list item to be tokenized.
  • bullet_indent (int) - The indentation of lines[start]. This is the indentation of the list item.
  • errors (list of ParseError) - A list of the errors generated by parsing. Any new errors generated while will tokenizing this paragraph will be appended to this list.
Returns: int
The line number of the first line following the list item's first paragraph.

_tokenize_para(lines, start, para_indent, tokens, errors)

source code 
call graph 
Construct a Token containing the paragraph starting at lines[start], and append it to tokens. para_indent should be the indentation of the paragraph . Any errors generated while tokenizing the paragraph will be appended to errors.
Parameters:
  • lines (list of string) - The list of lines to be tokenized
  • start (int) - The index into lines of the first line of the paragraph to be tokenized.
  • para_indent (int) - The indentation of lines[start]. This is the indentation of the paragraph.
  • errors (list of ParseError) - A list of the errors generated by parsing. Any new errors generated while will tokenizing this paragraph will be appended to this list.
Returns: int
The line number of the first line following the paragraph.

_tokenize(str, errors)

source code 
call graph 
Split a given formatted docstring into an ordered list of Tokens, according to the epytext markup rules.
Parameters:
  • str (string) - The epytext string
  • errors (list of ParseError) - A list where any errors generated during parsing will be stored. If no list is specified, then errors will generate exceptions.
Returns: list of Token
a list of the Tokens that make up the given string.

_colorize(doc, token, errors, tagName='para')

source code 
call graph 
Given a string containing the contents of a paragraph, produce a DOM Element encoding that paragraph. Colorized regions are represented using DOM Elements, and text is represented using DOM Texts.
Parameters:
  • errors (list of string) - A list of errors. Any newly generated errors will be appended to this list.
  • tagName (string) - The element tag for the DOM Element that should be generated.
Returns: Element
a DOM Element encoding the given paragraph.

_colorize_graph(doc, graph, token, end, errors)

source code 
call graph 
Eg: 
 G{classtree}
 G{classtree x, y, z}
 G{importgraph}

_colorize_link(doc, link, token, end, errors)

source code 
call graph 

to_epytext(tree, indent=0, seclevel=0)

source code 
Convert a DOM document encoding epytext back to an epytext string. This is the inverse operation from parse. I.e., assuming there are no errors, the following is true:
  • parse(to_epytext(tree)) == tree
The inverse is true, except that whitespace, line wrapping, and character escaping may be done differently.
  • to_epytext(parse(str)) == str (approximately)
Parameters:
  • tree (xml.dom.minidom.Document) - A DOM document encoding of an epytext string.
  • indent (int) - The indentation for the string representation of tree. Each line of the returned string will begin with indent space characters.
  • seclevel (int) - The section level that tree appears at. This is used to generate section headings.
Returns: string
The epytext string corresponding to tree.

to_plaintext(tree, indent=0, seclevel=0)

source code 
call graph 
Convert a DOM document encoding epytext to a string representation. This representation is similar to the string generated by to_epytext, but to_plaintext removes inline markup, prints escaped characters in unescaped form, etc.
Parameters:
  • tree (xml.dom.minidom.Document) - A DOM document encoding of an epytext string.
  • indent (int) - The indentation for the string representation of tree. Each line of the returned string will begin with indent space characters.
  • seclevel (int) - The section level that tree appears at. This is used to generate section headings.
Returns: string
The epytext string corresponding to tree.

to_debug(tree, indent=4, seclevel=0)

source code 
Convert a DOM document encoding epytext back to an epytext string, annotated with extra debugging information. This function is similar to to_epytext, but it adds explicit information about where different blocks begin, along the left margin.
Parameters:
  • tree (xml.dom.minidom.Document) - A DOM document encoding of an epytext string.
  • indent (int) - The indentation for the string representation of tree. Each line of the returned string will begin with indent space characters.
  • seclevel (int) - The section level that tree appears at. This is used to generate section headings.
Returns: string
The epytext string corresponding to tree.

pparse(str, show_warnings=1, show_errors=1, stream=sys.stderr)

source code 
Pretty-parse the string. This parses the string, and catches any warnings or errors produced. Any warnings and errors are displayed, and the resulting DOM parse structure is returned.
Parameters:
  • str (string) - The string to parse.
  • show_warnings (boolean) - Whether or not to display non-fatal errors generated by parsing str.
  • show_errors (boolean) - Whether or not to display fatal errors generated by parsing str.
  • stream (stream) - The stream that warnings and errors should be written to.
Returns: xml.dom.minidom.Document
a DOM document encoding the contents of str.
Raises:
  • SyntaxError - If any fatal errors were encountered.

parse_as_literal(str)

source code 
Return a DOM document matching the epytext DTD, containing a single literal block. That literal block will include the contents of the given string. This method is typically used as a fall-back when the parser fails.
Parameters:
  • str (string) - The string which should be enclosed in a literal block.
Returns: xml.dom.minidom.Document
A DOM document containing str in a single literal block.

parse_as_para(str)

source code 
Return a DOM document matching the epytext DTD, containing a single paragraph. That paragraph will include the contents of the given string. This can be used to wrap some forms of automatically generated information (such as type names) in paragraphs.
Parameters:
  • str (string) - The string which should be enclosed in a paragraph.
Returns: xml.dom.minidom.Document
A DOM document containing str in a single paragraph.

parse_docstring(docstring, errors, **options)

source code 
call graph 
Parse the given docstring, which is formatted using epytext; and return a ParsedDocstring representation of its contents.
Parameters:
  • docstring (string) - The docstring to parse
  • errors (list of ParseError) - A list where any errors generated during parsing will be stored.
  • options - Extra options. Unknown options are ignored. Currently, no extra options are defined.
Returns: ParsedDocstring

Variables Details [hide private]

_HEADING_CHARS

Value:
'=-~'

_ESCAPES

Value:
{'lb': '{', 'rb': '}'}

SYMBOLS

A list of the of escape symbols that are supported by epydoc. Currently the following symbols are supported:
  • S{<-}=←;
  • S{->}=→;
  • S{^}=↑;
  • S{v}=↓;
  • S{alpha}=α;
  • S{beta}=β;
  • S{gamma}=γ;
  • S{delta}=δ;
  • S{epsilon}=ε;
  • S{zeta}=ζ;
  • S{eta}=η;
  • S{theta}=θ;
  • S{iota}=ι;
  • S{kappa}=κ;
  • S{lambda}=λ;
  • S{mu}=μ;
  • S{nu}=ν;
  • S{xi}=ξ;
  • S{omicron}=ο;
  • S{pi}=π;
  • S{rho}=ρ;
  • S{sigma}=σ;
  • S{tau}=τ;
  • S{upsilon}=υ;
  • S{phi}=φ;
  • S{chi}=χ;
  • S{psi}=ψ;
  • S{omega}=ω;
  • S{Alpha}=Α;
  • S{Beta}=Β;
  • S{Gamma}=Γ;
  • S{Delta}=Δ;
  • S{Epsilon}=Ε;
  • S{Zeta}=Ζ;
  • S{Eta}=Η;
  • S{Theta}=Θ;
  • S{Iota}=Ι;
  • S{Kappa}=Κ;
  • S{Lambda}=Λ;
  • S{Mu}=Μ;
  • S{Nu}=Ν;
  • S{Xi}=Ξ;
  • S{Omicron}=Ο;
  • S{Pi}=Π;
  • S{Rho}=Ρ;
  • S{Sigma}=Σ;
  • S{Tau}=Τ;
  • S{Upsilon}=Υ;
  • S{Phi}=Φ;
  • S{Chi}=Χ;
  • S{Psi}=Ψ;
  • S{Omega}=Ω;
  • S{larr}=←;
  • S{rarr}=→;
  • S{uarr}=↑;
  • S{darr}=↓;
  • S{harr}=↔;
  • S{crarr}=↵;
  • S{lArr}=⇐;
  • S{rArr}=⇒;
  • S{uArr}=⇑;
  • S{dArr}=⇓;
  • S{hArr}=⇔;
  • S{copy}=©;
  • S{times}=×;
  • S{forall}=∀;
  • S{exist}=∃;
  • S{part}=∂;
  • S{empty}=∅;
  • S{isin}=∈;
  • S{notin}=∉;
  • S{ni}=∋;
  • S{prod}=∏;
  • S{sum}=∑;
  • S{prop}=∝;
  • S{infin}=∞;
  • S{ang}=∠;
  • S{and}=∧;
  • S{or}=∨;
  • S{cap}=∩;
  • S{cup}=∪;
  • S{int}=∫;
  • S{there4}=∴;
  • S{sim}=∼;
  • S{cong}=≅;
  • S{asymp}=≈;
  • S{ne}=≠;
  • S{equiv}=≡;
  • S{le}=≤;
  • S{ge}=≥;
  • S{sub}=⊂;
  • S{sup}=⊃;
  • S{nsub}=⊄;
  • S{sube}=⊆;
  • S{supe}=⊇;
  • S{oplus}=⊕;
  • S{otimes}=⊗;
  • S{perp}=⊥;
  • S{infinity}=∞;
  • S{integral}=∫;
  • S{product}=∏;
  • S{>=}=≥;
  • S{<=}=≤
Value:
['<-', '->', '^', 'v', 'alpha', 'beta', 'gamma', 'delta', 'epsilon']

_SYMBOLS

Value:
{'Chi': 1,
 'Epsilon': 1,
 'Eta': 1,
 'Psi': 1,
 'asymp': 1,
 'cup': 1,
 'equiv': 1,
 'ge': 1,
...

__doc__

Value:
__doc__.replace('<<<SYMBOLS>>>',symblist)

_COLORIZING_TAGS

Value:
{'B': 'bold',
 'C': 'code',
 'E': 'escape',
 'G': 'graph',
 'I': 'italic',
 'L': 'link',
 'M': 'math',
 'S': 'symbol',
...

_LINK_COLORIZING_TAGS

Value:
['link', 'uri']

_BULLET_RE

Value:
-( +|$)|(\d+\.)+( +|$)|@\w+( [^\{\}:\n]+)?:( +|$)

_LIST_BULLET_RE

Value:
-( +|$)|(\d+\.)+( +|$)

_FIELD_BULLET_RE

Value:
@\w+( [^\{\}:\n]+)?:( +|$)

_BRACE_RE

Value:
[\{\}]

_TARGET_RE

Value:
^(.*?)\s*<(?:URI:|L:)?([^<>]+)>$

GRAPH_TYPES

Value:
['classtree', 'packagetree', 'importgraph', 'callgraph']

   Home       Trees       Index       Help   

epydoc 3.0alpha2

Generated by Epydoc 3.0alpha2 on Tue Apr 11 17:31:40 2006 http://epydoc.sf.net