Compare commits

..
4 Commits
Author SHA1 Message Date
christianmanivong 2dea517e89 Merge pull request 'feat(firmware): install the offered firmware through FirmwareUpgradeMixin (NetOrk/netork#2615)' (#126) from feature/openwrt-sysupgrade-2615 into main
driver / types (push) Successful in 53s
driver / standard (push) Successful in 16s
driver / lint (push) Successful in 12s
driver / test (3.12) (push) Successful in 1m5s
driver / test (3.13) (push) Successful in 1m3s
driver / lowest (push) Successful in 39s
driver / build (push) Successful in 26s
driver / security (push) Successful in 54s
driver / publish (push) Successful in 28s
CI / driver (push) Successful in 2m57s
2026-11-17 11:38:29 +00:00
christianmanivong 1a7885d22e refactor(firmware): FirmwareOfferDict lives with its contract
driver / lint (pull_request) Successful in 14s
driver / standard (pull_request) Successful in 16s
driver / types (pull_request) Successful in 50s
driver / test (3.13) (pull_request) Successful in 59s
driver / test (3.12) (pull_request) Successful in 1m6s
driver / lowest (pull_request) Successful in 35s
driver / build (pull_request) Successful in 24s
driver / security (pull_request) Successful in 53s
CI / driver (pull_request) Successful in 2m9s
driver / publish (pull_request) Skipped
models.py is over the file limit and may not grow; the offer's two new
fields moved it past its recorded length. It is still importable from
napalm_device_types.models.
2026-11-17 12:35:34 +01:00
christianmanivong 71588613fb chore(release): 4.41.0
driver / lint (pull_request) Successful in 13s
driver / standard (pull_request) Failing after 15s
driver / types (pull_request) Successful in 53s
driver / test (3.13) (pull_request) Successful in 1m3s
driver / test (3.12) (pull_request) Successful in 1m14s
driver / lowest (pull_request) Successful in 40s
driver / build (pull_request) Successful in 25s
driver / security (pull_request) Successful in 52s
CI / driver (pull_request) Failing after 2m10s
driver / publish (pull_request) Skipped
2026-11-17 12:32:43 +01:00
christianmanivong 93ba335798 feat(firmware): install the offered firmware through FirmwareUpgradeMixin (NetOrk/netork#2615)
start_firmware_upgrade(version) starts an upgrade the device runs by itself and
restarts at the end of; get_update_progress follows it. The offer says whether
the driver can install it now (installable) and names a later release line it
never crosses to (latest_major_version).
2026-11-17 11:02:51 +01:00
8 changed files with 82 additions and 21 deletions

No files matched your search

+12
View File
@@ -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
+2 -2
View File
@@ -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",
+41 -5
View File
@@ -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).
"""
...
+4 -10
View File
@@ -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
+2 -1
View File
@@ -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
+1 -1
View File
@@ -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"
+1 -1
View File
@@ -31,7 +31,7 @@
},
"mypy_relaxed": [],
"python_file_lines": {
"napalm_device_types/models.py": 1442
"napalm_device_types/models.py": 1436
},
"untyped_public": []
}
+19 -1
View File
@@ -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")