Add pydocstyle to tox (#215)

Author: qduk

pyntc/__init__.py

@@ -1,5 +1,4 @@
-"""Kickoff functions for getting instancs of device objects.
-"""
+"""Kickoff functions for getting instancs of device objects."""
 
 import os
 import warnings
@@ -22,9 +21,10 @@
 
 
 def ntc_device(device_type, *args, **kwargs):
-    """Instantiate and return an instance of a device subclassed
-    from ``pyntc.devices.BaseDevice``. ``*args`` and ``*kwargs`` are passed
-    directly to the device initializer.
+    """
+    Instantiate an instance of a ``pyntc.devices.BaseDevice`` by ``device_type``.
+
+    The ``*args`` and ``*kwargs`` are passed directly to the device initializer.
 
     Arguments:
         device_type (string): A valid device_type
@@ -36,7 +36,6 @@ def ntc_device(device_type, *args, **kwargs):
     Raises:
         UnsupportedDeviceError: if the device_type is unsupported.
     """
-
     try:
         device_class = supported_devices[device_type]
         return device_class(*args, **kwargs)
@@ -45,9 +44,8 @@ def ntc_device(device_type, *args, **kwargs):
 
 
 def ntc_device_by_name(name, filename=None):
-    """Instantiate and return an instance of a device subclassed
-    from ``pyntc.devices.BaseDevice`` based on its name in an
-    NTC configuration file.
+    """
+    Instantiate an instance of a ``pyntc.devices.BaseDevice`` from ntc.conf file.
 
     If no filename is given the environment variable PYNTC_CONF is checked
     for a path, and then ~/.ntc.conf.
@@ -58,9 +56,8 @@ def ntc_device_by_name(name, filename=None):
             the ``name`` argument as section header.
 
     Raises:
-        DeviceNameNotFoundError: if the name is not found in the
-            NTC configuration file.
-        ConfFileNotFoundError: if no NTC configuration can be found.
+        DeviceNameNotFoundError: If the name is not found in the NTC configuration file.
+        ConfFileNotFoundError: If no NTC configuration can be found.
     """
     config, filename = _get_config_from_file(filename=filename)
     sections = config.sections()

pyntc/devices/__init__.py

@@ -1,6 +1,4 @@
-"""Supported devices are stored here. Every supported device needs a
-device_type stored as a string, and a class subclassed from BaseDevice.
-"""
+"""Device drivers."""
 
 from .eos_device import EOSDevice
 from .nxos_device import NXOSDevice

pyntc/devices/base_device.py

@@ -220,10 +220,8 @@ def vlans(self):
         """
         raise NotImplementedError
 
-    def facts(self):  # noqa: D403
-        """
-        DEPRECATED - Use individual properties to get facts.
-        """
+    def facts(self):  # noqa 401
+        """DEPRECATED - Use individual properties to get facts."""
         warnings.warn("facts() is deprecated; use individual fact properties.", DeprecationWarning)
         facts = {
             fact: getattr(self, fact, None)

pyntc/devices/ios_device.py

@@ -472,8 +472,10 @@ def uptime(self):
 
     @property
     def uptime_string(self):
-        """
-        Get uptime in format dd:hh:mm.
+        """Get uptime in format dd:hh:mm.
+
+        Returns:
+            str: Uptime of device.
         """
         if self._uptime_string is None:
             version_data = self._raw_version_data()

pyntc/devices/iosxewlc_device.py

@@ -88,5 +88,14 @@ def install_os(self, image_name, install_mode_delay_factor=20, **vendor_specific
         return False
 
     def show(self, command, expect_string=None, **netmiko_args):
+        """Run command on device.
+
+        Args:
+            command (str): Command to be ran.
+            expect_string (str, optional): Expected string from command output. Defaults to None.
+
+        Returns:
+            str: Output of command.
+        """
         self.enable()
         return self._send_command(command, expect_string=expect_string, **netmiko_args)

pyntc/devices/jnpr_device.py

@@ -403,6 +403,7 @@ def running_config(self):
     def save(self, filename=None):
         """
         Save current configuration to device.
+
         If filename is provided, save current configuration to file.
 
         Args:

pyntc/utils/converters.py

@@ -42,7 +42,21 @@ def convert_dict_by_key(original, key_map, fill_in=False, whitelist=[], blacklis
 
 
 def convert_list_by_key(original_list, key_map, fill_in=False, whitelist=[], blacklist=[]):
-    """Apply a dictionary conversion for all dictionaries in original_list."""
+    """Apply a list conversion for all items in original_list.
+
+    Args:
+        original_list (list): Original list to be converted.
+        key_map (dict): Key map to use to convert list.
+        fill_in (dict): Whether the returned list should contain
+            keys and values from the original dictionary if not specified in the key map.
+        whitelist: If fill_in is True, and whitelist isn't empty, only fill in the keys
+            in the whitelist in the returned dictionary.
+        blacklist: If fill_in is True, and blacklist isn't empty, fill in with all keys from
+            the original dictionary besides those in the blacklist.
+
+    Returns:
+        list: A converted list.
+    """
     converted_list = []
     for original in list(original_list):
         converted_list.append(
@@ -53,8 +67,19 @@ def convert_list_by_key(original_list, key_map, fill_in=False, whitelist=[], bla
 
 
 def recursive_key_lookup(keys, obj):
-    """Return obj[keys] if keys is actually a single key.
-    Otherwise return obj[keys[0]][keys[1]]...[keys[n]] if keys is a list."""
+    """
+    Lookup nested object by indexing through a dictionary sequentally through ``keys``.
+
+    Args:
+        keys (list): The dictionary keys to use to lookup an object.
+        obj (dict): The dictionary to traverse.
+
+    Example:
+        >>> keys = ["a", "b", "c"]
+        >>> data = {"a": {"b": {"c": 1}}}
+        >>> recursive_key_lookup(keys, data)
+        1
+    """
     if not isinstance(keys, list):
         return obj.get(keys)
 

pyntc/utils/templates/__init__.py

@@ -1,3 +1,4 @@
+"""Module to use NTC_TEMPLATES."""
 import os
 import textfsm
 
@@ -6,8 +7,14 @@
 
 
 def get_structured_data(template_name, rawtxt):
-    """Returns structured data given raw text using
-    TextFSM templates
+    """Return structured data given raw text using TextFSM templates.
+
+    Args:
+        template_name (str): Name of template to use.
+        rawtxt (str): Raw output from device.
+
+    Returns:
+        list: A dict per entry returned by TextFSM.
     """
     template_file = get_template(template_name)
     with open(template_file) as template:
@@ -23,11 +30,24 @@ def get_structured_data(template_name, rawtxt):
 
 
 def get_template(template_name):
+    """Path to the template passed in.
+
+    Args:
+        template_name (str): Name of the template.
+
+    Returns:
+        str: Path to the template.
+    """
     template_dir = get_template_dir()
     return os.path.join(template_dir, template_name)
 
 
 def get_template_dir():
+    """Get directory of NTC_TEMPLATE os environment.
+
+    Returns:
+        str: Path to NTC_TEMPLATES environment variable if set. Otherwise, path to this file.
+    """
     try:
         return os.environ[TEMPLATE_PATH_ENV_VAR]
     except KeyError:

tox.ini

@@ -5,7 +5,7 @@
 
 # TODO: Migrate this to unified interface under invoke
 [tox]
-envlist = py{36,37,38},black,flake8,bandit
+envlist = py{36,37,38},black,flake8,bandit,pydocstyle
 skip_missing_interpreters=true
 isolated_build = True
 download=true
@@ -29,6 +29,10 @@ commands = black ./ --diff --check
 deps = flake8
 commands = flake8 ./
 
+[testenv:pydocstyle]
+deps = pydocstyle
+commands = pydocstyle ./
+
 [testenv:bandit]
 deps = bandit==1.6.2
 commands = bandit -r ./pyntc/ -c .bandit.yml
@@ -52,3 +56,7 @@ exclude =
 
 # line length is handled by black
 ignore = E501
+
+[pydocstyle]
+match = (?!test_|error).*\.py
+match_dir = ^(?!(tmp|\..*|venv|\.venv|test|tables|system_features)).*