Finishing the PyMailGUI Client: User Help Tools

In this conclusion to a six-part series, you will learn about the user help tools that come with the PyMailGUI client, and more. This article is excerpted from chapter 15 of the book Programming Python, Third Edition, written by Mark Lutz (O’Reilly, 2006; ISBN: 0596009259) Copyright © 2006 O’Reilly Media, Inc. All rights reserved. Used with permission from the publisher. Available from booksellers or direct from O’Reilly Media.

messagecache: Message Cache Manager

The class in Example 15-5 implements a cache for already loaded messages. Its logic is split off into this file in order to avoid complicating list window implementations. The server list window creates and embeds an instance of this class to interface with the mail server, and to keep track of already loaded mail headers and full text.

Example 15-5. PP3EInternetEmailPyMailGuimessagecache.py

################################################################ # manage message and header loads and context, but not GUI
# a MailFetcher, with a list of already loaded headers and messages
# the caller must handle any required threading or GUI interfaces ###############################################################

from PP3E.Internet.Email import mailtools from popuputil import askPasswordWindow

class MessageInfo:
    """
    an item in the mail cache list
    """
    def __init__(self, hdrtext, size):
        self.hdrtext  = hdrtext           # fulltext is cached msg
        self.fullsize = size              # hdrtext is just the hdrs
        self.fulltext = None              # fulltext=hdrtext if no TOP

class MessageCache(mailtools.MailFetcher): 
    """
    keep track of already loaded headers and messages
    inherits server transfer methods from MailFetcher
    useful in other apps: no GUI or thread assumptions
    """
    def __init__(self):
       
mailtools.MailFetcher.__init__(self)
        self.msglist = []

    def loadHeaders(self, forceReloads, progress=None):
        """
        three cases to handle here: the initial full load,
        load newly arrived, and forced reload after delete;
        don’t refetch viewed msgs if hdrs list same or extended;
        retains cached msgs after a delete unless delete fails;
       
2.1: does quick check to see if msgnums still in sync
       
"""
        if forceReloads:
            loadfrom = 1
            self.msglist = []          # msg nums have changed
        else:
            loadfrom =
len(self.msglist)+1                    # continue from last load

        # only if loading newly arrived
        if loadfrom != 1:
            self.checkSynchError(self.allHdrs())                       # raises except if bad

        # get all or newly arrived msgs
       
reply = self.downloadAllHeaders(progress, loadfrom)
        headersList, msgSizes, loadedFull = reply

        for (hdrs, size) in zip(headersList, msgSizes):
            newmsg = MessageInfo(hdrs, size)
            if loadedFull:             # zip result may be empty
               
newmsg.fulltext =
hdrs                                    # got full msg if no ‘top’
            self.msglist.append(newmsg)

    def getMessage
(self, msgnum):                        # get raw msg text
       
if not self.msglist[msgnum-1].fulltext:                           # add to cache if fetched
            fulltext = self.downloadMessage(msgnum)                               # harmless if threaded
            self.msglist[msgnum-1].fulltext = fulltext
       
return self.msglist[msgnum-1].fulltext

    def getMessages(self, msgnums, progress=None):
        """
        prefetch full raw text of multiple messages, in thread;
       
2.1: does quick check to see if msgnums still in sync;
        we can’t get here unless the index list already loaded;
        """
        self.checkSynchError
(self.allHdrs())            # raises except if bad
       
nummsgs = len
msgnums)                    # adds messages to cache
        for (ix, msgnum)
in enumerate(msgnums):      # some poss already there
        if progress:
progress(ix+1, nummsgs)     # only connects if needed
        self.getMessage
(msgnum)                    # but may connect > once

    def getSize
(self, msgnum):             # encapsulate cache struct
        return self.msglist
[msgnum-1].fullsize         # it changed once already!

    def isLoaded(self, msgnum):
        return self.msglist[msgnum-1].fulltext

    def allHdrs(self):
        return [msg.hdrtext for msg in self.msglist]

    def deleteMessages(self, msgnums, progress=None):
        """
        if delete of all msgnums works, remove deleted entries
        from mail cache, but don’t reload either the headers list
        or already viewed mails text: cache list will reflect the
        changed msg nums on server; if delete fails for any reason,
        caller should forceably reload all hdrs next, because _some_
        server msg nums may have changed, in unpredictable ways;
        2.1: this now checks msg hdrs to detect out of synch msg
        numbers, if TOP supported by mail server; runs in thread
        """
        try:
           
self.deleteMessagesSafely(msgnums, self.allHdrs(), progress)
        except mailtools.TopNotSupported: 
        mailtools.MailFetcher.deleteMessages(self, msgnums, progress)

        # no errors: update index list 
        indexed = enumerate(self.msglist) 
        self.msglist = [msg for (ix, msg) in indexed if ix+1 not in msgnums]

class GuiMessageCache(MessageCache):
    """
    add any GUI-specific calls here so cache usable in non-GUI apps
    """

    def setPopPassword(self, appname):
        """
        get password from GUI here, in main thread
        forceably called from GUI to avoid pop ups in threads
        """
        if not self.popPassword:
           
prompt = ‘Password for %s on %s?’ % (self.popUser, self.popServer)
            self.popPassword = askPasswordWindow(appname, prompt)

    def askPopPassword(self):
        """
        but don’t use GUI pop up here: I am run in a thread!
       
when tried pop up in thread, caused GUI to hang;
        may be called by MailFetcher superclass, but only
        if passwd is still empty string due to dialog close
        """
        return self.popPassword

{mospagebreak title=popuputil: General-Purpose GUI Pop Ups}

Example 15-6 implements a handful of utility pop-up windows in a module, in case they ever prove useful in other programs. Note that the same windows utility module is imported here, to give a common look-and-feel to the popups (icons, titles, and so on).

Example 15-6. PP3EInternetEmailPyMailGuipopuputil.py

################################################################ # utility windows – may be useful in other programs ###############################################################

