Package epydoc :: Package docwriter :: Module html_colorize :: Class PythonSourceColorizer
[hide private]
[frames] | no frames]

Class PythonSourceColorizer
source code

A class that renders a python module's source code into HTML pages. These HTML pages are intended to be provided along with the API documentation for a module, in case a user wants to learn more about a particular object by examining its source code. Links are therefore generated from the API documentation to the source code pages, and from the source code pages back into the API documentation.

The HTML generated by PythonSourceColorizer has several notable features:

Instance Methods [hide private]
  __init__(self, module_filename, module_name, docindex=None, api_docs=None, url_func=None)
Create a new HTML colorizer for the specified module.
  find_line_offsets(self)
Construct the line_offsets table from self.text.
  lineno_to_html(self)
  colorize(self)
Return an HTML string that renders the source code for the module that was specified in the constructor.
  tokeneater(self, toktype, toktext, (srow, scol), (erow, ecol), line)
A callback function used by tokenize.tokenize to handle each token in the module.
  handle_line(self, line)
Render a single logical line from the module, and write the generated HTML to self.out.
  doclink(self, name, docs)
  doc_descr(self, doc, context)
  doc_kind(self, doc)
  mark_def(self, s, name)
  is_docstring(self, line, i)
  add_line_numbers(self, s, css_class)
  name2url(self, class_name, func_name=None)

Class Variables [hide private]
CSS_CLASSES A look-up table that is used to determine which CSS class should be used to colorize a given token.
START_DEF_BLOCK HTML code for the beginning of a collapsable function or class definition block.
END_DEF_BLOCK HTML code for the end of a collapsable function or class definition block.
UNICODE_CODING_RE A regular expression used to pick out the unicode encoding for the source file.
ADD_DEF_BLOCKS A configuration constant, used to determine whether or not to add collapsable <div> elements for definition blocks.
ADD_LINE_NUMBERS A configuration constant, used to determine whether or not to add line numbers.
ADD_TOOLTIPS A configuration constant, used to determine whether or not to add tooltips for linked names.
GUESS_LINK_TARGETS If true, then try to guess which target is appropriate for linked names; if false, then always open a div asking the user which one they want.
_next_uid  

Instance Variables [hide private]
module_filename The filename of the module we're colorizing.
module_name The dotted name of the module we're colorizing.
name_to_docs A mapping from short names to lists of ValueDoc.
url_func A function that maps APIDoc -> URL
pos The index in text of the last character of the last token we've processed.
line_offsets A list that maps line numbers to character offsets in text.
cur_line A list of (toktype, toktext) for all tokens on the logical line that we are currently processing.
context A list of the names of the class or functions that include the current block.
indents A list of indentation strings for each of the current block's indents.
lineno The line number of the line we're currently processing.
def_name The name of the class or function whose definition started on the previous logical line, or None if the previous logical line was not a class or function definition.

Method Details [hide private]

__init__(self, module_filename, module_name, docindex=None, api_docs=None, url_func=None)
(Constructor)

source code 
Create a new HTML colorizer for the specified module.
Parameters:
  • module_filename - The name of the file containing the module; its text will be loaded from this file.
  • module_name - The dotted name of the module; this will be used to create links back into the API source documentation.

find_line_offsets(self)

source code 
Construct the line_offsets table from self.text.

lineno_to_html(self)

source code 

colorize(self)

source code 
Return an HTML string that renders the source code for the module that was specified in the constructor.

tokeneater(self, toktype, toktext, (srow, scol), (erow, ecol), line)

source code 
A callback function used by tokenize.tokenize to handle each token in the module. tokeneater collects tokens into the self.cur_line list until a complete logical line has been formed; and then calls handle_line to process that line.

handle_line(self, line)

source code 
Render a single logical line from the module, and write the generated HTML to self.out.
Parameters:
  • line - A single logical line, encoded as a list of (toktype,tokttext) pairs corresponding to the tokens in the line.

doclink(self, name, docs)

