cpython-lru_cache-weakref: Doc/library/html.parser.rst annotate

annotate Doc/library/html.parser.rst @ 87690:66c1c9f32567 default tip

Add use_weakref option to functools.lru_cache The use_weakref option makes lru_cache create weak references to the function arguments when creating the cache key, which prevents them from staying in the memory forever even after all other references to them are gone. This is a proof of concept for http://bugs.python.org/issue19859

author	Radomir Dopieralski <devel@sheep.art.pl>
date	Tue, 03 Dec 2013 16:02:48 +0100
parents	1575f2dd08c4
children

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
87437 1575f2dd08c4 #13633: Added a new convert_charrefs keyword arg to HTMLParser that, when True, automatically converts all character references. Ezio Melotti <ezio.melotti@gmail.com> parents: 86842 diff changeset	19 .. class:: HTMLParser(strict=False, *, convert_charrefs=False)
1575f2dd08c4 #13633: Added a new convert_charrefs keyword arg to HTMLParser that, when True, automatically converts all character references. Ezio Melotti <ezio.melotti@gmail.com> parents: 86842 diff changeset	20
1575f2dd08c4 #13633: Added a new convert_charrefs keyword arg to HTMLParser that, when True, automatically converts all character references. Ezio Melotti <ezio.melotti@gmail.com> parents: 86842 diff changeset	21 Create a parser instance.
47151 cdb75af2385a Merged revisions 63438 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	22
87437 1575f2dd08c4 #13633: Added a new convert_charrefs keyword arg to HTMLParser that, when True, automatically converts all character references. Ezio Melotti <ezio.melotti@gmail.com> parents: 86842 diff changeset	23 If convert_charrefs is ``True`` (default: ``False``), all character
1575f2dd08c4 #13633: Added a new convert_charrefs keyword arg to HTMLParser that, when True, automatically converts all character references. Ezio Melotti <ezio.melotti@gmail.com> parents: 86842 diff changeset	24 references (except the ones in ``script``/``style`` elements) are
1575f2dd08c4 #13633: Added a new convert_charrefs keyword arg to HTMLParser that, when True, automatically converts all character references. Ezio Melotti <ezio.melotti@gmail.com> parents: 86842 diff changeset	25 automatically converted to the corresponding Unicode characters.
1575f2dd08c4 #13633: Added a new convert_charrefs keyword arg to HTMLParser that, when True, automatically converts all character references. Ezio Melotti <ezio.melotti@gmail.com> parents: 86842 diff changeset	26 The use of ``convert_charrefs=True`` is encouraged and will become
1575f2dd08c4 #13633: Added a new convert_charrefs keyword arg to HTMLParser that, when True, automatically converts all character references. Ezio Melotti <ezio.melotti@gmail.com> parents: 86842 diff changeset	27 the default in Python 3.5.
1575f2dd08c4 #13633: Added a new convert_charrefs keyword arg to HTMLParser that, when True, automatically converts all character references. Ezio Melotti <ezio.melotti@gmail.com> parents: 86842 diff changeset	28
1575f2dd08c4 #13633: Added a new convert_charrefs keyword arg to HTMLParser that, when True, automatically converts all character references. Ezio Melotti <ezio.melotti@gmail.com> parents: 86842 diff changeset	29 If strict is ``False`` (the default), the parser will accept and parse
1575f2dd08c4 #13633: Added a new convert_charrefs keyword arg to HTMLParser that, when True, automatically converts all character references. Ezio Melotti <ezio.melotti@gmail.com> parents: 86842 diff changeset	30 invalid markup. If strict is ``True`` the parser will raise an
1575f2dd08c4 #13633: Added a new convert_charrefs keyword arg to HTMLParser that, when True, automatically converts all character references. Ezio Melotti <ezio.melotti@gmail.com> parents: 86842 diff changeset	31 :exc:`~html.parser.HTMLParseError` exception instead [#]_ when it's not
1575f2dd08c4 #13633: Added a new convert_charrefs keyword arg to HTMLParser that, when True, automatically converts all character references. Ezio Melotti <ezio.melotti@gmail.com> parents: 86842 diff changeset	32 able to parse the markup. The use of ``strict=True`` is discouraged and
1575f2dd08c4 #13633: Added a new convert_charrefs keyword arg to HTMLParser that, when True, automatically converts all character references. Ezio Melotti <ezio.melotti@gmail.com> parents: 86842 diff changeset	33 the strict argument is deprecated.
47151 cdb75af2385a Merged revisions 63438 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	34
75010 569566cbfd13 #14020: improve HTMLParser documentation. Ezio Melotti <ezio.melotti@gmail.com> parents: 73274 diff changeset	35 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	36 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	37 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	38 methods to implement the desired behavior.
47151 cdb75af2385a Merged revisions 63438 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	39
47434 f150177ff1ff Remove the htmllib and sgmllib modules as per PEP 3108. Georg Brandl <georg@python.org> parents: 47151 diff changeset	40 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	41 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	42
77753 653cf179491d Fix a couple of versionadded/versionchanged related markup errors. Georg Brandl <georg@python.org> parents: 77630 diff changeset	43 .. versionchanged:: 3.2
87437 1575f2dd08c4 #13633: Added a new convert_charrefs keyword arg to HTMLParser that, when True, automatically converts all character references. Ezio Melotti <ezio.melotti@gmail.com> parents: 86842 diff changeset	44 strict argument added.
66624 6e49af2e0891 Add missing versionchanged, correct 'throw' wording to 'raise'. R. David Murray <rdmurray@bitdance.com> parents: 66623 diff changeset	45
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	46 .. 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	47 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	48 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	49
87437 1575f2dd08c4 #13633: Added a new convert_charrefs keyword arg to HTMLParser that, when True, automatically converts all character references. Ezio Melotti <ezio.melotti@gmail.com> parents: 86842 diff changeset	50 .. versionchanged:: 3.4
1575f2dd08c4 #13633: Added a new convert_charrefs keyword arg to HTMLParser that, when True, automatically converts all character references. Ezio Melotti <ezio.melotti@gmail.com> parents: 86842 diff changeset	51 convert_charrefs keyword argument added.
1575f2dd08c4 #13633: Added a new convert_charrefs keyword arg to HTMLParser that, when True, automatically converts all character references. Ezio Melotti <ezio.melotti@gmail.com> parents: 86842 diff changeset	52
47151 cdb75af2385a Merged revisions 63438 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	53 An exception is defined as well:
cdb75af2385a Merged revisions 63438 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	54
cdb75af2385a Merged revisions 63438 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	55
cdb75af2385a Merged revisions 63438 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	56 .. exception:: HTMLParseError
cdb75af2385a Merged revisions 63438 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	57
cdb75af2385a Merged revisions 63438 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	58 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	59 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	60 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	61 :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	62 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	63 which the construct starts.
569566cbfd13 #14020: improve HTMLParser documentation. Ezio Melotti <ezio.melotti@gmail.com> parents: 73274 diff changeset	64
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	65 .. 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	66 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	67 (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	68
75010 569566cbfd13 #14020: improve HTMLParser documentation. Ezio Melotti <ezio.melotti@gmail.com> parents: 73274 diff changeset	69
569566cbfd13 #14020: improve HTMLParser documentation. Ezio Melotti <ezio.melotti@gmail.com> parents: 73274 diff changeset	70 Example HTML Parser Application
569566cbfd13 #14020: improve HTMLParser documentation. Ezio Melotti <ezio.melotti@gmail.com> parents: 73274 diff changeset	71 -------------------------------
569566cbfd13 #14020: improve HTMLParser documentation. Ezio Melotti <ezio.melotti@gmail.com> parents: 73274 diff changeset	72
569566cbfd13 #14020: improve HTMLParser documentation. Ezio Melotti <ezio.melotti@gmail.com> parents: 73274 diff changeset	73 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	74 :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	75 as they are encountered::
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 from html.parser import HTMLParser
569566cbfd13 #14020: improve HTMLParser documentation. Ezio Melotti <ezio.melotti@gmail.com> parents: 73274 diff changeset	78
569566cbfd13 #14020: improve HTMLParser documentation. Ezio Melotti <ezio.melotti@gmail.com> parents: 73274 diff changeset	79 class MyHTMLParser(HTMLParser):
569566cbfd13 #14020: improve HTMLParser documentation. Ezio Melotti <ezio.melotti@gmail.com> parents: 73274 diff changeset	80 def handle_starttag(self, tag, attrs):
569566cbfd13 #14020: improve HTMLParser documentation. Ezio Melotti <ezio.melotti@gmail.com> parents: 73274 diff changeset	81 print("Encountered a start tag:", tag)
569566cbfd13 #14020: improve HTMLParser documentation. Ezio Melotti <ezio.melotti@gmail.com> parents: 73274 diff changeset	82 def handle_endtag(self, tag):
569566cbfd13 #14020: improve HTMLParser documentation. Ezio Melotti <ezio.melotti@gmail.com> parents: 73274 diff changeset	83 print("Encountered an end tag :", tag)
569566cbfd13 #14020: improve HTMLParser documentation. Ezio Melotti <ezio.melotti@gmail.com> parents: 73274 diff changeset	84 def handle_data(self, data):
569566cbfd13 #14020: improve HTMLParser documentation. Ezio Melotti <ezio.melotti@gmail.com> parents: 73274 diff changeset	85 print("Encountered some data :", data)
569566cbfd13 #14020: improve HTMLParser documentation. Ezio Melotti <ezio.melotti@gmail.com> parents: 73274 diff changeset	86
86842 0a56709eb798 #15114: The html.parser module now raises a DeprecationWarning when the strict argument of HTMLParser or the HTMLParser.error method are used. Ezio Melotti <ezio.melotti@gmail.com> parents: 77753 diff changeset	87 parser = MyHTMLParser()
75010 569566cbfd13 #14020: improve HTMLParser documentation. Ezio Melotti <ezio.melotti@gmail.com> parents: 73274 diff changeset	88 parser.feed('<html><head><title>Test</title></head>'
569566cbfd13 #14020: improve HTMLParser documentation. Ezio Melotti <ezio.melotti@gmail.com> parents: 73274 diff changeset	89 '<body><h1>Parse me!</h1></body></html>')
569566cbfd13 #14020: improve HTMLParser documentation. Ezio Melotti <ezio.melotti@gmail.com> parents: 73274 diff changeset	90
569566cbfd13 #14020: improve HTMLParser documentation. Ezio Melotti <ezio.melotti@gmail.com> parents: 73274 diff changeset	91 The output will then be::
569566cbfd13 #14020: improve HTMLParser documentation. Ezio Melotti <ezio.melotti@gmail.com> parents: 73274 diff changeset	92
569566cbfd13 #14020: improve HTMLParser documentation. Ezio Melotti <ezio.melotti@gmail.com> parents: 73274 diff changeset	93 Encountered a start tag: html
569566cbfd13 #14020: improve HTMLParser documentation. Ezio Melotti <ezio.melotti@gmail.com> parents: 73274 diff changeset	94 Encountered a start tag: head
569566cbfd13 #14020: improve HTMLParser documentation. Ezio Melotti <ezio.melotti@gmail.com> parents: 73274 diff changeset	95 Encountered a start tag: title
569566cbfd13 #14020: improve HTMLParser documentation. Ezio Melotti <ezio.melotti@gmail.com> parents: 73274 diff changeset	96 Encountered some data : Test
569566cbfd13 #14020: improve HTMLParser documentation. Ezio Melotti <ezio.melotti@gmail.com> parents: 73274 diff changeset	97 Encountered an end tag : title
569566cbfd13 #14020: improve HTMLParser documentation. Ezio Melotti <ezio.melotti@gmail.com> parents: 73274 diff changeset	98 Encountered an end tag : head
569566cbfd13 #14020: improve HTMLParser documentation. Ezio Melotti <ezio.melotti@gmail.com> parents: 73274 diff changeset	99 Encountered a start tag: body
569566cbfd13 #14020: improve HTMLParser documentation. Ezio Melotti <ezio.melotti@gmail.com> parents: 73274 diff changeset	100 Encountered a start tag: h1
569566cbfd13 #14020: improve HTMLParser documentation. Ezio Melotti <ezio.melotti@gmail.com> parents: 73274 diff changeset	101 Encountered some data : Parse me!
569566cbfd13 #14020: improve HTMLParser documentation. Ezio Melotti <ezio.melotti@gmail.com> parents: 73274 diff changeset	102 Encountered an end tag : h1
569566cbfd13 #14020: improve HTMLParser documentation. Ezio Melotti <ezio.melotti@gmail.com> parents: 73274 diff changeset	103 Encountered an end tag : body
569566cbfd13 #14020: improve HTMLParser documentation. Ezio Melotti <ezio.melotti@gmail.com> parents: 73274 diff changeset	104 Encountered an end tag : html
569566cbfd13 #14020: improve HTMLParser documentation. Ezio Melotti <ezio.melotti@gmail.com> parents: 73274 diff changeset	105
569566cbfd13 #14020: improve HTMLParser documentation. Ezio Melotti <ezio.melotti@gmail.com> parents: 73274 diff changeset	106
569566cbfd13 #14020: improve HTMLParser documentation. Ezio Melotti <ezio.melotti@gmail.com> parents: 73274 diff changeset	107 :class:`.HTMLParser` Methods
569566cbfd13 #14020: improve HTMLParser documentation. Ezio Melotti <ezio.melotti@gmail.com> parents: 73274 diff changeset	108 ----------------------------
47151 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 :class:`HTMLParser` instances have the following methods:
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
cdb75af2385a Merged revisions 63438 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	113 .. method:: HTMLParser.feed(data)
cdb75af2385a Merged revisions 63438 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	114
cdb75af2385a Merged revisions 63438 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	115 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	116 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	117 :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	118
cdb75af2385a Merged revisions 63438 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	119
cdb75af2385a Merged revisions 63438 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	120 .. method:: HTMLParser.close()
cdb75af2385a Merged revisions 63438 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	121
cdb75af2385a Merged revisions 63438 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	122 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	123 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	124 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	125 the :class:`HTMLParser` base class method :meth:`close`.
cdb75af2385a Merged revisions 63438 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	126
cdb75af2385a Merged revisions 63438 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	127
75010 569566cbfd13 #14020: improve HTMLParser documentation. Ezio Melotti <ezio.melotti@gmail.com> parents: 73274 diff changeset	128 .. method:: HTMLParser.reset()
569566cbfd13 #14020: improve HTMLParser documentation. Ezio Melotti <ezio.melotti@gmail.com> parents: 73274 diff changeset	129
569566cbfd13 #14020: improve HTMLParser documentation. Ezio Melotti <ezio.melotti@gmail.com> parents: 73274 diff changeset	130 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	131 instantiation time.
569566cbfd13 #14020: improve HTMLParser documentation. Ezio Melotti <ezio.melotti@gmail.com> parents: 73274 diff changeset	132
569566cbfd13 #14020: improve HTMLParser documentation. Ezio Melotti <ezio.melotti@gmail.com> parents: 73274 diff changeset	133
47151 cdb75af2385a Merged revisions 63438 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	134 .. method:: HTMLParser.getpos()
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 Return current line number and offset.
cdb75af2385a Merged revisions 63438 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	137
cdb75af2385a Merged revisions 63438 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	138
cdb75af2385a Merged revisions 63438 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	139 .. method:: HTMLParser.get_starttag_text()
cdb75af2385a Merged revisions 63438 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	140
cdb75af2385a Merged revisions 63438 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	141 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	142 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	143 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	144 attributes can be preserved, etc.).
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
75010 569566cbfd13 #14020: improve HTMLParser documentation. Ezio Melotti <ezio.melotti@gmail.com> parents: 73274 diff changeset	147 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	148 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	149 implementations do nothing (except for :meth:`~HTMLParser.handle_startendtag`):
569566cbfd13 #14020: improve HTMLParser documentation. Ezio Melotti <ezio.melotti@gmail.com> parents: 73274 diff changeset	150
569566cbfd13 #14020: improve HTMLParser documentation. Ezio Melotti <ezio.melotti@gmail.com> parents: 73274 diff changeset	151
47151 cdb75af2385a Merged revisions 63438 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	152 .. method:: HTMLParser.handle_starttag(tag, attrs)
cdb75af2385a Merged revisions 63438 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	153
75010 569566cbfd13 #14020: improve HTMLParser documentation. Ezio Melotti <ezio.melotti@gmail.com> parents: 73274 diff changeset	154 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	155
cdb75af2385a Merged revisions 63438 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	156 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	157 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	158 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	159 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	160 have been replaced.
569566cbfd13 #14020: improve HTMLParser documentation. Ezio Melotti <ezio.melotti@gmail.com> parents: 73274 diff changeset	161
569566cbfd13 #14020: improve HTMLParser documentation. Ezio Melotti <ezio.melotti@gmail.com> parents: 73274 diff changeset	162 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	163 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	164
cdb75af2385a Merged revisions 63438 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	165 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	166 values.
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
75010 569566cbfd13 #14020: improve HTMLParser documentation. Ezio Melotti <ezio.melotti@gmail.com> parents: 73274 diff changeset	169 .. method:: HTMLParser.handle_endtag(tag)
569566cbfd13 #14020: improve HTMLParser documentation. Ezio Melotti <ezio.melotti@gmail.com> parents: 73274 diff changeset	170
569566cbfd13 #14020: improve HTMLParser documentation. Ezio Melotti <ezio.melotti@gmail.com> parents: 73274 diff changeset	171 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	172
569566cbfd13 #14020: improve HTMLParser documentation. Ezio Melotti <ezio.melotti@gmail.com> parents: 73274 diff changeset	173 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	174
569566cbfd13 #14020: improve HTMLParser documentation. Ezio Melotti <ezio.melotti@gmail.com> parents: 73274 diff changeset	175
47151 cdb75af2385a Merged revisions 63438 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	176 .. method:: HTMLParser.handle_startendtag(tag, attrs)
cdb75af2385a Merged revisions 63438 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	177
cdb75af2385a Merged revisions 63438 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	178 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	179 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	180 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	181 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	182
cdb75af2385a Merged revisions 63438 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	183
cdb75af2385a Merged revisions 63438 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	184 .. method:: HTMLParser.handle_data(data)
cdb75af2385a Merged revisions 63438 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	185
75010 569566cbfd13 #14020: improve HTMLParser documentation. Ezio Melotti <ezio.melotti@gmail.com> parents: 73274 diff changeset	186 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	187 content of ``<script>...</script>`` and ``<style>...</style>``).
47151 cdb75af2385a Merged revisions 63438 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	188
cdb75af2385a Merged revisions 63438 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	189
cdb75af2385a Merged revisions 63438 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	190 .. method:: HTMLParser.handle_entityref(name)
cdb75af2385a Merged revisions 63438 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	191
75010 569566cbfd13 #14020: improve HTMLParser documentation. Ezio Melotti <ezio.melotti@gmail.com> parents: 73274 diff changeset	192 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	193 ``&name;`` (e.g. ``>``), where name is a general entity reference
87437 1575f2dd08c4 #13633: Added a new convert_charrefs keyword arg to HTMLParser that, when True, automatically converts all character references. Ezio Melotti <ezio.melotti@gmail.com> parents: 86842 diff changeset	194 (e.g. ``'gt'``). This method is never called if convert_charrefs is
1575f2dd08c4 #13633: Added a new convert_charrefs keyword arg to HTMLParser that, when True, automatically converts all character references. Ezio Melotti <ezio.melotti@gmail.com> parents: 86842 diff changeset	195 ``True``.
75010 569566cbfd13 #14020: improve HTMLParser documentation. Ezio Melotti <ezio.melotti@gmail.com> parents: 73274 diff changeset	196
569566cbfd13 #14020: improve HTMLParser documentation. Ezio Melotti <ezio.melotti@gmail.com> parents: 73274 diff changeset	197
569566cbfd13 #14020: improve HTMLParser documentation. Ezio Melotti <ezio.melotti@gmail.com> parents: 73274 diff changeset	198 .. method:: HTMLParser.handle_charref(name)
569566cbfd13 #14020: improve HTMLParser documentation. Ezio Melotti <ezio.melotti@gmail.com> parents: 73274 diff changeset	199
569566cbfd13 #14020: improve HTMLParser documentation. Ezio Melotti <ezio.melotti@gmail.com> parents: 73274 diff changeset	200 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	201 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	202 equivalent for ``>`` is ``>``, whereas the hexadecimal is ``>``;
87437 1575f2dd08c4 #13633: Added a new convert_charrefs keyword arg to HTMLParser that, when True, automatically converts all character references. Ezio Melotti <ezio.melotti@gmail.com> parents: 86842 diff changeset	203 in this case the method will receive ``'62'`` or ``'x3E'``. This method
1575f2dd08c4 #13633: Added a new convert_charrefs keyword arg to HTMLParser that, when True, automatically converts all character references. Ezio Melotti <ezio.melotti@gmail.com> parents: 86842 diff changeset	204 is never called if convert_charrefs is ``True``.
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_comment(data)
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 when a comment is encountered (e.g. ``<!--comment-->``).
569566cbfd13 #14020: improve HTMLParser documentation. Ezio Melotti <ezio.melotti@gmail.com> parents: 73274 diff changeset	210
569566cbfd13 #14020: improve HTMLParser documentation. Ezio Melotti <ezio.melotti@gmail.com> parents: 73274 diff changeset	211 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	212 called with the argument ``' comment '``.
569566cbfd13 #14020: improve HTMLParser documentation. Ezio Melotti <ezio.melotti@gmail.com> parents: 73274 diff changeset	213
569566cbfd13 #14020: improve HTMLParser documentation. Ezio Melotti <ezio.melotti@gmail.com> parents: 73274 diff changeset	214 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	215 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	216 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	217
cdb75af2385a Merged revisions 63438 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	218
cdb75af2385a Merged revisions 63438 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	219 .. method:: HTMLParser.handle_decl(decl)
cdb75af2385a Merged revisions 63438 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	220
75010 569566cbfd13 #14020: improve HTMLParser documentation. Ezio Melotti <ezio.melotti@gmail.com> parents: 73274 diff changeset	221 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	222 ``<!DOCTYPE html>``).
63284 054f3279e3cc #3874: document HTMLParser.unknown_decl(). Georg Brandl <georg@python.org> parents: 55600 diff changeset	223
75010 569566cbfd13 #14020: improve HTMLParser documentation. Ezio Melotti <ezio.melotti@gmail.com> parents: 73274 diff changeset	224 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	225 the ``<!...>`` markup (e.g. ``'DOCTYPE html'``).
47151 cdb75af2385a Merged revisions 63438 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	226
cdb75af2385a Merged revisions 63438 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	227
cdb75af2385a Merged revisions 63438 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	228 .. method:: HTMLParser.handle_pi(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 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	231 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	232 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	233 ``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	234 class; the base class implementation does nothing.
cdb75af2385a Merged revisions 63438 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	235
cdb75af2385a Merged revisions 63438 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	236 .. note::
cdb75af2385a Merged revisions 63438 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	237
cdb75af2385a Merged revisions 63438 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	238 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	239 instructions. An XHTML processing instruction using the trailing ``'?'`` will
cdb75af2385a Merged revisions 63438 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	240 cause the ``'?'`` to be included in data.
cdb75af2385a Merged revisions 63438 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	241
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 .. method:: HTMLParser.unknown_decl(data)
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 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	246
569566cbfd13 #14020: improve HTMLParser documentation. Ezio Melotti <ezio.melotti@gmail.com> parents: 73274 diff changeset	247 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	248 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	249 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	250 when strict is ``True``.
47151 cdb75af2385a Merged revisions 63438 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	251
75010 569566cbfd13 #14020: improve HTMLParser documentation. Ezio Melotti <ezio.melotti@gmail.com> parents: 73274 diff changeset	252
569566cbfd13 #14020: improve HTMLParser documentation. Ezio Melotti <ezio.melotti@gmail.com> parents: 73274 diff changeset	253 .. _htmlparser-examples:
47151 cdb75af2385a Merged revisions 63438 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	254
75010 569566cbfd13 #14020: improve HTMLParser documentation. Ezio Melotti <ezio.melotti@gmail.com> parents: 73274 diff changeset	255 Examples
569566cbfd13 #14020: improve HTMLParser documentation. Ezio Melotti <ezio.melotti@gmail.com> parents: 73274 diff changeset	256 --------
569566cbfd13 #14020: improve HTMLParser documentation. Ezio Melotti <ezio.melotti@gmail.com> parents: 73274 diff changeset	257
569566cbfd13 #14020: improve HTMLParser documentation. Ezio Melotti <ezio.melotti@gmail.com> parents: 73274 diff changeset	258 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	259 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	260
9ddcb6d44bb4 Improve HTMLParser example in the doc and fix a couple minor things. Ezio Melotti <ezio.melotti@gmail.com> parents: 68798 diff changeset	261 from html.parser import HTMLParser
75010 569566cbfd13 #14020: improve HTMLParser documentation. Ezio Melotti <ezio.melotti@gmail.com> parents: 73274 diff changeset	262 from html.entities import name2codepoint
47151 cdb75af2385a Merged revisions 63438 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	263
73163 9ddcb6d44bb4 Improve HTMLParser example in the doc and fix a couple minor things. Ezio Melotti <ezio.melotti@gmail.com> parents: 68798 diff changeset	264 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	265 def handle_starttag(self, tag, attrs):
75010 569566cbfd13 #14020: improve HTMLParser documentation. Ezio Melotti <ezio.melotti@gmail.com> parents: 73274 diff changeset	266 print("Start tag:", tag)
569566cbfd13 #14020: improve HTMLParser documentation. Ezio Melotti <ezio.melotti@gmail.com> parents: 73274 diff changeset	267 for attr in attrs:
569566cbfd13 #14020: improve HTMLParser documentation. Ezio Melotti <ezio.melotti@gmail.com> parents: 73274 diff changeset	268 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	269 def handle_endtag(self, tag):
75010 569566cbfd13 #14020: improve HTMLParser documentation. Ezio Melotti <ezio.melotti@gmail.com> parents: 73274 diff changeset	270 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	271 def handle_data(self, data):
75010 569566cbfd13 #14020: improve HTMLParser documentation. Ezio Melotti <ezio.melotti@gmail.com> parents: 73274 diff changeset	272 print("Data :", data)
569566cbfd13 #14020: improve HTMLParser documentation. Ezio Melotti <ezio.melotti@gmail.com> parents: 73274 diff changeset	273 def handle_comment(self, data):
569566cbfd13 #14020: improve HTMLParser documentation. Ezio Melotti <ezio.melotti@gmail.com> parents: 73274 diff changeset	274 print("Comment :", data)
569566cbfd13 #14020: improve HTMLParser documentation. Ezio Melotti <ezio.melotti@gmail.com> parents: 73274 diff changeset	275 def handle_entityref(self, name):
569566cbfd13 #14020: improve HTMLParser documentation. Ezio Melotti <ezio.melotti@gmail.com> parents: 73274 diff changeset	276 c = chr(name2codepoint[name])
569566cbfd13 #14020: improve HTMLParser documentation. Ezio Melotti <ezio.melotti@gmail.com> parents: 73274 diff changeset	277 print("Named ent:", c)
569566cbfd13 #14020: improve HTMLParser documentation. Ezio Melotti <ezio.melotti@gmail.com> parents: 73274 diff changeset	278 def handle_charref(self, name):
569566cbfd13 #14020: improve HTMLParser documentation. Ezio Melotti <ezio.melotti@gmail.com> parents: 73274 diff changeset	279 if name.startswith('x'):
569566cbfd13 #14020: improve HTMLParser documentation. Ezio Melotti <ezio.melotti@gmail.com> parents: 73274 diff changeset	280 c = chr(int(name[1:], 16))
569566cbfd13 #14020: improve HTMLParser documentation. Ezio Melotti <ezio.melotti@gmail.com> parents: 73274 diff changeset	281 else:
569566cbfd13 #14020: improve HTMLParser documentation. Ezio Melotti <ezio.melotti@gmail.com> parents: 73274 diff changeset	282 c = chr(int(name))
569566cbfd13 #14020: improve HTMLParser documentation. Ezio Melotti <ezio.melotti@gmail.com> parents: 73274 diff changeset	283 print("Num ent :", c)
569566cbfd13 #14020: improve HTMLParser documentation. Ezio Melotti <ezio.melotti@gmail.com> parents: 73274 diff changeset	284 def handle_decl(self, data):
569566cbfd13 #14020: improve HTMLParser documentation. Ezio Melotti <ezio.melotti@gmail.com> parents: 73274 diff changeset	285 print("Decl :", data)
569566cbfd13 #14020: improve HTMLParser documentation. Ezio Melotti <ezio.melotti@gmail.com> parents: 73274 diff changeset	286
86842 0a56709eb798 #15114: The html.parser module now raises a DeprecationWarning when the strict argument of HTMLParser or the HTMLParser.error method are used. Ezio Melotti <ezio.melotti@gmail.com> parents: 77753 diff changeset	287 parser = MyHTMLParser()
75010 569566cbfd13 #14020: improve HTMLParser documentation. Ezio Melotti <ezio.melotti@gmail.com> parents: 73274 diff changeset	288
569566cbfd13 #14020: improve HTMLParser documentation. Ezio Melotti <ezio.melotti@gmail.com> parents: 73274 diff changeset	289 Parsing a doctype::
569566cbfd13 #14020: improve HTMLParser documentation. Ezio Melotti <ezio.melotti@gmail.com> parents: 73274 diff changeset	290
569566cbfd13 #14020: improve HTMLParser documentation. Ezio Melotti <ezio.melotti@gmail.com> parents: 73274 diff changeset	291 >>> 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	292 ... '"http://www.w3.org/TR/html4/strict.dtd">')
569566cbfd13 #14020: improve HTMLParser documentation. Ezio Melotti <ezio.melotti@gmail.com> parents: 73274 diff changeset	293 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	294
569566cbfd13 #14020: improve HTMLParser documentation. Ezio Melotti <ezio.melotti@gmail.com> parents: 73274 diff changeset	295 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	296
569566cbfd13 #14020: improve HTMLParser documentation. Ezio Melotti <ezio.melotti@gmail.com> parents: 73274 diff changeset	297 >>> 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	298 Start tag: img
569566cbfd13 #14020: improve HTMLParser documentation. Ezio Melotti <ezio.melotti@gmail.com> parents: 73274 diff changeset	299 attr: ('src', 'python-logo.png')
569566cbfd13 #14020: improve HTMLParser documentation. Ezio Melotti <ezio.melotti@gmail.com> parents: 73274 diff changeset	300 attr: ('alt', 'The Python logo')
569566cbfd13 #14020: improve HTMLParser documentation. Ezio Melotti <ezio.melotti@gmail.com> parents: 73274 diff changeset	301 >>>
569566cbfd13 #14020: improve HTMLParser documentation. Ezio Melotti <ezio.melotti@gmail.com> parents: 73274 diff changeset	302 >>> parser.feed('<h1>Python</h1>')
569566cbfd13 #14020: improve HTMLParser documentation. Ezio Melotti <ezio.melotti@gmail.com> parents: 73274 diff changeset	303 Start tag: h1
569566cbfd13 #14020: improve HTMLParser documentation. Ezio Melotti <ezio.melotti@gmail.com> parents: 73274 diff changeset	304 Data : Python
569566cbfd13 #14020: improve HTMLParser documentation. Ezio Melotti <ezio.melotti@gmail.com> parents: 73274 diff changeset	305 End tag : h1
569566cbfd13 #14020: improve HTMLParser documentation. Ezio Melotti <ezio.melotti@gmail.com> parents: 73274 diff changeset	306
569566cbfd13 #14020: improve HTMLParser documentation. Ezio Melotti <ezio.melotti@gmail.com> parents: 73274 diff changeset	307 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	308 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	309
75010 569566cbfd13 #14020: improve HTMLParser documentation. Ezio Melotti <ezio.melotti@gmail.com> parents: 73274 diff changeset	310 >>> 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	311 Start tag: style
569566cbfd13 #14020: improve HTMLParser documentation. Ezio Melotti <ezio.melotti@gmail.com> parents: 73274 diff changeset	312 attr: ('type', 'text/css')
569566cbfd13 #14020: improve HTMLParser documentation. Ezio Melotti <ezio.melotti@gmail.com> parents: 73274 diff changeset	313 Data : #python { color: green }
569566cbfd13 #14020: improve HTMLParser documentation. Ezio Melotti <ezio.melotti@gmail.com> parents: 73274 diff changeset	314 End tag : style
569566cbfd13 #14020: improve HTMLParser documentation. Ezio Melotti <ezio.melotti@gmail.com> parents: 73274 diff changeset	315 >>>
569566cbfd13 #14020: improve HTMLParser documentation. Ezio Melotti <ezio.melotti@gmail.com> parents: 73274 diff changeset	316 >>> parser.feed('<script type="text/javascript">'
569566cbfd13 #14020: improve HTMLParser documentation. Ezio Melotti <ezio.melotti@gmail.com> parents: 73274 diff changeset	317 ... 'alert("<strong>hello!</strong>");</script>')
569566cbfd13 #14020: improve HTMLParser documentation. Ezio Melotti <ezio.melotti@gmail.com> parents: 73274 diff changeset	318 Start tag: script
569566cbfd13 #14020: improve HTMLParser documentation. Ezio Melotti <ezio.melotti@gmail.com> parents: 73274 diff changeset	319 attr: ('type', 'text/javascript')
569566cbfd13 #14020: improve HTMLParser documentation. Ezio Melotti <ezio.melotti@gmail.com> parents: 73274 diff changeset	320 Data : alert("<strong>hello!</strong>");
569566cbfd13 #14020: improve HTMLParser documentation. Ezio Melotti <ezio.melotti@gmail.com> parents: 73274 diff changeset	321 End tag : script
569566cbfd13 #14020: improve HTMLParser documentation. Ezio Melotti <ezio.melotti@gmail.com> parents: 73274 diff changeset	322
569566cbfd13 #14020: improve HTMLParser documentation. Ezio Melotti <ezio.melotti@gmail.com> parents: 73274 diff changeset	323 Parsing comments::
569566cbfd13 #14020: improve HTMLParser documentation. Ezio Melotti <ezio.melotti@gmail.com> parents: 73274 diff changeset	324
569566cbfd13 #14020: improve HTMLParser documentation. Ezio Melotti <ezio.melotti@gmail.com> parents: 73274 diff changeset	325 >>> parser.feed('<!-- a comment -->'
569566cbfd13 #14020: improve HTMLParser documentation. Ezio Melotti <ezio.melotti@gmail.com> parents: 73274 diff changeset	326 ... '<!--[if IE 9]>IE-specific content<![endif]-->')
569566cbfd13 #14020: improve HTMLParser documentation. Ezio Melotti <ezio.melotti@gmail.com> parents: 73274 diff changeset	327 Comment : a comment
569566cbfd13 #14020: improve HTMLParser documentation. Ezio Melotti <ezio.melotti@gmail.com> parents: 73274 diff changeset	328 Comment : [if IE 9]>IE-specific content<![endif]
569566cbfd13 #14020: improve HTMLParser documentation. Ezio Melotti <ezio.melotti@gmail.com> parents: 73274 diff changeset	329
569566cbfd13 #14020: improve HTMLParser documentation. Ezio Melotti <ezio.melotti@gmail.com> parents: 73274 diff changeset	330 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	331 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	332
75010 569566cbfd13 #14020: improve HTMLParser documentation. Ezio Melotti <ezio.melotti@gmail.com> parents: 73274 diff changeset	333 >>> parser.feed('>>>')
569566cbfd13 #14020: improve HTMLParser documentation. Ezio Melotti <ezio.melotti@gmail.com> parents: 73274 diff changeset	334 Named ent: >
569566cbfd13 #14020: improve HTMLParser documentation. Ezio Melotti <ezio.melotti@gmail.com> parents: 73274 diff changeset	335 Num ent : >
569566cbfd13 #14020: improve HTMLParser documentation. Ezio Melotti <ezio.melotti@gmail.com> parents: 73274 diff changeset	336 Num ent : >
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 Feeding incomplete chunks to :meth:`~HTMLParser.feed` works, but
87437 1575f2dd08c4 #13633: Added a new convert_charrefs keyword arg to HTMLParser that, when True, automatically converts all character references. Ezio Melotti <ezio.melotti@gmail.com> parents: 86842 diff changeset	339 :meth:`~HTMLParser.handle_data` might be called more than once
1575f2dd08c4 #13633: Added a new convert_charrefs keyword arg to HTMLParser that, when True, automatically converts all character references. Ezio Melotti <ezio.melotti@gmail.com> parents: 86842 diff changeset	340 (unless convert_charrefs is set to ``True``)::
75010 569566cbfd13 #14020: improve HTMLParser documentation. Ezio Melotti <ezio.melotti@gmail.com> parents: 73274 diff changeset	341
569566cbfd13 #14020: improve HTMLParser documentation. Ezio Melotti <ezio.melotti@gmail.com> parents: 73274 diff changeset	342 >>> 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	343 ... parser.feed(chunk)
569566cbfd13 #14020: improve HTMLParser documentation. Ezio Melotti <ezio.melotti@gmail.com> parents: 73274 diff changeset	344 ...
569566cbfd13 #14020: improve HTMLParser documentation. Ezio Melotti <ezio.melotti@gmail.com> parents: 73274 diff changeset	345 Start tag: span
569566cbfd13 #14020: improve HTMLParser documentation. Ezio Melotti <ezio.melotti@gmail.com> parents: 73274 diff changeset	346 Data : buff
569566cbfd13 #14020: improve HTMLParser documentation. Ezio Melotti <ezio.melotti@gmail.com> parents: 73274 diff changeset	347 Data : ered
569566cbfd13 #14020: improve HTMLParser documentation. Ezio Melotti <ezio.melotti@gmail.com> parents: 73274 diff changeset	348 Data : text
569566cbfd13 #14020: improve HTMLParser documentation. Ezio Melotti <ezio.melotti@gmail.com> parents: 73274 diff changeset	349 End tag : span
569566cbfd13 #14020: improve HTMLParser documentation. Ezio Melotti <ezio.melotti@gmail.com> parents: 73274 diff changeset	350
569566cbfd13 #14020: improve HTMLParser documentation. Ezio Melotti <ezio.melotti@gmail.com> parents: 73274 diff changeset	351 Parsing invalid HTML (e.g. unquoted attributes) also works::
569566cbfd13 #14020: improve HTMLParser documentation. Ezio Melotti <ezio.melotti@gmail.com> parents: 73274 diff changeset	352
569566cbfd13 #14020: improve HTMLParser documentation. Ezio Melotti <ezio.melotti@gmail.com> parents: 73274 diff changeset	353 >>> 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	354 Start tag: p
569566cbfd13 #14020: improve HTMLParser documentation. Ezio Melotti <ezio.melotti@gmail.com> parents: 73274 diff changeset	355 Start tag: a
569566cbfd13 #14020: improve HTMLParser documentation. Ezio Melotti <ezio.melotti@gmail.com> parents: 73274 diff changeset	356 attr: ('class', 'link')
569566cbfd13 #14020: improve HTMLParser documentation. Ezio Melotti <ezio.melotti@gmail.com> parents: 73274 diff changeset	357 attr: ('href', '#main')
569566cbfd13 #14020: improve HTMLParser documentation. Ezio Melotti <ezio.melotti@gmail.com> parents: 73274 diff changeset	358 Data : tag soup
569566cbfd13 #14020: improve HTMLParser documentation. Ezio Melotti <ezio.melotti@gmail.com> parents: 73274 diff changeset	359 End tag : p
569566cbfd13 #14020: improve HTMLParser documentation. Ezio Melotti <ezio.melotti@gmail.com> parents: 73274 diff changeset	360 End tag : a
47151 cdb75af2385a Merged revisions 63438 via svnmerge from Georg Brandl <georg@python.org> parents: diff changeset	361
66623 1cbfeffea19f #1486713: Add a tolerant mode to HTMLParser. R. David Murray <rdmurray@bitdance.com> parents: 63674 diff changeset	362 .. rubric:: Footnotes
1cbfeffea19f #1486713: Add a tolerant mode to HTMLParser. R. David Murray <rdmurray@bitdance.com> parents: 63674 diff changeset	363
66624 6e49af2e0891 Add missing versionchanged, correct 'throw' wording to 'raise'. R. David Murray <rdmurray@bitdance.com> parents: 66623 diff changeset	364 .. [#] 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	365 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	366 is tolerated even in strict mode.

Mercurial > cpython-lru_cache-weakref

annotate Doc/library/html.parser.rst @ 87690:66c1c9f32567 default tip