from Tkinter import *
from PP3E.Gui.Tools.windows import PopupWindow

class HelpPopup(PopupWindow):
    """
    custom Toplevel that shows help text as scrolled text
    source button runs a passed-in callback handler
    alternative: use HTML file and webbrowser module
    """
    myfont = ‘system’ # customizable

    def __init__(self, appname, helptext, iconfile=None, showsource=lambda:0) :  
        PopupWindow.__init__(self, appname, ‘Help’, iconfile)
       
from ScrolledText import ScrolledText                       # a nonmodal dialog
        bar = Frame(self)          # pack first=clip last
        bar.pack(side=BOTTOM, fill=X)
       
code = Button(bar, bg=’beige’, text="Source", command=showsource)
        quit = Button(bar, bg=’beige’, text="Cancel", command=self.destroy) 
        code.pack(pady=1, side=LEFT)
        quit.pack(pady=1, side=LEFT)
        text = ScrolledText(self)      # add
Text + scrollbar
        text.config(font=self.myfont, width=70)                              # too big for showinfo
        text.config(bg=’steelblue’, fg=’white’)                            # erase on btn or return
        text.insert(‘0.0′, helptext)
        text.pack(expand=YES, fill=BOTH)
        self.bind("<Return>", (lambda event: self.destroy()))

    def askPasswordWindow(appname, prompt):
        """
        modal dialog to input password string
        getpass.getpass uses stdin, not GUI
       
tkSimpleDialog.askstring echos input
        """
        win = PopupWindow(appname,
‘Prompt’)                            # a configured Toplevel
        Label(win, text=prompt).pack(side=LEFT)
        entvar = StringVar(win)
        ent = Entry(win, textvariable=entvar, show=’*’)       # display * for input
        ent.pack(side=RIGHT, expand=YES, fill=X)
        ent.bind(‘<Return>’, lambda event: win.destroy())
       
ent.focus_set(); win.grab_set(); win.wait_window()
        win.update()                # update forces redraw
        return entvar.get()         # ent widget is now gone

    class BusyBoxWait(PopupWindow):
        """
        pop up blocking wait message box: thread waits
        main GUI event thread stays alive during wait
        but GUI is inoperable during this wait state;
        uses quit redef here because lower, not leftmost;
        """
        def __init__(self, appname, message):
           
PopupWindow.__init__(self, appname, ‘Busy’)
            self.protocol(‘WM_DELETE_WINDOW’, lambda:0)      # ignore deletes
            label = Label(self,
text=message + ‘…’)               # win.quit() to erase
            label.config(height=10, width=40, cursor=’watch’)           # busy cursor
            label.pack()
            self.makeModal()
            self.message, self.label = message, label
       
def makeModal(self):
            self.focus_set()        # grab application
            self.grab_set()         # wait for threadexit
       
def changeText(self, newtext):
            self.label.config(text=self.message + ‘: ‘ + newtext)
        def quit(self):
            self.destroy()          # don’t verify quit

    class BusyBoxNowait(BusyBoxWait):
        """
        pop up nonblocking wait window
        call changeText to show progress, quit to close
        """
        def makeModal(self):
           
pass

    if __name__ == ‘__main__':
        HelpPopup(‘spam’, ‘See figure 1…n’)
        print askPasswordWindow(‘spam’, ‘enter password’)
        raw_input(‘Enter to exit’)

{mospagebreak title=wraplines: Line Split Tools}

The module in Example 15-7 implements general tools for wrapping long lines, at either a fixed column or the first delimiter at or before a fixed column. PyMailGUI uses this file’s wrapText1 function for text in view, reply, and forward windows, but this code is potentially useful in other programs. Run the file as a script to watch its self-test code at work, and study its functions to see its text-processing logic.

Example 15-7. PP3EInternetEmailPyMailGuiwraplines.py

################################################################ # split lines on fixed columns or at delimiters before a column
# see also: related but different textwrap standard library module (2.3+) ###############################################################

defaultsize = 80

def wrapLinesSimple(lineslist, size=defaultsize):
   
"split at fixed position size"
    wraplines = []
    for line in lineslist:
        while True:
        wraplines.append(line[:size])   # OK if len < size
        line = line[size:]              # split without analysis
        if not line: break
    return wraplines

def wrapLinesSmart(lineslist, size=defaultsize, delimiters=’.,:t ‘):
    "wrap at first delimiter left of size" 
    wraplines = []
    for line in lineslist:
       
while True:
           
if len(line) <= size:
                wraplines += [line]
                break
            else:
                for look in range(size-1, size/2, -1):
                   
if line[look] in delimiters:
                        front, line = line[:look+1], line[look+1:]
                        break
                
else:
                    front, line = line[:size], line[size:]
                wraplines += [front]
    return wraplines

################################################################ # common use case utilities ###############################################################

def wrapText1(text,
size=defaultsize):                 
# better for line-based txt: mail
    "when text read all at once"    # keeps original line brks struct
    lines = text.split(‘n’)        # split on newlines

lines = wrapLinesSmart(lines, size) # wrap lines on delimiters
return ‘n’.join(lines) # put back together
def wrapText2(text, size=defaultsize): # more uniform across lines
"same, but treat as one long line" # but loses original line struct
text = text.replace(‘n’, ‘ ‘) # drop newlines if any
lines = wrapLinesSmart([text], size) # wrap single line on delimiters
return lines # caller puts back together
def wrapText3(text, size=defaultsize):  
"same, but put back together"  
lines = wrapText2(text, size) # wrap as single long line
return ‘n’.join(lines) + ‘n’ # make one string with newlines
def wrapLines1(lines, size=defaultsize):  
"when newline included at end"  
lines = [line[:-1] for line in lines] # strip off newlines (or .rstrip)
lines = wrapLinesSmart(lines, size) # wrap on delimiters
return [(line + 'n') for line in lines] # put them back
def wrapLines2(lines, size=defaultsize): # more uniform across lines
"same, but concat as one long line" # but loses original structure
text = ”.join(lines) # put together as 1 line
lines = wrapText2(text) # wrap on delimiters
return [(line + 'n') for line in lines] # put newlines on ends