source code 

doc_descr(self, doc, context)

source code 

doc_kind(self, doc)

source code 

mark_def(self, s, name)

source code 

is_docstring(self, line, i)

source code 

add_line_numbers(self, s, css_class)

source code 

name2url(self, class_name, func_name=None)

source code 

Class Variable Details [hide private]

CSS_CLASSES

A look-up table that is used to determine which CSS class should be used to colorize a given token. The following keys may be used:
  • Any token name (e.g., 'STRING')
  • Any operator token (e.g., '=' or '@').
  • 'KEYWORD' -- Python keywords such as 'for' and 'if'
  • 'DEFNAME' -- the name of a class or function at the top of its definition statement.
  • 'BASECLASS' -- names of base classes at the top of a class definition statement.
  • 'PARAM' -- function parameters
  • 'DOCSTRING' -- docstrings
  • 'DECORATOR' -- decorator names
If no CSS class can be found for a given token, then it won't be marked with any CSS class.
Value:
{'@': 'py-decorator',
 'BASECLASS': 'py-base-class',
 'COMMENT': 'py-comment',
 'DECORATOR': 'py-decorator',
 'DEFNAME': 'py-def-name',
 'DOCSTRING': 'py-docstring',
 'KEYWORD': 'py-keyword',
 'NAME': 'py-name',
...                                                                    
      

START_DEF_BLOCK

HTML code for the beginning of a collapsable function or class definition block. The block contains two <div>...</div> elements -- a collapsed version and an expanded version -- and only one of these elements is visible at any given time. By default, all definition blocks are expanded. This string should be interpolated with the following values:
 (name, indentation, name)
Where name is the anchor name for the function or class; and indentation is a string of whitespace used to indent the ellipsis marker in the collapsed version.
Value:
'<div id="%s-collapsed" style="display:none;" pad="%s" indent="%s"></d\
iv><div id="%s-expanded">'                                             
      

END_DEF_BLOCK

HTML code for the end of a collapsable function or class definition block.
Value:
'</div>'                                                               
      

UNICODE_CODING_RE

A regular expression used to pick out the unicode encoding for the source file.
Value:
.*?\n?.*?coding[:=]\s*([-\w\.]+)                                       
      

ADD_DEF_BLOCKS

A configuration constant, used to determine whether or not to add collapsable <div> elements for definition blocks.
Value:
True                                                                   
      

ADD_LINE_NUMBERS

A configuration constant, used to determine whether or not to add line numbers.
Value:
True                                                                   
      

ADD_TOOLTIPS

A configuration constant, used to determine whether or not to add tooltips for linked names.
Value:
True                                                                   
      

GUESS_LINK_TARGETS

If true, then try to guess which target is appropriate for linked names; if false, then always open a div asking the user which one they want.
Value:
True                                                                   
      

_next_uid

Value:
0                                                                     
      

Instance Variable Details [hide private]

module_filename

The filename of the module we're colorizing.

module_name

The dotted name of the module we're colorizing.

name_to_docs

A mapping from short names to lists of ValueDoc.

url_func

A function that maps APIDoc -> URL

pos

The index in text of the last character of the last token we've processed.

line_offsets

A list that maps line numbers to character offsets in text. In particular, line i begins at character line_offset[i] in text. Since line numbers begin at 1, the first element of line_offsets is None.

cur_line

A list of (toktype, toktext) for all tokens on the logical line that we are currently processing. Once a complete line of tokens has been collected in cur_line, it is sent to handle_line for processing.

context

A list of the names of the class or functions that include the current block. context has one element for each level of indentation; context[i] is the name of the class or function defined by the ith level of indentation, or None if that level of indentation doesn't correspond to a class or function definition.

indents

A list of indentation strings for each of the current block's indents. I.e., the current total indentation can be found by taking ''.join(self.indents).

lineno

The line number of the line we're currently processing.

def_name

The name of the class or function whose definition started on the previous logical line, or None if the previous logical line was not a class or function definition.