ae.updater

application environment updater

this portion is providing helper functions to set up, prepare and/or upgrade packages, resources, config variables, like application status or user preferences of your app.

updater check functions

automatically copy, move or update any files on the destination machine with the help of the helper functions check_copies() and check_moves(). these functions can be restricted to copy/move only the files that do not exist in the destination folder (while protecting already existing files from being overwritten).

if your app needs to execute a Python pre-app-run-script on every startup of your application, then simply call the function check_local_pre_app_runs(), which will check if an importable and executable module with the name specified by the PRE_APP_MODULE_NAME constant exists and contains a function with the name run_updater.

the function check_local_updates() checks if a (newly added) update script/module with the name specified by the UPDATER_MODULE_NAME constant exists, and if yes, it imports this module and executes the function run_updater declared in it. after the successful execution, the update module will be deleted. this one-time execution feature can be used e.g., to deploy and configure more complex updates, or to adapt an existing app installation, respectively their resources and settings.

the function check_all() combines all the above update checks and executions.

..hint: more info on the update helper functions provided by this portion, you find in their respective doc-strings.

any of these update check helper functions has to be imported and executed before the loading and initialization of the updatable code modules and resources, e.g., like so:

from ae.updater import check_all
check_all()

from updatable_app_package import ...
...
initialize_updatable_app_resources()

if your app only has to support one or some of the update/pre-app-run features, then replace in the above code example the check_all() with the necessary check function(s).

Note

the ae.core is calling check_all() automatically on start of your console or GUI app on initialization of the main app AppBase class instance.

additionally, it extends the PATH_PLACEHOLDERS with OS-specific system paths (like e.g. {downloads}).

to use OS-specific PATH_PLACEHOLDERS ids as folder argument values for apps not based on the ae.core portion, the function add_common_storage_paths() has to be explicitly called.

data-driven file copy/move operations

the file copy and move operations provided by check_copies(), check_moves() and check_all() are highly parameterizable.

you can specify source and destination paths for all of them via their function arguments. relative folder paths will be relative to the current working directory ({cwd}).

additionally, the destination path and the OS where the copy/move operation has to be processed can be tweaked via two optional arguments specified in the name of the source folder.

in order to specify individual destination OS and path, append the string UPDATER_ARGS_SEP to the folder name directly followed by the argument name and value.

the argument name string UPDATER_ARG_OS_PLATFORM followed by the platform id restricts the copy/move operations for a certain OS.

to overwrite the default destination folder/path of the copy/move operations for a source folder, put the string UPDATER_ARG_DST_PATH as argument name, followed by the defused destination path string as argument value. this argument value is either a relative/absolute path string or a PATH_PLACEHOLDERS id.

for example, the files in a folder with the name ae_updater_moves___OnOS__android will only be moved to the destination folder if the app is running on Android OS.

Module Attributes

`COPIES_SRC_FOLDER_NAME`	copies if not exists dir name
`COPY_OVER_SRC_FOLDER_NAME`	overwrite copies dir name
`MOVES_SRC_FOLDER_NAME`	dir name for moves
`MOVE_OVER_SRC_FOLDER_NAME`	overwrite moves dir name
`UPDATER_ARGS_SEP`	folder-name-arg separator
`UPDATER_ARG_DST_PATH`	dst-path folder-name-arg
`UPDATER_ARG_OS_PLATFORM`	platform folder-name-arg
`PRE_APP_MODULE_NAME`	pre-app-run module name
`UPDATER_MODULE_NAME`	module name of updater

Functions

`check_all`([copy_src_path, ...])	check all outstanding scripts to be executed and files to be moved/overwritten.
`check_copies`([src_path, dst_path, overwrite])	check on new or missing files to be copied from src_folder to the dst_folder.
`check_local_pre_app_runs`()	check if a pre-app-run-script exists in the current working directory to be executed on/before app startup.
`check_local_updates`()	check if ae_updater script exists in the current working directory to be executed and deleted.
`check_moves`([src_path, dst_path, overwrite])	check on missing files to be moved from src_folder to the dst_folder.
`source_destination_paths`(src_folder_prefix, ...)	collect source folders and determine destination folders for each of them.

COPIES_SRC_FOLDER_NAME = 'ae_updater_copies': copies if not exists dir name

COPY_OVER_SRC_FOLDER_NAME = 'ae_updater_over_copies': overwrite copies dir name

MOVES_SRC_FOLDER_NAME = 'ae_updater_moves': dir name for moves

