classification
Title: socket.SocketType enum overwrites import of _socket.SocketType
Type: behavior Stage: resolved
Components: Library (Lib) Versions: Python 3.4, Python 3.5
process
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: eli.bendersky Nosy List: berker.peksag, docs@python, eli.bendersky, ethan.furman, georg.brandl, giampaolo.rodola, koobs, ncoghlan, python-dev
Priority: high Keywords: 3.4regression, patch

Created on 2014-01-24 22:48 by giampaolo.rodola, last changed 2014-10-15 10:20 by koobs. This issue is now closed.

Files
File name Uploaded Description Edit
issue20386.stoneleaf.test.patch.01 ethan.furman, 2014-01-25 19:50 review
issue20386.stoneleaf.patch.02 ethan.furman, 2014-01-25 20:35 review
issue20386.stoneleaf.03.patch ethan.furman, 2014-01-26 21:47 review
issue20386.stoneleaf.04.patch ethan.furman, 2014-02-06 16:25 review
koobs-freebsd9-py34-build-553.txt koobs, 2014-10-15 10:20
Messages (24)
msg209134 - (view) Author: Giampaolo Rodola' (giampaolo.rodola) * (Python committer) Date: 2014-01-24 22:48
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).
msg209158 - (view) Author: Nick Coghlan (ncoghlan) * (Python committer) Date: 2014-01-25 07:01
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.
msg209161 - (view) Author: Georg Brandl (georg.brandl) * (Python committer) Date: 2014-01-25 07:45
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.
msg209162 - (view) Author: Nick Coghlan (ncoghlan) * (Python committer) Date: 2014-01-25 07:49
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.
msg209231 - (view) Author: Ethan Furman (ethan.furman) * (Python committer) Date: 2014-01-25 19:50
Here's a patch for the test.
msg209232 - (view) Author: Giampaolo Rodola' (giampaolo.rodola) * (Python committer) Date: 2014-01-25 20:00
> 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.
msg209233 - (view) Author: Georg Brandl (georg.brandl) * (Python committer) Date: 2014-01-25 20:10
> 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.
msg209234 - (view) Author: Giampaolo Rodola' (giampaolo.rodola) * (Python committer) Date: 2014-01-25 20:20
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.
msg209235 - (view) Author: Georg Brandl (georg.brandl) * (Python committer) Date: 2014-01-25 20:33
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.
msg209236 - (view) Author: Ethan Furman (ethan.furman) * (Python committer) Date: 2014-01-25 20:35
Complete patch with new test, fixed tests, and regression fix.

Doc patch still needed.
msg209237 - (view) Author: Ethan Furman (ethan.furman) * (Python committer) Date: 2014-01-25 20:40
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)
msg209240 - (view) Author: Eli Bendersky (eli.bendersky) * (Python committer) Date: 2014-01-25 21:42
Yep, the overriding of the type name was inadvertent. Nothing sacred about it, so Ethan's SocketKind is just as good.
msg209244 - (view) Author: Ethan Furman (ethan.furman) * (Python committer) Date: 2014-01-25 22:07
How do we feel about SockType instead?  (Just a short round of bike-shedding, promise! ;)
msg209262 - (view) Author: Nick Coghlan (ncoghlan) * (Python committer) Date: 2014-01-26 00:43
I strongly prefer SocketKind - SockType is far too close to SocketType and
"type" is too closely associated with the type system in general.
msg209353 - (view) Author: Ethan Furman (ethan.furman) * (Python committer) Date: 2014-01-26 21:47
Okay, staying with SocketKind.

This patch also has a very small doc enhancement.
msg209401 - (view) Author: Georg Brandl (georg.brandl) * (Python committer) Date: 2014-01-27 06:15
"integer enumerations of <enumtype>" sounds weird to me.

Also, here it might be nice to link to IntEnum (use :class:`.IntEnum`).
msg209461 - (view) Author: Ethan Furman (ethan.furman) * (Python committer) Date: 2014-01-27 19:15
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?
msg209463 - (view) Author: Georg Brandl (georg.brandl) * (Python committer) Date: 2014-01-27 19:20
Well, IntEnum is nowhere documented as a class.  IOW,

