Enable bandit and pydocstyle; fix docstring warnings

glennmatthews · glennmatthews · commit 859ee637b2a2 · 2020-05-13T16:18:05.000-04:00
diff --git a/.pydocstyle.ini b/.pydocstyle.ini
@@ -0,0 +1,3 @@
+[pydocstyle]
+convention = google
+inherit = false
diff --git a/netbox_onboarding/__init__.py b/netbox_onboarding/__init__.py
@@ -1,4 +1,5 @@
-"""
+"""Plugin declaration for netbox_onboarding.
+
 (c) 2020 Network To Code
 Licensed under the Apache License, Version 2.0 (the "License");
 you may not use this file except in compliance with the License.
diff --git a/netbox_onboarding/api/__init__.py b/netbox_onboarding/api/__init__.py
@@ -0,0 +1 @@
+"""REST API module for netbox_onboarding plugin."""
diff --git a/netbox_onboarding/api/serializers.py b/netbox_onboarding/api/serializers.py
@@ -1,4 +1,5 @@
-"""
+"""Model serializers for the netbox_onboarding REST API.
+
 (c) 2020 Network To Code
 Licensed under the Apache License, Version 2.0 (the "License");
 you may not use this file except in compliance with the License.
@@ -72,7 +73,7 @@ class OnboardingTaskSerializer(serializers.ModelSerializer):
 
     timeout = serializers.IntegerField(required=False, help_text="Timeout (sec) for device connect")
 
-    class Meta:
+    class Meta:  # noqa: D106 "Missing docstring in public nested class"
         model = OnboardingTask
         fields = [
             "id",
@@ -93,6 +94,7 @@ class Meta:
         ]
 
     def create(self, validated_data):
+        """Create an OnboardingTask and enqueue it for processing."""
         # Fields are string-type so default to empty (instead of None)
         username = validated_data.pop("username", "")
         password = validated_data.pop("password", "")
diff --git a/netbox_onboarding/api/urls.py b/netbox_onboarding/api/urls.py
@@ -1,4 +1,5 @@
-"""
+"""REST API URLs for device onboarding.
+
 (c) 2020 Network To Code
 Licensed under the Apache License, Version 2.0 (the "License");
 you may not use this file except in compliance with the License.
diff --git a/netbox_onboarding/api/views.py b/netbox_onboarding/api/views.py
@@ -1,4 +1,5 @@
-"""
+"""Django REST Framework API views for device onboarding.
+
 (c) 2020 Network To Code
 Licensed under the Apache License, Version 2.0 (the "License");
 you may not use this file except in compliance with the License.
diff --git a/netbox_onboarding/choices.py b/netbox_onboarding/choices.py
@@ -1,4 +1,5 @@
-"""
+"""ChoiceSet classes for device onboarding.
+
 (c) 2020 Network To Code
 Licensed under the Apache License, Version 2.0 (the "License");
 you may not use this file except in compliance with the License.
diff --git a/netbox_onboarding/filters.py b/netbox_onboarding/filters.py
@@ -1,4 +1,5 @@
-"""
+"""Filtering logic for OnboardingTask instances.
+
 (c) 2020 Network To Code
 Licensed under the Apache License, Version 2.0 (the "License");
 you may not use this file except in compliance with the License.
@@ -41,11 +42,12 @@ class OnboardingTaskFilter(NameSlugSearchFilterSet):
         field_name="role__slug", queryset=DeviceRole.objects.all(), to_field_name="slug", label="Device Role (slug)",
     )
 
-    class Meta:
+    class Meta:  # noqa: D106 "Missing docstring in public nested class"
         model = OnboardingTask
         fields = ["id", "site", "site_id", "platform", "role", "status", "failed_reason"]
 
     def search(self, queryset, name, value):
