Python 2.7

>>> import socket
>>> socket.SocketType
<class 'socket._socketobject'>
>>> s = socket.socket()
>>> isinstance(s, socket.SocketType)
True
>>> 


Python 3.4

>>> socket.SocketType
<enum 'SocketType'>
>>> s = socket.socket()
>>> isinstance(s, socket.SocketType)
False
>>> 

SocketType was already present and documented in Python 2 so it should be preserved: http://docs.python.org/2/library/socket.html#socket.SocketType

Also, socket.SocketType and socket.AddressFamily names suggest they should be public but they're not mentioned in the doc.  I think they should just be private though (frankly I fail to understand why a set of constants such as AF_* and SOCK_* should be grouped in a common "container" in the first place).

Because that's the way enums work (http://docs.python.org/dev/library/enum):

>>> import socket
>>> list(socket.SocketType)
[<SocketType.SOCK_DGRAM: 2>, <SocketType.SOCK_SEQPACKET: 5>, <SocketType.SOCK_NONBLOCK: 2048>, <SocketType.SOCK_CLOEXEC: 524288>, <SocketType.SOCK_RDM: 4>, <SocketType.SOCK_STREAM: 1>, <SocketType.SOCK_RAW: 3>]
>>> list(socket.AddressFamily)
[<AddressFamily.AF_NETLINK: 16>, <AddressFamily.AF_CAN: 29>, <AddressFamily.AF_WANPIPE: 25>, <AddressFamily.AF_UNSPEC: 0>, <AddressFamily.AF_KEY: 15>, <AddressFamily.AF_PPPOX: 24>, <AddressFamily.AF_IPX: 4>, <AddressFamily.AF_UNIX: 1>, <AddressFamily.AF_IRDA: 23>, <AddressFamily.AF_SECURITY: 14>, <AddressFamily.AF_PACKET: 17>, <AddressFamily.AF_AX25: 3>, <AddressFamily.AF_APPLETALK: 5>, <AddressFamily.AF_NETROM: 6>, <AddressFamily.AF_ATMPVC: 8>, <AddressFamily.AF_SNA: 22>, <AddressFamily.AF_INET6: 10>, <AddressFamily.AF_TIPC: 30>, <AddressFamily.AF_RDS: 21>, <AddressFamily.AF_NETBEUI: 13>, <AddressFamily.AF_INET: 2>, <AddressFamily.AF_X25: 9>, <AddressFamily.AF_ECONET: 19>, <AddressFamily.AF_LLC: 26>, <AddressFamily.AF_ROSE: 11>, <AddressFamily.AF_BRIDGE: 7>, <AddressFamily.AF_ASH: 18>, <AddressFamily.AF_ATMSVC: 20>]

Marking as a docs issue, since the fact that these are now enums should be covered in the socket module docs.

Um... changing the name "socket.SocketType" from type(socket) to an enum of SOCK_ constants is not a docs issue, but a regression.

Eli, you introduced this change (inadvertently, I think, which can easily happen since SocketType is imported by "*" from _socket).  Please find a better name for the type enum and document the new enums.

Sorry, I misread Giampaolo's example as indicating that socket.SocketType wasn't there at all in Python 3.3. However, it's there, and with the same name as in Python 2, so I agree this is a regression.

I suggest socket.SocketKind as an alternate name for the enumeration that avoids the name clash, but we also need a test case that ensures that socket.SocketType has the correct value.

Here's a patch for the test.

> Please find a better name for the type enum and document the new enums.

Why should new enums be documented and how are they useful?
IMO socket module adopted enum module only to provide a better representation of AF_* and SOCK_* constants on repr(), which is fine.
The fact that in order to do that enum module forces you to create a container is incidental and should not result in polluting socket module API (which is already pretty crowded).
In summary I'd be for renaming those enums to _SocketType and _AddressFamily.

> Why should new enums be documented and how are they useful?

Because they are a new public class(-like object) in the module. When renaming them to a non-public name, as you suggest, that could be left out.

But as a user when are you gonna need to use AddressFamily container?
Before enum we didn't have something like:

AddressFamily = (AF_INET, AF_INET6, ...)

Basically because we didn't need it. Sorry if I'm missing something here.

I'm not saying the enums are necessary (argue about that with Eli), but that if they *are* in the module as a public attribute, they *have* to be documented, period.

Complete patch with new test, fixed tests, and regression fix.

Doc patch still needed.

The containers are there to help with discoverability.  If you want to know what all the (common) AF values are you can either do

    [name for name in dir(socket) if name.isupper() and name.startswith('AF_')]

or

    list(socket.AddressFamily)

Yep, the overriding of the type name was inadvertent. Nothing sacred about it, so Ethan's SocketKind is just as good.

How do we feel about SockType instead?  (Just a short round of bike-shedding, promise! ;)

I strongly prefer SocketKind - SockType is far too close to SocketType and
"type" is too closely associated with the type system in general.

Okay, staying with SocketKind.

This patch also has a very small doc enhancement.

"integer enumerations of <enumtype>" sounds weird to me.

Also, here it might be nice to link to IntEnum (use :class:`.IntEnum`).

Well, so far I have tried:

  :class:`IntEnum`
  :class:`.IntEnum`
  :class:`~IntEnum`
  :class:`enum.IntEnum`
  :class:`.enum.IntEnum`
  :class:`~enum.IntEnum`
  :class:`~.enum.IntEnum`

and probably some others I have forgotten; nothing is giving me a link to enum.IntEnum.

Any ideas?

Well, IntEnum is nowhere documented as a class.  IOW,

.. class:: IntEnum

is missing if you want these references to work.

IntEnum is not a class in the socket module.

How do I make a link into another rst document?

IntEnum is not a class in the enum module either, as far as the docs are concerned ;)

Otherwise :class:`enum.IntEnum` or :class:`.IntEnum` would work, no matter the source and target documents.

Thanks for the hints, Georg!

New changeset 613c30ffd344 by Ethan Furman in branch '3.4':
Issue20386: SocketType is again socket.socket; the IntEnum SOCK constants are SocketKind
https://hg.python.org/cpython/rev/613c30ffd344

New changeset ef24851f340f by Ethan Furman in branch 'default':
Issue20386: SocketType is again socket.socket; the IntEnum SOCK constants are SocketKind
https://hg.python.org/cpython/rev/ef24851f340f

+ self.assertTrue(socket.SocketType is _socket.socket)

You can use assertIs instead of assertTrue.

This change looks to be implicated in a buildbot breakage on koobs-freebsd9 (3.4).

I couldn't reproduce the test failure by re-running the build, so possibly intermittent or non-deterministic.

Full build log attached.

I'll leave the issue closed for now, please re-open if verified.

======================================================================
ERROR: test_pickling (test.test_multiprocessing_fork.WithProcessesTestPicklingConnections)
----------------------------------------------------------------------
Traceback (most recent call last):
  File "/usr/home/buildbot/python/3.4.koobs-freebsd9/build/Lib/test/_test_multiprocessing.py", line 2590, in test_pickling
    self.assertEqual(new_conn.recv(), msg.upper())
  File "/usr/home/buildbot/python/3.4.koobs-freebsd9/build/Lib/multiprocessing/connection.py", line 250, in recv
    buf = self._recv_bytes()
  File "/usr/home/buildbot/python/3.4.koobs-freebsd9/build/Lib/multiprocessing/connection.py", line 416, in _recv_bytes
    buf = self._recv(4)
  File "/usr/home/buildbot/python/3.4.koobs-freebsd9/build/Lib/multiprocessing/connection.py", line 389, in _recv
    raise EOFError
EOFError