PageRenderTime 24ms CodeModel.GetById 17ms app.highlight 3ms RepoModel.GetById 2ms app.codeStats 0ms

/Doc/library/htmllib.rst

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