diff --git a/CHANGELOG.md b/CHANGELOG.md index a895056f..abbc4b72 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 interface module (Issue [#313](https://github.com/fabric-testbed/fabrictestbed-extensions/issues/313)) - 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)) diff --git a/fabrictestbed_extensions/fablib/interface.py b/fabrictestbed_extensions/fablib/interface.py index 245ac7c0..aae3950e 100644 --- a/fabrictestbed_extensions/fablib/interface.py +++ b/fabrictestbed_extensions/fablib/interface.py @@ -87,6 +87,9 @@ def __init__( self.node = node def get_fablib_manager(self): + """ + Get a reference to :py:class:`.FablibManager` instance. + """ return self.get_slice().get_fablib_manager() def __str__(self): @@ -129,6 +132,9 @@ def toJson(self): @staticmethod def get_pretty_name_dict(): + """ + Return a mapping used when rendering table headers. + """ return { "name": "Name", "short_name": "Short Name", @@ -203,6 +209,9 @@ def toDict(self, skip=[]): } def get_numa_node(self) -> str: + """ + Get NUMA node assoicated with the interface. + """ if self.get_component() is not None: return self.get_component().get_numa_node() @@ -274,6 +283,9 @@ def show( return table def set_auto_config(self): + """ + Set interface to auto-configure. + """ fim_iface = self.get_fim_interface() fim_iface.flags = Flags(auto_config=True) # fim_iface.labels = Labels.update(fim_iface.labels, ipv4.... ) @@ -287,6 +299,9 @@ def set_auto_config(self): # fim_iface.set_properties(labels=if_labels) def unset_auto_config(self): + """ + Unset auto-configuration flag on the interface. + """ fim_iface = self.get_fim_interface() fim_iface.flags = Flags(auto_config=False) @@ -571,6 +586,9 @@ def get_vlan(self) -> str: return vlan def get_reservation_id(self) -> str or None: + """ + Get reservation ID for the interface. + """ try: # TODO THIS DOESNT WORK. # print(f"{self.get_fim_interface()}") @@ -615,6 +633,9 @@ def get_error_message(self) -> str: return "" def get_short_name(self): + """ + Get short name for the interface. + """ # strip of the extra parts of the name added by fim return self.get_name()[ len( @@ -733,6 +754,9 @@ def get_ip_link(self): logging.warning(f"{e}") def get_ip_addr_show(self, dev=None): + """ + Get the result of running `ip -j addr show` on the interface. + """ try: if not dev: dev = self.get_device_name() @@ -800,31 +824,59 @@ def get_ips(self, family=None): return return_ips def get_fim(self): + """ + .. warning:: + + Not recommended for most users. + + Get FABRIC Information Model (fim) object for the interface. + """ return self.get_fim_interface() def set_user_data(self, user_data: dict): + """ + Set user data on the interface. + + :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 on the interface. + """ try: return json.loads(str(self.get_fim().get_property(pname="user_data"))) except Exception as e: return {} def get_fablib_data(self): + """ + Get value associated with `fablib_data` key of user data. + """ try: return self.get_user_data()["fablib_data"] except: return {} def set_fablib_data(self, fablib_data: dict): + """ + Set value associated with `fablib_data` key of user data. + """ user_data = self.get_user_data() user_data["fablib_data"] = fablib_data self.set_user_data(user_data) def set_network(self, network: NetworkService): + """ + Associate a network with the interface. + + Any existing network will be replaced by the new one. + + :param network: a :py:class:`.NetworkService` object. + """ current_network = self.get_network() if current_network: current_network.remove_interface(self) @@ -834,6 +886,13 @@ def set_network(self, network: NetworkService): return self def set_ip_addr(self, addr: ipaddress = None, mode: str = None): + """ + Set IP address. + + :param addr: address to be set, as `IPv4Address` or an + `IPv6Address`. + :param mode: `"auto"`, `"manual"`, or `"config"`. + """ fablib_data = self.get_fablib_data() if mode: fablib_data[self.MODE] = str(mode) @@ -849,6 +908,9 @@ def set_ip_addr(self, addr: ipaddress = None, mode: str = None): return self def get_ip_addr(self): + """ + Get IP address for the interface. + """ fablib_data = self.get_fablib_data() if self.ADDR in fablib_data: try: @@ -863,6 +925,11 @@ def get_ip_addr(self): return self.get_ip_addr_ssh() def set_mode(self, mode: str = "config"): + """ + Set the interface's configuration mode. + + :param mode: `"auto"`, `"manual"`, or `"config"`. + """ fablib_data = self.get_fablib_data() fablib_data[self.MODE] = mode self.set_fablib_data(fablib_data) @@ -870,6 +937,9 @@ def set_mode(self, mode: str = "config"): return self def get_mode(self): + """ + Get the interface's configuration mode. + """ fablib_data = self.get_fablib_data() if self.MODE not in fablib_data: self.set_mode(self.CONFIG) @@ -878,6 +948,9 @@ def get_mode(self): return fablib_data[self.MODE] def is_configured(self): + """ + Return `True` if the interface is configured. + """ fablib_data = self.get_fablib_data() is_configured = fablib_data.get(self.CONFIGURED) if is_configured is None or not bool(is_configured): @@ -886,6 +959,11 @@ def is_configured(self): return True def config(self): + """ + Configure the interface. + + Called when a `.Node` is configured. + """ network = self.get_network() if not network: logging.info( @@ -927,6 +1005,12 @@ def config(self): pass def add_mirror(self, port_name: str, name: str = "mirror"): + """ + Add port mirroring service to the interface. + + :param port_name: Name of the port being mirrored. + :param name: Name of the mirror. Default is `"mirror"`. + """ self.get_slice().get_fim_topology().add_port_mirror_service( name=name, from_interface_name=port_name, @@ -934,6 +1018,9 @@ def add_mirror(self, port_name: str, name: str = "mirror"): ) def delete(self): + """ + Delete the interface. + """ net = self.get_network() net.remove_interface(self)