stouputils 1.12.1__py3-none-any.whl

stouputils/image.pyi

@@ -0,0 +1,172 @@
+import numpy as np
+from .io import super_open as super_open
+from .print import debug as debug, info as info
+from PIL import Image
+from collections.abc import Callable
+from numpy.typing import NDArray
+from typing import Any, TypeVar
+
+PIL_Image_or_NDArray = TypeVar('PIL_Image_or_NDArray', bound='Image.Image | NDArray[np.number]')
+
+def image_resize[PIL_Image_or_NDArray](image: PIL_Image_or_NDArray, max_result_size: int, resampling: Image.Resampling | None = None, min_or_max: Callable[[int, int], int] = ..., return_type: type[PIL_Image_or_NDArray] | str = 'same', keep_aspect_ratio: bool = True) -> Any:
+    ''' Resize an image while preserving its aspect ratio by default.
+\tScales the image so that its largest dimension equals max_result_size.
+
+\tArgs:
+\t\timage             (Image.Image | np.ndarray): The image to resize.
+\t\tmax_result_size   (int):                      Maximum size for the largest dimension.
+\t\tresampling        (Image.Resampling | None):  PIL resampling filter to use (default: Image.Resampling.LANCZOS).
+\t\tmin_or_max        (Callable):                 Function to use to get the minimum or maximum of the two ratios.
+\t\treturn_type       (type | str):               Type of the return value (Image.Image, np.ndarray, or "same" to match input type).
+\t\tkeep_aspect_ratio (bool):                     Whether to keep the aspect ratio.
+\tReturns:
+\t\tImage.Image | NDArray[np.number]: The resized image with preserved aspect ratio.
+\tExamples:
+\t\t>>> # Test with (height x width x channels) numpy array
+\t\t>>> import numpy as np
+\t\t>>> array = np.random.randint(0, 255, (100, 50, 3), dtype=np.uint8)
+\t\t>>> image_resize(array, 100).shape
+\t\t(100, 50, 3)
+\t\t>>> image_resize(array, 100, min_or_max=max).shape
+\t\t(100, 50, 3)
+\t\t>>> image_resize(array, 100, min_or_max=min).shape
+\t\t(200, 100, 3)
+
+\t\t>>> # Test with PIL Image
+\t\t>>> from PIL import Image
+\t\t>>> pil_image: Image.Image = Image.new(\'RGB\', (200, 100))
+\t\t>>> image_resize(pil_image, 50).size
+\t\t(50, 25)
+\t\t>>> # Test with different return types
+\t\t>>> resized_array = image_resize(array, 50, return_type=np.ndarray)
+\t\t>>> isinstance(resized_array, np.ndarray)
+\t\tTrue
+\t\t>>> resized_array.shape
+\t\t(50, 25, 3)
+\t\t>>> # Test with different resampling methods
+\t\t>>> image_resize(pil_image, 50, resampling=Image.Resampling.NEAREST).size
+\t\t(50, 25)
+\t'''
+def auto_crop[PIL_Image_or_NDArray](image: PIL_Image_or_NDArray, mask: NDArray[np.bool_] | None = None, threshold: int | float | Callable[[NDArray[np.number]], int | float] | None = None, return_type: type[PIL_Image_or_NDArray] | str = 'same', contiguous: bool = True) -> Any:
+    ''' Automatically crop an image to remove zero or uniform regions.
+
+\tThis function crops the image to keep only the region where pixels are non-zero
+\t(or above a threshold). It can work with a mask or directly analyze the image.
+
+\tArgs:
+\t\timage       (Image.Image | NDArray):\t  The image to crop.
+\t\tmask        (NDArray[bool] | None):       Optional binary mask indicating regions to keep.
+\t\tthreshold   (int | float | Callable):     Threshold value or function (default: np.min).
+\t\treturn_type (type | str):                 Type of the return value (Image.Image, NDArray[np.number], or "same" to match input type).
+\t\tcontiguous  (bool):                       If True (default), crop to bounding box. If False, remove entire rows/columns with no content.
+\tReturns:
+\t\tImage.Image | NDArray[np.number]: The cropped image.
+
+\tExamples:
+\t\t>>> # Test with numpy array with zeros on edges
+\t\t>>> import numpy as np
+\t\t>>> array = np.zeros((100, 100, 3), dtype=np.uint8)
+\t\t>>> array[20:80, 30:70] = 255  # White rectangle in center
+\t\t>>> cropped = auto_crop(array, return_type=np.ndarray)
+\t\t>>> cropped.shape
+\t\t(60, 40, 3)
+
+\t\t>>> # Test with custom mask
+\t\t>>> mask = np.zeros((100, 100), dtype=bool)
+\t\t>>> mask[10:90, 10:90] = True
+\t\t>>> cropped_with_mask = auto_crop(array, mask=mask, return_type=np.ndarray)
+\t\t>>> cropped_with_mask.shape
+\t\t(80, 80, 3)
+
+\t\t>>> # Test with PIL Image
+\t\t>>> from PIL import Image
+\t\t>>> pil_image = Image.new(\'RGB\', (100, 100), (0, 0, 0))
+\t\t>>> from PIL import ImageDraw
+\t\t>>> draw = ImageDraw.Draw(pil_image)
+\t\t>>> draw.rectangle([25, 25, 75, 75], fill=(255, 255, 255))
+\t\t>>> cropped_pil = auto_crop(pil_image)
+\t\t>>> cropped_pil.size
+\t\t(51, 51)
+
+\t\t>>> # Test with threshold
+\t\t>>> array_gray = np.ones((100, 100), dtype=np.uint8) * 10
+\t\t>>> array_gray[20:80, 30:70] = 255
+\t\t>>> cropped_threshold = auto_crop(array_gray, threshold=50, return_type=np.ndarray)
+\t\t>>> cropped_threshold.shape
+\t\t(60, 40)
+
+\t\t>>> # Test with callable threshold (using lambda to avoid min value)
+\t\t>>> array_gray2 = np.ones((100, 100), dtype=np.uint8) * 10
+\t\t>>> array_gray2[20:80, 30:70] = 255
+\t\t>>> cropped_max = auto_crop(array_gray2, threshold=lambda x: 50, return_type=np.ndarray)
+\t\t>>> cropped_max.shape
+\t\t(60, 40)
+
+\t>>> # Test with non-contiguous crop
+\t>>> array_sparse = np.zeros((100, 100, 3), dtype=np.uint8)
+\t>>> array_sparse[10, 10] = 255
+\t>>> array_sparse[50, 50] = 255
+\t>>> array_sparse[90, 90] = 255
+\t>>> cropped_contiguous = auto_crop(array_sparse, contiguous=True, return_type=np.ndarray)
+\t>>> cropped_contiguous.shape  # Bounding box from (10,10) to (90,90)
+\t(81, 81, 3)
+\t>>> cropped_non_contiguous = auto_crop(array_sparse, contiguous=False, return_type=np.ndarray)
+\t>>> cropped_non_contiguous.shape  # Only rows/cols 10, 50, 90
+\t(3, 3, 3)
+
+\t>>> # Test with 3D crop on depth dimension
+\t>>> array_3d = np.zeros((50, 50, 10), dtype=np.uint8)
+\t>>> array_3d[10:40, 10:40, 2:8] = 255  # Content only in depth slices 2-7
+\t>>> cropped_3d = auto_crop(array_3d, contiguous=True, return_type=np.ndarray)
+\t>>> cropped_3d.shape  # Should crop all 3 dimensions
+\t(30, 30, 6)
+\t'''
+def numpy_to_gif(path: str, array: NDArray[np.integer | np.floating | np.bool_], duration: int = 100, loop: int = 0, mkdir: bool = True, **kwargs: Any) -> None:
+    ''' Generate a \'.gif\' file from a numpy array for 3D/4D visualization.
+
+\tArgs:
+\t\tpath     (str):     Path to the output .gif file.
+\t\tarray    (NDArray): Numpy array to be dumped (must be 3D or 4D).
+\t\t\t3D: (depth, height, width) - e.g. (64, 1024, 1024)
+\t\t\t4D: (depth, height, width, channels) - e.g. (50, 64, 1024, 3)
+\t\tduration (int):     Duration between frames in milliseconds.
+\t\tloop     (int):     Number of loops (0 = infinite).
+\t\tmkdir    (bool):    Create the directory if it does not exist.
+\t\t**kwargs (Any):     Additional keyword arguments for PIL.Image.save().
+
+\tExamples:
+
+\t\t.. code-block:: python
+
+\t\t\t> # 3D array example
+\t\t\t> array = np.random.randint(0, 256, (10, 100, 100), dtype=np.uint8)
+\t\t\t> numpy_to_gif("output_10_frames_100x100.gif", array, duration=200, loop=0)
+
+\t\t\t> # 4D array example (batch of 3D images)
+\t\t\t> array_4d = np.random.randint(0, 256, (5, 10, 100, 3), dtype=np.uint8)
+\t\t\t> numpy_to_gif("output_50_frames_100x100.gif", array_4d, duration=200)
+
+\t\t\t> total_duration = 1000  # 1 second
+\t\t\t> numpy_to_gif("output_1s.gif", array, duration=total_duration // len(array))
+\t'''
+def numpy_to_obj(path: str, array: NDArray[np.integer | np.floating | np.bool_], threshold: float = 0.5, step_size: int = 1, pad_array: bool = True, verbose: int = 0) -> None:
+    ''' Generate a \'.obj\' file from a numpy array for 3D visualization using marching cubes.
+
+\tArgs:
+\t\tpath      (str):     Path to the output .obj file.
+\t\tarray     (NDArray): Numpy array to be dumped (must be 3D).
+\t\tthreshold (float):   Threshold level for marching cubes (0.5 for binary data).
+\t\tstep_size (int):     Step size for marching cubes (higher = simpler mesh, faster generation).
+\t\tpad_array (bool):    If True, pad array with zeros to ensure closed volumes for border cells.
+\t\tverbose   (int):     Verbosity level (0 = no output, 1 = some output, 2 = full output).
+
+\tExamples:
+
+\t\t.. code-block:: python
+
+\t\t\t> array = np.random.rand(64, 64, 64) > 0.5  # Binary volume
+\t\t\t> numpy_to_obj("output_mesh.obj", array, threshold=0.5, step_size=2, pad_array=True, verbose=1)
+
+\t\t\t> array = my_3d_data  # Some 3D numpy array (e.g. human lung scan)
+\t\t\t> numpy_to_obj("output_mesh.obj", array, threshold=0.3)
+\t'''

