Refactor API key parameters

README.md

@@ -40,26 +40,29 @@ This script is mostly based on the following original script: [REDVM/immich_auto
     ```
 3. Run the script
     ```
-    usage: immich_auto_album.py [-h] [-K API_KEY] [-F API_KEY_FILE] [-r ROOT_PATH] [-u] [-a ALBUM_LEVELS] [-s ALBUM_SEPARATOR] [-c CHUNK_SIZE] [-C FETCH_CHUNK_SIZE]
-                                [-l {CRITICAL,ERROR,WARNING,INFO,DEBUG}] [-k] [-i IGNORE] [-m {CREATE,CLEANUP,DELETE_ALL}] [-d] [-x SHARE_WITH] [-o {viewer,editor}] [-S {0,1,2}]
-                                [-O {False,asc,desc}] [-A] [-f PATH_FILTER] [--set-album-thumbnail {first,last,random,random-all,random-filtered}] [-v] [--find-archived-assets]
-                                root_path api_url
+    usage: immich_auto_album.py [-h] [-t {literal,file}] [-r ROOT_PATH] [-u] [-a ALBUM_LEVELS] [-s ALBUM_SEPARATOR] [-c CHUNK_SIZE] [-C FETCH_CHUNK_SIZE] [-l {CRITICAL,ERROR,WARNING,INFO,DEBUG}] [-k]
+                                [-i IGNORE] [-m {CREATE,CLEANUP,DELETE_ALL}] [-d] [-x SHARE_WITH] [-o {viewer,editor}] [-S {0,1,2}] [-O {False,asc,desc}] [-A] [-f PATH_FILTER]
+                                [--set-album-thumbnail {first,last,random,random-all,random-filtered}] [-v] [--find-archived-assets]
+                                root_path api_url api_key
 
     Create Immich Albums from an external library path based on the top level folders
 
     positional arguments:
-      root_path             The external libarary's root path in Immich
+      root_path             The external library's root path in Immich
       api_url               The root API URL of immich, e.g. https://immich.mydomain.com/api/
+      api_key               The Immich API Key to use. Set --api-key-type to 'file' if a file path is provided.
 
     options:
       -h, --help            show this help message and exit
+      -t {literal,file}, --api-key-type {literal,file}
+                            The type of the Immich API Key (default: literal)
       -r ROOT_PATH, --root-path ROOT_PATH
-                            Additional external libarary root path in Immich; May be specified multiple times for multiple import paths or external libraries. (default: None)
+                            Additional external library root path in Immich; May be specified multiple times for multiple import paths or external libraries. (default: None)
       -u, --unattended      Do not ask for user confirmation after identifying albums. Set this flag to run script as a cronjob. (default: False)
       -a ALBUM_LEVELS, --album-levels ALBUM_LEVELS
-                            Number of sub-folders or range of sub-folder levels below the root path used for album name creation. Positive numbers start from top of the folder structure,
-                            negative numbers from the bottom. Cannot be 0. If a range should be set, the start level and end level must be separated by a comma like '<startLevel>,<endLevel>'.
-                            If negative levels are used in a range, <startLevel> must be less than or equal to <endLevel>. (default: 1)
+                            Number of sub-folders or range of sub-folder levels below the root path used for album name creation. Positive numbers start from top of the folder structure, negative numbers
+                            from the bottom. Cannot be 0. If a range should be set, the start level and end level must be separated by a comma like '<startLevel>,<endLevel>'. If negative levels are used in
+                            a range, <startLevel> must be less than or equal to <endLevel>. (default: 1)
       -s ALBUM_SEPARATOR, --album-separator ALBUM_SEPARATOR
                             Separator string to use for compound album names created from nested folders. Only effective if -a is set to a value > 1 (default: )
       -c CHUNK_SIZE, --chunk-size CHUNK_SIZE
@@ -70,53 +73,46 @@ This script is mostly based on the following original script: [REDVM/immich_auto
                             Log level to use (default: INFO)
       -k, --insecure        Set to true to ignore SSL verification (default: False)
       -i IGNORE, --ignore IGNORE
-                            Use either literals or glob-like patterns to ignore assets for album name creation. This filter is evaluated after any values passed with --path-filter. May be
-                            specified multiple times. (default: None)
+                            Use either literals or glob-like patterns to ignore assets for album name creation. This filter is evaluated after any values passed with --path-filter. May be specified
+                            multiple times. (default: None)
       -m {CREATE,CLEANUP,DELETE_ALL}, --mode {CREATE,CLEANUP,DELETE_ALL}
-                            Mode for the script to run with. CREATE = Create albums based on folder names and provided arguments; CLEANUP = Create album nmaes based on current images and
-                            script arguments, but delete albums if they exist; DELETE_ALL = Delete all albums. If the mode is anything but CREATE, --unattended does not have any effect. Only
-                            performs deletion if -d/--delete-confirm option is set, otherwise only performs a dry-run. (default: CREATE)
-      -d, --delete-confirm  Confirm deletion of albums when running in mode CLEANUP or DELETE_ALL. If this flag is not set, these modes will perform a dry run only. Has no effect in mode
-                            CREATE (default: False)
+                            Mode for the script to run with. CREATE = Create albums based on folder names and provided arguments; CLEANUP = Create album nmaes based on current images and script arguments,
+                            but delete albums if they exist; DELETE_ALL = Delete all albums. If the mode is anything but CREATE, --unattended does not have any effect. Only performs deletion if
+                            -d/--delete-confirm option is set, otherwise only performs a dry-run. (default: CREATE)
+      -d, --delete-confirm  Confirm deletion of albums when running in mode CLEANUP or DELETE_ALL. If this flag is not set, these modes will perform a dry run only. Has no effect in mode CREATE (default:
+                            False)
       -x SHARE_WITH, --share-with SHARE_WITH
-                            A user name (or email address of an existing user) to share newly created albums with. Sharing only happens if the album was actually created, not if new assets
-                            were added to an existing album. If the the share role should be specified by user, the format <userName>=<shareRole> must be used, where <shareRole> must be one
-                            of 'viewer' or 'editor'. May be specified multiple times to share albums with more than one user. (default: None)
+                            A user name (or email address of an existing user) to share newly created albums with. Sharing only happens if the album was actually created, not if new assets were added to an
+                            existing album. If the the share role should be specified by user, the format <userName>=<shareRole> must be used, where <shareRole> must be one of 'viewer' or 'editor'. May be
+                            specified multiple times to share albums with more than one user. (default: None)
       -o {viewer,editor}, --share-role {viewer,editor}
-                            The default share role for users newly created albums are shared with. Only effective if --share-with is specified at least once and the share role is not
-                            specified within --share-with. (default: viewer)
+                            The default share role for users newly created albums are shared with. Only effective if --share-with is specified at least once and the share role is not specified within
+                            --share-with. (default: viewer)
       -S {0,1,2}, --sync-mode {0,1,2}
-                            Synchronization mode to use. Synchronization mode helps synchronizing changes in external libraries structures to Immich after albums have already been created.
-                            Possible Modes: 0 = do nothing; 1 = Delete any empty albums; 2 = Delete offline assets AND any empty albums (default: 0)
+                            Synchronization mode to use. Synchronization mode helps synchronizing changes in external libraries structures to Immich after albums have already been created. Possible Modes:
+                            0 = do nothing; 1 = Delete any empty albums; 2 = Delete offline assets AND any empty albums (default: 0)
       -O {False,asc,desc}, --album-order {False,asc,desc}
                             Set sorting order for newly created albums to newest or oldest file first, Immich defaults to newest file first (default: False)
       -A, --find-assets-in-albums
-                            By default, the script only finds assets that are not assigned to any album yet. Set this option to make the script discover assets that are already part of an
-                            album and handle them as usual. If --find-archived-assets is set as well, both options apply. (default: False)
+                            By default, the script only finds assets that are not assigned to any album yet. Set this option to make the script discover assets that are already part of an album and handle
+                            them as usual. If --find-archived-assets is set as well, both options apply. (default: False)
       -f PATH_FILTER, --path-filter PATH_FILTER
-                            Use either literals or glob-like patterns to filter assets before album name creation. This filter is evaluated before any values passed with --ignore. May be
-                            specified multiple times. (default: None)
+                            Use either literals or glob-like patterns to filter assets before album name creation. This filter is evaluated before any values passed with --ignore. May be specified multiple
+                            times. (default: None)
       --set-album-thumbnail {first,last,random,random-all,random-filtered}
-                            Set first/last/random image as thumbnail for newly created albums or albums assets have been added to. If set to random-filtered, thumbnails are shuffled for all
-                            albums whose assets would not be filtered out or ignored by the ignore or path-filter options, even if no assets were added during the run. If set to random-all,
-                            the thumbnails for ALL albums will be shuffled on every run. (default: None)
-      -v, --archive         Set this option to automatically archive all assets that were newly added to albums. If this option is set in combination with --mode = CLEANUP or DELETE_ALL,
-                            archived images of deleted albums will be unarchived. Archiving hides the assets from Immich's timeline. (default: False)
+                            Set first/last/random image as thumbnail for newly created albums or albums assets have been added to. If set to random-filtered, thumbnails are shuffled for all albums whose
+                            assets would not be filtered out or ignored by the ignore or path-filter options, even if no assets were added during the run. If set to random-all, the thumbnails for ALL
+                            albums will be shuffled on every run. (default: None)
+      -v, --archive         Set this option to automatically archive all assets that were newly added to albums. If this option is set in combination with --mode = CLEANUP or DELETE_ALL, archived images of
+                            deleted albums will be unarchived. Archiving hides the assets from Immich's timeline. (default: False)
       --find-archived-assets
-                            By default, the script only finds assets that are not archived in Immich. Set this option to make the script discover assets that are already archived. If
-                            -A/--find-assets-in-albums is set as well, both options apply. (default: False)
-
-    API Key:
-      -K API_KEY, --api-key API_KEY
-                            The Immich API Key to use. Either --api-key or --api-key-file must be specified. The --api-key variable takes precedence for ease of manual execution, but it is
-                            recommended to use --api-key-file. (default: None)
-      -F API_KEY_FILE, --api-key-file API_KEY_FILE
-                            A path to a file containing the Immich API Key to use. The file must contain only the value. (default: None)
+                            By default, the script only finds assets that are not archived in Immich. Set this option to make the script discover assets that are already archived. If -A/--find-assets-in-
+                            albums is set as well, both options apply. (default: False)
     ```
 
 __Plain example without optional arguments:__
 ```bash
-python3 ./immich_auto_album.py /path/to/external/lib https://immich.mydomain.com/api --api-key thisIsMyApiKeyCopiedFromImmichWebGui
+python3 ./immich_auto_album.py /path/to/external/lib https://immich.mydomain.com/api thisIsMyApiKeyCopiedFromImmichWebGui
 ```
 
 ### Docker
@@ -131,7 +127,7 @@ The environment variables are analoguous to the script's command line arguments.
 | ROOT_PATH            | yes | A single or a comma separated list of import paths for external libraries in Immich. <br>Refer to [Choosing the correct `root_path`](#choosing-the-correct-root_path).|
 | API_URL            | yes | The root API URL of immich, e.g. https://immich.mydomain.com/api/ |
 | API_KEY            | no | The Immich API Key to use. Either `API_KEY` or `API_KEY_FILE` must be specified. The `API_KEY` variable takes precedence for ease of manual execution, but it is recommended to use `API_KEY_FILE`. 
-| API_KEY_FILE       | no | A path to a file containing the Immich API Key to use. The file must contain only the value. |
+| API_KEY_FILE       | no | An absolute path (from the root of the container) to a file containing the Immich API Key. The file might be mounted into the container using a volume (e.g. `-v /path/to/api_key.secret:/immich_api_key.secret:ro`). The file must contain only the value. |
 | CRON_EXPRESSION    | yes | A [crontab-style expression](https://crontab.guru/) (e.g. `0 * * * *`) to perform album creation on a schedule (e.g. every hour). |
 | ALBUM_LEVELS       | no | Number of sub-folders or range of sub-folder levels below the root path used for album name creation. Positive numbers start from top of the folder structure, negative numbers from the bottom. Cannot be `0`. If a range should be set, the start level and end level must be separated by a comma. <br>Refer to [How it works](#how-it-works) for a detailed explanation and examples. |
 | ALBUM_SEPARATOR    | no | Separator string to use for compound album names created from nested folders. Only effective if `-a` is set to a value `> 1`(default: "` `") |

docker/immich_auto_album.sh

@@ -52,18 +52,21 @@ if [ ! -z "$UNATTENDED" ]; then
     unattended="--unattended"
 fi
 
-args="$unattended $main_root_path $API_URL"
-
-if [ ! -z "$additional_root_paths" ]; then
-    args="$additional_root_paths $args"
-fi
+api_key=""
+api_key_type=""
 
 if [ ! -z "$API_KEY" ]; then
-    args="--api-key \"$API_KEY\" $args"
+    api_key=$API_KEY
+    api_key_type="--api-key-type literal"
+elif [ ! -z "$API_KEY_FILE" ]; then
+    api_key=$API_KEY_FILE
+    api_key_type="--api-key-type file"
 fi
 
-if [ ! -z "$API_KEY_FILE" ]; then
-    args="--api-key-file \"$API_KEY_FILE\" $args"
+args="$api_key_type $unattended $main_root_path $API_URL $api_key"
+
+if [ ! -z "$additional_root_paths" ]; then
+    args="$additional_root_paths $args"
 fi
 
 if [ ! -z "$ALBUM_LEVELS" ]; then

immich_auto_album.py

@@ -68,12 +68,11 @@ def glob_to_re(pattern):
 }
 
 parser = argparse.ArgumentParser(description="Create Immich Albums from an external library path based on the top level folders", formatter_class=argparse.ArgumentDefaultsHelpFormatter)
-parser.add_argument("root_path", action='append', help="The external libarary's root path in Immich")
+parser.add_argument("root_path", action='append', help="The external library's root path in Immich")
 parser.add_argument("api_url", help="The root API URL of immich, e.g. https://immich.mydomain.com/api/")
-api_key_group = parser.add_argument_group('API Key')
-api_key_group.add_argument("-K", "--api-key", help="The Immich API Key to use. Either --api-key or --api-key-file must be specified. The --api-key parameter takes precedence for ease of manual execution, but it is recommended to use --api-key-file. ")
-api_key_group.add_argument("-F", "--api-key-file", help="A path to a file containing the Immich API Key to use. The file must contain only the value.")
-parser.add_argument("-r", "--root-path", action="append", help="Additional external libarary root path in Immich; May be specified multiple times for multiple import paths or external libraries.")
+parser.add_argument("api_key", help="The Immich API Key to use. Set --api-key-type to 'file' if a file path is provided.")
+parser.add_argument("-t", "--api-key-type", default="literal", choices=['literal', 'file'], help="The type of the Immich API Key")
+parser.add_argument("-r", "--root-path", action="append", help="Additional external library root path in Immich; May be specified multiple times for multiple import paths or external libraries.")
 parser.add_argument("-u", "--unattended", action="store_true", help="Do not ask for user confirmation after identifying albums. Set this flag to run script as a cronjob.")
 parser.add_argument("-a", "--album-levels", default="1", type=str, help="Number of sub-folders or range of sub-folder levels below the root path used for album name creation. Positive numbers start from top of the folder structure, negative numbers from the bottom. Cannot be 0. If a range should be set, the start level and end level must be separated by a comma like '<startLevel>,<endLevel>'. If negative levels are used in a range, <startLevel> must be less than or equal to <endLevel>.")
 parser.add_argument("-s", "--album-separator", default=" ", type=str, help="Separator string to use for compound album names created from nested folders. Only effective if -a is set to a value > 1")
@@ -100,9 +99,6 @@ def glob_to_re(pattern):
 logging.basicConfig(level=args["log_level"], stream=sys.stdout, format='time=%(asctime)s level=%(levelname)s msg=%(message)s')
 logging.Formatter.formatTime = (lambda self, record, datefmt=None: datetime.datetime.fromtimestamp(record.created, datetime.timezone.utc).astimezone().isoformat(sep="T",timespec="milliseconds"))
 
-if not (args["api_key"] or args["api_key_file"]):
-    parser.error("At least one of --api-key (-K) or --api-key-file (-F) must be provided.")
-
 def readApiKeyFromFile(file_path: str) -> str:
     try:
         with open(file_path, 'r') as secret_file:
@@ -112,12 +108,20 @@ def readApiKeyFromFile(file_path: str) -> str:
         exit(1)
     except Exception as e:
         logging.error("Error reading API Key file: %s", e)
-        exit(1)    
+        exit(1)
 
+def determine_api_key(api_key: str, key_type: str) -> str:
+    if key_type == "literal":
+        return api_key
+    elif key_type == "file":
+        return readApiKeyFromFile(api_key)
+    else:
+        logging.error("Unknown key type (-t, --key-type). Must be either 'literal' or 'file'.")
+        exit(1)
 
 root_paths = args["root_path"]
 root_url = args["api_url"]
-api_key = args["api_key"] if args["api_key"] else readApiKeyFromFile(args["api_key_file"])
+api_key = determine_api_key(args["api_key"], args["api_key_type"])
 number_of_images_per_request = args["chunk_size"]
 number_of_assets_to_fetch_per_request = args["fetch_chunk_size"]
 unattended = args["unattended"]