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.