stouputils/installer/__init__.py

@@ -0,0 +1,18 @@
+""" Installer module for stouputils.
+
+Provides functions for platform-agnostic installation tasks by dispatching
+to platform-specific implementations (Windows, Linux/macOS).
+
+It handles getting installation paths, adding programs to the PATH environment variable,
+and installing programs from local zip files or URLs.
+"""
+# ruff: noqa: F403
+# ruff: noqa: F405
+
+# Imports
+from .common import *
+from .downloader import *
+from .linux import *
+from .main import *
+from .windows import *
+

stouputils/installer/__init__.pyi

@@ -0,0 +1,5 @@
+from .common import *
+from .downloader import *
+from .linux import *
+from .main import *
+from .windows import *

stouputils/installer/common.py

@@ -0,0 +1,67 @@
+""" Common functions used by the Linux and Windows installers modules. """
+# Imports
+from typing import Literal
+
+from ..print import warning
+
+
+# Functions
+def prompt_for_path(prompt_message: str, default_path: str) -> str:
+	""" Prompt the user to override a default path.
+
+	Args:
+		prompt_message (str): The message to display to the user.
+		default_path   (str): The default path to suggest.
+
+	Returns:
+		str: The path entered by the user, or the default path if they pressed Enter.
+	"""
+	warning(f"{prompt_message}\nPress Enter to use this path, or type a new path to override it: ")
+	return input() or default_path
+
+
+def ask_install_type(ask_global: int, default_local_path: str, default_global_path: str | None) -> Literal["g", "l"]:
+	""" Determine the installation type (global 'g' or local 'l') based on user input.
+
+	Args:
+		ask_global          (int):           0 = ask, 1 = force global, 2 = force local.
+		default_local_path  (str):           The default local path.
+		default_global_path (str | None):    The default global path (if applicable).
+
+	Returns:
+		Literal["g", "l"]: 'g' for global install, 'l' for local install.
+
+	Examples:
+		.. code-block:: python
+
+			> # Ask the user while providing default paths
+			> install_choice: str = ask_install_type(0, f"{os.getcwd()}/MyProgram", "C:\\Program Files\\MyProgram")
+			g
+
+			> # Don't ask, force global
+			> install_choice: str = ask_install_type(1, ...)
+			g
+
+			> # Don't ask, force local
+			> install_choice: str = ask_install_type(2, ...)
+			l
+	"""
+	install_choice: str = ""
+	if ask_global == 0:
+		if default_global_path:
+			global_prompt: str = f"(Globally would target '{default_global_path}')"
+		else:
+			global_prompt: str = "(Global install not well-defined)"
+		warning(
+			f"Install globally (requires admin/sudo, suggests adding to PATH) or locally? (G/l):\n"
+			f"{global_prompt}, locally would be '{default_local_path}')"
+		)
+		install_choice = input().lower()
+	elif ask_global == 1:
+		install_choice = "g"
+	elif ask_global == 2:
+		install_choice = "l"
+
+	# Default to global unless user explicitly chooses local ('l')
+	return 'l' if install_choice == 'l' else 'g'
+

