From 2dc6eaddea10379cedf4bd8753ae70b1539088ef Mon Sep 17 00:00:00 2001 From: Sajith Sasidharan Date: Fri, 28 Jun 2024 13:12:26 -0500 Subject: [PATCH 01/17] Add docstring for FacilityPort class --- fabrictestbed_extensions/fablib/facility_port.py | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/fabrictestbed_extensions/fablib/facility_port.py b/fabrictestbed_extensions/fablib/facility_port.py index 568fbd5b..d524f749 100644 --- a/fabrictestbed_extensions/fablib/facility_port.py +++ b/fabrictestbed_extensions/fablib/facility_port.py @@ -47,6 +47,10 @@ class FacilityPort: + """ + A class for working with FABRIC facility ports. + """ + fim_interface = None slice = None From a4437d7ec0d282456a0815b5161672b1175c5e03 Mon Sep 17 00:00:00 2001 From: Sajith Sasidharan Date: Fri, 28 Jun 2024 11:00:46 -0500 Subject: [PATCH 02/17] Add docstrings for FacilityPort.toJson() and FacilityPort.toDict() --- fabrictestbed_extensions/fablib/facility_port.py | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/fabrictestbed_extensions/fablib/facility_port.py b/fabrictestbed_extensions/fablib/facility_port.py index d524f749..856410da 100644 --- a/fabrictestbed_extensions/fablib/facility_port.py +++ b/fabrictestbed_extensions/fablib/facility_port.py @@ -79,6 +79,9 @@ def __str__(self): return tabulate(table) def toJson(self): + """ + Return a JSON representation of the facility port. + """ return json.dumps(self.toDict(), indent=4) def get_pretty_name_dict(self): @@ -87,6 +90,9 @@ def get_pretty_name_dict(self): } def toDict(self, skip=[]): + """ + Return a Python `dict` representation of the facility port. + """ return {"name": str(self.get_name())} def get_template_context(self): From 5133131ffcf8a06a70d10efea75681a7f4ec8d75 Mon Sep 17 00:00:00 2001 From: Sajith Sasidharan Date: Fri, 28 Jun 2024 11:01:29 -0500 Subject: [PATCH 03/17] Add docstring for FacilityPort.get_site() --- fabrictestbed_extensions/fablib/facility_port.py | 3 +++ 1 file changed, 3 insertions(+) diff --git a/fabrictestbed_extensions/fablib/facility_port.py b/fabrictestbed_extensions/fablib/facility_port.py index 856410da..a15707e4 100644 --- a/fabrictestbed_extensions/fablib/facility_port.py +++ b/fabrictestbed_extensions/fablib/facility_port.py @@ -144,6 +144,9 @@ def get_name(self) -> str: return self.get_fim_interface().name def get_site(self) -> str: + """ + Gets the site associated with the facility port. + """ return self.fim_interface.site @staticmethod From dd61ab5b221636524fca8ecbf19f9f84378e8330 Mon Sep 17 00:00:00 2001 From: Sajith Sasidharan Date: Fri, 28 Jun 2024 12:00:21 -0500 Subject: [PATCH 04/17] Add docstring for FacilityPort.new_facility_port() --- fabrictestbed_extensions/fablib/facility_port.py | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/fabrictestbed_extensions/fablib/facility_port.py b/fabrictestbed_extensions/fablib/facility_port.py index a15707e4..7b797d0c 100644 --- a/fabrictestbed_extensions/fablib/facility_port.py +++ b/fabrictestbed_extensions/fablib/facility_port.py @@ -157,6 +157,18 @@ def new_facility_port( vlan: Union[str, list] = None, bandwidth: int = 10, ): + """ + Create a new facility port. + + You might want to :py:meth:`Slice.add_facility_port()`, in + most cases. + + :param Slice: Slice associated with the facility port. + :param name: name of the facility port. + :param site: site associated with the facility port. + :param vlan: VLAN. + :param bandwidth: bandwidth to be used, in Gbps. + """ if isinstance(vlan, list): interfaces = [] index = 1 From 7270a71e691f6c78c1889008dd4b018c5060f88a Mon Sep 17 00:00:00 2001 From: Sajith Sasidharan Date: Fri, 28 Jun 2024 13:13:41 -0500 Subject: [PATCH 05/17] Add docstring for FacilityPort.get_pretty_name_dict() --- fabrictestbed_extensions/fablib/facility_port.py | 3 +++ 1 file changed, 3 insertions(+) diff --git a/fabrictestbed_extensions/fablib/facility_port.py b/fabrictestbed_extensions/fablib/facility_port.py index 7b797d0c..97b2ec9a 100644 --- a/fabrictestbed_extensions/fablib/facility_port.py +++ b/fabrictestbed_extensions/fablib/facility_port.py @@ -85,6 +85,9 @@ def toJson(self): return json.dumps(self.toDict(), indent=4) def get_pretty_name_dict(self): + """ + Return a mapping used when rendering table headers. + """ return { "name": "Name", } From 15d2cf260a291fe8135b8c5e07c729aa01e768c9 Mon Sep 17 00:00:00 2001 From: Sajith Sasidharan Date: Fri, 28 Jun 2024 14:13:29 -0500 Subject: [PATCH 06/17] Add docstring for FacilityPort.show() --- fabrictestbed_extensions/fablib/facility_port.py | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/fabrictestbed_extensions/fablib/facility_port.py b/fabrictestbed_extensions/fablib/facility_port.py index 97b2ec9a..19c93695 100644 --- a/fabrictestbed_extensions/fablib/facility_port.py +++ b/fabrictestbed_extensions/fablib/facility_port.py @@ -50,7 +50,7 @@ class FacilityPort: """ A class for working with FABRIC facility ports. """ - + fim_interface = None slice = None @@ -111,6 +111,9 @@ def render_template(self, input_string): def show( self, fields=None, output=None, quiet=False, colors=False, pretty_names=True ): + """ + Get a human-readable representation of the facility port. + """ data = self.toDict(pretty_names=True) # fields = ["Name", From 88d81f0a7bec41423daac28002d0c61df9889ca7 Mon Sep 17 00:00:00 2001 From: Sajith Sasidharan Date: Fri, 28 Jun 2024 14:16:23 -0500 Subject: [PATCH 07/17] Add docstring for FacilityPort.get_model() --- fabrictestbed_extensions/fablib/facility_port.py | 3 +++ 1 file changed, 3 insertions(+) diff --git a/fabrictestbed_extensions/fablib/facility_port.py b/fabrictestbed_extensions/fablib/facility_port.py index 19c93695..1ffab508 100644 --- a/fabrictestbed_extensions/fablib/facility_port.py +++ b/fabrictestbed_extensions/fablib/facility_port.py @@ -139,6 +139,9 @@ def get_fim_interface(self) -> FimNode: return self.fim_interface def get_model(self) -> str: + """ + Get fablib model name for the facility port. + """ return "Facility_Port" def get_name(self) -> str: From 8b2c6b5bbcdcc67ba3642ce192865cf4200f9362 Mon Sep 17 00:00:00 2001 From: Sajith Sasidharan Date: Sat, 29 Jun 2024 06:29:50 -0500 Subject: [PATCH 08/17] Add docstring for FacilityPort.get_fim_interface() --- fabrictestbed_extensions/fablib/facility_port.py | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/fabrictestbed_extensions/fablib/facility_port.py b/fabrictestbed_extensions/fablib/facility_port.py index 1ffab508..2d085589 100644 --- a/fabrictestbed_extensions/fablib/facility_port.py +++ b/fabrictestbed_extensions/fablib/facility_port.py @@ -136,6 +136,13 @@ def show( return table def get_fim_interface(self) -> FimNode: + """ + .. warning:: + Not recommended for most users. + + Gets the node's FABRIC Information Model (fim) object. This + method is used to access data at a lower level than FABlib. + """ return self.fim_interface def get_model(self) -> str: From 0afe44a015ccabe64927d199cd71403997ec8a03 Mon Sep 17 00:00:00 2001 From: Sajith Sasidharan Date: Sat, 29 Jun 2024 06:39:34 -0500 Subject: [PATCH 09/17] Do not index the class itself when generating docs --- docs/source/facility_port.rst | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/source/facility_port.rst b/docs/source/facility_port.rst index 2dafabce..032bfcc2 100644 --- a/docs/source/facility_port.rst +++ b/docs/source/facility_port.rst @@ -6,4 +6,5 @@ facility_port .. autoclass:: fabrictestbed_extensions.fablib.facility_port.FacilityPort :members: + :no-index: :special-members: __str__ From 027bdd6a8d0ffba7fb4ec4dce04054410581f687 Mon Sep 17 00:00:00 2001 From: Sajith Sasidharan Date: Sat, 29 Jun 2024 07:32:46 -0500 Subject: [PATCH 10/17] Add a TODO for FacilityPort.render_template() --- fabrictestbed_extensions/fablib/facility_port.py | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/fabrictestbed_extensions/fablib/facility_port.py b/fabrictestbed_extensions/fablib/facility_port.py index 2d085589..c5e8cdcf 100644 --- a/fabrictestbed_extensions/fablib/facility_port.py +++ b/fabrictestbed_extensions/fablib/facility_port.py @@ -102,6 +102,14 @@ def get_template_context(self): return self.get_slice().get_template_context(self) def render_template(self, input_string): + """ + TODO: what is render_template() actually for? What is the + input_string parameter? + + The only usage of render_template() I could find is in + fabric_examples/fablib_api/post_boot_task_templates/post_boot_task_templates.ipynb, + but it is not clear to me what it does. + """ environment = jinja2.Environment() template = environment.from_string(input_string) output_string = template.render(self.get_template_context()) From a6f1bb03aad84aaa86ffdf5740a5cf0f11daa573 Mon Sep 17 00:00:00 2001 From: Sajith Sasidharan Date: Sat, 29 Jun 2024 07:40:31 -0500 Subject: [PATCH 11/17] Add a TODO for FacilityPort.get_template_context() --- fabrictestbed_extensions/fablib/facility_port.py | 3 +++ 1 file changed, 3 insertions(+) diff --git a/fabrictestbed_extensions/fablib/facility_port.py b/fabrictestbed_extensions/fablib/facility_port.py index c5e8cdcf..33e2b482 100644 --- a/fabrictestbed_extensions/fablib/facility_port.py +++ b/fabrictestbed_extensions/fablib/facility_port.py @@ -99,6 +99,9 @@ def toDict(self, skip=[]): return {"name": str(self.get_name())} def get_template_context(self): + """ + TODO: when/why to use this method? + """ return self.get_slice().get_template_context(self) def render_template(self, input_string): From a349fc2f421e0d970be7fd3b00c56b327c44a9da Mon Sep 17 00:00:00 2001 From: Sajith Sasidharan Date: Sat, 29 Jun 2024 07:42:21 -0500 Subject: [PATCH 12/17] Add changelog entry --- CHANGELOG.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index 486f1ed3..14061d1e 100644 --- a/CHANGELOG.md +++ b/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 facility_port module (Issue [#312](https://github.com/fabric-testbed/fabrictestbed-extensions/issues/312)) + ## [1.6.4] - 2024-03-05 ### Fixed From c6b7302b11d2166854ce6756c8fe3126783f8663 Mon Sep 17 00:00:00 2001 From: Sajith Sasidharan Date: Sat, 29 Jun 2024 07:42:42 -0500 Subject: [PATCH 13/17] Remove unused byte :^) --- fabrictestbed_extensions/fablib/__init__.py | 1 - 1 file changed, 1 deletion(-) diff --git a/fabrictestbed_extensions/fablib/__init__.py b/fabrictestbed_extensions/fablib/__init__.py index 8b137891..e69de29b 100644 --- a/fabrictestbed_extensions/fablib/__init__.py +++ b/fabrictestbed_extensions/fablib/__init__.py @@ -1 +0,0 @@ - From a36fc8ca3e5c4212dfa26e7de461035841791f10 Mon Sep 17 00:00:00 2001 From: Sajith Sasidharan Date: Sat, 29 Jun 2024 07:44:52 -0500 Subject: [PATCH 14/17] Refer to modules, not classes --- docs/source/index.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/source/index.rst b/docs/source/index.rst index dd6c4d85..a51c11b7 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -118,10 +118,10 @@ above. Currently, contents of the configuration file will override values set using environment variables. -FABLib classes +FABLib modules -------------- -Most of FABLib's functionality comes wrapped in these classes: +FABLib functionality is made available in these modules: .. toctree:: :maxdepth: 1 From 5ccb729bf263eee65e3e5c4b38d638f4f1e4cdd9 Mon Sep 17 00:00:00 2001 From: Sajith Sasidharan Date: Sat, 29 Jun 2024 07:50:14 -0500 Subject: [PATCH 15/17] Correct docstring format on FacilityPort.get_name() --- fabrictestbed_extensions/fablib/facility_port.py | 1 + 1 file changed, 1 insertion(+) diff --git a/fabrictestbed_extensions/fablib/facility_port.py b/fabrictestbed_extensions/fablib/facility_port.py index 33e2b482..7171ac28 100644 --- a/fabrictestbed_extensions/fablib/facility_port.py +++ b/fabrictestbed_extensions/fablib/facility_port.py @@ -165,6 +165,7 @@ def get_model(self) -> str: def get_name(self) -> str: """ Gets the name of the FABRIC node. + :return: the name of the node :rtype: String """ From ab8e3aa659affc582325495c3c821eb2a2656b98 Mon Sep 17 00:00:00 2001 From: Sajith Sasidharan Date: Tue, 2 Jul 2024 10:53:32 -0500 Subject: [PATCH 16/17] Omit docstrings on template methods for now Not quite sure how these are used or should be documented. Leaving them out for now. --- fabrictestbed_extensions/fablib/facility_port.py | 11 ----------- 1 file changed, 11 deletions(-) diff --git a/fabrictestbed_extensions/fablib/facility_port.py b/fabrictestbed_extensions/fablib/facility_port.py index 7171ac28..bbed7fe3 100644 --- a/fabrictestbed_extensions/fablib/facility_port.py +++ b/fabrictestbed_extensions/fablib/facility_port.py @@ -99,20 +99,9 @@ def toDict(self, skip=[]): return {"name": str(self.get_name())} def get_template_context(self): - """ - TODO: when/why to use this method? - """ return self.get_slice().get_template_context(self) def render_template(self, input_string): - """ - TODO: what is render_template() actually for? What is the - input_string parameter? - - The only usage of render_template() I could find is in - fabric_examples/fablib_api/post_boot_task_templates/post_boot_task_templates.ipynb, - but it is not clear to me what it does. - """ environment = jinja2.Environment() template = environment.from_string(input_string) output_string = template.render(self.get_template_context()) From a0bf801a34bc8b90c266110427ef5a829fadbf64 Mon Sep 17 00:00:00 2001 From: Sajith Sasidharan Date: Mon, 8 Jul 2024 21:53:16 -0500 Subject: [PATCH 17/17] Delete trailing whitespace --- docs/source/facility_port.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/facility_port.rst b/docs/source/facility_port.rst index 032bfcc2..fe2e58af 100644 --- a/docs/source/facility_port.rst +++ b/docs/source/facility_port.rst @@ -6,5 +6,5 @@ facility_port .. autoclass:: fabrictestbed_extensions.fablib.facility_port.FacilityPort :members: - :no-index: + :no-index: :special-members: __str__