merge from main

.github/workflows/check_docstring_coverage.yml

@@ -0,0 +1,42 @@
+# A check to ensure that our docstring coverage remains pretty good.
+#
+# We use interrogate (https://interrogate.readthedocs.io/) to check
+# docstring coverage.  Settings are under `[tool.interrogate]` section
+# of the pyproject.toml file in the top-level directory.
+
+name: Check docstring coverage
+
+on:
+  push:
+    branches:
+      - "main"
+  pull_request:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+
+  checks:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Check out sources
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.x"
+          cache: 'pip'  # cache pip dependencies
+          cache-dependency-path: pyproject.toml
+
+      - name: Install interrogate
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install interrogate==1.7.0
+
+      - name: Check docstring coverage with interrogate
+        run: |
+          python -m interrogate -vv fabrictestbed_extensions

CHANGELOG.md

@@ -12,12 +12,17 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Missing docstrings in network_service module (Issue [#313](https://github.com/fabric-testbed/fabrictestbed-extensions/issues/314))
 - Artifact Manager Support (Issue [#358](https://github.com/fabric-testbed/fabrictestbed-extensions/issues/358))
 - FabNet user specified subnets (Issue [#361](https://github.com/fabric-testbed/fabrictestbed-extensions/issues/361))
+- Print a hint when bastion probe fails (Issue [#363](https://github.com/fabric-testbed/fabrictestbed-extensions/issues/363))
+- Missing docstrings in resources module (Issue [#315](https://github.com/fabric-testbed/fabrictestbed-extensions/issues/315))
+- Missing docstrings in slice module (Issue [#316](https://github.com/fabric-testbed/fabrictestbed-extensions/issues/316))
+- Missing docstrings in component module (Issue [#317](https://github.com/fabric-testbed/fabrictestbed-extensions/issues/317))
+- Missing docstrings in fablib module (Issue [#319](https://github.com/fabric-testbed/fabrictestbed-extensions/issues/319))
+- Missing docstrings in fablib.config module (Issue [#320](https://github.com/fabric-testbed/fabrictestbed-extensions/issues/320))
 - Renew Slice leaves the slivers in ActiveTicketed State (Issue [#364](https://github.com/fabric-testbed/fabrictestbed-extensions/issues/364))
 - get_management_os_interface and get_dataplane_os_interfaces doesn't take into account IPv6 addresses. (Issue [#362](https://github.com/fabric-testbed/fabrictestbed-extensions/issues/362))
 - Disable post boot config for renew (Issue [#373](https://github.com/fabric-testbed/fabrictestbed-extensions/issues/373))
 - slice.renew() should pass **kwargs through to slice.submit() (Issue [#374](https://github.com/fabric-testbed/fabrictestbed-extensions/issues/374))
 - node.execute() retry parameter is off-by-one (and/or misnamed) (Issue [#375](https://github.com/fabric-testbed/fabrictestbed-extensions/issues/375))
-
 
 ## [1.7.3] - 08/05/2024
 ### Fixed

docs/source/artifact.rst

@@ -1,5 +1,5 @@
-switch
-======
+artifact
+========
 
 .. automodule:: fabrictestbed_extensions.fablib.artifact
    :members:

docs/source/artifact_manager_ui.rst

@@ -1,5 +1,5 @@
-switch
-======
+artifact_manager_ui
+===================
 
 .. automodule:: fabrictestbed_extensions.ui.artifact_manager_ui
    :members:

docs/source/component.rst

@@ -6,4 +6,5 @@ component
 
 .. autoclass:: fabrictestbed_extensions.fablib.component.Component
    :members:
+   :no-index:
    :special-members: __str__

docs/source/conf.py

@@ -32,6 +32,9 @@
     "sphinx.ext.duration",
     "sphinx.ext.doctest",
     "sphinx.ext.autodoc",
+    "sphinx_autodoc_typehints",
+    "sphinx.ext.viewcode",
+    "sphinx.ext.intersphinx",
 ]
 
 # Add any paths that contain templates here, relative to this directory.
@@ -46,6 +49,11 @@
 # "class" and "both".
 autoclass_content = "init"
 
+# Link to Python stdlib docs when possible.
+intersphinx_mapping = {
+    "python": ("https://docs.python.org/3", None),
+}
+
 # -- Options for HTML output -------------------------------------------------
 
 # The theme to use for HTML and HTML Help pages.  See the documentation for

docs/source/fablib.rst

@@ -6,4 +6,5 @@ fablib
 
 .. autoclass:: fabrictestbed_extensions.fablib.fablib.FablibManager
    :members:
+   :no-index:
    :special-members: __str__

docs/source/index.rst

@@ -131,11 +131,13 @@ FABLib functionality is made available in these modules:
    node
    component
    interface
-   switch.rst
+   switch
    network_service
-   facility_port.rst
-   resources.rst
-   site.rst
+   facility_port
+   resources
+   site
+   artifact
+   artifact_manager_ui
 
 
 Indices and tables

docs/source/network_service.rst

@@ -6,5 +6,5 @@ network_service
 
 .. autoclass:: fabrictestbed_extensions.fablib.network_service.NetworkService
    :members:
-   :no-index:      
+   :no-index:
    :special-members: __str__

docs/source/resources.rst

@@ -6,12 +6,15 @@ resources
 
 .. autoclass:: fabrictestbed_extensions.fablib.resources.Resources
    :members:
+   :no-index:
    :special-members: __str__
 
 .. autoclass:: fabrictestbed_extensions.fablib.resources.Links
    :members:
+   :no-index:
    :special-members: __str__
 
 .. autoclass:: fabrictestbed_extensions.fablib.resources.FacilityPorts
    :members:
-   :special-members: __str__
+   :no-index:
+   :special-members: __str__

fabrictestbed_extensions/fablib/component.py

@@ -61,6 +61,10 @@
 
 
 class Component:
+    """
+    A class for working with FABRIC components.
+    """
+
     component_model_map = {
         Constants.CMP_NIC_Basic: ComponentModelType.SharedNIC_ConnectX_6,
         Constants.CMP_NIC_ConnectX_6: ComponentModelType.SmartNIC_ConnectX_6,
@@ -97,6 +101,9 @@ def __str__(self):
         return tabulate(table)
 
     def get_fablib_manager(self):
+        """
+        Get the Fabric library manager associated with the component.
+        """
         return self.get_slice().get_fablib_manager()
 
     def toJson(self):
@@ -110,6 +117,9 @@ def toJson(self):
 
     @staticmethod
     def get_pretty_name_dict():
+        """
+        Returns the mapping used when rendering table headers.
+        """
         return {
             "name": "Name",
             "short_name": "Short Name",
@@ -384,6 +394,9 @@ def get_site(self) -> str:
         return self.node.get_site()
 
     def get_short_name(self):
+        """
+        Gets the short name of the component.
+        """
         # strip of the extra parts of the name added by fim
         return self.get_name()[len(f"{self.get_node().get_name()}-") :]
 
@@ -636,20 +649,48 @@ def new_storage(node: Node, name: str, auto_mount: bool = False):
         return Component(node=node, fim_component=fim_component)
 
     def get_fim(self):
+        """
+        Gets the component's FABRIC Information Model (fim) object.
+
+        This method is used to access data at a lower level than
+        FABlib.
+        """
         return self.get_fim_component()
 
     def set_user_data(self, user_data: dict):
+        """
+        Set the user data for the component.
+
+        This method stores the given user data dictionary as a JSON
+        string in the FIM object associated with the component.
+
+        :param user_data: The user data to be set.
+        :type user_data: dict
+        """
         self.get_fim().set_property(
             pname="user_data", pval=UserData(json.dumps(user_data))
         )
 
-    def get_user_data(self):
+    def get_user_data(self) -> dict:
+        """
+        Retrieve the user data for the component.
+
+        This method fetches the user data stored in the FIM object
+        associated with the component and returns it as a dictionary.
+        If an error occurs, it returns an empty dictionary.
+
+        :return: The user data dictionary.
+        :rtype: dict
+        """
         try:
             return json.loads(str(self.get_fim().get_property(pname="user_data")))
         except:
             return {}
 
     def delete(self):
+        """
+        Remove the component from the slice/node.
+        """
         if self.get_interfaces():
             for interface in self.get_interfaces():
                 interface.delete()

fabrictestbed_extensions/fablib/config/config.py

@@ -38,10 +38,18 @@
 
 
 class ConfigException(Exception):
+    """
+    An exception class to represent configuration errors.
+    """
+
     pass
 
 
 class Config:
+    """
+    A class that represents fablib configuration.
+    """
+
     LOG_LEVELS = {
         "DEBUG": logging.DEBUG,
         "INFO": logging.INFO,
@@ -744,6 +752,9 @@ def get_config_pretty_names_dict(self) -> Dict[str, str]:
         return self.REQUIRED_ATTRS_PRETTY_NAMES
 
     def save_config(self):
+        """
+        Write the configuration file.
+        """
         if self.config_file_path is None:
             print("Config file path not set!")
             return