stouputils/installer/common.pyi

@@ -0,0 +1,39 @@
+from ..print import warning as warning
+from typing import Literal
+
+def prompt_for_path(prompt_message: str, default_path: str) -> str:
+    """ Prompt the user to override a default path.
+
+\tArgs:
+\t\tprompt_message (str): The message to display to the user.
+\t\tdefault_path   (str): The default path to suggest.
+
+\tReturns:
+\t\tstr: The path entered by the user, or the default path if they pressed Enter.
+\t"""
+def ask_install_type(ask_global: int, default_local_path: str, default_global_path: str | None) -> Literal['g', 'l']:
+    ''' Determine the installation type (global \'g\' or local \'l\') based on user input.
+
+\tArgs:
+\t\task_global          (int):           0 = ask, 1 = force global, 2 = force local.
+\t\tdefault_local_path  (str):           The default local path.
+\t\tdefault_global_path (str | None):    The default global path (if applicable).
+
+\tReturns:
+\t\tLiteral["g", "l"]: \'g\' for global install, \'l\' for local install.
+
+\tExamples:
+\t\t.. code-block:: python
+
+\t\t\t> # Ask the user while providing default paths
+\t\t\t> install_choice: str = ask_install_type(0, f"{os.getcwd()}/MyProgram", "C:\\Program Files\\MyProgram")
+\t\t\tg
+
+\t\t\t> # Don\'t ask, force global
+\t\t\t> install_choice: str = ask_install_type(1, ...)
+\t\t\tg
+
+\t\t\t> # Don\'t ask, force local
+\t\t\t> install_choice: str = ask_install_type(2, ...)
+\t\t\tl
+\t'''

