Edited doc-strings to compile in Sphinx. Added missing :return: in socket.

Author: BiffoBear

adafruit_wiznet5k/adafruit_wiznet5k.py

@@ -26,6 +26,10 @@
 
 * Adafruit's Bus Device library: https://github.com/adafruit/Adafruit_CircuitPython_BusDevice
 """
+
+__version__ = "0.0.0+auto.0"
+__repo__ = "https://github.com/adafruit/Adafruit_CircuitPython_Wiznet5k.git"
+
 # pylint: disable=too-many-lines
 try:
     from typing import Optional, Union, List, Tuple, Sequence
@@ -43,11 +47,6 @@
 import adafruit_wiznet5k.adafruit_wiznet5k_dhcp as dhcp
 import adafruit_wiznet5k.adafruit_wiznet5k_dns as dns
 
-
-__version__ = "0.0.0+auto.0"
-__repo__ = "https://github.com/adafruit/Adafruit_CircuitPython_Wiznet5k.git"
-
-
 # Wiznet5k Registers
 REG_MR = const(0x0000)  # Mode
 REG_GAR = const(0x0001)  # Gateway IP Address
@@ -223,7 +222,7 @@ def set_dhcp(
         :param Optional[str] hostname: The desired hostname for the DHCP server with optional {} to
             fill in the MAC address, defaults to None.
         :param float response_timeout: Time to wait for server to return packet in seconds,
-            defaults to 30.
+            defaults to 30.0.
 
         :return int: 0 if DHCP configured, -1 otherwise.
         """
