Deleting Email and More with the PyMailGUI Client

Continuing our tour through PyMailGUI, this week we show you how to delete email, explain POP message numbers and synchronization, and finally begin talking about the code. This article, the fourth of six parts, 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.

Deleting Email

So far, we’ve covered every action button on list windows except for Delete and the All checkbox. The All checkbox simply toggles from selecting all messages at once or deselecting all (View, Delete, Reply, Fwd, and Save action buttons apply to all currently selected messages). PyMailGUI also lets us delete messages from the server permanently, so that we won’t see them the next time we access our inbox.

Delete operations are kicked off the same way as Views and Saves; just press the Delete button instead. In typical operation, I eventually delete email I’m not interested in, and save and delete emails that are important. We met Save earlier in this demo.


Figure 15-31.  PyMailGUI view forwarded mail


Figure 15-32.  PyMailGUI view forwarded mail, raw

Like View, Save, and other operations, Delete can be applied to one or more messages. Deletes happen immediately, and like all server transfers they are run in a non-blocking thread but are performed only if you verify the operation in a popup, such as the one shown in Figure 15-33.


Figure 15-33.  PyMailGUI delete verification on quit

By design, no mail is ever removed automatically: you will see the same messages the next time PyMailGUI runs. It deletes mail from your server only when you ask it to, and then only if verified in the last popup shown (this is your last chance to prevent permanent mail removal). After the deletions are performed, the mail index is updated, and the GUI session continues.

Deletions disable mail loads and other deletes while running and cannot be run in parallel with loads or other deletes already in progress because they may change POP message numbers and thus modify the mail index list. Messages may still be composed during a deletion, however, and offline save files may be processed.

{mospagebreak title=POP Message Numbers and Synchronization}

Deletions are complicated by POP’s message-numbering scheme. We learned about the potential for synchronization errors between the server’s inbox and the fetched email list in Chapter 14, when studying the mailtools package PyMailGUI uses (near Example 14-21). In brief, POP assigns each message a relative sequential number, starting from one, and these numbers are passed to the server to fetch and delete messages. The server’s inbox is normally locked while a connection is held so that a series of deletions can be run as an atomic operation; no other inbox changes occur until the connection is closed.

However, message number changes also have some implications for the GUI itself. It’s all right if new mail arrives while we’re displaying the result of a prior download—the new mail is assigned higher numbers, beyond what is displayed on the client. But if we delete a message in the middle of a mailbox after the index has been loaded from the mail server, the numbers of all messages after the one deleted change (they are decremented by one). As a result, some message numbers might no longer be valid if deletions are made while viewing previously loaded email.

To work around this, PyMailGUI adjusts all the displayed numbers after a Delete by simply removing the entries for deleted mails from its index list and mail cache. However, this adjustment is not enough to keep the GUI in sync with the server’s inbox if the inbox is modified at a time other than after the end, by deletions in another email client (even in another PyMailGUI session) or by deletions performed by the mail server itself (e.g., messages determined to be undeliverable and automatically removed from the inbox).

To handle these cases, PyMailGUI uses the safe deletion and synchronization tests in mailtools . That module uses mail header matching to detect mail list and server inbox synchronization errors. For instance, if another email client has deleted a message prior to the one to be deleted by PyMailGUI, mailtools catches the problem and cancels the deletion, and an error popup like the one in Figure 15-34 is displayed.


Figure 15-34.  Safe deletion test detection of inbox difference

Similarly, index loads and message fetches run a synchronization test in mailtools , as well. Figure 15-35 captures the error generated if a message has been deleted in another client since we last loaded the server index window.


Figure 15-35.  Synchronization error on after delete in another client

In both error cases, the inbox is automatically reloaded by PyMailGUI immediately after the error popup is dismissed. This scheme ensures that PyMailGUI won’t delete or display the wrong message, in the rare case that the server’s inbox is changed without its knowledge. See mailtools in Chapter 14 for more on synchronization tests.

{mospagebreak title=Multiple Windows and Status Messages}

Note that PyMailGUI is really meant to be a multiple-window interface—a detail not made obvious by the earlier screenshots. For example, Figure 15-36 shows PyMailGUI with the main server list window, two save-file list windows, two message view windows, and help. All these windows are nonmodal; that is, they are all active and independent, and do not block other windows from being selected. This interface looks slightly different on Linux and the Mac, but it has the same functionality.


Figure 15-36.  PyMailGUI multiple windows and text editors