stouputils/installer/downloader.py

@@ -0,0 +1,101 @@
+""" Downloader module for the installer subpackage.
+
+Provides functions for downloading and installing programs from URLs.
+It handles platform-specific downloads, checking if programs are already installed,
+and setting up the downloaded programs for use.
+
+This module works with the main installer module to provide a complete installation
+solution for programs that need to be downloaded from the internet.
+"""
+# Imports
+import os
+import platform
+import subprocess
+import sys
+
+from ..print import info, warning
+from .main import install_program
+
+
+# Functions
+def download_executable(download_urls: dict[str, str], program_name: str, append_to_path: str = "") -> bool:
+	""" Ask the user if they want to download the program (ex: waifu2x-ncnn-vulkan).
+	If yes, try to download the program from the GitHub releases page.
+
+	Args:
+		download_urls  (dict[str, str]):  The URLs to download the program from.
+		program_name   (str):             The name of the program to download.
+
+	Returns:
+		bool: True if the program is now ready to use, False otherwise.
+	"""
+	# Ask the user if they want to download the upscaler
+	program_url: str = next(iter(download_urls.values())).split("/download/")[0]
+	warning(
+		f"Program executable not found, would you like to download it automatically from GitHub? (Y/n) :\n"
+		f"({program_url})"
+	)
+
+	# Handle the user's response
+	if input().lower() == "n":
+		info("User declined to download the upscaler.")
+		return False
+
+	# Get the platform
+	system: str = platform.system()
+	download_url: str = download_urls.get(system, "")
+	if not download_url:
+		warning(
+			f"Unsupported platform: {system}, please download the program manually from the following URL:\n"
+			f"  {program_url}"
+		)
+		return False
+
+	# Download the upscaler
+	if not install_program(download_url, program_name=program_name, append_to_path=append_to_path):
+		warning("Failed to download the upscaler, please download it manually from the following URL:")
+		print(f"  {download_url}")
+		return False
+
+	return True
+
+def check_executable(
+	executable: str,
+	executable_help_text: str,
+	download_urls: dict[str, str],
+	append_to_path: str = ""
+) -> None:
+	""" Check if the executable exists, optionally download it if it doesn't.
+
+	Args:
+		executable            (str):             The path to the executable.
+		executable_help_text  (str):             The help text to check for in the executable's output.
+		download_urls         (dict[str, str]):  The URLs to download the executable from.
+		append_to_path        (str):             The path to append to the executable's path.
+			(ex: "bin" if executables are in the bin folder)
+	"""
+	program_name: str = os.path.basename(executable)
+	try_download: bool = True
+
+	# Run the command, capture output, don't check exit code immediately
+	try:
+		result: subprocess.CompletedProcess[str] = subprocess.run(
+			[executable, "-h"],
+			capture_output=True,
+			text=True,  # Decode stdout/stderr as text
+			check=False # Don't raise exception on non-zero exit code
+		)
+
+		# If the command failed (no help text matching), try to download the upscaler
+		try_download: bool = executable_help_text.lower() not in result.stdout.lower()
+	except FileNotFoundError:
+		try_download: bool = True
+
+	# If the command failed, try to download the upscaler
+	if try_download:
+		if not download_executable(download_urls, program_name, append_to_path=append_to_path):
+			warning(f"'{program_name}' is required but not available. Exiting.")
+		else:
+			info(f"'{program_name}' downloaded successfully, please restart the script.")
+		sys.exit(1)
+

