stouputils.installer.main module#

Main module of the installer subpackage for stouputils.

Provides functions for installing programs from local zip files or URLs. It handles downloading, extracting, and setting up programs in a platform-agnostic way.

This module contains the core installation functions that are used by both the Windows and Linux/macOS specific modules.

extract_archive(
extraction_path: str,
temp_dir: str,
extract_func: Callable[[str], None],
get_file_list_func: Callable[[], list[str]],
) → None[source]#

Helper function to extract archive files with consistent handling.

Parameters:

  • extraction_path (str) – Path where files should be extracted

  • temp_dir (str) – Temporary directory for intermediate extraction

  • extract_func (Callable[[str], None]) – Function to extract the archive

  • get_file_list_func (Callable[[], list[str]]) – Function to get the list of files in the archive

get_install_path(
program_name: str,
platform_str: str = 'Linux',
ask_global: int = 0,
add_path: bool = True,
append_to_path: str = '',
) → str[source]#

Get the installation path for the program on the current platform.

Parameters:

  • program_name (str) – The name of the program to install.

  • platform_str (str) – The platform to get the installation path for.

  • ask_global (int) – Whether to ask the user for a path, 0 = ask, 1 = install globally, 2 = install locally.

  • add_path (bool) – Whether to add the program to the PATH environment variable.

  • append_to_path (str) – String to append to the installation path when adding to PATH. (ex: “bin” if executables are in the bin folder)

Returns:

The installation path for the program.

Return type:

str

Examples

> # Get install path, ask user if they want global or local
> path = get_install_path("waifu2x-ncnn-vulkan", ask_global=0)
> # User will be prompted to choose between global and local installation

> # Force local installation
> path = get_install_path("my-tool", ask_global=2)
> # Returns a local path like "/home/user/my-tool" or "C:/Users/user/my-tool"

> # Force global installation
> path = get_install_path("my-tool", ask_global=1)
> # Returns a global path like "/usr/local/bin/my-tool" or "C:/Program Files/my-tool"
add_to_path(
install_path: str,
platform_str: str = 'Linux',
) → bool[source]#

Add the program to the PATH environment variable.

Parameters:

  • install_path (str) – The path to the program to add to the PATH environment variable.

  • platform_str (str) – The platform you are running on (ex: “Windows”, “Linux”, “Darwin”, …), we use this to determine the installation path if not provided.

Returns:

True if add to PATH was successful, False otherwise.

Return type:

bool

Examples

> # Add a directory to PATH on the current platform
> success = add_to_path("/usr/local/bin/my-program")
> print(success)
True

> # Add a Windows path (when running on Windows)
> add_to_path("C:/Program Files/MyApp/bin", platform_str="Windows")
True
install_program(
input_path: str,
install_path: str = '',
platform_str: str = 'Linux',
program_name: str = '',
add_path: bool = True,
append_to_path: str = '',
) → bool[source]#

Install a program to a specific path from a local zip file or URL.

Parameters:

  • input_path (str) – Path to a zip file or a download URL.

  • install_path (str) – The directory to extract the program into, we ask user for a path if not provided.

  • platform_str (str) – The platform you are running on (ex: “Windows”, “Linux”, “Darwin”, …), we use this to determine the installation path if not provided.

  • add_path (bool) – Whether to add the program to the PATH environment variable.

  • program_name (str) – Override the program name, we get it from the input path if not provided.

  • append_to_path (str) – String to append to the installation path when adding to PATH. (ex: “bin” if executables are in the bin folder)

Returns:

True if installation was successful, False otherwise.

Return type:

bool

Examples

> # Install from a URL
> success = install_program(
>     "https://github.com/example/tool/releases/download/v1.0/tool.zip",
>     install_path="/usr/local/bin/tool",
>     program_name="tool",
>     add_path=True
> )
> print(success)
True

> # Install from a local file
> install_program(
>     "/downloads/program.zip",
>     install_path="C:/Program Files/MyProgram",
>     add_path=False
> )
True

> # Install with executables in a subdirectory
> install_program(
>     "https://example.com/ffmpeg.zip",
>     program_name="ffmpeg",
>     append_to_path="bin"  # Adds /path/to/ffmpeg/bin to PATH
> )
True