In the enclosed patch, there are four changes 
1. add support for the optional CAPA pop command, since it is needed
   for starttls support discovery
2. add support for the STLS pop command
3. replace home-grown file-like methods and replace them with ssl
   socket's makefile() in POP3_SSL
4. Properly shutdown sockets at close() time to avoid server-side pile-up

The needed changes to documentation if the patch gets accepted

You might split your patch into smaller patches, example:
  * patch 1: implement CAPA method
  * patch 2: POP3_SSL refatoring
  * patch 3: stls() method

Comments:
- Do you really need to keep a reference to the "raw" socket 
(self._sock) for a SSL connection?
- I don't understand what is sock.shutdown(SHUT_RDWR). When is it 
needed? Does it change the behaviour?
- Could you write a method to parse the capabilities because I hate 
long lambda function. You may write doctest for the new method :-)

I understand the need to keep things simple, but this time the split
seemed a bit overkill. If needed, I'll redo the patch into a small
series. Thinking of it... I was unsure if it really made sense to split
out smtp/pop/imap patches instead of sending them all at once... :-)

As for the shutdown before close, it's needed to let the server know
we are leaving, instead of waiting until socket timeout. This is the
reason I need to keep the reference to the wrapped socket.

You don't usually configure maildrop servers to limit the number/rate of
connects as you do on smtp servers; still, you could get into problems
with stateful forewalls or the like.

> As for the shutdown before close, it's needed to let the server know
> we are leaving, instead of waiting until socket timeout.

Extracts of an UNIX FAQ [1]:
"Generally the difference between close() and shutdown() is: close() 
closes the socket id for the process but the connection is still 
opened if another process shares this socket id."

"i have noticed on some (mostly non-unix) operating systems though a 
close by all processes (threads) is not enough to correctly flush 
data, (or threads) is not. A shutdown must be done, but on many 
systems it is superfulous."

So shutdown() is useless on most OS, but it looks like it's better to 
use it ;-)

> This is the reason I need to keep the reference to the wrapped 
socket.

You don't need to do that. The wrapper already calls shutdown() of the 
parent socket (see Lib/ssl.py).

[1] http://www.developerweb.net/forum/archive/index.php/t-2940.html

I'm reasonably sure Victor is right about the original socket being
unneeded. How does the series look now?

"lst[1:] if len(lst)>1 else []" is useless, lst[1:] alone does the 
same :-) So it can be simplify to:
  def _parsecap(line):
     lst = line.split()
     return lst[0], lst[1:]

You might add a real example in the capa() docstring.

About poplib_02_sock_shutdown.diff: I'm not sure that poplib is the 
right place to fix the issue... if there is really an issue. Why not 
calling shutdown directly in socket.close()? :-)

You removed self._sock, nice.

Changed CAPA as requested: now there is a proper docstring, and the
useless if ... else ... is gone.

As for the shutdown/close comment, I think there could be cases
where you are going to close but don't want to shutdown: e.g. you might
close a dup-ed socket, but the other owner would want to continue
working with his copy of the socket.

There is a problem I forgot to state with test_anonlogin:
since I try and test both SSL and starttls, the DoS checker at cmu kicks
in and refuse the login attempt in PopSSLTest. Since I'd rather avoid
cheating, I'm leaning to try logging in as SomeUser, and expecting a
failure in both cases. Comments?

I'm enclosing the expected-failure version of test_popnet. It's much
simpler to talk and comment about something you can see!

How is going? Any hope for 2.7/3.2?

Ping...

Any hope for 2.7/3.2?

3.3 beta will be published next Sunday. Any hope?

Lorenzo, is your patch applicable to 3.3?

I've refreshed the patches to apply on 3.3, and adapted the to the
unit-test framework by giampaolo.rodola.

I've refreshed once more the patches, adding the implementation of the stls command in test_poplib.py.

IMHO, the changes as they stand now are low risk, and could as well go into 3.3.

With many thanks to Giampaolo for implementing the asynchat/asyncore pop3 server!

