Doc/library/htmllib.rst

   1
   2 :mod:`htmllib` --- A parser for HTML documents
   3 ==============================================
   4
   5 .. module:: htmllib
   6    :synopsis: A parser for HTML documents.
   7
   8
   9 .. index::
  10    single: HTML
  11    single: hypertext
  12
  13 .. index::
  14    module: sgmllib
  15    module: formatter
  16    single: SGMLParser (in module sgmllib)
  17
  18 This module defines a class which can serve as a base for parsing text files
  19 formatted in the HyperText Mark-up Language (HTML).  The class is not directly
  20 concerned with I/O --- it must be provided with input in string form via a
  21 method, and makes calls to methods of a "formatter" object in order to produce
  22 output.  The :class:`HTMLParser` class is designed to be used as a base class
  23 for other classes in order to add functionality, and allows most of its methods
  24 to be extended or overridden.  In turn, this class is derived from and extends
  25 the :class:`SGMLParser` class defined in module :mod:`sgmllib`.  The
  26 :class:`HTMLParser` implementation supports the HTML 2.0 language as described
  27 in :rfc:`1866`.  Two implementations of formatter objects are provided in the
  28 :mod:`formatter` module; refer to the documentation for that module for
  29 information on the formatter interface.
  30
  31 The following is a summary of the interface defined by
  32 :class:`sgmllib.SGMLParser`:
  33
  34 * The interface to feed data to an instance is through the :meth:`feed` method,
  35   which takes a string argument.  This can be called with as little or as much
  36   text at a time as desired; ``p.feed(a); p.feed(b)`` has the same effect as
  37   ``p.feed(a+b)``.  When the data contains complete HTML markup constructs, these
  38   are processed immediately; incomplete constructs are saved in a buffer.  To
  39   force processing of all unprocessed data, call the :meth:`close` method.
  40
  41   For example, to parse the entire contents of a file, use::
  42
  43      parser.feed(open('myfile.html').read())
  44      parser.close()
  45
  46 * The interface to define semantics for HTML tags is very simple: derive a class
  47   and define methods called :meth:`start_tag`, :meth:`end_tag`, or :meth:`do_tag`.
  48   The parser will call these at appropriate moments: :meth:`start_tag` or
  49   :meth:`do_tag` is called when an opening tag of the form ``<tag ...>`` is
  50   encountered; :meth:`end_tag` is called when a closing tag of the form ``<tag>``
  51   is encountered.  If an opening tag requires a corresponding closing tag, like
  52   ``<H1>`` ... ``</H1>``, the class should define the :meth:`start_tag` method; if
  53   a tag requires no closing tag, like ``<P>``, the class should define the
  54   :meth:`do_tag` method.
  55
  56 The module defines a parser class and an exception:
  57
  58
  59 .. class:: HTMLParser(formatter)
  60
  61    This is the basic HTML parser class.  It supports all entity names required by
  62    the XHTML 1.0 Recommendation (http://www.w3.org/TR/xhtml1).   It also defines
  63    handlers for all HTML 2.0 and many HTML 3.0 and 3.2 elements.
  64
  65
  66 .. exception:: HTMLParseError
  67
  68    Exception raised by the :class:`HTMLParser` class when it encounters an error
  69    while parsing.
  70
  71    .. versionadded:: 2.4
  72
  73
  74 .. seealso::
  75
  76    Module :mod:`formatter`
  77       Interface definition for transforming an abstract flow of formatting events into
  78       specific output events on writer objects.
  79
  80    Module :mod:`html.parser`
  81       Alternate HTML parser that offers a slightly lower-level view of the input, but
  82       is designed to work with XHTML, and does not implement some of the SGML syntax
  83       not used in "HTML as deployed" and which isn't legal for XHTML.
  84
  85    Module :mod:`html.entities`
  86       Definition of replacement text for XHTML 1.0  entities.
  87
  88    Module :mod:`sgmllib`
  89       Base class for :class:`HTMLParser`.
  90
  91
  92 .. _html-parser-objects:
  93
  94 HTMLParser Objects
  95 ------------------
  96
  97 In addition to tag methods, the :class:`HTMLParser` class provides some
  98 additional methods and instance variables for use within tag methods.
  99
 100
 101 .. attribute:: HTMLParser.formatter
 102
 103    This is the formatter instance associated with the parser.
 104
 105
 106 .. attribute:: HTMLParser.nofill
 107
 108    Boolean flag which should be true when whitespace should not be collapsed, or
 109    false when it should be.  In general, this should only be true when character
 110    data is to be treated as "preformatted" text, as within a ``<PRE>`` element.
 111    The default value is false.  This affects the operation of :meth:`handle_data`
 112    and :meth:`save_end`.
 113
 114
 115 .. method:: HTMLParser.anchor_bgn(href, name, type)
 116
 117    This method is called at the start of an anchor region.  The arguments
 118    correspond to the attributes of the ``<A>`` tag with the same names.  The
 119    default implementation maintains a list of hyperlinks (defined by the ``HREF``
 120    attribute for ``<A>`` tags) within the document.  The list of hyperlinks is
 121    available as the data attribute :attr:`anchorlist`.
 122
 123
 124 .. method:: HTMLParser.anchor_end()
 125
 126    This method is called at the end of an anchor region.  The default
 127    implementation adds a textual footnote marker using an index into the list of
 128    hyperlinks created by :meth:`anchor_bgn`.
 129
 130
 131 .. method:: HTMLParser.handle_image(source, alt[, ismap[, align[, width[, height]]]])
 132
 133    This method is called to handle images.  The default implementation simply
 134    passes the *alt* value to the :meth:`handle_data` method.
 135
 136
 137 .. method:: HTMLParser.save_bgn()
 138
 139    Begins saving character data in a buffer instead of sending it to the formatter
 140    object.  Retrieve the stored data via :meth:`save_end`. Use of the
 141    :meth:`save_bgn` / :meth:`save_end` pair may not be nested.
 142
 143
 144 .. method:: HTMLParser.save_end()
 145
 146    Ends buffering character data and returns all data saved since the preceding
 147    call to :meth:`save_bgn`.  If the :attr:`nofill` flag is false, whitespace is
 148    collapsed to single spaces.  A call to this method without a preceding call to
 149    :meth:`save_bgn` will raise a :exc:`TypeError` exception.