################################################################ a self-test ###############################################################

if __name__ == ‘__main__':
   
lines = ['spam ham ' * 20 + 'spam,ni' * 20,
             'spam ham ' * 20,
             'spam,ni'   * 20,
             'spam ham.ni' * 20,
             '',
             'spam'*80,
             ' ',
             'spam ham eggs']
   
print ‘all’, ‘-‘*30
    for line in lines: print repr(line) 
    print ‘simple’, ‘-‘*30
    for line in wrapLinesSimple(lines): print repr(line)
    print ‘smart’, ‘-‘*30
    for line in wrapLinesSmart(lines): print repr(line)

    print ‘single1′, ‘-‘*30
    for line in wrapLinesSimple([lines[0]], 60): print repr(line)
    print ‘single2′, ‘-‘*30
    for line in wrapLinesSmart([lines[0]], 60): print repr(line)
    print ‘combined text’, ‘-‘*30
    for line in wrapLines2(lines): print repr(line)
   
print ‘combined lines’, ‘-‘*30
    print wrapText1(‘n’.join(lines))

    assert ”.join(lines) == ”.join(wrapLinesSimple(lines, 60))
    assert ”.join(lines) == ”.join(wrapLinesSmart(lines, 60))
    print len(”.join(lines)),
    print len(”.join(wrapLinesSimple(lines))),
    print len(”.join(wrapLinesSmart(lines))),
    print len(”.join(wrapLinesSmart(lines, 60))),
    raw_input(‘Press enter’)

{mospagebreak title=mailconfig: User Configurations}

In Example 15-8, PyMailGUI’s mailconfig user settings module is listed. This program has its own version of this module because many of its settings are unique for PyMailGUI. To use the program for reading your own email, set its initial variables to reflect your POP and SMTP server names and login parameters. The variables in this module also allow the user to tailor the appearance and operation of the program without finding and editing actual program logic.

Example 15-8. PP3EInternetEmailPyMailGuimailconfig.py

################################################################ # PyMailGUI user configuration settings.
# Email scripts get their server names and other email config options from
# this module: change me to reflect your machine names, sig, and preferences.
# Warning: PyMailGUI won’t run without most variables here: make a backup copy!
# Notes: could get some settings from the command line too, and a configure
# dialog would be better, but this common module file suffices for now. #################################################################

#——————————————- # (required for load, delete) POP3 email server machine, user
#——————————————-

# popservername = ‘?Please set your mailconfig.py attributes?’

#popservername = ‘pop.rmi.net’ # or starship.python.net, ‘localhost’
#popusername = ‘lutz’ # password fetched or asked when run
#popservername = ‘pop.mindspring.com’ # yes, I have a few email accounts
#popusername = ‘lutz4′
#popservername = ‘pop.yahoo.com’  
#popusername = ‘for_personal_mail’  
popservername = ‘pop.earthlink.net’ # pp3e@earthlink.net
popusername = ‘pp3e’  

#——————————————-
# (required for send) SMTP email server machine name
# see Python smtpd module for a SMTP server class to run locally;
# note: your ISP may require that you be directly connected to their system:
# I can email through Earthlink on dial up, but cannot via Comcast cable
#——————————————-

smtpservername = ‘smtp.comcast.net’     # or ‘smtp.mindspring.com’, ‘localhost’

#——————————————-
# (may be required for send) SMTP user/password if authenticated
# set user to None or ” if no login/authentication is required
# set pswd to name of a file holding your SMTP password, or an
# empty string to force programs to ask (in a console, or GUI)
#——————————————-

smtpuser = None               # per your ISP smtppasswdfile = ”           # set to ” to be asked

#——————————————-
# (optional) PyMailGUI: name of local one-line text file with your POP
# password; if empty or file cannot be read, pswd is requested when first
# connecting; pswd not encrypted: leave this empty on shared machines;
# PyMailCGI always asks for pswd (runs on a possibly remote server);
#——————————————-

poppasswdfile =
r’c:temppymailgui.txt’        # set to ” to be asked

#——————————————-
# (optional) personal information used by PyMailGUI to fill in edit forms;
# if not set, does not fill in initial form values;
# sig  — can be a triple-quoted block, ignored if empty string;
# addr — used for initial value of "From" field if not empty,
# no longer tries to guess From for replies–varying success;
#——————————————-

