stouputils 1.14.0__py3-none-any.whl → 1.14.2__py3-none-any.whl

stouputils/installer/windows.py

@@ -1,136 +1,136 @@
-""" Installer module for Windows specific functions.
-
-Provides Windows specific implementations for checking administrator privileges,
-determining appropriate installation paths (global/local), and modifying
-the user'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 add to PATH (Windows)", error_log=LogLevels.WARNING_TRACEBACK)
-def add_to_path_windows(install_path: str) -> bool | None:
-	""" Add install_path to the User PATH environment variable on Windows.
-
-	Args:
-		install_path (str): The path to add to the User PATH environment variable.
-
-	Returns:
-		bool | None: True if the path was added to the User PATH environment variable, None otherwise.
-	"""
-	# Convert install_path to a Windows path if it's not already
-	install_path = install_path.replace("/", "\\")
-	os.makedirs(install_path, exist_ok=True)
-
-	# Get current user PATH
-	import winreg
-	with winreg.OpenKey(winreg.HKEY_CURRENT_USER, "Environment", 0, winreg.KEY_READ | winreg.KEY_WRITE) as key:
-
-		# Get the number of values in the registry key
-		num_values = winreg.QueryInfoKey(key)[1]
-
-		# Find the index of the 'Path' value
-		path_index = -1
-		for i in range(num_values):
-			if winreg.EnumValue(key, i)[0] == 'Path':
-				path_index = i
-				break
-
-		# Get the current path value
-		current_path: str = winreg.EnumValue(key, path_index)[1]
-
-		# Check if path is already present
-		if install_path not in current_path.split(';'):
-			new_path: str = f"{current_path};{install_path}"
-			winreg.SetValueEx(key, "Path", 0, winreg.REG_EXPAND_SZ, new_path)
-			debug(f"Added '{install_path}' to user PATH. Please restart your terminal for changes to take effect.")
-		else:
-			debug(f"'{install_path}' is already in user PATH.")
-	return True
-
-
-def check_admin_windows() -> bool:
-	""" Check if the script is running with administrator privileges on Windows. """
-	try:
-		import ctypes
-		return ctypes.windll.shell32.IsUserAnAdmin() != 0
-	except Exception:
-		return False
-
-
-@handle_error(message="Failed to get installation path (Windows)", error_log=LogLevels.ERROR_TRACEBACK)
-def get_install_path_windows(
-	program_name: str,
-	ask_global: int = 0,
-	add_path: bool = True,
-	append_to_path: str = "",
-	default_global: str = os.environ.get("ProgramFiles", "C:\\Program Files")
-) -> str:
-	""" Get the installation path for the program
-
-	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 "C:\\Program Files" which is the most common location for executables on Windows)
-
-	Returns:
-		str: The installation path.
-	"""
-	# Default path is located in the current working directory
-	default_local_path: str = clean_path(os.path.join(os.getcwd(), program_name))
-
-	# Define default global path (used in prompt even if not chosen initially)
-	default_global_path: str = clean_path(os.path.join(default_global, program_name))
-
-	# Ask user for installation type (global/local)
-	install_type: str = ask_install_type(ask_global, default_local_path, default_global_path)
-
-	# If the user wants to install globally,
-	if install_type == 'g':
-
-		# Check if the user has admin privileges,
-		if not check_admin_windows():
-
-			# If the user doesn't have admin privileges, fallback to local
-			warning(
-				f"Global installation requires administrator privileges. Please re-run as administrator.\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
-				)
-
-		# If the user has admin privileges,
-		else:
-			# Ask it user wants to override the default global install path
-			install_path: str = prompt_for_path(
-				f"Default global installation path is {default_global_path}.",
-				default_global_path
-			)
-			if add_path:
-				add_to_path_windows(os.path.join(install_path, append_to_path))
-			return install_path
-
-	# Local install
-	else: # install_type == 'l'
-		return prompt_for_path(
-			f"Default local installation path is {default_local_path}.",
-			default_local_path
-		)
-
+""" Installer module for Windows specific functions.
+
+Provides Windows specific implementations for checking administrator privileges,
+determining appropriate installation paths (global/local), and modifying
+the user'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 add to PATH (Windows)", error_log=LogLevels.WARNING_TRACEBACK)
+def add_to_path_windows(install_path: str) -> bool | None:
+	""" Add install_path to the User PATH environment variable on Windows.
+
+	Args:
+		install_path (str): The path to add to the User PATH environment variable.
+
+	Returns:
+		bool | None: True if the path was added to the User PATH environment variable, None otherwise.
+	"""
+	# Convert install_path to a Windows path if it's not already
+	install_path = install_path.replace("/", "\\")
+	os.makedirs(install_path, exist_ok=True)
+
+	# Get current user PATH
+	import winreg
+	with winreg.OpenKey(winreg.HKEY_CURRENT_USER, "Environment", 0, winreg.KEY_READ | winreg.KEY_WRITE) as key:
+
+		# Get the number of values in the registry key
+		num_values = winreg.QueryInfoKey(key)[1]
+
+		# Find the index of the 'Path' value
+		path_index = -1
+		for i in range(num_values):
+			if winreg.EnumValue(key, i)[0] == 'Path':
+				path_index = i
+				break
+
+		# Get the current path value
+		current_path: str = winreg.EnumValue(key, path_index)[1]
+
+		# Check if path is already present
+		if install_path not in current_path.split(';'):
+			new_path: str = f"{current_path};{install_path}"
+			winreg.SetValueEx(key, "Path", 0, winreg.REG_EXPAND_SZ, new_path)
+			debug(f"Added '{install_path}' to user PATH. Please restart your terminal for changes to take effect.")
+		else:
+			debug(f"'{install_path}' is already in user PATH.")
+	return True
+
+
+def check_admin_windows() -> bool:
+	""" Check if the script is running with administrator privileges on Windows. """
+	try:
+		import ctypes
+		return ctypes.windll.shell32.IsUserAnAdmin() != 0
+	except Exception:
+		return False
+
+
+@handle_error(message="Failed to get installation path (Windows)", error_log=LogLevels.ERROR_TRACEBACK)
+def get_install_path_windows(
+	program_name: str,
+	ask_global: int = 0,
+	add_path: bool = True,
+	append_to_path: str = "",
+	default_global: str = os.environ.get("ProgramFiles", "C:\\Program Files")
+) -> str:
+	""" Get the installation path for the program
+
+	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 "C:\\Program Files" which is the most common location for executables on Windows)
+
+	Returns:
+		str: The installation path.
+	"""
+	# Default path is located in the current working directory
+	default_local_path: str = clean_path(os.path.join(os.getcwd(), program_name))
+
+	# Define default global path (used in prompt even if not chosen initially)
+	default_global_path: str = clean_path(os.path.join(default_global, program_name))
+
+	# Ask user for installation type (global/local)
+	install_type: str = ask_install_type(ask_global, default_local_path, default_global_path)
+
+	# If the user wants to install globally,
+	if install_type == 'g':
+
+		# Check if the user has admin privileges,
+		if not check_admin_windows():
+
+			# If the user doesn't have admin privileges, fallback to local
+			warning(
+				f"Global installation requires administrator privileges. Please re-run as administrator.\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
+				)
+
+		# If the user has admin privileges,
+		else:
+			# Ask it user wants to override the default global install path
+			install_path: str = prompt_for_path(
+				f"Default global installation path is {default_global_path}.",
+				default_global_path
+			)
+			if add_path:
+				add_to_path_windows(os.path.join(install_path, append_to_path))
+			return install_path
+
+	# Local install
+	else: # install_type == 'l'
+		return prompt_for_path(
+			f"Default local installation path is {default_local_path}.",
+			default_local_path
+		)
+

