Merge pull request #55 from Neradoc/fix-documentation-params

Fix documentation

Author: tekktrik

adafruit_wiznet5k/adafruit_wiznet5k.py

@@ -131,6 +131,7 @@
 
 class WIZNET5K:  # pylint: disable=too-many-public-methods
     """Interface for WIZNET5K module.
+
     :param ~busio.SPI spi_bus: The SPI bus the Wiznet module is connected to.
     :param ~digitalio.DigitalInOut cs: Chip select pin.
     :param ~digitalio.DigitalInOut rst: Optional reset pin.
@@ -139,7 +140,6 @@ class WIZNET5K:  # pylint: disable=too-many-public-methods
     :param str hostname: The desired hostname, with optional {} to fill in MAC.
     :param int dhcp_timeout: Timeout in seconds for DHCP response.
     :param bool debug: Enable debugging output.
-
     """
 
     TCP_MODE = const(0x21)
@@ -206,9 +206,9 @@ def set_dhcp(self, hostname=None, response_timeout=30):
         """Initializes the DHCP client and attempts to retrieve
         and set network configuration from the DHCP server.
         Returns 0 if DHCP configured, -1 otherwise.
+
         :param str hostname: The desired hostname, with optional {} to fill in MAC.
         :param int response_timeout: Time to wait for server to return packet, in seconds.
-
         """
         if self._debug:
             print("* Initializing DHCP")
@@ -290,8 +290,8 @@ def mac_address(self):
     @mac_address.setter
     def mac_address(self, address):
         """Sets the hardware MAC address.
-        :param tuple address: Hardware MAC address.
 
+        :param tuple address: Hardware MAC address.
         """
         self.write(REG_SHAR, 0x04, address)
 
@@ -311,8 +311,8 @@ def pretty_mac(self, mac):  # pylint: disable=no-self-use, invalid-name
 
     def remote_ip(self, socket_num):
         """Returns the IP address of the host who sent the current incoming packet.
-        :param int socket num: Desired socket.
 
+        :param int socket num: Desired socket.
         """
         if socket_num >= self.max_sockets:
             return self._pbuff
@@ -441,15 +441,15 @@ def _read_mr(self):
 
     def _write_mr(self, data):
         """Writes to the mode register (MR).
-        :param int data: Data to write to the mode register.
 
+        :param int data: Data to write to the mode register.
         """
         self.write(REG_MR, 0x04, data)
 
     def read(self, addr, callback, length=1, buffer=None):
         """Reads data from a register address.
-        :param int addr: Register address.
 
+        :param int addr: Register address.
         """
         with self._device as bus_device:
             if self._chip_type == "w5500":
@@ -471,11 +471,11 @@ def read(self, addr, callback, length=1, buffer=None):
 
     def write(self, addr, callback, data):
         """Write data to a register address.
+
         :param int addr: Destination address.
         :param int callback: Callback reference.
         :param int data: Data to write, as an integer.
         :param bytearray data: Data to write, as a bytearray.
-
         """
         with self._device as bus_device:
             if self._chip_type == "w5500":
@@ -602,9 +602,10 @@ def get_socket(self):
 
     def socket_listen(self, socket_num, port, conn_mode=SNMR_TCP):
         """Start listening on a socket (default TCP mode).
-        :parm int socket_num: socket number
-        :parm int port: port to listen on
-        :parm int conn_mode: connection mode SNMR_TCP (default) or SNMR_UDP
+
+        :param int socket_num: socket number
+        :param int port: port to listen on
+        :param int conn_mode: connection mode SNMR_TCP (default) or SNMR_UDP
         """
         assert self.link_status, "Ethernet cable disconnected!"
         if self._debug:
@@ -631,7 +632,8 @@ def socket_listen(self, socket_num, port, conn_mode=SNMR_TCP):
     def socket_accept(self, socket_num):
         """Gets the dest IP and port from an incoming connection.
         Returns the next socket number so listening can continue
-        :parm int socket_num: socket number
+
+        :param int socket_num: socket number
         """
         dest_ip = self.remote_ip(socket_num)
         dest_port = self.remote_port(socket_num)
@@ -704,7 +706,6 @@ def socket_disconnect(self, socket_num):
     def socket_read(self, socket_num, length):
         """Reads data from a socket into a buffer.
         Returns buffer.
-
         """
         assert self.link_status, "Ethernet cable disconnected!"
         assert socket_num <= self.max_sockets, "Provided socket exceeds max_sockets."
@@ -840,17 +841,13 @@ def socket_write(self, socket_num, buffer, timeout=0):
         while (
             self._read_socket(socket_num, REG_SNIR)[0] & SNIR_SEND_OK
         ) != SNIR_SEND_OK:
