Merge pull request #322 from fabric-testbed/318.node-function-docstrings

Add missing docstrings to `node` module

CHANGELOG.md

@@ -16,6 +16,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - create_ssh_config adds extra indentation (Issue [#300](https://github.com/fabric-testbed/fabrictestbed-extensions/issues/300))
 - Remove duplicate Node.delete() method (Issue [#321](https://github.com/fabric-testbed/fabrictestbed-extensions/issues/321))
 
+## Added
+- Missing docstrings in node module (Issue [#318](https://github.com/fabric-testbed/fabrictestbed-extensions/issues/318))
+
 ## [1.6.4] - 2024-03-05
 
 ### Fixed

docs/source/node.rst

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

fabrictestbed_extensions/fablib/fablib.py

@@ -676,27 +676,30 @@ def __init__(
 
     def validate_config(self):
         """
-        Validate and create Fablib config - checks if all the required configuration exists for slice
-        provisioning to work successfully
+        Validate and create Fablib config - checks if all the required
+        configuration exists for slice provisioning to work
+        successfully
 
-        - Checks Credential Manager Host is configured properly
+            - Checks Credential Manager Host is configured properly
 
-        - Checks Orchestrator Host is configured properly
+            - Checks Orchestrator Host is configured properly
 
-        - Checks Core API Host is configured properly
+            - Checks Core API Host is configured properly
 
-        - Checks Bastion Host is configured properly
+            - Checks Bastion Host is configured properly
 
-        - Check Sliver keys exist; create sliver keys if they do not exist
+            - Check Sliver keys exist; create sliver keys if they do
+              not exist
 
-        - Check Bastion keys exist and are not expired; update/create bastion keys if expired or do not exist
+            - Check Bastion keys exist and are not expired;
+              update/create bastion keys if expired or do not exist
 
-        - Check Bastion Username is configured
+            - Check Bastion Username is configured
 
-        - Check Project Id is configured
+            - Check Project Id is configured
+
+        .. deprecated:: 1.6.5 Use `verify_and_configure()` instead.
 
-        .. deprecated:: 1.6.5
-           Use `verify_and_configure()` instead.
         @raises Exception if the configuration is invalid
         """
         warnings.warn(

fabrictestbed_extensions/fablib/node.py

@@ -83,6 +83,10 @@
 
 
 class Node:
+    """
+    A class for working with FABRIC nodes.
+    """
+
     default_cores = 2
     default_ram = 8
     default_disk = 10
@@ -121,6 +125,9 @@ def __init__(self, slice: Slice, node: FimNode):
         logging.getLogger("paramiko").setLevel(logging.WARNING)
 
     def get_fablib_manager(self):
+        """
+        Get a reference to :py:class:`.FablibManager`.
+        """
         return self.slice.get_fablib_manager()
 
     def __str__(self):
@@ -230,6 +237,11 @@ def toJson(self):
 
     @staticmethod
     def get_pretty_name_dict():
+        """
+        Return mappings from non-pretty names to pretty names.
+
+        Pretty names are in table headers.
+        """
         return {
             "id": "ID",
             "name": "Name",
@@ -648,6 +660,9 @@ def combined_filter_function(x):
         )
 
     def get_networks(self):
+        """
+        Get a list of networks attached to the node.
+        """
         networks = []
         for interface in self.get_interfaces():
             networks.append(interface.get_network())
@@ -1206,6 +1221,12 @@ def validIPAddress(self, IP: str) -> str:
     def get_paramiko_key(
         self, private_key_file: str = None, get_private_key_passphrase: str = None
     ) -> paramiko.PKey:
+        """
+        Get SSH pubkey, for internal use.
+
+        :return: an SSH pubkey.
+        :rtype: paramiko.PKey
+        """
         # TODO: This is a bit of a hack and should probably test he keys for their types
         # rather than relying on execptions
         if get_private_key_passphrase:
@@ -2749,26 +2770,43 @@ def add_storage(self, name: str, auto_mount: bool = False) -> Component:
         return Component.new_storage(node=self, name=name, auto_mount=auto_mount)
 
     def get_fim(self):
+        """
+        Get FABRIC Information Model (fim) object for the node.
+        """
         return self.get_fim_node()
 
     def set_user_data(self, user_data: dict):
+        """
+        Set user data.
+
+        :param user_data: a `dict`.
+        """
         self.get_fim().set_property(
             pname="user_data", pval=UserData(json.dumps(user_data))
         )
 
     def get_user_data(self):
+        """
+        Get user data.
+        """
         try:
             return json.loads(str(self.get_fim().get_property(pname="user_data")))
         except:
             return {}
 
     def delete(self):
+        """
+        Remove the node, including components connected to it.
+        """
         for component in self.get_components():
             component.delete()
 
         self.get_slice().get_fim_topology().remove_node(name=self.get_name())
 
     def init_fablib_data(self):
+        """
+        Initialize fablib data.  Called by :py:meth:`new_node()`.
+        """
         fablib_data = {
             "instantiated": "False",
             "run_update_commands": "False",
@@ -2778,12 +2816,18 @@ def init_fablib_data(self):
         self.set_fablib_data(fablib_data)
 
     def get_fablib_data(self):
+        """
+        Get fablib data. Usually used internally.
+        """
         try:
             return self.get_user_data()["fablib_data"]
         except:
             return {}
 
     def set_fablib_data(self, fablib_data: dict):
+        """
+        Set fablib data. Usually used internally.
+        """
         user_data = self.get_user_data()
         user_data["fablib_data"] = fablib_data
         self.set_user_data(user_data)
@@ -2900,12 +2944,22 @@ def post_boot_tasks(self):
             return []
 
     def get_routes(self):
+        """
+        .. warning::
+
+            This method is for fablib internal use, and will be made private in the future.
+        """
         try:
             return self.get_fablib_data()["routes"]
         except Exception as e:
             return []
 
     def config_routes(self):
+        """
+        .. warning::
+
+            This method is for fablib internal use, and will be made private in the future.
+        """
         routes = self.get_routes()
 
         for route in routes:
@@ -2931,6 +2985,12 @@ def config_routes(self):
             self.ip_route_add(subnet=ipaddress.ip_network(subnet), gateway=next_hop)
 
     def run_post_boot_tasks(self, log_dir: str = "."):
+        """
+        Run post-boot tasks.  Called by :py:meth:`config()`.
+
+        Post-boot tasks are list of commands associated with
+        `post_boot_tasks` in fablib data.
+        """
         logging.debug(f"run_post_boot_tasks: {self.get_name()}")
         fablib_data = self.get_fablib_data()
         if "post_boot_tasks" in fablib_data:
@@ -2965,6 +3025,12 @@ def run_post_boot_tasks(self, log_dir: str = "."):
                 logging.error(f"Invalid post boot command: {command}")
 
     def run_post_update_commands(self, log_dir: str = "."):
+        """
+        Run post-update commands.  Called by :py:meth:`config()`.
+
+        Post-update commands are list of commands associated with
+        `post_update_commands` in fablib data.
+        """
         fablib_data = self.get_fablib_data()
         if "post_update_commands" in fablib_data:
             commands = fablib_data["post_update_commands"]
@@ -2977,6 +3043,9 @@ def run_post_update_commands(self, log_dir: str = "."):
             )
 
     def is_instantiated(self):
+        """
+        Returns `True` if the node has been instantiated.
+        """
         fablib_data = self.get_fablib_data()
         if "instantiated" not in fablib_data:
             logging.debug(
@@ -2996,18 +3065,27 @@ def is_instantiated(self):
             return False
 
     def set_instantiated(self, instantiated: bool = True):
+        """
+        Mark node as instantiated. Called by :py:meth:`config()`.
+        """
         fablib_data = self.get_fablib_data()
         fablib_data["instantiated"] = str(instantiated)
         self.set_fablib_data(fablib_data)
 
     def run_update_commands(self):
+        """
+        Returns `True` if `run_update_commands` flag is set.
+        """
         fablib_data = self.get_fablib_data()
         if fablib_data["run_update_commands"] == "True":
             return True
         else:
             return False
 
     def set_run_update_commands(self, run_update_commands: bool = True):
+        """
+        Set `run_update_commands` flag.
+        """
         fablib_data = self.get_fablib_data()
         fablib_data["run_update_commands"] = str(run_update_commands)
         self.set_fablib_data(fablib_data)