myaddress   = ‘pp3e@earthlink.net’         #
lutz@rmi.net
mysignature = ‘–Mark Lutz (http://www.rmi.net/~lutz)’

#——————————————-
# (optional) local file where sent messages are saved;
# PyMailGUI ‘Open’ button allows this file to be opened and viewed
# don’t use ‘.’ form if may be run from another dir: e.g., pp3e demos
#——————————————-

#sentmailfile   =
r’.sentmail.txt’               # . means in current working dir

#sourcedir    = r’C:MarkPP3E-cdExamplesPP3EInternetEmailPyMailGui’ #sentmailfile = sourcedir + ‘sentmail.txt’

# determine auto from one of my source files import wraplines, os
mysourcedir = os.path.dirname(os.path.abspath(wraplines.__file__))

sentmailfile = os.path.join(mysourcedir, ‘sentmail.txt’)

#——————————————-
# (optional) local file where pymail saves POP mail;
# PyMailGUI instead asks for a name with a pop-up dialog
#——————————————-

savemailfile =
r’c:tempsavemail.txt’        # not used in PyMailGUI: dialog

#——————————————-
# (optional) customize headers displayed in PyMailGUI list and view windows;
# listheaders replaces default, viewheaders extends it; both must be tuple of
# strings, or None to use default hdrs;
#——————————————-

listheaders = (‘Subject’, ‘From’, ‘Date’, ‘To’, ‘X-Mailer’)
viewheaders = (‘Bcc’,)

#——————————————-
# (optional) PyMailGUI fonts and colors for text server/file message list
# windows, message content view windows, and view window attachment buttons;
# use (‘family’, size, ‘style’) for font; ‘colorname’ or hexstr ‘#RRGGBB’ for
# color (background, foreground); None means use defaults; font/color of
# view windows can also be set interactively with texteditor’s Tools menu;
#——————————————-

listbg = ‘indianred’         # None, ‘white’, ‘#RRGGBB’ (see setcolor example)

listfg = ‘black’
listfont = (‘courier’, 9, ‘bold’) # None, (‘courier’, 12, ‘bold italic’)
  # use fixed-width font for list columns
viewbg = ‘#dbbedc’  
viewfg = ‘black’  
viewfont = (‘courier’, 10, ‘bold’)  
viewheight = 24 # max lines for height when opened
partfg = None  
partbg = None  

# see Tk color names: aquamarine paleturqoise powderblue goldenrod burgundy ….

#listbg = listfg = listfont = None
#viewbg = viewfg = viewfont = viewheight = None                      # to use defaults
#partbg = partfg = None

#——————————————-
# (optional) column at which mail’s original text should be wrapped for view,
# reply, and forward; wraps at first delimiter to left of this position;
# composed text is not auto-wrapped: user or recipient’s mail tool must wrap
# new text if desired; to disable wrapping, set this to a high value (1024?);
#——————————————-

wrapsz = 100

#——————————————-
# (optional) control how PyMailGUI opens mail parts in the GUI;
# for view window Split actions and attachment quick-access buttons;
# if not okayToOpenParts, quick-access part buttons will not appear in
# the GUI, and Split saves parts in a directory but does not open them;
# verifyPartOpens used by both Split action and quick-access buttons:
# all known-type parts open automatically on Split if this set to False;
# verifyHTMLTextOpen used by web browser open of HTML main text part:
#——————————————-

okayToOpenParts = True # open any parts/attachments at all?
verifyPartOpens = False # ask permission before opening each part?
verifyHTMLTextOpen = False # if main text part is HTML, ask before open?

#——————————————-
# (optional) the maximum number of quick-access mail part buttons to show
# in the middle of view windows; after this many, a "…" button will be
# displayed, which runs the "Split" action to extract additional parts;
#——————————————-

maxPartButtons = 8           # how many part buttons in view windows

#end

{mospagebreak title=PyMailGuiHelp: User Help Text}

Finally, Example 15-9 lists the module that defines the text displayed in PyMailGUI’s help popup as one triple-quoted string. Read this here or live within the program to learn more about how PyMailGUI’s interface operates (click the help bar at the top of the server list window to open the help display). It is included because it explains some properties of PyMailGUI not introduced by the demo earlier in this chapter.

This text may be more usefully formatted as HTML with section links and popped up in a web browser, but we take a lowest-common–denominator approach here to minimize external dependencies—we don’t want help to fail if no browser can be located, and we don’t want to maintain both text and HTML versions. Other schemes are possible (e.g., converting HTML to text as a fallback by parsing), but they are left as suggested improvements.

Example 15-9.
PP3EInternetPyMailGui2PyMailGuiHelp.py

################################################################ # PyMailGUI help text string, in this separate module only to avoid
# distracting from executable code. As coded, we throw up this text
# in a simple scrollable text box; in the future, we might instead
# use an HTML file opened with a browser (use webbrowser module, or
# run a "netscape help.html" or DOS "start help.html" with os.system);
# that would add an external dependency, unless text on browser fail; ################################################################ # used to have to be narrow for Linux info box pop ups;
# now uses scrolledtext with buttons instead;

helptext = """PyMailGUI, version 2.1 January, 2006
Programming Python, 3rd Edition
O’Reilly Media, Inc.

PyMailGUI is a multiwindow interface for processing email, both online and offline. Its main interfaces include one list window for the mail server, zero or more list windows for mail save files, and multiple view windows for composing or viewing emails selected in a list window. On startup, the main (server) list window appears first, but no mail server connection is attempted
until a Load or message send request. All PyMailGUI windows may be resized, which is especially useful in list windows to see additional columns.

Major enhancements in this version:

* MIME multipart mails with attachments may
  be both viewed and composed.
* Mail transfers are no longer blocking, and
  may overlap in time.
* Mail may be saved and processed offline 
  from a local file.
* Message parts may now be opened 
  automatically within the GUI.
* Multiple messages may be selected for 
  processing in list windows.
* Initial downloads fetch mail headers only;
  full mails are fetched on request.
* View window headers and list window
  columns are configurable.
* Deletions are performed immediately, not
  delayed until program exit.
* Most server transfers report their
  progress in the GUI.
* Long lines are intelligently wrapped in
  viewed and quoted text.
* Fonts and colors in list and view windows
  may be configured by the user.
* Authenticating SMTP mail-send servers that
  require login are supported.
* Sent messages are saved in a local file,
  which may be opened in the GUI.
* View windows intelligently pick a main
  text part to be displayed.
* Already fetched mail headers and full
  mails are cached for speed.
* Date strings and addresses in composed
  mails are formatted properly.
* (2.1) View windows now have quick-access
  buttons for attachments/parts.
* (2.1) Inbox out-of-synch errors detected
  on deletes, and index and mail loads.
* (2.1) Save-file loads and deletes
  threaded, to avoid pauses for large files.

Note: To use PyMailGUI to read and write email of your own, you must change the POP and SMTP server names and login details in the file mailconfig.py, located in PyMailGUI’s source-code directory. See section 10 for details.

Contents:
1)  LIST WINDOW ACTIONS
2)  VIEW WINDOW ACTIONS
3)  OFFLINE PROCESSING
4)  VIEWING TEXT AND ATTACHMENTS
5)  SENDING TEXT AND ATTACHMENTS
6)  MAIL TRANSFER OVERLAP
7)  MAIL DELETION
8)  INBOX MESSAGE NUMBER SYNCHRONIZATION
9)  LOADING EMAIL
10) THE mailconfig CONFIGURATION MODULE
11) DEPENDENCIES
12) MISCELLANEOUS HINTS

 

1) LIST WINDOW ACTIONS

Click list window buttons to process email:

- Load:t fetch all (or new) mail headers
  from POP server inbox
- View:t display selected emails nicely
  formatted
- Delete:t delete selected emails from
  server or save file
- Write:t compose a new email message, send
  by SMTP
- Reply:t compose replies to selected
  emails, send by SMTP
- Fwd:t compose forwards of selected
  emails, send by SMTP
- Save:t write all selected emails to a
  chosen save file
- Open:t load emails from an offline save
  file into new list window
- Quit:t exit program (server list), close
  window (file list)

Double-click on an email in a list window’s listbox to view the mail’s raw text, including any mail headers not shown by the View button. List windows opened for mail save files support all of the above except Load. After the initial Load, Load only fetches newly arrived message headers. To forceably reload all mails from the server, restart PyMailGUI. There is reload button, because full reloads are only required on rare deletion and inbox synchronization errors (described ahead), and reloads are initiated automatically in these cases.

Click on emails in the main window’s listbox to select them. Click the "All" checkbox to select all or no emails at once. More than one email may be selected at the same time: View, Delete, Reply, Fwd, and Save buttons are applied to all currently selected emails, in both server and save-file list windows. Use Ctrl+click to select multiple mails, Shift+click to select all
from prior selecion, or click+move to drag the selection out.

In 2.1, most of the actions in the server List window automatically run a quick-check to detect inbox out-of-synch errors with the server. If a synch error pop up appears, a full index reload will be automatically run; there is no need to stop and restart PyMailGUI (see ahead in this help).

 

2) VIEW WINDOW ACTIONS

Action buttons in message view windows (View):

- Cancel:t closes the message view window
- Parts:t lists all message parts,
  including attachments
- Split:t extracts, saves, and possibly
  opens message parts

Actions in message compose windows (Write, Reply, Fwd):

- Cancel:t closes the message window,
  discarding its content
- Parts:t lists files already attached to
  mail being edited
- Attach:t adds a file as an attachment to
  a mail being edited
- Send:t sends the message to all its
  recipients

Parts and Split buttons appear in all View windows; for simple messages, the sole part is the message body. Message reply, forward, and delete requests are made in the list windows, not message view windows. Deletions do not erase open view windows.

New in 2.1: View windows also have up to a fixed maximum number of quick access buttons for attached message parts. They are alternatives to Split. After the maximum number, a ‘…’ button is added, which simply runs Split. The maximum number of part buttons to display per view window can be set in the mailconfig.py user settings module (described ahead).

 

3) OFFLINE PROCESSING

To process email offline: Load from the server, Save to a local file, and later select Open to open a save file’s list window in either the server List window or another save file’s List window. Open creates a new List window for the file, or raises its window if the file is already open.

A save file’s list window allows all main window actions listed above, except for Load. For example, saved messages can be viewed, deleted, replied to, or forwarded, from the file’s list window. Operations are mapped to the local mail save file, instead of the server’s inbox. Saved messages may also be
saved: to move mails from one save file to another, Save and then Delete from the source file’s window.

You do not need to connect to a server to process save files offline: click the Open button in the main list window. In a save-file list window, a Quit erases that window only; a Delete removes the message from the local save file, not from a server. Save-file list windows are automatically updated when new
mails are saved to the corresponding file anywhere in the GUI. The sent-mail file may also be opened and processed as a normal save-mail file, with Open.

Save buttons in list windows save the full message text (including its headers, and a message separator). To save just the main text part of a message, either use the Save button in the TextEditor at the bottom of a view or edit window, or select the "Split" action button. To save attachments, see the next section.

New in 2.1: local save-file Open and Delete requests are threaded to avoid blocking the GUI during loads and deletes of large files. Because of this, a loaded file’s index may not appear in its List window immediately. Similarly, when new mails are saved or messages are sent, there may be a delay before the corresponding local file’s List window is updated, if it is currently open.

As a status indication, the window’s title changes to "Loading…" on loads and "Deleting…" during deletes, and is reset to the file’s name after the thread exits (the server window uses pop ups for status indication, because the delay
is longer, and there is progress to display). Eventually, either the index will appear and its window raised, or an error message will pop up. Save-file loads and deletes are not allowed to overlap with each other for a given file, but may overlap with server transfers and operations on other open files.

Note: save-file Save operations are still not threaded, and may pause the GUI momentarily when saving very many large mails. This is normaly not noticeable, because unlike Open and Delete, saves simply append to the save-file, and do not reload its content. To avoid pauses completely, though, don’t save very many large mails in a single operation.

Also note: the current implementation loads the entire save-mail file into memory when opened. Because of this, save-mail files are limited in size, depending upon your computer. To avoid consuming too much memory, you should try to keep your save files relatively small (at the least, smaller than your computer’s available memory). As a rule of thumb, organize your saved mails by categories into many small files, instead of a few large files.

4) VIEWING TEXT AND ATTACHMENTS

PyMailGUI’s view windows use a text-oriented display. When a mail is viewed, its main text is displayed in the View window. This text is taken from the entire body of a simple message, or the first text part of a multipart MIME message. To extract the main message text, PyMailGUI looks for plain text, then HTML, and then text of any other kind. If no such text content is found, nothing is displayed in the view window, but parts may be opened manually with the "Split" button (and quick-access part buttons in 2.1, described below).

If the body of a simple message is HTML type, or a HTML part is used as the main message text, a web browser is popped up as an alternative display for the main message text, if verified by the user (the mailconfig module can be used to bypass the verification; see ahead). This is equivalent to opening
the HTML part with the "Split" button, but is initiated automatically for the main message text’s HTML. If a simple message is something other than text or HTML, its content must be openened manually with Split.

When viewing mails, messages with multipart attachments are prefixed with a "*" in list windows. "Parts" and "Split" buttons appear in all View windows. Message parts are defined as follows:

- For simple messages, the message body is
  considered to be the sole
  part of the message.
- For multipart messages, the message parts
  list includes the main message text, as
  well as all attachments.

In both cases, message parts may be saved and opened with the "Split" button.

For simple messages, the message body may be saved with Split, as well as the Save button in the view window’s text editor. To process multipart messages:

- Use "Parts" to display the names of all
  message parts, including any
  attachments, in a pop-up dialog.
- Use "Split" to view message parts: all
  mail parts are first saved to a
  selected directory, and any well-known 
  and generally safe part files are
  opened automatically, but only if verified
  by the user.

- See also the note below about 2.1 quick
  access buttons, for an alternative
  to the Parts/Split interface on View
  windows.

For "Split", select a local directory to save parts to. After the save, text parts open in the TextEditor GUI, HTML and multimedia types open in a web browser, and common Windows document types (e.g., .doc and .xls files) open via the Windows registry entry for the filename extension. For safety, unknown types and executable program parts are never run automatically; even Python
programs are displayed as source text only (save the code to run manually).

Web browsers on some platforms may open multimedia types (image, audio, video) in specific content handler programs (e.g., MediaPlayer, image viewers). No other types of attachments are ever opened, and attachments are never opened without user verification (or mailconfig.py authorization in 2.1, described
below). Browse the parts save directory to open other parts manually.

To avoid scrolling for very long lines (sometimes sent by HTML-based mailers), the main text part of a message is automatically wrapped for easy viewing. Long lines are split up at the first delimiter found before a fixed column, when viewed, replied, or forwarded. The wrapping column may be configured or disabled in the mailconfig module (see ahead). Text lines are never
automatically wrapped when sent; users or recipients should manage line length in composed mails.

New in 2.1: View windows also have up to a fixed maximum number of quick-access buttons for attached message parts. They are alternatives to Split: selecting an attachment’s button automatically extracts, saves, and opens that single attachment directly, without Split directory and pop-up dialogs (a temporary
directory is used). The maximum number of part buttons to display per view window can be set in the mailconfig.py user settings module (described ahead). For mails with more than the maximum number of attachments, a ‘…’ button is added which simply runs Split to save and open any additional attachments.

Also in 2.1, two settings in the mailconfig.py module (see section 10) can be used to control how PyMailGUI opens parts in the GUI:

- okayToOpenParts: controls whether part opens are allowed at all

- verifyPartOpens: controls whether to ask before each part is opened.

Both are used for View window Split actions and part quick-access buttons. If okayToOpenParts is False, quick-access part buttons will not appear in the GUI, and Split saves parts in a directory but does not open them. verifyPartOpens is used by both Split and quick-access part buttons: if False, part buttons open parts immediately, and Split opens all known-type parts automatically
after they are saved (unknown types and executables are never opened).

An additional setting in this module, verifyHTMLTextOpen, controls verification of opening a web browser on a HTML main text part of a message; if False, the web browser is opened without prompts. This is a separate setting from verifyPartOpens, because this is more automatic than part opens, and some HTML main text parts may have dubious content (e.g., images, ads).

 

5) SENDING TEXT AND ATTACHMENTS

When composing new mails, the view window’s "Attach" button adds selected files as attachments, to be sent with the email’s main text when the View window’s "Send" is clicked. Attachment files may be of any type; they are selected in a pop-up dialog, but are not loaded until Send. The view window’s "Parts" button displays attachments already added.

The main text of the message (in the view window editor) is sent as a simple message if there are no attachments, or as the first part of a multipart MIME message if there are. In both cases, the main message text is always sent as plain text. HTML files may be attached to the message, but there is no support for text-or-HTML multipart alternative format for the main text, nor for sending the main text as HTML only. Not all clients can handle HTML, and
PyMailGUI’s text-based view windows have no HTML editing tools.

Multipart nesting is never applied: composed mails are always either a simple body, or a linear list of parts containing the main message text and attachment files.

For mail replies and forwards, headers are given intial values, the main message text (described in the prior section) is wrapped and quoted with ‘>’ prefixes, and any attachments in the original message are stripped. Only new attachments added are sent with the message.

To send to multiple addresses, separate each recipient’s address in To and Cc fields with semicolons. For instance:
        
tim@oreily.com; |"Smith, Bob" <bob@bob.com>; john@nasa.gov
Note that because these fields are split on semicolons without full parsing, a recipient’s address should not embed a ‘;’. For replies, this is handled automatically: the To field is prefilled with the original message’s From, using either the original name and address, or just the address if the name contains a ‘;’ (a rare case). Cc and Bcc headers fields are ignored if they contain just the initial "?" when sent.

Successfully sent messages are saved in a local file whose name you list in the mailconfig.py module. Sent mails are saved if the variable "sentmailfile" is set to a valid filename; set to an empty string to disable saves. This file may be opened using the Open button of the GUI’s list windows, and its content may be viewed, processed, deleted, saved, and so on within the GUI, just like a manually saved mail file. Also like manually saved mail files, the sent-file list window is automatically updated whenever a new message is sent, if it is open (there is no need to close and reopen to see new sends). If this file grows too large to open, you can delete its content with Delete, after possibly saving sent mails you wish to keep to another file with Save.

Note that some ISPs may require that you be connected to their systems in order to use their SMTP servers (sending through your dial-up ISP’s server while connected to a broadband provider may not work–try the SMTP server at your broadband provider instead), and some SMTP servers may require authentication
(set the "smtpuser" variable in the mailconfig.py module to force authentication logins on sends). See also the Python library module smptd for SMTP server tools; in principle, you could run your own SMTP server locally on ‘localhost’.

 

6) MAIL TRANSFER OVERLAP

PyMailGUI runs mail server transfers (loads, sends, and deletes) in threads, to avoid blocking the GUI. Transfers never block the GUI’s windows, and windows do not generally block other windows. Users can view, create, and process mails while server transfers are in progress. The transfers run in the background, while the GUI remains active.

PyMailGUI also allows mail transfer threads to overlap in time. In particular, new emails may be written and sent while a load or send is in progress, and mail loads may overlap with sends and other mail loads already in progress. For example, while waiting for a download of mail headers or a large message, you can open a new Write window, compose a message, and send it; the send will
overlap with the load currently in progress. You may also load another mail, while the load of a large mail is in progress.

While mail transfers are in progress, pop-up windows display their current progress as a message counter. When sending a message, the original edit View window is popped back up automatically on Send failures, to save or retry. Because delete operations may change POP message numbers on the server, this operation disables other deletions and loads while in progress.

Offline mail save-file loads and deletes are also threaded: these threads may overlap in time with server transfers, and with operations on other open save files. Saves are disabled if the source or target file is busy with a load or save operation. Quit is never allowed while any thread is busy.

7) MAIL DELETION

Mail is not removed from POP servers on Load requests, but only on explicit "Delete" button deletion requests, if verified by the user. Delete requests are run immediately, upon user verification.

To delete your mail from a server and process offline: in the server list window select the All checkbutton, Save to a local file, and then Delete to delete all mails from the server; use Open to open the save file later to view and process saved mail.

When deleting from the server window, the mail list (and any already viewed message text) is not reloaded from server, if the delete was successful. If the delete fails, all email must be reloaded, because some POP message numbers may have changed; the reload occurs automatically. Delete in a file list
window deletes from the loal file only.

As of version 2.1, PyMailGUI automatically matches messages selected for deletion with their headers on the mail server, to ensure that the correct mail is deleted. If the mail index is out of synch with the server, mails that do not match the server are not deleted, since their POP message numbers are no longer accurate. In this event, an error is displayed, and a full reload
of the mail index list is automatically performed; you do not need to stop and restart PyMailGUI to reload the index list. This can slow deletions (it adds roughly one second per deleted mail on the test machine used), but prevents the wrong mail from being deleted. See the POP message number synchronization errors description in the next section.

 

8) INBOX MESSAGE NUMBER SYNCHRONIZATION

PyMailGUI does header matching in order to ensure that deletions only delete the correct messages, and periodically detect synchronization errors with the server. If a synchronization error message appears, the operation is cancelled, and a full index reload from the server is automatically performed. You need
not stop and restart PyMailGUI and reload the index, but must reattempt the operation after the reload.

The POP email protocol assigns emails a relative message number, reflecting their position in your inbox. In the server List window, PyMailGUI loads its mail index list on demand from the server, and assumes it reflects the content of your inbox from that point on. A message’s position in the index list is used as its POP relative message number for later loads and deletes.

This normally works well, since newly arrived emails are added to the end of the inbox. However, the message numbers of the index list can become out of synch with the server in two ways:

A) Because delete operations change POP relative message numbers in the inbox, deleting messages in another email client (even another PyMailGUI instance) while the PyMailGUI server list window is open can invalidate PyMailGUI’s message index numbers. In this case, the index list window may be arbitrarily out of synch with the inbox on the server.

B) It is also possible that your ISP may automatically delete emails from your inbox at any time, making PyMailGUI’s email list out of synch with message numbers on the mail server. For example, some ISPs may automatically move an email from the inbox to the undeliverable box, in response to a fetch failure. If this happens, PyMailGUI’s message numbers will be off by one, according to the server’s inbox.

To accommodate such cases, PyMailGUI 2.1 always matches messages to be deleted against the server’s inbox, by comparing already fetched headers text with the headers text returned for the same message number; the delete only occurs if the two match. In addition, PyMailGUI runs a quick check for out-of-synch errors by comparing headers for just the last message in the index, whenever the index list is updated, and whenever full messages are fetched.

This header matching adds a slight overhead to deletes, index loads, and mail fetches, but guarantees that deletes will not remove the wrong message, and ensures that the message you receive corresponds to the item selected in the server index List window. The synch test overhead is one second or less on test machines used – it requires 1 POP server connect and an inbox size and (possibly) header text fetch.

In general, you still shouldn’t delete messages in PyMailGUI while running a different email client, or that client’s message numbers may become confused unless it has simlar synchronization tests. If you receive a synch error pop up on deletes or loads, PyMailGUI automatically begins a full reload of the mail index list displayed in the server List window.

9) LOADING EMAIL

To save time, Load requests only fetch mail headers, not entire messages. View operations fetch the entire message, unless it has been previously viewed (already loaded messages are cached). Multiple message downloads may overlap in time, and may overlap with message editing and sends.

In addition, after the initial load, new Load requests only fetch headers of newly arrived messages. All headers must be refetched after a delete failure, however, due to possibly changed POP message numbers.

PyMailGUI only is connected to a mail server while a load, send, or delete operation is in progress. It does not connect at all unless one of these operations is attempted, and disconnects as soon as the operation finishes. You do not need any Internet connectivity to run PyMailGUI unless you attempt one of these operations. In addition, you may disconnect from the Internet
when they are not in progress, without having to stop the GUI–the program will reconnect on the next transfer operation.

Note: if your POP mail server does support the TOP command for fetching mail headers (most do), see variable "srvrHasTop" in the mailtools.py module to force full message downloads.

Also note that, although PyMailGUI only fetches message headers initially if your email server supports TOP, this can still take some time for very large inboxes; as a rule of thumb, use save-mail files and deletions to keep your inbox small.

10) THE mailconfig CONFIGURATION MODULE

Change the mailconfig.py module file in PyMailGUI’s home directory on your own machine to reflect your email server names, username, email address, and optional mail signature line added to all composed mails.

Most settings in this module are optional, or have reasonable preset defaults. However, you must minimally set this module’s "smtpservername" variable to send mail, and its "popservername" and "popusername" to load mail from a server. These are simple Python variables assigned to strings in this file. See the
module file and its embedded comments for details.

The mailconfig module’s "listheaders" attribute can also be set to a tuple of string header field name, to customize the set of headers displayed in list windows; mail size is always displayed last. Similarly mailconfig’s "viewheaders" attribute can extend the set of headers shown in a View window (though From, To, Cc, and Subject fields are always shown). List windows display message headers in fixed-width columns.

Variables in the mailconfig module also can be used to tailor the font used in list windows ("fontsz"), the column at which viewed and quoted text is automatically wrapped ("wrapsz"), colors and fonts in various windows, the local file where sent messages are saved, the opening of mail parts, and more; see the file’s source code for more details.

Note: use caution when changing this file, as PyMailGUI may not run at all if some of its variables are missing. You may wish to make a backup copy before editing it in case you need to restore its defaults. A future version of this system may have a configuration dialog which generates this module’s code.

11) DEPENDENCIES

This client-side program currently requires Python and Tkinter. It uses Python threads, if installed, to avoid blocking the GUI. Sending and loading email from a server requires an Internet connection. Requires Python 2.3 or later, and uses the Python "email" standard library module to parse and compose mail
text. Reuses a number of modules located in the PP3E examples tree.

12) MISCELLANEOUS HINTS

- Use ‘;’ between multiple addresses in "To"
  and "Cc" headers.
- Passwords are requested if needed, and not
  stored by PyMailGUI.
- You may list your password in a file named
  in mailconfig.py.
- Reply and Fwd automatically quote the 
  original mail text.
- Save pops up a dialog for selecting a file
  to hold saved mails.
- Save always appends to the save file,
  rather than erasing it.
- Delete does not reload message headers,
  unless it fails.
- Delete checks your inbox to make sure the
  correct mail is deleted.
- Fetches detect inbox changes and
  automatically reload index list.
- Open and save dialogs always remember the
  prior directory.
- To print emails, "Save" to a text file and
  print with other tools.
- Click this window’s Source button to view
  its source-code files.
- Watch http://www.rmi.net/~lutz for updates
  and patches
- This is an Open Source system: change its
  code as you like.
- See the SpamBayes system for a spam filter
  for incoming email.
"""

if _ _name_ _ == ‘_ _main_ _':
    print helptext                 # to stdout if run alone
    raw_input(‘Press Enter key’)   # pause in DOS console pop ups

{mospagebreak title=Ideas for Improvement}

Although I use PyMailGUI on a regular basis as is, there is always room for improvement to software, and this system is no exception. If you wish to experiment with its code, here are a few suggested projects:

  • Mail list windows could be sorted by columns on demand. This may require a more sophisticated list window structure.
  • The implementation of save-mail files limits their size by loading them into memory all at once; a DBM keyed-access implementation may work around this constraint. See the list windows module comments for ideas.
  • Hyperlink URLs within messages could be highlighted visually and made to spawn a web browser automatically when clicked by using the launcher tools we met in the GUI and system parts of this book (Tkinter’s text widget supports links directly).
  • Because Internet newsgroup posts are similar in structure to emails (header lines plus body text; see the nntplib example in Chapter 14), this script could in principle be extended to display both email messages and news articles. Classifying such a mutation as clever generalization or diabolical hack is left as an exercise in itself.
  • The help text has grown large in this version: this might be better implemented as HTML, and displayed in a web browser, with simple text as a fallback option. In fact, we might extract the simple text from the HTML, to avoid redundant copies.
  • Saves and Split writes could also be threaded for worst-case scenarios. For pointers on making Saves parallel, see the comments in the file class of ListWindows.py ; there may be some subtle issues that require both thread locks and general file locking for potentially concurrent updates.
  • There is currently no way to delete an attachment once it has been added in compose windows. This might be supported by adding quick-access part buttons to compose windows, too, which could verify and delete the part when clicked.
  • We could add an automatic spam filter for mails fetched, in addition to any provided at the email server or ISP.
  • Mail text is editable in message view windows, even though a new mail is not being composed. This is deliberate—users can annotate the message’s text and save it in a text file with the Save button at the bottom of the window. This might be confusing, though, and is redundant (we can also edit and save by clicking on the main text’s quick-access part button). Removing edit tools would require extending PyEdit.
  • We could also add support for mail lists, allowing users to associate multiple email addresses with a saved list name. On sends to a list name, the mail would be sent to all on the list (the “To:” addresses passed to smtplib ), but the email list could be used for the email’s “To:” header line).

