"html.parser" --- Simple HTML and XHTML parser
**********************************************

**Code source :** Lib/html/parser.py

======================================================================

Ce module définit une classe "HTMLParser" qui sert de base pour
l'analyse syntaxique de fichiers texte formatés HTML (*HyperText Mark-
up Language*, le  « langage de balisage hypertexte ») et XHTML
(*EXtensible HyperText Markup Language*, le « langage extensible de
balisage hypertexte »).

class html.parser.HTMLParser(*, convert_charrefs=True)

   Crée une instance d'analyseur capable de traiter tout balisage,
   même invalide.

   Si *convert_charrefs* est "True" (valeur par défaut), toute
   référence de caractère (sauf ceux enchâssés dans des éléments
   "script"/"style") est automatiquement convertie en son caractère
   Unicode.

   Une instance de "HTMLParser" est alimentée par des données HTML.
   Elle fait appel à des méthodes offrant un traitement spécifique
   quand est rencontré un élément de balisage : balise ouvrante ou
   fermante, textes, commentaires… Pour implémenter le comportement
   désiré, l'utilisateur crée une sous-classe de "HTMLParser" en
   surchargeant ses méthodes.

   Cet analyseur ne vérifie ni que les balises fermantes correspondent
   aux balises ouvrantes, ni n'invoque le gestionnaire de balises
   fermantes pour les éléments implicitement fermés par un élément
   extérieur.

   Modifié dans la version 3.4: L'argument *convert_charrefs* a été
   ajouté.

   Modifié dans la version 3.5: La valeur par défaut de l'argument
   *convert_charrefs* est désormais "True".


Exemple d'application de l'analyseur HTML
=========================================

Comme exemple simple, un analyseur HTML minimal qui utilise la classe
"HTMLParser" pour afficher les balises ouvrantes, les balises
fermantes ainsi que les données quand elles apparaissent :

   from html.parser import HTMLParser

   class MyHTMLParser(HTMLParser):
       def handle_starttag(self, tag, attrs):
           print("Encountered a start tag:", tag)

       def handle_endtag(self, tag):
           print("Encountered an end tag :", tag)

       def handle_data(self, data):
           print("Encountered some data  :", data)

   parser = MyHTMLParser()
   parser.feed('<html><head><title>Test</title></head>'
               '<body><h1>Parse me!</h1></body></html>')

La sortie est alors :

   Encountered a start tag: html
   Encountered a start tag: head
   Encountered a start tag: title
   Encountered some data  : Test
   Encountered an end tag : title
   Encountered an end tag : head
   Encountered a start tag: body
   Encountered a start tag: h1
   Encountered some data  : Parse me!
   Encountered an end tag : h1
   Encountered an end tag : body
   Encountered an end tag : html


Méthodes de la classe "HTMLParser"
==================================

Les instances de "HTMLParser" disposent des méthodes suivantes :

HTMLParser.feed(data)

   Alimente l'analyseur avec du texte. Ce texte est traité dans la
   mesure où il constitue des éléments complets ; les données
   incomplètes sont mises dans un tampon jusqu'à ce que d'autres
   données soient fournies ou que la méthode "close()" soit appelée.
   L'argument *data* doit être de classe "str".

HTMLParser.close()

   Force le traitement de toutes les données du tampon comme si elles
   étaient suivies par un caractère *fin de fichier*. Cette méthode
   peut-être redéfinie par une classe dérivée pour ajouter des
   traitements supplémentaires à la fin de l'entrée, mais la version
   redéfinie devra impérativement appeler la méthode "close()" de la
   classe de base "HTMLParser".

HTMLParser.reset()

   Réinitialise l'instance. Toutes les données non traitées sont
   perdues. Cette méthode est appelée implicitement lors de
   l'instanciation.

HTMLParser.getpos()

   Renvoie le numéro de ligne et le numéro du caractère dans la ligne
   où le curseur est positionné.

HTMLParser.get_starttag_text()

   Return the text of the most recently opened start tag.  This should
   not normally be needed for structured processing, but may be useful
   in dealing with HTML "as deployed" or for re-generating input with
   minimal changes (whitespace between attributes can be preserved,
   etc.).

Les méthodes suivantes sont appelées lors de la rencontre de données
ou d'éléments de balisage ; elles sont destinées à être surchargées
par la sous-classe. L'implémentation de la classe de base ne fait rien
(sauf pour ce qui est de "handle_startendtag()") :

HTMLParser.handle_starttag(tag, attrs)

   Cette méthode est appelée pour traiter une balise ouvrante (p.  ex.
   "<div id="main">").

   L'argument *tag* contient le nom de la balise en minuscules.
   L'argument *attrs* contient une liste de *n-uplets* "(name, value)"
   regroupant les attributs présents entre les symboles "<" et ">" de
   la balise. Le paramètre *name* est converti en minuscule ; les
   guillemets sont supprimés du paramètre *value* et toute entité de
   référence ou de caractère est remplacée.

   Par exemple, pour la balise "<A HREF="https://www.cwi.nl/">", cette
   méthode est appelée par "handle_starttag('a', [('href',
   'https://www.cwi.nl/')])".

   Toute référence d'entité présente dans "html.entities" est
   remplacée dans la valeur des attributs.

HTMLParser.handle_endtag(tag)

   Cette méthode est appelée pour traiter les balises fermantes (p.
   ex. "</div>").

   L'argument *tag* est le nom de la balise en minuscules.

HTMLParser.handle_startendtag(tag, attrs)

   Traitée de façon similaire à "handle_starttag()", mais appelée
   quand l'analyseur rencontre une balise vide de type *XHTML* (p.
   ex. "<img ... />"). Cette méthode peut-être surchargée par les
   sous-classes demandant cette information lexicale ;
   l'implémentation par défaut appelle simplement "handle_starttag()"
   et "handle_endtag()".

HTMLParser.handle_data(data)

   Cette méthode est appelée pour traiter toute donnée arbitraire (p.
   ex. les nœuds textuels ou les contenus de "<script>...</script>" et
   "<style>...</style>").

HTMLParser.handle_entityref(name)

   Cette méthode est appelée pour traiter les références nommées de
   caractères de la forme "&name;" (p.  ex. "&gt;"), où *name* est une
   référence à une entité générique (p.  ex. "'gt'"). Cette méthode
   n'est jamais appelée si *convert_charrefs* vaut "True".

HTMLParser.handle_charref(name)

   This method is called to process decimal and hexadecimal numeric
   character references of the form "&#*NNN*;" and "&#x*NNN*;".  For
   example, the decimal equivalent for "&gt;" is "&#62;", whereas the
   hexadecimal is "&#x3E;"; in this case the method will receive
   "'62'" or "'x3E'".  This method is never called if
   *convert_charrefs* is "True".

HTMLParser.handle_comment(data)

   Cette méthode est appelée quand un commentaire (p.  ex. "<!--
   commentaire-->") est rencontré.

   Par exemple, le commentaire "<!-- commentaire -->" provoque l'appel
   de cette méthode avec l'argument "' commentaire '".

   Le contenu des commentaires conditionnels d'Internet Explorer
   (*condcoms*) ne sont pas traités de manière particulière par
   l'analyseur.  Ils sont passés à cette méthode comme tous les autres
   commentaires. Ainsi, pour "<!--[if IE 9]>Contenu spécifique à
   IE9<![endif]-->", cette méthode sera appelée avec "'[if IE
   9]>Contenu spécifique à IE9<![endif]'".

HTMLParser.handle_decl(decl)

   Cette méthode est appelée pour traiter la déclaration *doctype* de
   HTML (p.  ex. "<!DOCTYPE html>").

   Le paramètre *decl* contient la totalité de la déclaration contenue
   dans le balisage "<!...>" (p.  ex. "'DOCTYPE html'").

HTMLParser.handle_pi(data)

   Méthode appelée quand une instruction de traitement est rencontrée.
   Le paramètre *data* contient la totalité de l'instruction de
   traitement. Par exemple, pour l'instruction de traitement "<?proc
   color='rouge'>", cette méthode est appelée par "handle_pi("proc
   color='rouge'")". Elle est destinée à être surchargée dans une
   classe dérivée ; la classe de base ne réalise aucun traitement.

   Note:

     La classe "HTMLParser" utilise les règles syntaxiques de **SGML**
     pour traiter les instructions de traitement. Une instruction de
     traitement *XHTML* utilisant une terminaison en "'?'" se traduit
     par l'inclusion de ce "'?'" dans *data*.

HTMLParser.unknown_decl(data)

   Cette méthode est appelée quand une déclaration non reconnue est
   lue par l'analyseur.

   Le paramètre *data* contient toute la déclaration enchâssée dans le
   balisage "<![...]>". Il est parfois utile de le surcharger dans une
   classe dérivée. L'implémentation de la classe de base ne réalise
   aucune opération.


Exemples
========

La classe suivante implémente un analyseur qui est utilisé dans les
exemples ci-dessous :

   from html.parser import HTMLParser
   from html.entities import name2codepoint

   class MyHTMLParser(HTMLParser):
       def handle_starttag(self, tag, attrs):
           print("Start tag:", tag)
           for attr in attrs:
               print("     attr:", attr)

       def handle_endtag(self, tag):
           print("End tag  :", tag)

       def handle_data(self, data):
           print("Data     :", data)

       def handle_comment(self, data):
           print("Comment  :", data)

       def handle_entityref(self, name):
           c = chr(name2codepoint[name])
           print("Named ent:", c)

       def handle_charref(self, name):
           if name.startswith('x'):
               c = chr(int(name[1:], 16))
           else:
               c = chr(int(name))
           print("Num ent  :", c)

       def handle_decl(self, data):
           print("Decl     :", data)

   parser = MyHTMLParser()

Traitement du *doctype* :

   >>> parser.feed('<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" '
   ...             '"http://www.w3.org/TR/html4/strict.dtd">')
   Decl     : DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd"

Analyse d'un élément avec un titre et des attributs :

   >>> parser.feed('<img src="python-logo.png" alt="The Python logo">')
   Start tag: img
        attr: ('src', 'python-logo.png')
        attr: ('alt', 'The Python logo')
   >>>
   >>> parser.feed('<h1>Python</h1>')
   Start tag: h1
   Data     : Python
   End tag  : h1

Le contenu des éléments "script" et "style" est renvoyé tel quel (sans
autre traitement) :

   >>> parser.feed('<style type="text/css">#python { color: green }</style>')
   Start tag: style
        attr: ('type', 'text/css')
   Data     : #python { color: green }
   End tag  : style

   >>> parser.feed('<script type="text/javascript">'
   ...             'alert("<strong>hello!</strong>");</script>')
   Start tag: script
        attr: ('type', 'text/javascript')
   Data     : alert("<strong>hello!</strong>");
   End tag  : script

Traitement des commentaires :

   >>> parser.feed('<!-- a comment -->'
   ...             '<!--[if IE 9]>IE-specific content<![endif]-->')
   Comment  :  a comment
   Comment  : [if IE 9]>IE-specific content<![endif]

L'analyse des caractères nommés et des références numériques de
caractères et leur conversion en leur caractère correct (note : ces
trois références sont équivalentes à "'>'") :

   >>> parser.feed('&gt;&#62;&#x3E;')
   Named ent: >
   Num ent  : >
   Num ent  : >

Il est possible de fournir des portions de code incomplètes à
"feed()", mais alors il est possible que "handle_data()" soit appelée
plusieurs fois, à moins que *convert_charrefs* soit "True" :

   >>> for chunk in ['<sp', 'an>buff', 'ered ', 'text</s', 'pan>']:
   ...     parser.feed(chunk)
   ...
   Start tag: span
   Data     : buff
   Data     : ered
   Data     : text
   End tag  : span

L'analyse de code *HTML* non valide (p. ex. des attributs sans
guillemets) fonctionne également :

   >>> parser.feed('<p><a class=link href=#main>tag soup</p ></a>')
   Start tag: p
   Start tag: a
        attr: ('class', 'link')
        attr: ('href', '#main')
   Data     : tag soup
   End tag  : p
   End tag  : a
