From f5ab94a1ddcf0692f9f7f02b72149ef28bd31c29 Mon Sep 17 00:00:00 2001 From: Erik Montnemery Date: Tue, 4 Mar 2025 17:45:57 +0100 Subject: [PATCH] Document changes in BackupAgent API (#2588) --- blog/2025-03-04-backup-agent-api-changes.md | 12 ++++++++++++ docs/core/platform/backup.md | 13 ++++++++++--- 2 files changed, 22 insertions(+), 3 deletions(-) create mode 100644 blog/2025-03-04-backup-agent-api-changes.md diff --git a/blog/2025-03-04-backup-agent-api-changes.md b/blog/2025-03-04-backup-agent-api-changes.md new file mode 100644 index 00000000..8e1f48fd --- /dev/null +++ b/blog/2025-03-04-backup-agent-api-changes.md @@ -0,0 +1,12 @@ +--- +author: Erik Montnemery +authorURL: https://github.com/emontnemery +title: "Changes to the BackupAgent API" +--- + +The `BackupAgent` API has been adjusted such that the following methods should now raise `BackupNotFound` when a backup is not found: +- `BackupAgent.async_delete_backup` +- `BackupAgent.async_download_backup` +- `BackupAgent.async_get_backup` + +Check the backup agent documentation](/docs/core/platform/backup#backup-agents), and the [home assistant core PR #139754](https://github.com/home-assistant/core/pull/139754) for additional background. diff --git a/docs/core/platform/backup.md b/docs/core/platform/backup.md index 96131912..f02fc829 100644 --- a/docs/core/platform/backup.md +++ b/docs/core/platform/backup.md @@ -81,6 +81,8 @@ class ExampleBackupAgent(BackupAgent): ) -> AsyncIterator[bytes]: """Download a backup file. + Raises BackupNotFound if the backup does not exist. + :param backup_id: The ID of the backup that was returned in async_list_backups. :return: An async iterator that yields bytes. """ @@ -105,6 +107,8 @@ class ExampleBackupAgent(BackupAgent): ) -> None: """Delete a backup file. + Raises BackupNotFound if the backup does not exist. + :param backup_id: The ID of the backup that was returned in async_list_backups. """ @@ -115,11 +119,14 @@ class ExampleBackupAgent(BackupAgent): self, backup_id: str, **kwargs: Any, - ) -> AgentBackup | None: - """Return a backup.""" + ) -> AgentBackup: + """Return a backup. + + Raises BackupNotFound if the backup does not exist. + """ ``` -Backup agents should raise a `BackupAgentError` exception on error. Other exceptions are not expected to leave the backup agent. +Backup agents should raise a `BackupAgentError` (or a subclass of `BackupAgentError`) exception on error. Other exceptions are not expected to leave the backup agent. ## Pre- and post-operations