[DOCS] Added How-to guide for UDP clients

docs/source/_include/examples/howto/udp_clients/basics/api_async/connection_example1.py

@@ -0,0 +1,21 @@
+from __future__ import annotations
+
+import asyncio
+
+from easynetwork.api_async.client import AsyncUDPNetworkClient
+from easynetwork.protocol import DatagramProtocol
+from easynetwork.serializers import JSONSerializer
+
+
+async def main() -> None:
+    protocol = DatagramProtocol(JSONSerializer())
+    address = ("localhost", 9000)
+
+    async with AsyncUDPNetworkClient(address, protocol) as client:
+        print(f"Remote address: {client.get_remote_address()}")
+
+        ...
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

docs/source/_include/examples/howto/udp_clients/basics/api_async/socket_example1.py

@@ -0,0 +1,30 @@
+from __future__ import annotations
+
+import asyncio
+import socket
+
+from easynetwork.api_async.client import AsyncUDPNetworkClient
+from easynetwork.protocol import DatagramProtocol
+from easynetwork.serializers import JSONSerializer
+
+
+async def obtain_a_connected_socket() -> socket.socket:
+    sock = socket.socket(socket.AF_INET, socket.SOCK_DGRAM)
+
+    ...
+
+    return sock
+
+
+async def main() -> None:
+    protocol = DatagramProtocol(JSONSerializer())
+    sock = await obtain_a_connected_socket()
+
+    async with AsyncUDPNetworkClient(sock, protocol) as client:
+        print(f"Remote address: {client.get_remote_address()}")
+
+        ...
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

docs/source/_include/examples/howto/udp_clients/basics/api_sync/connection_example1.py

@@ -0,0 +1,19 @@
+from __future__ import annotations
+
+from easynetwork.api_sync.client import UDPNetworkClient
+from easynetwork.protocol import DatagramProtocol
+from easynetwork.serializers import JSONSerializer
+
+
+def main() -> None:
+    protocol = DatagramProtocol(JSONSerializer())
+    address = ("127.0.0.1", 9000)
+
+    with UDPNetworkClient(address, protocol) as client:
+        print(f"Remote address: {client.get_remote_address()}")
+
+        ...
+
+
+if __name__ == "__main__":
+    main()

docs/source/_include/examples/howto/udp_clients/basics/api_sync/socket_example1.py

@@ -0,0 +1,29 @@
+from __future__ import annotations
+
+import socket
+
+from easynetwork.api_sync.client import UDPNetworkClient
+from easynetwork.protocol import DatagramProtocol
+from easynetwork.serializers import JSONSerializer
+
+
+def obtain_a_connected_socket() -> socket.socket:
+    sock = socket.socket(socket.AF_INET, socket.SOCK_DGRAM)
+
+    ...
+
+    return sock
+
+
+def main() -> None:
+    protocol = DatagramProtocol(JSONSerializer())
+    sock = obtain_a_connected_socket()
+
+    with UDPNetworkClient(sock, protocol) as client:
+        print(f"Remote address: {client.get_remote_address()}")
+
+        ...
+
+
+if __name__ == "__main__":
+    main()

docs/source/_include/examples/howto/udp_clients/usage/api_async.py

@@ -0,0 +1,67 @@
+from __future__ import annotations
+
+import asyncio
+import socket
+from typing import Any
+
+from easynetwork.api_async.client import AsyncUDPNetworkClient
+from easynetwork.exceptions import DatagramProtocolParseError
+
+###############
+# Basic usage #
+###############
+
+
+async def send_packet_example1(client: AsyncUDPNetworkClient[Any, Any]) -> None:
+    # [start]
+    await client.send_packet({"data": 42})
+
+
+async def recv_packet_example1(client: AsyncUDPNetworkClient[Any, Any]) -> None:
+    # [start]
+    packet = await client.recv_packet()
+    print(f"Received packet: {packet!r}")
+
+
+async def recv_packet_example2(client: AsyncUDPNetworkClient[Any, Any]) -> None:
+    # [start]
+    try:
+        async with asyncio.timeout(30):
+            packet = await client.recv_packet()
+    except TimeoutError:
+        print("Timed out")
+    else:
+        print(f"Received packet: {packet!r}")
+
+
+async def recv_packet_example3(client: AsyncUDPNetworkClient[Any, Any]) -> None:
+    # [start]
+    try:
+        async with asyncio.timeout(30):
+            packet = await client.recv_packet()
+    except DatagramProtocolParseError:
+        print("Received something, but was not valid")
+    except TimeoutError:
+        print("Timed out")
+    else:
+        print(f"Received packet: {packet!r}")
+
+
+async def recv_packet_example4(client: AsyncUDPNetworkClient[Any, Any]) -> None:
+    # [start]
+    all_packets = [p async for p in client.iter_received_packets()]
+
+
+async def recv_packet_example5(client: AsyncUDPNetworkClient[Any, Any]) -> None:
+    # [start]
+    all_packets = [p async for p in client.iter_received_packets(timeout=1)]
+
+
+##################
+# Advanced usage #
+##################
+
+
+async def socket_proxy_example(client: AsyncUDPNetworkClient[Any, Any]) -> None:
+    # [start]
+    client.socket.setsockopt(socket.SOL_SOCKET, socket.SO_BROADCAST, True)

docs/source/_include/examples/howto/udp_clients/usage/api_sync.py

@@ -0,0 +1,64 @@
+from __future__ import annotations
+
+import socket
+from typing import Any
+
+from easynetwork.api_sync.client import UDPNetworkClient
+from easynetwork.exceptions import DatagramProtocolParseError
+
+###############
+# Basic usage #
+###############
+
+
+def send_packet_example1(client: UDPNetworkClient[Any, Any]) -> None:
+    # [start]
+    client.send_packet({"data": 42})
+
+
+def recv_packet_example1(client: UDPNetworkClient[Any, Any]) -> None:
+    # [start]
+    packet = client.recv_packet()
+    print(f"Received packet: {packet!r}")
+
+
+def recv_packet_example2(client: UDPNetworkClient[Any, Any]) -> None:
+    # [start]
+    try:
+        packet = client.recv_packet(timeout=30)
+    except TimeoutError:
+        print("Timed out")
+    else:
+        print(f"Received packet: {packet!r}")
+
+
+def recv_packet_example3(client: UDPNetworkClient[Any, Any]) -> None:
+    # [start]
+    try:
+        packet = client.recv_packet(timeout=30)
+    except DatagramProtocolParseError:
+        print("Received something, but was not valid")
+    except TimeoutError:
+        print("Timed out")
+    else:
+        print(f"Received packet: {packet!r}")
+
+
+def recv_packet_example4(client: UDPNetworkClient[Any, Any]) -> None:
+    # [start]
+    all_packets = [p for p in client.iter_received_packets()]
+
+
+def recv_packet_example5(client: UDPNetworkClient[Any, Any]) -> None:
+    # [start]
+    all_packets = [p for p in client.iter_received_packets(timeout=1)]
+
+
+##################
+# Advanced usage #
+##################
+
+
+def socket_proxy_example(client: UDPNetworkClient[Any, Any]) -> None:
+    # [start]
+    client.socket.setsockopt(socket.SOL_SOCKET, socket.SO_BROADCAST, True)

docs/source/howto/index.rst

@@ -9,3 +9,4 @@ How-to Guide
    serializers
    tcp_clients
    tcp_servers
+   udp_clients