stouputils/installer/windows.pyi

@@ -0,0 +1,31 @@
+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_windows(install_path: str) -> bool | None:
+    """ Add install_path to the User PATH environment variable on Windows.
+
+\tArgs:
+\t\tinstall_path (str): The path to add to the User PATH environment variable.
+
+\tReturns:
+\t\tbool | None: True if the path was added to the User PATH environment variable, None otherwise.
+\t"""
+def check_admin_windows() -> bool:
+    """ Check if the script is running with administrator privileges on Windows. """
+def get_install_path_windows(program_name: str, ask_global: int = 0, add_path: bool = True, append_to_path: str = '', default_global: str = ...) -> str:
+    ''' Get the installation path for the program
+
+\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 "C:\\Program Files" which is the most common location for executables on Windows)
+
+\tReturns:
+\t\tstr: The installation path.
+\t'''

stouputils/io.pyi

@@ -0,0 +1,213 @@
+from typing import Any, IO
+
+def get_root_path(relative_path: str, go_up: int = 0) -> str:
+    """ Get the absolute path of the directory.
+\tUsually used to get the root path of the project using the __file__ variable.
+
+\tArgs:
+\t\trelative_path   (str): The path to get the absolute directory path from
+\t\tgo_up           (int): Number of parent directories to go up (default: 0)
+\tReturns:
+\t\tstr: The absolute path of the directory
+
+\tExamples:
+
+\t\t.. code-block:: python
+
+\t\t\t> get_root_path(__file__)
+\t\t\t'C:/Users/Alexandre-PC/AppData/Local/Programs/Python/Python310/lib/site-packages/stouputils'
+
+\t\t\t> get_root_path(__file__, 3)
+\t\t\t'C:/Users/Alexandre-PC/AppData/Local/Programs/Python/Python310'
+\t"""
+def relative_path(file_path: str, relative_to: str = '') -> str:
+    ''' Get the relative path of a file relative to a given directory.
+
+\tArgs:
+\t\tfile_path     (str): The path to get the relative path from
+\t\trelative_to   (str): The path to get the relative path to (default: current working directory -> os.getcwd())
+\tReturns:
+\t\tstr: The relative path of the file
+\tExamples:
+
+\t\t>>> relative_path("D:/some/random/path/stouputils/io.py", "D:\\\\some")
+\t\t\'random/path/stouputils/io.py\'
+\t\t>>> relative_path("D:/some/random/path/stouputils/io.py", "D:\\\\some\\\\")
+\t\t\'random/path/stouputils/io.py\'
+\t'''
+def json_dump(data: Any, file: IO[Any] | str | None = None, max_level: int | None = 2, indent: str | int = '\t', suffix: str = '\n', ensure_ascii: bool = False) -> str:
+    ''' Writes the provided data to a JSON file with a specified indentation depth.
+\tFor instance, setting max_level to 2 will limit the indentation to 2 levels.
+
+\tArgs:
+\t\tdata\t\t(Any): \t\t\t\tThe data to dump (usually a dict or a list)
+\t\tfile\t\t(IO[Any] | str): \tThe file object or path to dump the data to
+\t\tmax_level\t(int | None):\t\tThe depth of indentation to stop at (-1 for infinite), None will default to 2
+\t\tindent\t\t(str | int):\t\tThe indentation character (default: \'\\t\')
+\t\tsuffix\t\t(str):\t\t\t\tThe suffix to add at the end of the string (default: \'\\n\')
+\t\tensure_ascii (bool):\t\t\tWhether to escape non-ASCII characters (default: False)
+\tReturns:
+\t\tstr: The content of the file in every case
+
+\t>>> json_dump({"a": [[1,2,3]], "b": 2}, max_level = 0)
+\t\'{"a": [[1,2,3]],"b": 2}\\n\'
+\t>>> json_dump({"a": [[1,2,3]], "b": 2}, max_level = 1)
+\t\'{\\n\\t"a": [[1,2,3]],\\n\\t"b": 2\\n}\\n\'
+\t>>> json_dump({"a": [[1,2,3]], "b": 2}, max_level = 2)
+\t\'{\\n\\t"a": [\\n\\t\\t[1,2,3]\\n\\t],\\n\\t"b": 2\\n}\\n\'
+\t>>> json_dump({"a": [[1,2,3]], "b": 2}, max_level = 3)
+\t\'{\\n\\t"a": [\\n\\t\\t[\\n\\t\\t\\t1,\\n\\t\\t\\t2,\\n\\t\\t\\t3\\n\\t\\t]\\n\\t],\\n\\t"b": 2\\n}\\n\'
+\t>>> json_dump({"éà": "üñ"}, ensure_ascii = True, max_level = 0)
+\t\'{"\\\\u00e9\\\\u00e0": "\\\\u00fc\\\\u00f1"}\\n\'
+\t>>> json_dump({"éà": "üñ"}, ensure_ascii = False, max_level = 0)
+\t\'{"éà": "üñ"}\\n\'
+\t'''
+def json_load(file_path: str) -> Any:
+    """ Load a JSON file from the given path
+
+\tArgs:
+\t\tfile_path (str): The path to the JSON file
+\tReturns:
+\t\tAny: The content of the JSON file
+\t"""
+def csv_dump(data: Any, file: IO[Any] | str | None = None, delimiter: str = ',', has_header: bool = True, index: bool = False, *args: Any, **kwargs: Any) -> str:
+    ''' Writes data to a CSV file with customizable options and returns the CSV content as a string.
+
+\tArgs:
+\t\tdata\t\t(list[list[Any]] | list[dict[str, Any]] | pd.DataFrame | pl.DataFrame):
+\t\t\t\t\t\tThe data to write, either a list of lists, list of dicts, pandas DataFrame, or Polars DataFrame
+\t\tfile\t\t(IO[Any] | str): The file object or path to dump the data to
+\t\tdelimiter\t(str): The delimiter to use (default: \',\')
+\t\thas_header\t(bool): Whether to include headers (default: True, applies to dict and DataFrame data)
+\t\tindex\t\t(bool): Whether to include the index (default: False, only applies to pandas DataFrame)
+\t\t*args\t\t(Any): Additional positional arguments to pass to the underlying CSV writer or DataFrame method
+\t\t**kwargs\t(Any): Additional keyword arguments to pass to the underlying CSV writer or DataFrame method
+\tReturns:
+\t\tstr: The CSV content as a string
+
+\tExamples:
+
+\t\t>>> csv_dump([["a", "b", "c"], [1, 2, 3], [4, 5, 6]])
+\t\t\'a,b,c\\r\\n1,2,3\\r\\n4,5,6\\r\\n\'
+
+\t\t>>> csv_dump([{"name": "Alice", "age": 30}, {"name": "Bob", "age": 25}])
+\t\t\'name,age\\r\\nAlice,30\\r\\nBob,25\\r\\n\'
+\t'''
+def csv_load(file_path: str, delimiter: str = ',', has_header: bool = True, as_dict: bool = False, as_dataframe: bool = False, use_polars: bool = False, *args: Any, **kwargs: Any) -> Any:
+    ''' Load a CSV file from the given path
+
+\tArgs:
+\t\tfile_path (str): The path to the CSV file
+\t\tdelimiter (str): The delimiter used in the CSV (default: \',\')
+\t\thas_header (bool): Whether the CSV has a header row (default: True)
+\t\tas_dict (bool): Whether to return data as list of dicts (default: False)
+\t\tas_dataframe (bool): Whether to return data as a DataFrame (default: False)
+\t\tuse_polars (bool): Whether to use Polars instead of pandas for DataFrame (default: False, requires polars)
+\t\t*args: Additional positional arguments to pass to the underlying CSV reader or DataFrame method
+\t\t**kwargs: Additional keyword arguments to pass to the underlying CSV reader or DataFrame method
+\tReturns:
+\t\tlist[list[str]] | list[dict[str, str]] | pd.DataFrame | pl.DataFrame: The content of the CSV file
+
+\tExamples:
+
+\t\t.. code-block:: python
+
+\t\t\t> Assuming "test.csv" contains: a,b,c\\n1,2,3\\n4,5,6
+\t\t\t> csv_load("test.csv")
+\t\t\t[[\'1\', \'2\', \'3\'], [\'4\', \'5\', \'6\']]
+
+\t\t\t> csv_load("test.csv", as_dict=True)
+\t\t\t[{\'a\': \'1\', \'b\': \'2\', \'c\': \'3\'}, {\'a\': \'4\', \'b\': \'5\', \'c\': \'6\'}]
+
+\t\t\t> csv_load("test.csv", as_dataframe=True)
+\t\t\t   a  b  c
+\t\t\t0  1  2  3
+\t\t\t1  4  5  6
+
+\t\t.. code-block:: console
+
+\t\t\t> csv_load("test.csv", as_dataframe=True, use_polars=True)
+\t\t\tshape: (2, 3)
+\t\t\t┌─────┬─────┬─────┐
+\t\t\t│ a   ┆ b   ┆ c   │
+\t\t\t│ --- ┆ --- ┆ --- │
+\t\t\t│ i64 ┆ i64 ┆ i64 │
+\t\t\t╞═════╪═════╪═════╡
+\t\t\t│ 1   ┆ 2   ┆ 3   │
+\t\t\t│ 4   ┆ 5   ┆ 6   │
+\t\t\t└─────┴─────┴─────┘
+\t'''
+def super_copy(src: str, dst: str, create_dir: bool = True, symlink: bool = False) -> str:
+    """ Copy a file (or a folder) from the source to the destination
+
+\tArgs:
+\t\tsrc         (str):  The source path
+\t\tdst         (str):  The destination path
+\t\tcreate_dir  (bool): Whether to create the directory if it doesn't exist (default: True)
+\t\tsymlink     (bool): Whether to create a symlink instead of copying (Linux only, default: True)
+\tReturns:
+\t\tstr: The destination path
+\t"""
+def super_open(file_path: str, mode: str, encoding: str = 'utf-8') -> IO[Any]:
+    ''' Open a file with the given mode, creating the directory if it doesn\'t exist (only if writing)
+
+\tArgs:
+\t\tfile_path\t(str): The path to the file
+\t\tmode\t\t(str): The mode to open the file with, ex: "w", "r", "a", "wb", "rb", "ab"
+\t\tencoding\t(str): The encoding to use when opening the file (default: "utf-8")
+\tReturns:
+\t\topen: The file object, ready to be used
+\t'''
+def read_file(file_path: str, encoding: str = 'utf-8') -> str:
+    ''' Read the content of a file and return it as a string
+
+\tArgs:
+\t\tfile_path (str): The path to the file
+\t\tencoding  (str): The encoding to use when opening the file (default: "utf-8")
+\tReturns:
+\t\tstr: The content of the file
+\t'''
+def replace_tilde(path: str) -> str:
+    ''' Replace the "~" by the user\'s home directory
+
+\tArgs:
+\t\tpath (str): The path to replace the "~" by the user\'s home directory
+\tReturns:
+\t\tstr: The path with the "~" replaced by the user\'s home directory
+\tExamples:
+
+\t\t.. code-block:: python
+
+\t\t\t> replace_tilde("~/Documents/test.txt")
+\t\t\t\'/home/user/Documents/test.txt\'
+\t'''
+def clean_path(file_path: str, trailing_slash: bool = True) -> str:
+    ''' Clean the path by replacing backslashes with forward slashes and simplifying the path
+
+\tArgs:
+\t\tfile_path (str): The path to clean
+\t\ttrailing_slash (bool): Whether to keep the trailing slash, ex: "test/" -> "test/"
+\tReturns:
+\t\tstr: The cleaned path
+\tExamples:
+\t\t>>> clean_path("C:\\\\Users\\\\Stoupy\\\\Documents\\\\test.txt")
+\t\t\'C:/Users/Stoupy/Documents/test.txt\'
+
+\t\t>>> clean_path("Some Folder////")
+\t\t\'Some Folder/\'
+
+\t\t>>> clean_path("test/uwu/1/../../")
+\t\t\'test/\'
+
+\t\t>>> clean_path("some/./folder/../")
+\t\t\'some/\'
+
+\t\t>>> clean_path("folder1/folder2/../../folder3")
+\t\t\'folder3\'
+
+\t\t>>> clean_path("./test/./folder/")
+\t\t\'test/folder/\'
+
+\t\t>>> clean_path("C:/folder1\\\\folder2")
+\t\t\'C:/folder1/folder2\'
+\t'''

