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=True, url_func=True, name_to_docs=True)
Create a new HTML colorizer for the specified module.
source code
call graph 
 
find_line_offsets(self)
Construct the line_offsets table from self.text.
source code
call graph 
 
lineno_to_html(self) source code
call graph 
 
colorize(self)
Return an HTML string that renders the source code for the module that was specified in the constructor.
source code
call graph 
 
tokeneater(self, toktype, toktext, (srow, scol), (erow, ecol), line)
A callback function used by tokenize.tokenize to handle each token in the module.
source code
call graph 
 
handle_line(self, line)
Render a single logical line from the module, and write the generated HTML to self.out.
source code
call graph 
 
context_name(self, extra=True) source code
call graph 
 
doclink(self, name, docs) source code
call graph 
 
doc_descr(self, doc, context) source code
call graph 
 
doc_kind(self, doc) source code
call graph 
 
mark_def(self, s, name) source code
call graph 
 
is_docstring(self, line, i) source code
call graph 
 
add_line_numbers(self, s, css_class) source code
call graph 
 
name2url(self, class_name, func_name=True) source code
call graph 
Class Variables [hide private]
  CSS_CLASSES = {'@': 'py-decorator', 'BASECLASS': 'py-base-clas...
A look-up table that is used to determine which CSS class should be used to colorize a given token.
  START_DEF_BLOCK = '<div id="%s-collapsed" style="display:none;...
HTML code for the beginning of a collapsable function or class definition block.
  END_DEF_BLOCK = '</div>'
HTML code for the end of a collapsable function or class definition block.
  UNICODE_CODING_RE = re.compile(r'.*?\n?.*?coding[:=]\s*([-\w\....
A regular expression used to pick out the unicode encoding for the source file.
  ADD_DEF_BLOCKS = True
A configuration constant, used to determine whether or not to add collapsable <div> elements for definition blocks.
  ADD_LINE_NUMBERS = True
A configuration constant, used to determine whether or not to add line numbers.
  ADD_TOOLTIPS = True
A configuration constant, used to determine whether or not to add tooltips for linked names.
  GUESS_LINK_TARGETS = True
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 = 0
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.
  docindex
A docindex, used to create href links from identifiers to the API documentation for their values.
  name_to_docs
A mapping from short names to lists of ValueDoc, used to decide which values an identifier might map to when creating href links from identifiers to the API docs for their values.
  url_func
A function that maps APIDoc -> URL, used to create href links from identifiers to the API documentation for their values.
  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.
  context_types
A list, corresponding one-to-one with self.context, indicating the type of each entry.
  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.
  def_type
The type 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=True, url_func=True, name_to_docs=True)
(Constructor)

source code 
call graph 
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.

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

source code 
call graph 
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 
call graph 
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.

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">'

UNICODE_CODING_RE

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

Instance Variable Details [hide private]

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.

context_types

A list, corresponding one-to-one with self.context, indicating the type of each entry. Each element of context_types is one of: 'func', 'class', None.

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).

def_type

The type 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. Can be 'func', 'class', None.