==================================
 Le package python Beautiful Soup
==================================

Le package `requests`_ permet de consulter et de manipuler la structure arborescente d'un document HTML.

Installation
============

.. highlight: bash

Depuis votre `environnement virtuel <a1_venv>`:doc:,
exécutez la commande suivante ::

    pip install beautifulsoup4


.. highlight: python

Si tout s'est bien passé, vous pouvez désormais importer le package dans l'interprétaur python ::

    >>> import bs4
    >>> bs4.__version__
    '4.7.1'
    
(le numéro de version peut évidemment être différent).

Premiers pas
============

La classe ``bs4.BeautifulSoup`` permet de créer un objet Python représentant un document HTML.
Une manière de créer un tel objet est de passer simplement le code HTML (une chaîne de caractères ou d'octets) ::

    >>> import bs4
    >>> doc = bs4.BeautifulSoup("""
    ...    <ul>
    ...     <li>Premier élément</li>
    ...     <li>Deuxième <em>élément</em></li>
    ...     <li><a href="toto">Un lien</a></li>
    ...   </ul>
    ...   <p>Un autre <a href="tata">lien</a>.</p>
    ... """)

Inspecter le document
~~~~~~~~~~~~~~~~~~~~~

Cet objet possède une méthode ``select`` qui prend en paramètre un sélecteur CSS,
et retourne la liste des éléments HTML vérifiant ce sélecteur ::

    >>> doc.select('li')
    [<li>Premier élément</li>, <li>Deuxième <em>élément</em></li>, <li><a href="toto">Un lien</a></li>]
    >>> doc.select('a')
    [<a href="toto">Un lien</a>, <a href="tata">lien</a>]
    >>> doc.select('p *')
    [<a href="tata">lien</a>]

On peut également accéder au *premier* élément d'un type donné,
en utilisant le nom de balise comme attribut de l'objet document ::

    >>> doc.li
    <li>Premier élément</li>
    >>> doc.a
    <a href="toto">Un lien</a>
    >>> doc.p
    <p>Un autre <a href="tata">lien</a>.</p>

Attributs d'un élément
~~~~~~~~~~~~~~~~~~~~~~

Chaque élément récupéré par les méthodes ci-dessus possède les attributs suivants :

* ``name`` : le nom de la balise ;
* ``contents``: la liste des "enfants" de cet élément (peuvent être des chaînes de caractères ou d'autres éléments) ;
* ``string`` : le texte contenu dans cet élément (ou ``None`` si l'élément a plusieurs enfants) ;
* la notation ``[a]`` peut également être utilisée pour accéder aux attributs HTML de cet élément.

Exemples ::

    >>> doc.p.contents
    ['Un autre ', <a href="tata">lien</a>, '.']
    >>> doc.p.contents[1].name
    'a'
    >>> doc.p.contents[1]['href']
    'tata'
    >>> doc.p.contents[1].string
    'lien'

Homogénéité
~~~~~~~~~~~

L'objet document et les objets éléments
sont en fait homogènes entre eux.
Ils possèdent les mêmes attributs et méthodes.

On peut notamment utiliser la méthode ``select`` sur un élément,
ou un attribut ayant le nom d'une balise,
pour rechercher à l'intérieur de cet élément ::

    >>> doc.ul.select('a')
    [<a href="toto">Un lien</a>]
    >>> doc.ul.li
    <li>Premier élément</li>

Les chaînes de caractère retournées par ``string`` ou ``contents``
sont également partielement homogènes à des éléments.
Elles possèdent notamment un attribut ``name`` (qui vaut toujours ``None``)
et un attribut ``string`` (qui retourne la chaîne elle-même).
En revanche, elle n'ont pas d'attribut ``contents``.
Cette homogénéité facilite toutefois le traitement systématique des valeurs retournées par l'attribut ``contents`` d'un élément ::

    >>> def full_text(e):
    ...     if e.string:
    ...         return e.string
    ...     else:
    ...         return "".join(full_text(i) for i in e.contents)
    ... 
    >>> full_text(doc)
    '\nPremier élément\nDeuxième élément\nUn lien\n\nUn autre lien.\n'


Pour aller plus loin
====================

Consultez la `documentation`_ pour en savoir plus.

.. _requests: https://2.python-requests.org/en/master/

.. _documentation: https://www.crummy.com/software/BeautifulSoup/bs4/doc/