And so on—because this software is open source, it is also necessarily open-ended. Suggested exercises in this category are delegated to your imagination.

This concludes our tour of Python client-side programming. In the next chapter, we’ll hop the fence to the other side of the Internet world and explore scripts that run on server machines. Such programs give rise to the grander notion of applications that live entirely on the Web and are launched by web browsers. As we take this leap in structure, keep in mind that the tools we met in this and the previous chapter are often sufficient to implement all the distributed processing that many applications require, and they can work in harmony with scripts that run on a server. To completely understand the Web world view, though, we need to explore the server realm, too.


* And remember: you would have to multiply these line counts by a factor of four or five to get the equivalent in a language like C or C++. If you’ve done much programming, you probably recognize that the fact that we can implement a fairly full-featured mail processing program in roughly 2,000 lines of code speaks volumes about the power of the Python language and its libraries. For comparison, the original version of this program from the second edition of this book was just 725 lines in 3 new modules, but also was very limited—it did not support PyMailGUI2’s attachments, thread overlap, local mail files, and so on.

* In fact, my ISP’s webmail send system went down the very day I had to submit this edition of the book to my publisher! No worries—-I fired up PyMailGUI and used it to send the book as attachment files through a different server. In a sense, this book submitted itself.

* The standard library’s webbrowser module would help for HTML-based help. Actually, the help display started life even less fancy: it originally displayed help text in a standard information box pop up, generated by the Tkinter showinfo call used earlier in the book. This worked fine on Windows (at least with a small amount of help text), but it failed on Linux because of a default line-length limit in information pop-up boxes; lines were broken so badly as to be illegible.

[gp-comments width="770" linklove="off" ]
antalya escort bayan antalya escort bayan