diff --git a/CHANGELOG.md b/CHANGELOG.md index c50390d..6ce0d86 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -7,6 +7,18 @@ recorded here; their history is the git log. ## [Unreleased] +## [4.41.0] - 2026-11-17 + +### Added +- `FirmwareUpgradeMixin.start_firmware_upgrade(version)`: start installing the firmware a + driver offers; the device runs it by itself and restarts at its end, and + `UpdateMixin.get_update_progress` follows it until then (NetOrk/netork#2615, OpenWrt's + sysupgrade through owut). +- `FirmwareOfferDict.installable`: whether the driver can install `latest_version` itself + now, False while the device lacks what that takes; and + `FirmwareOfferDict.latest_major_version`, the newest of a later release line, shown and + never crossed to by the driver. + ## [4.40.0] - 2026-11-17 ### Added diff --git a/napalm_device_types/__init__.py b/napalm_device_types/__init__.py index 5ade277..573b4ba 100644 --- a/napalm_device_types/__init__.py +++ b/napalm_device_types/__init__.py @@ -138,7 +138,7 @@ from napalm_device_types.dhcp import DhcpApplyError, DhcpServerMixin, normalize_ from napalm_device_types.dns_forward import DnsForwardMixin from napalm_device_types.firewall import FirewallDriver from napalm_device_types.firewall_rules import FirewallRuleMixin -from napalm_device_types.firmware import FirmwareOfferMixin +from napalm_device_types.firmware import FirmwareOfferDict, FirmwareOfferMixin, FirmwareUpgradeMixin from napalm_device_types.fixes import ( EnsurePackageMixin, LldpAgentMixin, @@ -205,7 +205,6 @@ from napalm_device_types.models import ( DnsForwardDict, EventLogEntryDict, FirmwareDict, - FirmwareOfferDict, FixResultDict, FixStepDict, FixStepOutcomeDict, @@ -382,6 +381,7 @@ __all__ = [ "OspfMixin", "UpdateProgressDict", "FirmwareOfferMixin", + "FirmwareUpgradeMixin", "LicenseDict", "LicenseMixin", "EnsurePackageMixin", diff --git a/napalm_device_types/firmware.py b/napalm_device_types/firmware.py index 08b0af1..9540355 100644 --- a/napalm_device_types/firmware.py +++ b/napalm_device_types/firmware.py @@ -1,23 +1,39 @@ -"""The firmware a vendor offers for a device. +"""The firmware a vendor offers for a device, and installing it. A fact for the caller (docs/STRUCTURE.md): a driver may know the newer firmware from the vendor's download catalogue or the device's own update check; whether running an older one is a problem is decided above the driver. Comparing the vendor's version strings is vendor knowledge, so the driver says itself whether the offer is newer. Declared only; a driver that can tell implements it. + +Installing it is a capability of its own (``FirmwareUpgradeMixin``): when and +whether is the caller's call, as with package updates; how is the driver's. """ -from __future__ import annotations +from typing import TYPE_CHECKING, NotRequired, TypedDict -from typing import TYPE_CHECKING -from napalm_device_types.models import FirmwareOfferDict +class FirmwareOfferDict(TypedDict): + """The firmware a device runs and the newest its vendor offers + (``FirmwareOfferMixin.get_firmware_offer``). A fact, not a judgement.""" + + current_version: str + latest_version: str + newer: bool # the offer is newer than what runs, by the vendor's versioning + download_url: NotRequired[str] + # The driver can install latest_version itself (FirmwareUpgradeMixin) now; False + # while the device lacks what that takes (OpenWrt without owut). Left out where + # the driver never installs firmware on this device. + installable: NotRequired[bool] + # The newest of a later release line (OpenWrt 25.12 on a 24.10 device), which + # latest_version does not cross to: shown, never installed by the driver. + latest_major_version: NotRequired[str] class FirmwareOfferMixin: if TYPE_CHECKING: # pragma: no cover - declared for type checkers only - def get_firmware_offer(self) -> FirmwareOfferDict | None: + def get_firmware_offer(self) -> "FirmwareOfferDict | None": """The firmware running and the newest the vendor offers. None when the driver cannot tell for this device (an unknown model, @@ -29,3 +45,23 @@ class FirmwareOfferMixin: "newer": True, "download_url": "https://.../GS308E_1.0.2.12.zip"} """ ... + + +class FirmwareUpgradeMixin: + if TYPE_CHECKING: # pragma: no cover - declared for type checkers only + + def start_firmware_upgrade(self, version: str) -> None: + """Starts installing *version*, an offer's ``latest_version`` that + :meth:`FirmwareOfferMixin.get_firmware_offer` called ``installable``. + + The device runs the upgrade by itself and restarts at its end, which + ends the session; the configuration is kept. Returns once it has + started. ``UpdateMixin.get_update_progress`` follows it until then: + ``"failed"`` when it stopped before the device restarted, which leaves + the running firmware as it was. + + :raises ValueError: *version* is not a version string the driver takes. + :raises RuntimeError: the device cannot start it (what it takes is + missing, an upgrade is already running). + """ + ... diff --git a/napalm_device_types/models.py b/napalm_device_types/models.py index 8355a18..66667ba 100644 --- a/napalm_device_types/models.py +++ b/napalm_device_types/models.py @@ -1172,16 +1172,6 @@ class OspfDict(TypedDict): interfaces: dict[str, OspfInterfaceDict] # by interface name -class FirmwareOfferDict(TypedDict): - """The firmware a device runs and the newest its vendor offers - (``FirmwareOfferMixin.get_firmware_offer``). A fact, not a judgement.""" - - current_version: str - latest_version: str - newer: bool # the offer is newer than what runs, by the vendor's versioning - download_url: NotRequired[str] - - class HypervisorHostDict(TypedDict): """One host of a hypervisor or cluster (``HypervisorDriver.get_hypervisor_hosts``).""" @@ -1440,3 +1430,7 @@ class ManagementProtocolsDict(TypedDict): snmp: ProtocolStateDict kvm: ProtocolStateDict virtual_media: ProtocolStateDict + + +# Importable from here as before 4.41; it lives with its contract now. +from napalm_device_types.firmware import FirmwareOfferDict as FirmwareOfferDict # noqa: E402 diff --git a/napalm_device_types/updates.py b/napalm_device_types/updates.py index 91c25c4..a24b186 100644 --- a/napalm_device_types/updates.py +++ b/napalm_device_types/updates.py @@ -97,7 +97,8 @@ class UpdateMixin: """ Where an update the device runs by itself stands, for a caller that follows it: a firewall's firmware upgrade, which :meth:`apply_updates` - only starts. ``state`` is ``"running"`` until it ends in ``"done"`` + only starts, or one that ``FirmwareUpgradeMixin.start_firmware_upgrade`` + started. ``state`` is ``"running"`` until it ends in ``"done"`` or ``"failed"``; ``log`` is the device's whole log of it. Declared only: a driver whose :meth:`apply_updates` returns when the diff --git a/pyproject.toml b/pyproject.toml index ac73da6..220cce4 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta" [project] name = "napalm-device-types" -version = "4.40.0" +version = "4.41.0" description = "Abstract device-type base classes for NAPALM drivers" readme = "README.md" requires-python = ">=3.12" diff --git a/tests/quality_baseline.json b/tests/quality_baseline.json index 06714cf..73db258 100644 --- a/tests/quality_baseline.json +++ b/tests/quality_baseline.json @@ -31,7 +31,7 @@ }, "mypy_relaxed": [], "python_file_lines": { - "napalm_device_types/models.py": 1442 + "napalm_device_types/models.py": 1436 }, "untyped_public": [] } diff --git a/tests/test_fact_getters.py b/tests/test_fact_getters.py index d9cc556..06f6b9a 100644 --- a/tests/test_fact_getters.py +++ b/tests/test_fact_getters.py @@ -56,8 +56,26 @@ def test_a_firmware_offer_says_what_runs_and_what_is_offered(): from napalm_device_types import FirmwareOfferDict, FirmwareOfferMixin hints = get_type_hints(FirmwareOfferDict) - assert set(hints) == {"current_version", "latest_version", "newer", "download_url"} + assert set(hints) == { + "current_version", + "latest_version", + "newer", + "download_url", + "installable", + "latest_major_version", + } assert FirmwareOfferDict.__required_keys__ == frozenset( {"current_version", "latest_version", "newer"} ) assert not hasattr(FirmwareOfferMixin, "get_firmware_offer") + + +def test_a_firmware_upgrade_is_started_and_followed_like_a_device_run_update(): + """A driver that can install the firmware it offers starts it and the device + runs it by itself, restarting at its end (OpenWrt's sysupgrade, NetOrk/netork#2615); + the caller follows it through ``get_update_progress``. Declared only, so + ``hasattr`` tells a caller whether the driver offers it.""" + from napalm_device_types import FirmwareUpgradeMixin, UpdateMixin + + assert not hasattr(FirmwareUpgradeMixin, "start_firmware_upgrade") + assert not hasattr(UpdateMixin, "get_update_progress")