Internal Reference

Update Module

class ghau.update.Update(version: str, repo: str, pre_releases: bool = False, reboot: str = None, download: str = 'zip', asset: str = None, auth: str = None, ratemin: int = 20, boot_check: bool = True, success_func=None, fail_func=None, pre_update_func=None, fail_args=None, success_args=None, post_update_func=None, pre_update_args=None, post_update_args=None)

Main class used to trigger updates through ghau.

Parameters:
  • version (str) – local version to check against online versions.
  • repo (str) – github repository to check for updates in. Must be publicly accessible unless you are using a Github Token.
  • pre-releases (bool, optional) – accept pre-releases as valid updates, defaults to False.
  • reboot (str, optional) – command intended to reboot the program after a successful update installs.
  • download (str, optional) – the type of download you wish to use for updates. Either “zip” (source code) or “asset” (uploaded files), defaults to “zip”.
  • asset (str, optional.) – name of asset to download when set to “asset” mode.
  • auth (str, optional) – authentication token used for accessing the Github API, defaults to None.
  • ratemin (int, optional.) – minimum amount of API requests left before updates will stop, defaults to 20. Maximum is 60/hr for unauthorized requests, and 5000 for authorized requests.
restart()

Restarts the program

update()

Check for updates and install if an update is found.

All expected exceptions triggered during the run of this method are automatically handled. They are intentionally raised to stop the update process should it be needed, not the entire program.

An error message will be printed to the console summarizing what occurred when this happens.

Raises:ghau.errors.InvalidDownloadTypeError – an unexpected value was given to the download parameter of ghau.update.Update.
update_check()

Returns True if an update is available to download.

wl_files(*args)

Add files to the whitelist. This protects any listed files from deletion during update installation. Each file should be a string referring to its name.

Parameters:args (str) – list of files to protect.
wl_test()

Test the whitelist and output what’s protected.

Useful for testing your whitelist configuration.

ghau.update._do_update(local, online)

Compares the given versions, returns True if the values are different.

ghau.update._find_release_asset(release: github.GitRelease.GitRelease, asset: str) → str

Return the requested asset’s download url from the given release. If no specific asset is requested, it will return the first one it comes across.

Raises:
ghau.update._load_release(repo: str, pre_releases: bool, auth) → github.GitRelease.GitRelease

Returns the latest release (or pre_release if enabled) for the loaded repository.

Raises:
ghau.update._run_cmd(command: str)

Run the given command and close the python interpreter. If no command is given, it will just close. Does not currently support Windows OS.

ghau.update.cmd(command: str) → str

Added for consistency with ghau.update.python.

Useful for building the command to place in the reboot parameter of ghau.update.Update.

This is the recommended way to reboot using a command, as it adds an argument ghau detects to stop update loops.

See also: ghau.update.python(), ghau.update.exe()

ghau.update.exe(file: str) → str

Added for consistency with ghau.update.python.

Useful for building the command to place in the reboot parameter of ghau.update.Update.

This is the recommended way to reboot into an executable file, as it adds an argument ghau detects to stop update loops. This will also ensure the file given is an .exe file.

See also: ghau.update.python(), ghau.update.cmd()

Raises:ghau.errors.FileNotExeError – raised if the given file is not an executable.
ghau.update.python(file: pathlib.Path) → str

Builds the command required to run the given python file if it is in the current working directory.

Useful for building the command to place in the reboot parameter of ghau.update.Update.

This is the recommended way to reboot into a python file, as it adds an argument ghau detects to stop update loops. This will also ensure the file given is a python script.

See also: ghau.update.exe(), ghau.update.cmd()

Raises:ghau.errors.FileNotScriptError – raised if the given file is not a python script.

Files Module

ghau.files.download(url: str, save_file: str)

Download a file from the given url and save it to the given save_file.

Parameters:
  • url (str) – url of the file to download.
  • save_file (str) – file to save the downloaded to.
ghau.files.extract_zip(extract_path, file_path, wl: list)

Extracts files from the given zip file_path into the given extract_path and performs cleanup operations.

Will not overwrite files present in the given whitelist.

Parameters:
  • extract_path (str) – path to extract the contents of the given zip to.
  • file_path (str) – path of the zip to extract.
  • wl (list) – whitelist to avoid overwriting files from.

Errors Module

exception ghau.errors.FileNotExeError(file: str)

Raised when the file given is not an executable.

exception ghau.errors.FileNotScriptError(file: str)

Raised when the file given is not a python script.

exception ghau.errors.GhauError

Base Exception class

exception ghau.errors.GitRepositoryFoundError

Raised when a git repository is detected.

exception ghau.errors.GithubRateLimitError(resettime)

Raised when exceeding GitHub’s API rate.

exception ghau.errors.InvalidDownloadTypeError(download)

Raised when the download parameter value is not expected.

exception ghau.errors.LoopPreventionError

Raised when rebooting after an update, to prevent potential loops if user doesn’t bump version number.

exception ghau.errors.NoAssetsFoundError(release)

Raised when an asset request returns no asset list

exception ghau.errors.NotAFileOrDirectoryError(path)

Raised when a path leads to neither a file nor a directory

exception ghau.errors.ReleaseAssetError(release, asset_name)

Raised when there is no asset found in the release by the requested name

exception ghau.errors.ReleaseNotFoundError(repo: str)

Raised when there are no releases found for the requested repository.

exception ghau.errors.RepositoryNotFoundError(repo: str)

Raised when Github request returns a 404

ghau.errors.argtest(args: list, arg: str)

Raises an error if the specified arg is found in the given args.

Used to determine if booting after an update installation.

Raises:ghau.errors.LoopPreventionError – stops the update process if booting after an update installation.
ghau.errors.devtest(root)

Tests for an active dev environment.

Raises:ghau.errors.GitRepositoryFoundError – stops the update process if a .git folder is found within the program directory
ghau.errors.ratetest(ratemin: int, token=None)

Tests available Github API rate.

Raises:ghau.errors.GithubRateLimitError – stops the update process if the available rates are below the ratemin.