Merge pull request #7 from brentru/update-property-docstrings

Rewrite properties documentation

Author: tannewt

adafruit_fona/adafruit_fona.py

@@ -44,7 +44,6 @@
 __version__ = "0.0.0-auto.0"
 __repo__ = "https://github.com/adafruit/Adafruit_CircuitPython_FONA.git"
 
-# pylint: disable=bad-whitespace
 FONA_DEFAULT_TIMEOUT_MS = 500  # TODO: Check this against arduino...
 
 # Commands
@@ -67,7 +66,6 @@
 # FONA preferred SMS storage
 FONA_SMS_STORAGE_SIM = b'"SM"'  # Storage on the SIM
 FONA_SMS_STORAGE_INTERNAL = b'"ME"'  # Internal storage on the FONA
-# pylint: enable=bad-whitespace
 
 
 # pylint: disable=too-many-instance-attributes, too-many-public-methods
@@ -177,12 +175,14 @@ def reset(self):
     @property
     # pylint: disable=too-many-return-statements
     def version(self):
-        """Returns FONA Version."""
+        """The version of the FONA module. Can be FONA_800_L,
+        FONA_800_H, FONA_808_V1, FONA_808_V2, FONA_3G_A, FONA3G_E.
+        """
         return self._fona_type
 
     @property
     def iemi(self):
-        """Returns FONA module's IEMI number."""
+        """FONA Module's IEMI (International Mobile Equipment Identity) number."""
         if self._debug:
             print("FONA IEMI")
         self._uart.reset_input_buffer()
@@ -194,18 +194,18 @@ def iemi(self):
 
     @property
     def local_ip(self):
-        """Returns the local IP Address, False if not set."""
+        """Module's local IP address, None if not set."""
         self._uart_write(b"AT+CIFSR\r\n")
         self._read_line()
         try:
             ip_addr = self.pretty_ip(self._buf)
         except ValueError:
-            return False
+            return None
         return ip_addr
 
     @property
     def iccid(self):
-        """Returns SIM Card's ICCID number as a string."""
+        """SIM Card's unique ICCID (Integrated Circuit Card Identifier)."""
         if self._debug:
             print("ICCID")
         self._uart_write(b"AT+CCID\r\n")
@@ -215,7 +215,7 @@ def iccid(self):
 
     @property
     def gprs(self):
-        """Returns module's GPRS state."""
+        """GPRS (General Packet Radio Services) power status."""
         if not self._send_parse_reply(b"AT+CGATT?", b"+CGATT: ", ":"):
             return False
         if not self._buf:
@@ -311,7 +311,7 @@ def set_gprs(self, apn=None, enable=True):
 
     @property
     def network_status(self):
-        """Returns cellular network status"""
+        """The status of the cellular network."""
         self._read_line()
         if self._debug:
             print("Network status")
@@ -324,7 +324,9 @@ def network_status(self):
 
     @property
     def rssi(self):
-        """Returns cellular network's Received Signal Strength Indicator (RSSI)."""
+        """The received signal strength indicator for the cellular network
+        we are connected to.
+        """
         if self._debug:
             print("RSSI")
         if not self._send_parse_reply(b"AT+CSQ", b"+CSQ: "):
@@ -347,7 +349,7 @@ def rssi(self):
 
     @property
     def gps(self):
-        """Returns the GPS fix."""
+        """Module's GPS status."""
         if self._debug:
             print("GPS Fix")
         if self._fona_type == FONA_808_V2:
@@ -370,10 +372,6 @@ def gps(self):
 
     @gps.setter
     def gps(self, gps_on=False):
