From cc3146fbaca94c5381bbb9c3a52537070604665c Mon Sep 17 00:00:00 2001 From: Oleg Iarygin Date: Wed, 11 May 2022 13:58:04 +0300 Subject: [PATCH 1/3] Clarify roles of asyncio protocols and transports --- Doc/library/asyncio-protocol.rst | 24 ++++++++++++------------ 1 file changed, 12 insertions(+), 12 deletions(-) diff --git a/Doc/library/asyncio-protocol.rst b/Doc/library/asyncio-protocol.rst index 8b67f4b8957ef6..1726f984a3feb1 100644 --- a/Doc/library/asyncio-protocol.rst +++ b/Doc/library/asyncio-protocol.rst @@ -23,21 +23,21 @@ This documentation page covers both `Transports`_ and `Protocols`_. .. rubric:: Introduction -At the highest level, the transport is concerned with *how* bytes -are transmitted, while the protocol determines *which* bytes to -transmit (and to some extent when). +The transport is an interface for an asynchronous source of raw bytes, +while the protocol represents an object that feeds and consumes these bytes. -A different way of saying the same thing: a transport is an -abstraction for a socket (or similar I/O endpoint) while a protocol -is an abstraction for an application, from the transport's point -of view. +The protocol object may either generate and consume data by its own (like a +fallback background sender behind :func:`~asyncio.loop.sendfile`), be an +adapter for another I/O interface (like the +:func:`~asyncio.StreamReader`/:func:`~asyncio.StreamWriter` backend), +or play a role of a converter middle man between other transport and protocol +(like the one created by :func:`~asyncio.loop.start_tls`). -Yet another view is the transport and protocol interfaces -together define an abstract interface for using network I/O and -interprocess I/O. +While the transport is actively puppeteered by an asyncio event loop, the +protocol . -There is always a 1:1 relationship between transport and protocol -objects: the protocol calls transport methods to send data, +There is always a 1:1 relationship between immediately communicating transport +and protocol objects: the protocol calls transport methods to send data, while the transport calls protocol methods to pass it data that has been received. From 4e8479fe04b4758aa0c11d1fd6b9f1eea6041684 Mon Sep 17 00:00:00 2001 From: Oleg Iarygin Date: Wed, 11 May 2022 21:36:52 +0300 Subject: [PATCH 2/3] Fix: Transport and Protocol have no asyncio methods --- Doc/library/asyncio-protocol.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/Doc/library/asyncio-protocol.rst b/Doc/library/asyncio-protocol.rst index 1726f984a3feb1..01c3e03d2ddc4c 100644 --- a/Doc/library/asyncio-protocol.rst +++ b/Doc/library/asyncio-protocol.rst @@ -23,8 +23,8 @@ This documentation page covers both `Transports`_ and `Protocols`_. .. rubric:: Introduction -The transport is an interface for an asynchronous source of raw bytes, -while the protocol represents an object that feeds and consumes these bytes. +The transport is an interface for a closable source of raw bytes, +while the protocol represents a consumer of these bytes that may answer back. The protocol object may either generate and consume data by its own (like a fallback background sender behind :func:`~asyncio.loop.sendfile`), be an @@ -34,7 +34,7 @@ or play a role of a converter middle man between other transport and protocol (like the one created by :func:`~asyncio.loop.start_tls`). While the transport is actively puppeteered by an asyncio event loop, the -protocol . +protocol is passively triggered by events from the transport. There is always a 1:1 relationship between immediately communicating transport and protocol objects: the protocol calls transport methods to send data, From eb57bb69ffefcd4af6f49bfe37da813238e0f25e Mon Sep 17 00:00:00 2001 From: Oleg Iarygin Date: Fri, 25 Nov 2022 19:45:31 +0300 Subject: [PATCH 3/3] Apply suggestions from code review Co-authored-by: Guido van Rossum --- Doc/library/asyncio-protocol.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/Doc/library/asyncio-protocol.rst b/Doc/library/asyncio-protocol.rst index 51450915e84a0f..bf7f54528c25a0 100644 --- a/Doc/library/asyncio-protocol.rst +++ b/Doc/library/asyncio-protocol.rst @@ -23,10 +23,10 @@ This documentation page covers both `Transports`_ and `Protocols`_. .. rubric:: Introduction -The transport is an interface for a closable source of raw bytes, +The transport is an interface for a source of raw bytes, while the protocol represents a consumer of these bytes that may answer back. -The protocol object may either generate and consume data by its own (like a +The protocol object may either generate and consume data on its own (like a fallback background sender behind :func:`~asyncio.loop.sendfile`), be an adapter for another I/O interface (like the :func:`~asyncio.StreamReader`/:func:`~asyncio.StreamWriter` backend),