Merge pull request #378 from networktocode/release-v2.4.0

Release v2.4.0

Author: jeffkala

.gitignore

@@ -309,3 +309,6 @@ public
 /compose.yaml
 /dump.sql
 /pyntc/static/pyntc/docs
+
+# Exception for pynxos/lib
+!/pyntc/devices/pynxos/lib/

docs/admin/release_notes/version_2.4.md

@@ -0,0 +1,26 @@
+
+# v2.4 Release Notes
+
+This document describes all new features and changes in the release. The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/) and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## Release Overview
+
+- Add ability to check for sufficient free space before copying files to devices, with support for EOS, IOS, ASA, and JunOS platforms.
+- Added reboot flag to Device.install_os for supported platforms.
+
+## [v2.4.0 (2026-04-29)](https://github.com/networktocode/pyntc/releases/tag/v2.4.0)
+
+### Added
+
+- [#370](https://github.com/networktocode/pyntc/issues/370) - Added a pre-transfer free-space check to EOS ``file_copy`` and ``remote_file_copy`` that raises ``NotEnoughFreeSpaceError`` when the target filesystem lacks room for the image.
+- [#370](https://github.com/networktocode/pyntc/issues/370) - Added ``file_size_unit`` (``bytes``, ``megabytes``, or ``gigabytes``; default ``bytes``) and a computed ``file_size_bytes`` to ``FileCopyModel`` so ``remote_file_copy`` can verify free space against a caller-supplied size; when ``file_size`` is omitted the pre-transfer check is skipped.
+- [#371](https://github.com/networktocode/pyntc/issues/371) - Added free space validation for file copy operations on IOS devices.
+- [#372](https://github.com/networktocode/pyntc/issues/372) - Added a pre-transfer free-space check to Cisco ASA ``file_copy`` and ``remote_file_copy`` that raises ``NotEnoughFreeSpaceError`` when the target filesystem lacks room for the image.
+- [#373](https://github.com/networktocode/pyntc/issues/373) - Added a pre-transfer free-space check to Juniper JunOS ``file_copy`` and ``remote_file_copy`` that raises ``NotEnoughFreeSpaceError`` when the target filesystem lacks room for the image.
+- [#375](https://github.com/networktocode/pyntc/issues/375) - Added free space validation for file copy operations on NXOS devices.
+- [#376](https://github.com/networktocode/pyntc/issues/376) - Added reboot flag to Device.install_os for supported platforms.
+- [#376](https://github.com/networktocode/pyntc/issues/376) - Vendored pynxos library and added reboot flag to Device.set_boot_options.
+
+### Changed
+
+- [#356](https://github.com/networktocode/pyntc/issues/356) - Bump dependencies

docs/generate_code_reference_pages.py

@@ -4,7 +4,13 @@
 
 import mkdocs_gen_files
 
+EXCLUDE_PATHS = {
+    "pyntc/devices/pynxos",  # Exclude vendored package pynxos
+}
+
 for file_path in Path("pyntc").rglob("*.py"):
+    if any(str(file_path).startswith(excluded) for excluded in EXCLUDE_PATHS):
+        continue
     module_path = file_path.with_suffix("")
     doc_path = file_path.with_suffix(".md")
     full_doc_path = Path("code-reference", doc_path)

docs/user/lib_getting_started.md

@@ -264,7 +264,12 @@ from pyntc.utils.models import FileCopyModel
 ...     checksum='abc123def456',
 ...     hashing_algorithm='md5',
 ...     file_name='newconfig.cfg',
-        vrf='Mgmt-vrf'
+...     # file_size is optional. When supplied, remote_file_copy verifies
+...     # the target device has room before starting the transfer. When
+...     # omitted, the pre-transfer space check is skipped.
+...     file_size=512,
+...     file_size_unit='megabytes',
+...     vrf='Mgmt-vrf',
 ... )
 >>> for device in devices:
 ...    device.remote_file_copy(source_file)

mkdocs.yml

@@ -132,6 +132,7 @@ nav:
       - Uninstall: "admin/uninstall.md"
       - Release Notes:
           - "admin/release_notes/index.md"
+          - v2.4: "admin/release_notes/version_2.4.md"
           - v2.3: "admin/release_notes/version_2.3.md"
           - v2.2: "admin/release_notes/version_2.2.md"
           - v2.1: "admin/release_notes/version_2.1.md"

poetry.lock

@@ -971,12 +971,15 @@ def hostname(self):
         hostname_string = hostname.group(1)
         return hostname_string
 
-    def install_os(self, image_name, controller="both", save_config=True, disable_wlans=None, **vendor_specifics):
+    def install_os(
+        self, image_name, reboot=True, controller="both", save_config=True, disable_wlans=None, **vendor_specifics
+    ):
         """
         Install an operating system on the controller.
 
         Args:
             image_name (str): The version to install on the device.
+            reboot (bool): Whether to reboot the device after setting the boot options. Defaults to true.
             controller (str): The controller(s) to reboot for install (only applies to HA device).
             save_config (bool): Whether the config should be saved to the device before reboot.
             disable_wlans (str|list): Which WLANs to disable/enable before/after upgrade. Default is None.
@@ -1014,6 +1017,9 @@ def install_os(self, image_name, controller="both", save_config=True, disable_wl
         if not self._image_booted(image_name):
             peer_redundancy = self.peer_redundancy_state
             self.set_boot_options(image_name, **vendor_specifics)
+            if not reboot:
+                log.info("Host %s: OS image %s boot options set. Reboot the device to apply", self.host, image_name)
+                return True
             if disable_wlans is not None:
                 self.disable_wlans(disable_wlans)
             self.reboot(controller=controller, save_config=save_config)

pyntc/devices/aireos_device.py

@@ -138,6 +138,39 @@ def _get_file_system(self):
         log.debug("Host %s: File system %s.", self.host, file_system)
         return file_system
 
+    def _get_free_space(self, file_system=None):  # pylint: disable=unused-argument
+        """Return free bytes on ``file_system`` as reported by ASA's ``dir`` output.
+
+        ASA exposes a single flash filesystem in practice and ``dir`` always prints
+        a ``<total> bytes total (<free> bytes free...)`` trailer as the last line.
+        Real platforms append an ``/<pct>% free`` suffix inside the parentheses
+        (e.g., ``(3580170240 bytes free/86% free)``); older releases and some
+        emulators omit it. The regex matches both shapes. The ``file_system``
+        argument is accepted for API parity with other drivers but is otherwise
+        unused.
+
+        Args:
+            file_system (str, optional): Ignored; retained for BaseDevice API parity.
+
+        Returns:
+            int: Free bytes available on the target filesystem.
+
+        Raises:
+            CommandError: When the ``dir`` output does not contain a parseable
+                ``N bytes free`` trailer.
+        """
+        raw_data = self.show("dir")
+        # Examples seen in the wild:
+        #   16777216 bytes total (1592488 bytes free)
+        #   4118732800 bytes total (3580170240 bytes free/86% free)
+        match = re.search(r"\((\d+)\s+bytes\s+free", raw_data)
+        if match is None:
+            log.error("Host %s: could not parse free space from 'dir' output.", self.host)
+            raise CommandError(command="dir", message="Unable to parse free space from dir output.")
+        free_bytes = int(match.group(1))
+        log.debug("Host %s: %s bytes free on flash.", self.host, free_bytes)
+        return free_bytes
+
     def _get_ipv4_addresses(self, host: str) -> Dict[str, List[IPv4Address]]:
         """
         Get IPv4 Addresses for ``host``.
@@ -555,6 +588,8 @@ def file_copy(
 
         Raises:
             FileTransferError: When the ``src`` file is unable to transfer the file to any device.
+            NotEnoughFreeSpaceError: When ``file_system`` has fewer free bytes than
+                ``src`` requires.
 
         Example:
             >>> dev = ASADevice(**connection_args)
@@ -566,6 +601,8 @@ def file_copy(
         if file_system is None:
             file_system = self._get_file_system()
 
+        self._check_free_space(os.path.getsize(src), file_system=file_system)
+
         # netmiko's enable_scp
         self.enable_scp()
         self._file_copy(src, dest, file_system)
@@ -648,12 +685,13 @@ def get_remote_checksum(self, filename, hashing_algorithm="md5", **kwargs: Any):
         log.error("Host %s: Unable to parse checksum for %s from output: %s", self.host, filename, result)
         raise CommandError(cmd, f"Unable to parse checksum for {filename}")
 
-    def install_os(self, image_name, **vendor_specifics):
+    def install_os(self, image_name, reboot=True, **vendor_specifics):
         """
         Install OS on device.
 
         Args:
             image_name (str): Name of the image to be installed.
+            reboot (bool): Whether to reboot the device after setting the boot options. Defaults to true.
             vendor_specifics (dict): Vendor specific arguments to pass to the install process.
 
         Raises:
@@ -665,6 +703,9 @@ def install_os(self, image_name, **vendor_specifics):
         timeout = vendor_specifics.get("timeout", 3600)
         if not self._image_booted(image_name):
             self.set_boot_options(image_name, **vendor_specifics)
+            if not reboot:
+                log.info("Host %s: OS image %s boot options set. Reboot the device to apply", self.host, image_name)
+                return True
             self.reboot()
             self._wait_for_device_reboot(timeout=timeout)
             if not self._image_booted(image_name):
@@ -1018,6 +1059,10 @@ def remote_file_copy(self, src: FileCopyModel = None, dest=None, **kwargs: Any):
         Raises:
             TypeError: If ``src`` is not a ``FileCopyModel`` instance.
             FileTransferError: If the transfer fails or the file cannot be verified afterwards.
+            NotEnoughFreeSpaceError: If ``src.file_size_bytes`` is set and
+                ``file_system`` has fewer free bytes than ``src.file_size_bytes``.
+                When ``file_size`` is omitted from ``src``, the pre-transfer space
+                check is skipped entirely.
         """
         if not isinstance(src, FileCopyModel):
             raise TypeError("src must be an instance of FileCopyModel")
@@ -1028,6 +1073,7 @@ def remote_file_copy(self, src: FileCopyModel = None, dest=None, **kwargs: Any):
             dest = src.file_name
 
         if not self.verify_file(src.checksum, dest, hashing_algorithm=src.hashing_algorithm, file_system=file_system):
+            self._pre_transfer_space_check(src, file_system=file_system)
             current_prompt = self.native.find_prompt()
             prompt_answers = {
                 r"Password": src.token or "",

pyntc/devices/asa_device.py

@@ -2,11 +2,14 @@
 
 import hashlib
 import importlib
+import logging
 import warnings
 
-from pyntc.errors import FeatureNotFoundError, NTCError
+from pyntc.errors import FeatureNotFoundError, NotEnoughFreeSpaceError, NTCError
 from pyntc.utils.models import FileCopyModel
 
+log = logging.getLogger(__name__)
+
 
 def fix_docs(cls):
     """Create docstring at runtime.
@@ -52,6 +55,90 @@ def __init__(self, host, username, password, device_type=None, **kwargs):  # noq
         self._model = None
         self._vlans = None
 
+    def _check_free_space(self, required_bytes, file_system=None):
+        """Raise NotEnoughFreeSpaceError when the target filesystem lacks room for a transfer.
+
+        Drivers call this from ``file_copy`` and ``remote_file_copy`` before starting a
+        transfer. The concrete per-platform probe is ``_get_free_space``; this helper
+        centralises the comparison, logging, and error shape so every driver behaves the
+        same way.
+
+        Args:
+            required_bytes (int): Number of bytes the pending transfer needs.
+            file_system (str, optional): Target filesystem passed through to
+                ``_get_free_space``. Drivers that auto-detect a filesystem should resolve
+                it before calling.
+
+        Raises:
+            NotEnoughFreeSpaceError: When the device reports fewer free bytes than
+                ``required_bytes``.
+        """
+        available = self._get_free_space(file_system)
+        log.debug(
+            "Host %s: filesystem %s has %s bytes free; %s bytes required.",
+            self.host,
+            file_system,
+            available,
+            required_bytes,
+        )
+        if available < required_bytes:
+            log.error(
+                "Host %s: insufficient free space on %s (%s free, %s required).",
+                self.host,
+                file_system,
+                available,
+                required_bytes,
+            )
+            raise NotEnoughFreeSpaceError(
+                hostname=self.host,
+                required=required_bytes,
+                available=available,
+                file_system=file_system,
+            )
+
+    def _get_free_space(self, file_system=None):
+        """Return the number of free bytes on ``file_system``.
+
+        Drivers override this to issue a platform-specific command (e.g., ``dir`` on
+        EOS/IOS/NXOS, ``show system storage`` on JUNOS) and parse the result. Drivers
+        whose platform exposes only one practical filesystem (e.g., EOS) may safely
+        ignore ``file_system``.
+
+        Args:
+            file_system (str, optional): The target filesystem to inspect. Drivers
+                that support multiple filesystems should treat ``None`` as "auto-detect
+                the default filesystem".
+
+        Returns:
+            int: Free bytes available on ``file_system``.
+
+        Raises:
+            NotImplementedError: When a driver has not yet implemented the probe.
+        """
+        raise NotImplementedError(f"{self.__class__.__name__} does not implement _get_free_space")
+
+    def _pre_transfer_space_check(self, src, file_system=None):
+        """Run the free-space check if ``src.file_size_bytes`` is populated.
+
+        Drivers call this from ``remote_file_copy`` so the check is skipped
+        (fail-open) when the caller omits ``FileCopyModel.file_size``; when set,
+        ``_check_free_space`` raises ``NotEnoughFreeSpaceError`` if the device
+        lacks room. Lives on ``BaseDevice`` so every driver inherits the same
+        shape without duplicating the if/else.
+
+        Args:
+            src (FileCopyModel): The source specification for the pending transfer.
+            file_system (str, optional): Target filesystem; passed through to
+                ``_check_free_space`` (and from there to ``_get_free_space``).
+        """
+        if src.file_size_bytes is not None:
+            self._check_free_space(src.file_size_bytes, file_system=file_system)
+        else:
+            log.debug(
+                "Host %s: no file_size on FileCopyModel; skipping pre-transfer space check.",
+                self.host,
+            )
+
     def _image_booted(self, image_name, **vendor_specifics):
         """Determine if a particular image is serving as the active OS.
 
@@ -363,11 +450,12 @@ def verify_file(self, checksum, filename, hashing_algorithm="md5", **kwargs):
         """
         raise NotImplementedError
 
-    def install_os(self, image_name, **vendor_specifics):
+    def install_os(self, image_name, reboot=True, **vendor_specifics):
         """Install the OS from specified image_name.
 
         Args:
             image_name (str): The name of the image on the device to install.
+            reboot (bool): Whether to reboot the device after setting the boot options. Defaults to true.
 
         Keyword Args:
             kickstart (str): Option for ``NXOSDevice`` for devices that require a kickstart image.