Package epydoc :: Package docwriter :: Module html_colorize :: Class PythonSourceColorizer

Class PythonSourceColorizer

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:

CSS styles are used to color tokens according to their type. (See CSS_CLASSES for a list of the different token types that are identified).
Line numbers are included to the left of each line.
The first line of each class and function definition includes a link to the API source documentation for that object.
The first line of each class and function definition includes an anchor that can be used to link directly to that class or function.
If javascript is enabled, and the page is loaded using the anchor for a class or function (i.e., if the url ends in '#<name>'), then that class or function will automatically be highlighted; and all other classes and function definition blocks will be 'collapsed'. These collapsed blocks can be expanded by clicking on them.
Unicode input is supported (including automatic detection of 'coding:' declarations).

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.

Class PythonSourceColorizer

__init__(self, module_filename, module_name, docindex=True, url_func=True, name_to_docs=True) (Constructor)

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

handle_line(self, line)

CSS_CLASSES

START_DEF_BLOCK

UNICODE_CODING_RE

line_offsets

cur_line

context

context_types

indents

def_type

init(self, module_filename, module_name, docindex=True, url_func=True, name_to_docs=True)
(Constructor)