Compare commits
| Author | SHA1 | Date | |
|---|---|---|---|
|
|
278a707157 | ||
|
|
56e5e82a59 |
No files matched your search
@@ -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
|
||||
|
||||
@@ -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",
|
||||
|
||||
@@ -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
@@ -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"
|
||||
|
||||
@@ -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
|
||||
Reference in new issue
Block a user