Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Documentation: Rewritten all docstrings #310

Merged
merged 1 commit into from
Jun 28, 2024
Merged

Documentation: Rewritten all docstrings #310

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions docs/source/_include/examples/howto/udp_servers/request_handler_explanation.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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

...
Expand Down
2 changes: 1 addition & 1 deletion docs/source/_include/examples/tutorials/ftp_server/ftp_request.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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."""
Expand Down
4 changes: 0 additions & 4 deletions docs/source/_include/see-also-optional-dependencies.rst
View file
Open in desktop

This file was deleted.

28 changes: 10 additions & 18 deletions docs/source/api/clients/index.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,53 +9,45 @@ 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:


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:
11 changes: 10 additions & 1 deletion docs/source/api/lowlevel/async/backend.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,8 @@
Asynchronous Backend Engine API
*******************************

.. automodule:: easynetwork.lowlevel.api_async.backend

.. contents:: Table of Contents
:local:
:depth: 1
Expand All @@ -20,7 +22,6 @@ Backend Interface
=================

.. automodule:: easynetwork.lowlevel.api_async.backend.abc
:no-docstring:

.. autoclass:: AsyncBackend

Expand Down Expand Up @@ -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:
9 changes: 7 additions & 2 deletions docs/source/api/lowlevel/async/endpoints.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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:
20 changes: 14 additions & 6 deletions docs/source/api/lowlevel/async/servers.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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__
10 changes: 7 additions & 3 deletions docs/source/api/lowlevel/async/transports.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,25 +2,29 @@
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
=============

.. automodule:: easynetwork.lowlevel.api_async.transports.utils
:members:
:no-docstring:
5 changes: 0 additions & 5 deletions docs/source/api/lowlevel/futures.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
9 changes: 7 additions & 2 deletions docs/source/api/lowlevel/sync/endpoints.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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:
10 changes: 7 additions & 3 deletions docs/source/api/lowlevel/sync/transports.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
==============================
Expand All @@ -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:
4 changes: 0 additions & 4 deletions docs/source/api/serializers/abc.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11,7 +11,6 @@ Top-Level Base Classes
======================

.. automodule:: easynetwork.serializers.abc
:no-docstring:
:members:


Expand All @@ -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:
8 changes: 1 addition & 7 deletions docs/source/api/serializers/cbor.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,20 +2,14 @@
CBOR Serializer
***************

.. currentmodule:: easynetwork.serializers

The `CBOR <https://cbor.io>`_ is an alternative representation of the ``JSON`` data models.

.. include:: ../../_include/see-also-optional-dependencies.rst
.. automodule:: easynetwork.serializers.cbor

.. autoclass:: CBORSerializer
:members:

Configuration
=============

.. currentmodule:: easynetwork.serializers.cbor

.. autoclass:: CBOREncoderConfig
:members:

Expand Down
4 changes: 1 addition & 3 deletions docs/source/api/serializers/json.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,16 +2,14 @@
JSON Serializer
***************

.. currentmodule:: easynetwork.serializers
.. automodule:: easynetwork.serializers.json

.. autoclass:: JSONSerializer
:members:

Configuration
=============

.. currentmodule:: easynetwork.serializers.json

.. autoclass:: JSONEncoderConfig
:members:

Expand Down
2 changes: 1 addition & 1 deletion docs/source/api/serializers/line.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@
String Serializer
*****************

.. currentmodule:: easynetwork.serializers
.. automodule:: easynetwork.serializers.line

.. autoclass:: StringLineSerializer
:members:
8 changes: 1 addition & 7 deletions docs/source/api/serializers/msgpack.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,20 +2,14 @@
MessagePack Serializer
**********************

.. currentmodule:: easynetwork.serializers

The `MessagePack <https://msgpack.org/>`_ is an alternative representation of the ``JSON`` data models.

.. include:: ../../_include/see-also-optional-dependencies.rst
.. automodule:: easynetwork.serializers.msgpack

.. autoclass:: MessagePackSerializer
:members:

Configuration
=============

.. currentmodule:: easynetwork.serializers.msgpack

.. autoclass:: MessagePackerConfig
:members:

Expand Down
4 changes: 1 addition & 3 deletions docs/source/api/serializers/pickle.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@
Pickle Serializer
*****************

.. currentmodule:: easynetwork.serializers
.. automodule:: easynetwork.serializers.pickle

.. warning::

Expand All @@ -18,8 +18,6 @@ Pickle Serializer
Configuration
=============

.. currentmodule:: easynetwork.serializers.pickle

.. autoclass:: PicklerConfig
:members:

Expand Down
Loading