stouputils/installer/downloader.pyi

@@ -0,0 +1,24 @@
+from ..print import info as info, warning as warning
+from .main import install_program as install_program
+
+def download_executable(download_urls: dict[str, str], program_name: str, append_to_path: str = '') -> bool:
+    """ Ask the user if they want to download the program (ex: waifu2x-ncnn-vulkan).
+\tIf yes, try to download the program from the GitHub releases page.
+
+\tArgs:
+\t\tdownload_urls  (dict[str, str]):  The URLs to download the program from.
+\t\tprogram_name   (str):             The name of the program to download.
+
+\tReturns:
+\t\tbool: True if the program is now ready to use, False otherwise.
+\t"""
+def check_executable(executable: str, executable_help_text: str, download_urls: dict[str, str], append_to_path: str = '') -> None:
+    ''' Check if the executable exists, optionally download it if it doesn\'t.
+
+\tArgs:
+\t\texecutable            (str):             The path to the executable.
+\t\texecutable_help_text  (str):             The help text to check for in the executable\'s output.
+\t\tdownload_urls         (dict[str, str]):  The URLs to download the executable from.
+\t\tappend_to_path        (str):             The path to append to the executable\'s path.
+\t\t\t(ex: "bin" if executables are in the bin folder)
+\t'''

