classification
Title: SSLSocket.read() not documented
Type: behavior Stage: resolved
Components: Documentation, SSL Versions: Python 3.7, Python 3.6
process
Status: closed Resolution: later
Dependencies: Superseder: SSL releated deprecation for 3.6
View: 28022
Assigned To: docs@python Nosy List: christian.heimes, docs@python, ebianchi, ezio.melotti, martin.panter, pitrou, r.david.murray
Priority: normal Keywords:

Created on 2014-02-24 17:21 by ebianchi, last changed 2017-09-05 22:53 by christian.heimes. This issue is now closed.

Messages (7)
msg212115 - (view) Author: Enrico Bianchi (ebianchi) Date: 2014-02-24 17:21
although exists, read() method isn't reported in the SSLSocket documentation. Please, fix it
msg212117 - (view) Author: R. David Murray (r.david.murray) * (Python committer) Date: 2014-02-24 17:26
That's because SSLSocket is a wrapper around a regular socket, and the read method is documented in the Socket documentation.  You will notice that *only* SSL specific methods are documented in the SSLSocket documentation.
msg212122 - (view) Author: R. David Murray (r.david.murray) * (Python committer) Date: 2014-02-24 17:30
Oops.  My mistake.  It's been too long since I did any socket programming :(
msg212124 - (view) Author: Antoine Pitrou (pitrou) * (Python committer) Date: 2014-02-24 17:35
Hmm, yeah, this is actually intended. The read() and write() methods on SSLSocket are not intended to be a public API: you should call send() or recv() instead.

Ideally we would deprecate the read() and write() methods and rename the internal helpers to _read() and _write(). Christian, what do you think?
msg275200 - (view) Author: Christian Heimes (christian.heimes) * (Python committer) Date: 2016-09-08 22:48
Sounds good, let's deprecate them with #28022.
msg275231 - (view) Author: Martin Panter (martin.panter) * (Python committer) Date: 2016-09-09 01:34
In the meantime, full documentation for the read() and write() methods was added for Python 3 in revision 61e52fda1006. The Python 2 documentation only mentions read() indirectly, in passing and in example code, and does not mention write().

But deprecating them makes sense to me. The essential functionality seems to already be available in the recv(), recv_into(), and send() or sendall() methods. The write() documentation is not clear regarding partial writes, in constrast with send() and sendall().
msg301391 - (view) Author: Christian Heimes (christian.heimes) * (Python committer) Date: 2017-09-05 22:53
I'll deprecate read() and write() in my upcoming PEP.
History
Date User Action Args
2017-09-05 22:53:58christian.heimessetstatus: open -> closed
resolution: later
messages: + msg301391

stage: needs patch -> resolved
2016-09-15 07:49:36christian.heimessetcomponents: + SSL
2016-09-09 01:34:00martin.pantersetnosy: + martin.panter
messages: + msg275231
2016-09-08 22:48:44christian.heimessetsuperseder: SSL releated deprecation for 3.6
messages: + msg275200
versions: + Python 3.6, Python 3.7, - Python 3.5
2014-02-24 19:47:22ezio.melottisetnosy: + ezio.melotti
2014-02-24 17:35:25pitrousetnosy: + christian.heimes, pitrou

messages: + msg212124
versions: + Python 3.5, - Python 3.3
2014-02-24 17:30:58r.david.murraysetstatus: closed -> open
resolution: not a bug -> (no value)
messages: + msg212122

stage: resolved -> needs patch
2014-02-24 17:26:24r.david.murraysetstatus: open -> closed

type: behavior

nosy: + r.david.murray
messages: + msg212117
resolution: not a bug
stage: resolved
2014-02-24 17:21:43ebianchicreate