fileinput – итерация по строкам из нескольких входных потоков¶fileinput – Iterate over lines from multiple input streams

Исходный код: Lib/fileinput.py

Этот модуль реализует вспомогательный класс и функции для быстрого создания цикла по стандартному вводу или списку файлов. Если нужно только прочитать или записать один файл, см. open().

Типичное использование:

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

Функция перебирает строки всех файлов, указанных в sys.argv[1:]; если список пуст, по умолчанию используется sys.stdin. Если имя файла равно '-', оно также заменяется на sys.stdin, а необязательные аргументы mode и openhook игнорируются. Чтобы задать альтернативный список имён файлов, передайте его первым аргументом в input(). Допускается также одно имя файла.

Все файлы по умолчанию открываются в текстовом режиме, но это можно изменить, указав параметр mode в вызове input() или FileInput. Если при открытии или чтении файла происходит ошибка ввода-вывода, возбуждается OSError.

Если sys.stdin используется более одного раза, второй и последующие вызовы не вернут ни одной строки, за исключением, возможно, интерактивного использования или если он был явно сброшен (например, с помощью sys.stdin.seek(0)).

Пустые файлы открываются и сразу закрываются; их присутствие в списке имён файлов становится заметным, только когда последний открытый файл пуст.

Строки возвращаются с сохранением всех символов новой строки; это означает, что последняя строка в файле может не иметь такого символа.

Можно управлять открытием файлов, передав хук открытия через параметр openhook в fileinput.input() или FileInput(). Хук должен быть функцией, принимающей два аргумента: filename и mode, и возвращающей соответствующий образом открытый файлоподобный объект. Если указаны encoding и/или errors, они будут переданы хуку как дополнительные именованные аргументы. Этот модуль предоставляет hook_compressed() для поддержки сжатых файлов.

Следующая функция является основным интерфейсом этого модуля:

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

Создаёт экземпляр класса FileInput. Этот экземпляр будет использоваться как глобальное состояние для функций этого модуля, а также возвращается для использования во время итерации. Параметры этой функции будут переданы конструктору класса FileInput.

Экземпляр FileInput можно использовать как контекстный менеджер в операторе with. В этом примере input закрывается после выхода из оператора with, даже если возникло исключение:

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

Изменено в версии 3.2: Может использоваться как контекстный менеджер.

Изменено в версии 3.8: Именованные параметры mode и openhook теперь являются только ключевыми (keyword-only).

Изменено в версии 3.10: Добавлены именованные параметры encoding и errors.

Следующие функции используют глобальное состояние, созданное fileinput.input(); если активное состояние отсутствует, возбуждается RuntimeError.

fileinput.filename()¶

Возвращает имя файла, который в данный момент читается. До чтения первой строки возвращает None.

fileinput.fileno()¶

Возвращает целочисленный «файловый дескриптор» текущего файла. Когда файл не открыт (до первой строки и между файлами), возвращает -1.

fileinput.lineno()¶

Возвращает накопленный номер строки для только что прочитанной строки. До чтения первой строки возвращает 0. После чтения последней строки последнего файла возвращает номер этой строки.

fileinput.filelineno()¶

Возвращает номер строки в текущем файле. До чтения первой строки возвращает 0. После чтения последней строки последнего файла возвращает номер этой строки внутри файла.

fileinput.isfirstline()¶

Возвращает True, если только что прочитанная строка является первой строкой своего файла, иначе возвращает False.

fileinput.isstdin()¶

Возвращает True, если последняя строка была прочитана из sys.stdin, иначе возвращает False.

fileinput.nextfile()¶

Закрывает текущий файл, чтобы следующая итерация начала чтение с первой строки следующего файла (если такой есть); строки, не прочитанные из файла, не учитываются в общем количестве строк. Имя файла не изменяется до тех пор, пока не будет прочитана первая строка следующего файла. До чтения первой строки эта функция не действует; её нельзя использовать для пропуска первого файла. После чтения последней строки последнего файла эта функция также не действует.

fileinput.close()¶

Закрывает последовательность.

Класс, реализующий поведение последовательности, предоставляемое модулем, также доступен для создания подклассов:

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

Класс FileInput является реализацией; его методы filename(), fileno(), lineno(), filelineno(), isfirstline(), isstdin(), nextfile() и close() соответствуют функциям с теми же именами в модуле. Кроме того, он является итерируемым и имеет метод readline(), который возвращает следующую входную строку. К последовательности следует обращаться строго последовательно; произвольный доступ и readline() несовместимы.

С помощью mode можно указать, какой режим файла будет передан в open(). Он должен быть одним из 'r' и 'rb'.

Параметр openhook, если задан, должен быть функцией, принимающей два аргумента: filename и mode, и возвращающей соответствующим образом открытый файлоподобный объект. inplace и openhook нельзя использовать вместе.

Можно указать encoding и errors, которые передаются в open() или openhook.

Экземпляр FileInput можно использовать как контекстный менеджер в операторе with. В этом примере input закрывается после выхода из оператора with, даже если возникло исключение:

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

Изменено в версии 3.2: Может использоваться как контекстный менеджер.

Изменено в версии 3.8: Именованные параметры mode и openhook теперь передаются только как именованные (keyword-only).

Изменено в версии 3.10: Добавлены именованные параметры encoding и errors.

Изменено в версии 3.11: Режимы 'rU' и 'U', а также метод __getitem__() были удалены.

Необязательная фильтрация на месте: если именованный аргумент inplace=True передан в fileinput.input() или в конструктор FileInput, файл перемещается в резервную копию, а стандартный вывод направляется во входной файл (если файл с тем же именем, что и резервная копия, уже существует, он будет молча заменён). Это позволяет написать фильтр, который перезаписывает свой входной файл на месте. Если задан параметр backup (обычно как backup='.<some extension>'), он указывает расширение для резервного файла, и резервный файл остаётся; по умолчанию расширение равно '.bak' и оно удаляется при закрытии выходного файла. Фильтрация на месте отключается, когда читается стандартный ввод.

Следующие два хука открытия предоставляются этим модулем:

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

Прозрачно открывает файлы, сжатые gzip и bzip2 (распознаваемые по расширениям '.gz' и '.bz2'), с использованием модулей gzip и bz2. Если расширение имени файла не '.gz' и не '.bz2', файл открывается обычным образом (то есть с помощью open() без какого-либо распаковывания).

Значения encoding и errors передаются в io.TextIOWrapper для сжатых файлов и в open для обычных файлов.

Пример использования: fi = fileinput.FileInput(openhook=fileinput.hook_compressed, encoding="utf-8")

Изменено в версии 3.10: Добавлены именованные параметры encoding и errors.

fileinput.hook_encoded(encoding, errors=None)¶

Возвращает хук, который открывает каждый файл с помощью open(), используя заданные encoding и errors для чтения файла.

Пример использования: fi = fileinput.FileInput(openhook=fileinput.hook_encoded("utf-8", "surrogateescape"))

Изменено в версии 3.6: Добавлен необязательный параметр errors.

Устарело с версии 3.10: Эта функция устарела, поскольку fileinput.input() и FileInput теперь имеют параметры encoding и errors.