Mercurial > cpython-lru_cache-weakref

annotate Doc/library/html.parser.rst @ 79691:05c8928362ee

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Merge __next__ method link fixes with 3.3.
author Ezio Melotti <ezio.melotti@gmail.com>
date Fri, 12 Oct 2012 13:46:37 +0300
parents 653cf179491d
children 0a56709eb798
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
47151
cdb75af2385a Merged revisions 63438 via svnmerge from
Georg Brandl <georg@python.org>
parents:
diff changeset
1 :mod:`html.parser` --- Simple HTML and XHTML parser
cdb75af2385a Merged revisions 63438 via svnmerge from
Georg Brandl <georg@python.org>
parents:
diff changeset
2 ===================================================
cdb75af2385a Merged revisions 63438 via svnmerge from
Georg Brandl <georg@python.org>
parents:
diff changeset
3
cdb75af2385a Merged revisions 63438 via svnmerge from
Georg Brandl <georg@python.org>
parents:
diff changeset
4 .. module:: html.parser
cdb75af2385a Merged revisions 63438 via svnmerge from
Georg Brandl <georg@python.org>
parents:
diff changeset
5 :synopsis: A simple parser that can handle HTML and XHTML.
cdb75af2385a Merged revisions 63438 via svnmerge from
Georg Brandl <georg@python.org>
parents:
diff changeset
6
cdb75af2385a Merged revisions 63438 via svnmerge from
Georg Brandl <georg@python.org>
parents:
diff changeset
7
cdb75af2385a Merged revisions 63438 via svnmerge from
Georg Brandl <georg@python.org>
parents:
diff changeset
8 .. index::
cdb75af2385a Merged revisions 63438 via svnmerge from
Georg Brandl <georg@python.org>
parents:
diff changeset
9 single: HTML
cdb75af2385a Merged revisions 63438 via svnmerge from
Georg Brandl <georg@python.org>
parents:
diff changeset
10 single: XHTML
cdb75af2385a Merged revisions 63438 via svnmerge from
Georg Brandl <georg@python.org>
parents:
diff changeset
11
67779
591d54ffe969 More source links.
Raymond Hettinger <python@rcn.com>
parents: 66624
diff changeset
12 **Source code:** :source:`Lib/html/parser.py`
591d54ffe969 More source links.
Raymond Hettinger <python@rcn.com>
parents: 66624
diff changeset
13
591d54ffe969 More source links.
Raymond Hettinger <python@rcn.com>
parents: 66624
diff changeset
14 --------------
591d54ffe969 More source links.
Raymond Hettinger <python@rcn.com>
parents: 66624
diff changeset
15
47151
cdb75af2385a Merged revisions 63438 via svnmerge from
Georg Brandl <georg@python.org>
parents:
diff changeset
16 This module defines a class :class:`HTMLParser` which serves as the basis for
cdb75af2385a Merged revisions 63438 via svnmerge from
Georg Brandl <georg@python.org>
parents:
diff changeset
17 parsing text files formatted in HTML (HyperText Mark-up Language) and XHTML.
cdb75af2385a Merged revisions 63438 via svnmerge from
Georg Brandl <georg@python.org>
parents:
diff changeset
18
77630
8dd2f5754b2f #15114: the strict mode of HTMLParser and the HTMLParseError exception are deprecated now that the parser is able to parse invalid markup.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 75010
diff changeset
19 .. class:: HTMLParser(strict=False)
47151
cdb75af2385a Merged revisions 63438 via svnmerge from
Georg Brandl <georg@python.org>
parents:
diff changeset
20
77630
8dd2f5754b2f #15114: the strict mode of HTMLParser and the HTMLParseError exception are deprecated now that the parser is able to parse invalid markup.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 75010
diff changeset
21 Create a parser instance. If *strict* is ``False`` (the default), the parser
8dd2f5754b2f #15114: the strict mode of HTMLParser and the HTMLParseError exception are deprecated now that the parser is able to parse invalid markup.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 75010
diff changeset
22 will accept and parse invalid markup. If *strict* is ``True`` the parser
8dd2f5754b2f #15114: the strict mode of HTMLParser and the HTMLParseError exception are deprecated now that the parser is able to parse invalid markup.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 75010
diff changeset
23 will raise an :exc:`~html.parser.HTMLParseError` exception instead [#]_ when
8dd2f5754b2f #15114: the strict mode of HTMLParser and the HTMLParseError exception are deprecated now that the parser is able to parse invalid markup.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 75010
diff changeset
24 it's not able to parse the markup.
8dd2f5754b2f #15114: the strict mode of HTMLParser and the HTMLParseError exception are deprecated now that the parser is able to parse invalid markup.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 75010
diff changeset
25 The use of ``strict=True`` is discouraged and the *strict* argument is
8dd2f5754b2f #15114: the strict mode of HTMLParser and the HTMLParseError exception are deprecated now that the parser is able to parse invalid markup.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 75010
diff changeset
26 deprecated.
47151
cdb75af2385a Merged revisions 63438 via svnmerge from
Georg Brandl <georg@python.org>
parents:
diff changeset
27
75010
569566cbfd13 #14020: improve HTMLParser documentation.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 73274
diff changeset
28 An :class:`.HTMLParser` instance is fed HTML data and calls handler methods
569566cbfd13 #14020: improve HTMLParser documentation.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 73274
diff changeset
29 when start tags, end tags, text, comments, and other markup elements are
569566cbfd13 #14020: improve HTMLParser documentation.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 73274
diff changeset
30 encountered. The user should subclass :class:`.HTMLParser` and override its
569566cbfd13 #14020: improve HTMLParser documentation.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 73274
diff changeset
31 methods to implement the desired behavior.
47151
cdb75af2385a Merged revisions 63438 via svnmerge from
Georg Brandl <georg@python.org>
parents:
diff changeset
32
47434
f150177ff1ff Remove the htmllib and sgmllib modules as per PEP 3108.
Georg Brandl <georg@python.org>
parents: 47151
diff changeset
33 This parser does not check that end tags match start tags or call the end-tag
f150177ff1ff Remove the htmllib and sgmllib modules as per PEP 3108.
Georg Brandl <georg@python.org>
parents: 47151
diff changeset
34 handler for elements which are closed implicitly by closing an outer element.
47151
cdb75af2385a Merged revisions 63438 via svnmerge from
Georg Brandl <georg@python.org>
parents:
diff changeset
35
77753
653cf179491d Fix a couple of versionadded/versionchanged related markup errors.
Georg Brandl <georg@python.org>
parents: 77630
diff changeset
36 .. versionchanged:: 3.2
653cf179491d Fix a couple of versionadded/versionchanged related markup errors.
Georg Brandl <georg@python.org>
parents: 77630
diff changeset
37 *strict* keyword added.
66624
6e49af2e0891 Add missing versionchanged, correct 'throw' wording to 'raise'.
R. David Murray <rdmurray@bitdance.com>
parents: 66623
diff changeset
38
77630
8dd2f5754b2f #15114: the strict mode of HTMLParser and the HTMLParseError exception are deprecated now that the parser is able to parse invalid markup.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 75010
diff changeset
39 .. deprecated-removed:: 3.3 3.5
8dd2f5754b2f #15114: the strict mode of HTMLParser and the HTMLParseError exception are deprecated now that the parser is able to parse invalid markup.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 75010
diff changeset
40 The *strict* argument and the strict mode have been deprecated.
8dd2f5754b2f #15114: the strict mode of HTMLParser and the HTMLParseError exception are deprecated now that the parser is able to parse invalid markup.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 75010
diff changeset
41 The parser is now able to accept and parse invalid markup too.
8dd2f5754b2f #15114: the strict mode of HTMLParser and the HTMLParseError exception are deprecated now that the parser is able to parse invalid markup.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 75010
diff changeset
42
47151
cdb75af2385a Merged revisions 63438 via svnmerge from
Georg Brandl <georg@python.org>
parents:
diff changeset
43 An exception is defined as well:
cdb75af2385a Merged revisions 63438 via svnmerge from
Georg Brandl <georg@python.org>
parents:
diff changeset
44
cdb75af2385a Merged revisions 63438 via svnmerge from
Georg Brandl <georg@python.org>
parents:
diff changeset
45
cdb75af2385a Merged revisions 63438 via svnmerge from
Georg Brandl <georg@python.org>
parents:
diff changeset
46 .. exception:: HTMLParseError
cdb75af2385a Merged revisions 63438 via svnmerge from
Georg Brandl <georg@python.org>
parents:
diff changeset
47
cdb75af2385a Merged revisions 63438 via svnmerge from
Georg Brandl <georg@python.org>
parents:
diff changeset
48 Exception raised by the :class:`HTMLParser` class when it encounters an error
75010
569566cbfd13 #14020: improve HTMLParser documentation.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 73274
diff changeset
49 while parsing and *strict* is ``True``. This exception provides three
569566cbfd13 #14020: improve HTMLParser documentation.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 73274
diff changeset
50 attributes: :attr:`msg` is a brief message explaining the error,
569566cbfd13 #14020: improve HTMLParser documentation.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 73274
diff changeset
51 :attr:`lineno` is the number of the line on which the broken construct was
569566cbfd13 #14020: improve HTMLParser documentation.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 73274
diff changeset
52 detected, and :attr:`offset` is the number of characters into the line at
569566cbfd13 #14020: improve HTMLParser documentation.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 73274
diff changeset
53 which the construct starts.
569566cbfd13 #14020: improve HTMLParser documentation.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 73274
diff changeset
54
77630
8dd2f5754b2f #15114: the strict mode of HTMLParser and the HTMLParseError exception are deprecated now that the parser is able to parse invalid markup.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 75010
diff changeset
55 .. deprecated-removed:: 3.3 3.5
8dd2f5754b2f #15114: the strict mode of HTMLParser and the HTMLParseError exception are deprecated now that the parser is able to parse invalid markup.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 75010
diff changeset
56 This exception has been deprecated because it's never raised by the parser
8dd2f5754b2f #15114: the strict mode of HTMLParser and the HTMLParseError exception are deprecated now that the parser is able to parse invalid markup.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 75010
diff changeset
57 (when the default non-strict mode is used).
8dd2f5754b2f #15114: the strict mode of HTMLParser and the HTMLParseError exception are deprecated now that the parser is able to parse invalid markup.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 75010
diff changeset
58
75010
569566cbfd13 #14020: improve HTMLParser documentation.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 73274
diff changeset
59
569566cbfd13 #14020: improve HTMLParser documentation.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 73274
diff changeset
60 Example HTML Parser Application
569566cbfd13 #14020: improve HTMLParser documentation.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 73274
diff changeset
61 -------------------------------
569566cbfd13 #14020: improve HTMLParser documentation.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 73274
diff changeset
62
569566cbfd13 #14020: improve HTMLParser documentation.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 73274
diff changeset
63 As a basic example, below is a simple HTML parser that uses the
569566cbfd13 #14020: improve HTMLParser documentation.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 73274
diff changeset
64 :class:`HTMLParser` class to print out start tags, end tags, and data
569566cbfd13 #14020: improve HTMLParser documentation.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 73274
diff changeset
65 as they are encountered::
569566cbfd13 #14020: improve HTMLParser documentation.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 73274
diff changeset
66
569566cbfd13 #14020: improve HTMLParser documentation.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 73274
diff changeset
67 from html.parser import HTMLParser
569566cbfd13 #14020: improve HTMLParser documentation.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 73274
diff changeset
68
569566cbfd13 #14020: improve HTMLParser documentation.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 73274
diff changeset
69 class MyHTMLParser(HTMLParser):
569566cbfd13 #14020: improve HTMLParser documentation.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 73274
diff changeset
70 def handle_starttag(self, tag, attrs):
569566cbfd13 #14020: improve HTMLParser documentation.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 73274
diff changeset
71 print("Encountered a start tag:", tag)
569566cbfd13 #14020: improve HTMLParser documentation.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 73274
diff changeset
72 def handle_endtag(self, tag):
569566cbfd13 #14020: improve HTMLParser documentation.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 73274
diff changeset
73 print("Encountered an end tag :", tag)
569566cbfd13 #14020: improve HTMLParser documentation.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 73274
diff changeset
74 def handle_data(self, data):
569566cbfd13 #14020: improve HTMLParser documentation.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 73274
diff changeset
75 print("Encountered some data :", data)
569566cbfd13 #14020: improve HTMLParser documentation.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 73274
diff changeset
76
569566cbfd13 #14020: improve HTMLParser documentation.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 73274
diff changeset
77 parser = MyHTMLParser(strict=False)
569566cbfd13 #14020: improve HTMLParser documentation.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 73274
diff changeset
78 parser.feed('<html><head><title>Test</title></head>'
569566cbfd13 #14020: improve HTMLParser documentation.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 73274
diff changeset
79 '<body><h1>Parse me!</h1></body></html>')
569566cbfd13 #14020: improve HTMLParser documentation.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 73274
diff changeset
80
569566cbfd13 #14020: improve HTMLParser documentation.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 73274
diff changeset
81 The output will then be::
569566cbfd13 #14020: improve HTMLParser documentation.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 73274
diff changeset
82
569566cbfd13 #14020: improve HTMLParser documentation.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 73274
diff changeset
83 Encountered a start tag: html
569566cbfd13 #14020: improve HTMLParser documentation.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 73274
diff changeset
84 Encountered a start tag: head
569566cbfd13 #14020: improve HTMLParser documentation.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 73274
diff changeset
85 Encountered a start tag: title
569566cbfd13 #14020: improve HTMLParser documentation.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 73274
diff changeset
86 Encountered some data : Test
569566cbfd13 #14020: improve HTMLParser documentation.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 73274
diff changeset
87 Encountered an end tag : title
569566cbfd13 #14020: improve HTMLParser documentation.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 73274
diff changeset
88 Encountered an end tag : head
569566cbfd13 #14020: improve HTMLParser documentation.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 73274
diff changeset
89 Encountered a start tag: body
569566cbfd13 #14020: improve HTMLParser documentation.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 73274
diff changeset
90 Encountered a start tag: h1
569566cbfd13 #14020: improve HTMLParser documentation.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 73274
diff changeset
91 Encountered some data : Parse me!
569566cbfd13 #14020: improve HTMLParser documentation.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 73274
diff changeset
92 Encountered an end tag : h1
569566cbfd13 #14020: improve HTMLParser documentation.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 73274
diff changeset
93 Encountered an end tag : body
569566cbfd13 #14020: improve HTMLParser documentation.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 73274
diff changeset
94 Encountered an end tag : html
569566cbfd13 #14020: improve HTMLParser documentation.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 73274
diff changeset
95
569566cbfd13 #14020: improve HTMLParser documentation.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 73274
diff changeset
96
569566cbfd13 #14020: improve HTMLParser documentation.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 73274
diff changeset
97 :class:`.HTMLParser` Methods
569566cbfd13 #14020: improve HTMLParser documentation.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 73274
diff changeset
98 ----------------------------
47151
cdb75af2385a Merged revisions 63438 via svnmerge from
Georg Brandl <georg@python.org>
parents:
diff changeset
99
cdb75af2385a Merged revisions 63438 via svnmerge from
Georg Brandl <georg@python.org>
parents:
diff changeset
100 :class:`HTMLParser` instances have the following methods:
cdb75af2385a Merged revisions 63438 via svnmerge from
Georg Brandl <georg@python.org>
parents:
diff changeset
101
cdb75af2385a Merged revisions 63438 via svnmerge from
Georg Brandl <georg@python.org>
parents:
diff changeset
102
cdb75af2385a Merged revisions 63438 via svnmerge from
Georg Brandl <georg@python.org>
parents:
diff changeset
103 .. method:: HTMLParser.feed(data)
cdb75af2385a Merged revisions 63438 via svnmerge from
Georg Brandl <georg@python.org>
parents:
diff changeset
104
cdb75af2385a Merged revisions 63438 via svnmerge from
Georg Brandl <georg@python.org>
parents:
diff changeset
105 Feed some text to the parser. It is processed insofar as it consists of
cdb75af2385a Merged revisions 63438 via svnmerge from
Georg Brandl <georg@python.org>
parents:
diff changeset
106 complete elements; incomplete data is buffered until more data is fed or
75010
569566cbfd13 #14020: improve HTMLParser documentation.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 73274
diff changeset
107 :meth:`close` is called. *data* must be :class:`str`.
47151
cdb75af2385a Merged revisions 63438 via svnmerge from
Georg Brandl <georg@python.org>
parents:
diff changeset
108
cdb75af2385a Merged revisions 63438 via svnmerge from
Georg Brandl <georg@python.org>
parents:
diff changeset
109
cdb75af2385a Merged revisions 63438 via svnmerge from
Georg Brandl <georg@python.org>
parents:
diff changeset
110 .. method:: HTMLParser.close()
cdb75af2385a Merged revisions 63438 via svnmerge from
Georg Brandl <georg@python.org>
parents:
diff changeset
111
cdb75af2385a Merged revisions 63438 via svnmerge from
Georg Brandl <georg@python.org>
parents:
diff changeset
112 Force processing of all buffered data as if it were followed by an end-of-file
cdb75af2385a Merged revisions 63438 via svnmerge from
Georg Brandl <georg@python.org>
parents:
diff changeset
113 mark. This method may be redefined by a derived class to define additional
cdb75af2385a Merged revisions 63438 via svnmerge from
Georg Brandl <georg@python.org>
parents:
diff changeset
114 processing at the end of the input, but the redefined version should always call
cdb75af2385a Merged revisions 63438 via svnmerge from
Georg Brandl <georg@python.org>
parents:
diff changeset
115 the :class:`HTMLParser` base class method :meth:`close`.
cdb75af2385a Merged revisions 63438 via svnmerge from
Georg Brandl <georg@python.org>
parents:
diff changeset
116
cdb75af2385a Merged revisions 63438 via svnmerge from
Georg Brandl <georg@python.org>
parents:
diff changeset
117
75010
569566cbfd13 #14020: improve HTMLParser documentation.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 73274
diff changeset
118 .. method:: HTMLParser.reset()
569566cbfd13 #14020: improve HTMLParser documentation.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 73274
diff changeset
119
569566cbfd13 #14020: improve HTMLParser documentation.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 73274
diff changeset
120 Reset the instance. Loses all unprocessed data. This is called implicitly at
569566cbfd13 #14020: improve HTMLParser documentation.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 73274
diff changeset
121 instantiation time.
569566cbfd13 #14020: improve HTMLParser documentation.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 73274
diff changeset
122
569566cbfd13 #14020: improve HTMLParser documentation.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 73274
diff changeset
123
47151
cdb75af2385a Merged revisions 63438 via svnmerge from
Georg Brandl <georg@python.org>
parents:
diff changeset
124 .. method:: HTMLParser.getpos()
cdb75af2385a Merged revisions 63438 via svnmerge from
Georg Brandl <georg@python.org>
parents:
diff changeset
125
cdb75af2385a Merged revisions 63438 via svnmerge from
Georg Brandl <georg@python.org>
parents:
diff changeset
126 Return current line number and offset.
cdb75af2385a Merged revisions 63438 via svnmerge from
Georg Brandl <georg@python.org>
parents:
diff changeset
127
cdb75af2385a Merged revisions 63438 via svnmerge from
Georg Brandl <georg@python.org>
parents:
diff changeset
128
cdb75af2385a Merged revisions 63438 via svnmerge from
Georg Brandl <georg@python.org>
parents:
diff changeset
129 .. method:: HTMLParser.get_starttag_text()
cdb75af2385a Merged revisions 63438 via svnmerge from
Georg Brandl <georg@python.org>
parents:
diff changeset
130
cdb75af2385a Merged revisions 63438 via svnmerge from
Georg Brandl <georg@python.org>
parents:
diff changeset
131 Return the text of the most recently opened start tag. This should not normally
cdb75af2385a Merged revisions 63438 via svnmerge from
Georg Brandl <georg@python.org>
parents:
diff changeset
132 be needed for structured processing, but may be useful in dealing with HTML "as
cdb75af2385a Merged revisions 63438 via svnmerge from
Georg Brandl <georg@python.org>
parents:
diff changeset
133 deployed" or for re-generating input with minimal changes (whitespace between
cdb75af2385a Merged revisions 63438 via svnmerge from
Georg Brandl <georg@python.org>
parents:
diff changeset
134 attributes can be preserved, etc.).
cdb75af2385a Merged revisions 63438 via svnmerge from
Georg Brandl <georg@python.org>
parents:
diff changeset
135
cdb75af2385a Merged revisions 63438 via svnmerge from
Georg Brandl <georg@python.org>
parents:
diff changeset
136
75010
569566cbfd13 #14020: improve HTMLParser documentation.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 73274
diff changeset
137 The following methods are called when data or markup elements are encountered
569566cbfd13 #14020: improve HTMLParser documentation.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 73274
diff changeset
138 and they are meant to be overridden in a subclass. The base class
569566cbfd13 #14020: improve HTMLParser documentation.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 73274
diff changeset
139 implementations do nothing (except for :meth:`~HTMLParser.handle_startendtag`):
569566cbfd13 #14020: improve HTMLParser documentation.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 73274
diff changeset
140
569566cbfd13 #14020: improve HTMLParser documentation.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 73274
diff changeset
141
47151
cdb75af2385a Merged revisions 63438 via svnmerge from
Georg Brandl <georg@python.org>
parents:
diff changeset
142 .. method:: HTMLParser.handle_starttag(tag, attrs)
cdb75af2385a Merged revisions 63438 via svnmerge from
Georg Brandl <georg@python.org>
parents:
diff changeset
143
75010
569566cbfd13 #14020: improve HTMLParser documentation.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 73274
diff changeset
144 This method is called to handle the start of a tag (e.g. ``<div id="main">``).
47151
cdb75af2385a Merged revisions 63438 via svnmerge from
Georg Brandl <georg@python.org>
parents:
diff changeset
145
cdb75af2385a Merged revisions 63438 via svnmerge from
Georg Brandl <georg@python.org>
parents:
diff changeset
146 The *tag* argument is the name of the tag converted to lower case. The *attrs*
cdb75af2385a Merged revisions 63438 via svnmerge from
Georg Brandl <georg@python.org>
parents:
diff changeset
147 argument is a list of ``(name, value)`` pairs containing the attributes found
cdb75af2385a Merged revisions 63438 via svnmerge from
Georg Brandl <georg@python.org>
parents:
diff changeset
148 inside the tag's ``<>`` brackets. The *name* will be translated to lower case,
cdb75af2385a Merged revisions 63438 via svnmerge from
Georg Brandl <georg@python.org>
parents:
diff changeset
149 and quotes in the *value* have been removed, and character and entity references
75010
569566cbfd13 #14020: improve HTMLParser documentation.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 73274
diff changeset
150 have been replaced.
569566cbfd13 #14020: improve HTMLParser documentation.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 73274
diff changeset
151
569566cbfd13 #14020: improve HTMLParser documentation.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 73274
diff changeset
152 For instance, for the tag ``<A HREF="http://www.cwi.nl/">``, this method
569566cbfd13 #14020: improve HTMLParser documentation.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 73274
diff changeset
153 would be called as ``handle_starttag('a', [('href', 'http://www.cwi.nl/')])``.
47151
cdb75af2385a Merged revisions 63438 via svnmerge from
Georg Brandl <georg@python.org>
parents:
diff changeset
154
cdb75af2385a Merged revisions 63438 via svnmerge from
Georg Brandl <georg@python.org>
parents:
diff changeset
155 All entity references from :mod:`html.entities` are replaced in the attribute
cdb75af2385a Merged revisions 63438 via svnmerge from
Georg Brandl <georg@python.org>
parents:
diff changeset
156 values.
cdb75af2385a Merged revisions 63438 via svnmerge from
Georg Brandl <georg@python.org>
parents:
diff changeset
157
cdb75af2385a Merged revisions 63438 via svnmerge from
Georg Brandl <georg@python.org>
parents:
diff changeset
158
75010
569566cbfd13 #14020: improve HTMLParser documentation.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 73274
diff changeset
159 .. method:: HTMLParser.handle_endtag(tag)
569566cbfd13 #14020: improve HTMLParser documentation.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 73274
diff changeset
160
569566cbfd13 #14020: improve HTMLParser documentation.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 73274
diff changeset
161 This method is called to handle the end tag of an element (e.g. ``</div>``).
569566cbfd13 #14020: improve HTMLParser documentation.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 73274
diff changeset
162
569566cbfd13 #14020: improve HTMLParser documentation.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 73274
diff changeset
163 The *tag* argument is the name of the tag converted to lower case.
569566cbfd13 #14020: improve HTMLParser documentation.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 73274
diff changeset
164
569566cbfd13 #14020: improve HTMLParser documentation.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 73274
diff changeset
165
47151
cdb75af2385a Merged revisions 63438 via svnmerge from
Georg Brandl <georg@python.org>
parents:
diff changeset
166 .. method:: HTMLParser.handle_startendtag(tag, attrs)
cdb75af2385a Merged revisions 63438 via svnmerge from
Georg Brandl <georg@python.org>
parents:
diff changeset
167
cdb75af2385a Merged revisions 63438 via svnmerge from
Georg Brandl <georg@python.org>
parents:
diff changeset
168 Similar to :meth:`handle_starttag`, but called when the parser encounters an
73163
9ddcb6d44bb4 Improve HTMLParser example in the doc and fix a couple minor things.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 68798
diff changeset
169 XHTML-style empty tag (``<img ... />``). This method may be overridden by
47151
cdb75af2385a Merged revisions 63438 via svnmerge from
Georg Brandl <georg@python.org>
parents:
diff changeset
170 subclasses which require this particular lexical information; the default
73163
9ddcb6d44bb4 Improve HTMLParser example in the doc and fix a couple minor things.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 68798
diff changeset
171 implementation simply calls :meth:`handle_starttag` and :meth:`handle_endtag`.
47151
cdb75af2385a Merged revisions 63438 via svnmerge from
Georg Brandl <georg@python.org>
parents:
diff changeset
172
cdb75af2385a Merged revisions 63438 via svnmerge from
Georg Brandl <georg@python.org>
parents:
diff changeset
173
cdb75af2385a Merged revisions 63438 via svnmerge from
Georg Brandl <georg@python.org>
parents:
diff changeset
174 .. method:: HTMLParser.handle_data(data)
cdb75af2385a Merged revisions 63438 via svnmerge from
Georg Brandl <georg@python.org>
parents:
diff changeset
175
75010
569566cbfd13 #14020: improve HTMLParser documentation.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 73274
diff changeset
176 This method is called to process arbitrary data (e.g. text nodes and the
569566cbfd13 #14020: improve HTMLParser documentation.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 73274
diff changeset
177 content of ``<script>...</script>`` and ``<style>...</style>``).
47151
cdb75af2385a Merged revisions 63438 via svnmerge from
Georg Brandl <georg@python.org>
parents:
diff changeset
178
cdb75af2385a Merged revisions 63438 via svnmerge from
Georg Brandl <georg@python.org>
parents:
diff changeset
179
cdb75af2385a Merged revisions 63438 via svnmerge from
Georg Brandl <georg@python.org>
parents:
diff changeset
180 .. method:: HTMLParser.handle_entityref(name)
cdb75af2385a Merged revisions 63438 via svnmerge from
Georg Brandl <georg@python.org>
parents:
diff changeset
181
75010
569566cbfd13 #14020: improve HTMLParser documentation.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 73274
diff changeset
182 This method is called to process a named character reference of the form
569566cbfd13 #14020: improve HTMLParser documentation.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 73274
diff changeset
183 ``&name;`` (e.g. ``&gt;``), where *name* is a general entity reference
569566cbfd13 #14020: improve HTMLParser documentation.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 73274
diff changeset
184 (e.g. ``'gt'``).
569566cbfd13 #14020: improve HTMLParser documentation.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 73274
diff changeset
185
569566cbfd13 #14020: improve HTMLParser documentation.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 73274
diff changeset
186
569566cbfd13 #14020: improve HTMLParser documentation.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 73274
diff changeset
187 .. method:: HTMLParser.handle_charref(name)
569566cbfd13 #14020: improve HTMLParser documentation.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 73274
diff changeset
188
569566cbfd13 #14020: improve HTMLParser documentation.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 73274
diff changeset
189 This method is called to process decimal and hexadecimal numeric character
569566cbfd13 #14020: improve HTMLParser documentation.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 73274
diff changeset
190 references of the form ``&#NNN;`` and ``&#xNNN;``. For example, the decimal
569566cbfd13 #14020: improve HTMLParser documentation.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 73274
diff changeset
191 equivalent for ``&gt;`` is ``&#62;``, whereas the hexadecimal is ``&#x3E;``;
569566cbfd13 #14020: improve HTMLParser documentation.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 73274
diff changeset
192 in this case the method will receive ``'62'`` or ``'x3E'``.
47151
cdb75af2385a Merged revisions 63438 via svnmerge from
Georg Brandl <georg@python.org>
parents:
diff changeset
193
cdb75af2385a Merged revisions 63438 via svnmerge from
Georg Brandl <georg@python.org>
parents:
diff changeset
194
cdb75af2385a Merged revisions 63438 via svnmerge from
Georg Brandl <georg@python.org>
parents:
diff changeset
195 .. method:: HTMLParser.handle_comment(data)
cdb75af2385a Merged revisions 63438 via svnmerge from
Georg Brandl <georg@python.org>
parents:
diff changeset
196
75010
569566cbfd13 #14020: improve HTMLParser documentation.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 73274
diff changeset
197 This method is called when a comment is encountered (e.g. ``<!--comment-->``).
569566cbfd13 #14020: improve HTMLParser documentation.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 73274
diff changeset
198
569566cbfd13 #14020: improve HTMLParser documentation.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 73274
diff changeset
199 For example, the comment ``<!-- comment -->`` will cause this method to be
569566cbfd13 #14020: improve HTMLParser documentation.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 73274
diff changeset
200 called with the argument ``' comment '``.
569566cbfd13 #14020: improve HTMLParser documentation.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 73274
diff changeset
201
569566cbfd13 #14020: improve HTMLParser documentation.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 73274
diff changeset
202 The content of Internet Explorer conditional comments (condcoms) will also be
569566cbfd13 #14020: improve HTMLParser documentation.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 73274
diff changeset
203 sent to this method, so, for ``<!--[if IE 9]>IE9-specific content<![endif]-->``,
569566cbfd13 #14020: improve HTMLParser documentation.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 73274
diff changeset
204 this method will receive ``'[if IE 9]>IE-specific content<![endif]'``.
47151
cdb75af2385a Merged revisions 63438 via svnmerge from
Georg Brandl <georg@python.org>
parents:
diff changeset
205
cdb75af2385a Merged revisions 63438 via svnmerge from
Georg Brandl <georg@python.org>
parents:
diff changeset
206
cdb75af2385a Merged revisions 63438 via svnmerge from
Georg Brandl <georg@python.org>
parents:
diff changeset
207 .. method:: HTMLParser.handle_decl(decl)
cdb75af2385a Merged revisions 63438 via svnmerge from
Georg Brandl <georg@python.org>
parents:
diff changeset
208
75010
569566cbfd13 #14020: improve HTMLParser documentation.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 73274
diff changeset
209 This method is called to handle an HTML doctype declaration (e.g.
569566cbfd13 #14020: improve HTMLParser documentation.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 73274
diff changeset
210 ``<!DOCTYPE html>``).
63284
054f3279e3cc #3874: document HTMLParser.unknown_decl().
Georg Brandl <georg@python.org>
parents: 55600
diff changeset
211
75010
569566cbfd13 #14020: improve HTMLParser documentation.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 73274
diff changeset
212 The *decl* parameter will be the entire contents of the declaration inside
569566cbfd13 #14020: improve HTMLParser documentation.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 73274
diff changeset
213 the ``<!...>`` markup (e.g. ``'DOCTYPE html'``).
47151
cdb75af2385a Merged revisions 63438 via svnmerge from
Georg Brandl <georg@python.org>
parents:
diff changeset
214
cdb75af2385a Merged revisions 63438 via svnmerge from
Georg Brandl <georg@python.org>
parents:
diff changeset
215
cdb75af2385a Merged revisions 63438 via svnmerge from
Georg Brandl <georg@python.org>
parents:
diff changeset
216 .. method:: HTMLParser.handle_pi(data)
cdb75af2385a Merged revisions 63438 via svnmerge from
Georg Brandl <georg@python.org>
parents:
diff changeset
217
cdb75af2385a Merged revisions 63438 via svnmerge from
Georg Brandl <georg@python.org>
parents:
diff changeset
218 Method called when a processing instruction is encountered. The *data*
cdb75af2385a Merged revisions 63438 via svnmerge from
Georg Brandl <georg@python.org>
parents:
diff changeset
219 parameter will contain the entire processing instruction. For example, for the
cdb75af2385a Merged revisions 63438 via svnmerge from
Georg Brandl <georg@python.org>
parents:
diff changeset
220 processing instruction ``<?proc color='red'>``, this method would be called as
cdb75af2385a Merged revisions 63438 via svnmerge from
Georg Brandl <georg@python.org>
parents:
diff changeset
221 ``handle_pi("proc color='red'")``. It is intended to be overridden by a derived
cdb75af2385a Merged revisions 63438 via svnmerge from
Georg Brandl <georg@python.org>
parents:
diff changeset
222 class; the base class implementation does nothing.
cdb75af2385a Merged revisions 63438 via svnmerge from
Georg Brandl <georg@python.org>
parents:
diff changeset
223
cdb75af2385a Merged revisions 63438 via svnmerge from
Georg Brandl <georg@python.org>
parents:
diff changeset
224 .. note::
cdb75af2385a Merged revisions 63438 via svnmerge from
Georg Brandl <georg@python.org>
parents:
diff changeset
225
cdb75af2385a Merged revisions 63438 via svnmerge from
Georg Brandl <georg@python.org>
parents:
diff changeset
226 The :class:`HTMLParser` class uses the SGML syntactic rules for processing
cdb75af2385a Merged revisions 63438 via svnmerge from
Georg Brandl <georg@python.org>
parents:
diff changeset
227 instructions. An XHTML processing instruction using the trailing ``'?'`` will
cdb75af2385a Merged revisions 63438 via svnmerge from
Georg Brandl <georg@python.org>
parents:
diff changeset
228 cause the ``'?'`` to be included in *data*.
cdb75af2385a Merged revisions 63438 via svnmerge from
Georg Brandl <georg@python.org>
parents:
diff changeset
229
cdb75af2385a Merged revisions 63438 via svnmerge from
Georg Brandl <georg@python.org>
parents:
diff changeset
230
75010
569566cbfd13 #14020: improve HTMLParser documentation.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 73274
diff changeset
231 .. method:: HTMLParser.unknown_decl(data)
569566cbfd13 #14020: improve HTMLParser documentation.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 73274
diff changeset
232
569566cbfd13 #14020: improve HTMLParser documentation.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 73274
diff changeset
233 This method is called when an unrecognized declaration is read by the parser.
569566cbfd13 #14020: improve HTMLParser documentation.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 73274
diff changeset
234
569566cbfd13 #14020: improve HTMLParser documentation.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 73274
diff changeset
235 The *data* parameter will be the entire contents of the declaration inside
569566cbfd13 #14020: improve HTMLParser documentation.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 73274
diff changeset
236 the ``<![...]>`` markup. It is sometimes useful to be overridden by a
569566cbfd13 #14020: improve HTMLParser documentation.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 73274
diff changeset
237 derived class. The base class implementation raises an :exc:`HTMLParseError`
569566cbfd13 #14020: improve HTMLParser documentation.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 73274
diff changeset
238 when *strict* is ``True``.
47151
cdb75af2385a Merged revisions 63438 via svnmerge from
Georg Brandl <georg@python.org>
parents:
diff changeset
239
75010
569566cbfd13 #14020: improve HTMLParser documentation.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 73274
diff changeset
240
569566cbfd13 #14020: improve HTMLParser documentation.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 73274
diff changeset
241 .. _htmlparser-examples:
47151
cdb75af2385a Merged revisions 63438 via svnmerge from
Georg Brandl <georg@python.org>
parents:
diff changeset
242
75010
569566cbfd13 #14020: improve HTMLParser documentation.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 73274
diff changeset
243 Examples
569566cbfd13 #14020: improve HTMLParser documentation.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 73274
diff changeset
244 --------
569566cbfd13 #14020: improve HTMLParser documentation.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 73274
diff changeset
245
569566cbfd13 #14020: improve HTMLParser documentation.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 73274
diff changeset
246 The following class implements a parser that will be used to illustrate more
569566cbfd13 #14020: improve HTMLParser documentation.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 73274
diff changeset
247 examples::
73163
9ddcb6d44bb4 Improve HTMLParser example in the doc and fix a couple minor things.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 68798
diff changeset
248
9ddcb6d44bb4 Improve HTMLParser example in the doc and fix a couple minor things.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 68798
diff changeset
249 from html.parser import HTMLParser
75010
569566cbfd13 #14020: improve HTMLParser documentation.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 73274
diff changeset
250 from html.entities import name2codepoint
47151
cdb75af2385a Merged revisions 63438 via svnmerge from
Georg Brandl <georg@python.org>
parents:
diff changeset
251
73163
9ddcb6d44bb4 Improve HTMLParser example in the doc and fix a couple minor things.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 68798
diff changeset
252 class MyHTMLParser(HTMLParser):
9ddcb6d44bb4 Improve HTMLParser example in the doc and fix a couple minor things.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 68798
diff changeset
253 def handle_starttag(self, tag, attrs):
75010
569566cbfd13 #14020: improve HTMLParser documentation.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 73274
diff changeset
254 print("Start tag:", tag)
569566cbfd13 #14020: improve HTMLParser documentation.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 73274
diff changeset
255 for attr in attrs:
569566cbfd13 #14020: improve HTMLParser documentation.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 73274
diff changeset
256 print(" attr:", attr)
73163
9ddcb6d44bb4 Improve HTMLParser example in the doc and fix a couple minor things.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 68798
diff changeset
257 def handle_endtag(self, tag):
75010
569566cbfd13 #14020: improve HTMLParser documentation.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 73274
diff changeset
258 print("End tag :", tag)
73163
9ddcb6d44bb4 Improve HTMLParser example in the doc and fix a couple minor things.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 68798
diff changeset
259 def handle_data(self, data):
75010
569566cbfd13 #14020: improve HTMLParser documentation.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 73274
diff changeset
260 print("Data :", data)
569566cbfd13 #14020: improve HTMLParser documentation.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 73274
diff changeset
261 def handle_comment(self, data):
569566cbfd13 #14020: improve HTMLParser documentation.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 73274
diff changeset
262 print("Comment :", data)
569566cbfd13 #14020: improve HTMLParser documentation.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 73274
diff changeset
263 def handle_entityref(self, name):
569566cbfd13 #14020: improve HTMLParser documentation.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 73274
diff changeset
264 c = chr(name2codepoint[name])
569566cbfd13 #14020: improve HTMLParser documentation.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 73274
diff changeset
265 print("Named ent:", c)
569566cbfd13 #14020: improve HTMLParser documentation.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 73274
diff changeset
266 def handle_charref(self, name):
569566cbfd13 #14020: improve HTMLParser documentation.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 73274
diff changeset
267 if name.startswith('x'):
569566cbfd13 #14020: improve HTMLParser documentation.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 73274
diff changeset
268 c = chr(int(name[1:], 16))
569566cbfd13 #14020: improve HTMLParser documentation.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 73274
diff changeset
269 else:
569566cbfd13 #14020: improve HTMLParser documentation.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 73274
diff changeset
270 c = chr(int(name))
569566cbfd13 #14020: improve HTMLParser documentation.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 73274
diff changeset
271 print("Num ent :", c)
569566cbfd13 #14020: improve HTMLParser documentation.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 73274
diff changeset
272 def handle_decl(self, data):
569566cbfd13 #14020: improve HTMLParser documentation.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 73274
diff changeset
273 print("Decl :", data)
569566cbfd13 #14020: improve HTMLParser documentation.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 73274
diff changeset
274
569566cbfd13 #14020: improve HTMLParser documentation.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 73274
diff changeset
275 parser = MyHTMLParser(strict=False)
569566cbfd13 #14020: improve HTMLParser documentation.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 73274
diff changeset
276
569566cbfd13 #14020: improve HTMLParser documentation.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 73274
diff changeset
277 Parsing a doctype::
569566cbfd13 #14020: improve HTMLParser documentation.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 73274
diff changeset
278
569566cbfd13 #14020: improve HTMLParser documentation.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 73274
diff changeset
279 >>> parser.feed('<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" '
569566cbfd13 #14020: improve HTMLParser documentation.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 73274
diff changeset
280 ... '"http://www.w3.org/TR/html4/strict.dtd">')
569566cbfd13 #14020: improve HTMLParser documentation.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 73274
diff changeset
281 Decl : DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd"
569566cbfd13 #14020: improve HTMLParser documentation.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 73274
diff changeset
282
569566cbfd13 #14020: improve HTMLParser documentation.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 73274
diff changeset
283 Parsing an element with a few attributes and a title::
569566cbfd13 #14020: improve HTMLParser documentation.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 73274
diff changeset
284
569566cbfd13 #14020: improve HTMLParser documentation.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 73274
diff changeset
285 >>> parser.feed('<img src="python-logo.png" alt="The Python logo">')
569566cbfd13 #14020: improve HTMLParser documentation.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 73274
diff changeset
286 Start tag: img
569566cbfd13 #14020: improve HTMLParser documentation.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 73274
diff changeset
287 attr: ('src', 'python-logo.png')
569566cbfd13 #14020: improve HTMLParser documentation.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 73274
diff changeset
288 attr: ('alt', 'The Python logo')
569566cbfd13 #14020: improve HTMLParser documentation.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 73274
diff changeset
289 >>>
569566cbfd13 #14020: improve HTMLParser documentation.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 73274
diff changeset
290 >>> parser.feed('<h1>Python</h1>')
569566cbfd13 #14020: improve HTMLParser documentation.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 73274
diff changeset
291 Start tag: h1
569566cbfd13 #14020: improve HTMLParser documentation.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 73274
diff changeset
292 Data : Python
569566cbfd13 #14020: improve HTMLParser documentation.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 73274
diff changeset
293 End tag : h1
569566cbfd13 #14020: improve HTMLParser documentation.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 73274
diff changeset
294
569566cbfd13 #14020: improve HTMLParser documentation.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 73274
diff changeset
295 The content of ``script`` and ``style`` elements is returned as is, without
569566cbfd13 #14020: improve HTMLParser documentation.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 73274
diff changeset
296 further parsing::
73163
9ddcb6d44bb4 Improve HTMLParser example in the doc and fix a couple minor things.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 68798
diff changeset
297
75010
569566cbfd13 #14020: improve HTMLParser documentation.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 73274
diff changeset
298 >>> parser.feed('<style type="text/css">#python { color: green }</style>')
569566cbfd13 #14020: improve HTMLParser documentation.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 73274
diff changeset
299 Start tag: style
569566cbfd13 #14020: improve HTMLParser documentation.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 73274
diff changeset
300 attr: ('type', 'text/css')
569566cbfd13 #14020: improve HTMLParser documentation.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 73274
diff changeset
301 Data : #python { color: green }
569566cbfd13 #14020: improve HTMLParser documentation.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 73274
diff changeset
302 End tag : style
569566cbfd13 #14020: improve HTMLParser documentation.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 73274
diff changeset
303 >>>
569566cbfd13 #14020: improve HTMLParser documentation.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 73274
diff changeset
304 >>> parser.feed('<script type="text/javascript">'
569566cbfd13 #14020: improve HTMLParser documentation.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 73274
diff changeset
305 ... 'alert("<strong>hello!</strong>");</script>')
569566cbfd13 #14020: improve HTMLParser documentation.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 73274
diff changeset
306 Start tag: script
569566cbfd13 #14020: improve HTMLParser documentation.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 73274
diff changeset
307 attr: ('type', 'text/javascript')
569566cbfd13 #14020: improve HTMLParser documentation.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 73274
diff changeset
308 Data : alert("<strong>hello!</strong>");
569566cbfd13 #14020: improve HTMLParser documentation.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 73274
diff changeset
309 End tag : script
569566cbfd13 #14020: improve HTMLParser documentation.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 73274
diff changeset
310
569566cbfd13 #14020: improve HTMLParser documentation.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 73274
diff changeset
311 Parsing comments::
569566cbfd13 #14020: improve HTMLParser documentation.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 73274
diff changeset
312
569566cbfd13 #14020: improve HTMLParser documentation.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 73274
diff changeset
313 >>> parser.feed('<!-- a comment -->'
569566cbfd13 #14020: improve HTMLParser documentation.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 73274
diff changeset
314 ... '<!--[if IE 9]>IE-specific content<![endif]-->')
569566cbfd13 #14020: improve HTMLParser documentation.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 73274
diff changeset
315 Comment : a comment
569566cbfd13 #14020: improve HTMLParser documentation.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 73274
diff changeset
316 Comment : [if IE 9]>IE-specific content<![endif]
569566cbfd13 #14020: improve HTMLParser documentation.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 73274
diff changeset
317
569566cbfd13 #14020: improve HTMLParser documentation.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 73274
diff changeset
318 Parsing named and numeric character references and converting them to the
569566cbfd13 #14020: improve HTMLParser documentation.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 73274
diff changeset
319 correct char (note: these 3 references are all equivalent to ``'>'``)::
47151
cdb75af2385a Merged revisions 63438 via svnmerge from
Georg Brandl <georg@python.org>
parents:
diff changeset
320
75010
569566cbfd13 #14020: improve HTMLParser documentation.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 73274
diff changeset
321 >>> parser.feed('&gt;&#62;&#x3E;')
569566cbfd13 #14020: improve HTMLParser documentation.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 73274
diff changeset
322 Named ent: >
569566cbfd13 #14020: improve HTMLParser documentation.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 73274
diff changeset
323 Num ent : >
569566cbfd13 #14020: improve HTMLParser documentation.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 73274
diff changeset
324 Num ent : >
569566cbfd13 #14020: improve HTMLParser documentation.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 73274
diff changeset
325
569566cbfd13 #14020: improve HTMLParser documentation.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 73274
diff changeset
326 Feeding incomplete chunks to :meth:`~HTMLParser.feed` works, but
569566cbfd13 #14020: improve HTMLParser documentation.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 73274
diff changeset
327 :meth:`~HTMLParser.handle_data` might be called more than once::
569566cbfd13 #14020: improve HTMLParser documentation.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 73274
diff changeset
328
569566cbfd13 #14020: improve HTMLParser documentation.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 73274
diff changeset
329 >>> for chunk in ['<sp', 'an>buff', 'ered ', 'text</s', 'pan>']:
569566cbfd13 #14020: improve HTMLParser documentation.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 73274
diff changeset
330 ... parser.feed(chunk)
569566cbfd13 #14020: improve HTMLParser documentation.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 73274
diff changeset
331 ...
569566cbfd13 #14020: improve HTMLParser documentation.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 73274
diff changeset
332 Start tag: span
569566cbfd13 #14020: improve HTMLParser documentation.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 73274
diff changeset
333 Data : buff
569566cbfd13 #14020: improve HTMLParser documentation.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 73274
diff changeset
334 Data : ered
569566cbfd13 #14020: improve HTMLParser documentation.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 73274
diff changeset
335 Data : text
569566cbfd13 #14020: improve HTMLParser documentation.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 73274
diff changeset
336 End tag : span
569566cbfd13 #14020: improve HTMLParser documentation.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 73274
diff changeset
337
569566cbfd13 #14020: improve HTMLParser documentation.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 73274
diff changeset
338 Parsing invalid HTML (e.g. unquoted attributes) also works::
569566cbfd13 #14020: improve HTMLParser documentation.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 73274
diff changeset
339
569566cbfd13 #14020: improve HTMLParser documentation.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 73274
diff changeset
340 >>> parser.feed('<p><a class=link href=#main>tag soup</p ></a>')
569566cbfd13 #14020: improve HTMLParser documentation.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 73274
diff changeset
341 Start tag: p
569566cbfd13 #14020: improve HTMLParser documentation.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 73274
diff changeset
342 Start tag: a
569566cbfd13 #14020: improve HTMLParser documentation.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 73274
diff changeset
343 attr: ('class', 'link')
569566cbfd13 #14020: improve HTMLParser documentation.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 73274
diff changeset
344 attr: ('href', '#main')
569566cbfd13 #14020: improve HTMLParser documentation.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 73274
diff changeset
345 Data : tag soup
569566cbfd13 #14020: improve HTMLParser documentation.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 73274
diff changeset
346 End tag : p
569566cbfd13 #14020: improve HTMLParser documentation.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 73274
diff changeset
347 End tag : a
47151
cdb75af2385a Merged revisions 63438 via svnmerge from
Georg Brandl <georg@python.org>
parents:
diff changeset
348
66623
1cbfeffea19f #1486713: Add a tolerant mode to HTMLParser.
R. David Murray <rdmurray@bitdance.com>
parents: 63674
diff changeset
349 .. rubric:: Footnotes
1cbfeffea19f #1486713: Add a tolerant mode to HTMLParser.
R. David Murray <rdmurray@bitdance.com>
parents: 63674
diff changeset
350
66624
6e49af2e0891 Add missing versionchanged, correct 'throw' wording to 'raise'.
R. David Murray <rdmurray@bitdance.com>
parents: 66623
diff changeset
351 .. [#] For backward compatibility reasons *strict* mode does not raise
6e49af2e0891 Add missing versionchanged, correct 'throw' wording to 'raise'.
R. David Murray <rdmurray@bitdance.com>
parents: 66623
diff changeset
352 exceptions for all non-compliant HTML. That is, some invalid HTML
66623
1cbfeffea19f #1486713: Add a tolerant mode to HTMLParser.
R. David Murray <rdmurray@bitdance.com>
parents: 63674
diff changeset
353 is tolerated even in *strict* mode.