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.

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

С помощью mode вы можете указать, какой режим файла будет передан в open(). Он должен быть одним из 'r', 'rU', 'U' и '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.4: Режимы 'rU' и 'U'.

Устарело начиная с версии 3.8: Поддержка метода __getitem__() устарела.

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

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

Дополнительная фильтрация на месте: если аргумент ключевого слова 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 для сжатых файлов и открыты для обычных файлов.

Пример использования: 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.