From 067ca36f8d5aa3153d30518bb8db1035d1778d72 Mon Sep 17 00:00:00 2001 From: Sajith Sasidharan Date: Mon, 16 Sep 2024 11:51:43 -0500 Subject: [PATCH 01/12] Add docstring to Component.get_short_name() --- fabrictestbed_extensions/fablib/component.py | 3 +++ 1 file changed, 3 insertions(+) diff --git a/fabrictestbed_extensions/fablib/component.py b/fabrictestbed_extensions/fablib/component.py index c9eea51b..874932f1 100644 --- a/fabrictestbed_extensions/fablib/component.py +++ b/fabrictestbed_extensions/fablib/component.py @@ -384,6 +384,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()}-") :] From 2492d5138fea7c3c5b172b14e7d0d60725e92c18 Mon Sep 17 00:00:00 2001 From: Sajith Sasidharan Date: Mon, 16 Sep 2024 11:52:29 -0500 Subject: [PATCH 02/12] Add docstring to Component.get_fablib_manager() --- fabrictestbed_extensions/fablib/component.py | 3 +++ 1 file changed, 3 insertions(+) diff --git a/fabrictestbed_extensions/fablib/component.py b/fabrictestbed_extensions/fablib/component.py index 874932f1..26659ad4 100644 --- a/fabrictestbed_extensions/fablib/component.py +++ b/fabrictestbed_extensions/fablib/component.py @@ -97,6 +97,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): From 6058e7b8903b15781056d04aae8722b203d1c29f Mon Sep 17 00:00:00 2001 From: Sajith Sasidharan Date: Mon, 16 Sep 2024 11:53:10 -0500 Subject: [PATCH 03/12] Add docstring to Component.get_pretty_name_dict() --- fabrictestbed_extensions/fablib/component.py | 3 +++ 1 file changed, 3 insertions(+) diff --git a/fabrictestbed_extensions/fablib/component.py b/fabrictestbed_extensions/fablib/component.py index 26659ad4..4055cba1 100644 --- a/fabrictestbed_extensions/fablib/component.py +++ b/fabrictestbed_extensions/fablib/component.py @@ -113,6 +113,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", From 42c863d817737bb31a6b869d0586ae97c2c187d0 Mon Sep 17 00:00:00 2001 From: Sajith Sasidharan Date: Mon, 16 Sep 2024 11:55:16 -0500 Subject: [PATCH 04/12] Add docstring to Component.get_fim() --- fabrictestbed_extensions/fablib/component.py | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/fabrictestbed_extensions/fablib/component.py b/fabrictestbed_extensions/fablib/component.py index 4055cba1..d5c3c4fc 100644 --- a/fabrictestbed_extensions/fablib/component.py +++ b/fabrictestbed_extensions/fablib/component.py @@ -645,6 +645,12 @@ 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): From 6dd03db834d9ee1564aeadcf7856584a591c6954 Mon Sep 17 00:00:00 2001 From: Sajith Sasidharan Date: Mon, 16 Sep 2024 12:07:59 -0500 Subject: [PATCH 05/12] Add docstrings to Component.{set,get}_user_data() --- fabrictestbed_extensions/fablib/component.py | 21 +++++++++++++++++++- 1 file changed, 20 insertions(+), 1 deletion(-) diff --git a/fabrictestbed_extensions/fablib/component.py b/fabrictestbed_extensions/fablib/component.py index d5c3c4fc..fc3591c7 100644 --- a/fabrictestbed_extensions/fablib/component.py +++ b/fabrictestbed_extensions/fablib/component.py @@ -654,11 +654,30 @@ def get_fim(self): 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: From d88fe207ae1a7b30d0a27be2dd4b25ad414a277a Mon Sep 17 00:00:00 2001 From: Sajith Sasidharan Date: Mon, 16 Sep 2024 12:10:32 -0500 Subject: [PATCH 06/12] Add docstring to Component.delete() --- fabrictestbed_extensions/fablib/component.py | 3 +++ 1 file changed, 3 insertions(+) diff --git a/fabrictestbed_extensions/fablib/component.py b/fabrictestbed_extensions/fablib/component.py index fc3591c7..f4faf0d1 100644 --- a/fabrictestbed_extensions/fablib/component.py +++ b/fabrictestbed_extensions/fablib/component.py @@ -684,6 +684,9 @@ def get_user_data(self) -> dict: return {} def delete(self): + """ + Remove the component from the slice/node. + """ if self.get_interfaces(): for interface in self.get_interfaces(): interface.delete() From 7700d15c626ea0c5046a550031a6a0c0797506c9 Mon Sep 17 00:00:00 2001 From: Sajith Sasidharan Date: Mon, 16 Sep 2024 12:11:43 -0500 Subject: [PATCH 07/12] Update changelog --- CHANGELOG.md | 1 + 1 file changed, 1 insertion(+) 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 From 27734dc82a13d69d40652823d2ff38c0270ce895 Mon Sep 17 00:00:00 2001 From: Sajith Sasidharan Date: Mon, 16 Sep 2024 12:20:31 -0500 Subject: [PATCH 08/12] Add a docstring to Component class --- docs/source/component.rst | 1 + fabrictestbed_extensions/fablib/component.py | 4 ++++ 2 files changed, 5 insertions(+) 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/fabrictestbed_extensions/fablib/component.py b/fabrictestbed_extensions/fablib/component.py index f4faf0d1..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, From 78c7e96eb0ef1bce1f7fc037b8479850b6bc4075 Mon Sep 17 00:00:00 2001 From: Sajith Sasidharan Date: Mon, 16 Sep 2024 12:23:31 -0500 Subject: [PATCH 09/12] Fix a warning when running `sphinx-build -W` This is the warning: > fabrictestbed_extensions/fablib/slice.py:docstring of > fabrictestbed_extensions.fablib.slice.Slice.add_l3network:53:Field > list ends without a blank line; unexpected unindent. [docutils] --- fabrictestbed_extensions/fablib/slice.py | 12 +++++++----- 1 file changed, 7 insertions(+), 5 deletions(-) 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 From 6586eddadd9343b82a12b64861a0833011a4086f Mon Sep 17 00:00:00 2001 From: Sajith Sasidharan Date: Mon, 16 Sep 2024 12:31:18 -0500 Subject: [PATCH 10/12] Include artifact and artifact_manager_ui in doc toctree Addressing these warnings: > docs/source/artifact.rst:document isn't included in any toctree and > docs/source/artifact_manager_ui.rst:document isn't included in any > toctree --- docs/source/index.rst | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/source/index.rst b/docs/source/index.rst index bfc95a3f..9ace8148 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -136,6 +136,8 @@ FABLib functionality is made available in these modules: facility_port.rst resources.rst site.rst + artifact + artifact_manager_ui Indices and tables From fb0716e773999f1a98e85ad562c5c817e5aadf08 Mon Sep 17 00:00:00 2001 From: Sajith Sasidharan Date: Mon, 16 Sep 2024 14:40:52 -0500 Subject: [PATCH 11/12] Use correct titles Addressing this warnings from `sphinx-build -W`: > docstring of > fabrictestbed_extensions.fablib.interface.Interface:1:more than one > target found for cross-reference 'Switch': > fabrictestbed_extensions.fablib.site.Switch, > fabrictestbed_extensions.fablib.switch.Switch [ref.python] --- docs/source/artifact.rst | 4 ++-- docs/source/artifact_manager_ui.rst | 4 ++-- 2 files changed, 4 insertions(+), 4 deletions(-) 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: From 65edec5dc611dab98f0e948e9d6570bdee99d0a7 Mon Sep 17 00:00:00 2001 From: Sajith Sasidharan Date: Mon, 16 Sep 2024 14:41:08 -0500 Subject: [PATCH 12/12] Be consistent in toctree --- docs/source/index.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/source/index.rst b/docs/source/index.rst index 9ace8148..298bd2d8 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -131,11 +131,11 @@ 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