Home | History | Annotate | Download | only in library 
      1 :mod:`mhlib` --- Access to MH mailboxes
      2 =======================================
      3 
      4 .. module:: mhlib
      5    :synopsis: Manipulate MH mailboxes from Python.
      6    :deprecated:
      7 
      8 .. deprecated:: 2.6
      9     The :mod:`mhlib` module has been removed in Python 3. Use the
     10     :mod:`mailbox` instead.
     11 
     12 .. sectionauthor:: Skip Montanaro <skip (a] pobox.com>
     13 
     14 The :mod:`mhlib` module provides a Python interface to MH folders and their
     15 contents.
     16 
     17 The module contains three basic classes, :class:`MH`, which represents a
     18 particular collection of folders, :class:`Folder`, which represents a single
     19 folder, and :class:`Message`, which represents a single message.
     20 
     21 
     22 .. class:: MH([path[, profile]])
     23 
     24    :class:`MH` represents a collection of MH folders.
     25 
     26 
     27 .. class:: Folder(mh, name)
     28 
     29    The :class:`Folder` class represents a single folder and its messages.
     30 
     31 
     32 .. class:: Message(folder, number[, name])
     33 
     34    :class:`Message` objects represent individual messages in a folder.  The Message
     35    class is derived from :class:`mimetools.Message`.
     36 
     37 
     38 .. _mh-objects:
     39 
     40 MH Objects
     41 ----------
     42 
     43 :class:`MH` instances have the following methods:
     44 
     45 
     46 .. method:: MH.error(format[, ...])
     47 
     48    Print an error message -- can be overridden.
     49 
     50 
     51 .. method:: MH.getprofile(key)
     52 
     53    Return a profile entry (``None`` if not set).
     54 
     55 
     56 .. method:: MH.getpath()
     57 
     58    Return the mailbox pathname.
     59 
     60 
     61 .. method:: MH.getcontext()
     62 
     63    Return the current folder name.
     64 
     65 
     66 .. method:: MH.setcontext(name)
     67 
     68    Set the current folder name.
     69 
     70 
     71 .. method:: MH.listfolders()
     72 
     73    Return a list of top-level folders.
     74 
     75 
     76 .. method:: MH.listallfolders()
     77 
     78    Return a list of all folders.
     79 
     80 
     81 .. method:: MH.listsubfolders(name)
     82 
     83    Return a list of direct subfolders of the given folder.
     84 
     85 
     86 .. method:: MH.listallsubfolders(name)
     87 
     88    Return a list of all subfolders of the given folder.
     89 
     90 
     91 .. method:: MH.makefolder(name)
     92 
     93    Create a new folder.
     94 
     95 
     96 .. method:: MH.deletefolder(name)
     97 
     98    Delete a folder -- must have no subfolders.
     99 
    100 
    101 .. method:: MH.openfolder(name)
    102 
    103    Return a new open folder object.
    104 
    105 
    106 .. _mh-folder-objects:
    107 
    108 Folder Objects
    109 --------------
    110 
    111 :class:`Folder` instances represent open folders and have the following methods:
    112 
    113 
    114 .. method:: Folder.error(format[, ...])
    115 
    116    Print an error message -- can be overridden.
    117 
    118 
    119 .. method:: Folder.getfullname()
    120 
    121    Return the folder's full pathname.
    122 
    123 
    124 .. method:: Folder.getsequencesfilename()
    125 
    126    Return the full pathname of the folder's sequences file.
    127 
    128 
    129 .. method:: Folder.getmessagefilename(n)
    130 
    131    Return the full pathname of message *n* of the folder.
    132 
    133 
    134 .. method:: Folder.listmessages()
    135 
    136    Return a list of messages in the folder (as numbers).
    137 
    138 
    139 .. method:: Folder.getcurrent()
    140 
    141    Return the current message number.
    142 
    143 
    144 .. method:: Folder.setcurrent(n)
    145 
    146    Set the current message number to *n*.
    147 
    148 
    149 .. method:: Folder.parsesequence(seq)
    150 
    151    Parse msgs syntax into list of messages.
    152 
    153 
    154 .. method:: Folder.getlast()
    155 
    156    Get last message, or ``0`` if no messages are in the folder.
    157 
    158 
    159 .. method:: Folder.setlast(n)
    160 
    161    Set last message (internal use only).
    162 
    163 
    164 .. method:: Folder.getsequences()
    165 
    166    Return dictionary of sequences in folder.  The sequence names are used  as keys,
    167    and the values are the lists of message numbers in the sequences.
    168 
    169 
    170 .. method:: Folder.putsequences(dict)
    171 
    172    Return dictionary of sequences in folder name: list.
    173 
    174 
    175 .. method:: Folder.removemessages(list)
    176 
    177    Remove messages in list from folder.
    178 
    179 
    180 .. method:: Folder.refilemessages(list, tofolder)
    181 
    182    Move messages in list to other folder.
    183 
    184 
    185 .. method:: Folder.movemessage(n, tofolder, ton)
    186 
    187    Move one message to a given destination in another folder.
    188 
    189 
    190 .. method:: Folder.copymessage(n, tofolder, ton)
    191 
    192    Copy one message to a given destination in another folder.
    193 
    194 
    195 .. _mh-message-objects:
    196 
    197 Message Objects
    198 ---------------
    199 
    200 The :class:`Message` class adds one method to those of
    201 :class:`mimetools.Message`:
    202 
    203 
    204 .. method:: Message.openmessage(n)
    205 
    206    Return a new open message object (costs a file descriptor).
    207 
    208