[issue24911] Context manager of socket.socket is not documented
New submission from zodalahtathi: socket.socket has a context manager to automatically close the socket with the `with` statement: https://hg.python.org/cpython/file/d1bf181afa82/Lib/socket.py#l138 However it is not documented, unlike socket.create_connection. ---------- assignee: docs@python components: Documentation messages: 248979 nosy: docs@python, zodalahtathi priority: normal severity: normal status: open title: Context manager of socket.socket is not documented versions: Python 3.4 _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue24911> _______________________________________
Changes by Berker Peksag <berker.peksag@gmail.com>: ---------- keywords: +easy stage: -> needs patch type: -> enhancement versions: +Python 3.5, Python 3.6 _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue24911> _______________________________________
Martin Panter added the comment: IMO the change notice for create_connection() should be moved to apply to the “socket” class, perhaps the “Socket Objects” section. Issue 9794 looks like context manager support was added specifically for create_connection(), however any socket object, no matter what function is used to create it, should be usable the same way for free. Also, we should explicitly document that exiting the context manager (“with” statement) invokes close(), since that affects how the underlying socket is closed when makefile() has been used. ---------- nosy: +martin.panter _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue24911> _______________________________________
Martin Panter added the comment: Here is my proposed patch ---------- keywords: +patch stage: needs patch -> patch review Added file: http://bugs.python.org/file40307/socket-context.patch _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue24911> _______________________________________
Berker Peksag added the comment: socket-context.patch looks good to me. There is no need to add a NEWS entry for this. ---------- nosy: +berker.peksag stage: patch review -> commit review versions: -Python 3.4 _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue24911> _______________________________________
Yury Selivanov added the comment: The patch looks good. It would also be cool if you can add a short code snippet somewhere: sock = socket.socket() with sock: sock.bind(('127.0.0.1', 8080)) sock.listen() ... ---------- nosy: +yselivanov _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue24911> _______________________________________
STINNER Victor added the comment: I reviewed the patch.
It would also be cool if you can add a short code snippet somewhere:
The socket module has examples. Why not modifying these examples to promote the context manager protocol? Example: -------- s = socket.socket(socket.AF_INET, socket.SOCK_STREAM) as s # use with to ensure that the socket is closed, especially on error with s: s.bind((HOST, PORT)) s.listen(1) conn, addr = s.accept() with conn: print('Connected by', addr) while True: data = conn.recv(1024) if not data: break conn.sendall(data) conn.close() -------- The second "with conn:" is maybe overkill. What do you think? For a client connection, usually I prefer to explicitly close the socket (even if I use "with conn:") to get exception on my ".close()" line, instead of getting an exception from the context manager, which is harder to understand. ---------- nosy: +haypo _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue24911> _______________________________________
Martin Panter added the comment: Thanks for the reviews. In this new patch, I modified two existing examples, but did not add any new example. Does that work for you Yury? Also modified example code for the socketserver module. Victor: IMO the “with conn” in the example is not overkill. It ensures the client connection socket is cleaned up, which is completely independent of the server listening socket s. What exceptions can you get out of conn.close()? I can only think of unusual programming errors like EBADF. I would prefer to remove close() as being redundant with the context manager. ---------- Added file: http://bugs.python.org/file41943/socket-context.v2.patch _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue24911> _______________________________________
Martin Panter added the comment: FWIW I discovered that socket.close() or __exit__() does not actually raise exceptions for cases like EBADF, see Issue 26685. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue24911> _______________________________________
Roundup Robot added the comment: New changeset d5f7980dd654 by Martin Panter in branch '3.5': Issue #24911: All socket objects are context managers; update examples https://hg.python.org/cpython/rev/d5f7980dd654 New changeset 711201953505 by Martin Panter in branch 'default': Issue #24911: Merge socket context manager doc from 3.5 https://hg.python.org/cpython/rev/711201953505 ---------- nosy: +python-dev _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue24911> _______________________________________
Changes by Martin Panter <vadmium+py@gmail.com>: ---------- resolution: -> fixed stage: commit review -> resolved status: open -> closed _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue24911> _______________________________________
participants (6)
-
Berker Peksag -
Martin Panter
-
Roundup Robot
-
STINNER Victor
-
Yury Selivanov
-
zodalahtathi