Lorenzo, 3.3 is in beta mode now. No new features accepted :-(.

Please, fulfill a PSF contributor agreement http://www.python.org/psf/contrib/

Jesús,
      as requested, I've scanned and sent the signed contributor agreement.

In the meanwhile, I updated once more patches 01 and 03:

01: stealed the socket shutdown check from Antoine Pitrou's r66134
03: adapt DummyPOP3_SSLHandler to use the handle_read() and
    the _do_tls_handshake() methods inherited from DummyPOP3Handler

As for the "no-new-features"... I know, I know... (that's the reason why I wrote that big "in my HUMBLE opionion" ;-)

Hello,

Here are some comments about the patches:

1) poplib_01_socket_shutdown_v3.diff: looks fine to me

2) poplib_02_server_capabilities_v3.diff:

- please try to follow PEP 8 (i.e. `capa = {}` not `capa={}`)
- I think the capa() result should be a dict mapping str keys to str values (not bytes), since that part of the POP3 protocol seems to have a well-defined character set (ASCII)

3) poplib_03_starttls_v3.diff:

- same comment about PEP 8
- why did you change the signature of the _create_socket() method? it looks gratuitous
- the new method should be called starttls() as in other modules, not stls()
- starttls() should only take a context argument; no need to support separate keyfile and certfile arguments
- what is the point of catching errors like this:

+        except error_proto as _err:
+            resp = _err

Updated 02 and 03 patches (mostly) in line with Antoine's review comments:

> 2) poplib_02_server_capabilities_v3.diff:
> - please try to follow PEP 8 (i.e. `capa = {}` not `capa={}`)
> - I think the capa() result should be a dict mapping str keys to str > values (not bytes), since that part of the POP3 protocol seems to
> have a well-defined character set (ASCII)

Completely right. Done.

> 3) poplib_03_starttls_v3.diff:
>
> - same comment about PEP 8

where?

> - why did you change the signature of the _create_socket() 
>  method? it looks gratuitous

undone

> - the new method should be called starttls() as in other modules, not >  stls()

Here I'm following: at :ref:`pop3-objects` in Doc/library/poplib.rst, 

  All POP3 commands are represented by methods of the same name, in
  lower-case; most return the response text sent by the server.

IMHO, having a single method with a name different than the underlying
POP command would just be confusing. For this reason, I'd rather avoid
adding an alias like in

    starttls = stls

or the reverse...

> - starttls() should only take a context argument; no need to support > separate keyfile and certfile arguments

Right, non need to mimick pre-SSLContext method signatures!

> - what is the point of catching errors like this:
> [...]

undone

> where?

In `caps=self.capa()` (you need a space around the assignment operator).

> Here I'm following: at :ref:`pop3-objects` in Doc/library/poplib.rst, 

Ah, ok. Then I agree it makes sense to call it stls(). No need for an alias, IMO.

OK, I'm uploading poplib_03_starttls_v5.diff; I only changed the 
"caps=self.capa()" into "caps = self.capa()" in the "@@ -352,21 +360,42 @@ class POP3:" hunk.

Thank you for pointing at the line; I tried to run pep8.py on poplib.py, but failed to find the line, since I was overwhelmed by the reported pre-existing pep8 inconsistencies...

I'm tempted to open a pep8 issue on poplib after we finish with stls...

Thank you very much for reviewing!

Thank you Lorenzo. Your patch lacks a couple of details, such as "versionadded" and "versionchanged" tags, but I can handle this myself.

New changeset 79e33578dc05 by Antoine Pitrou in branch 'default':
Issue #4473: Ensure the socket is shutdown cleanly in POP3.close().
http://hg.python.org/cpython/rev/79e33578dc05

New changeset d30fd9834cec by Antoine Pitrou in branch 'default':
Issue #4473: Add a POP3.capa() method to query the capabilities advertised by the POP3 server.
http://hg.python.org/cpython/rev/d30fd9834cec

New changeset 2329f9198d7f by Antoine Pitrou in branch 'default':
Issue #4473: Add a POP3.stls() to switch a clear-text POP3 session into an encrypted POP3 session, on supported servers.
http://hg.python.org/cpython/rev/2329f9198d7f

Patches committed. Thank you very much!

New changeset 75a146a657d9 by Antoine Pitrou in branch 'default':
Fix missing import (followup to #4473).
http://hg.python.org/cpython/rev/75a146a657d9