+        """Perform the filtered search."""
         if not value.strip():
             return queryset
         qs_filter = (
diff --git a/netbox_onboarding/forms.py b/netbox_onboarding/forms.py
@@ -1,4 +1,5 @@
-"""
+"""Forms for network device onboarding.
+
 (c) 2020 Network To Code
 Licensed under the Apache License, Version 2.0 (the "License");
 you may not use this file except in compliance with the License.
@@ -38,7 +39,7 @@ class OnboardingTaskFilterForm(BootstrapMixin, forms.ModelForm):
 
     q = forms.CharField(required=False, label="Search")
 
-    class Meta:
+    class Meta:  # noqa: D106 "Missing docstring in public nested class"
         model = OnboardingTask
         fields = ["q", "site", "platform", "status", "failed_reason"]
 
@@ -76,6 +77,6 @@ class OnboardingTaskFeedCSVForm(CustomFieldModelCSVForm):
         error_messages={"invalid_choice": "DeviceRole not found",},
     )
 
-    class Meta:
+    class Meta:  # noqa: D106 "Missing docstring in public nested class"
         model = OnboardingTask
         fields = OnboardingTask.csv_headers
diff --git a/netbox_onboarding/models.py b/netbox_onboarding/models.py
@@ -1,4 +1,5 @@
-"""
+"""OnboardingTask Django model.
+
 (c) 2020 Network To Code
 Licensed under the Apache License, Version 2.0 (the "License");
 you may not use this file except in compliance with the License.
@@ -16,9 +17,7 @@
 
 
 class OnboardingTask(models.Model):
-    """
-    The status of each onboarding Task is tracked in the OnboardingTask table
-    """
+    """The status of each onboarding Task is tracked in the OnboardingTask table."""
 
     group_id = models.CharField(max_length=255, help_text="CSV Bulk Import Group ID (optional)", blank=True)
 
@@ -73,5 +72,5 @@ class OnboardingTask(models.Model):
         "role",
     ]
 
-    class Meta:
+    class Meta:  # noqa: D106 "missing docstring in public nested class"
         ordering = ["created_on"]
diff --git a/netbox_onboarding/navigation.py b/netbox_onboarding/navigation.py
@@ -1,4 +1,5 @@
-"""
+"""Plugin additions to the NetBox navigation menu.
+
 (c) 2020 Network To Code
 Licensed under the Apache License, Version 2.0 (the "License");
 you may not use this file except in compliance with the License.
diff --git a/netbox_onboarding/onboard.py b/netbox_onboarding/onboard.py
@@ -1,4 +1,5 @@
-"""
+"""Worker code for processing inbound OnboardingTasks.
+
 (c) 2020 Network To Code
 Licensed under the Apache License, Version 2.0 (the "License");
 you may not use this file except in compliance with the License.
@@ -27,10 +28,9 @@
 
 
 class OnboardException(Exception):
-    """
-    Any failure during the onboard process will result in an an
-    OnboardException. The exception includes a reason "slug" as defined below
-    as well as a humanized message.
+    """A failure occurred during the onboarding process.
+
+    The exception includes a reason "slug" as defined below as well as a humanized message.
     """
 
     REASONS = (
@@ -58,26 +58,20 @@ def __str__(self):
 
 
 class NetdevKeeper:
-    """
-    Used to maintain information about the network device during the onboarding
-    process.
-    """
+    """Used to maintain information about the network device during the onboarding process."""
 
     def __init__(self, onboarding_task, username=None, password=None):
-        """
-        Initialize the network device keeper instance and ensure the required
-        configuration parameters are provided.
+        """Initialize the network device keeper instance and ensure the required configuration parameters are provided.
 
-        Parameters
-        ----------
-        config : dict - config params.
+        Args:
+          onboarding_task (OnboardingTask): Task being processed
+          username (str): Device username (if unspecified, NAPALM_USERNAME environment variable will be used)
+          password (str): Device password (if unspecified, NAPALM_PASSWORD environment variable will be used)
 
-        Raises
-        ------
-        OnboardException('fail-config'):
+        Raises:
+          OnboardException('fail-config'):
             When any required config options are missing.
         """
-
         self.ot = onboarding_task
 
         # Attributes that are set when reading info from device
