Next: formatter Prev: sgmllib Up: Internet and WWW Top: Top

10.9. Standard Module `htmllib`

This module defines a class which can serve as a base for parsing text files formatted in the HyperText Mark-up Language (HTML). The class is not directly concerned with I/O --- it must be provided with input in string form via a method, and makes calls to methods of a ``formatter'' object in order to produce output. The HTMLParser class is designed to be used as a base class for other classes in order to add functionality, and allows most of its methods to be extended or overridden. In turn, this class is derived from and extends the SGMLParser class defined in module sgmllib. Two implementations of formatter objects are provided in the formatter module; refer to the documentation for that module for information on the formatter interface. The following is a summary of the interface defined by sgmllib.SGMLParser:

• The interface to feed data to an instance is through the feed() method, which takes a string argument. This can be called with as little or as much text at a time as desired; p.feed(a); p.feed(b) has the same effect as p.feed(a+b). When the data contains complete HTML tags, these are processed immediately; incomplete elements are saved in a buffer. To force processing of all unprocessed data, call the close() method.
For example, to parse the entire contents of a file, use:
• The interface to define semantics for HTML tags is very simple: derive a class and define methods called start_tag(), end_tag(), or do_tag(). The parser will call these at appropriate moments: start_tag or do_tag is called when an opening tag of the form <tag ...> is encountered; end_tag is called when a closing tag of the form <tag> is encountered. If an opening tag requires a corresponding closing tag, like <H1> ... </H1>, the class should define the start_tag method; if a tag requires no closing tag, like <P>, the class should define the do_tag method.

The module defines a single class:

HTMLParser (formatter) -- function of module htmllib: This is the basic HTML parser class. It supports all entity names required by the HTML 2.0 specification (RFC 1866). It also defines handlers for all HTML 2.0 and many HTML 3.0 and 3.2 elements.

In addition to tag methods, the HTMLParser class provides some additional methods and instance variables for use within tag methods.

formatter -- data of HTMLParser method: This is the formatter instance associated with the parser.

nofill -- data of HTMLParser method: Boolean flag which should be true when whitespace should not be collapsed, or false when it should be. In general, this should only be true when character data is to be treated as ``preformatted'' text, as within a <PRE> element. The default value is false. This affects the operation of handle_data() and save_end().

anchor_bgn (href, name, type) -- Method on HTMLParser: This method is called at the start of an anchor region. The arguments correspond to the attributes of the <A> tag with the same names. The default implementation maintains a list of hyperlinks (defined by the href argument) within the document. The list of hyperlinks is available as the data attribute anchorlist.

anchor_end () -- Method on HTMLParser: This method is called at the end of an anchor region. The default implementation adds a textual footnote marker using an index into the list of hyperlinks created by anchor_bgn().

handle_image (source, alt[, ismap[, align[, width[, height]]]]) -- Method on HTMLParser: This method is called to handle images. The default implementation simply passes the alt value to the handle_data() method.

save_bgn () -- Method on HTMLParser: Begins saving character data in a buffer instead of sending it to the formatter object. Retrieve the stored data via save_end() Use of the save_bgn() / save_end() pair may not be nested.

save_end () -- Method on HTMLParser: Ends buffering character data and returns all data saved since the preceeding call to save_bgn(). If nofill flag is false, whitespace is collapsed to single spaces. A call to this method without a preceeding call to save_bgn() will raise a TypeError exception.

10.9. Standard Module htmllib

10.9. Standard Module `htmllib`