Added docstrings to asa_device.py functions (#203)

Author: qduk

.travis.yml

@@ -6,14 +6,16 @@ python:
   - "3.7"
   - "3.8"
 
-
 install:
   # XXX: Migrate this to Poetry fully
-  # Install Tox, which is currently our testrunner and helper
-  - pip install tox
+  - pip install virtualenv
 
 
 script:
-  # Run all our tests
+  # Activate virtualenv, install tox and run all tests.
+  - virtualenv ./venv
+  - source ./venv/bin/activate
+  - python -m pip install -U pip
+  - pip install tox
   - tox
   - tox -e coveralls

pyntc/devices/asa_device.py

@@ -1,5 +1,4 @@
-"""Module for using a Cisco ASA device over SSH.
-"""
+"""Module for using a Cisco ASA device over SSH."""
 
 import os
 import re
@@ -41,6 +40,16 @@ class ASADevice(BaseDevice):
     active_redundancy_states = {None, "active"}
 
     def __init__(self, host: str, username: str, password: str, secret="", port=22, **kwargs):
+        """
+        Pyntc Device constructor for Cisco ASA.
+
+        Args:
+            host (str): The address of the network device.
+            username (str): The username to authenticate to the device.
+            password (str): The password to authenticate to the device.
+            secret (str, optional): The password to escalate privlege on the device. Defaults to "".
+            port (int, optional): Port used to establish connection. Defaults to 22.
+        """
         super().__init__(host, username, password, device_type="cisco_asa_ssh")
 
         self.native: Optional[CiscoAsaSSH] = None
@@ -93,7 +102,7 @@ def _file_copy_instance(
         return fc
 
     def _get_file_system(self):
-        """Determines the default file system or directory for device.
+        """Determine the default file system or directory for device.
 
         Returns:
             str: The name of the default file system or directory for the device.
@@ -301,11 +310,23 @@ def _wait_for_peer_reboot(self, acceptable_states: Iterable[str], timeout: int =
         raise RebootTimeoutError(hostname=f"{self.host}-peer", wait_time=timeout)
 
     def backup_running_config(self, filename):
+        """
+        Backups running config.
+
+        Args:
+            filename (str): Name of backup file.
+        """
         with open(filename, "w") as f:
             f.write(self.running_config)
 
     @property
     def boot_options(self):
+        """
+        Determine boot image.
+
+        Returns:
+            dict: Key: 'sys' Value: Current boot image.
+        """
         show_boot_out = self.show("show boot | i BOOT variable")
         # Improve regex to get only the first boot $var in the sequence!
         boot_path_regex = r"Current BOOT variable = (\S+):\/(\S+)"
@@ -319,19 +340,41 @@ def boot_options(self):
         return dict(sys=boot_image)
 
     def checkpoint(self, checkpoint_file):
+        """
+        Create a checkpoint file of the current config.
+
+        Args:
+            checkpoint_file (str):  Saves a checkpoint file with the name provided to the function.
+        """
         self.save(filename=checkpoint_file)
 
     def close(self):
+        """Disconnect from device."""
         if self._connected:
             self.native.disconnect()
             self._connected = False
 
     def config(self, command):
+        """
+        Send single command to device.
+
+        Args:
+            command (str): command to be sent to device.
+        """
         self._enter_config()
         self._send_command(command)
         self.native.exit_config_mode()
 
     def config_list(self, commands):
+        """
+        Send list of commands to device.
+
+        Args:
+            commands (list): list of commands to be set to device.
+
+        Raises:
+            CommandListError: Message stating which command failed and the response from the device.
+        """
         self._enter_config()
         entered_commands = []
         for command in commands:
@@ -345,7 +388,7 @@ def config_list(self, commands):
     @property
     def connected_interface(self) -> str:
         """
-        The interface that is assigned an IP Address of ``self.ip_address``.
+        Interface that is assigned an IP Address of ``self.ip_address``.
 
         Returns:
             str: The name of the interfaces associated to ``self.ip_address``.
@@ -415,7 +458,7 @@ def enable_scp(self) -> None:
 
     @property
     def facts(self):
-        """Implement this once facts' re-factor is done. """
+        """Implement this once facts re-factor is done."""
         return {}
 
     def file_copy(
@@ -462,6 +505,25 @@ def file_copy(
 
     # TODO: Make this an internal method since exposing file_copy should be sufficient
     def file_copy_remote_exists(self, src, dest=None, file_system=None):
+        """
+        Copy ``src`` file to device.
+
+        Args:
+            src (str): The path to the file to be copied to the device.
+            dest (str, optional): The name to use for storing the file on the device.
+                Defaults to use the name of the ``src`` file..
+            file_system (str, optional): The directory name to store files on the device.
+                Defaults to discover the default directory of the device.
+
+        Returns:
+            bool: True if the file exists on the device and the md5 hashes match. Otherwise, false.
+
+        Example:
+        >>> status = file_copy_remote_exists("path/to/asa-image.bin")
+        >>> print(status)
+        True
+        >>>
+        """
         self.enable()
         if file_system is None:
             file_system = self._get_file_system()
@@ -472,6 +534,18 @@ def file_copy_remote_exists(self, src, dest=None, file_system=None):
         return False
 
     def install_os(self, image_name, **vendor_specifics):
+        """
+        Install OS on device.
+
+        Args:
+            image_name (str): Name of the image to be installed.
+
+        Raises:
+            OSInstallError: Message stating the end device could not boot into the new image.
+
+        Returns:
+            bool: True if new image is installed correctly. False if device is already running image_name.
+        """
         timeout = vendor_specifics.get("timeout", 3600)
         if not self._image_booted(image_name):
             self.set_boot_options(image_name, **vendor_specifics)
@@ -487,7 +561,7 @@ def install_os(self, image_name, **vendor_specifics):
     @property
     def ip_address(self) -> Union[IPv4Address, IPv6Address]:
         """
-        The IP Address used to establish the connection to the device.
+        IP Address used to establish the connection to the device.
 
         Returns:
             IPv4Address/IPv6Address: The IP address used by the paramiko connection.
@@ -515,7 +589,7 @@ def ip_address(self) -> Union[IPv4Address, IPv6Address]:
     @property
     def ipv4_addresses(self) -> Dict[str, List[IPv4Address]]:
         """
-        The IPv4 addresses of the device's interfaces.
+        IPv4 addresses of the device's interfaces.
 
         Returns:
             dict: The ipv4 addresses mapped to their interfaces.
@@ -531,7 +605,7 @@ def ipv4_addresses(self) -> Dict[str, List[IPv4Address]]:
     @property
     def ipv6_addresses(self) -> Dict[str, List[IPv6Address]]:
         """
-        The IPv6 addresses of the device's interfaces.
+        IPv6 addresses of the device's interfaces.
 
         Returns:
             dict: The ipv6 addresses mapped to their interfaces.
@@ -547,7 +621,7 @@ def ipv6_addresses(self) -> Dict[str, List[IPv6Address]]:
     @property
     def ip_protocol(self) -> str:
         """
-        The IP Protocol of the IP Addressed used by the underlying paramiko connection.
+        IP Protocol of the IP Addressed used by the underlying paramiko connection.
 
         Returns:
             str: "ipv4" for IPv4 Addresses and "ipv6" for IPv6 Addresses.
@@ -584,6 +658,7 @@ def is_active(self):
         return self.redundancy_state in self.active_redundancy_states
 
     def open(self):
+        """Attempt to find device prompt. If not found, create Connecthandler object to device."""
         if self._connected:
             try:
                 self.native.find_prompt()
@@ -605,6 +680,12 @@ def open(self):
 
     @property
     def peer_device(self) -> "ASADevice":
+        """
+        Create instance of ASADevice for peer device.
+
+        Returns:
+            :class`~devices.ASADevice`: Cisco ASA device instance.
+        """
         if self._peer_device is None:
             self._peer_device = self.__class__(
                 str(self.peer_ip_address), self.username, self.password, self.secret, self.port, **self.kwargs
@@ -617,7 +698,7 @@ def peer_device(self) -> "ASADevice":
     @property
     def peer_ip_address(self) -> Union[IPv4Address, IPv6Address]:
         """
-        The IP Address associated with ``self.ip_address`` on the peer device.
+        IP Address associated with ``self.ip_address`` on the peer device.
 
         Returns:
             IPv4Address/IPv6Address: The IP address used by the paramiko connection.
@@ -644,7 +725,7 @@ def peer_ip_address(self) -> Union[IPv4Address, IPv6Address]:
     @property
     def peer_ipv4_addresses(self) -> Dict[str, List[IPv4Address]]:
         """
-        The IPv4 addresses of the peer device's interfaces.
+        IPv4 addresses of the peer device's interfaces.
 
         Returns:
             dict: The ipv4 addresses mapped to their interfaces.
@@ -660,7 +741,7 @@ def peer_ipv4_addresses(self) -> Dict[str, List[IPv4Address]]:
     @property
     def peer_ipv6_addresses(self) -> Dict[str, List[IPv6Address]]:
         """
-        The IPv6 addresses of the peer device's interfaces.
+        IPv6 addresses of the peer device's interfaces.
 
         Returns:
             dict: The ipv6 addresses mapped to their interfaces.
@@ -789,7 +870,7 @@ def reboot_standby(self, acceptable_states: Optional[Iterable[str]] = None, time
     @property
     def redundancy_mode(self):
         """
-        The operating redundancy mode of the device.
+        Operating redundancy mode of the device.
 
         Returns:
             str: The redundancy mode the device is operating in.
@@ -852,13 +933,37 @@ def redundancy_state(self):
         return redundancy_state.lower()
 
     def rollback(self, rollback_to):
+        """
+        Rollback the device configuration.
+
+        Args:
+            rollback_to (str): Name of checkpoint file to rollback to
+
+        Raises:
+            NotImplementedError: Function not implemented yet.
+        """
         raise NotImplementedError
 
     @property
     def running_config(self):
+        """
+        Get current running config on device.
+
+        Returns:
+            str: Running configuration on device.
+        """
         return self.show("show running-config")
 
     def save(self, filename="startup-config"):
+        """
+        Save changes to startup config.
+
+        Args:
+            filename (str, optional): Name of startup configuration file. Defaults to "startup-config".
+
+        Returns:
+            bool: True if configuration saved succesfully.
+        """
         command = "copy running-config %s" % filename
         # Changed to send_command_timing to not require a direct prompt return.
         self.native.send_command_timing(command)
@@ -871,6 +976,16 @@ def save(self, filename="startup-config"):
         return True
 
     def set_boot_options(self, image_name, **vendor_specifics):
+        """
+        Set new image as boot option on device.
+
+        Args:
+            image_name (str): AName of image.
+
+        Raises:
+            NTCFileNotFoundError: File not found on device.
+            CommandError: Unable to issue command on device.
+        """
         current_boot = self.show("show running-config | inc ^boot system ")
         file_system = vendor_specifics.get("file_system")
         if file_system is None:
@@ -898,10 +1013,32 @@ def set_boot_options(self, image_name, **vendor_specifics):
             )
 
     def show(self, command, expect_string=None):
+        """
+        Send command to device.
+
+        Args:
+            command (str): Command to be ran on device.
+            expect_string (str, optional): Expected response from running command on device. Defaults to None.
+
+        Returns:
+            str: Output from running command on device.
+        """
         self.enable()
         return self._send_command(command, expect_string=expect_string)
 
     def show_list(self, commands):
+        """
+        Send list of commands to device.
+
+        Args:
+            commands (list): Commands to be sent to device.
+
+        Raises:
+            CommandListError: Failure running command on device.
+
+        Returns:
+            list: Output from each command sent.
+        """
         self.enable()
 
         responses = []
@@ -917,8 +1054,15 @@ def show_list(self, commands):
 
     @property
     def startup_config(self):
+        """
+        Show startup config.
+
+        :return: Output of command 'show startup-config'.
+        """
         return self.show("show startup-config")
 
 
 class RebootSignal(NTCError):
+    """Not implemented."""
+
     pass

tox.ini

@@ -8,6 +8,7 @@
 envlist = py{36,37,38},black,flake8,bandit
 skip_missing_interpreters=true
 isolated_build = True
+download=true
 
 [testenv]
 passenv = TRAVIS TRAVIS_*