diff --git a/CHANGELOG.md b/CHANGELOG.md index ee2e0797..3c556597 100644 --- a/CHANGELOG.md +++ b/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 diff --git a/docs/source/artifact.rst b/docs/source/artifact.rst index 26600970..0c47ca31 100644 --- a/docs/source/artifact.rst +++ b/docs/source/artifact.rst @@ -1,5 +1,5 @@ -switch -====== +artifact +======== .. automodule:: fabrictestbed_extensions.fablib.artifact :members: diff --git a/docs/source/artifact_manager_ui.rst b/docs/source/artifact_manager_ui.rst index d46d9689..1b0a75a5 100644 --- a/docs/source/artifact_manager_ui.rst +++ b/docs/source/artifact_manager_ui.rst @@ -1,5 +1,5 @@ -switch -====== +artifact_manager_ui +=================== .. automodule:: fabrictestbed_extensions.ui.artifact_manager_ui :members: diff --git a/docs/source/component.rst b/docs/source/component.rst index 7321e038..1b772078 100644 --- a/docs/source/component.rst +++ b/docs/source/component.rst @@ -6,4 +6,5 @@ component .. autoclass:: fabrictestbed_extensions.fablib.component.Component :members: + :no-index: :special-members: __str__ diff --git a/docs/source/index.rst b/docs/source/index.rst index bfc95a3f..298bd2d8 100644 --- a/docs/source/index.rst +++ b/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 diff --git a/fabrictestbed_extensions/fablib/component.py b/fabrictestbed_extensions/fablib/component.py index c9eea51b..575dd890 100644 --- a/fabrictestbed_extensions/fablib/component.py +++ b/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() diff --git a/fabrictestbed_extensions/fablib/slice.py b/fabrictestbed_extensions/fablib/slice.py index 03cde3bc..f59b5ee9 100644 --- a/fabrictestbed_extensions/fablib/slice.py +++ b/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