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.