@@ -92,14 +86,13 @@ def __init__(self, onboarding_task, username=None, password=None):
         self.password = password or os.environ.get("NAPALM_PASSWORD", None)
 
     def check_reachability(self):
-        """
-        Ensure that the device at the mgmt-ipaddr provided is reachable.  We do this
-        check before attempting other "show" commands so that we know we've got a
+        """Ensure that the device at the mgmt-ipaddr provided is reachable.
+
+        We do this check before attempting other "show" commands so that we know we've got a
         device that can be reached.
 
-        Raises
-        ------
-        OnboardException('fail-connect'):
+        Raises:
+          OnboardException('fail-connect'):
             When device unreachable
         """
         ip_addr = self.ot.ip_address
@@ -117,19 +110,16 @@ def check_reachability(self):
             raise OnboardException(reason="fail-connect", message=f"ERROR device unreachable: {ip_addr}:{port}")
 
     def get_required_info(self):
-        """
-        Gather information from the network device that is needed to onboard
-        the device into the NetBox system.
+        """Gather information from the network device that is needed to onboard the device into the NetBox system.
 
-        Raises
-        ------
-        OnboardException('fail-login'):
+        Raises:
+          OnboardException('fail-login'):
             When unable to login to device
 
-        OnboardException('fail-exectute'):
+          OnboardException('fail-execute'):
             When unable to run commands to collect device information
 
-        OnboardException('fail-general'):
+          OnboardException('fail-general'):
             Any other unexpected device comms failure.
         """
         self.check_reachability()
@@ -192,19 +182,13 @@ def get_required_info(self):
 
 
 class NetboxKeeper:
-    """
-    Used to manage the information relating to the network device within the
-    NetBox server.
-    """
+    """Used to manage the information relating to the network device within the NetBox server."""
 
     def __init__(self, netdev):
-        """
-        Creates an instance to the NetBox API and initializes the managed
-        attributes that are used throughout the onboard processing.
+        """Create an instance and initialize the managed attributes that are used throughout the onboard processing.
 
-        Parameters
-        ----------
-        netdev : NetdevKeeper - instance
+        Args:
+          netdev (NetdevKeeper): instance
         """
         self.netdev = netdev
 
@@ -221,22 +205,18 @@ def __init__(self, netdev):
         self.primary_ip = None
 
     def ensure_device_type(self):
-        """
-        This function ensures that the Device Type (slug) exists in NetBox
-        assocaited to the netdev "model" and  `vendor` (manufacturer).
+        """Ensure the Device Type (slug) exists in NetBox associated to the netdev "model" and "vendor" (manufacturer).
 
-        Raises
-        ------
-        OnboardException('fail-config'):
+        Raises:
+          OnboardException('fail-config'):
             When the device vendor value does not exist as a Manufacturer in
             NetBox.
 
-        OnboardException('fail-config'):
+          OnboardException('fail-config'):
             When the device-type exists by slug, but is assigned to a different
             manufacturer.  This should *not* happen, but guard-rail checking
             regardless in case two vendors have the same model name.
         """
-
         # First ensure that the vendor, as extracted from the network device exists
         # in NetBox.  We need the ID for this vendor when ensuring the DeviceType
         # instance.
@@ -280,11 +260,7 @@ def ensure_device_type(self):
         self.device_type.save()
 
     def ensure_device_instance(self):
