# `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.