-            if (
-                self.socket_status(socket_num)[0]
-                in (
-                    SNSR_SOCK_CLOSED,
-                    SNSR_SOCK_TIME_WAIT,
-                    SNSR_SOCK_FIN_WAIT,
-                    SNSR_SOCK_CLOSE_WAIT,
-                    SNSR_SOCK_CLOSING,
-                )
-                or (timeout and time.monotonic() - stamp > timeout)
-            ):
+            if self.socket_status(socket_num)[0] in (
+                SNSR_SOCK_CLOSED,
+                SNSR_SOCK_TIME_WAIT,
+                SNSR_SOCK_FIN_WAIT,
+                SNSR_SOCK_CLOSE_WAIT,
+                SNSR_SOCK_CLOSING,
+            ) or (timeout and time.monotonic() - stamp > timeout):
                 # self.socket_close(socket_num)
                 return 0
             time.sleep(0.01)

adafruit_wiznet5k/adafruit_wiznet5k_dhcp.py

@@ -80,6 +80,7 @@
 
 class DHCP:
     """W5k DHCP Client implementation.
+
     :param eth: Wiznet 5k object
     :param list mac_address: Hardware MAC.
     :param str hostname: The desired hostname, with optional {} to fill in MAC.
@@ -134,6 +135,7 @@ def __init__(
     # pylint: disable=too-many-statements
     def send_dhcp_message(self, state, time_elapsed, renew=False):
         """Assemble and send a DHCP message packet to a socket.
+
         :param int state: DHCP Message state.
         :param float time_elapsed: Number of seconds elapsed since DHCP process started
         :param bool renew: Set True for renew and rebind
@@ -470,14 +472,10 @@ def _dhcp_state_machine(self):
                 if self._debug:
                     print("* DHCP: Time to renew lease")
 
-        if (
-            self._dhcp_state
-            in (
-                STATE_DHCP_DISCOVER,
-                STATE_DHCP_REQUEST,
-            )
-            and time.monotonic() > (self._start_time + self._response_timeout)
-        ):
+        if self._dhcp_state in (
+            STATE_DHCP_DISCOVER,
+            STATE_DHCP_REQUEST,
+        ) and time.monotonic() > (self._start_time + self._response_timeout):
             self._dhcp_state = STATE_DHCP_WAIT
             if self._sock is not None:
                 self._sock.close()

adafruit_wiznet5k/adafruit_wiznet5k_dns.py

@@ -58,6 +58,7 @@ def __init__(self, iface, dns_address, debug=False):
 
     def gethostbyname(self, hostname):
         """Translate a host name to IPv4 address format.
+
         :param str hostname: Desired host name to connect to.
 
         Returns the IPv4 address as a bytearray if successful, -1 otherwise.

adafruit_wiznet5k/adafruit_wiznet5k_ntp.py

@@ -3,7 +3,7 @@
 # SPDX-License-Identifier: MIT
 
 """
-`wiznet5k_ntp`
+`adafruit_wiznet5k_ntp`
 ================================================================================
 
 Network Time Protocol (NTP) helper for CircuitPython
@@ -27,6 +27,7 @@
 class NTP:
     """
     Wiznet5k NTP Client
+
     :param iface: Wiznet 5k object
     :param str ntp_address: The hostname of the NTP server
     :param int utc: Numbers of hours to offset time from UTC
@@ -50,6 +51,7 @@ def __init__(self, iface, ntp_address, utc, debug=False):
     def get_time(self):
         """
         Get the time from the NTP server
+
         :return: time in seconds since the epoch
         """
         self._sock.bind((None, 50001))

adafruit_wiznet5k/adafruit_wiznet5k_socket.py

@@ -64,6 +64,7 @@ def getaddrinfo(host, port, family=0, socktype=0, proto=0, flags=0):
 def gethostbyname(hostname):
     """Translate a host name to IPv4 address format. The IPv4 address
     is returned as a string.
+
     :param str hostname: Desired hostname.
     """
     addr = _the_interface.get_host_by_name(hostname)
@@ -73,6 +74,7 @@ def gethostbyname(hostname):
 
 def is_ipv4(host):
     """Checks if a host string is an IPv4 address.
+
     :param str host: host's name or ip
     """
     octets = host.split(".", 3)
@@ -88,9 +90,9 @@ def is_ipv4(host):
 class socket:
     """A simplified implementation of the Python 'socket' class
     for connecting to a Wiznet5k module.
+
     :param int family: Socket address (and protocol) family.
     :param int type: Socket type.
-
     """
 
     # pylint: disable=redefined-builtin,unused-argument
@@ -162,8 +164,8 @@ def getpeername(self):
 
     def inet_aton(self, ip_string):
         """Convert an IPv4 address from dotted-quad string format.
-        :param str ip_string: IP Address, as a dotted-quad string.
 
