diff --git a/CHANGELOG.md b/CHANGELOG.md index 937eade4..a895056f 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -17,6 +17,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 - 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)) - Missing docstrings in node module (Issue [#318](https://github.com/fabric-testbed/fabrictestbed-extensions/issues/318)) ## [1.6.4] - 2024-03-05 diff --git a/docs/source/facility_port.rst b/docs/source/facility_port.rst index 2dafabce..fe2e58af 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__ 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 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 @@ - diff --git a/fabrictestbed_extensions/fablib/facility_port.py b/fabrictestbed_extensions/fablib/facility_port.py index 568fbd5b..bbed7fe3 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 @@ -75,14 +79,23 @@ 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): + """ + Return a mapping used when rendering table headers. + """ return { "name": "Name", } def toDict(self, skip=[]): + """ + Return a Python `dict` representation of the facility port. + """ return {"name": str(self.get_name())} def get_template_context(self): @@ -98,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", @@ -120,20 +136,34 @@ 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: + """ + Get fablib model name for the facility port. + """ return "Facility_Port" def get_name(self) -> str: """ Gets the name of the FABRIC node. + :return: the name of the node :rtype: String """ 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 @@ -144,6 +174,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