[PATCH 02/13] Re: Import newest version of imaplib2

[Nicolas Sebrecht]

On Mon, Feb 07, 2011 at 01:23:52PM -0500, Ethan Glasser-Camp wrote:
> On 02/06/2011 03:38 PM, Nicolas Sebrecht wrote:

> >The http://sydney.edu.au/engineering/it/~piers/python/ page states it's
> >a modified version from the standard distribution. It would be nice to
> >explain what was changed and why we want this one.
> 
> Are you looking for this information in an email, in a commit
> message, in comments, or what?

Exactly. This information is all about policy/choices done (how and
_why_) at a given time in the development process. Such information is
important to have in the history of the project.

You did the job very nicely. You should simply add all the following in
the commit message:

" imaplib2, written by the same guy who wrote imaplib, is very
  different from imaplib itself. Calling it a modified version from
  the standard distribution is misleading. It's more like a complete
  rewrite. As such, it's not really possible to summarize what was
  changed.
  
  The largest thing is that imaplib2 is "threaded". Instead of doing
  blocking writes/reads on the socket during/after every command,
  imaplib2 forks off threads to read and write to the socket based on
  input and output buffers. This opens the door to asynchronous
  commands (every command is potentially asynchronous, according to
  the docs), and in particular IDLE, which is by definition an
  asynchronous command.
  
  The author writes: "imaplib2 can be substituted for imaplib in
  existing clients with no changes in the code", but that's pretty
  misleading. It might be true for certain simple users of imaplib,
  but for us it's completely false. Among other things, how untagged
  responses are stored in-memory is different -- instead of a hash
  table, it's a list. I'm guessing this is to preserve order of
  responses.
  
  I think there are other miscellaneous improvements, like I think
  imaplib2 is IPv6 safe out-of-the-box, but I haven't conducted an
  extremely thorough examination of the differences :)
"

-- 
Nicolas Sebrecht