Add an initial stab at docstrings - enable docstring pylinter

config/__init__.py

@@ -13,6 +13,7 @@
 # limitations under the License.
 #
 # -*- coding: utf-8 -*-
+""" A vppcfg configuration module that exposes its semantic/syntax validators """
 from __future__ import (
     absolute_import,
     division,
@@ -66,6 +67,15 @@ class IPInterfaceWithPrefixLength(Validator):
 
 
 class Validator:
+    """The Validator class takes a schema filename (which may be None, in which
+    case a built-in default is used), and a given YAML file represented as a string,
+    and holds it against syntax and semantic validators, returning a tuple of (bool,list)
+    where the boolean signals success/failure, and the list of strings are messages
+    that were added when validating the YAML config.
+
+    The purpose is to  ensure that the YAML file is both syntactically correct,
+    which is ensured by Yamale, and semantically correct, which is ensured by a set
+    of built-in validators, and user-added validators (see the add_validator() method)."""
     def __init__(self, schema):
         self.logger = logging.getLogger("vppcfg.config")
         self.logger.addHandler(logging.NullHandler())
@@ -81,6 +91,8 @@ class Validator:
         ]
 
     def validate(self, yaml):
+        """Validate the semantics of all YAML maps, by calling self.validators in turn,
+        and then optionally calling validators that were added with add_validator()"""
         ret_retval = True
         ret_msgs = []
         if not yaml:

config/address.py

@@ -11,6 +11,7 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 #
+""" A vppcfg configuration module that handles addresses """
 import ipaddress
 
 

config/bondethernet.py

@@ -11,6 +11,7 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 #
+""" A vppcfg configuration module that handles bondethernets """
 import logging
 from config import interface
 from config import mac
@@ -162,6 +163,7 @@ def int_to_lb(loadbalance):
 
 
 def validate_bondethernets(yaml):
+    """Validate the semantics of all YAML 'bondethernets' entries"""
     result = True
     msgs = []
     logger = logging.getLogger("vppcfg.config")

config/bridgedomain.py

@@ -11,6 +11,7 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 #
+""" A vppcfg configuration module that handles bridgedomains """
 import logging
 from config import interface
 from config import loopback
@@ -81,6 +82,8 @@ def bvi_unique(yaml, bviname):
 
 
 def get_settings(yaml, ifname):
+    """Return a dictionary of 'settings' including their VPP defaults, for the
+    bridgedomain identified by 'ifname' (bd10)"""
     ifname, iface = get_by_name(yaml, ifname)
     if not iface:
         return None
@@ -115,6 +118,7 @@ def get_settings(yaml, ifname):
 
 
 def validate_bridgedomains(yaml):
+    """Validate the semantics of all YAML 'bridgedomains' entries"""
     result = True
     msgs = []
     logger = logging.getLogger("vppcfg.config")

config/interface.py

@@ -11,6 +11,7 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 #
+""" A vppcfg configuration module that validates interfaces """
 import logging
 from config import bondethernet
 from config import bridgedomain
@@ -415,6 +416,7 @@ def get_admin_state(yaml, ifname):
 
 
 def validate_interfaces(yaml):
+    """Validate the semantics of all YAML 'interfaces' entries"""
     result = True
     msgs = []
     logger = logging.getLogger("vppcfg.config")

config/lcp.py

@@ -11,6 +11,7 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 #
+""" A vppcfg configuration module that validates Linux Control Plane (lcp) elements """
 
 
 def get_lcps(yaml, interfaces=True, loopbacks=True, bridgedomains=True):

config/loopback.py

@@ -11,6 +11,7 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 #
+""" A vppcfg configuration module that validates loopbacks """
 import logging
 from config import lcp
 from config import address
@@ -53,6 +54,7 @@ def is_loopback(yaml, ifname):
 
 
 def validate_loopbacks(yaml):
+    """Validate the semantics of all YAML 'loopbacks' entries"""
     result = True
     msgs = []
     logger = logging.getLogger("vppcfg.config")

config/mac.py

@@ -11,6 +11,7 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 #
+""" A vppcfg configuration module that validates MAC addresses """
 import netaddr
 
 

config/tap.py

@@ -11,6 +11,7 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 #
+""" A vppcfg configuration module that validates taps """
 import logging
 from config import mac
 
@@ -54,6 +55,7 @@ def is_host_name_unique(yaml, hostname):
 
 
 def validate_taps(yaml):
+    """Validate the semantics of all YAML 'taps' entries"""
     result = True
     msgs = []
     logger = logging.getLogger("vppcfg.config")

config/test_bondethernet.py

@@ -1,3 +1,18 @@
+#
+# Copyright (c) 2022 Pim van Pelt
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at:
+#     http://www.apache.org/licenses/LICENSE-2.0
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+# -*- coding: utf-8 -*-
+""" Unit tests for bondethernet """
 import unittest
 import yaml
 import config.bondethernet as bondethernet

config/test_bridgedomain.py

@@ -1,3 +1,18 @@
+#
+# Copyright (c) 2022 Pim van Pelt
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at:
+#     http://www.apache.org/licenses/LICENSE-2.0
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+# -*- coding: utf-8 -*-
+""" Unit tests for bridgedomains """
 import unittest
 import yaml
 import config.bridgedomain as bridgedomain

config/test_interface.py

@@ -1,3 +1,18 @@
+#
+# Copyright (c) 2022 Pim van Pelt
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at:
+#     http://www.apache.org/licenses/LICENSE-2.0
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+# -*- coding: utf-8 -*-
+""" Unit tests for interfaces """
 import unittest
 import yaml
 import config.interface as interface

config/test_lcp.py

@@ -1,3 +1,18 @@
+#
+# Copyright (c) 2022 Pim van Pelt
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at:
+#     http://www.apache.org/licenses/LICENSE-2.0
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+# -*- coding: utf-8 -*-
+""" Unit tests for LCPs """
 import unittest
 import yaml
 import config.lcp as lcp

config/test_loopback.py

@@ -1,3 +1,18 @@
+#
+# Copyright (c) 2022 Pim van Pelt
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at:
+#     http://www.apache.org/licenses/LICENSE-2.0
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+# -*- coding: utf-8 -*-
+""" Unit tests for loopbacks """
 import unittest
 import yaml
 import config.loopback as loopback

config/test_mac.py

@@ -1,3 +1,18 @@
+#
+# Copyright (c) 2022 Pim van Pelt
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at:
+#     http://www.apache.org/licenses/LICENSE-2.0
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+# -*- coding: utf-8 -*-
+""" Unit tests for MAC addresses """
 import unittest
 import config.mac as mac
 

config/test_tap.py

@@ -1,3 +1,18 @@
+#
+# Copyright (c) 2022 Pim van Pelt
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at:
+#     http://www.apache.org/licenses/LICENSE-2.0
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+# -*- coding: utf-8 -*-
+""" Unit tests for taps """
 import unittest
 import yaml
 import config.tap as tap

config/test_vxlan_tunnel.py

@@ -1,3 +1,18 @@
+#
+# Copyright (c) 2022 Pim van Pelt
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at:
+#     http://www.apache.org/licenses/LICENSE-2.0
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+# -*- coding: utf-8 -*-
+""" Unit tests for vxlan_tunnels """
 import unittest
 import yaml
 import config.vxlan_tunnel as vxlan_tunnel

config/vxlan_tunnel.py

@@ -11,6 +11,7 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 #
+""" A vppcfg configuration module that validates vxlan_tunnels """
 import logging
 import ipaddress
 
@@ -56,6 +57,7 @@ def get_vxlan_tunnels(yaml):
 
 
 def validate_vxlan_tunnels(yaml):
+    """Validate the semantics of all YAML 'vxlan_tunnels' entries"""
     result = True
     msgs = []
     logger = logging.getLogger("vppcfg.config")