19.3. "htmllib" — A parser for HTML documents
*********************************************

Deprecated since version 2.6: The "htmllib" module has been removed in
Python 3. Use "HTMLParser" instead in Python 2, and the equivalent,
"html.parser", in Python 3.

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".  The "HTMLParser"
implementation supports the HTML 2.0 language as described in **RFC
1866**.  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 markup constructs, these are processed immediately;
  incomplete constructs 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:

     parser.feed(open('myfile.html').read())
     parser.close()

* 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 parser class and an exception:

class htmllib.HTMLParser(formatter)

   This is the basic HTML parser class.  It supports all entity names
   required by the XHTML 1.0 Recommendation
   (https://www.w3.org/TR/xhtml1).   It also defines handlers for all
   HTML 2.0 and many HTML 3.0 and 3.2 elements.

exception htmllib.HTMLParseError

   Exception raised by the "HTMLParser" class when it encounters an
   error while parsing.

   New in version 2.4.

See also:

  Module "formatter"
     Interface definition for transforming an abstract flow of
     formatting events into specific output events on writer objects.

  Module "HTMLParser"
     Alternate HTML parser that offers a slightly lower-level view of
     the input, but is designed to work with XHTML, and does not
     implement some of the SGML syntax not used in “HTML as deployed”
     and which isn’t legal for XHTML.

  Module "htmlentitydefs"
     Definition of replacement text for XHTML 1.0  entities.

  Module "sgmllib"
     Base class for "HTMLParser".


19.3.1. HTMLParser Objects
==========================

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

HTMLParser.formatter

   This is the formatter instance associated with the parser.

HTMLParser.nofill

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

HTMLParser.anchor_bgn(href, name, type)

   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" attribute for "<A>" tags) within
   the document.  The list of hyperlinks is available as the data
   attribute "anchorlist".

HTMLParser.anchor_end()

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

HTMLParser.handle_image(source, alt[, ismap[, align[, width[, height]]]])

   This method is called to handle images.  The default implementation
   simply passes the *alt* value to the "handle_data()" method.

HTMLParser.save_bgn()

   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.

HTMLParser.save_end()

   Ends buffering character data and returns all data saved since the
   preceding call to "save_bgn()".  If the "nofill" flag is false,
   whitespace is collapsed to single spaces.  A call to this method
   without a preceding call to "save_bgn()" will raise a "TypeError"
   exception.


19.4. "htmlentitydefs" — Definitions of HTML general entities
*************************************************************

Note: The "htmlentitydefs" module has been renamed to
  "html.entities" in Python 3.  The *2to3* tool will automatically
  adapt imports when converting your sources to Python 3.

**Source code:** Lib/htmlentitydefs.py

======================================================================

This module defines three dictionaries, "name2codepoint",
"codepoint2name", and "entitydefs". "entitydefs" is used by the
"htmllib" module to provide the "entitydefs" attribute of the
"HTMLParser" class.  The definition provided here contains all the
entities defined by XHTML 1.0  that can be handled using simple
textual substitution in the Latin-1 character set (ISO-8859-1).

htmlentitydefs.entitydefs

   A dictionary mapping XHTML 1.0 entity definitions to their
   replacement text in ISO Latin-1.

htmlentitydefs.name2codepoint

   A dictionary that maps HTML entity names to the Unicode code
   points.

   New in version 2.3.

htmlentitydefs.codepoint2name

   A dictionary that maps Unicode code points to HTML entity names.

   New in version 2.3.