=================================
 Connexion à une base de données
=================================

Référez vous à l'introduction de la documentation du module ``sqlite3``,
dans la bibliothèque standard de Python :

https://docs.python.org/fr/3.6/library/sqlite3.html

Bonne pratique pour la méthode ``close``
++++++++++++++++++++++++++++++++++++++++

.. note::

    Ce qui suit est valable pour de nombreux types d'objets ayant une méthode
    ``close`` ou équivalente, pas uniquement pour les connexions à une base de données.

Il est important de fermer la connexion quoi qu'il arrive,
*y compris* si une exception est levée.
C'est pourquoi il faut normalement appeler la méthode ``close``
dans la clause ``finally` d'un bloc ``try`` ::

    conn = sqlite3.connect('example.db')
    try:
        c = conn.cursor()
        c.execute("INSERT INTO stocks VALUES ('2006-01-05','BUY','RHAT',100,35.14)")
        conn.commit()
    finally:
        conn.close()

Une autre manière consiste à utiliser la clause ``with`` de python,
et la fonction ``contextlib.closing`` qui garantira l'appel à ``close`` ::

    from contextlib import closing

    with closing(sqlite3.connect('example.db')) as conn:
        c = conn.cursor()
        c.execute("INSERT INTO stocks VALUES ('2006-01-05','BUY','RHAT',100,35.14)")
        conn.commit()


.. note::

    De plus en plus d'objets en Python supportent nativement la clause ``with`` ;
    dans ce cas, il n'est pas nécessaire d'encapsuler l'appel avec ``closing(...)``.
    C'est notamment le cas de l'objet retourné par ``sqlite3.connect``.

    On pourrait donc écrire encore plus simplement ::

        with sqlite3.connect('example.db') as conn:
            c = conn.cursor()
            c.execute("INSERT INTO stocks VALUES ('2006-01-05','BUY','RHAT',100,35.14)")
            conn.commit()

    Cependant, la :pep:`249` n'impose pas ce support de la clause ``with``,
    donc si on souhaite garantir la compatibilité avec d'autres types de bases de données,
    il est préférable de garder l'appel explicite à ``closing(...)``.