Add file_pull option to Cisco IOS devices (#345)

* Add file_pull option to Cisco IOS devices

* Add docs, ruff and change fragment.

* Pylint fixes

Ignore the import position as Ruff is handling that.

* Address feedback

* Fix pylint commands

The find command was too greedy and capturing files ignore by the pylint config in pyproject.toml.  This allows pylint to use the pyproject.tom.

* Rewrite to make the logic for checking files part of the Device.

Not all Devices use netmiko, these changes allow other devices to also implement fix exist validation.

* Update ios_device.py

* Ruff

* Apply suggestions from code review

Co-authored-by: Gary Snider <75227981+gsnider2195@users.noreply.github.com>

* Apply suggestions from code review.

---------

Co-authored-by: Gary Snider <75227981+gsnider2195@users.noreply.github.com>

Author: smk4664

changes/345.added

@@ -0,0 +1 @@
+Added the ability to download files from within a Cisco IOS device.

docs/user/lib_getting_started.md

@@ -250,6 +250,35 @@ interface GigabitEthernet1
 >>>
 ```
 
+#### Remote File Copy (Download to Device)
+
+Some devices support copying files directly from a URL to the device. This is useful for larger files like OS images.  To do this, you need to use the `FileCopyModel` data model to specify the source file information and then pass that to the `remote_file_copy` method. Currently only supported on Cisco IOS devices. Tested with ftp, http, https, sftp, and tftp urls.
+
+- `remote_file_copy` method
+
+```python
+from pyntc.utils.models import FileCopyModel
+
+>>> source_file = FileCopyModel(
+...     download_url='sftp://example.com/newconfig.cfg',
+...     checksum='abc123def456',
+...     hashing_algorithm='md5',
+...     file_name='newconfig.cfg',
+        vrf='Mgmt-vrf'
+... )
+>>> for device in devices:
+...    device.remote_file_copy(source_file)
+...
+>>>
+```
+
+Before using this feature you may need to configure a client on the device. For instance, on a Cisco IOS device you would need to set the source interface for the ip http client when using http or https urls.  You can do this with the `config` method:
+
+```python
+>>> csr1.config('ip http client source-interface GigabitEthernet1')
+>>>
+```
+
 ### Save Configs
 
 - `save` method

pyntc/devices/base_device.py

@@ -1,9 +1,11 @@
 """The module contains the base class that all device classes must inherit from."""
 
+import hashlib
 import importlib
 import warnings
 
 from pyntc.errors import FeatureNotFoundError, NTCError
+from pyntc.utils.models import FileCopyModel
 
 
 def fix_docs(cls):
@@ -221,7 +223,7 @@ def file_copy(self, src, dest=None, **kwargs):
 
         Keyword Args:
             file_system (str): Supported only for IOS and NXOS. The file system for the
-                remote fle. If no file_system is provided, then the ``get_file_system``
+                remote file. If no file_system is provided, then the ``get_file_system``
                 method is used to determine the correct file system to use.
         """
         raise NotImplementedError
@@ -241,13 +243,126 @@ def file_copy_remote_exists(self, src, dest=None, **kwargs):
 
         Keyword Args:
             file_system (str): Supported only for IOS and NXOS. The file system for the
-                remote fle. If no file_system is provided, then the ``get_file_system``
+                remote file. If no file_system is provided, then the ``get_file_system``
                 method is used to determine the correct file system to use.
 
         Returns:
             (bool): True if the remote file exists, False if it doesn't.
         """
 
+    def check_file_exists(self, filename, **kwargs):
+        """Check if a remote file exists by filename.
+
+        Args:
+            filename (str): The name of the file to check for on the remote device.
+            kwargs (dict): Additional keyword arguments that may be used by subclasses.
+
+        Keyword Args:
+            file_system (str): Supported only for IOS and NXOS. The file system for the
+                remote file. If no file_system is provided, then the ``get_file_system``
+                method is used to determine the correct file system to use.
+
+        Returns:
+            (bool): True if the remote file exists, False if it doesn't.
+        """
+        raise NotImplementedError
+
+    def get_remote_checksum(self, filename, hashing_algorithm="md5", **kwargs):
+        """Get the checksum of a remote file.
+
+        Args:
+            filename (str): The name of the file to check for on the remote device.
+            hashing_algorithm (str): The hashing algorithm to use (default: "md5").
+            kwargs (dict): Additional keyword arguments that may be used by subclasses.
+
+        Keyword Args:
+            file_system (str): Supported only for IOS and NXOS. The file system for the
+                remote file. If no file_system is provided, then the ``get_file_system``
+                method is used to determine the correct file system to use.
+
+        Returns:
+            (str): The checksum of the remote file.
+        """
+        raise NotImplementedError
+
+    @staticmethod
+    def get_local_checksum(filepath, hashing_algorithm="md5", add_newline=False):
+        """Get the checksum of a local file using a specified algorithm.
+
+        Args:
+            filepath (str): The path to the local file.
+            hashing_algorithm (str): The hashing algorithm to use (e.g., "md5", "sha256").
+            add_newline (bool): Whether to append a newline before final hashing (Some devices may require this).
+
+        Returns:
+            (str): The hex digest of the file.
+        """
+        # Initialize the hash object dynamically
+        file_hash = hashlib.new(hashing_algorithm.lower())
+
+        with open(filepath, "rb") as f:
+            # Read in chunks to handle large firmware files without RAM spikes
+            for chunk in iter(lambda: f.read(4096), b""):
+                file_hash.update(chunk)
+
+        if add_newline:
+            file_hash.update(b"\n")
+
+        return file_hash.hexdigest()
+
+    def compare_file_checksum(self, checksum, filename, hashing_algorithm="md5", **kwargs):
+        """Compare the checksum of a local file with a remote file.
+
+        Args:
+            checksum (str): The checksum of the file.
+            filename (str): The name of the file to check for on the remote device.
+            hashing_algorithm (str): The hashing algorithm to use (default: "md5").
+            kwargs (dict): Additional keyword arguments that may be used by subclasses.
+
+        Keyword Args:
+            file_system (str): Supported only for IOS and NXOS. The file system for the
+                remote file. If no file_system is provided, then the ``get_file_system``
+                method is used to determine the correct file system to use.
+
+        Returns:
+            (bool): True if the checksums match, False otherwise.
+        """
+        return checksum == self.get_remote_checksum(filename, hashing_algorithm, **kwargs)
+
+    def remote_file_copy(self, src: FileCopyModel = None, dest=None, **kwargs):
+        """Copy a file to a remote device.
+
+        Args:
+            src (FileCopyModel): The source file model.
+            dest (str): The destination file path on the remote device.
+            kwargs (dict): Additional keyword arguments that may be used by subclasses.
+
+        Keyword Args:
+            file_system (str): Supported only for IOS and NXOS. The file system for the
+                remote file. If no file_system is provided, then the ``get_file_system``
+                method is used to determine the correct file system to use.
+        """
+        raise NotImplementedError
+
+    def verify_file(self, checksum, filename, hashing_algorithm="md5", **kwargs):
+        """Verify a file on the remote device by confirming the file exists and validate the checksum.
+
+        Args:
+            checksum (str): The checksum of the file.
+            filename (str): The name of the file to check for on the remote device.
+            hashing_algorithm (str): The hashing algorithm to use (default: "md5").
+            kwargs (dict): Additional keyword arguments that may be used by subclasses.
+
+        Keyword Args:
+            file_system (str): Supported only for IOS and NXOS. The file system for the
+                remote file. If no file_system is provided, then the ``get_file_system``
+                method is used to determine the correct file system to use.
+
+        Returns:
+            (bool): True if the file is verified successfully, False otherwise.
+        """
+        raise NotImplementedError
+
     def install_os(self, image_name, **vendor_specifics):
         """Install the OS from specified image_name.