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

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

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

Можно указать encoding и errors; эти значения передаются функции open() или обработчику openhook.

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

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

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

Изменено в версии 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")

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.