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.