add docstrings everywhere

Author: ryanmerolle

netbox_acls/api/serializers.py

@@ -29,18 +29,19 @@
     "ACLExtendedRuleSerializer",
 ]
 
+# TODO: Check Constants across codebase for consistency.
 # Sets a standard error message for ACL rules with an action of remark, but no remark set.
-error_message_no_remark = "Action is set to remark, you MUST add a remark."
+ERROR_MESSAGE_NO_REMARK = "Action is set to remark, you MUST add a remark."
 # Sets a standard error message for ACL rules with an action of remark, but no source_prefix is set.
-error_message_action_remark_source_prefix_set = (
+ERROR_MESSAGE_ACTION_REMARK_SOURCE_PREFIX_SET = (
     "Action is set to remark, Source Prefix CANNOT be set."
 )
 # Sets a standard error message for ACL rules with an action not set to remark, but no remark is set.
-error_message_remark_without_action_remark = (
+ERROR_MESSAGE_REMARK_WITHOUT_ACTION_REMARK = (
     "CANNOT set remark unless action is set to remark."
 )
 # Sets a standard error message for ACL rules no associated to an ACL of the same type.
-error_message_acl_type = "Provided parent Access List is not of right type."
+ERROR_MESSAGE_ACL_TYPE = "Provided parent Access List is not of right type."
 
 
 class AccessListSerializer(NetBoxModelSerializer):
@@ -83,6 +84,9 @@ class Meta:
 
     @swagger_serializer_method(serializer_or_field=serializers.DictField)
     def get_assigned_object(self, obj):
+        """
+        Returns the assigned object for the Access List.
+        """
         serializer = get_serializer_for_model(
             obj.assigned_object,
             prefix=NESTED_SERIALIZER_PREFIX,
@@ -166,6 +170,9 @@ class Meta:
 
     @swagger_serializer_method(serializer_or_field=serializers.DictField)
     def get_assigned_object(self, obj):
+        """
+        Returns the assigned object for the ACLInterfaceAssignment.
+        """
         serializer = get_serializer_for_model(
             obj.assigned_object,
             prefix=NESTED_SERIALIZER_PREFIX,
@@ -272,11 +279,11 @@ def validate(self, data):
 
         # Check if action set to remark, but no remark set.
         if data.get("action") == "remark" and data.get("remark") is None:
-            error_message["remark"] = [error_message_no_remark]
+            error_message["remark"] = [ERROR_MESSAGE_NO_REMARK]
         # Check if action set to remark, but source_prefix set.
         if data.get("source_prefix"):
             error_message["source_prefix"] = [
-                error_message_action_remark_source_prefix_set,
+                ERROR_MESSAGE_ACTION_REMARK_SOURCE_PREFIX_SET,
             ]
 
         if error_message:
@@ -346,11 +353,11 @@ def validate(self, data):
 
         # Check if action set to remark, but no remark set.
         if data.get("action") == "remark" and data.get("remark") is None:
-            error_message["remark"] = [error_message_no_remark]
+            error_message["remark"] = [ERROR_MESSAGE_NO_REMARK]
         # Check if action set to remark, but source_prefix set.
         if data.get("source_prefix"):
             error_message["source_prefix"] = [
-                error_message_action_remark_source_prefix_set,
+                ERROR_MESSAGE_ACTION_REMARK_SOURCE_PREFIX_SET,
             ]
         # Check if action set to remark, but source_ports set.
         if data.get("source_ports"):

netbox_acls/forms/filtersets.py

@@ -44,6 +44,10 @@ class BaseACLFilterForm(NetBoxModelFilterSetForm):
     """
 
     class Meta:
+        """
+        Sets the parent class as an abstract class to be inherited by other classes.
+        """
+
         abstract = True
 
     model = AccessList
@@ -163,6 +167,10 @@ class BaseACLRuleFilterForm(NetBoxModelFilterSetForm):
     """
 
     class Meta:
+        """
+        Sets the parent class as an abstract class to be inherited by other classes.
+        """
+
         abstract = True
 
     model = BaseACLRule

netbox_acls/forms/models.py

@@ -37,20 +37,20 @@
     "<b>*Note:</b> CANNOT be set if action is set to remark.",
 )
 # Sets a standard help_text value to be used by the various classes for acl action
-help_text_acl_action = "Action the rule will take (remark, deny, or allow)."
+HELP_TEXT_ACL_ACTION = "Action the rule will take (remark, deny, or allow)."
 # Sets a standard help_text value to be used by the various classes for acl index
-help_text_acl_rule_index = (
+HELP_TEXT_ACL_RULE_INDEX = (
     "Determines the order of the rule in the ACL processing. AKA Sequence Number."
 )
 
 # Sets a standard error message for ACL rules with an action of remark, but no remark set.
-error_message_no_remark = "Action is set to remark, you MUST add a remark."
+ERROR_MESSAGE_NO_REMARK = "Action is set to remark, you MUST add a remark."
 # Sets a standard error message for ACL rules with an action of remark, but no source_prefix is set.
-error_message_action_remark_source_prefix_set = (
+ERROR_MESSAGE_ACTION_REMARK_SOURCE_PREFIX_SET = (
     "Action is set to remark, Source Prefix CANNOT be set."
 )
 # Sets a standard error message for ACL rules with an action not set to remark, but no remark is set.
-error_message_remark_without_action_remark = (
+ERROR_MESSAGE_REMARK_WITHOUT_ACTION_REMARK = (
     "CANNOT set remark unless action is set to remark."
 )
 
@@ -133,6 +133,10 @@ class AccessListForm(NetBoxModelForm):
     comments = CommentField()
 
     class Meta:
+        """
+        Defines the Model and fields to be used by the form.
+        """
+
         model = AccessList
         fields = (
             "region",
@@ -156,16 +160,19 @@ class Meta:
         }
 
     def __init__(self, *args, **kwargs):
+        """
+        Initializes the form
+        """
 
         # Initialize helper selectors
         instance = kwargs.get("instance")
         initial = kwargs.get("initial", {}).copy()
         if instance:
-            if type(instance.assigned_object) is Device:
+            if isinstance(instance.assigned_object, Device):
                 initial["device"] = instance.assigned_object
-            elif type(instance.assigned_object) is VirtualChassis:
+            elif isinstance(instance.assigned_object, VirtualChassis):
                 initial["virtual_chassis"] = instance.assigned_object
-            elif type(instance.assigned_object) is VirtualMachine:
+            elif isinstance(instance.assigned_object, VirtualMachine):
                 initial["virtual_machine"] = instance.assigned_object
         kwargs["initial"] = initial
 
@@ -231,12 +238,16 @@ def clean(self):
                 host_type: [error_same_acl_name],
                 "name": [error_same_acl_name],
             }
+        # Check if Access List has no existing rules before change the Access List's type.
         if self.instance.pk:
-            # Check if Access List has no existing rules before change the Access List's type.
             if (
                 acl_type == ACLTypeChoices.TYPE_EXTENDED
                 and self.instance.aclstandardrules.exists()
-            ) or (
+            ):
+                error_message["type"] = [
+                    "This ACL has ACL rules associated, CANNOT change ACL type.",
+                ]
+            elif (
                 acl_type == ACLTypeChoices.TYPE_STANDARD
                 and self.instance.aclextendedrules.exists()
             ):
@@ -250,7 +261,9 @@ def clean(self):
         return cleaned_data
 
     def save(self, *args, **kwargs):
-        # Set assigned object
+        """
+        Set assigned object
+        """
         self.instance.assigned_object = (
             self.cleaned_data.get("device")
             or self.cleaned_data.get("virtual_chassis")
@@ -315,22 +328,28 @@ class ACLInterfaceAssignmentForm(NetBoxModelForm):
     comments = CommentField()
 
     def __init__(self, *args, **kwargs):
+        """
+        Initialize helper selectors
+        """
 
-        # Initialize helper selectors
         instance = kwargs.get("instance")
         initial = kwargs.get("initial", {}).copy()
         if instance:
-            if type(instance.assigned_object) is Interface:
+            if isinstance(instance.assigned_object, Interface):
                 initial["interface"] = instance.assigned_object
                 initial["device"] = "device"
-            elif type(instance.assigned_object) is VMInterface:
+            elif isinstance(instance.assigned_object, VMInterface):
                 initial["vminterface"] = instance.assigned_object
                 initial["virtual_machine"] = "virtual_machine"
         kwargs["initial"] = initial
 
         super().__init__(*args, **kwargs)
 
     class Meta:
+        """
+        Defines the Model and fields to be used by the form.
+        """
+
         model = ACLInterfaceAssignment
         fields = (
             "access_list",
@@ -441,7 +460,9 @@ def clean(self):
         return cleaned_data
 
     def save(self, *args, **kwargs):
-        # Set assigned object
+        """
+        Set assigned object
+        """
         self.instance.assigned_object = self.cleaned_data.get(
             "interface",
         ) or self.cleaned_data.get("vminterface")
@@ -478,6 +499,10 @@ class ACLStandardRuleForm(NetBoxModelForm):
     )
 
     class Meta:
+        """
+        Defines the Model and fields to be used by the form.
+        """
+
         model = ACLStandardRule
         fields = (
             "access_list",
@@ -489,8 +514,8 @@ class Meta:
             "description",
         )
         help_texts = {
-            "index": help_text_acl_rule_index,
-            "action": help_text_acl_action,
+            "index": HELP_TEXT_ACL_RULE_INDEX,
+            "action": HELP_TEXT_ACL_ACTION,
             "remark": mark_safe(
                 "<b>*Note:</b> CANNOT be set if source prefix OR action is set.",
             ),
@@ -511,15 +536,15 @@ def clean(self):
         if cleaned_data.get("action") == "remark":
             # Check if action set to remark, but no remark set.
             if not cleaned_data.get("remark"):
-                error_message["remark"] = [error_message_no_remark]
+                error_message["remark"] = [ERROR_MESSAGE_NO_REMARK]
             # Check if action set to remark, but source_prefix set.
             if cleaned_data.get("source_prefix"):
                 error_message["source_prefix"] = [
-                    error_message_action_remark_source_prefix_set,
+                    ERROR_MESSAGE_ACTION_REMARK_SOURCE_PREFIX_SET,
                 ]
         # Check remark set, but action not set to remark.
         elif cleaned_data.get("remark"):
-            error_message["remark"] = [error_message_remark_without_action_remark]
+            error_message["remark"] = [ERROR_MESSAGE_REMARK_WITHOUT_ACTION_REMARK]
 
         if error_message:
             raise forms.ValidationError(error_message)
@@ -574,6 +599,10 @@ class ACLExtendedRuleForm(NetBoxModelForm):
     )
 
     class Meta:
+        """
+        Defines the Model and fields to be used by the form.
+        """
+
         model = ACLExtendedRule
         fields = (
             "access_list",
@@ -589,9 +618,9 @@ class Meta:
             "description",
         )
         help_texts = {
-            "action": help_text_acl_action,
+            "action": HELP_TEXT_ACL_ACTION,
             "destination_ports": help_text_acl_rule_logic,
-            "index": help_text_acl_rule_index,
+            "index": HELP_TEXT_ACL_RULE_INDEX,
             "protocol": help_text_acl_rule_logic,
             "remark": mark_safe(
                 "<b>*Note:</b> CANNOT be set if action is not set to remark.",
@@ -619,11 +648,11 @@ def clean(self):
         if cleaned_data.get("action") == "remark":
             # Check if action set to remark, but no remark set.
             if not cleaned_data.get("remark"):
-                error_message["remark"] = [error_message_no_remark]
+                error_message["remark"] = [ERROR_MESSAGE_NO_REMARK]
             # Check if action set to remark, but source_prefix set.
             if cleaned_data.get("source_prefix"):
                 error_message["source_prefix"] = [
-                    error_message_action_remark_source_prefix_set,
+                    ERROR_MESSAGE_ACTION_REMARK_SOURCE_PREFIX_SET,
                 ]
             # Check if action set to remark, but source_ports set.
             if cleaned_data.get("source_ports"):
@@ -647,7 +676,7 @@ def clean(self):
                 ]
         # Check if action not set to remark, but remark set.
         elif cleaned_data.get("remark"):
-            error_message["remark"] = [error_message_remark_without_action_remark]
+            error_message["remark"] = [ERROR_MESSAGE_REMARK_WITHOUT_ACTION_REMARK]
 
         if error_message:
             raise forms.ValidationError(error_message)

netbox_acls/models/access_list_rules.py

@@ -55,13 +55,22 @@ class BaseACLRule(NetBoxModel):
     clone_fields = ("access_list", "action", "source_prefix")
 
     def __str__(self):
+        """
+        Return a string representation of the model.
+        """
         return f"{self.access_list}: Rule {self.index}"
 
     def get_action_color(self):
+        """
+        Return the color for the action.
+        """
         return ACLRuleActionChoices.colors.get(self.action)
 
     @classmethod
     def get_prerequisite_models(cls):
+        """
+        Return a list of prerequisite models for this model.
+        """
         return [apps.get_model("ipam.Prefix"), AccessList]
 
     class Meta:
@@ -99,6 +108,9 @@ def get_absolute_url(self):
 
     @classmethod
     def get_prerequisite_models(cls):
+        """
+        Return a list of prerequisite models for this model.
+        """
         return [AccessList]
 
     class Meta(BaseACLRule.Meta):
@@ -160,10 +172,16 @@ def get_absolute_url(self):
         return reverse("plugins:netbox_acls:aclextendedrule", args=[self.pk])
 
     def get_protocol_color(self):
+        """
+        Return the color for the protocol.
+        """
         return ACLProtocolChoices.colors.get(self.protocol)
 
     @classmethod
     def get_prerequisite_models(cls):
+        """
+        Return a list of prerequisite models for this model.
+        xs"""
         return [apps.get_model("ipam.Prefix"), AccessList]
 
     class Meta(BaseACLRule.Meta):