From ab3fbfad63ef4fd0de833df6374fbb6b2d9b8938 Mon Sep 17 00:00:00 2001 From: Francis CLAIRICIA-ROSE-CLAIRE-JOSEPHINE Date: Fri, 28 Jun 2024 15:31:30 +0200 Subject: [PATCH] Documentation: Rewritten all docstrings --- .../request_handler_explanation.py | 1 + .../tutorials/ftp_server/ftp_request.py | 2 +- .../see-also-optional-dependencies.rst | 4 --- docs/source/api/clients/index.rst | 28 ++++++----------- docs/source/api/lowlevel/async/backend.rst | 11 ++++++- docs/source/api/lowlevel/async/endpoints.rst | 9 ++++-- docs/source/api/lowlevel/async/servers.rst | 20 ++++++++---- docs/source/api/lowlevel/async/transports.rst | 10 ++++-- docs/source/api/lowlevel/futures.rst | 5 --- docs/source/api/lowlevel/sync/endpoints.rst | 9 ++++-- docs/source/api/lowlevel/sync/transports.rst | 10 ++++-- docs/source/api/serializers/abc.rst | 4 --- docs/source/api/serializers/cbor.rst | 8 +---- docs/source/api/serializers/json.rst | 4 +-- docs/source/api/serializers/line.rst | 2 +- docs/source/api/serializers/msgpack.rst | 8 +---- docs/source/api/serializers/pickle.rst | 4 +-- docs/source/api/serializers/struct.rst | 6 ++-- docs/source/api/serializers/tools.rst | 1 - .../api/serializers/wrappers/base64.rst | 2 +- .../api/serializers/wrappers/compressor.rst | 4 +-- docs/source/api/servers/index.rst | 30 ++++++------------ docs/source/conf.py | 16 +++++++--- .../howto/advanced/standalone_servers.rst | 2 ++ docs/source/howto/serializers.rst | 2 +- docs/source/howto/udp_servers.rst | 2 +- docs/source/quickstart/install.rst | 7 +---- src/easynetwork/_typevars.py | 5 +-- src/easynetwork/clients/__init__.py | 2 +- src/easynetwork/clients/abc.py | 2 +- src/easynetwork/clients/async_tcp.py | 10 +++--- src/easynetwork/clients/async_udp.py | 10 +++--- src/easynetwork/clients/tcp.py | 2 +- src/easynetwork/clients/udp.py | 2 +- src/easynetwork/converter.py | 2 +- src/easynetwork/exceptions.py | 2 +- src/easynetwork/lowlevel/__init__.py | 2 +- src/easynetwork/lowlevel/_asyncgen.py | 2 +- src/easynetwork/lowlevel/_stream.py | 2 +- .../lowlevel/api_async/__init__.py | 2 +- .../lowlevel/api_async/backend/__init__.py | 2 +- .../api_async/backend/_sniffio_helpers.py | 2 +- .../lowlevel/api_async/backend/abc.py | 2 +- .../lowlevel/api_async/backend/utils.py | 31 +++++++++++++++---- .../lowlevel/api_async/endpoints/__init__.py | 2 +- .../lowlevel/api_async/endpoints/datagram.py | 2 +- .../lowlevel/api_async/endpoints/stream.py | 2 +- .../lowlevel/api_async/servers/__init__.py | 2 +- .../lowlevel/api_async/servers/datagram.py | 6 ++-- .../lowlevel/api_async/servers/stream.py | 12 +++---- .../lowlevel/api_async/transports/__init__.py | 2 +- .../lowlevel/api_async/transports/abc.py | 2 +- .../lowlevel/api_async/transports/tls.py | 12 +++++-- .../lowlevel/api_async/transports/utils.py | 2 +- src/easynetwork/lowlevel/api_sync/__init__.py | 2 +- .../lowlevel/api_sync/endpoints/__init__.py | 2 +- .../lowlevel/api_sync/endpoints/datagram.py | 2 +- .../lowlevel/api_sync/endpoints/stream.py | 2 +- .../lowlevel/api_sync/transports/__init__.py | 2 +- .../lowlevel/api_sync/transports/abc.py | 2 +- .../api_sync/transports/base_selector.py | 9 ++++-- .../lowlevel/api_sync/transports/socket.py | 2 +- src/easynetwork/lowlevel/constants.py | 2 +- src/easynetwork/lowlevel/futures.py | 6 ++-- src/easynetwork/lowlevel/socket.py | 9 +++--- src/easynetwork/protocol.py | 2 +- src/easynetwork/serializers/__init__.py | 2 +- src/easynetwork/serializers/abc.py | 2 +- src/easynetwork/serializers/base_stream.py | 5 ++- src/easynetwork/serializers/cbor.py | 10 +++++- src/easynetwork/serializers/json.py | 2 +- src/easynetwork/serializers/line.py | 2 +- src/easynetwork/serializers/msgpack.py | 10 +++++- src/easynetwork/serializers/pickle.py | 2 +- src/easynetwork/serializers/struct.py | 2 +- src/easynetwork/serializers/tools.py | 2 +- .../serializers/wrapper/__init__.py | 2 +- src/easynetwork/serializers/wrapper/base64.py | 2 +- .../serializers/wrapper/compressor.py | 2 +- src/easynetwork/servers/__init__.py | 2 +- src/easynetwork/servers/_base.py | 6 ++-- src/easynetwork/servers/abc.py | 2 +- src/easynetwork/servers/async_tcp.py | 12 +++---- src/easynetwork/servers/async_udp.py | 6 ++-- src/easynetwork/servers/handlers.py | 2 +- src/easynetwork/servers/misc.py | 12 +++---- src/easynetwork/servers/standalone_tcp.py | 6 ++-- src/easynetwork/servers/standalone_udp.py | 6 ++-- src/easynetwork/servers/threads_helper.py | 4 +-- .../test_servers/test_stream.py | 16 +++++----- 90 files changed, 265 insertions(+), 233 deletions(-) delete mode 100644 docs/source/_include/see-also-optional-dependencies.rst diff --git a/docs/source/_include/examples/howto/udp_servers/request_handler_explanation.py b/docs/source/_include/examples/howto/udp_servers/request_handler_explanation.py index a8e6b529..e5be0ea0 100644 --- a/docs/source/_include/examples/howto/udp_servers/request_handler_explanation.py +++ b/docs/source/_include/examples/howto/udp_servers/request_handler_explanation.py @@ -145,6 +145,7 @@ async def handle( ) -> AsyncGenerator[float | None, Request]: # It is *never* useful to have a timeout for the 1st datagram # because the datagram is already in the queue. + # The yielded value is simply ignored. request: Request = yield None ... diff --git a/docs/source/_include/examples/tutorials/ftp_server/ftp_request.py b/docs/source/_include/examples/tutorials/ftp_server/ftp_request.py index e118e648..406d7603 100644 --- a/docs/source/_include/examples/tutorials/ftp_server/ftp_request.py +++ b/docs/source/_include/examples/tutorials/ftp_server/ftp_request.py @@ -8,7 +8,7 @@ @dataclass(frozen=True, match_args=True) class FTPRequest: - """Dataclass defining an FTP request""" + """Dataclass defining an FTP request.""" command: FTPCommand """Command name.""" diff --git a/docs/source/_include/see-also-optional-dependencies.rst b/docs/source/_include/see-also-optional-dependencies.rst deleted file mode 100644 index d2ea862f..00000000 --- a/docs/source/_include/see-also-optional-dependencies.rst +++ /dev/null @@ -1,4 +0,0 @@ -.. seealso:: - - :ref:`optional-dependencies` - Explains how to install required dependencies. diff --git a/docs/source/api/clients/index.rst b/docs/source/api/clients/index.rst index 70e6f2ba..5150019b 100644 --- a/docs/source/api/clients/index.rst +++ b/docs/source/api/clients/index.rst @@ -9,28 +9,28 @@ Clients API ------ -Asynchronous Client Objects (``async def``) -=========================================== - -Abstract Base Class -------------------- +Abstract Base Classes +===================== -.. autoclass:: easynetwork.clients.abc::AbstractAsyncNetworkClient +.. automodule:: easynetwork.clients.abc :members: :special-members: __aenter__, __aexit__ +Asynchronous Client Objects (``async def``) +=========================================== + TCP Implementation ------------------ -.. autoclass:: AsyncTCPNetworkClient +.. automodule:: easynetwork.clients.async_tcp :members: :inherited-members: UDP Implementation ------------------ -.. autoclass:: AsyncUDPNetworkClient +.. automodule:: easynetwork.clients.async_udp :members: :inherited-members: @@ -38,24 +38,16 @@ UDP Implementation Synchronous Client Objects ========================== -Abstract Base Class -------------------- - -.. autoclass:: easynetwork.clients.abc::AbstractNetworkClient - :members: - :special-members: __enter__, __exit__ - - TCP Implementation ------------------ -.. autoclass:: TCPNetworkClient +.. automodule:: easynetwork.clients.tcp :members: :inherited-members: UDP Implementation ------------------ -.. autoclass:: UDPNetworkClient +.. automodule:: easynetwork.clients.udp :members: :inherited-members: diff --git a/docs/source/api/lowlevel/async/backend.rst b/docs/source/api/lowlevel/async/backend.rst index 03cceb25..5928d800 100644 --- a/docs/source/api/lowlevel/async/backend.rst +++ b/docs/source/api/lowlevel/async/backend.rst @@ -2,6 +2,8 @@ Asynchronous Backend Engine API ******************************* +.. automodule:: easynetwork.lowlevel.api_async.backend + .. contents:: Table of Contents :local: :depth: 1 @@ -20,7 +22,6 @@ Backend Interface ================= .. automodule:: easynetwork.lowlevel.api_async.backend.abc - :no-docstring: .. autoclass:: AsyncBackend @@ -158,3 +159,11 @@ Scheduling From Other Threads .. autoclass:: ThreadsPortal :members: :special-members: __aenter__, __aexit__ + + +Useful tools +============ + +.. automodule:: easynetwork.lowlevel.api_async.backend.utils + :no-docstring: + :members: diff --git a/docs/source/api/lowlevel/async/endpoints.rst b/docs/source/api/lowlevel/async/endpoints.rst index 8fb6ee93..76e8c399 100644 --- a/docs/source/api/lowlevel/async/endpoints.rst +++ b/docs/source/api/lowlevel/async/endpoints.rst @@ -2,16 +2,21 @@ Generic Endpoints ***************** +.. automodule:: easynetwork.lowlevel.api_async.endpoints + +.. contents:: Table of Contents + :local: + +------ + Stream Endpoints ================ .. automodule:: easynetwork.lowlevel.api_async.endpoints.stream :members: - :no-docstring: Datagram Endpoints ================== .. automodule:: easynetwork.lowlevel.api_async.endpoints.datagram :members: - :no-docstring: diff --git a/docs/source/api/lowlevel/async/servers.rst b/docs/source/api/lowlevel/async/servers.rst index 1bb65c22..4a02c71e 100644 --- a/docs/source/api/lowlevel/async/servers.rst +++ b/docs/source/api/lowlevel/async/servers.rst @@ -2,24 +2,32 @@ Generic Servers *************** +.. automodule:: easynetwork.lowlevel.api_async.servers + +.. contents:: Table of Contents + :local: + +------ + Stream Servers ============== .. automodule:: easynetwork.lowlevel.api_async.servers.stream :members: - :no-docstring: -.. autoclass:: easynetwork.lowlevel.api_async.servers.stream::Client() +.. autoclass:: ConnectedStreamClient() + :no-index: :members: - :exclude-members: __init__ + Datagram Servers ================ .. automodule:: easynetwork.lowlevel.api_async.servers.datagram :members: - :no-docstring: -.. autoclass:: easynetwork.lowlevel.api_async.servers.datagram::DatagramClientContext() +.. autotypevar:: easynetwork.lowlevel.api_async.servers.datagram::_T_Address + +.. autoclass:: DatagramClientContext() + :no-index: :members: - :exclude-members: __init__ diff --git a/docs/source/api/lowlevel/async/transports.rst b/docs/source/api/lowlevel/async/transports.rst index 3b680518..4253c473 100644 --- a/docs/source/api/lowlevel/async/transports.rst +++ b/docs/source/api/lowlevel/async/transports.rst @@ -2,20 +2,25 @@ Data Transport Adapters *********************** +.. automodule:: easynetwork.lowlevel.api_async.transports + +.. contents:: Table of Contents + :local: + +------ + Abstract Base Classes ===================== .. automodule:: easynetwork.lowlevel.api_async.transports.abc :members: :special-members: __aenter__, __aexit__ - :no-docstring: SSL/TLS Support =============== .. automodule:: easynetwork.lowlevel.api_async.transports.tls :members: - :no-docstring: Miscellaneous @@ -23,4 +28,3 @@ Miscellaneous .. automodule:: easynetwork.lowlevel.api_async.transports.utils :members: - :no-docstring: diff --git a/docs/source/api/lowlevel/futures.rst b/docs/source/api/lowlevel/futures.rst index 38f1375b..b1725a48 100644 --- a/docs/source/api/lowlevel/futures.rst +++ b/docs/source/api/lowlevel/futures.rst @@ -3,10 +3,5 @@ Concurrency And Multithreading (``concurrent.futures`` Integration) ******************************************************************* .. automodule:: easynetwork.lowlevel.futures - :no-docstring: - -.. autoclass:: AsyncExecutor :members: :special-members: __aenter__, __aexit__ - -.. autofunction:: unwrap_future diff --git a/docs/source/api/lowlevel/sync/endpoints.rst b/docs/source/api/lowlevel/sync/endpoints.rst index 08eefebd..98d08885 100644 --- a/docs/source/api/lowlevel/sync/endpoints.rst +++ b/docs/source/api/lowlevel/sync/endpoints.rst @@ -2,16 +2,21 @@ Generic Endpoints ***************** +.. automodule:: easynetwork.lowlevel.api_sync.endpoints + +.. contents:: Table of Contents + :local: + +------ + Stream Endpoints ================ .. automodule:: easynetwork.lowlevel.api_sync.endpoints.stream :members: - :no-docstring: Datagram Endpoints ================== .. automodule:: easynetwork.lowlevel.api_sync.endpoints.datagram :members: - :no-docstring: diff --git a/docs/source/api/lowlevel/sync/transports.rst b/docs/source/api/lowlevel/sync/transports.rst index 645c7650..e83f392e 100644 --- a/docs/source/api/lowlevel/sync/transports.rst +++ b/docs/source/api/lowlevel/sync/transports.rst @@ -2,13 +2,19 @@ Data Transport Adapters *********************** +.. automodule:: easynetwork.lowlevel.api_sync.transports + +.. contents:: Table of Contents + :local: + +------ + Abstract Base Classes ===================== .. automodule:: easynetwork.lowlevel.api_sync.transports.abc :members: :special-members: __enter__, __exit__ - :no-docstring: ``selectors``-based transports ============================== @@ -20,11 +26,9 @@ Abstract Base Classes .. automodule:: easynetwork.lowlevel.api_sync.transports.base_selector :members: - :no-docstring: Socket Transport Implementations ================================ .. automodule:: easynetwork.lowlevel.api_sync.transports.socket :members: - :no-docstring: diff --git a/docs/source/api/serializers/abc.rst b/docs/source/api/serializers/abc.rst index 6fdf5ce2..b38c2334 100644 --- a/docs/source/api/serializers/abc.rst +++ b/docs/source/api/serializers/abc.rst @@ -11,7 +11,6 @@ Top-Level Base Classes ====================== .. automodule:: easynetwork.serializers.abc - :no-docstring: :members: @@ -20,8 +19,5 @@ Top-Level Base Classes Stream Base Classes =================== -Here are abstract classes that implement common stream protocol patterns. - .. automodule:: easynetwork.serializers.base_stream - :no-docstring: :members: diff --git a/docs/source/api/serializers/cbor.rst b/docs/source/api/serializers/cbor.rst index 7e7aa7b4..b553e897 100644 --- a/docs/source/api/serializers/cbor.rst +++ b/docs/source/api/serializers/cbor.rst @@ -2,11 +2,7 @@ CBOR Serializer *************** -.. currentmodule:: easynetwork.serializers - -The `CBOR `_ is an alternative representation of the ``JSON`` data models. - -.. include:: ../../_include/see-also-optional-dependencies.rst +.. automodule:: easynetwork.serializers.cbor .. autoclass:: CBORSerializer :members: @@ -14,8 +10,6 @@ The `CBOR `_ is an alternative representation of the ``JSON`` d Configuration ============= -.. currentmodule:: easynetwork.serializers.cbor - .. autoclass:: CBOREncoderConfig :members: diff --git a/docs/source/api/serializers/json.rst b/docs/source/api/serializers/json.rst index db3cd3fe..8ac3774c 100644 --- a/docs/source/api/serializers/json.rst +++ b/docs/source/api/serializers/json.rst @@ -2,7 +2,7 @@ JSON Serializer *************** -.. currentmodule:: easynetwork.serializers +.. automodule:: easynetwork.serializers.json .. autoclass:: JSONSerializer :members: @@ -10,8 +10,6 @@ JSON Serializer Configuration ============= -.. currentmodule:: easynetwork.serializers.json - .. autoclass:: JSONEncoderConfig :members: diff --git a/docs/source/api/serializers/line.rst b/docs/source/api/serializers/line.rst index 946cf82a..4c699103 100644 --- a/docs/source/api/serializers/line.rst +++ b/docs/source/api/serializers/line.rst @@ -2,7 +2,7 @@ String Serializer ***************** -.. currentmodule:: easynetwork.serializers +.. automodule:: easynetwork.serializers.line .. autoclass:: StringLineSerializer :members: diff --git a/docs/source/api/serializers/msgpack.rst b/docs/source/api/serializers/msgpack.rst index 629a9cbb..1b667986 100644 --- a/docs/source/api/serializers/msgpack.rst +++ b/docs/source/api/serializers/msgpack.rst @@ -2,11 +2,7 @@ MessagePack Serializer ********************** -.. currentmodule:: easynetwork.serializers - -The `MessagePack `_ is an alternative representation of the ``JSON`` data models. - -.. include:: ../../_include/see-also-optional-dependencies.rst +.. automodule:: easynetwork.serializers.msgpack .. autoclass:: MessagePackSerializer :members: @@ -14,8 +10,6 @@ The `MessagePack `_ is an alternative representation of th Configuration ============= -.. currentmodule:: easynetwork.serializers.msgpack - .. autoclass:: MessagePackerConfig :members: diff --git a/docs/source/api/serializers/pickle.rst b/docs/source/api/serializers/pickle.rst index 78e73f28..671d2c05 100644 --- a/docs/source/api/serializers/pickle.rst +++ b/docs/source/api/serializers/pickle.rst @@ -2,7 +2,7 @@ Pickle Serializer ***************** -.. currentmodule:: easynetwork.serializers +.. automodule:: easynetwork.serializers.pickle .. warning:: @@ -18,8 +18,6 @@ Pickle Serializer Configuration ============= -.. currentmodule:: easynetwork.serializers.pickle - .. autoclass:: PicklerConfig :members: diff --git a/docs/source/api/serializers/struct.rst b/docs/source/api/serializers/struct.rst index c6b39aa1..948e1660 100644 --- a/docs/source/api/serializers/struct.rst +++ b/docs/source/api/serializers/struct.rst @@ -2,12 +2,12 @@ Structure Serializer ******************** -.. currentmodule:: easynetwork.serializers +.. automodule:: easynetwork.serializers.struct .. autoclass:: StructSerializer :members: -.. autotypevar:: easynetwork.serializers.struct::_T_NamedTuple +.. autotypevar:: _T_NamedTuple :noindex: .. autoclass:: NamedTupleStructSerializer @@ -16,7 +16,5 @@ Structure Serializer Abstract Structure Interface ============================ -.. currentmodule:: easynetwork.serializers.struct - .. autoclass:: AbstractStructSerializer :members: diff --git a/docs/source/api/serializers/tools.rst b/docs/source/api/serializers/tools.rst index 39bdb70b..4591e0f0 100644 --- a/docs/source/api/serializers/tools.rst +++ b/docs/source/api/serializers/tools.rst @@ -4,4 +4,3 @@ Serializer implementation tools .. automodule:: easynetwork.serializers.tools :members: - :no-docstring: diff --git a/docs/source/api/serializers/wrappers/base64.rst b/docs/source/api/serializers/wrappers/base64.rst index a1a1a0b7..1b40c422 100644 --- a/docs/source/api/serializers/wrappers/base64.rst +++ b/docs/source/api/serializers/wrappers/base64.rst @@ -2,7 +2,7 @@ Base64 Encoder Serializer ************************* -.. currentmodule:: easynetwork.serializers.wrapper +.. automodule:: easynetwork.serializers.wrapper.base64 .. autoclass:: Base64EncoderSerializer :members: diff --git a/docs/source/api/serializers/wrappers/compressor.rst b/docs/source/api/serializers/wrappers/compressor.rst index 734e2792..94a94255 100644 --- a/docs/source/api/serializers/wrappers/compressor.rst +++ b/docs/source/api/serializers/wrappers/compressor.rst @@ -2,7 +2,7 @@ Compressor Serializers ********************** -.. currentmodule:: easynetwork.serializers.wrapper +.. automodule:: easynetwork.serializers.wrapper.compressor .. autoclass:: BZ2CompressorSerializer :members: @@ -14,8 +14,6 @@ Compressor Serializers Abstract Compressor Interface ============================= -.. currentmodule:: easynetwork.serializers.wrapper.compressor - .. autoclass:: AbstractCompressorSerializer :members: diff --git a/docs/source/api/servers/index.rst b/docs/source/api/servers/index.rst index 6232406d..8e2acedb 100644 --- a/docs/source/api/servers/index.rst +++ b/docs/source/api/servers/index.rst @@ -9,30 +9,28 @@ Servers API ------ -Asynchronous Server Objects (``async def``) -=========================================== - -Abstract Base Class -------------------- +Abstract Base Classes +===================== -.. autoclass:: easynetwork.servers.abc::AbstractAsyncNetworkServer +.. automodule:: easynetwork.servers.abc :members: :special-members: __aenter__, __aexit__ -.. autoprotocol:: easynetwork.servers.abc::SupportsEventSet +Asynchronous Server Objects (``async def``) +=========================================== TCP Implementation ------------------ -.. autoclass:: AsyncTCPNetworkServer +.. automodule:: easynetwork.servers.async_tcp :members: :inherited-members: UDP Implementation ------------------ -.. autoclass:: AsyncUDPNetworkServer +.. automodule:: easynetwork.servers.async_udp :members: :inherited-members: @@ -40,33 +38,25 @@ UDP Implementation Synchronous Server Objects ========================== -Abstract Base Class -------------------- - -.. autoclass:: easynetwork.servers.abc::AbstractNetworkServer - :members: - :special-members: __enter__, __exit__ - TCP Implementation ------------------ -.. autoclass:: StandaloneTCPNetworkServer +.. automodule:: easynetwork.servers.standalone_tcp :members: :inherited-members: UDP Implementation ------------------ -.. autoclass:: StandaloneUDPNetworkServer +.. automodule:: easynetwork.servers.standalone_udp :members: :inherited-members: - Request Handler Interface ========================= -.. currentmodule:: easynetwork.servers.handlers +.. automodule:: easynetwork.servers.handlers .. autoclass:: AsyncStreamRequestHandler :members: diff --git a/docs/source/conf.py b/docs/source/conf.py index 086eb05b..56250201 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -52,10 +52,15 @@ manpages_url = "https://manpages.debian.org/{path}" templates_path = [] -exclude_patterns = ["_include", "_extensions", "_static"] +exclude_patterns = [ + "_include", + "_extensions", + "_static", + "_build", # <- Created by readthedocs.io +] rst_prolog = """ -.. ifconfig:: '.dev' in release or html_context.get('current_version') == 'latest' +.. ifconfig:: html_context.get('current_version') == 'latest' .. warning:: @@ -70,7 +75,7 @@ autodoc_class_signature = "separated" autodoc_member_order = "bysource" autodoc_default_options = { - "undoc-members": None, + "undoc-members": None, # TODO: To remove when all the project have docstrings "member-order": "bysource", "no-value": None, "show-inheritance": None, @@ -86,13 +91,14 @@ "contextvars.Context": "contextvars.Context", "MemoryBIO": "ssl.MemoryBIO", "Pickler": "pickle.Pickler", - "ReadableBuffer": "bytes | bytearray | memoryview", + "ReadableBuffer": "bytes | bytearray | memoryview | collections.abc.Buffer", "SSLContext": "ssl.SSLContext", + "SSLObject": "ssl.SSLObject", "SSLSession": "ssl.SSLSession", "SSLSocket": "ssl.SSLSocket", "Struct": "struct.Struct", "Unpickler": "pickle.Unpickler", - "WriteableBuffer": "bytearray | memoryview", + "WriteableBuffer": "bytearray | memoryview | collections.abc.Buffer", "ZLibCompress": "zlib.Compress", "ZLibDecompress": "zlib.Decompress", } diff --git a/docs/source/howto/advanced/standalone_servers.rst b/docs/source/howto/advanced/standalone_servers.rst index f40e1b0c..5a02e1c2 100644 --- a/docs/source/howto/advanced/standalone_servers.rst +++ b/docs/source/howto/advanced/standalone_servers.rst @@ -48,11 +48,13 @@ Unlike asynchronous tasks, it is mandatory to spawn a separate execution thread. .. literalinclude:: ../../_include/examples/howto/tcp_servers/standalone/background_server.py :linenos: + :emphasize-lines: 13,54-55 .. group-tab:: StandaloneUDPNetworkServer .. literalinclude:: ../../_include/examples/howto/udp_servers/standalone/background_server.py :linenos: + :emphasize-lines: 13,54-55 The output of the example should look something like this: diff --git a/docs/source/howto/serializers.rst b/docs/source/howto/serializers.rst index d8ae32f5..c2e11771 100644 --- a/docs/source/howto/serializers.rst +++ b/docs/source/howto/serializers.rst @@ -244,7 +244,7 @@ At each :keyword:`yield` checkpoint, the endpoint implementation sends to the ge The proposal to enhance the API and syntax of generators, making them usable as simple coroutines. :pep:`380` — Syntax for Delegating to a Subgenerator - The proposal to introduce the ``yield_from`` syntax, making delegation to subgenerators easy. + The proposal to introduce the ``yield from`` syntax, making delegation to subgenerators easy. Parsing Error diff --git a/docs/source/howto/udp_servers.rst b/docs/source/howto/udp_servers.rst index dc7f94d6..deca639f 100644 --- a/docs/source/howto/udp_servers.rst +++ b/docs/source/howto/udp_servers.rst @@ -122,7 +122,7 @@ Cancellation And Timeouts :pyobject: TimeoutYieldedRequestHandler.handle :dedent: :linenos: - :emphasize-lines: 4,15-17 + :emphasize-lines: 4,16-18 .. tab:: Using ``with`` diff --git a/docs/source/quickstart/install.rst b/docs/source/quickstart/install.rst index e2968d13..031bcbe5 100644 --- a/docs/source/quickstart/install.rst +++ b/docs/source/quickstart/install.rst @@ -26,7 +26,7 @@ Here is the full list: * Asynchronous I/O extensions: - * ``sniffio``: Installs the version supported and tested of :github:repo:`sniffio `. + * ``sniffio``: Installs the version supported and tested of :github:repo:`sniffio `, used by :func:`.ensure_backend`. Example where the ``cbor`` and ``msgpack`` extensions are installed: @@ -34,8 +34,3 @@ Example where the ``cbor`` and ``msgpack`` extensions are installed: .. code-block:: console (.venv) $ pip install "easynetwork[cbor,msgpack]" - - -.. todo:: - - Explain what we do with ``sniffio`` when adding documentation of ``AsyncIOBackend`` diff --git a/src/easynetwork/_typevars.py b/src/easynetwork/_typevars.py index 2a67dd8d..b277d084 100644 --- a/src/easynetwork/_typevars.py +++ b/src/easynetwork/_typevars.py @@ -12,7 +12,7 @@ # limitations under the License. # # -"""Common type variables for EasyNetwork's classes""" +"""Common type variables for EasyNetwork's classes.""" from __future__ import annotations @@ -30,9 +30,6 @@ if typing.TYPE_CHECKING: from _typeshed import WriteableBuffer -else: # pragma: no cover - # Needed for sphinx-autodoc - WriteableBuffer = bytearray | memoryview _T_SentDTOPacket = typing.TypeVar("_T_SentDTOPacket") _T_ReceivedDTOPacket = typing.TypeVar("_T_ReceivedDTOPacket") diff --git a/src/easynetwork/clients/__init__.py b/src/easynetwork/clients/__init__.py index 6bb07699..2e41cb9b 100644 --- a/src/easynetwork/clients/__init__.py +++ b/src/easynetwork/clients/__init__.py @@ -12,7 +12,7 @@ # limitations under the License. # # -"""Network client module""" +"""Network client module.""" from __future__ import annotations diff --git a/src/easynetwork/clients/abc.py b/src/easynetwork/clients/abc.py index 7aa3c330..39636b21 100644 --- a/src/easynetwork/clients/abc.py +++ b/src/easynetwork/clients/abc.py @@ -12,7 +12,7 @@ # limitations under the License. # # -"""Network client interfaces definition module""" +"""Network client interfaces definition module.""" from __future__ import annotations diff --git a/src/easynetwork/clients/async_tcp.py b/src/easynetwork/clients/async_tcp.py index aebdb64f..5f565c16 100644 --- a/src/easynetwork/clients/async_tcp.py +++ b/src/easynetwork/clients/async_tcp.py @@ -12,7 +12,7 @@ # limitations under the License. # # -"""Asynchronous network client module""" +"""Asynchronous TCP Network client implementation module.""" from __future__ import annotations @@ -38,7 +38,7 @@ from ..exceptions import ClientClosedError from ..lowlevel import _utils, constants from ..lowlevel.api_async.backend.abc import AsyncBackend, CancelScope, ILock -from ..lowlevel.api_async.backend.utils import BuiltinAsyncBackendToken, ensure_backend +from ..lowlevel.api_async.backend.utils import BuiltinAsyncBackendLiteral, ensure_backend from ..lowlevel.api_async.endpoints.stream import AsyncStreamEndpoint from ..lowlevel.api_async.transports.abc import AsyncStreamTransport from ..lowlevel.socket import ( @@ -91,7 +91,7 @@ def __init__( address: tuple[str, int], /, protocol: AnyStreamProtocolType[_T_SentPacket, _T_ReceivedPacket], - backend: AsyncBackend | BuiltinAsyncBackendToken | None = ..., + backend: AsyncBackend | BuiltinAsyncBackendLiteral | None = ..., *, local_address: tuple[str, int] | None = ..., happy_eyeballs_delay: float | None = ..., @@ -110,7 +110,7 @@ def __init__( socket: _socket.socket, /, protocol: AnyStreamProtocolType[_T_SentPacket, _T_ReceivedPacket], - backend: AsyncBackend | BuiltinAsyncBackendToken | None = ..., + backend: AsyncBackend | BuiltinAsyncBackendLiteral | None = ..., *, ssl: SSLContext | bool | None = ..., server_hostname: str | None = ..., @@ -126,7 +126,7 @@ def __init__( __arg: tuple[str, int] | _socket.socket, /, protocol: AnyStreamProtocolType[_T_SentPacket, _T_ReceivedPacket], - backend: AsyncBackend | BuiltinAsyncBackendToken | None = None, + backend: AsyncBackend | BuiltinAsyncBackendLiteral | None = None, *, ssl: SSLContext | bool | None = None, server_hostname: str | None = None, diff --git a/src/easynetwork/clients/async_udp.py b/src/easynetwork/clients/async_udp.py index d4bea9d5..c60421bd 100644 --- a/src/easynetwork/clients/async_udp.py +++ b/src/easynetwork/clients/async_udp.py @@ -12,7 +12,7 @@ # limitations under the License. # # -"""Asynchronous network client module""" +"""Asynchronous UDP Network client implementation module.""" from __future__ import annotations @@ -30,7 +30,7 @@ from ..exceptions import ClientClosedError from ..lowlevel import _utils, constants from ..lowlevel.api_async.backend.abc import AsyncBackend, CancelScope, ILock -from ..lowlevel.api_async.backend.utils import BuiltinAsyncBackendToken, ensure_backend +from ..lowlevel.api_async.backend.utils import BuiltinAsyncBackendLiteral, ensure_backend from ..lowlevel.api_async.endpoints.datagram import AsyncDatagramEndpoint from ..lowlevel.api_async.transports.abc import AsyncDatagramTransport from ..lowlevel.socket import INETSocketAttribute, SocketAddress, SocketProxy, new_socket_address @@ -72,7 +72,7 @@ def __init__( address: tuple[str, int], /, protocol: DatagramProtocol[_T_SentPacket, _T_ReceivedPacket], - backend: AsyncBackend | BuiltinAsyncBackendToken | None = ..., + backend: AsyncBackend | BuiltinAsyncBackendLiteral | None = ..., *, local_address: tuple[str, int] | None = ..., family: int = ..., @@ -84,7 +84,7 @@ def __init__( socket: _socket.socket, /, protocol: DatagramProtocol[_T_SentPacket, _T_ReceivedPacket], - backend: AsyncBackend | BuiltinAsyncBackendToken | None = ..., + backend: AsyncBackend | BuiltinAsyncBackendLiteral | None = ..., ) -> None: ... def __init__( @@ -92,7 +92,7 @@ def __init__( __arg: tuple[str, int] | _socket.socket, /, protocol: DatagramProtocol[_T_SentPacket, _T_ReceivedPacket], - backend: AsyncBackend | BuiltinAsyncBackendToken | None = None, + backend: AsyncBackend | BuiltinAsyncBackendLiteral | None = None, **kwargs: Any, ) -> None: """ diff --git a/src/easynetwork/clients/tcp.py b/src/easynetwork/clients/tcp.py index 78153eca..e5f0c2e2 100644 --- a/src/easynetwork/clients/tcp.py +++ b/src/easynetwork/clients/tcp.py @@ -12,7 +12,7 @@ # limitations under the License. # # -"""TCP Network client implementation module""" +"""TCP Network client implementation module.""" from __future__ import annotations diff --git a/src/easynetwork/clients/udp.py b/src/easynetwork/clients/udp.py index 15d56886..9b060f7c 100644 --- a/src/easynetwork/clients/udp.py +++ b/src/easynetwork/clients/udp.py @@ -12,7 +12,7 @@ # limitations under the License. # # -"""UDP Network client implementation module""" +"""UDP Network client implementation module.""" from __future__ import annotations diff --git a/src/easynetwork/converter.py b/src/easynetwork/converter.py index ca4ccea0..d82b112e 100644 --- a/src/easynetwork/converter.py +++ b/src/easynetwork/converter.py @@ -12,7 +12,7 @@ # limitations under the License. # # -"""EasyNetwork's packet converters module""" +"""EasyNetwork's packet converters module.""" from __future__ import annotations diff --git a/src/easynetwork/exceptions.py b/src/easynetwork/exceptions.py index 8183f4c2..8e88c6f0 100644 --- a/src/easynetwork/exceptions.py +++ b/src/easynetwork/exceptions.py @@ -134,7 +134,7 @@ def __init__(self, message: str, error_info: Any = None) -> None: super().__init__(message) self.error_info: Any = error_info - """Additional error data""" + """Additional error data.""" class BaseProtocolParseError(Exception): diff --git a/src/easynetwork/lowlevel/__init__.py b/src/easynetwork/lowlevel/__init__.py index 17f0a28a..d634f905 100644 --- a/src/easynetwork/lowlevel/__init__.py +++ b/src/easynetwork/lowlevel/__init__.py @@ -12,7 +12,7 @@ # limitations under the License. # # -"""EasyNetwork's low-level API module""" +"""EasyNetwork's low-level API module.""" from __future__ import annotations diff --git a/src/easynetwork/lowlevel/_asyncgen.py b/src/easynetwork/lowlevel/_asyncgen.py index 84787386..89919921 100644 --- a/src/easynetwork/lowlevel/_asyncgen.py +++ b/src/easynetwork/lowlevel/_asyncgen.py @@ -12,7 +12,7 @@ # limitations under the License. # # -"""Async generators helper module""" +"""Async generators helper module.""" from __future__ import annotations diff --git a/src/easynetwork/lowlevel/_stream.py b/src/easynetwork/lowlevel/_stream.py index 4f5cca27..a593bfcd 100644 --- a/src/easynetwork/lowlevel/_stream.py +++ b/src/easynetwork/lowlevel/_stream.py @@ -12,7 +12,7 @@ # limitations under the License. # # -"""Stream network packet serializer handler module""" +"""Stream network packet serializer handler module.""" from __future__ import annotations diff --git a/src/easynetwork/lowlevel/api_async/__init__.py b/src/easynetwork/lowlevel/api_async/__init__.py index 3e7ec1be..e99d736a 100644 --- a/src/easynetwork/lowlevel/api_async/__init__.py +++ b/src/easynetwork/lowlevel/api_async/__init__.py @@ -12,7 +12,7 @@ # limitations under the License. # # -"""Low-level asynchronous API module""" +"""Low-level asynchronous API module.""" from __future__ import annotations diff --git a/src/easynetwork/lowlevel/api_async/backend/__init__.py b/src/easynetwork/lowlevel/api_async/backend/__init__.py index b2429bad..5e6eba99 100644 --- a/src/easynetwork/lowlevel/api_async/backend/__init__.py +++ b/src/easynetwork/lowlevel/api_async/backend/__init__.py @@ -12,7 +12,7 @@ # limitations under the License. # # -"""Asynchronous backend engine module""" +"""Asynchronous backend engine module.""" from __future__ import annotations diff --git a/src/easynetwork/lowlevel/api_async/backend/_sniffio_helpers.py b/src/easynetwork/lowlevel/api_async/backend/_sniffio_helpers.py index b9a1f8d5..15413589 100644 --- a/src/easynetwork/lowlevel/api_async/backend/_sniffio_helpers.py +++ b/src/easynetwork/lowlevel/api_async/backend/_sniffio_helpers.py @@ -12,7 +12,7 @@ # limitations under the License. # # -"""Helper module for sniffio integration""" +"""Helper module for sniffio integration.""" from __future__ import annotations diff --git a/src/easynetwork/lowlevel/api_async/backend/abc.py b/src/easynetwork/lowlevel/api_async/backend/abc.py index 2298f6a0..a7c2ea45 100644 --- a/src/easynetwork/lowlevel/api_async/backend/abc.py +++ b/src/easynetwork/lowlevel/api_async/backend/abc.py @@ -12,7 +12,7 @@ # limitations under the License. # # -"""Asynchronous backend engine interfaces module""" +"""Asynchronous backend engine interfaces module.""" from __future__ import annotations diff --git a/src/easynetwork/lowlevel/api_async/backend/utils.py b/src/easynetwork/lowlevel/api_async/backend/utils.py index b2e83357..541c0497 100644 --- a/src/easynetwork/lowlevel/api_async/backend/utils.py +++ b/src/easynetwork/lowlevel/api_async/backend/utils.py @@ -12,12 +12,12 @@ # limitations under the License. # # -"""Helper module for async backend""" +"""Helper module for async backend.""" from __future__ import annotations __all__ = [ - "BuiltinAsyncBackendToken", + "BuiltinAsyncBackendLiteral", "ensure_backend", ] @@ -26,15 +26,34 @@ from . import _sniffio_helpers from .abc import AsyncBackend -BuiltinAsyncBackendToken: TypeAlias = Literal["asyncio"] +BuiltinAsyncBackendLiteral: TypeAlias = Literal["asyncio"] -def ensure_backend(backend: AsyncBackend | BuiltinAsyncBackendToken | None) -> AsyncBackend: +def ensure_backend(backend: AsyncBackend | BuiltinAsyncBackendLiteral | None) -> AsyncBackend: """ - TODO: Add docstring + Obtain an interface for the give `backend`. + + * If `backend` is already an :class:`AsyncBackend`, this object is returned. + + * If `backend` is a string token and matches one of the built-in implementation, a new object is returned. + + * Currently, only ``"asyncio"`` is recognized. + + * If :data:`None`, the function tries to guess the library currently used. + + * Needs ``sniffio`` feature to have extended researches, otherwise only :mod:`asyncio` is recognized. + + See Also: + + :ref:`optional-dependencies` + Explains how to install ``sniffio`` extra. + + Raises: + NotImplementedError: the current asynchronous library is not implemented. + RuntimeError: unknown async library, or not in async context """ if backend is None: - backend = cast(BuiltinAsyncBackendToken, _sniffio_helpers.current_async_library()) + backend = cast(BuiltinAsyncBackendLiteral, _sniffio_helpers.current_async_library()) match backend: case "asyncio": diff --git a/src/easynetwork/lowlevel/api_async/endpoints/__init__.py b/src/easynetwork/lowlevel/api_async/endpoints/__init__.py index 04a89a4b..16a0e4c9 100644 --- a/src/easynetwork/lowlevel/api_async/endpoints/__init__.py +++ b/src/easynetwork/lowlevel/api_async/endpoints/__init__.py @@ -12,7 +12,7 @@ # limitations under the License. # # -"""Low-level asynchronous endpoints module""" +"""Low-level asynchronous endpoints module.""" from __future__ import annotations diff --git a/src/easynetwork/lowlevel/api_async/endpoints/datagram.py b/src/easynetwork/lowlevel/api_async/endpoints/datagram.py index 1b7b2bbb..7b9bb7cf 100644 --- a/src/easynetwork/lowlevel/api_async/endpoints/datagram.py +++ b/src/easynetwork/lowlevel/api_async/endpoints/datagram.py @@ -12,7 +12,7 @@ # limitations under the License. # # -"""Low-level asynchronous endpoints module""" +"""Low-level asynchronous endpoints module for datagram-based communication.""" from __future__ import annotations diff --git a/src/easynetwork/lowlevel/api_async/endpoints/stream.py b/src/easynetwork/lowlevel/api_async/endpoints/stream.py index 7965609a..6dbef0bc 100644 --- a/src/easynetwork/lowlevel/api_async/endpoints/stream.py +++ b/src/easynetwork/lowlevel/api_async/endpoints/stream.py @@ -12,7 +12,7 @@ # limitations under the License. # # -"""Low-level asynchronous endpoints module""" +"""Low-level asynchronous endpoints module for connection-oriented communication.""" from __future__ import annotations diff --git a/src/easynetwork/lowlevel/api_async/servers/__init__.py b/src/easynetwork/lowlevel/api_async/servers/__init__.py index 1d274966..c0f99610 100644 --- a/src/easynetwork/lowlevel/api_async/servers/__init__.py +++ b/src/easynetwork/lowlevel/api_async/servers/__init__.py @@ -12,7 +12,7 @@ # limitations under the License. # # -"""Low-level asynchronous servers module""" +"""Low-level asynchronous servers module.""" from __future__ import annotations diff --git a/src/easynetwork/lowlevel/api_async/servers/datagram.py b/src/easynetwork/lowlevel/api_async/servers/datagram.py index 83c17d93..2a811314 100644 --- a/src/easynetwork/lowlevel/api_async/servers/datagram.py +++ b/src/easynetwork/lowlevel/api_async/servers/datagram.py @@ -12,11 +12,11 @@ # limitations under the License. # # -"""Low-level asynchronous datagram servers module""" +"""Low-level asynchronous datagram servers module.""" from __future__ import annotations -__all__ = ["AsyncDatagramServer"] +__all__ = ["AsyncDatagramServer", "DatagramClientContext"] import contextlib import contextvars @@ -58,7 +58,7 @@ class DatagramClientContext(Generic[_T_Response, _T_Address]): ) address: _T_Address - """The client address""" + """The client address.""" server: AsyncDatagramServer[Any, _T_Response, _T_Address] """The server which receives the datagram.""" diff --git a/src/easynetwork/lowlevel/api_async/servers/stream.py b/src/easynetwork/lowlevel/api_async/servers/stream.py index ee402a21..d1589145 100644 --- a/src/easynetwork/lowlevel/api_async/servers/stream.py +++ b/src/easynetwork/lowlevel/api_async/servers/stream.py @@ -12,11 +12,11 @@ # limitations under the License. # # -"""Low-level asynchronous stream servers module""" +"""Low-level asynchronous stream servers module.""" from __future__ import annotations -__all__ = ["AsyncStreamServer"] +__all__ = ["AsyncStreamServer", "ConnectedStreamClient"] import contextlib import dataclasses @@ -39,7 +39,7 @@ ) -class Client(AsyncBaseTransport, Generic[_T_Response]): +class ConnectedStreamClient(AsyncBaseTransport, Generic[_T_Response]): """ Write-end of the connected client. """ @@ -175,7 +175,7 @@ def backend(self) -> AsyncBackend: async def serve( self, - client_connected_cb: Callable[[Client[_T_Response]], AsyncGenerator[float | None, _T_Request]], + client_connected_cb: Callable[[ConnectedStreamClient[_T_Response]], AsyncGenerator[float | None, _T_Request]], task_group: TaskGroup | None = None, ) -> NoReturn: """ @@ -191,7 +191,7 @@ async def serve( async def __client_coroutine( self, - client_connected_cb: Callable[[Client[_T_Response]], AsyncGenerator[float | None, _T_Request]], + client_connected_cb: Callable[[ConnectedStreamClient[_T_Response]], AsyncGenerator[float | None, _T_Request]], transport: AsyncStreamTransport, ) -> None: if not isinstance(transport, AsyncStreamTransport): @@ -227,7 +227,7 @@ async def __client_coroutine( client_exit_stack.callback(consumer.clear) request_handler_generator = client_connected_cb( - Client( + ConnectedStreamClient( _transport=transport, _producer=producer, _exit_stack=client_exit_stack, diff --git a/src/easynetwork/lowlevel/api_async/transports/__init__.py b/src/easynetwork/lowlevel/api_async/transports/__init__.py index 4e5c3613..25cc3f77 100644 --- a/src/easynetwork/lowlevel/api_async/transports/__init__.py +++ b/src/easynetwork/lowlevel/api_async/transports/__init__.py @@ -12,7 +12,7 @@ # limitations under the License. # # -"""Low-level asynchronous transports module""" +"""Low-level asynchronous transports module.""" from __future__ import annotations diff --git a/src/easynetwork/lowlevel/api_async/transports/abc.py b/src/easynetwork/lowlevel/api_async/transports/abc.py index b99ade5a..f41c3cca 100644 --- a/src/easynetwork/lowlevel/api_async/transports/abc.py +++ b/src/easynetwork/lowlevel/api_async/transports/abc.py @@ -12,7 +12,7 @@ # limitations under the License. # # -"""Low-level asynchronous transports module""" +"""Low-level asynchronous transports interfaces module.""" from __future__ import annotations diff --git a/src/easynetwork/lowlevel/api_async/transports/tls.py b/src/easynetwork/lowlevel/api_async/transports/tls.py index 14b8365c..9a4eb90b 100644 --- a/src/easynetwork/lowlevel/api_async/transports/tls.py +++ b/src/easynetwork/lowlevel/api_async/transports/tls.py @@ -12,7 +12,10 @@ # limitations under the License. # # -"""Low-level asynchronous transports module""" +"""Low-level asynchronous SSL transports module. + +To use this module, the standard :mod:`ssl` module must be available. +""" from __future__ import annotations @@ -246,8 +249,13 @@ def __write_all_to_ssl_object(ssl_object: SSLObject, write_backlog: deque[memory else: del write_backlog[0] - @_utils.inherit_doc(AsyncStreamTransport) async def send_eof(self) -> None: + """ + Closes the write end of the stream after the buffered write data is flushed. + + Raises: + UnsupportedOperation: SSL/TLS API does not support sending EOF (for now). + """ raise UnsupportedOperation("SSL/TLS API does not support sending EOF.") async def _retry_ssl_method( diff --git a/src/easynetwork/lowlevel/api_async/transports/utils.py b/src/easynetwork/lowlevel/api_async/transports/utils.py index d191532e..44e9bd6a 100644 --- a/src/easynetwork/lowlevel/api_async/transports/utils.py +++ b/src/easynetwork/lowlevel/api_async/transports/utils.py @@ -12,7 +12,7 @@ # limitations under the License. # # -"""Low-level asynchronous transports module""" +"""Low-level asynchronous transports tools module.""" from __future__ import annotations diff --git a/src/easynetwork/lowlevel/api_sync/__init__.py b/src/easynetwork/lowlevel/api_sync/__init__.py index a22ee921..671eb35a 100644 --- a/src/easynetwork/lowlevel/api_sync/__init__.py +++ b/src/easynetwork/lowlevel/api_sync/__init__.py @@ -12,7 +12,7 @@ # limitations under the License. # # -"""Low-level synchronous API module""" +"""Low-level synchronous API module.""" from __future__ import annotations diff --git a/src/easynetwork/lowlevel/api_sync/endpoints/__init__.py b/src/easynetwork/lowlevel/api_sync/endpoints/__init__.py index 61a1abaf..482601b8 100644 --- a/src/easynetwork/lowlevel/api_sync/endpoints/__init__.py +++ b/src/easynetwork/lowlevel/api_sync/endpoints/__init__.py @@ -12,7 +12,7 @@ # limitations under the License. # # -"""Low-level endpoints module""" +"""Low-level endpoints module.""" from __future__ import annotations diff --git a/src/easynetwork/lowlevel/api_sync/endpoints/datagram.py b/src/easynetwork/lowlevel/api_sync/endpoints/datagram.py index 8f1fdd3e..15dd11c4 100644 --- a/src/easynetwork/lowlevel/api_sync/endpoints/datagram.py +++ b/src/easynetwork/lowlevel/api_sync/endpoints/datagram.py @@ -12,7 +12,7 @@ # limitations under the License. # # -"""Low-level endpoints module""" +"""Low-level endpoints module for datagram-based communication.""" from __future__ import annotations diff --git a/src/easynetwork/lowlevel/api_sync/endpoints/stream.py b/src/easynetwork/lowlevel/api_sync/endpoints/stream.py index 67d8a0ae..6f1b1d98 100644 --- a/src/easynetwork/lowlevel/api_sync/endpoints/stream.py +++ b/src/easynetwork/lowlevel/api_sync/endpoints/stream.py @@ -12,7 +12,7 @@ # limitations under the License. # # -"""Low-level endpoints module""" +"""Low-level endpoints module for connection-oriented communication.""" from __future__ import annotations diff --git a/src/easynetwork/lowlevel/api_sync/transports/__init__.py b/src/easynetwork/lowlevel/api_sync/transports/__init__.py index a7225da9..d1028735 100644 --- a/src/easynetwork/lowlevel/api_sync/transports/__init__.py +++ b/src/easynetwork/lowlevel/api_sync/transports/__init__.py @@ -12,7 +12,7 @@ # limitations under the License. # # -"""Low-level transports module""" +"""Low-level transports module.""" from __future__ import annotations diff --git a/src/easynetwork/lowlevel/api_sync/transports/abc.py b/src/easynetwork/lowlevel/api_sync/transports/abc.py index dc3a43fa..df8f41ae 100644 --- a/src/easynetwork/lowlevel/api_sync/transports/abc.py +++ b/src/easynetwork/lowlevel/api_sync/transports/abc.py @@ -12,7 +12,7 @@ # limitations under the License. # # -"""Low-level transports module""" +"""Low-level transports interfaces module.""" from __future__ import annotations diff --git a/src/easynetwork/lowlevel/api_sync/transports/base_selector.py b/src/easynetwork/lowlevel/api_sync/transports/base_selector.py index d6c846d7..17049289 100644 --- a/src/easynetwork/lowlevel/api_sync/transports/base_selector.py +++ b/src/easynetwork/lowlevel/api_sync/transports/base_selector.py @@ -12,7 +12,10 @@ # limitations under the License. # # -"""Low-level transports module""" +""":mod:`selectors` transports module. + +Here are abstract base classes which use :mod:`selectors` module to perform I/O polling. +""" from __future__ import annotations @@ -104,8 +107,8 @@ def _retry( """ Calls `callback` without argument and returns the output. - If the callable raises :class:`WouldBlockOnRead` or :class:`WouldBlockOnWrite`, waits for ``fileno`` to be - available for reading or writing respectively, and retries to call the callback. + If the callable raises :class:`WouldBlockOnRead` or :class:`WouldBlockOnWrite`, waits for + :attr:`~.WouldBlockOnRead.fileno` to be available for reading or writing respectively, and retries to call the callback. Parameters: callback: the function to call. diff --git a/src/easynetwork/lowlevel/api_sync/transports/socket.py b/src/easynetwork/lowlevel/api_sync/transports/socket.py index 4b2c21d7..45c4ee5d 100644 --- a/src/easynetwork/lowlevel/api_sync/transports/socket.py +++ b/src/easynetwork/lowlevel/api_sync/transports/socket.py @@ -12,7 +12,7 @@ # limitations under the License. # # -"""Low-level transports module""" +"""Transport implementations module wrapping sockets.""" from __future__ import annotations diff --git a/src/easynetwork/lowlevel/constants.py b/src/easynetwork/lowlevel/constants.py index 382b255e..21be5b9c 100644 --- a/src/easynetwork/lowlevel/constants.py +++ b/src/easynetwork/lowlevel/constants.py @@ -12,7 +12,7 @@ # limitations under the License. # # -"""EasyNetwork's constants module""" +"""EasyNetwork's constants module.""" from __future__ import annotations diff --git a/src/easynetwork/lowlevel/futures.py b/src/easynetwork/lowlevel/futures.py index ed32cb58..0b53e310 100644 --- a/src/easynetwork/lowlevel/futures.py +++ b/src/easynetwork/lowlevel/futures.py @@ -12,7 +12,7 @@ # limitations under the License. # # -"""Asynchronous backend engine bindings with concurrent.futures module""" +"""Asynchronous backend engine bindings with ``concurrent.futures`` module.""" from __future__ import annotations @@ -30,7 +30,7 @@ from .api_async.backend import _sniffio_helpers from .api_async.backend.abc import AsyncBackend -from .api_async.backend.utils import BuiltinAsyncBackendToken, ensure_backend +from .api_async.backend.utils import BuiltinAsyncBackendLiteral, ensure_backend _P = ParamSpec("_P") _T = TypeVar("_T") @@ -70,7 +70,7 @@ async def main() -> None: def __init__( self, executor: _T_Executor, - backend: AsyncBackend | BuiltinAsyncBackendToken | None = None, + backend: AsyncBackend | BuiltinAsyncBackendLiteral | None = None, *, handle_contexts: bool = True, ) -> None: diff --git a/src/easynetwork/lowlevel/socket.py b/src/easynetwork/lowlevel/socket.py index 4562f374..166ab0aa 100644 --- a/src/easynetwork/lowlevel/socket.py +++ b/src/easynetwork/lowlevel/socket.py @@ -12,7 +12,7 @@ # limitations under the License. # # -"""Network socket module""" +"""Network socket helper module.""" from __future__ import annotations @@ -119,7 +119,7 @@ class TLSAttribute(typed_attr.TypedAttributeSet): """:data:`True` if this stream does (and expects) a closing TLS handshake when the stream is being closed.""" tls_version: str = typed_attr.typed_attribute() - """the TLS protocol version (e.g. TLSv1.2)""" + """the TLS protocol version (e.g. TLSv1.2).""" class IPv4SocketAddress(NamedTuple): @@ -155,7 +155,6 @@ def for_connection(self) -> tuple[str, int]: SocketAddress: TypeAlias = IPv4SocketAddress | IPv6SocketAddress -"""Alias for :class:`IPv4SocketAddress` | :class:`IPv6SocketAddress`""" @overload @@ -507,10 +506,10 @@ class socket_linger(NamedTuple): """ enabled: bool - """Linger active""" + """Linger active.""" timeout: int - """How many seconds to linger for (if active)""" + """How many seconds to linger for (if active).""" def get_socket_linger_struct() -> Struct: diff --git a/src/easynetwork/protocol.py b/src/easynetwork/protocol.py index 3d44440c..51d452a4 100644 --- a/src/easynetwork/protocol.py +++ b/src/easynetwork/protocol.py @@ -12,7 +12,7 @@ # limitations under the License. # # -"""Communication protocol objects module""" +"""Communication protocol objects module.""" from __future__ import annotations diff --git a/src/easynetwork/serializers/__init__.py b/src/easynetwork/serializers/__init__.py index d34a262b..2bf3351a 100644 --- a/src/easynetwork/serializers/__init__.py +++ b/src/easynetwork/serializers/__init__.py @@ -12,7 +12,7 @@ # limitations under the License. # # -"""EasyNetwork's packet serializers module""" +"""EasyNetwork's packet serializers module.""" from __future__ import annotations diff --git a/src/easynetwork/serializers/abc.py b/src/easynetwork/serializers/abc.py index 10e9aa18..8a54468b 100644 --- a/src/easynetwork/serializers/abc.py +++ b/src/easynetwork/serializers/abc.py @@ -12,7 +12,7 @@ # limitations under the License. # # -"""Network packet serializer base classes module""" +"""Network packet serializer base classes module.""" from __future__ import annotations diff --git a/src/easynetwork/serializers/base_stream.py b/src/easynetwork/serializers/base_stream.py index efcd01e9..e42f5b8e 100644 --- a/src/easynetwork/serializers/base_stream.py +++ b/src/easynetwork/serializers/base_stream.py @@ -12,7 +12,10 @@ # limitations under the License. # # -"""Stream network packet serializer handler module""" +"""Stream network packet serializer handler module. + +Here are abstract classes that implement common stream protocol patterns. +""" from __future__ import annotations diff --git a/src/easynetwork/serializers/cbor.py b/src/easynetwork/serializers/cbor.py index abcafe96..755fdf23 100644 --- a/src/easynetwork/serializers/cbor.py +++ b/src/easynetwork/serializers/cbor.py @@ -12,7 +12,15 @@ # limitations under the License. # # -"""cbor-based network packet serializer module""" +"""``cbor``-based network packet serializer module. + +The `CBOR `_ is an alternative representation of the ``JSON`` data models. + +See Also: + + :ref:`optional-dependencies` + Explains how to install ``cbor`` extra. +""" from __future__ import annotations diff --git a/src/easynetwork/serializers/json.py b/src/easynetwork/serializers/json.py index c663c131..a9ca3eb0 100644 --- a/src/easynetwork/serializers/json.py +++ b/src/easynetwork/serializers/json.py @@ -12,7 +12,7 @@ # limitations under the License. # # -"""json-based packet serializer module""" +"""``json``-based packet serializer module.""" from __future__ import annotations diff --git a/src/easynetwork/serializers/line.py b/src/easynetwork/serializers/line.py index 9fd0928f..373b0c8d 100644 --- a/src/easynetwork/serializers/line.py +++ b/src/easynetwork/serializers/line.py @@ -12,7 +12,7 @@ # limitations under the License. # # -"""string line packet serializer module""" +"""String line packet serializer module.""" from __future__ import annotations diff --git a/src/easynetwork/serializers/msgpack.py b/src/easynetwork/serializers/msgpack.py index 3061190f..e7e72e40 100644 --- a/src/easynetwork/serializers/msgpack.py +++ b/src/easynetwork/serializers/msgpack.py @@ -12,7 +12,15 @@ # limitations under the License. # # -"""msgpack-based network packet serializer module""" +"""``MessagePack``-based network packet serializer module. + +The `MessagePack `_ is an alternative representation of the ``JSON`` data models. + +See Also: + + :ref:`optional-dependencies` + Explains how to install ``msgpack`` extra. +""" from __future__ import annotations diff --git a/src/easynetwork/serializers/pickle.py b/src/easynetwork/serializers/pickle.py index ab9fe160..daa23aab 100644 --- a/src/easynetwork/serializers/pickle.py +++ b/src/easynetwork/serializers/pickle.py @@ -12,7 +12,7 @@ # limitations under the License. # # -"""pickle-based packet serializer module""" +"""``pickle``-based packet serializer module.""" from __future__ import annotations diff --git a/src/easynetwork/serializers/struct.py b/src/easynetwork/serializers/struct.py index 77a34dfa..27b92573 100644 --- a/src/easynetwork/serializers/struct.py +++ b/src/easynetwork/serializers/struct.py @@ -12,7 +12,7 @@ # limitations under the License. # # -"""struct.Struct-based network packet serializer module""" +"""Network packet serializer module based on structures.""" from __future__ import annotations diff --git a/src/easynetwork/serializers/tools.py b/src/easynetwork/serializers/tools.py index 7ce6aecb..8cbba82e 100644 --- a/src/easynetwork/serializers/tools.py +++ b/src/easynetwork/serializers/tools.py @@ -12,7 +12,7 @@ # limitations under the License. # # -"""Serializer implementation tools module""" +"""Serializer implementation tools module.""" from __future__ import annotations diff --git a/src/easynetwork/serializers/wrapper/__init__.py b/src/easynetwork/serializers/wrapper/__init__.py index 947fcb52..41f83ed0 100644 --- a/src/easynetwork/serializers/wrapper/__init__.py +++ b/src/easynetwork/serializers/wrapper/__init__.py @@ -12,7 +12,7 @@ # limitations under the License. # # -"""EasyNetwork's packet serializer module""" +"""EasyNetwork's packet serializer module.""" from __future__ import annotations diff --git a/src/easynetwork/serializers/wrapper/base64.py b/src/easynetwork/serializers/wrapper/base64.py index ed4846df..1d966056 100644 --- a/src/easynetwork/serializers/wrapper/base64.py +++ b/src/easynetwork/serializers/wrapper/base64.py @@ -12,7 +12,7 @@ # limitations under the License. # # -"""base64 encoder serializer module""" +"""base64 encoder serializer module.""" from __future__ import annotations diff --git a/src/easynetwork/serializers/wrapper/compressor.py b/src/easynetwork/serializers/wrapper/compressor.py index 2c04b5fe..5edd1ad7 100644 --- a/src/easynetwork/serializers/wrapper/compressor.py +++ b/src/easynetwork/serializers/wrapper/compressor.py @@ -12,7 +12,7 @@ # limitations under the License. # # -"""Data compressor serializer module""" +"""Data compressor serializer module.""" from __future__ import annotations diff --git a/src/easynetwork/servers/__init__.py b/src/easynetwork/servers/__init__.py index 7b8ac5f7..6d423426 100644 --- a/src/easynetwork/servers/__init__.py +++ b/src/easynetwork/servers/__init__.py @@ -12,7 +12,7 @@ # limitations under the License. # # -"""Network server module""" +"""Network server module.""" from __future__ import annotations diff --git a/src/easynetwork/servers/_base.py b/src/easynetwork/servers/_base.py index 0ec4f63e..42bcaf8c 100644 --- a/src/easynetwork/servers/_base.py +++ b/src/easynetwork/servers/_base.py @@ -12,7 +12,7 @@ # limitations under the License. # # -"""Generic network servers module""" +"""Generic network servers module.""" from __future__ import annotations @@ -28,7 +28,7 @@ from ..lowlevel import _utils from ..lowlevel._lock import ForkSafeLock from ..lowlevel.api_async.backend.abc import AsyncBackend, ThreadsPortal -from ..lowlevel.api_async.backend.utils import BuiltinAsyncBackendToken, ensure_backend +from ..lowlevel.api_async.backend.utils import BuiltinAsyncBackendLiteral, ensure_backend from ..lowlevel.socket import SocketAddress from .abc import AbstractAsyncNetworkServer, AbstractNetworkServer, SupportsEventSet @@ -52,7 +52,7 @@ class BaseStandaloneNetworkServerImpl(AbstractNetworkServer, Generic[_T_AsyncSer def __init__( self, - backend: AsyncBackend | BuiltinAsyncBackendToken | None, + backend: AsyncBackend | BuiltinAsyncBackendLiteral | None, server_factory: Callable[[AsyncBackend], _T_AsyncServer], *, runner_options: Mapping[str, Any] | None = None, diff --git a/src/easynetwork/servers/abc.py b/src/easynetwork/servers/abc.py index b5c262fb..669aae71 100644 --- a/src/easynetwork/servers/abc.py +++ b/src/easynetwork/servers/abc.py @@ -12,7 +12,7 @@ # limitations under the License. # # -"""Asynchronous network server module""" +"""Network server interfaces definition module.""" from __future__ import annotations diff --git a/src/easynetwork/servers/async_tcp.py b/src/easynetwork/servers/async_tcp.py index 28f9928a..c06f0c29 100644 --- a/src/easynetwork/servers/async_tcp.py +++ b/src/easynetwork/servers/async_tcp.py @@ -12,7 +12,7 @@ # limitations under the License. # # -"""Asynchronous network server module""" +"""Asynchronous TCP Network server implementation module.""" from __future__ import annotations @@ -30,7 +30,7 @@ from ..lowlevel import _utils, constants from ..lowlevel._final import runtime_final_class from ..lowlevel.api_async.backend.abc import AsyncBackend, CancelScope, IEvent, Task, TaskGroup -from ..lowlevel.api_async.backend.utils import BuiltinAsyncBackendToken, ensure_backend +from ..lowlevel.api_async.backend.utils import BuiltinAsyncBackendLiteral, ensure_backend from ..lowlevel.api_async.servers import stream as _stream_server from ..lowlevel.api_async.transports.abc import AsyncListener, AsyncStreamTransport from ..lowlevel.socket import ( @@ -80,7 +80,7 @@ def __init__( port: int, protocol: AnyStreamProtocolType[_T_Response, _T_Request], request_handler: AsyncStreamRequestHandler[_T_Request, _T_Response], - backend: AsyncBackend | BuiltinAsyncBackendToken | None = None, + backend: AsyncBackend | BuiltinAsyncBackendLiteral | None = None, *, ssl: SSLContext | None = None, ssl_handshake_timeout: float | None = None, @@ -386,7 +386,7 @@ async def __serve( @contextlib.asynccontextmanager async def __client_initializer( self, - lowlevel_client: _stream_server.Client[_T_Response], + lowlevel_client: _stream_server.ConnectedStreamClient[_T_Response], ) -> AsyncIterator[AsyncStreamClient[_T_Response] | None]: async with contextlib.AsyncExitStack() as client_exit_stack: self.__attach_server() @@ -512,9 +512,9 @@ class _ConnectedClientAPI(AsyncStreamClient[_T_Response]): def __init__( self, address: SocketAddress, - client: _stream_server.Client[_T_Response], + client: _stream_server.ConnectedStreamClient[_T_Response], ) -> None: - self.__client: _stream_server.Client[_T_Response] = client + self.__client: _stream_server.ConnectedStreamClient[_T_Response] = client self.__closing: bool = False self.__send_lock = client.backend().create_lock() self.__proxy: SocketProxy = SocketProxy(client.extra(INETSocketAttribute.socket)) diff --git a/src/easynetwork/servers/async_udp.py b/src/easynetwork/servers/async_udp.py index f63187e9..3afc2109 100644 --- a/src/easynetwork/servers/async_udp.py +++ b/src/easynetwork/servers/async_udp.py @@ -12,7 +12,7 @@ # limitations under the License. # # -"""Asynchronous network server module""" +"""Asynchronous UDP Network client implementation module.""" from __future__ import annotations @@ -31,7 +31,7 @@ from ..lowlevel import _utils from ..lowlevel._final import runtime_final_class from ..lowlevel.api_async.backend.abc import AsyncBackend, CancelScope, IEvent, Task, TaskGroup -from ..lowlevel.api_async.backend.utils import BuiltinAsyncBackendToken, ensure_backend +from ..lowlevel.api_async.backend.utils import BuiltinAsyncBackendLiteral, ensure_backend from ..lowlevel.api_async.servers import datagram as _datagram_server from ..lowlevel.api_async.transports.abc import AsyncDatagramListener from ..lowlevel.socket import INETSocketAttribute, SocketAddress, SocketProxy, new_socket_address @@ -65,7 +65,7 @@ def __init__( port: int, protocol: DatagramProtocol[_T_Response, _T_Request], request_handler: AsyncDatagramRequestHandler[_T_Request, _T_Response], - backend: AsyncBackend | BuiltinAsyncBackendToken | None = None, + backend: AsyncBackend | BuiltinAsyncBackendLiteral | None = None, *, reuse_port: bool = False, logger: logging.Logger | None = None, diff --git a/src/easynetwork/servers/handlers.py b/src/easynetwork/servers/handlers.py index 6ce3dd8e..4be053f4 100644 --- a/src/easynetwork/servers/handlers.py +++ b/src/easynetwork/servers/handlers.py @@ -12,7 +12,7 @@ # limitations under the License. # # -"""Asynchronous network servers' request handler base classes module""" +"""Asynchronous network servers' request handler base classes module.""" from __future__ import annotations diff --git a/src/easynetwork/servers/misc.py b/src/easynetwork/servers/misc.py index 3cbc68ae..55d5e576 100644 --- a/src/easynetwork/servers/misc.py +++ b/src/easynetwork/servers/misc.py @@ -12,7 +12,7 @@ # limitations under the License. # # -"""Asynchronous network server module""" +"""Server implementation tools module.""" from __future__ import annotations @@ -38,16 +38,16 @@ def build_lowlevel_stream_server_handler( initializer: Callable[ - [_lowlevel_stream_server.Client[_T_Response]], + [_lowlevel_stream_server.ConnectedStreamClient[_T_Response]], AbstractAsyncContextManager[AsyncStreamClient[_T_Response] | None], ], request_handler: AsyncStreamRequestHandler[_T_Request, _T_Response], *, logger: logging.Logger | None = None, -) -> Callable[[_lowlevel_stream_server.Client[_T_Response]], AsyncGenerator[float | None, _T_Request]]: +) -> Callable[[_lowlevel_stream_server.ConnectedStreamClient[_T_Response]], AsyncGenerator[float | None, _T_Request]]: """ Creates an :term:`asynchronous generator` function, usable by :meth:`.AsyncStreamServer.serve`, from - an :class:`AsyncStreamRequestHandler`. + an :class:`.AsyncStreamRequestHandler`. Parameters: initializer: a callback returning an :term:`asynchronous context manager` to create the final client interface and @@ -66,7 +66,7 @@ def build_lowlevel_stream_server_handler( from ..lowlevel._asyncgen import SendAction, ThrowAction async def handler( - lowlevel_client: _lowlevel_stream_server.Client[_T_Response], / + lowlevel_client: _lowlevel_stream_server.ConnectedStreamClient[_T_Response], / ) -> AsyncGenerator[float | None, _T_Request]: async with initializer(lowlevel_client) as client, AsyncExitStack() as request_handler_exit_stack: del lowlevel_client @@ -169,7 +169,7 @@ def build_lowlevel_datagram_server_handler( ]: """ Creates an :term:`asynchronous generator` function, usable by :meth:`.AsyncDatagramServer.serve`, from - an :class:`AsyncDatagramRequestHandler`. + an :class:`.AsyncDatagramRequestHandler`. Parameters: initializer: a callback returning an :term:`asynchronous context manager` to create the final client interface and diff --git a/src/easynetwork/servers/standalone_tcp.py b/src/easynetwork/servers/standalone_tcp.py index 322025a9..d9a37a27 100644 --- a/src/easynetwork/servers/standalone_tcp.py +++ b/src/easynetwork/servers/standalone_tcp.py @@ -12,7 +12,7 @@ # limitations under the License. # # -"""Asynchronous network server module""" +"""TCP Network server implementation module.""" from __future__ import annotations @@ -26,7 +26,7 @@ from .._typevars import _T_Request, _T_Response from ..lowlevel.api_async.backend.abc import AsyncBackend -from ..lowlevel.api_async.backend.utils import BuiltinAsyncBackendToken +from ..lowlevel.api_async.backend.utils import BuiltinAsyncBackendLiteral from ..lowlevel.socket import SocketProxy from ..protocol import AnyStreamProtocolType from . import _base @@ -55,7 +55,7 @@ def __init__( port: int, protocol: AnyStreamProtocolType[_T_Response, _T_Request], request_handler: AsyncStreamRequestHandler[_T_Request, _T_Response], - backend: AsyncBackend | BuiltinAsyncBackendToken | None = None, + backend: AsyncBackend | BuiltinAsyncBackendLiteral | None = None, *, runner_options: Mapping[str, Any] | None = None, ssl: _SSLContext | None = None, diff --git a/src/easynetwork/servers/standalone_udp.py b/src/easynetwork/servers/standalone_udp.py index 2bae3389..7f6db9b1 100644 --- a/src/easynetwork/servers/standalone_udp.py +++ b/src/easynetwork/servers/standalone_udp.py @@ -12,7 +12,7 @@ # limitations under the License. # # -"""Asynchronous network server module""" +"""UDP Network client implementation module.""" from __future__ import annotations @@ -26,7 +26,7 @@ from .._typevars import _T_Request, _T_Response from ..lowlevel.api_async.backend.abc import AsyncBackend -from ..lowlevel.api_async.backend.utils import BuiltinAsyncBackendToken +from ..lowlevel.api_async.backend.utils import BuiltinAsyncBackendLiteral from ..lowlevel.socket import SocketProxy from ..protocol import DatagramProtocol from . import _base @@ -52,7 +52,7 @@ def __init__( port: int, protocol: DatagramProtocol[_T_Response, _T_Request], request_handler: AsyncDatagramRequestHandler[_T_Request, _T_Response], - backend: AsyncBackend | BuiltinAsyncBackendToken | None = None, + backend: AsyncBackend | BuiltinAsyncBackendLiteral | None = None, *, runner_options: Mapping[str, Any] | None = None, reuse_port: bool = False, diff --git a/src/easynetwork/servers/threads_helper.py b/src/easynetwork/servers/threads_helper.py index 1af8ab4f..e37230ad 100644 --- a/src/easynetwork/servers/threads_helper.py +++ b/src/easynetwork/servers/threads_helper.py @@ -12,7 +12,7 @@ # limitations under the License. # # -"""Asynchronous network server module""" +"""Server implementation tools module for thread management.""" from __future__ import annotations @@ -78,7 +78,7 @@ def join(self, timeout: float | None = None) -> None: """ Wait until the thread terminates. - This calls the server's :meth:`~AbstractNetworkServer.shutdown` method and then the default `~threading.Thread.join` + This calls the server's :meth:`~AbstractNetworkServer.shutdown` method and then the default :meth:`~threading.Thread.join` method. Parameters: diff --git a/tests/unit_test/test_async/test_lowlevel_api/test_servers/test_stream.py b/tests/unit_test/test_async/test_lowlevel_api/test_servers/test_stream.py index 8932f891..0a1ac0f3 100644 --- a/tests/unit_test/test_async/test_lowlevel_api/test_servers/test_stream.py +++ b/tests/unit_test/test_async/test_lowlevel_api/test_servers/test_stream.py @@ -9,7 +9,7 @@ from typing import TYPE_CHECKING, Any, NoReturn from easynetwork.lowlevel._stream import StreamDataProducer -from easynetwork.lowlevel.api_async.servers.stream import AsyncStreamServer, Client +from easynetwork.lowlevel.api_async.servers.stream import AsyncStreamServer, ConnectedStreamClient from easynetwork.lowlevel.api_async.transports.abc import AsyncListener, AsyncStreamTransport, AsyncStreamWriteTransport from easynetwork.lowlevel.std_asyncio.backend import AsyncIOBackend from easynetwork.lowlevel.std_asyncio.tasks import TaskGroup @@ -29,7 +29,7 @@ @pytest.mark.asyncio -class TestAsyncStreamClient(BaseTestWithStreamProtocol): +class TestConnectedStreamClient(BaseTestWithStreamProtocol): @pytest.fixture @staticmethod def mock_stream_transport(asyncio_backend: AsyncIOBackend, mocker: MockerFixture) -> MagicMock: @@ -51,8 +51,8 @@ def client( mock_stream_transport: MagicMock, mock_stream_protocol: MagicMock, client_exit_stack: contextlib.AsyncExitStack, - ) -> Client[Any]: - return Client( + ) -> ConnectedStreamClient[Any]: + return ConnectedStreamClient( _transport=mock_stream_transport, _producer=StreamDataProducer(mock_stream_protocol), _exit_stack=client_exit_stack, @@ -61,7 +61,7 @@ def client( @pytest.mark.parametrize("transport_closed", [False, True]) async def test____is_closing____default( self, - client: Client[Any], + client: ConnectedStreamClient[Any], mock_stream_transport: MagicMock, transport_closed: bool, ) -> None: @@ -78,7 +78,7 @@ async def test____is_closing____default( async def test____aclose____default( self, - client: Client[Any], + client: ConnectedStreamClient[Any], mock_stream_transport: MagicMock, client_exit_stack: contextlib.AsyncExitStack, mocker: MockerFixture, @@ -97,7 +97,7 @@ async def test____aclose____default( async def test____extra_attributes____default( self, - client: Client[Any], + client: ConnectedStreamClient[Any], mock_stream_transport: MagicMock, mocker: MockerFixture, ) -> None: @@ -112,7 +112,7 @@ async def test____extra_attributes____default( async def test____send_packet____send_bytes_to_transport( self, - client: Client[Any], + client: ConnectedStreamClient[Any], mock_stream_transport: MagicMock, mock_stream_protocol: MagicMock, mocker: MockerFixture,