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:

- 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=None, url_func=None, name_to_docs=None, tab_width=8) Create a new HTML colorizer for the specified module. | source code call graph

Call Graph

find_line_offsets(self) Construct the line_offsets table from `self.text`. | source code call graph

Call Graph

lineno_to_html(self) | source code call graph

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

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

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

Call Graph

context_name(self, extra=None) | source code call graph

Call Graph

doclink(self, name, docs) | source code call graph

Call Graph

doc_descr(self, doc, context) | source code call graph

Call Graph

doc_kind(self, doc) | source code call graph

Call Graph

mark_def(self, s, name) | source code call graph

Call Graph

is_docstring(self, line, i) | source code call graph

Call Graph

add_line_numbers(self, s, css_class) | source code call graph

Call Graph

name2url(self, class_name, func_name=None) | source code call graph

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 = `False` 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`
| _FIX_DECORATOR_RE = `re.compile(r'`(?m)``(``(?:`^<a name="L\d`+`"></a><`...`` A regexp used to move the <div> that marks the beginning of a function or method to just before the decorators.

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.
| tab_width The number of spaces to replace each tab in source code with

Method Details | [hide private]

### __init__(self, module_filename, module_name, docindex=None, url_func=None, name_to_docs=None, tab_width=8)
(Constructor)

source code
call graph

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

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

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\.]+)')

### _FIX_DECORATOR_RE

A regexp used to move the <div> that marks the beginning of a function or method to just before the decorators.

Value:

      re.compile(r'(?m)((?:^<a name="L\d+"></a><tt class="py-lineno">\s*\d+<
      /tt>\s*<tt class="py-line">(?:<tt class="py-decorator">.*|\s*</tt>|\s*
      <tt class="py-comment">.*)\n)+)(<a name="\w+"></a><div id="\w+-def">)'
      )

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 `i`th 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`.