Doc/library/multifile.rst

   1
   2 :mod:`multifile` --- Support for files containing distinct parts
   3 ================================================================
   4
   5 .. module:: multifile
   6    :synopsis: Support for reading files which contain distinct parts, such as some MIME data.
   7    :deprecated:
   8 .. sectionauthor:: Eric S. Raymond <esr@snark.thyrsus.com>
   9
  10
  11 .. deprecated:: 2.5
  12    The :mod:`email` package should be used in preference to the :mod:`multifile`
  13    module. This module is present only to maintain backward compatibility.
  14
  15 The :class:`MultiFile` object enables you to treat sections of a text file as
  16 file-like input objects, with ``''`` being returned by :meth:`readline` when a
  17 given delimiter pattern is encountered.  The defaults of this class are designed
  18 to make it useful for parsing MIME multipart messages, but by subclassing it and
  19 overriding methods  it can be easily adapted for more general use.
  20
  21
  22 .. class:: MultiFile(fp[, seekable])
  23
  24    Create a multi-file.  You must instantiate this class with an input object
  25    argument for the :class:`MultiFile` instance to get lines from, such as a file
  26    object returned by :func:`open`.
  27
  28    :class:`MultiFile` only ever looks at the input object's :meth:`readline`,
  29    :meth:`seek` and :meth:`tell` methods, and the latter two are only needed if you
  30    want random access to the individual MIME parts. To use :class:`MultiFile` on a
  31    non-seekable stream object, set the optional *seekable* argument to false; this
  32    will prevent using the input object's :meth:`seek` and :meth:`tell` methods.
  33
  34 It will be useful to know that in :class:`MultiFile`'s view of the world, text
  35 is composed of three kinds of lines: data, section-dividers, and end-markers.
  36 MultiFile is designed to support parsing of messages that may have multiple
  37 nested message parts, each with its own pattern for section-divider and
  38 end-marker lines.
  39
  40
  41 .. seealso::
  42
  43    Module :mod:`email`
  44       Comprehensive email handling package; supersedes the :mod:`multifile` module.
  45
  46
  47 .. _multifile-objects:
  48
  49 MultiFile Objects
  50 -----------------
  51
  52 A :class:`MultiFile` instance has the following methods:
  53
  54
  55 .. method:: MultiFile.readline(str)
  56
  57    Read a line.  If the line is data (not a section-divider or end-marker or real
  58    EOF) return it.  If the line matches the most-recently-stacked boundary, return
  59    ``''`` and set ``self.last`` to 1 or 0 according as the match is or is not an
  60    end-marker.  If the line matches any other stacked boundary, raise an error.  On
  61    encountering end-of-file on the underlying stream object, the method raises
  62    :exc:`Error` unless all boundaries have been popped.
  63
  64
  65 .. method:: MultiFile.readlines(str)
  66
  67    Return all lines remaining in this part as a list of strings.
  68
  69
  70 .. method:: MultiFile.read()
  71
  72    Read all lines, up to the next section.  Return them as a single (multiline)
  73    string.  Note that this doesn't take a size argument!
  74
  75
  76 .. method:: MultiFile.seek(pos[, whence])
  77
  78    Seek.  Seek indices are relative to the start of the current section. The *pos*
  79    and *whence* arguments are interpreted as for a file seek.
  80
  81
  82 .. method:: MultiFile.tell()
  83
  84    Return the file position relative to the start of the current section.
  85
  86
  87 .. method:: MultiFile.next()
  88
  89    Skip lines to the next section (that is, read lines until a section-divider or
  90    end-marker has been consumed).  Return true if there is such a section, false if
  91    an end-marker is seen.  Re-enable the most-recently-pushed boundary.
  92
  93
  94 .. method:: MultiFile.is_data(str)
  95
  96    Return true if *str* is data and false if it might be a section boundary.  As
  97    written, it tests for a prefix other than ``'-``\ ``-'`` at start of line (which
  98    all MIME boundaries have) but it is declared so it can be overridden in derived
  99    classes.
 100
 101    Note that this test is used intended as a fast guard for the real boundary
 102    tests; if it always returns false it will merely slow processing, not cause it
 103    to fail.
 104
 105
 106 .. method:: MultiFile.push(str)
 107
 108    Push a boundary string.  When a decorated version of this boundary  is found as
 109    an input line, it will be interpreted as a section-divider  or end-marker
 110    (depending on the decoration, see :rfc:`2045`).  All subsequent reads will
 111    return the empty string to indicate end-of-file, until a call to :meth:`pop`
 112    removes the boundary a or :meth:`.next` call reenables it.
 113
 114    It is possible to push more than one boundary.  Encountering the
 115    most-recently-pushed boundary will return EOF; encountering any other
 116    boundary will raise an error.
 117
 118
 119 .. method:: MultiFile.pop()
 120
 121    Pop a section boundary.  This boundary will no longer be interpreted as EOF.
 122
 123
 124 .. method:: MultiFile.section_divider(str)
 125
 126    Turn a boundary into a section-divider line.  By default, this method
 127    prepends ``'--'`` (which MIME section boundaries have) but it is declared so
 128    it can be overridden in derived classes.  This method need not append LF or
 129    CR-LF, as comparison with the result ignores trailing whitespace.
 130
 131
 132 .. method:: MultiFile.end_marker(str)
 133
 134    Turn a boundary string into an end-marker line.  By default, this method
 135    prepends ``'--'`` and appends ``'--'`` (like a MIME-multipart end-of-message
 136    marker) but it is declared so it can be overridden in derived classes.  This
 137    method need not append LF or CR-LF, as comparison with the result ignores
 138    trailing whitespace.
 139
 140 Finally, :class:`MultiFile` instances have two public instance variables:
 141
 142
 143 .. attribute:: MultiFile.level
 144
 145    Nesting depth of the current part.
 146
 147
 148 .. attribute:: MultiFile.last
 149
 150    True if the last end-of-file was for an end-of-message marker.
 151
 152
 153 .. _multifile-example:
 154
 155 :class:`MultiFile` Example
 156 --------------------------
 157
 158 .. sectionauthor:: Skip Montanaro <skip@pobox.com>
 159
 160
 161 ::
 162
 163    import mimetools
 164    import multifile
 165    import StringIO
 166
 167    def extract_mime_part_matching(stream, mimetype):
 168        """Return the first element in a multipart MIME message on stream
 169        matching mimetype."""
 170
 171        msg = mimetools.Message(stream)
 172        msgtype = msg.gettype()
 173        params = msg.getplist()
 174
 175        data = StringIO.StringIO()
 176        if msgtype[:10] == "multipart/":
 177
 178            file = multifile.MultiFile(stream)
 179            file.push(msg.getparam("boundary"))
 180            while file.next():
 181                submsg = mimetools.Message(file)
 182                try:
 183                    data = StringIO.StringIO()
 184                    mimetools.decode(file, data, submsg.getencoding())
 185                except ValueError:
 186                    continue
 187                if submsg.gettype() == mimetype:
 188                    break
 189            file.pop()
 190        return data.getvalue()
 191