@@ -359,7 +358,6 @@ def pretty_mac(
         :param bytearray mac: The MAC address.
 
         :return str: Mac Address in the form 00:00:00:00:00:00
-
         """
         return "%s:%s:%s:%s:%s:%s" % (
             hex(mac[0]),
@@ -420,7 +418,7 @@ def ifconfig(
         Network configuration information.
 
         :return Tuple[bytearray, bytearray, bytearray, Tuple[int, int, int, int]]: \
-        The IP address, subnet mask, gateway address and DNS server address."""
+            The IP address, subnet mask, gateway address and DNS server address."""
         return (
             self.ip_address,
             self.read(REG_SUBR, 0x00, 4),
@@ -435,8 +433,8 @@ def ifconfig(
         """
         Set network configuration.
 
-        :params Tuple[bytearray, bytearray, bytearray, Tuple[int, int, int, int]]: \
-        Configuration settings - (ip_address, subnet_mask, gateway_address, dns_server).
+        :param Tuple[bytearray, bytearray, bytearray, Tuple[int, int, int, int]]:
+            Configuration settings - (ip_address, subnet_mask, gateway_address, dns_server).
         """
         ip_address, subnet_mask, gateway_address, dns_server = params
 
@@ -606,12 +604,11 @@ def write(
 
     def socket_available(self, socket_num: int, sock_type: int = SNMR_TCP) -> int:
         """
-        Return the number of bytes available to be read from the socket.
+        Number of bytes available to be read from the socket.
 
         :param int socket_num: Socket to check for available bytes.
         :param int sock_type: Socket type. Use SNMR_TCP for TCP or SNMR_UDP for UDP, \
-        defaults to SNMR_TCP.
-
+            defaults to SNMR_TCP.
         :return int: Number of bytes available to read.
         """
         if self._debug:
@@ -642,7 +639,7 @@ def socket_available(self, socket_num: int, sock_type: int = SNMR_TCP) -> int:
 
     def socket_status(self, socket_num: int) -> Optional[bytearray]:
         """
-        Return the socket connection status.
+        Socket connection status.
 
         Can be: SNSR_SOCK_CLOSED, SNSR_SOCK_INIT, SNSR_SOCK_LISTEN, SNSR_SOCK_SYNSENT,
         SNSR_SOCK_SYNRECV, SNSR_SYN_SOCK_ESTABLISHED, SNSR_SOCK_FIN_WAIT,
@@ -671,7 +668,7 @@ def socket_connect(
         :param Union[bytes, bytearray] dest: The destination as a host name or IP address.
         :param int port: Port to connect to (0 - 65,536).
         :param int conn_mode: The connection mode. Use SNMR_TCP for TCP or SNMR_UDP for UDP,
-        defaults to SNMR_TCP.
+            defaults to SNMR_TCP.
         """
         assert self.link_status, "Ethernet cable disconnected!"
         if self._debug:
@@ -712,7 +709,7 @@ def _send_socket_cmd(self, socket: int, cmd: int) -> None:
     def get_socket(self) -> int:
         """Request, allocate and return a socket from the W5k chip.
 
-        Cycles through the sockets to find the first available one, if any.
+        Cycle through the sockets to find the first available one, if any.
 
         :return int: The first available socket. Returns 0xFF if no sockets are free.
         """
@@ -773,7 +770,6 @@ def socket_accept(
         the IP address and port of the incoming connection.
 
         :param int socket_num: Socket number with connection to check.
-
         :return Tuple[int, Tuple[Union[str, bytearray], Union[int, bytearray]]]:
             If successful, the next (socket number, (destination IP address, destination port)).
 
@@ -799,8 +795,7 @@ def socket_open(self, socket_num: int, conn_mode: int = SNMR_TCP) -> int:
 
         :param int socket_num: The socket number to open.
         :param int conn_mode: The protocol to use. Use SNMR_TCP for TCP or SNMR_UDP for \
-        UDP, defaults to SNMR_TCP.
-
+            UDP, defaults to SNMR_TCP.
         :return int: 1 if the socket was opened, 0 if not.
         """
         assert self.link_status, "Ethernet cable disconnected!"
@@ -874,9 +869,9 @@ def socket_read(
         :param int length: The number of bytes to read from the socket.
 
         :return Tuple[int, Union[int, bytearray]]: If the read was successful then the first
-        item of the tuple is the length of the data and the second is the data. If the read
-        was unsuccessful then both items equal an error code, 0 for no data waiting and -1
-        for no connection to the socket.
+            item of the tuple is the length of the data and the second is the data. If the read
+            was unsuccessful then both items equal an error code, 0 for no data waiting and -1
+            for no connection to the socket.
         """
         assert self.link_status, "Ethernet cable disconnected!"
         assert socket_num <= self.max_sockets, "Provided socket exceeds max_sockets."

adafruit_wiznet5k/adafruit_wiznet5k_dhcp.py

@@ -369,7 +369,7 @@ def parse_dhcp_response(
     # pylint: disable=too-many-branches, too-many-statements
     def _dhcp_state_machine(self) -> None:
         """
-        DHCP state machine without wait loops to enable cooperative multitasking
+        DHCP state machine without wait loops to enable cooperative multitasking.
         This state machine is used both by the initial blocking lease request and
         the non-blocking DHCP maintenance function.
         """

adafruit_wiznet5k/adafruit_wiznet5k_socket.py

@@ -86,8 +86,8 @@ def getaddrinfo(
     flags: int = 0,
 ) -> List[Tuple[int, int, int, str, Tuple[str, int]]]:
     """
-    Translate the host/port argument into a sequence of 5-tuples that
-    contain all the necessary arguments for creating a socket connected to that service.
+    Translate the host/port argument into a sequence of 5-tuples that contain all the necessary
+    arguments for creating a socket connected to that service.
 
     :param str host: a domain name, a string representation of an IPv4/v6 address or
         None.
@@ -97,6 +97,8 @@ def getaddrinfo(
         for UDP, defaults to 0x00.
     :param int proto: Unused in this implementation of socket.
     :param int flags: Unused in this implementation of socket.
+
+    :return List[Tuple[int, int, int, str, Tuple[str, int]]]: Address info entries.
     """
     if not isinstance(port, int):
         raise RuntimeError("Port must be an integer")
@@ -191,7 +193,7 @@ def socknum(self) -> int:
         """
         Return the socket object's socket number.
 
-        :return int: The socket number
+        :return int: Socket number.
         """
         return self._socknum
 
@@ -259,7 +261,7 @@ def bind(self, address: Tuple[Optional[str], int]) -> None:
 
         :param Tuple[Optional[str], int] address: Address as a (host, port) tuple. The host
             may be an IPv4 address (a string of the form '255.255.255.255'), or None.
-            The port number is in the range (0- 65536).
+            The port number is in the range (0 - 65536).
         """
         if address[0] is not None:
             ip_address = _the_interface.unpretty_ip(address[0])
@@ -279,7 +281,7 @@ def listen(self, backlog: Optional[Any] = None) -> None:
         """
         Listen on the port specified by bind.
 
-        :param backlog: For compatibility but ignored.
+        :param Optional[Any] backlog: Included for compatibility but ignored.
         """
         assert self._listen_port is not None, "Use bind to set the port before listen!"
         _the_interface.socket_listen(self.socknum, self._listen_port)
@@ -373,7 +375,7 @@ def sendto(self, data: bytearray, address: [Tuple[str, int]]) -> None:
         """
         Connect to a remote socket and send data.
 
-        :param bytearray data: Desired data to send to the socket.
+        :param bytearray data: Data to send to the socket.
         :param tuple address: Remote socket as a (host, port) tuple.
         """
         self.connect(address)
@@ -390,6 +392,8 @@ def recv(
 
         :param int bufsize: Maximum number of bytes to receive.
         :param int flags: ignored, present for compatibility.
+
+        :return bytes: Data from the remote address.
         """
         if self.status == wiznet5k.adafruit_wiznet5k.SNSR_SOCK_CLOSED:
             return b""
@@ -501,7 +505,7 @@ def recv_into(self, buf: bytearray, nbytes: int = 0, flags: Any = 0) -> int:
         :param nbytes: Maximum number of bytes to receive
         :param Any flags: ignored, present for compatibility.
 
-        :return: the number of bytes received
+        :return int: the number of bytes received
         """
         if nbytes == 0:
             nbytes = len(buf)
@@ -520,7 +524,8 @@ def recvfrom_into(
         :param int nbytes: Maximum number of bytes to receive.
         :param int flags: Unused, present for compatibility.
 
-        :return: A tuple (nbytes, address) where address is a tuple (ip, port)
+        :return Tuple[int, Tuple[str, int]]: A tuple (nbytes, address) where address is a
+            tuple (ip, port)
         """
         return (
             self.recv_into(buf, nbytes),
@@ -534,7 +539,8 @@ def readline(self) -> bytes:
         """
         Read a line from the socket.
 
-        Attempt to return as many bytes as we can up to but not including '\r\n'.
+        Attempt to return as many bytes as we can up to but not including carriage return and
+        linefeed charater pairs.
 
         :return bytes: The data read from the socket.
         """

adafruit_wiznet5k/adafruit_wiznet5k_wsgiserver.py

@@ -27,7 +27,6 @@
 * Author(s): Matt Costi, Patrick Van Oosterwijck
 """
 # pylint: disable=no-name-in-module
-# from __future__ import annotations
 try:
     from typing import Optional, List, Tuple, Dict
     from adafruit_wiznet5k.adafruit_wiznet5k import WIZNET5K