Add new typed api

Author: uroni

.gitignore

@@ -5,3 +5,4 @@ urbackup_api/__pycache__/*
 # IDE
 .idea
 tests/__pycache__
+test/__pycache__

README.md

@@ -1,5 +1,9 @@
 # urbackup-server-web-api-wrapper
-Python wrapper to access and control an UrBackup server
+Python wrapper to access and control an UrBackup server.
+
+All responses are returned as **typed dataclasses** (e.g. `StatusResult`,
+`Backups`, `UserListItem`) so you get IDE autocompletion and type checking
+out of the box.
 
 ## Installation
 
@@ -9,34 +13,150 @@ Install with:
 
 ## Usage
 
-Start a full file backup:
+### Connect and log in
 
 ```python
-import urbackup_api
+from urbackup_api import urbackup_server_typed
+
+server = urbackup_server_typed("http://127.0.0.1:55414/x", "admin", "foo")
+server.login()
+```
 
-server = urbackup_api.urbackup_server("http://127.0.0.1:55414/x", "admin", "foo")
+### Start a backup
 
-server.start_full_file_backup("testclient0")
+```python
+from urbackup_api import BackupType
+
+# Get the client ID from the status list
+status = server.get_status_result()
+client = [c for c in status.status if c.name == "testclient0"][0]
+
+results = server.start_backup([client.id], BackupType.FULL_FILE)
+for r in results:
+    print(f"client {r.clientid}: start_ok={r.start_ok}")
 ```
 
-List clients with no file backup in the last three days:
+### List clients with no file backup in the last three days
 
 ```python
-import urbackup_api
-import time
 import datetime
-server = urbackup_api.urbackup_server("http://127.0.0.1:55414/x", "admin", "foo")
-clients = server.get_status()
-diff_time = 3*24*60*60 # 3 days
-for client in clients:
-    if client["lastbackup"]=="-" or client["lastbackup"] < time.time() - diff_time:
+import time
+
+status = server.get_status_result()
+diff_time = 3 * 24 * 60 * 60  # 3 days
 
-        if client["lastbackup"]=="-" or client["lastbackup"]==0:
+for client in status.status:
+    if client.lastbackup == "-" or client.lastbackup < time.time() - diff_time:
+        if client.lastbackup == "-" or client.lastbackup == 0:
             lastbackup = "Never"
         else:
-            lastbackup = datetime.datetime.fromtimestamp(client["lastbackup"]).strftime("%x %X")
+            lastbackup = datetime.datetime.fromtimestamp(client.lastbackup).strftime("%x %X")
+
+        print(f"Last file backup at {lastbackup} of client {client.name} is older than three days")
+```
+
+### Browse backups
+
+```python
+from urbackup_api import Backups
+
+backups = server.get_backups(client.id)
+for b in backups.backups:
+    print(f"Backup {b.id}: {b.size_bytes} bytes, incremental={b.incremental}")
+
+# Browse files inside a backup
+files = server.get_files(client.id, backups.backups[0].id, path="/")
+for f in files.files:
+    print(f"  {'[dir]' if f.dir else '     '} {f.name}")
+```
+
+### Monitor progress
+
+```python
+from urbackup_api import ProgressResult
+
+progress = server.get_progress(with_last_activities=True)
+for p in progress.progress:
+    print(f"Client {p.name}: {p.pcdone:.1f}% done")
+
+for a in progress.lastacts or []:
+    print(f"  Last activity: {a.name} ({a.duration}s)")
+```
+
+### Manage settings
+
+```python
+# Global settings
+settings = server.get_general_settings_result()
+print(settings["settings"]["max_file_incr"]["value"])
+
+server.save_general_settings({"max_file_incr": "15"})
 
-        print("Last file backup at {lastbackup} of client {clientname} is older than three days".format(
-              lastbackup=lastbackup, clientname=client["name"] ) )
+# Client settings (by ID)
+client_settings = server.get_client_settings_by_id(client.id)
+server.save_client_settings_by_id(client.id, {"internet_authkey": "mykey", "overwrite": "true"})
+
+# Mail / LDAP
+server.save_mail_settings({"mail_servername": "smtp.example.com", "mail_serverport": "587"})
+ldap = server.get_ldap_settings()
+```
+
+### User management
+
+```python
+from urbackup_api import UserListItem
+
+# List users
+users = server.get_user_list()
+for u in users:
+    print(f"{u.name} (id={u.id})")
+
+# Create / remove / change password
+server.create_user("operator", "s3cret")
+server.change_user_rights(users[0].id, "all=all")
+server.change_user_password(users[0].id, "newpassword")
+server.remove_user(users[0].id)
+```
+
+### Logs
+
+```python
+from urbackup_api import LogLevel
+
+logs = server.get_logs(log_level=LogLevel.WARNING)
+for entry in logs:
+    print(f"[{entry.name}] errors={entry.errors} warnings={entry.warnings}")
+
+# Detailed log entries
+details = server.get_log(logs[0].id)
+for row in details:
+    print(f"  [{row.level}] {row.message}")
+```
+
+### Extra clients
+
+```python
+# Extra clients are included in the status result
+status = server.get_status_result()
+for ec in status.extra_clients:
+    print(ec["hostname"])
+
+server.add_extra_client("10.0.1.100")
+server.remove_extra_client(ec_id)
+```
+
+### Remove / stop-remove clients
+
+```python
+server.remove_client(client.id)
+server.stop_remove_client(client.id)  # cancel pending removal
+```
+
+### Usage statistics
+
+```python
+usage = server.get_usage_stats()
+for u in usage:
+    print(f"{u.name}: files={u.files}, images={u.images}, used={u.used}")
 ```
 

tests/test_new_backups.py

@@ -0,0 +1,133 @@
+"""Tests for new typed backup-related operations."""
+
+import pytest
+
+from urbackup_api import (
+    BackupType,
+    Backups,
+    ClientProcessActionTypes,
+    ProgressResult,
+    StartBackupResultItem,
+)
+
+
+class TestBackupList:
+
+    def test_get_backups_returns_typed(self, server):
+        server.add_client("pytest-new-backup-client")
+        status = server.get_client_status("pytest-new-backup-client")
+        result = server.get_backups(status["id"])
+        assert isinstance(result, Backups)
+        assert isinstance(result.backups, list)
+        assert result.backups == []
+
+    def test_get_backups_has_image_backups(self, server):
+        server.add_client("pytest-new-imgbackup-client")
+        status = server.get_client_status("pytest-new-imgbackup-client")
+        result = server.get_backups(status["id"])
+        assert isinstance(result, Backups)
+        assert isinstance(result.backup_images, list)
+        assert result.backup_images == []
+
+    def test_get_backups_has_client_info(self, server):
+        server.add_client("pytest-new-bkp-info")
+        status = server.get_client_status("pytest-new-bkp-info")
+        result = server.get_backups(status["id"])
+        assert result.clientid == status["id"]
+        assert result.clientname == "pytest-new-bkp-info"
+
+
+class TestStartBackup:
+
+    @pytest.fixture(autouse=True)
+    def _create_client(self, server):
+        server.add_client("pytest-new-startbackup")
+        self._status = server.get_client_status("pytest-new-startbackup")
+
+    def test_start_incr_file_backup_no_online_client(self, server):
+        results = server.start_backup(
+            [self._status["id"]], BackupType.INCR_FILE
+        )
+        assert isinstance(results, list)
+        for r in results:
+            assert isinstance(r, StartBackupResultItem)
+            # Client not online, so start_ok should be False
+            assert r.start_ok is False
+
+    def test_start_full_file_backup_no_online_client(self, server):
+        results = server.start_backup(
+            [self._status["id"]], BackupType.FULL_FILE
+        )
+        assert isinstance(results, list)
+        for r in results:
+            assert isinstance(r, StartBackupResultItem)
+            assert r.start_ok is False
+
+    def test_start_incr_image_backup_no_online_client(self, server):
+        results = server.start_backup(
+            [self._status["id"]], BackupType.INCR_IMAGE
+        )
+        assert isinstance(results, list)
+        for r in results:
+            assert isinstance(r, StartBackupResultItem)
+            assert r.start_ok is False
+
+    def test_start_full_image_backup_no_online_client(self, server):
+        results = server.start_backup(
+            [self._status["id"]], BackupType.FULL_IMAGE
+        )
+        assert isinstance(results, list)
+        for r in results:
+            assert isinstance(r, StartBackupResultItem)
+            assert r.start_ok is False
+
+    def test_start_backup_returns_client_id(self, server):
+        results = server.start_backup(
+            [self._status["id"]], BackupType.INCR_FILE
+        )
+        assert len(results) == 1
+        assert results[0].clientid == self._status["id"]
+
+    def test_start_backup_returns_start_type(self, server):
+        results = server.start_backup(
+            [self._status["id"]], BackupType.FULL_FILE
+        )
+        assert len(results) == 1
+        assert results[0].start_type == "full_file"
+
+
+class TestProgressTyped:
+
+    def test_get_progress_empty(self, server):
+        result = server.get_progress()
+        assert isinstance(result, ProgressResult)
+        assert result.progress == []
+
+    def test_stop_process_invalid(self, server):
+        # Stopping a nonexistent process should still return a result
+        result = server.stop_process(clientid=99999, process_id=99999)
+        assert isinstance(result, ProgressResult)
+
+
+class TestProcessActionTypes:
+
+    def test_action_types_enum_values(self):
+        assert ClientProcessActionTypes.NONE == 0
+        assert ClientProcessActionTypes.INCR_FILE == 1
+        assert ClientProcessActionTypes.FULL_FILE == 2
+        assert ClientProcessActionTypes.INCR_IMAGE == 3
+        assert ClientProcessActionTypes.FULL_IMAGE == 4
+        assert ClientProcessActionTypes.RESUME_INCR_FILE == 5
+        assert ClientProcessActionTypes.RESUME_FULL_FILE == 6
+        assert ClientProcessActionTypes.RESTORE_FILE == 8
+        assert ClientProcessActionTypes.RESTORE_IMAGE == 9
+        assert ClientProcessActionTypes.UPDATE == 10
+        assert ClientProcessActionTypes.CHECK_INTEGRITY == 11
+        assert ClientProcessActionTypes.BACKUP_DATABASE == 12
+        assert ClientProcessActionTypes.RECALCULATE_STATISTICS == 13
+
+    def test_backup_type_enum_values(self):
+        assert BackupType.INCR_FILE.value == "incr_file"
+        assert BackupType.FULL_FILE.value == "full_file"
+        assert BackupType.INCR_IMAGE.value == "incr_image"
+        assert BackupType.FULL_IMAGE.value == "full_image"