Doc/library/html.parser.rst

   1 :mod:`html.parser` --- Simple HTML and XHTML parser
   2 ===================================================
   3
   4 .. module:: HTMLParser
   5    :synopsis: Old name for the html.parser module.
   6
   7 .. module:: html.parser
   8    :synopsis: A simple parser that can handle HTML and XHTML.
   9
  10 .. note::
  11    The :mod:`HTMLParser` module has been renamed to :mod:`html.parser` in Python
  12    3.0.  It is importable under both names in Python 2.6 and the rest of the 2.x
  13    series.
  14
  15
  16 .. versionadded:: 2.2
  17
  18 .. index::
  19    single: HTML
  20    single: XHTML
  21
  22 This module defines a class :class:`HTMLParser` which serves as the basis for
  23 parsing text files formatted in HTML (HyperText Mark-up Language) and XHTML.
  24 Unlike the parser in :mod:`htmllib`, this parser is not based on the SGML parser
  25 in :mod:`sgmllib`.
  26
  27
  28 .. class:: HTMLParser()
  29
  30    The :class:`HTMLParser` class is instantiated without arguments.
  31
  32    An :class:`HTMLParser` instance is fed HTML data and calls handler functions when tags
  33    begin and end.  The :class:`HTMLParser` class is meant to be overridden by the
  34    user to provide a desired behavior.
  35
  36    Unlike the parser in :mod:`htmllib`, this parser does not check that end tags
  37    match start tags or call the end-tag handler for elements which are closed
  38    implicitly by closing an outer element.
  39
  40 An exception is defined as well:
  41
  42
  43 .. exception:: HTMLParseError
  44
  45    Exception raised by the :class:`HTMLParser` class when it encounters an error
  46    while parsing.  This exception provides three attributes: :attr:`msg` is a brief
  47    message explaining the error, :attr:`lineno` is the number of the line on which
  48    the broken construct was detected, and :attr:`offset` is the number of
  49    characters into the line at which the construct starts.
  50
  51 :class:`HTMLParser` instances have the following methods:
  52
  53
  54 .. method:: HTMLParser.reset()
  55
  56    Reset the instance.  Loses all unprocessed data.  This is called implicitly at
  57    instantiation time.
  58
  59
  60 .. method:: HTMLParser.feed(data)
  61
  62    Feed some text to the parser.  It is processed insofar as it consists of
  63    complete elements; incomplete data is buffered until more data is fed or
  64    :meth:`close` is called.
  65
  66
  67 .. method:: HTMLParser.close()
  68
  69    Force processing of all buffered data as if it were followed by an end-of-file
  70    mark.  This method may be redefined by a derived class to define additional
  71    processing at the end of the input, but the redefined version should always call
  72    the :class:`HTMLParser` base class method :meth:`close`.
  73
  74
  75 .. method:: HTMLParser.getpos()
  76
  77    Return current line number and offset.
  78
  79
  80 .. method:: HTMLParser.get_starttag_text()
  81
  82    Return the text of the most recently opened start tag.  This should not normally
  83    be needed for structured processing, but may be useful in dealing with HTML "as
  84    deployed" or for re-generating input with minimal changes (whitespace between
  85    attributes can be preserved, etc.).
  86
  87
  88 .. method:: HTMLParser.handle_starttag(tag, attrs)
  89
  90    This method is called to handle the start of a tag.  It is intended to be
  91    overridden by a derived class; the base class implementation does nothing.
  92
  93    The *tag* argument is the name of the tag converted to lower case. The *attrs*
  94    argument is a list of ``(name, value)`` pairs containing the attributes found
  95    inside the tag's ``<>`` brackets.  The *name* will be translated to lower case,
  96    and quotes in the *value* have been removed, and character and entity references
  97    have been replaced.  For instance, for the tag ``<A
  98    HREF="http://www.cwi.nl/">``, this method would be called as
  99    ``handle_starttag('a', [('href', 'http://www.cwi.nl/')])``.
 100
 101    .. versionchanged:: 2.6
 102       All entity references from :mod:`html.entities` are now replaced in the
 103       attribute values.
 104
 105
 106 .. method:: HTMLParser.handle_startendtag(tag, attrs)
 107
 108    Similar to :meth:`handle_starttag`, but called when the parser encounters an
 109    XHTML-style empty tag (``<a .../>``).  This method may be overridden by
 110    subclasses which require this particular lexical information; the default
 111    implementation simple calls :meth:`handle_starttag` and :meth:`handle_endtag`.
 112
 113
 114 .. method:: HTMLParser.handle_endtag(tag)
 115
 116    This method is called to handle the end tag of an element.  It is intended to be
 117    overridden by a derived class; the base class implementation does nothing.  The
 118    *tag* argument is the name of the tag converted to lower case.
 119
 120
 121 .. method:: HTMLParser.handle_data(data)
 122
 123    This method is called to process arbitrary data.  It is intended to be
 124    overridden by a derived class; the base class implementation does nothing.
 125
 126
 127 .. method:: HTMLParser.handle_charref(name)
 128
 129    This method is called to process a character reference of the form ``&#ref;``.
 130    It is intended to be overridden by a derived class; the base class
 131    implementation does nothing.
 132
 133
 134 .. method:: HTMLParser.handle_entityref(name)
 135
 136    This method is called to process a general entity reference of the form
 137    ``&name;`` where *name* is an general entity reference.  It is intended to be
 138    overridden by a derived class; the base class implementation does nothing.
 139
 140
 141 .. method:: HTMLParser.handle_comment(data)
 142
 143    This method is called when a comment is encountered.  The *comment* argument is
 144    a string containing the text between the ``--`` and ``--`` delimiters, but not
 145    the delimiters themselves.  For example, the comment ``<!--text-->`` will cause
 146    this method to be called with the argument ``'text'``.  It is intended to be
 147    overridden by a derived class; the base class implementation does nothing.
 148
 149
 150 .. method:: HTMLParser.handle_decl(decl)
 151
 152    Method called when an SGML declaration is read by the parser.  The *decl*
 153    parameter will be the entire contents of the declaration inside the ``<!``...\
 154    ``>`` markup.  It is intended to be overridden by a derived class; the base
 155    class implementation does nothing.
 156
 157
 158 .. method:: HTMLParser.handle_pi(data)
 159
 160    Method called when a processing instruction is encountered.  The *data*
 161    parameter will contain the entire processing instruction. For example, for the
 162    processing instruction ``<?proc color='red'>``, this method would be called as
 163    ``handle_pi("proc color='red'")``.  It is intended to be overridden by a derived
 164    class; the base class implementation does nothing.
 165
 166    .. note::
 167
 168       The :class:`HTMLParser` class uses the SGML syntactic rules for processing
 169       instructions.  An XHTML processing instruction using the trailing ``'?'`` will
 170       cause the ``'?'`` to be included in *data*.
 171
 172
 173 .. _htmlparser-example:
 174
 175 Example HTML Parser Application
 176 -------------------------------
 177
 178 As a basic example, below is a very basic HTML parser that uses the
 179 :class:`HTMLParser` class to print out tags as they are encountered::
 180
 181    from html.parser import HTMLParser
 182
 183    class MyHTMLParser(HTMLParser):
 184
 185        def handle_starttag(self, tag, attrs):
 186            print "Encountered the beginning of a %s tag" % tag
 187
 188        def handle_endtag(self, tag):
 189            print "Encountered the end of a %s tag" % tag
 190