stouputils/installer/linux.py

@@ -0,0 +1,144 @@
+""" Installer module for Linux/macOS specific functions.
+
+Provides Linux/macOS specific implementations for checking admin privileges,
+determining appropriate installation paths (global/local), and suggesting
+how to add directories to the system's PATH environment variable.
+"""
+# Imports
+import os
+
+from ..decorators import LogLevels, handle_error
+from ..io import clean_path
+from ..print import debug, info, warning
+from .common import ask_install_type, prompt_for_path
+
+
+# Functions
+@handle_error(message="Failed to suggest how to add to PATH (Linux)", error_log=LogLevels.WARNING_TRACEBACK)
+def add_to_path_linux(install_path: str) -> bool:
+	""" Suggest how to add install_path to PATH on Linux.
+
+	Checks the current shell and provides instructions for adding the path
+	to the appropriate configuration file (e.g., .bashrc, .zshrc, config.fish).
+
+	Args:
+		install_path (str): The path to add to the PATH environment variable.
+
+	Returns:
+		bool: True if instructions were provided, False otherwise (e.g., unknown shell).
+	"""
+	shell_config_files: dict[str, str] = {
+		"bash": "~/.bashrc",
+		"zsh": "~/.zshrc",
+		"fish": "~/.config/fish/config.fish"
+	}
+	current_shell: str = os.environ.get("SHELL", "").split('/')[-1]
+	config_file: str | None = shell_config_files.get(current_shell)
+
+	if config_file:
+		export_cmd: str = ""
+		if current_shell == "fish":
+			export_cmd = f"set -gx PATH $PATH {install_path}"
+		else:
+			export_cmd = f"export PATH=\"$PATH:{install_path}\"" # Escape quotes for print
+
+		debug(
+			f"To add the installation directory to your PATH, add the following line to your '{config_file}':\n"
+			f"  {export_cmd}\n"
+			f"Then restart your shell or run 'source {config_file}'."
+		)
+		return True
+	else:
+		warning(f"Could not determine your shell configuration file. Please add '{install_path}' to your PATH manually.")
+		return False
+
+
+def check_admin_linux() -> bool:
+	""" Check if the script is running with root privileges on Linux/macOS.
+
+	Returns:
+		bool: True if the effective user ID is 0 (root), False otherwise.
+	"""
+	try:
+		return os.geteuid() == 0 # type: ignore
+	except AttributeError as e:
+		# os.geteuid() is not available on all platforms (e.g., Windows)
+		# This function should ideally only be called on Linux/macOS.
+		warning(f"Could not determine user privileges on this platform: {e}")
+		return False
+	except Exception as e:
+		warning(f"Error checking admin privileges: {e}")
+		return False
+
+
+@handle_error(message="Failed to get installation path (Linux)", error_log=LogLevels.ERROR_TRACEBACK)
+def get_install_path_linux(
+	program_name: str,
+	ask_global: int = 0,
+	add_path: bool = True,
+	append_to_path: str = "",
+	default_global: str = "/usr/local/bin",
+	) -> str:
+	""" Get the installation path for the program on Linux/macOS.
+
+	Args:
+		program_name   (str):   The name of the program to install.
+		ask_global     (int):   0 = ask for anything, 1 = install globally, 2 = install locally
+		add_path       (bool):  Whether to add the program to the PATH environment variable. (Only if installed globally)
+		append_to_path (str):   String to append to the installation path when adding to PATH.
+			(ex: "bin" if executables are in the bin folder)
+		default_global (str):   The default global installation path.
+			(Default is "/usr/local/bin" which is the most common location for executables on Linux/macOS,
+			could be "/opt" or any other directory)
+
+	Returns:
+		str: The chosen installation path, or an empty string if installation is cancelled.
+	"""
+	# Default paths
+	default_local_path: str = clean_path(os.path.join(os.getcwd(), program_name))
+
+	# Common global locations: /usr/local/bin for executables, /opt/ for self-contained apps
+	# We assume 'program_name' might be an executable or a directory, /usr/local/ is safer
+	default_global_path: str = clean_path(f"{default_global}/{program_name}") # Or potentially /opt/{program_name}
+
+	# Ask user for installation type (global/local)
+	install_type: str = ask_install_type(ask_global, default_local_path, default_global_path)
+
+	# Handle global installation choice
+	if install_type == 'g':
+		if not check_admin_linux():
+			warning(
+				f"Global installation typically requires sudo privileges to write to "
+				f"'{os.path.dirname(default_global_path)}'.\n"
+				f"You may need to re-run the script with 'sudo'.\n"
+				f"Install locally instead to '{default_local_path}'? (Y/n): "
+			)
+			if input().lower() == 'n':
+				info("Installation cancelled.")
+				return ""
+			else:
+				# Fallback to local path if user agrees
+				return prompt_for_path(
+					f"Falling back to local installation path: {default_local_path}.",
+					default_local_path
+				)
+		else:
+			# User is admin or proceeding with global install anyway
+			install_path: str = prompt_for_path(
+				f"Default global installation path is {default_global_path}.",
+				default_global_path
+			)
+			if add_path:
+				# Suggest adding the *directory* containing the program to PATH,
+				# or the path itself if it seems like a directory install
+				path_to_add: str = os.path.dirname(install_path) if os.path.isfile(install_path) else install_path
+				add_to_path_linux(os.path.join(path_to_add, append_to_path))
+			return install_path
+
+	# Handle local installation choice
+	else: # install_type == 'l'
+		return prompt_for_path(
+			f"Default local installation path is {default_local_path}.",
+			default_local_path
+		)
+

