fileinput — Итерация строк из нескольких входных потоков

Источник: 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.

Изменено в версии 3.3: Раньше поднимался IOError; теперь это псевдоним 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 теперь только для ключевых слов.

Изменено в версии 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() соответствуют одноименным функциям в модуле. Кроме того, она является iterable и имеет метод readline(), который возвращает следующую строку ввода. Доступ к последовательности должен осуществляться строго последовательно; случайный доступ и readline() нельзя смешивать.

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

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

Вы можете указать кодировку и ошибки, которые передаются в open() или openhook.

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

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

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

Изменено в версии 3.8: Параметр ключевого слова mode и openhook теперь только для ключевого слова.

Изменено в версии 3.10: Добавлены параметры encoding и errors, доступные только по ключевому слову.

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

Опциональная фильтрация на месте: если в fileinput.input() или в конструктор FileInput передан аргумент с ключевым словом inplace=True, файл перемещается в резервный файл, а стандартный вывод направляется на входной файл (если файл с тем же именем, что и резервный файл, уже существует, он будет заменен беззвучно). Это позволяет написать фильтр, который переписывает свой входной файл на месте. Если указан параметр 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(), используя заданные кодировку и ошибки для чтения файла.

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

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

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