Title: Document Transport.set_protocol and get_protocol
Type: enhancement Stage: resolved
Components: asyncio, Documentation Versions: Python 3.7, Python 3.6, Python 3.5
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: docs@python Nosy List: Mariatta, berker.peksag, docs@python, gvanrossum, methane, ned.deily, python-dev, vstinner, yselivanov
Priority: normal Keywords: easy, patch

Created on 2016-09-12 01:33 by yselivanov, last changed 2016-11-07 21:22 by gvanrossum. This issue is now closed.

File name Uploaded Description Edit
issue28088.patch Mariatta, 2016-10-02 00:46 review
issue28088v2.patch Mariatta, 2016-10-28 04:02 review
Messages (9)
msg277836 - (view) Author: Mariatta (Mariatta) * (Python committer) Date: 2016-10-02 00:46
Added the documentation for set_protocol and get_protocol.
msg277954 - (view) Author: Inada Naoki (methane) * (Python committer) Date: 2016-10-03 11:44

But I think adding note like following may be helpful to avoid users try
switching protocols which protocol author doesn't expect.
(I'm not good English writer.  I hope someone polish my sentence).

.. note::

   Generally speaking, switching protocols requires special knowledge
   about two protocols. For example, old protocol may have inner receive
   buffer and new protocol should take over it.
   Transport doesn't take care about such issues. Protocols should support
   switching protocol using this API.
msg279575 - (view) Author: Mariatta (Mariatta) * (Python committer) Date: 2016-10-28 04:02
I added a note like this. 

.. note::
   Switching protocol should only be done when both protocols are
   documented to support the switch.

Would this work? Would appreciate any feedback of how to properly document this behavior.

msg279576 - (view) Author: Inada Naoki (methane) * (Python committer) Date: 2016-10-28 04:06
msg279951 - (view) Author: Guido van Rossum (gvanrossum) * (Python committer) Date: 2016-11-02 21:22
LGTM too. Can someone add this to the asyncio docs (starting at the 3.5 branch please)?
msg280038 - (view) Author: Roundup Robot (python-dev) (Python triager) Date: 2016-11-04 07:35
New changeset 3f5af4a25995 by INADA Naoki in branch '3.5':
Issue #28088: Document Transport.set_protocol and get_protocol

New changeset a5e52b7be71f by INADA Naoki in branch '3.6':
Issue #28088: Document Transport.set_protocol and get_protocol.

New changeset a0299574a733 by INADA Naoki in branch 'default':
Issue #28088: Document Transport.set_protocol and get_protocol.
msg280231 - (view) Author: Roundup Robot (python-dev) (Python triager) Date: 2016-11-07 20:21
New changeset f4e86b1b051e by Berker Peksag in branch '3.5':
Issue #28088: Don't include self in method signature

New changeset f2858945c058 by Berker Peksag in branch '3.6':
Issue #28088: Merge from 3.5

New changeset 62b7614970bd by Berker Peksag in branch 'default':
Issue #28088: Merge from 3.6
msg280232 - (view) Author: Berker Peksag (berker.peksag) * (Python committer) Date: 2016-11-07 20:25
I just removed self from method signatures (we don't usually include it) and updated the versionadded directives to 3.5.3 since it was also backported to 3.5 in f12a59311885. Please let me know if got the 3.5 version wrong, thanks!
msg280246 - (view) Author: Guido van Rossum (gvanrossum) * (Python committer) Date: 2016-11-07 21:22
Good point. Thanks Berker!
Date User Action Args
2016-11-07 21:22:10gvanrossumsetmessages: + msg280246
2016-11-07 20:25:49berker.peksagsetpriority: release blocker -> normal
nosy: - larry
2016-11-07 20:25:21berker.peksagsetnosy: + larry, berker.peksag

messages: + msg280232
versions: + Python 3.5, Python 3.7
2016-11-07 20:21:42python-devsetmessages: + msg280231
2016-11-04 07:36:18methanesetstatus: open -> closed
resolution: fixed
stage: needs patch -> resolved
2016-11-04 07:35:42python-devsetnosy: + python-dev
messages: + msg280038
2016-11-02 21:22:34gvanrossumsetmessages: + msg279951
2016-10-28 04:06:45methanesetmessages: + msg279576
2016-10-28 04:02:02Mariattasetfiles: + issue28088v2.patch

messages: + msg279575
2016-10-03 11:44:50methanesetnosy: + methane
messages: + msg277954
2016-10-02 00:46:13Mariattasetfiles: + issue28088.patch
keywords: + patch
messages: + msg277836
2016-10-01 21:39:05Mariattasetnosy: + Mariatta
2016-09-12 01:34:12yselivanovsetnosy: + docs@python
assignee: docs@python
components: + Documentation
type: enhancement
stage: needs patch
2016-09-12 01:33:02yselivanovcreate