stouputils/installer/linux.pyi

@@ -0,0 +1,39 @@
+from ..decorators import LogLevels as LogLevels, handle_error as handle_error
+from ..io import clean_path as clean_path
+from ..print import debug as debug, info as info, warning as warning
+from .common import ask_install_type as ask_install_type, prompt_for_path as prompt_for_path
+
+def add_to_path_linux(install_path: str) -> bool:
+    """ Suggest how to add install_path to PATH on Linux.
+
+\tChecks the current shell and provides instructions for adding the path
+\tto the appropriate configuration file (e.g., .bashrc, .zshrc, config.fish).
+
+\tArgs:
+\t\tinstall_path (str): The path to add to the PATH environment variable.
+
+\tReturns:
+\t\tbool: True if instructions were provided, False otherwise (e.g., unknown shell).
+\t"""
+def check_admin_linux() -> bool:
+    """ Check if the script is running with root privileges on Linux/macOS.
+
+\tReturns:
+\t\tbool: True if the effective user ID is 0 (root), False otherwise.
+\t"""
+def get_install_path_linux(program_name: str, ask_global: int = 0, add_path: bool = True, append_to_path: str = '', default_global: str = '/usr/local/bin') -> str:
+    ''' Get the installation path for the program on Linux/macOS.
+
+\tArgs:
+\t\tprogram_name   (str):   The name of the program to install.
+\t\task_global     (int):   0 = ask for anything, 1 = install globally, 2 = install locally
+\t\tadd_path       (bool):  Whether to add the program to the PATH environment variable. (Only if installed globally)
+\t\tappend_to_path (str):   String to append to the installation path when adding to PATH.
+\t\t\t(ex: "bin" if executables are in the bin folder)
+\t\tdefault_global (str):   The default global installation path.
+\t\t\t(Default is "/usr/local/bin" which is the most common location for executables on Linux/macOS,
+\t\t\tcould be "/opt" or any other directory)
+
+\tReturns:
+\t\tstr: The chosen installation path, or an empty string if installation is cancelled.
+\t'''