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 если последняя строка была прочитана из 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 теперь являются только ключевыми.

Изменено в версии 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 для сжатых файлов и открыты для обычных файлов.

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