"fileinput" --- Iterate over lines from multiple input streams
**************************************************************

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

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

Ce module offre une classe auxiliaire et des fonctions pour lire
facilement l'entrée standard ou bien les fichiers d'une liste. Si vous
n'avez besoin de lire ou écrire qu'un seul fichier, il suffit de
"open()".

Ce module s'utilise le plus couramment comme ceci :

   import fileinput
   for line in fileinput.input(encoding="utf-8"):
       process(line)

Ce code traite une à une les lignes des fichiers de "sys.argv[1:]". Si
cette liste est vide (pas d'argument en ligne de commande), il lit
l'entrée standard. Le nom de fichier "'-'" est équivalent à l'entrée
standard (les arguments facultatifs *mode* et *openhook* sont ignorés
dans ce cas). On peut aussi passer la liste des fichiers comme
argument à "input()", voire un nom de fichier unique.

Par défaut, tous les fichiers sont ouverts en mode texte. On peut
changer ce comportement à l'aide du paramètre *mode* de la fonction
"input()" ou du constructeur de "FileInput". Si une erreur d'entrée-
sortie se produit durant l'ouverture ou la lecture d'un fichier,
l'exception "OSError" est levée.

Modifié dans la version 3.3: "IOError" était levée auparavant, elle
est devenue un alias de "OSError".

Si "sys.stdin" apparaît plus d'une fois dans la liste, toutes les
lignes sont consommées dès la première fois, sauf éventuellement en
cas d'usage interactif ou si le flux d'entrée standard a été modifié
dans l'intervalle (par exemple avec "sys.stdin.seek(0)").

Les fichiers vides sont ouverts et refermés immédiatement. Ils ne sont
pas détectables dans la liste des fichiers, sauf éventuellement dans
le cas où le dernier fichier est vide.

Les caractères de saut de ligne sont préservés, donc toutes les lignes
se terminent par un saut de ligne, sauf éventuellement la dernière
ligne d'un fichier.

You can control how files are opened by providing an opening hook via
the *openhook* parameter to "fileinput.input()" or "FileInput()". The
hook must be a function that takes two arguments, *filename* and
*mode*, and returns an accordingly opened file-like object. If
*encoding* and/or *errors* are specified, they will be passed to the
hook as additional keyword arguments. This module provides a
"hook_compressed()" to support compressed files.

La fonction suivante constitue l'interface principale du module :

fileinput.input(files=None, inplace=False, backup='', *, mode='r', openhook=None, encoding=None, errors=None)

   Crée une instance de "FileInput", qui devient l'état global pour
   toutes les fonctions du module. Elle est également renvoyée afin
   que l'utilisateur puisse la parcourir comme un objet itérable. Tous
   les paramètres de cette fonction sont transmis au constructeur de
   "FileInput".

   Les instances de "FileInput" peuvent s'utiliser comme gestionnaires
   de contexte, avec l'instruction "with". Dans le code suivant,
   *input* est fermé lorsque le bloc "with" se termine, y compris si
   une exception l'a interrompu :

      with fileinput.input(files=('spam.txt', 'eggs.txt'), encoding="utf-8") as f:
          for line in f:
              process(line)

   Modifié dans la version 3.2: prise en charge du protocole de
   gestionnaire de contexte.

   Modifié dans la version 3.8: les paramètres *mode* et *openhook*
   doivent être nommés.

   Modifié dans la version 3.10: The keyword-only parameter *encoding*
   and *errors* are added.

Toutes les fonctions suivantes font appel à l'état global du module
mis en place par "fileinput.input()". L'absence de cet état déclenche
l'exception "RuntimeError".

fileinput.filename()

   Renvoie le nom du fichier en train d'être lu, ou "None" avant la
   lecture de la toute première ligne.

fileinput.fileno()

   Renvoie le descripteur de fichier (sous forme d'entier) utilisé
   pour lire le fichier courant. Si aucun fichier n'est ouvert (avant
   la première ligne et entre les fichiers), le résultat est "-1".

fileinput.lineno()

   Renvoie le numéro de la ligne qui vient d'être lue, en commençant
   par la première ligne du premier fichier. Avant cette toute
   première ligne, renvoie "0". Après la dernière ligne du dernier
   fichier, renvoie le numéro de cette ligne.

fileinput.filelineno()

   Renvoie le numéro de ligne relatif au fichier courant. Avant la
   toute première ligne, renvoie "0". Après la toute dernière ligne,
   renvoie le numéro de cette ligne par rapport à son fichier source.

fileinput.isfirstline()

   Renvoie "True" ou "False" selon que la ligne qui vient d'être lue
   est la première du fichier.

fileinput.isstdin()

   "True" ou "False" selon que la dernière ligne lue provenait de
   "sys.stdin" ou non.

fileinput.nextfile()

   Ferme le fichier courant et laisse la lecture se poursuivre au
   début du suivant (ou se terminer si c'était le dernier fichier ;
   dans ce cas cette fonction ne fait rien). Les lignes court-
   circuitées ne comptent pas dans les numéros des lignes des fichiers
   suivants. Le nom du fichier courant n'est pas modifié
   immédiatement, mais seulement après que la première ligne du
   fichier suivant a été lue. Cette fonction n'a pas d'effet avant la
   lecture de la première ligne (elle ne peut pas sauter le premier
   fichier).

fileinput.close()

   Ferme le fichier courant et termine la lecture en sautant les
   fichiers suivants.

La classe qui implémente ce comportement du module est publique. On
peut en créer des classes filles :

class fileinput.FileInput(files=None, inplace=False, backup='', *, mode='r', openhook=None, encoding=None, errors=None)

   Class "FileInput" is the implementation; its methods "filename()",
   "fileno()", "lineno()", "filelineno()", "isfirstline()",
   "isstdin()", "nextfile()" and "close()" correspond to the functions
   of the same name in the module. In addition it is *iterable* and
   has a "readline()" method which returns the next input line. The
   sequence must be accessed in strictly sequential order; random
   access and "readline()" cannot be mixed.

   With *mode* you can specify which file mode will be passed to
   "open()". It must be one of "'r'" and "'rb'".

   S'il est fourni, l'argument *openhook* est une fonction. Elle est
   appelée avec les paramètres *filename* et *mode*, et renvoie un
   objet fichier-compatible ouvert selon *mode*. Notez que *openhook*
   et *inplace* sont mutuellement exclusifs.

   You can specify *encoding* and *errors* that is passed to "open()"
   or *openhook*.

   Les objets "FileInput" peuvent aussi fonctionner comme
   gestionnaires de contexte dans un bloc "with". Dans l'exemple
   suivant, *input* est fermé à la fin du bloc "with", même arrêté par
   une exception :

      with FileInput(files=('spam.txt', 'eggs.txt')) as input:
          process(input)

   Modifié dans la version 3.2: prise en charge du protocole de
   gestionnaire de contexte.

   Modifié dans la version 3.8: les paramètres *mode* et *openhook*
   doivent impérativement être nommés.

   Modifié dans la version 3.10: The keyword-only parameter *encoding*
   and *errors* are added.

   Modifié dans la version 3.11: The "'rU'" and "'U'" modes and the
   "__getitem__()" method have been removed.

**Filtrage sur place optionnel :** si "inplace=True" est passé à
"fileinput.input()" ou au constructeur de "FileInput", chaque fichier
d'entrée est déplacé vers une sauvegarde et la sortie standard est
redirigée vers le fichier lui-même, ce qui permet d'écrire des filtres
qui modifient directement les fichiers existants. Si le paramètre
*backup* est fourni, il donne l'extension des fichiers de sauvegarde.
Dans ce cas, la sauvegarde est conservée après l'opération. Par
défaut, les fichiers de sauvegarde ont l'extension "'.bak'" et sont
supprimés dès que le fichier de sortie est fermé. Si un fichier existe
avec le même nom que la sauvegarde, il est écrasé. Le filtrage sur
place ne fait rien pour l'entrée standard.

Les deux fonctions suivantes fournissent des valeurs prédéfinies pour
*openhook* :

fileinput.hook_compressed(filename, mode, *, encoding=None, errors=None)

   Ouvre de façon transparente les fichiers compressés avec gzip ou
   bzip2, à l'aide des modules "gzip" et "bz2". Les fichiers
   compressés sont reconnus aux extensions "'.gz'" et "'.bz2'". Tous
   les fichiers qui n'ont pas l'une de ces deux extensions sont
   ouverts normalement (avec "open()", sans décompression).

   The *encoding* and *errors* values are passed to "io.TextIOWrapper"
   for compressed files and open for normal files.

   Usage example:  "fi =
   fileinput.FileInput(openhook=fileinput.hook_compressed,
   encoding="utf-8")"

   Modifié dans la version 3.10: The keyword-only parameter *encoding*
   and *errors* are added.

fileinput.hook_encoded(encoding, errors=None)

   Renvoie une fonction qui ouvre les fichiers en passant à "open()"
   les arguments *encoding* et *errors*. Le résultat peut être
   exploité à travers le point d'entrée automatique *openhook*.

   Exemple d'utilisation : "fi =
   fileinput.FileInput(openhook=fileinput.hook_encoded("utf-8",
   "surrogateescape"))".

   Modifié dans la version 3.6: ajout du paramètre facultatif
   *errors*.

   Obsolète depuis la version 3.10: This function is deprecated since
   "fileinput.input()" and "FileInput" now have *encoding* and
   *errors* parameters.
