Compare commits

...
2 Commits
Author SHA1 Message Date
christianmanivong 278a707157 Merge pull request 'feat(running-backups): the backups running on a device right now' (#102) from feature/running-backups-2318 into main
driver / lint (push) Successful in 13s
driver / standard (push) Successful in 14s
driver / types (push) Successful in 59s
driver / test (3.13) (push) Successful in 58s
driver / test (3.12) (push) Successful in 1m13s
driver / lowest (push) Successful in 35s
driver / build (push) Successful in 26s
driver / security (push) Successful in 56s
driver / publish (push) Successful in 26s
CI / driver (push) Successful in 2m36s
2026-11-11 07:22:54 +00:00
christianmanivong 56e5e82a59 feat(running-backups): the backups running on a device right now
driver / lint (pull_request) Successful in 17s
driver / standard (pull_request) Successful in 19s
driver / types (pull_request) Successful in 1m2s
driver / test (3.13) (pull_request) Successful in 1m5s
driver / test (3.12) (pull_request) Successful in 1m15s
driver / lowest (pull_request) Successful in 37s
driver / build (pull_request) Successful in 29s
driver / security (pull_request) Successful in 59s
CI / driver (pull_request) Successful in 2m24s
driver / publish (pull_request) Skipped
A restart aborts every backup that runs on the device it restarts, and a
guest's restart breaks the backup its hypervisor is taking of it. netOrk
asks right before it restarts a host after patching (NetOrk/netork#2318),
so the reading belongs in the contract first: RunningBackupsMixin declares
get_running_backups(), opt-in like VmStopRequestMixin, so hasattr tells a
caller whether the driver can tell at all.

Release 4.34.0: the drivers that implement it need it on PyPI.
2026-11-10 23:39:17 +01:00
5 changed files with 142 additions and 1 deletions

No files matched your search

+10
View File
@@ -7,6 +7,16 @@ recorded here; their history is the git log.
## [Unreleased]
## [4.34.0] - 2026-11-10
### Added
- `RunningBackupsMixin.get_running_backups()`: the backups running on a device right now --
a hypervisor's backup of its guests (with the guests it is taking now), a backup server's
backup, sync, verify, garbage collection, prune or tape run, a host's own file-level backup.
Declared only; a driver mixes it in when it can tell, and a driver without it cannot tell.
`RunningBackupDict`, `RunningBackupKind` and `RUNNING_BACKUP_KINDS` are public. An
application asks right before it restarts a device (NetOrk/netork#2318).
## [4.33.0] - 2026-11-07
### Added
+11
View File
@@ -56,6 +56,7 @@ instead of being restated on every role that happens to need it:
* :class:`~napalm_device_types.nat_vpn.NatVpnMixin`
* :class:`~napalm_device_types.packages.PackageManagementMixin`
* :class:`~napalm_device_types.ping_sweep.PingSweepMixin`
* :class:`~napalm_device_types.running_backups.RunningBackupsMixin`
* :class:`~napalm_device_types.service_clusters.ServiceClustersMixin`
* :class:`~napalm_device_types.service_packages.ServicePackagesMixin`
* :class:`~napalm_device_types.ssh_server_auth.SshServerAuthMixin`
@@ -224,6 +225,12 @@ from napalm_device_types.ping_sweep import PingSweepMixin, driver_supports_ping
from napalm_device_types.provisioning import VMProvisionIncomplete
from napalm_device_types.residential_gateway import ResidentialGatewayDriver
from napalm_device_types.roles import primary_role_of, role_keys_of, roles_of
from napalm_device_types.running_backups import (
RUNNING_BACKUP_KINDS,
RunningBackupDict,
RunningBackupKind,
RunningBackupsMixin,
)
from napalm_device_types.scheduled_jobs import (
ScheduledJobChanged,
ScheduledJobDict,
@@ -468,6 +475,10 @@ __all__ = [
"VIRTUAL_IPS_COMMAND",
"VirtualIpsMixin",
"VmStopRequestMixin",
"RUNNING_BACKUP_KINDS",
"RunningBackupDict",
"RunningBackupKind",
"RunningBackupsMixin",
"VMProvisionIncomplete",
"SERVICE_CLUSTERS_COMMAND",
"ServiceClustersMixin",
+69
View File
@@ -0,0 +1,69 @@
"""The backups running on a device right now.
A restart aborts every backup that runs on the device it restarts: a
hypervisor's backup of its guests, a backup server's backup, sync, verify or
garbage collection, a host's own file-level backup (restic, borg and the like).
A guest's restart breaks the backup its hypervisor is taking of it. So an
application that restarts a device asks first, right before the restart.
Declared under ``if TYPE_CHECKING``: a driver mixes this in when it can tell;
``hasattr`` tells a caller whether it did. No role base carries it, and a driver
without it cannot tell -- which is not the same as "nothing runs".
"""
from __future__ import annotations
from typing import TYPE_CHECKING, Literal, TypedDict, get_args
#: What a running backup does: the backup itself, or one of a backup server's
#: jobs (``napalm_device_types.backups.BackupJobKind``).
RunningBackupKind = Literal["backup", "sync", "verify", "gc", "prune", "tape"]
RUNNING_BACKUP_KINDS: tuple[str, ...] = get_args(RunningBackupKind)
class RunningBackupDict(TypedDict):
"""One backup running on the device (``get_running_backups``)."""
kind: RunningBackupKind
job: str | None # the job it runs for, as the platform names it; None: started by hand
task: str | None # this run's id on the platform: a task id, a unit, a process id
guests: list[str] # the guests (get_vms' ids) it is backing up now; [] for the host's own
since: int | None # unix seconds it started; None when the platform does not say
class RunningBackupsMixin:
if TYPE_CHECKING:
def get_running_backups(self) -> list[RunningBackupDict]:
"""
Returns the backups running on the device now; ``[]`` when none is.
Every entry runs on this device: restarting the device aborts it.
A hypervisor names in ``guests`` the guests a backup is taking right
now -- a guest that is locked for its backup counts, with or without
a task the platform still shows -- so the application can tell a
guest's own restart not to break it.
Example::
[
{
"kind": "backup",
"job": "backup-3f2a9c1e-77d1",
"task": "UPID:pve1:0001F2A3:00C4B1D2:6731A0C0:vzdump::root@pam:",
"guests": ["101"],
"since": 1793660400,
},
{
"kind": "gc",
"job": "store1",
"task": "UPID:localhost:000004D2:...:garbage_collection:store1:root@pam:",
"guests": [],
"since": 1793664000,
},
]
:raises Exception: when the device could not be read; never an
empty list for a failed read.
"""
...
+1 -1
View File
@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
[project]
name = "napalm-device-types"
version = "4.33.0"
version = "4.34.0"
description = "Abstract device-type base classes for NAPALM drivers"
readme = "README.md"
requires-python = ">=3.12"
+51
View File
@@ -0,0 +1,51 @@
"""get_running_backups: the backups running on a device right now.
An application that restarts a device asks first, right before the restart: a
restart aborts a backup that runs on the device -- a hypervisor's vzdump, a
backup server's backup, sync, verify or garbage collection, a host's own restic
or borg run -- and a guest's restart breaks the backup its hypervisor is taking
of it (NetOrk/netork#2318). A driver mixes it in when it can tell; no role
demands it, and a driver without it cannot tell.
"""
from __future__ import annotations
import inspect
from typing import get_type_hints
from napalm_device_types import (
RUNNING_BACKUP_KINDS,
BackupServerDriver,
DeviceTypeDriver,
HypervisorDriver,
OSDriver,
RunningBackupDict,
RunningBackupsMixin,
)
def test_no_role_demands_it():
for role in (BackupServerDriver, HypervisorDriver, OSDriver, DeviceTypeDriver):
assert not issubclass(role, RunningBackupsMixin)
def test_declared_not_implemented():
"""hasattr is the caller's probe: only a driver that can tell answers True."""
assert not hasattr(RunningBackupsMixin, "get_running_backups")
def test_declaration_documents_the_contract():
source = inspect.getsource(RunningBackupsMixin)
assert "def get_running_backups(self) -> list[RunningBackupDict]" in source
assert "empty list for a failed read" in source
def test_the_kinds_cover_a_backup_servers_jobs_and_the_backup_itself():
assert set(RUNNING_BACKUP_KINDS) == {"backup", "sync", "verify", "gc", "prune", "tape"}
def test_the_shape():
hints = get_type_hints(RunningBackupDict)
assert set(hints) == {"kind", "job", "task", "guests", "since"}
assert hints["guests"] == list[str]
assert hints["since"] == int | None