.. class:: IntEnum

is missing if you want these references to work.
msg209468 - (view) Author: Ethan Furman (ethan.furman) * (Python committer) Date: 2014-01-27 19:33
IntEnum is not a class in the socket module.

How do I make a link into another rst document?
msg209473 - (view) Author: Georg Brandl (georg.brandl) * (Python committer) Date: 2014-01-27 20:28
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.
msg210407 - (view) Author: Ethan Furman (ethan.furman) * (Python committer) Date: 2014-02-06 16:25
Thanks for the hints, Georg!
msg229394 - (view) Author: Roundup Robot (python-dev) (Python triager) Date: 2014-10-15 01:58
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
msg229418 - (view) Author: Berker Peksag (berker.peksag) * (Python committer) Date: 2014-10-15 08:56
+ self.assertTrue(socket.SocketType is _socket.socket)

You can use assertIs instead of assertTrue.
msg229429 - (view) Author: Kubilay Kocak (koobs) (Python triager) Date: 2014-10-15 10:20
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
History
Date User Action Args
2014-10-15 10:20:34koobssetfiles: + koobs-freebsd9-py34-build-553.txt
nosy: + koobs
messages: + msg229429

2014-10-15 08:56:15berker.peksagsetnosy: + berker.peksag

messages: + msg229418
versions: + Python 3.5
2014-10-15 02:02:05ethan.furmansetstatus: open -> closed
resolution: fixed
stage: patch review -> resolved
2014-10-15 01:58:18python-devsetnosy: + python-dev
messages: + msg229394
2014-02-06 16:25:41ethan.furmansetfiles: + issue20386.stoneleaf.04.patch

messages: + msg210407
2014-01-27 20:28:14georg.brandlsetmessages: + msg209473
2014-01-27 19:33:11ethan.furmansetmessages: + msg209468
2014-01-27 19:20:41georg.brandlsetmessages: + msg209463
2014-01-27 19:15:32ethan.furmansetmessages: + msg209461
2014-01-27 06:15:22georg.brandlsetmessages: + msg209401
2014-01-26 21:47:22ethan.furmansetfiles: + issue20386.stoneleaf.03.patch
keywords: + patch
messages: + msg209353
2014-01-26 00:43:25ncoghlansetmessages: + msg209262
2014-01-25 22:07:28ethan.furmansetmessages: + msg209244
2014-01-25 21:42:46eli.benderskysetmessages: + msg209240
2014-01-25 20:40:35ethan.furmansetmessages: + msg209237
2014-01-25 20:35:23ethan.furmansetfiles: + issue20386.stoneleaf.patch.02

messages: + msg209236
stage: test needed -> patch review
2014-01-25 20:33:59georg.brandlsetmessages: + msg209235
2014-01-25 20:20:33giampaolo.rodolasetmessages: + msg209234
2014-01-25 20:10:54georg.brandlsetmessages: + msg209233
2014-01-25 20:00:28giampaolo.rodolasetmessages: + msg209232
2014-01-25 19:50:10ethan.furmansetfiles: + issue20386.stoneleaf.test.patch.01

messages: + msg209231
2014-01-25 07:52:28ncoghlansettitle: Missing docs for SocketType and AddressFamily in socket module -> socket.SocketType enum overwrites import of _socket.SocketType
2014-01-25 07:49:18ncoghlansetmessages: + msg209162

components: + Library (Lib), - Documentation
keywords: + 3.4regression
type: enhancement -> behavior
stage: needs patch -> test needed
2014-01-25 07:45:36georg.brandlsetpriority: normal -> high

nosy: + eli.bendersky, georg.brandl
messages: + msg209161

assignee: docs@python -> eli.bendersky
2014-01-25 07:01:22ncoghlansetassignee: docs@python
type: enhancement
components: + Documentation
title: socket.SocketType is different in Python 3.4 -> Missing docs for SocketType and AddressFamily in socket module
nosy: + docs@python, ethan.furman, ncoghlan

messages: + msg209158
stage: needs patch
2014-01-24 22:48:21giampaolo.rodolacreate