-        """
-        Ensure that the device instance exists in NetBox and is assigned either
-        the provide device role, or uses the DEFAULT_ROLE value.
-        """
-
+        """Ensure that the device instance exists in NetBox and is assigned the provided device role or DEFAULT_ROLE."""
         self.device, _ = Device.objects.get_or_create(
             name=self.netdev.hostname,
             device_type=self.device_type,
@@ -297,19 +273,11 @@ def ensure_device_instance(self):
         self.device.save()
 
     def ensure_interface(self):
-        """
-        Ensures that the interface associated with the mgmt_ipaddr exists and
-        is assigned to the device.
-        """
-
+        """Ensure that the interface associated with the mgmt_ipaddr exists and is assigned to the device."""
         self.interface, _ = Interface.objects.get_or_create(name=self.netdev.mgmt_ifname, device=self.device)
 
     def ensure_primary_ip(self):
-        """
-        Ensure that the network device mgmt_ipaddr exists in IPAM, is assigned
-        to the device interface, and is also assigned as the device primary IP
-        address.
-        """
+        """Ensure mgmt_ipaddr exists in IPAM, has the device interface, and is assigned as the primary IP address."""
         mgmt_ipaddr = self.netdev.ot.ip_address
 
         # see if the primary IP address exists in IPAM
@@ -328,9 +296,9 @@ def ensure_primary_ip(self):
         self.device.save()
 
     def ensure_device(self):
-        """
-        Ensure that the device represented by the dev_info data exists in the NetBox
-        system.  This means the following is true:
+        """Ensure that the device represented by the dev_info data exists in the NetBox system.
+
+        This means the following is true:
 
             1. The device 'hostname' exists and is a member of 'site'
             2. The 'serial_number' is assigned to the device
@@ -343,7 +311,6 @@ def ensure_device(self):
         an OnboardException.
 
         """
-
         self.ensure_device_type()
         self.ensure_device_instance()
         self.ensure_interface()
diff --git a/netbox_onboarding/tables.py b/netbox_onboarding/tables.py
@@ -1,4 +1,5 @@
-"""
+"""Tables for device onboarding tasks.
+
 (c) 2020 Network To Code
 Licensed under the Apache License, Version 2.0 (the "License");
 you may not use this file except in compliance with the License.
@@ -20,7 +21,7 @@ class OnboardingTaskTable(BaseTable):
 
     site = tables.LinkColumn()
 
-    class Meta(BaseTable.Meta):
+    class Meta(BaseTable.Meta):  # noqa: D106 "Missing docstring in public nested class"
         model = OnboardingTask
         fields = ("pk", "created_on", "ip_address", "site", "platform", "device", "status", "failed_reason", "message")
 
@@ -30,7 +31,7 @@ class OnboardingTaskFeedBulkTable(BaseTable):
 
     site = tables.LinkColumn()
 
-    class Meta(BaseTable.Meta):
+    class Meta(BaseTable.Meta):  # noqa: D106 "Missing docstring in public nested class"
         model = OnboardingTask
         fields = (
             "id",
diff --git a/netbox_onboarding/tests/__init__.py b/netbox_onboarding/tests/__init__.py
@@ -0,0 +1 @@
+"""Unit tests for netbox_onboarding plugin."""
diff --git a/netbox_onboarding/tests/test_api.py b/netbox_onboarding/tests/test_api.py
@@ -1,4 +1,5 @@
-"""
+"""Unit tests for netbox_onboarding REST API.
+
 (c) 2020 Network To Code
 Licensed under the Apache License, Version 2.0 (the "License");
 you may not use this file except in compliance with the License.
diff --git a/netbox_onboarding/urls.py b/netbox_onboarding/urls.py
@@ -1,4 +1,5 @@
-"""
+"""Django urlpatterns declaration for netbox_onboarding plugin.
+
 (c) 2020 Network To Code
 Licensed under the Apache License, Version 2.0 (the "License");
 you may not use this file except in compliance with the License.
diff --git a/netbox_onboarding/utils/credentials.py b/netbox_onboarding/utils/credentials.py
diff --git a/netbox_onboarding/views.py b/netbox_onboarding/views.py
diff --git a/netbox_onboarding/worker.py b/netbox_onboarding/worker.py
diff --git a/poetry.lock b/poetry.lock
diff --git a/pyproject.toml b/pyproject.toml
diff --git a/tasks.py b/tasks.py

Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,3 @@`
	`1`	`+[pydocstyle]`
	`2`	`+convention = google`
	`3`	`+inherit = false`
Original file line number	Diff line number	Diff line change
`@@ -0,0 +1 @@`
	`1`	`+"""REST API module for netbox_onboarding plugin."""`