-        """Sets GPS module power, parses returned buffer.
-        :param bool gps_on: Enables the GPS module, disabled by default.
-
-        """
         if not (
             self._fona_type == FONA_3G_A
             or self._fona_type == FONA_3G_E
@@ -422,14 +420,13 @@ def unpretty_ip(self, ip):  # pylint: disable=no-self-use, invalid-name
 
     @property
     def enable_sms_notification(self):
-        """Returns status of new SMS message notifications"""
+        """Checks if SMS notifications are enabled."""
         if not self._send_parse_reply(b"AT+CNMI?\r\n", b"+CNMI:", idx=1):
             return False
         return self._buf
 
     @enable_sms_notification.setter
     def enable_sms_notification(self, enable=True):
-        """Enables or disables new SMS message notifications."""
         if enable:
             if not self._send_check_reply(b"AT+CNMI=2,1\r\n", reply=REPLY_OK):
                 return False
@@ -442,8 +439,7 @@ def receive_sms(self):
         """Checks for a message notification from the FONA module,
         replies back with the a tuple containing (sender, message).
         NOTE: This method needs to be polled consistently due to the lack
-        of hw-based interrupts in CircuitPython. Adding time.sleep delays
-        may cause missed messages if using the RI pin instead of UART.
+        of hw-based interrupts in CircuitPython.
 
         """
         if self._ri is not None:  # poll the RI pin
@@ -501,12 +497,12 @@ def send_sms(self, phone_number, message):
         return True
 
     def num_sms(self, sim_storage=True):
-        """Returns the number of SMS messages stored in memory, False if none stored.
+        """Returns the number of SMS messages stored in memory.
         :param bool sim_storage: SMS storage on the SIM, otherwise internal storage on FONA chip.
 
         """
         if not self._send_check_reply(b"AT+CMGF=1", reply=REPLY_OK):
-            return False
+            raise RuntimeError("Operating mode not supported by FONA module.")
 
         if sim_storage:  # ask how many SMS are stored
             if self._send_parse_reply(b"AT+CPMS?", FONA_SMS_STORAGE_SIM + b",", idx=1):
@@ -524,10 +520,10 @@ def num_sms(self, sim_storage=True):
         self._read_line()  # eat OK
         if self._send_parse_reply(b"AT+CPMS?", b'"SM_P",', idx=1):
             return self._buf
-        return False
+        return 0
 
     def delete_sms(self, sms_slot):
-        """Deletes a SMS message in the provided SMS slot.
+        """Deletes a SMS message from a storage (internal or sim) slot
         :param int sms_slot: SMS SIM or FONA memory slot number.
 
         """
@@ -597,7 +593,6 @@ def read_sms(self, sms_slot):
 
     def get_host_by_name(self, hostname):
         """Converts a hostname to a packed 4-byte IP address.
-        Returns a 4 bytearray.
         :param str hostname: Destination server.
 
         """
@@ -618,9 +613,7 @@ def get_host_by_name(self, hostname):
         return self._buf
 
     def get_socket(self):
-        """Returns an avaliable socket (INITIAL or CLOSED state).
-
-        """
+        """Obtains a socket, if available."""
         if self._debug:
             print("*** Get socket")
 
@@ -643,7 +636,7 @@ def get_socket(self):
         return allocated_socket
 
     def remote_ip(self, sock_num):
-        """Returns the IP address of the host who sent the current incoming packet.
+        """Returns the IP address of the remote server.
         :param int sock_num: Desired socket.
 
         """
@@ -658,7 +651,7 @@ def remote_ip(self, sock_num):
         return self._buf
 
     def socket_status(self, sock_num):
-        """Returns if socket is connected.
+        """Returns the socket connection status, False if not connected.
         :param int sock_num: Desired socket number.
 
         """
@@ -688,7 +681,7 @@ def socket_status(self, sock_num):
         return True
 
     def socket_available(self, sock_num):
-        """Returns the amount of bytes to be read from the socket.
+        """Returns the amount of bytes available to be read from the socket.
         :param int sock_num: Desired socket to return bytes available from.
 
         """

adafruit_fona/adafruit_fona_socket.py

@@ -57,13 +57,11 @@ def htons(x):
     return (((x) << 8) & 0xFF00) | (((x) >> 8) & 0xFF)
 
 
-# pylint: disable=bad-whitespace
 SOCK_STREAM = const(0x00)  # TCP
 TCP_MODE = 80
 SOCK_DGRAM = const(0x01)  # UDP
 AF_INET = const(3)
 NO_SOCKET_AVAIL = const(255)
-# pylint: enable=bad-whitespace
 
 # keep track of sockets we allocate
 SOCKETS = []

adafruit_fona/fona_3g.py

@@ -58,7 +58,7 @@ class FONA3G(FONA):
 
     def __init__(self, uart, rst, ri=None, debug=False):
         uart.baudrate = 4800
-        super(FONA3G, self).__init__(uart, rst, ri, debug)
+        super().__init__(uart, rst, ri, debug)
 
     def set_baudrate(self, baudrate):
         """Sets the FONA's UART baudrate."""
@@ -70,17 +70,13 @@ def set_baudrate(self, baudrate):
 
     @property
     def gps(self):
-        """Returns True if the GPS session is active, False if it's stopped.."""
+        """Module's GPS status."""
         if not self._send_check_reply(b"AT+CGPS?", reply=b"+CGPS: 1,1"):
             return False
         return True
 
     @gps.setter
     def gps(self, gps_on=False):
-        """Sets GPS module power, parses returned buffer.
-        :param bool gps_on: Enables the GPS module, disabled by default.
-
-        """
         # check if GPS is already enabled
         if not self._send_parse_reply(b"AT+CGPS?", b"+CGPS: "):
             return False
@@ -99,17 +95,17 @@ def gps(self, gps_on=False):
 
     @property
     def ue_system_info(self):
-        """Returns True if UE system is online, otherwise False."""
+        """UE System status."""
         self._send_parse_reply(b"AT+CPSI?\r\n", b"+CPSI: ")
         if not self._buf == "GSM" or self._buf == "WCDMA":  # 5.15
             return False
         return True
 
     @property
     def local_ip(self):
-        """Returns the IP address of the current active socket."""
+        """Module's local IP address, None if not set."""
         if not self._send_parse_reply(b"AT+IPADDR", b"+IPADDR:"):
-            return False
+            return None
         return self._buf
 
     # pylint: disable=too-many-return-statements
@@ -164,15 +160,14 @@ def set_gprs(self, apn=None, enable=True):
 
     @property
     def tx_timeout(self):
-        """Returns CIPSEND timeout, in milliseconds."""
+        """CIPSEND timeout, in milliseconds."""
         self._read_line()
         if not self._send_parse_reply(b"AT+CIPTIMEOUT?", b"+CIPTIMEOUT:", idx=2):
             return False
         return True
 
     @tx_timeout.setter
     def tx_timeout(self, timeout):
-        """Sets CIPSEND timeout."""
         self._read_line()
         if not self._send_check_reply(
             b"AT+CIPTIMEOUT=" + str(timeout).encode(), reply=REPLY_OK
@@ -259,7 +254,8 @@ def socket_connect(self, sock_num, dest, port, conn_mode=0):
         return True
 
     def remote_ip(self, sock_num):
-        """Returns the IP address of sender."""
+        """Returns the IP address of the remote connection.
+        """
         self._read_line()
         assert (
             sock_num < FONA_MAX_SOCKETS
@@ -277,7 +273,7 @@ def remote_ip(self, sock_num):
         return ip_addr
 
     def socket_write(self, sock_num, buffer, timeout=120000):
-        """Writes bytes to the socket.
+        """Writes len(buffer) bytes to the socket.
         :param int sock_num: Desired socket number to write to.
         :param bytes buffer: Bytes to write to socket.
         :param int timeout: Socket write timeout, in milliseconds. Defaults to 120000ms.
@@ -318,7 +314,7 @@ def socket_write(self, sock_num, buffer, timeout=120000):
         return True
 
     def socket_status(self, sock_num):
-        """Returns True if socket is connected, False otherwise.
+        """Returns socket status, True if connected. False otherwise.
         :param int sock_num: Desired socket number.
 
         """

examples/fona_aio_post.py

@@ -3,11 +3,11 @@
 import board
 import busio
 import digitalio
+import adafruit_requests as requests
 from adafruit_fona.adafruit_fona import FONA
 from adafruit_fona.fona_3g import FONA3G
 import adafruit_fona.adafruit_fona_network as network
 import adafruit_fona.adafruit_fona_socket as cellular_socket
-import adafruit_requests as requests
 
 # Get GPRS details and more from a secrets.py file
 try:

examples/fona_cheerlights.py

@@ -3,15 +3,13 @@
 import board
 import busio
 import digitalio
+import neopixel
+import adafruit_requests as requests
+import adafruit_fancyled.adafruit_fancyled as fancy
 from adafruit_fona.adafruit_fona import FONA
 from adafruit_fona.fona_3g import FONA3G
 import adafruit_fona.adafruit_fona_network as network
 import adafruit_fona.adafruit_fona_socket as cellular_socket
-import adafruit_requests as requests
-
-import neopixel
-import adafruit_fancyled.adafruit_fancyled as fancy
-
 
 # Get GPRS details and more from a secrets.py file
 try:

examples/fona_simpletest.py

@@ -3,11 +3,11 @@
 import board
 import busio
 import digitalio
+import adafruit_requests as requests
 from adafruit_fona.adafruit_fona import FONA
 from adafruit_fona.fona_3g import FONA3G
 import adafruit_fona.adafruit_fona_network as network
 import adafruit_fona.adafruit_fona_socket as cellular_socket
-import adafruit_requests as requests
 
 print("FONA Webclient Test")