Merged revisions 53451-53537 via svnmerge from
svn+ssh://pythondev@svn.python.org/python/trunk
........
r53454 | brett.cannon | 2007-01-15 20:12:08 +0100 (Mon, 15 Jan 2007) | 3 lines
Add a note for strptime that just because strftime supports some extra
directive that is not documented that strptime will as well.
........
r53458 | vinay.sajip | 2007-01-16 10:50:07 +0100 (Tue, 16 Jan 2007) | 1 line
Updated rotating file handlers to use _open().
........
r53459 | marc-andre.lemburg | 2007-01-16 14:03:06 +0100 (Tue, 16 Jan 2007) | 2 lines
Add news items for the recent pybench and platform changes.
........
r53460 | sjoerd.mullender | 2007-01-16 17:42:38 +0100 (Tue, 16 Jan 2007) | 4 lines
Fixed ntpath.expandvars to not replace references to non-existing
variables with nothing. Also added tests.
This fixes bug #494589.
........
r53464 | neal.norwitz | 2007-01-17 07:23:51 +0100 (Wed, 17 Jan 2007) | 1 line
Give Calvin Spealman access for python-dev summaries.
........
r53465 | neal.norwitz | 2007-01-17 09:37:26 +0100 (Wed, 17 Jan 2007) | 1 line
Remove Calvin since he only has access to the website currently.
........
r53466 | thomas.heller | 2007-01-17 10:40:34 +0100 (Wed, 17 Jan 2007) | 2 lines
Replace C++ comments with C comments.
........
r53472 | andrew.kuchling | 2007-01-17 20:55:06 +0100 (Wed, 17 Jan 2007) | 1 line
[Part of bug #1599254] Add suggestion to Mailbox docs to use Maildir, and warn user to lock/unlock mailboxes when modifying them
........
r53475 | georg.brandl | 2007-01-17 22:09:04 +0100 (Wed, 17 Jan 2007) | 2 lines
Bug #1637967: missing //= operator in list.
........
r53477 | georg.brandl | 2007-01-17 22:19:58 +0100 (Wed, 17 Jan 2007) | 2 lines
Bug #1629125: fix wrong data type (int -> Py_ssize_t) in PyDict_Next docs.
........
r53481 | neal.norwitz | 2007-01-18 06:40:58 +0100 (Thu, 18 Jan 2007) | 1 line
Try reverting part of r53145 that seems to cause the Windows buildbots to fail in test_uu.UUFileTest.test_encode
........
r53482 | fred.drake | 2007-01-18 06:42:30 +0100 (Thu, 18 Jan 2007) | 1 line
add missing version entry
........
r53483 | neal.norwitz | 2007-01-18 07:20:55 +0100 (Thu, 18 Jan 2007) | 7 lines
This test doesn't pass on Windows. The cause seems to be that chmod
doesn't support the same funcationality as on Unix. I'm not sure if
this fix is the best (or if it will even work)--it's a test to see
if the buildbots start passing again.
It might be better to not even run this test if it's windows (or non-posix).
........
r53488 | neal.norwitz | 2007-01-19 06:53:33 +0100 (Fri, 19 Jan 2007) | 1 line
SF #1635217, Fix unbalanced paren
........
r53489 | martin.v.loewis | 2007-01-19 07:42:22 +0100 (Fri, 19 Jan 2007) | 3 lines
Prefix AST symbols with _Py_. Fixes #1637022.
Will backport.
........
r53497 | martin.v.loewis | 2007-01-19 19:01:38 +0100 (Fri, 19 Jan 2007) | 2 lines
Add UUIDs for 2.5.1 and 2.5.2
........
r53499 | raymond.hettinger | 2007-01-19 19:07:18 +0100 (Fri, 19 Jan 2007) | 1 line
SF# 1635892: Fix docs for betavariate's input parameters .
........
r53503 | martin.v.loewis | 2007-01-20 15:05:39 +0100 (Sat, 20 Jan 2007) | 2 lines
Merge 53501 and 53502 from 25 branch:
Add /GS- for AMD64 and Itanium builds where missing.
........
r53504 | walter.doerwald | 2007-01-20 18:28:31 +0100 (Sat, 20 Jan 2007) | 2 lines
Port test_resource.py to unittest.
........
r53505 | walter.doerwald | 2007-01-20 19:19:33 +0100 (Sat, 20 Jan 2007) | 2 lines
Add argument tests an calls of resource.getrusage().
........
r53506 | walter.doerwald | 2007-01-20 20:03:17 +0100 (Sat, 20 Jan 2007) | 2 lines
resource.RUSAGE_BOTH might not exist.
........
r53507 | walter.doerwald | 2007-01-21 00:07:28 +0100 (Sun, 21 Jan 2007) | 2 lines
Port test_new.py to unittest.
........
r53508 | martin.v.loewis | 2007-01-21 10:33:07 +0100 (Sun, 21 Jan 2007) | 2 lines
Patch #1610575: Add support for _Bool to struct.
........
r53509 | georg.brandl | 2007-01-21 11:28:43 +0100 (Sun, 21 Jan 2007) | 3 lines
Bug #1486663: don't reject keyword arguments for subclasses of builtin
types.
........
r53511 | georg.brandl | 2007-01-21 11:35:10 +0100 (Sun, 21 Jan 2007) | 2 lines
Patch #1627441: close sockets properly in urllib2.
........
r53517 | georg.brandl | 2007-01-22 20:40:21 +0100 (Mon, 22 Jan 2007) | 3 lines
Use new email module names (#1637162, #1637159, #1637157).
........
r53518 | andrew.kuchling | 2007-01-22 21:26:40 +0100 (Mon, 22 Jan 2007) | 1 line
Improve pattern used for mbox 'From' lines; add a simple test
........
r53519 | andrew.kuchling | 2007-01-22 21:27:50 +0100 (Mon, 22 Jan 2007) | 1 line
Make comment match the code
........
r53522 | georg.brandl | 2007-01-22 22:10:33 +0100 (Mon, 22 Jan 2007) | 2 lines
Bug #1249573: fix rfc822.parsedate not accepting a certain date format
........
r53524 | georg.brandl | 2007-01-22 22:23:41 +0100 (Mon, 22 Jan 2007) | 2 lines
Bug #1627316: handle error in condition/ignore pdb commands more gracefully.
........
r53526 | lars.gustaebel | 2007-01-23 12:17:33 +0100 (Tue, 23 Jan 2007) | 4 lines
Patch #1507247: tarfile.py: use current umask for intermediate
directories.
........
r53527 | thomas.wouters | 2007-01-23 14:42:00 +0100 (Tue, 23 Jan 2007) | 13 lines
SF patch #1630975: Fix crash when replacing sys.stdout in sitecustomize
When running the interpreter in an environment that would cause it to set
stdout/stderr/stdin's encoding, having a sitecustomize that would replace
them with something other than PyFile objects would crash the interpreter.
Fix it by simply ignoring the encoding-setting for non-files.
This could do with a test, but I can think of no maintainable and portable
way to test this bug, short of adding a sitecustomize.py to the buildsystem
and have it always run with it (hmmm....)
........
r53528 | thomas.wouters | 2007-01-23 14:50:49 +0100 (Tue, 23 Jan 2007) | 4 lines
Add news entry about last checkin (oops.)
........
r53531 | martin.v.loewis | 2007-01-23 22:11:47 +0100 (Tue, 23 Jan 2007) | 4 lines
Make PyTraceBack_Here use the current thread, not the
frame's thread state. Fixes #1579370.
Will backport.
........
r53535 | brett.cannon | 2007-01-24 00:21:22 +0100 (Wed, 24 Jan 2007) | 5 lines
Fix crasher for when an object's __del__ creates a new weakref to itself.
Patch only fixes new-style classes; classic classes still buggy.
Closes bug #1377858. Already backported.
........
r53536 | walter.doerwald | 2007-01-24 01:42:19 +0100 (Wed, 24 Jan 2007) | 2 lines
Port test_popen.py to unittest.
........
diff --git a/Doc/lib/libmailbox.tex b/Doc/lib/libmailbox.tex
index 75ea7e1..961b050 100644
--- a/Doc/lib/libmailbox.tex
+++ b/Doc/lib/libmailbox.tex
@@ -25,22 +25,29 @@
A mailbox, which may be inspected and modified.
\end{classdesc*}
+The \class{Mailbox} class defines an interface and
+is not intended to be instantiated. Instead, format-specific
+subclasses should inherit from \class{Mailbox} and your code
+should instantiate a particular subclass.
+
The \class{Mailbox} interface is dictionary-like, with small keys
-corresponding to messages. Keys are issued by the \class{Mailbox} instance
-with which they will be used and are only meaningful to that \class{Mailbox}
-instance. A key continues to identify a message even if the corresponding
-message is modified, such as by replacing it with another message. Messages may
-be added to a \class{Mailbox} instance using the set-like method
-\method{add()} and removed using a \code{del} statement or the set-like methods
-\method{remove()} and \method{discard()}.
+corresponding to messages. Keys are issued by the \class{Mailbox}
+instance with which they will be used and are only meaningful to that
+\class{Mailbox} instance. A key continues to identify a message even
+if the corresponding message is modified, such as by replacing it with
+another message.
+
+Messages may be added to a \class{Mailbox} instance using the set-like
+method \method{add()} and removed using a \code{del} statement or the
+set-like methods \method{remove()} and \method{discard()}.
\class{Mailbox} interface semantics differ from dictionary semantics in some
-noteworthy ways. Each time a message is requested, a new representation
-(typically a \class{Message} instance) is generated, based upon the current
-state of the mailbox. Similarly, when a message is added to a \class{Mailbox}
-instance, the provided message representation's contents are copied. In neither
-case is a reference to the message representation kept by the \class{Mailbox}
-instance.
+noteworthy ways. Each time a message is requested, a new
+representation (typically a \class{Message} instance) is generated
+based upon the current state of the mailbox. Similarly, when a message
+is added to a \class{Mailbox} instance, the provided message
+representation's contents are copied. In neither case is a reference
+to the message representation kept by the \class{Mailbox} instance.
The default \class{Mailbox} iterator iterates over message representations, not
keys as the default dictionary iterator does. Moreover, modification of a
@@ -51,9 +58,14 @@
\exception{KeyError} exception if the corresponding message is subsequently
removed.
-\class{Mailbox} itself is intended to define an interface and to be inherited
-from by format-specific subclasses but is not intended to be instantiated.
-Instead, you should instantiate a subclass.
+Be very cautious when modifying mailboxes that might also be changed
+by some other process. The safest mailbox format to use for such
+tasks is Maildir; try to avoid using single-file formats such as mbox
+for concurrent writing. If you're modifying a mailbox, no matter what
+the format, you must lock it by calling the \method{lock()} and
+\method{unlock()} methods before making any changes. Failing to lock
+the mailbox runs the risk of losing data if some other process makes
+changes to the mailbox while your Python code is running.
\class{Mailbox} instances have the following methods:
@@ -202,15 +214,16 @@
\begin{methoddesc}{flush}{}
Write any pending changes to the filesystem. For some \class{Mailbox}
-subclasses, changes are always written immediately and this method does
-nothing.
+subclasses, changes are always written immediately and \method{flush()} does
+nothing, but you should still make a habit of calling this method.
\end{methoddesc}
\begin{methoddesc}{lock}{}
Acquire an exclusive advisory lock on the mailbox so that other processes know
not to modify it. An \exception{ExternalClashError} is raised if the lock is
not available. The particular locking mechanisms used depend upon the mailbox
-format.
+format. You should \emph{always} lock the mailbox before making any
+modifications to its contents.
\end{methoddesc}
\begin{methoddesc}{unlock}{}
@@ -1373,36 +1386,55 @@
\begin{verbatim}
import mailbox
destination = mailbox.MH('~/Mail')
+destination.lock()
for message in mailbox.Babyl('~/RMAIL'):
destination.add(MHMessage(message))
+destination.flush()
+destination.unlock()
\end{verbatim}
-An example of sorting mail from numerous mailing lists, being careful to avoid
-mail corruption due to concurrent modification by other programs, mail loss due
-to interruption of the program, or premature termination due to malformed
-messages in the mailbox:
+This example sorts mail from several mailing lists into different
+mailboxes, being careful to avoid mail corruption due to concurrent
+modification by other programs, mail loss due to interruption of the
+program, or premature termination due to malformed messages in the
+mailbox:
\begin{verbatim}
import mailbox
import email.Errors
+
list_names = ('python-list', 'python-dev', 'python-bugs')
+
boxes = dict((name, mailbox.mbox('~/email/%s' % name)) for name in list_names)
-inbox = mailbox.Maildir('~/Maildir', None)
+inbox = mailbox.Maildir('~/Maildir', factory=None)
+
for key in inbox.iterkeys():
try:
message = inbox[key]
except email.Errors.MessageParseError:
continue # The message is malformed. Just leave it.
+
for name in list_names:
list_id = message['list-id']
if list_id and name in list_id:
+ # Get mailbox to use
box = boxes[name]
+
+ # Write copy to disk before removing original.
+ # If there's a crash, you might duplicate a message, but
+ # that's better than losing a message completely.
box.lock()
box.add(message)
- box.flush() # Write copy to disk before removing original.
+ box.flush()
box.unlock()
+
+ # Remove original message
+ inbox.lock()
inbox.discard(key)
+ inbox.flush()
+ inbox.unlock()
break # Found destination, so stop looking.
+
for box in boxes.itervalues():
box.close()
\end{verbatim}