In general, you can have any number of mail view or compose windows up at once, and cut and paste between them. This matters, because PyMailGUI must take care to make sure that each window has a distinct text-editor object. If the text-editor object were a global, or used globals internally, you’d likely see the same text in each window (and the Send operations might wind up sending text from another window). To avoid this, PyMailGUI creates and attaches a new TextEditor instance to each view and compose window it creates, and associates the new editor with the Send button’s callback handler to make sure we get the right text.

Finally, PyMailGUI prints a variety of status messages as it runs, but you see them only if you launch the program from the system command-line console window (e.g., a DOS box on Windows or an xterm on Linux), or by double-clicking on its filename icon (its main script is a .py, not a .pyw). On Windows, you won’t see these messages when PyMailGUI is started from another program, such as the PyDemos or PyGadgets launcher bar GUIs. These status messages print server information, show mail loading status, and trace the load, store, and delete threads that are spawned along the way. If you want PyMailGUI to be more verbose, launch it from a command line and watch:

  C:…PP3EInternetEmail PyMailGui>PyMailGui2.py
 
user: pp3e
  loading headers
  Connecting…
  +OK NGPopper vEL_6_10 at earthlink.net ready<7044.1139211610@poptawny.atl.sa.
  earthlink.net>
  load headers exit
  synch check
  Connecting…
  +OK NGPopper vEL_6_10 at earthlink.net ready <22399.1139211626@pop-tawny.atl.sa.
  earthlink.net>
  Same headers text
  load 16
  Connecting…
  +OK NGPopper vEL_6_10 at earthlink.net ready <27558.1139211627@pop-tawny.atl.sa.
  earthlink.net>
  Sending to…['pp3e@earthlink.net']
  From: pp3e@earthlink.net
  To: pp3e@earthlink.net
  Subject: Fwd: Re: America MP3 file
  Date: Mon, 06 Feb 2006 07:41:05 -0000
  X-Mailer: PyMailGUI 2.1 (Python)

  –Mark Lutz (http://www.rmi.net/~lutz)

  > —–Original Message—–
  > From: pp3e@earthlink.net
  >
  Send exit

You can also double-click on the PyMailGui.py filename in your file explorer GUI and monitor the popped-up DOS console box on Windows. Console messages are mostly intended for debugging, but they can also be used to help understand the system’s operation.

For more details on using PyMailGUI, see its help display, or read the help string in the module PyMailGuiHelp.py , listed in Example 15-9 in the next section.

{mospagebreak title=PyMailGUI Implementation}

Last but not least, we get to the code. PyMailGUI consists of the nine new modules listed at the start of this chapter; the source code for these modules is listed in this section.

Code Reuse

Besides the code here, PyMailGUI also gets a lot of mileage out of reusing modules we wrote earlier and won’t repeat here: mailtools for mail loads, composition, pars ing, and delete operations; threadtools for managing server and local file access threads; the GUI section’s TextEditor for displaying and editing mail message text; and so on.

In addition, standard Python modules and packages such as poplib , smtplib , and email hide most of the details of pushing bytes around the Net and extracting and building message components. As usual, the Tkinter standard library module also implements GUI components in a portable fashion.

Code Structure

As mentioned earlier, PyMailGUI applies code factoring and OOP to leverage code reuse. For instance, list view windows are implemented as a common superclass that codes most actions, along with one subclass for the server inbox list window and one for local save-file list windows. The subclasses customize the common superclass for their specific mail media.

This design reflects the operation of the GUI itself—server list windows load mail over POP, and save-file list windows load from local files. The basic operation of list window layout and actions, though, is similar for both and is shared in the common superclass to avoid redundancy and simplify the code. Message view windows are similarly factored: a common view window superclass is reused and customized for write, reply, and forward view windows.

To make the code easier to follow, it is divided into two main modules that reflect the structure of the GUI—one for the implementation of list window actions and one for view window actions. If you are looking for the implementation of a button that appears in a mail view or edit window, for instance, see the view window module and search for a method whose name begins with the word on—the convention used for callback handler methods. Button text can also be located in name/callback tables used to build the windows. Actions initiated on list windows are coded in the list window module instead.

In addition, the message cache is split off into an object and module of its own, and potentially reusable tools are coded in importable modules (e.g., line wrapping and utility popups). PyMailGUI also includes a main module that defines startup window classes, a module that contains the help text as a string, and the mailconfig user settings module (a version specific to PyMailGUI is used here).

The next few sections list all of PyMailGUI’s code for you to study; as you read, refer back to the demo earlier in this chapter and run the program live to map its behavior back to its code. PyMailGUI also includes a __init__.py file so that it can be used as a package—some of its modules may be useful in other programs. The __init__.py is empty in this package, so we omit it here.

Please check back next week for the continuation of this article.

[gp-comments width="770" linklove="off" ]

chat