multifile — Поддержка файлов, содержащих отдельные части

Объект MultiFile позволяет обрабатывать разделы текстового файла как объекты входного типа «файл», при этом значение '' возвращается методом readline() при обнаружении заданного разделителя. По умолчанию этот класс предназначен для разбора сообщений MIME multipart, но благодаря наследованию и переопределению методов его можно легко адаптировать для более широкого применения.

class multifile.MultiFile(fp[, seekable])

Создаёт объект многофайлового объекта. Для работы с объектом MultiFile необходимо создать экземпляр этого класса с объектом ввода, из которого будут считываться строки, например, объект файла, возвращаемый методом open().

Объект MultiFile использует только методы объекта ввода readline(), seek() и tell(), и последние два метода необходимы только для произвольного доступа к отдельным частям MIME. Чтобы использовать MultiFile с объектом потока без возможности позиционирования, установите необязательный аргумент seekable в значение false. Это предотвратит использование методов seek() и tell() объекта ввода.

Важно отметить, что в представлении MultiFile текст состоит из трёх типов строк: данных, разделителей разделов и маркеров конца. Класс MultiFile разработан для поддержки разбора сообщений, которые могут содержать несколько вложенных частей сообщения, каждая со своим шаблоном для строк разделителей разделов и маркеров конца.

1. Объекты MultiFile

Экземпляр MultiFile имеет следующие методы:

MultiFile.readline(str)

Считывает строку. Если строка является данными (не разделителем раздела, маркером конца или реальным концом файла), возвращает её. Если строка совпадает с последней добавленной границей, возвращает '' и устанавливает self.last в 1 или 0 в зависимости от того, является ли совпадение маркером конца или нет. Если строка совпадает с любой другой добавленной границей, генерируется ошибка. При достижении конца файла в базовом объекте потока, метод генерирует Error исключение, если все границы не были удалены.

MultiFile.readlines(str)

Возвращает список всех оставшихся строк в текущей части.

MultiFile.read()

Считывает все строки до следующего раздела. Возвращает их как одну (многострочную) строку. Обратите внимание, что этот метод не принимает аргумент размера!

MultiFile.seek(pos[, whence])

Позиционирует указатель. Индексы позиционирования относятся к началу текущего раздела. Аргументы pos и whence интерпретируются аналогично методу seek файла.

MultiFile.tell()

Возвращает позицию файла относительно начала текущего раздела.

MultiFile.next()

Переходит к следующему разделу (т. е. считывает строки, пока не будет встречен разделитель раздела или маркер конца). Возвращает true, если такой раздел существует, false, если встречается маркер конца. Восстанавливает последнюю добавленную границу.

MultiFile.is_data(str)

Возвращает true, если str является данными, и false, если это может быть граница раздела. В текущей реализации проверяется префикс, отличный от '--' в начале строки (что имеют все границы MIME), но метод объявлен таким образом, чтобы его можно было переопределить в производных классах.

Обратите внимание, что эта проверка предназначена как быстрый фильтр для реальных проверок границ; если она всегда возвращает false, это лишь замедлит обработку, но не приведёт к ошибке.

MultiFile.push(str)

Добавляет строку границы. При обнаружении декорированной версии этой границы в строке ввода, она интерпретируется как разделитель раздела или маркер конца (в зависимости от декорации, см. RFC 2045). Все последующие считывания вернут пустую строку для обозначения конца файла, пока вызов pop() не удалит границу или вызов next() её не активирует.

Можно добавить более одной границы. Встреча последней добавленной границы вернёт EOF; встреча любой другой границы вызовет ошибку.

MultiFile.pop()

Удаляет границу раздела. Эта граница больше не будет интерпретироваться как EOF.

MultiFile.section_divider(str)

Преобразует границу в строку разделителя раздела. По умолчанию этот метод добавляет '--' (которую имеют границы разделов MIME), но он объявлен таким образом, чтобы его можно было переопределить в производных классах. Этот метод не должен добавлять LF или CR-LF, так как сравнение результата игнорирует хвостовые пробелы.

MultiFile.end_marker(str)

Преобразует строку границы в строку маркера конца. По умолчанию этот метод добавляет '--' и '--' (как маркер конца сообщения MIME multipart), но он объявлен таким образом, чтобы его можно было переопределить в производных классах. Этот метод не должен добавлять LF или CR-LF, так как сравнение результата игнорирует хвостовые пробелы.

Наконец, экземпляры MultiFile имеют две публичные переменные экземпляра:

MultiFile.level

Глубина вложенности текущей части.

MultiFile.last

True, если последний конец файла был для маркера конца сообщения.

2. Пример MultiFile

import mimetools
import multifile
import StringIO

def extract_mime_part_matching(stream, mimetype):
    """Return the first element in a multipart MIME message on stream
    matching mimetype."""

    msg = mimetools.Message(stream)
    msgtype = msg.gettype()
    params = msg.getplist()

    data = StringIO.StringIO()
    if msgtype[:10] == "multipart/":

        file = multifile.MultiFile(stream)
        file.push(msg.getparam("boundary"))
        while file.next():
            submsg = mimetools.Message(file)
            try:
                data = StringIO.StringIO()
                mimetools.decode(file, data, submsg.getencoding())
            except ValueError:
                continue
            if submsg.gettype() == mimetype:
                break
        file.pop()
    return data.getvalue()