Start adding docstrings

Author: webdjoe

src/pyvesync/vesync.py

@@ -74,11 +74,45 @@ def kitchen(dev_type, config, manager):
 
 
 class VeSync:  # pylint: disable=function-redefined
-    """VeSync API functions."""
+    """VeSync Manager Class."""
 
     def __init__(self, username, password, time_zone=DEFAULT_TZ,
                  debug=False, redact=True):
-        """Initialize VeSync class with username, password and time zone."""
+        """Initialize VeSync Manager.
+
+        This class is used as the manager for all VeSync objects, all methods and
+        API calls are performed from this class. Time zone, debug and redact are
+        optional. Time zone must be a string of an IANA time zone format. Once
+        class is instantiated, call `manager.login()` to log in to VeSync servers,
+        which returns `True` if successful. Once logged in, call `manager.update()`
+        to retrieve devices and update device details.
+
+        Parameters:
+        -----------
+            username : str
+                VeSync account username (usually email address)
+            password : str
+                VeSync account password
+            time_zone : str, optional
+                Time zone for device from IANA database, by default DEFAULT_TZ
+            debug : bool, optional
+                Enable debug logging, by default False
+            redact : bool, optional
+                Redact sensitive information in logs, by default True
+
+        Attributes
+        ----------
+            fans : list
+                List of VeSyncFan objects for humidifiers and air purifiers
+            outlets : list
+                List of VeSyncOutlet objects for smart plugs
+            switches : list
+                List of VeSyncSwitch objects for wall switches
+            bulbs : list
+                List of VeSyncBulb objects for smart bulbs
+            kitchen : list
+                List of VeSyncKitchen objects for smart kitchen appliances
+        """
         self.debug = debug
         if debug:  # pragma: no cover
             logger.setLevel(logging.DEBUG)
@@ -308,7 +342,15 @@ def get_devices(self) -> bool:
         return proc_return
 
     def login(self) -> bool:
-        """Return True if log in request succeeds."""
+        """Log into VeSync server.
+
+        Username and password are provided when class is instantiated.
+
+        Returns
+        -------
+        bool
+            True if login successful, False if not
+        """
         user_check = isinstance(self.username, str) and len(self.username) > 0
         pass_check = isinstance(self.password, str) and len(self.password) > 0
         if user_check is False:
@@ -346,7 +388,16 @@ def device_time_check(self) -> bool:
         return False
 
     def update(self) -> None:
-        """Fetch updated information about devices."""
+        """Fetch updated information about devices.
+
+        Pulls devices list from VeSync and instantiates any new devices. Devices
+        are stored in the instance attributes `outlets`, `switches`, `fans`, and
+        `bulbs`. The `_device_list` attribute is a dictionary of these attributes.
+
+        Returns
+        -------
+        None
+        """
         if self.device_time_check():
 
             if not self.enabled:

src/pyvesync/vesyncfan.py

@@ -168,7 +168,52 @@ class VeSyncAirBypass(VeSyncBaseDevice):
     """Base class for Levoit Purifier Bypass API Calls."""
 
     def __init__(self, details: Dict[str, list], manager):
-        """Initialize air devices."""
+        """Initialize air purifier devices.
+
+        Instantiated by VeSync manager object. Inherits from
+        VeSyncBaseDevice class.
+
+        Arguments
+        ----------
+        details : dict
+            Dictionary of device details
+        manager : VeSync
+            Instantiated VeSync object used to make API calls
+
+        Attributes
+        ----------
+        modes : list
+            List of available operation modes for device
+        air_quality_feature : bool
+            True if device has air quality sensor
+        details : dict
+            Dictionary of device details
+        timer : Timer
+            Timer object for device, None if no timer exists. See `Timer` class
+        config : dict
+            Dictionary of device configuration
+
+        Notes
+        -----
+        The `details` attribute holds device information that is updated when
+        the `update()` method is called. An example of the `details` attribute:
+        >>> {
+        >>>     'filter_life': 0,
+        >>>     'mode': 'manual',
+        >>>     'level': 0,
+        >>>     'display': False,
+        >>>     'child_lock': False,
+        >>>     'night_light': 'off',
+        >>>     'air_quality': 0 # air quality level
+        >>>     'air_quality_value': 0, # PM2.5 value from device,
+        >>>     'display_forever': False
+        >>> }
+
+        See Also
+        --------
+        VeSyncBaseDevice : Parent class for all VeSync devices
+
+        """
         super().__init__(details, manager)
         self.enabled = True
         self._config_dict = model_features(self.device_type)
@@ -297,7 +342,31 @@ def update(self):
         self.get_details()
 
     def get_timer(self) -> Optional[Timer]:
-        """Retrieve running timer from purifier."""
+        """Retrieve running timer from purifier.
+
+        Returns Timer object if timer is running, None if no timer is running.
+
+        Arguments
+        ----------
+        None
+
+        Returns
+        -------
+        Timer or None
+
+        Notes
+        -----
+        Timer object tracks the time remaining based on the last update. Timer
+        properties include `status`, `time_remaining`, `duration`, `action`,
+        `paused` and `done`. The methods `start()`, `end()` and `pause()`
+        are available but should be called through the purifier object
+        to update through the API.
+
+        See Also
+        --------
+        Timer : Timer object used to track device timers
+
+        """
         head, body = self.build_api_dict('getTimer')
         body['payload']['data'] = {}
         if not head and not body:
@@ -345,6 +414,11 @@ def set_timer(self, timer_duration: int) -> bool:
         ----------
         timer_duration: int
             Duration of timer in seconds
+
+        Returns
+        -------
+        bool
+
         """
         if self.device_status != 'on':
             logger.debug("Can't set timer when device is off")
@@ -382,7 +456,15 @@ def set_timer(self, timer_duration: int) -> bool:
         return True
 
     def clear_timer(self) -> bool:
-        """Clear timer."""
+        """Clear timer.
+
+        Returns True if no error is returned from API call.
+
+        Returns
+        -------
+        bool
+
+        """
         self.get_timer()
         if self.timer is None:
             logger.debug('No timer to clear')
@@ -465,7 +547,20 @@ def child_lock_off(self) -> bool:
         return self.set_child_lock(False)
 
     def set_child_lock(self, mode: bool) -> bool:
-        """Set Bypass child lock."""
+        """Set Bypass child lock.
+
+        Set child lock to on or off.
+
+        Arguments
+        ----------
+        mode: bool
+            True to turn child lock on, False to turn off
+
+        Returns
+        -------
+        bool
+
+        """
         if mode not in (True, False):
             logger.debug('Invalid mode passed to set_child_lock - %s', mode)
             return False
@@ -519,7 +614,20 @@ def reset_filter(self) -> bool:
         return False
 
     def mode_toggle(self, mode: str) -> bool:
-        """Set purifier mode - sleep or manual."""
+        """Set purifier mode - sleep or manual.
+
+        Set purifier mode based on devices available modes.
+
+        Arguments
+        ----------
+        mode: str
+            Mode to set purifier. Based on device modes in attribute `modes`
+
+        Returns
+        -------
+        bool
+
+        """
         if mode.lower() not in self.modes:
             logger.debug('Invalid purifier mode used - %s',
                          mode)