1 """A readline()-style interface to the parts of a multipart message.

     2 

     3 The MultiFile class makes each part of a multipart message "feel" like

     4 an ordinary file, as long as you use fp.readline().  Allows recursive

     5 use, for nested multipart messages.  Probably best used together

     6 with module mimetools.

     7 

     8 Suggested use:

     9 

    10 real_fp = open(...)

    11 fp = MultiFile(real_fp)

    12 

    13 "read some lines from fp"

    14 fp.push(separator)

    15 while 1:

    16         "read lines from fp until it returns an empty string" (A)

    17         if not fp.next(): break

    18 fp.pop()

    19 "read remaining lines from fp until it returns an empty string"

    20 

    21 The latter sequence may be used recursively at (A).

    22 It is also allowed to use multiple push()...pop() sequences.

    23 

    24 If seekable is given as 0, the class code will not do the bookkeeping

    25 it normally attempts in order to make seeks relative to the beginning of the

    26 current file part.  This may be useful when using MultiFile with a non-

    27 seekable stream object.

    28 """

    29 from warnings import warn

    30 warn("the multifile module has been deprecated since Python 2.5",

    31         DeprecationWarning, stacklevel=2)

    32 del warn

    33 

    34 __all__ = ["MultiFile","Error"]

    35 

    36 class Error(Exception):

    37     pass

    38 

    39 class MultiFile:

    40 

    41     seekable = 0

    42 

    43     def __init__(self, fp, seekable=1):

    44         self.fp = fp

    45         self.stack = []

    46         self.level = 0

    47         self.last = 0

    48         if seekable:

    49             self.seekable = 1

    50             self.start = self.fp.tell()

    51             self.posstack = []

    52 

    53     def tell(self):

    54         if self.level > 0:

    55             return self.lastpos

    56         return self.fp.tell() - self.start

    57 

    58     def seek(self, pos, whence=0):

    59         here = self.tell()

    60         if whence:

    61             if whence == 1:

    62                 pos = pos + here

    63             elif whence == 2:

    64                 if self.level > 0:

    65                     pos = pos + self.lastpos

    66                 else:

    67                     raise Error, "can't use whence=2 yet"

    68         if not 0 <= pos <= here or \

    69                         self.level > 0 and pos > self.lastpos:

    70             raise Error, 'bad MultiFile.seek() call'

    71         self.fp.seek(pos + self.start)

    72         self.level = 0

    73         self.last = 0

    74 

    75     def readline(self):

    76         if self.level > 0:

    77             return ''

    78         line = self.fp.readline()

    79         # Real EOF?

    80         if not line:

    81             self.level = len(self.stack)

    82             self.last = (self.level > 0)

    83             if self.last:

    84                 raise Error, 'sudden EOF in MultiFile.readline()'

    85             return ''

    86         assert self.level == 0

    87         # Fast check to see if this is just data

    88         if self.is_data(line):

    89             return line

    90         else:

    91             # Ignore trailing whitespace on marker lines

    92             marker = line.rstrip()

    93         # No?  OK, try to match a boundary.

    94         # Return the line (unstripped) if we don't.

    95         for i, sep in enumerate(reversed(self.stack)):

    96             if marker == self.section_divider(sep):

    97                 self.last = 0

    98                 break

    99             elif marker == self.end_marker(sep):

   100                 self.last = 1

   101                 break

   102         else:

   103             return line

   104         # We only get here if we see a section divider or EOM line

   105         if self.seekable:

   106             self.lastpos = self.tell() - len(line)

   107         self.level = i+1

   108         if self.level > 1:

   109             raise Error,'Missing endmarker in MultiFile.readline()'

   110         return ''

   111 

   112     def readlines(self):

   113         list = []

   114         while 1:

   115             line = self.readline()

   116             if not line: break

   117             list.append(line)

   118         return list

   119 

   120     def read(self): # Note: no size argument -- read until EOF only!

   121         return ''.join(self.readlines())

   122 

   123     def next(self):

   124         while self.readline(): pass

   125         if self.level > 1 or self.last:

   126             return 0

   127         self.level = 0

   128         self.last = 0

   129         if self.seekable:

   130             self.start = self.fp.tell()

   131         return 1

   132 

   133     def push(self, sep):

   134         if self.level > 0:

   135             raise Error, 'bad MultiFile.push() call'

   136         self.stack.append(sep)

   137         if self.seekable:

   138             self.posstack.append(self.start)

   139             self.start = self.fp.tell()

   140 

   141     def pop(self):

   142         if self.stack == []:

   143             raise Error, 'bad MultiFile.pop() call'

   144         if self.level <= 1:

   145             self.last = 0

   146         else:

   147             abslastpos = self.lastpos + self.start

   148         self.level = max(0, self.level - 1)

   149         self.stack.pop()

   150         if self.seekable:

   151             self.start = self.posstack.pop()

   152             if self.level > 0:

   153                 self.lastpos = abslastpos - self.start

   154 

   155     def is_data(self, line):

   156         return line[:2] != '--'

   157 

   158     def section_divider(self, str):

   159         return "--" + str

   160 

   161     def end_marker(self, str):

   162         return "--" + str + "--"