stouputils/parallel.py

@@ -335,8 +335,8 @@ def run_in_subprocess[R](
 	import multiprocessing as mp
 	from multiprocessing import Queue
 
-	# Create a queue to get the result from the subprocess
-	result_queue: Queue[R | Exception] = Queue()
+	# Create a queue to get the result from the subprocess (only if we need to wait)
+	result_queue: Queue[R | Exception] | None = None if no_join else Queue()
 
 	# Create and start the subprocess using the module-level wrapper
 	process: mp.Process = mp.Process(
@@ -345,8 +345,8 @@ def run_in_subprocess[R](
 	)
 	process.start()
 
-	# Join with timeout to prevent indefinite hanging
-	if no_join:
+	# Detach process if no_join (fire-and-forget)
+	if result_queue is None:
 		return None  # type: ignore
 	process.join(timeout=timeout)
 
@@ -394,16 +394,18 @@ def _subprocess_wrapper[R](
 	Must be at module level to be pickable on Windows (spawn context).
 
 	Args:
-		result_queue (multiprocessing.Queue):  Queue to store the result or exception.
-		func         (Callable):               The target function to execute.
-		args         (tuple):                  Positional arguments for the function.
-		kwargs       (dict):                   Keyword arguments for the function.
+		result_queue (multiprocessing.Queue | None):  Queue to store the result or exception (None if detached).
+		func         (Callable):                            The target function to execute.
+		args         (tuple):                               Positional arguments for the function.
+		kwargs       (dict):                                Keyword arguments for the function.
 	"""
 	try:
 		result: R = func(*args, **kwargs)
-		result_queue.put(result)
+		if result_queue is not None:
+			result_queue.put(result)
 	except Exception as e:
-		result_queue.put(e)
+		if result_queue is not None:
+			result_queue.put(e)
 
 # "Private" function to use starmap
 def _starmap[T, R](args: tuple[Callable[[T], R], list[T]]) -> R: