# `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 `&#xNNN;`. 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