Logged In: YES 
user_id=1504904

I'd forgotten about this for a while, but I see the docs
didn't actually get changed for 2.5.  I was going to submit
a patch for them today and suggest using subclasses as
described below, but then I realized that subclassing
wouldn't work, since the code makes use of the module
functions _lock_file() and _unlock_file() outside of the
lock()/unlock() methods.

A possible solution is attached; the Mailbox class is given
methods _acquire_lock() and _release_lock() wrapping
_lock_file() and _unlock_file(), and these are used instead
(thus, they can be overridden as methods, but if someone had
replaced _lock_file() in the module namespace instead, then
their code would still work).

Also attached is a minimal doc patch to describe the new
(shorter) list of locking methods.  I've called the
system-call locking "fcntl()" since that's the usual term
when dealing with mailboxes, and the name fcntl.lockf() is
misleading (it calls fcntl() directly, not lockf(), and the
Linux man pages say that "In general, the relation between
lockf() and fcntl() is unspecified.").