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 для сжатых файлов и в 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.