| :meth:`seek` and :meth:`tell` methods, and the latter two are only needed if you |
| want random access to the individual MIME parts. To use :class:`MultiFile` on a |
| non-seekable stream object, set the optional *seekable* argument to false; this |
| will prevent using the input object's :meth:`seek` and :meth:`tell` methods. |
| |
| It will be useful to know that in :class:`MultiFile`'s view of the world, text |
| is composed of three kinds of lines: data, section-dividers, and end-markers. |
| MultiFile is designed to support parsing of messages that may have multiple |
n | nested message parts, each with its own pattern for section-divider and end- |
n | nested message parts, each with its own pattern for section-divider and |
| marker lines. |
| end-marker lines. |
| |
| |
| .. seealso:: |
| |
| Module :mod:`email` |
| Comprehensive email handling package; supersedes the :mod:`multifile` module. |
| |
| |
| .. _multifile-objects: |
| |
| MultiFile Objects |
| ----------------- |
| |
| A :class:`MultiFile` instance has the following methods: |
| |
| |
n | .. method:: XXX Class.readline(str) |
n | .. method:: MultiFile.readline(str) |
| |
| Read a line. If the line is data (not a section-divider or end-marker or real |
| EOF) return it. If the line matches the most-recently-stacked boundary, return |
| ``''`` and set ``self.last`` to 1 or 0 according as the match is or is not an |
| end-marker. If the line matches any other stacked boundary, raise an error. On |
| encountering end-of-file on the underlying stream object, the method raises |
| :exc:`Error` unless all boundaries have been popped. |
| |
| |
n | .. method:: XXX Class.readlines(str) |
n | .. method:: MultiFile.readlines(str) |
| |
| Return all lines remaining in this part as a list of strings. |
| |
| |
n | .. method:: XXX Class.read() |
n | .. method:: MultiFile.read() |
| |
| Read all lines, up to the next section. Return them as a single (multiline) |
| string. Note that this doesn't take a size argument! |
| |
| |
n | .. method:: XXX Class.seek(pos[, whence]) |
n | .. method:: MultiFile.seek(pos[, whence]) |
| |
| Seek. Seek indices are relative to the start of the current section. The *pos* |
| and *whence* arguments are interpreted as for a file seek. |
| |
| |
n | .. method:: XXX Class.tell() |
n | .. method:: MultiFile.tell() |
| |
| Return the file position relative to the start of the current section. |
| |
| |
n | .. method:: XXX Class.next() |
n | .. method:: MultiFile.next() |
| |
| Skip lines to the next section (that is, read lines until a section-divider or |
| end-marker has been consumed). Return true if there is such a section, false if |
| an end-marker is seen. Re-enable the most-recently-pushed boundary. |
| |
| |
n | .. method:: XXX Class.is_data(str) |
n | .. method:: MultiFile.is_data(str) |
| |
| Return true if *str* is data and false if it might be a section boundary. As |
| written, it tests for a prefix other than ``'-``\ ``-'`` at start of line (which |
| all MIME boundaries have) but it is declared so it can be overridden in derived |
| classes. |
| |
| Note that this test is used intended as a fast guard for the real boundary |
| tests; if it always returns false it will merely slow processing, not cause it |
| to fail. |
| |
| |
n | .. method:: XXX Class.push(str) |
n | .. method:: MultiFile.push(str) |
| |
| Push a boundary string. When a decorated version of this boundary is found as |
| an input line, it will be interpreted as a section-divider or end-marker |
| (depending on the decoration, see :rfc:`2045`). All subsequent reads will |
| return the empty string to indicate end-of-file, until a call to :meth:`pop` |
| removes the boundary a or :meth:`next` call reenables it. |
| |
n | It is possible to push more than one boundary. Encountering the most-recently- |
n | It is possible to push more than one boundary. Encountering the |
| pushed boundary will return EOF; encountering any other boundary will raise an |
| most-recently-pushed boundary will return EOF; encountering any other |
| error. |
| boundary will raise an error. |
| |
| |
n | .. method:: XXX Class.pop() |
n | .. method:: MultiFile.pop() |
| |
| Pop a section boundary. This boundary will no longer be interpreted as EOF. |
| |
| |
n | .. method:: XXX Class.section_divider(str) |
n | .. method:: MultiFile.section_divider(str) |
| |
n | Turn a boundary into a section-divider line. By default, this method prepends |
n | Turn a boundary into a section-divider line. By default, this method |
| ``'-``\ ``-'`` (which MIME section boundaries have) but it is declared so it can |
| prepends ``'--'`` (which MIME section boundaries have) but it is declared so |
| be overridden in derived classes. This method need not append LF or CR-LF, as |
| it can be overridden in derived classes. This method need not append LF or |
| comparison with the result ignores trailing whitespace. |
| CR-LF, as comparison with the result ignores trailing whitespace. |
| |
| |
n | .. method:: XXX Class.end_marker(str) |
n | .. method:: MultiFile.end_marker(str) |
| |
| Turn a boundary string into an end-marker line. By default, this method |
n | prepends ``'-``\ ``-'`` and appends ``'-``\ ``-'`` (like a MIME-multipart end- |
n | prepends ``'--'`` and appends ``'--'`` (like a MIME-multipart end-of-message |
| of-message marker) but it is declared so it can be overridden in derived |
| marker) but it is declared so it can be overridden in derived classes. This |
| classes. This method need not append LF or CR-LF, as comparison with the result |
| method need not append LF or CR-LF, as comparison with the result ignores |
| ignores trailing whitespace. |
| trailing whitespace. |
| |
| Finally, :class:`MultiFile` instances have two public instance variables: |
| |
| |
n | .. attribute:: XXX Class.level |
n | .. attribute:: MultiFile.level |
| |
| Nesting depth of the current part. |
| |
| |
n | .. attribute:: XXX Class.last |
n | .. attribute:: MultiFile.last |
| |
| True if the last end-of-file was for an end-of-message marker. |
| |
| |
| .. _multifile-example: |
| |
| :class:`MultiFile` Example |
| -------------------------- |
| |
t | .. sectionauthor:: Skip Montanaro <skip@mojam.com> |
t | .. sectionauthor:: Skip Montanaro <skip@pobox.com> |
| |
| |
| :: |
| |
| import mimetools |
| import multifile |
| import StringIO |
| |