MailFetcher Class
The class defined in Example 13-24 does the work of interfacing with a POP email
server—loading, deleting, and synchronizing. This class merits a few additional words
of explanation.
General usage
This module deals strictly in email text; parsing email after it has been fetched is dele-
gated to a different module in the package. Moreover, this module doesn’t cache already
loaded information; clients must add their own mail-retention tools if desired. Clients
must also provide password input methods or pass one in, if they cannot use the console
input subclass here (e.g., GUIs and web-based programs).
The loading and deleting tasks use the standard library poplib module in ways we saw
earlier in this chapter, but notice that there are interfaces for fetching just message
header text with the TOP action in POP if the mail server supports it. This can save
substantial time if clients need to fetch only basic details for an email index. In addition,
the header and full-text fetchers are equipped to load just mails newer than a particular
number (useful once an initial load is run), and to restrict fetches to a fixed-sized set of
the mostly recently arrived emails (useful for large inboxes with slow Internet access
or servers).
This module also supports the notion of progress indicators—for methods that perform
multiple downloads or deletions, callers may pass in a function that will be called as
each mail is processed. This function will receive the current and total step numbers.
It’s left up to the caller to render this in a GUI, console, or other user interface.
Unicode decoding for full mail text on fetches
Additionally, this module is where we apply the session-wide message bytes Unicode
decoding policy required for parsing, as discussed earlier in this chapter. This decoding
uses an encoding name user setting in the mailconfig module, followed by heuristics.
Because this decoding is performed immediately when a mail is fetched, all clients of
this package can assume message text is str Unicode strings—including any later pars-
ing, display, or save operations. In addition to the mailconfig setting, we also apply a
few guesses with common encoding types, though it’s not impossible that this may lead
to problems if mails decoded by guessing cannot be written to mail save fails using the
mailconfig setting.
As described, this session-wide approach to encodings is not ideal, but it can be adjusted
per client session and reflects the current limitations of email in Python 3.1—its parser
requires already decoded Unicode strings, but fetches return bytes. If this decoding
fails, as a last resort we attempt to decode headers only, as either ASCII (or other com-
mon format) text or the platform default, and insert an error message in the email
body—a heuristic that attempts to avoid killing clients with exceptions if possible (see
The mailtools Utility Package | 967