+        :param str ip_string: IP Address, as a dotted-quad string.
         """
         self._buffer = b""
         self._buffer = [int(item) for item in ip_string.split(".")]
@@ -173,6 +175,7 @@ def inet_aton(self, ip_string):
     def bind(self, address):
         """Bind the socket to the listen port, if host is specified the interface
         will be reconfigured to that IP.
+
         :param tuple address: local socket as a (host, port) tuple.
         """
         if address[0] is not None:
@@ -191,6 +194,7 @@ def bind(self, address):
 
     def listen(self, backlog=None):
         """Listen on the port specified by bind.
+
         :param backlog: For compatibility but ignored.
         """
         assert self._listen_port is not None, "Use bind to set the port before listen!"
@@ -228,6 +232,7 @@ def accept(self):
 
     def connect(self, address, conntype=None):
         """Connect to a remote socket at address.
+
         :param tuple address: Remote socket as a (host, port) tuple.
         """
         assert (
@@ -253,6 +258,7 @@ def connect(self, address, conntype=None):
     def send(self, data):
         """Send data to the socket. The socket must be connected to
         a remote socket.
+
         :param bytearray data: Desired data to send to the socket.
         """
         _the_interface.socket_write(self.socknum, data, self._timeout)
@@ -261,6 +267,7 @@ def send(self, data):
     def sendto(self, data, address):
         """Send data to the socket. The socket must be connected to
         a remote socket.
+
         :param bytearray data: Desired data to send to the socket.
         :param tuple address: Remote socket as a (host, port) tuple.
         """
@@ -269,6 +276,7 @@ def sendto(self, data, address):
 
     def recv(self, bufsize=0, flags=0):  # pylint: disable=too-many-branches
         """Reads some bytes from the connected remote address.
+
         :param int bufsize: Maximum number of bytes to receive.
         :param int flags: ignored, present for compatibility.
         """
@@ -327,9 +335,10 @@ def recv(self, bufsize=0, flags=0):  # pylint: disable=too-many-branches
 
     def recvfrom(self, bufsize=0, flags=0):
         """Reads some bytes from the connected remote address.
+
         :param int bufsize: Maximum number of bytes to receive.
         :param int flags: ignored, present for compatibility.
-        :returns: a tuple (bytes, address) where address is a tuple (ip, port)
+        :return: a tuple (bytes, address) where address is a tuple (ip, port)
         """
         return (
             self.recv(bufsize),
@@ -341,10 +350,11 @@ def recvfrom(self, bufsize=0, flags=0):
 
     def recv_into(self, buf, nbytes=0, flags=0):
         """Reads some bytes from the connected remote address info the provided buffer.
+
         :param bytearray buf: Data buffer
         :param nbytes: Maximum number of bytes to receive
         :param int flags: ignored, present for compatibility.
-        :returns: the number of bytes received
+        :return: the number of bytes received
         """
         if nbytes == 0:
             nbytes = len(buf)
@@ -355,10 +365,11 @@ def recv_into(self, buf, nbytes=0, flags=0):
 
     def recvfrom_into(self, buf, nbytes=0, flags=0):
         """Reads some bytes from the connected remote address info the provided buffer.
+
         :param bytearray buf: Data buffer
         :param nbytes: Maximum number of bytes to receive
         :param int flags: ignored, present for compatibility.
-        :returns a tuple (nbytes, address) where address is a tuple (ip, port)
+        :return: a tuple (nbytes, address) where address is a tuple (ip, port)
         """
         return (
             self.recv_into(buf, nbytes),
@@ -371,7 +382,6 @@ def recvfrom_into(self, buf, nbytes=0, flags=0):
     def readline(self):
         """Attempt to return as many bytes as we can up to \
         but not including '\r\n'.
-
         """
         stamp = time.monotonic()
         while b"\r\n" not in self._buffer:
@@ -407,8 +417,8 @@ def available(self):
 
     def settimeout(self, value):
         """Sets socket read timeout.
-        :param int value: Socket read timeout, in seconds.
 
+        :param int value: Socket read timeout, in seconds.
         """
         if value < 0:
             raise Exception("Timeout period should be non-negative.")
@@ -417,6 +427,5 @@ def settimeout(self, value):
     def gettimeout(self):
         """Return the timeout in seconds (float) associated
         with socket operations, or None if no timeout is set.
-
         """
         return self._timeout

docs/api.rst

@@ -12,3 +12,12 @@
 
 .. automodule:: adafruit_wiznet5k.adafruit_wiznet5k_dhcp
    :members:
+
+.. automodule:: adafruit_wiznet5k.adafruit_wiznet5k_ntp
+   :members:
+
+.. automodule:: adafruit_wiznet5k.adafruit_wiznet5k_dns
+   :members:
+
+.. automodule:: adafruit_wiznet5k.adafruit_wiznet5k_wsgiserver
+   :members: