Merge pull request #368 from fabric-testbed/317.component-docstrings

Add docstrings to `fablib.component`

CHANGELOG.md

@@ -15,6 +15,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - 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))
 
 ## [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/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

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/slice.py

@@ -1075,15 +1075,17 @@ def add_l3network(
         :param type: L3 network type "IPv4" or "IPv6"
         :type type: String
 
-        :param user_data
+        :param user_data:
         :type user_data: dict
 
-        :param technology: Specify the technology used should be set to AL2S when using for AL2S peering; otherwise None
+        :param technology: Specify the technology used should be set
+            to AL2S when using for AL2S peering; otherwise None
         :type technology: str
 
-        :param subnet: Request a specific subnet for FabNetv4, FabNetv6 or FabNetv6Ext services.
-                       It's ignored for any other services.
-        :type ipaddress.ip_network
+        :param subnet: Request a specific subnet for FabNetv4,
+            FabNetv6 or FabNetv6Ext services.  It's ignored for any
+            other services.
+        :type subnet: ipaddress.ip_network
 
         :return: a new L3 network service
         :rtype: NetworkService