MOVE_OVER_SRC_FOLDER_NAME = 'ae_updater_over_moves': overwrite moves dir name

UPDATER_ARGS_SEP = '___': folder-name-arg separator

UPDATER_ARG_DST_PATH = 'ToPath__': dst-path folder-name-arg

UPDATER_ARG_OS_PLATFORM = 'OnOS__': platform folder-name-arg

PRE_APP_MODULE_NAME = 'ae_pre_app_run': pre-app-run module name

UPDATER_MODULE_NAME = 'ae_updater': module name of updater

check_all(copy_src_path='ae_updater_copies', copy_over_src_path='ae_updater_over_copies', move_src_path='ae_updater_moves', move_over_src_path='ae_updater_over_moves', dst_folder='{usr}')[source]

check all outstanding scripts to be executed and files to be moved/overwritten.

Parameters:

copy_src_path¶ (str) – path to the source folder / directory where the files get copied from. if not specified or if you pass an empty string, then COPIES_SRC_FOLDER_NAME will be used.
copy_over_src_path¶ (str) – path to the source folder / directory where the files get copied from and overwritten to. if not specified then COPY_OVER_SRC_FOLDER_NAME will be used.
move_src_path¶ (str) – path to the source folder / directory where the files get moved from. if not specified or if you pass an empty string, then MOVES_SRC_FOLDER_NAME will be used.
move_over_src_path¶ (str) – path to the source folder / directory where the files get moved from and overwritten to. if not specified, then MOVE_OVER_SRC_FOLDER_NAME will be used.
dst_folder¶ (str) – path to the destination folder / directory where the files get moved to. if not specified or if you pass an empty string, then the user data/preferences path ({usr}) will be used. this argument may get overwritten for source folder names specifying the data-driven UPDATER_ARG_DST_PATH argument.

Return type:

List[str]

Returns:

list of processed (copied, moved or overwritten) files, with their destination path.

check_copies(src_path='ae_updater_copies', dst_path='{usr}', overwrite=False)[source]

check on new or missing files to be copied from src_folder to the dst_folder.

Parameters:

src_path¶ (str) – path to the source folder / directory where the files get copied from. if not specified then COPIES_SRC_FOLDER_NAME will be used.
dst_path¶ (str) – path to the destination folder / directory where the files get copied to. if not specified or if you pass an empty string, then the user data/preferences path ({usr}) will be used. this argument may get overwritten for source folder names specifying the data-driven UPDATER_ARG_DST_PATH argument.
overwrite¶ (bool) – pass True to overwrite existing files in the destination folder/directory. on False the files will only get copied if they do not exist in the destination.

Return type:

List[str]

Returns:

list of copied files, with their destination path.

check_moves(src_path='ae_updater_moves', dst_path='{usr}', overwrite=False)[source]

check on missing files to be moved from src_folder to the dst_folder.

Parameters:

src_path¶ (str) – path to the source folder / directory where the files get moved from. if not specified, then MOVES_SRC_FOLDER_NAME will be used. note that the source folder itself will neither be moved nor removed (but will be empty after the operation is finished).
dst_path¶ (str) – path to the destination folder/directory where the files get moved to. if not specified or if you pass an empty string, then the user data/preferences path ({usr}) will be used. this argument may get overwritten for source folder names specifying the data-driven UPDATER_ARG_DST_PATH argument.
overwrite¶ (bool) – pass True to overwrite existing files in the destination folder/directory. on False the files will only get moved if they do not exist in the destination.

Return type:

List[str]

Returns:

list of moved files, with their destination path.

check_local_updates()[source]

check if ae_updater script exists in the current working directory to be executed and deleted.

Return type:: bool
Returns:: return value of the executed run_updater function (if the module UPDATER_MODULE_NAME can be loaded/imported and contains this function) else False.

check_local_pre_app_runs()[source]

check if a pre-app-run-script exists in the current working directory to be executed on/before app startup.

Return type:: bool
Returns:: return value of the executed run_updater function (if the module PRE_APP_MODULE_NAME can be loaded/imported and contains this function) else False.

source_destination_paths(src_folder_prefix, default_dst_folder)[source]

collect source folders and determine destination folders for each of them.

Parameters:

src_folder_prefix¶ (str) – source folder name without folder-name-args.
default_dst_folder¶ (str) – destination folder default (if not specified in folder-name-args).

Return type:

list[tuple[str, str]]

Returns:

list of source and destination folders to process.