"linecache" --- Random access to text lines
*******************************************

**Code source :** Lib/linecache.py

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

The "linecache" module allows one to get any line from a Python source
file, while attempting to optimize internally, using a cache, the
common case where many lines are read from a single file.  This is
used by the "traceback" module to retrieve source lines for inclusion
in  the formatted traceback.

Les fichiers sont ouverts par la fonction "tokenize.open()". Cette
fonction utilise "tokenize.detect_encoding()" pour obtenir l'encodage
du fichier. En l'absence d'un BOM et d'un cookie d'encodage, c'est
l'encodage UTF-8 qui sera utilisé.

The "linecache" module defines the following functions:

linecache.getline(filename, lineno, module_globals=None)

   Récupère la ligne *lineno* du fichier *filename*.  Cette fonction
   ne lèvera jamais d'exception, elle préfèrera renvoyer "''" en cas
   d'erreur (le caractère de retour à la ligne sera inclus pour les
   lignes existantes).

   If *filename* indicates a frozen module (starting with "'<frozen
   '"), the function will attempt to get the real file name from
   "module_globals['__file__']" if *module_globals* is not "None".

   Si le fichier *filename* n'existe pas, cette fonction vérifie
   d'abord la présence d'un chargeur "__loader__" dans
   *module_globals*, comme le prescrit la **PEP 302**. Si un chargeur
   est trouvé avec une méthode "get_source", c'est cette méthode qui
   détermine les lignes sources (si "get_source()" renvoie "None",
   cette valeur est remplacée par la chaîne vide "''"). Sinon, si le
   nom de fichier *filename* est relatif, il est recherché dans les
   dossiers du chemin de recherche des modules, "sys.path".

   Modifié dans la version 3.14: Support *filename* of frozen modules.

linecache.clearcache()

   Nettoie le cache. Utilisez cette fonction si vous n'avez plus
   besoin des lignes des fichiers précédemment lus via "getline()".

linecache.checkcache(filename=None)

   Vérifie la validité du cache. Utilisez cette fonction si les
   fichiers du cache pourraient avoir changé sur le disque, et que
   vous en voudriez une version à jour. Sans *filename*, toutes les
   entrées du cache seront vérifiées.

linecache.lazycache(filename, module_globals)

   Récupère suffisamment d'informations sur un module situé hors du
   système de fichiers pour récupérer ses lignes plus tard via
   "getline()", même si *module_globals* devient "None". Cela évite de
   lire le fichier avant d'avoir besoin d'une ligne, tout en évitant
   de conserver les globales du module indéfiniment.

   Ajouté dans la version 3.5.

Exemple :

   >>> import linecache
   >>> linecache.getline(linecache.__file__, 8)
   'import sys\n'
