Mercurial > cpython-lru_cache-weakref

annotate Doc/library/htmlparser.rst @ 79675:c0a2294de787 2.7

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