refactor: un-deprecate download_path option

Enough people are using this, so we'll keep this feature for now. This reverts commit 6354f9f.
jcwillox · Jul 30, 2023 · 4c522ac · 4c522ac
1 parent 07cbcff
commit 4c522ac
Show file tree

Hide file tree

Showing 5 changed files with 58 additions and 32 deletions.
diff --git a/README.md b/README.md
@@ -20,6 +20,7 @@ For more information and examples check the [documentation](https://jcwillox.git
 - [Exclude addons/folders](https://jcwillox.github.io/hass-auto-backup/services) from a backup.
 - [Automatically delete backups](https://jcwillox.github.io/hass-auto-backup/services/#keep-days) after an individually specified amount of time.
 - Backup to [custom locations](https://jcwillox.github.io/hass-auto-backup/services/#custom-locations) such as network storage.
+- [Download backups](https://jcwillox.github.io/hass-auto-backup/services/#download-path) to a specified directory after completion (for example a usb drive).
 - Allows the use of [addon names instead of slugs](https://jcwillox.github.io/hass-auto-backup/services/#addon-and-folder-names).
 - Provides a [sensor](https://jcwillox.github.io/hass-auto-backup/sensors) to monitor the status of your backups.
 - Creates [events](https://jcwillox.github.io/hass-auto-backup/events) for when backups are started/created/failed/deleted.

diff --git a/custom_components/auto_backup/__init__.py b/custom_components/auto_backup/__init__.py
@@ -94,36 +94,29 @@
     vol.Optional(ATTR_ADDONS, default=[]): SCHEMA_LIST_STRING,
 }
 
-SCHEMA_BACKUP_FULL = vol.All(
-    cv.deprecated(ATTR_DOWNLOAD_PATH),
-    SCHEMA_BACKUP_BASE.extend({vol.Optional(ATTR_EXCLUDE): SCHEMA_ADDONS_FOLDERS}),
+SCHEMA_BACKUP_FULL = SCHEMA_BACKUP_BASE.extend(
+    {vol.Optional(ATTR_EXCLUDE): SCHEMA_ADDONS_FOLDERS}
 )
 
-SCHEMA_BACKUP_PARTIAL = vol.All(
-    cv.deprecated(ATTR_DOWNLOAD_PATH), SCHEMA_BACKUP_BASE.extend(SCHEMA_ADDONS_FOLDERS)
-)
+SCHEMA_BACKUP_PARTIAL = SCHEMA_BACKUP_BASE.extend(SCHEMA_ADDONS_FOLDERS)
 
-SCHEMA_BACKUP = vol.All(
-    cv.deprecated(ATTR_DOWNLOAD_PATH),
-    vol.Any(
-        SCHEMA_BACKUP_BASE.extend(
-            {
-                vol.Optional(ATTR_INCLUDE): SCHEMA_ADDONS_FOLDERS,
-                vol.Optional(ATTR_EXCLUDE): SCHEMA_ADDONS_FOLDERS,
-            }
-        ),
-        SCHEMA_BACKUP_BASE.extend(
-            {
-                vol.Optional(ATTR_INCLUDE_ADDONS): SCHEMA_LIST_STRING,
-                vol.Optional(ATTR_INCLUDE_FOLDERS): SCHEMA_LIST_STRING,
-                vol.Optional(ATTR_EXCLUDE_ADDONS): SCHEMA_LIST_STRING,
-                vol.Optional(ATTR_EXCLUDE_FOLDERS): SCHEMA_LIST_STRING,
-            }
-        ),
+SCHEMA_BACKUP = vol.Any(
+    SCHEMA_BACKUP_BASE.extend(
+        {
+            vol.Optional(ATTR_INCLUDE): SCHEMA_ADDONS_FOLDERS,
+            vol.Optional(ATTR_EXCLUDE): SCHEMA_ADDONS_FOLDERS,
+        }
+    ),
+    SCHEMA_BACKUP_BASE.extend(
+        {
+            vol.Optional(ATTR_INCLUDE_ADDONS): SCHEMA_LIST_STRING,
+            vol.Optional(ATTR_INCLUDE_FOLDERS): SCHEMA_LIST_STRING,
+            vol.Optional(ATTR_EXCLUDE_ADDONS): SCHEMA_LIST_STRING,
+            vol.Optional(ATTR_EXCLUDE_FOLDERS): SCHEMA_LIST_STRING,
+        }
     ),
 )
 
-
 MAP_SERVICES = {
     SERVICE_BACKUP: SCHEMA_BACKUP,
     SERVICE_BACKUP_FULL: SCHEMA_BACKUP_FULL,

diff --git a/custom_components/auto_backup/services.yaml b/custom_components/auto_backup/services.yaml
@@ -84,6 +84,16 @@ backup:
       example: my_backup_mount
       selector:
         backup_location:
+    download_path: &download_path
+      name: Download path
+      description: Locations to download the backup to after creation.
+      example: "[/usb_drive]"
+      advanced: true
+      selector:
+        select:
+          multiple: true
+          custom_value: true
+          options: [ ]
     compressed: &compressed
       name: Compressed
       description: Use compressed archives
@@ -106,6 +116,7 @@ backup_full:
     password: *password
     keep_days: *keep_days
     location: *location
+    download_path: *download_path
     compressed: *compressed
 
 backup_partial:
@@ -142,6 +153,7 @@ backup_partial:
     password: *password
     keep_days: *keep_days
     location: *location
+    download_path: *download_path
     compressed: *compressed
 
 purge:

diff --git a/docs/index.md b/docs/index.md
@@ -14,6 +14,7 @@ Auto Backup is an Improved Backup Service for Home Assistant that can Automatica
 - [x] [Exclude addons/folders](services.md) from a backup.
 - [x] [Automatically delete backups](services.md#keep-days) after an individually specified amount of time.
 - [x] Backup to [custom locations](services.md#custom-locations) such as network storage.
+- [x] [Download backups](services.md#download-path) to a specified directory after completion (for example a usb drive).
 - [x] Allows the use of [addon names instead of slugs](services.md#addon-and-folder-names).
 - [x] Provides a [sensor](sensors.md) to monitor the status of your backups.
 - [x] Creates [events](events.md) for when backups are started/created/failed/deleted.

diff --git a/docs/services.md b/docs/services.md
@@ -18,6 +18,7 @@ This is the primary method and includes the functionality of the `backup_full` a
 | `password`                                   | Optional password to secure backup.                                                      | `string` | `#!json 1234`                                               |
 | [`keep_days`](#keep-days)                    | The number of days to keep the backup.                                                   | `float`  | `#!json 2`                                                  |
 | [`location`](#custom-locations)              | Name of a backup network storage to put backup (or /backup)                              | `string` | `#!json my_backup_mount`                                    |
+| [`download_path`](#download-path)            | Locations to download the backup to after creation.                                      | `list`   | `#!json ["/usb_drive"]`                                     |
 | `compressed`                                 | Use compressed archives (default: true)                                                  | `bool`   | `#!json true`                                               |
 
 ??? example "Create a full backup"
@@ -88,18 +89,35 @@ Home Assistant [2023.6](https://www.home-assistant.io/blog/2023/06/07/release-20
 
 [![Open your Home Assistant instance and show storage information.](https://my.home-assistant.io/badges/storage.svg)](https://my.home-assistant.io/redirect/storage/)
 
+### Download Path
+
+The `download_path` parameter allows you to specify a location or of list of locations to download the backup to after creation. This directory must be accessible from Home Assistant. If you are running in docker your paths will be relative to the container for example your Home Assistant configuration directory is stored under `/config` and the share folder is under `/share`.
+
+!!! tip
+
+    The backup will still be stored under `/backup` and show up on the [backups](https://my.home-assistant.io/redirect/backup) page, it will only be copied/downloaded to the location specified, to immediately delete the backup use a negative value for `keep_days` (e.g. `#!yaml keep_days: -1` ).
+
+!!! info
+
+    A slugified version of the backups name will be used for the filename, if a file with that name already exists the backups id (slug) will be used instead.
+
+!!! note
+
+    When running on **Home Assistant Core** backups will be copied not downloaded. When running **Home Assistant Supervised** integrations do not have direct access to the `/backup` folder, which is why the backup is downloaded and not simply copied.
+
 ## `auto_backup.backup_full`
 
 Create a full backup with optional exclusions.
 
-| Parameter                       | Description                                                 | Type                                | Example                                                                                                                      |
-| ------------------------------- | ----------------------------------------------------------- | ----------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
-| `name`                          | Optional name, defaults to the current date and time.       | `string`                            | `#!jinja Automatic Backup {{ now().strftime('%Y-%m-%d') }}`                                                                  |
-| `exclude`                       | Addons/Folders to exclude from the backup.                  | [`Exclude Object`](#exclude-object) | [`#!json {"addons": ["MariaDB"], "folders": ["Local add-ons", "share"]}`](examples.md#excluding-addonsfolders-from-a-backup) |
-| `password`                      | Optional password to secure backup.                         | `string`                            | `#!json 1234`                                                                                                                |
-| [`keep_days`](#keep-days)       | The number of days to keep the backup.                      | `float`                             | `#!json 2`                                                                                                                   |
-| [`location`](#custom-locations) | Name of a backup network storage to put backup (or /backup) | `string`                            | `#!json my_backup_mount`                                                                                                     |
-| `compressed`                    | Use compressed archives (default: true)                     | `bool`                              | `#!json true`                                                                                                                |
+| Parameter                         | Description                                                 | Type                                | Example                                                                                                                      |
+| --------------------------------- | ----------------------------------------------------------- | ----------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
+| `name`                            | Optional name, defaults to the current date and time.       | `string`                            | `#!jinja Automatic Backup {{ now().strftime('%Y-%m-%d') }}`                                                                  |
+| `exclude`                         | Addons/Folders to exclude from the backup.                  | [`Exclude Object`](#exclude-object) | [`#!json {"addons": ["MariaDB"], "folders": ["Local add-ons", "share"]}`](examples.md#excluding-addonsfolders-from-a-backup) |
+| `password`                        | Optional password to secure backup.                         | `string`                            | `#!json 1234`                                                                                                                |
+| [`keep_days`](#keep-days)         | The number of days to keep the backup.                      | `float`                             | `#!json 2`                                                                                                                   |
+| [`location`](#custom-locations)   | Name of a backup network storage to put backup (or /backup) | `string`                            | `#!json my_backup_mount`                                                                                                     |
+| [`download_path`](#download-path) | Locations to download the backup to after creation.         | `list`                              | `#!json ["/usb_drive"]`                                                                                                      |
+| `compressed`                      | Use compressed archives (default: true)                     | `bool`                              | `#!json true`                                                                                                                |
 
 #### Exclude Object
 
@@ -120,6 +138,7 @@ Create a partial backup.
 | `password`                           | Optional password to secure backup.                         | `string` | `#!json 1234`                                               |
 | [`keep_days`](#keep-days)            | The number of days to keep the backup.                      | `float`  | `#!json 2`                                                  |
 | [`location`](#custom-locations)      | Name of a backup network storage to put backup (or /backup) | `string` | `#!json my_backup_mount`                                    |
+| [`download_path`](#download-path)    | Locations to download the backup to after creation.         | `list`   | `#!json ["/usb_drive"]`                                     |
 | `compressed`                         | Use compressed archives (default: true)                     | `bool`   | `#!json true`                                               |
 
 ## `auto_backup.purge`