stouputils 1.12.1__py3-none-any.whl → 1.13.0__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/print.py

@@ -432,64 +432,6 @@ def current_time() -> str:
 		return time.strftime("%H:%M:%S")
 
 
-def show_version(main_package: str = "stouputils", primary_color: str = CYAN, secondary_color: str = GREEN) -> None:
-	""" Print the version of the main package and its dependencies.
-
-	Used by the "stouputils --version" command.
-
-	Args:
-		main_package			(str):			Name of the main package to show version for
-		primary_color			(str):			Color to use for the primary package name
-		secondary_color			(str):			Color to use for the secondary package names
-	"""
-	# Imports
-	from importlib.metadata import requires, version
-	def ver(package_name: str) -> str:
-		try:
-			return version(package_name)
-		except Exception:
-			return ""
-
-	# Get dependencies dynamically and extract package names from requirements (e.g., "tqdm>=4.0.0" -> "tqdm")
-	deps: list[str] = requires(main_package) or []
-	dep_names: list[str] = sorted([
-		dep
-			.split(">")[0]
-			.split("<")[0]
-			.split("=")[0]
-			.split("[")[0]
-		for dep in deps
-	])
-	all_deps: list[tuple[str, str]] = [
-		(x, ver(x).split("version: ")[-1])
-		for x in (main_package, *dep_names)
-	]
-	all_deps = [pair for pair in all_deps if pair[1]]  # Filter out packages with no version found
-	longest_name_length: int = max(len(name) for name, _ in all_deps)
-	longest_version_length: int = max(len(ver) for _, ver in all_deps)
-
-	# Get Python version
-	python_version: str = f" Python {sys.version_info.major}.{sys.version_info.minor}.{sys.version_info.micro} "
-	minimum_separator_length: int = len(python_version) + 10	# Always at least 5 dashes on each side
-	separator_length: int = max(minimum_separator_length, longest_name_length + longest_version_length + 4)
-	python_text_length: int = len(python_version)
-	left_dashes: int = (separator_length - python_text_length) // 2
-	right_dashes: int = separator_length - python_text_length - left_dashes
-	separator_with_python: str = "─" * left_dashes + python_version + "─" * right_dashes
-	separator: str = "─" * separator_length
-
-	for pkg, v in all_deps:
-		pkg_spacing: str = " " * (longest_name_length - len(pkg))
-
-		# Highlight the main package with a different style
-		if pkg == main_package:
-			print(f"{primary_color}{separator_with_python}{RESET}")
-			print(f"{primary_color}{pkg}{pkg_spacing}  {secondary_color}v{v}{RESET}")
-			print(f"{primary_color}{separator}{RESET}")
-		else:
-			print(f"{primary_color}{pkg}{pkg_spacing}  {secondary_color}v{v}{RESET}")
-	return
-
 # Test the print functions
 if __name__ == "__main__":
 	info("Hello", "World")

stouputils/print.pyi

@@ -134,13 +134,3 @@ def is_same_print(*args: Any, **kwargs: Any) -> bool:
     """ Checks if the current print call is the same as the previous one. """
 def current_time() -> str:
     ''' Get the current time as "HH:MM:SS" if less than 24 hours since import, else "YYYY-MM-DD HH:MM:SS" '''
-def show_version(main_package: str = 'stouputils', primary_color: str = ..., secondary_color: str = ...) -> None:
-    ''' Print the version of the main package and its dependencies.
-
-\tUsed by the "stouputils --version" command.
-
-\tArgs:
-\t\tmain_package\t\t\t(str):\t\t\tName of the main package to show version for
-\t\tprimary_color\t\t\t(str):\t\t\tColor to use for the primary package name
-\t\tsecondary_color\t\t\t(str):\t\t\tColor to use for the secondary package names
-\t'''

stouputils/py.typed

@@ -1 +1 @@
-
+

stouputils/stouputils/__init__.pyi

@@ -0,0 +1,15 @@
+from ._deprecated import *
+from .all_doctests import *
+from .archive import *
+from .backup import *
+from .collections import *
+from .continuous_delivery import *
+from .ctx import *
+from .decorators import *
+from .image import *
+from .io import *
+from .parallel import *
+from .print import *
+from .version_pkg import *
+
+__version__: str

stouputils/stouputils/_deprecated.pyi

@@ -0,0 +1,12 @@
+from .decorators import LogLevels as LogLevels, deprecated as deprecated
+from .io import csv_dump as csv_dump, csv_load as csv_load, json_dump as json_dump, json_load as json_load
+from typing import Any
+
+def super_csv_dump(*args: Any, **kwargs: Any) -> Any:
+    ''' Deprecated function, use "csv_dump" instead. '''
+def super_csv_load(*args: Any, **kwargs: Any) -> Any:
+    ''' Deprecated function, use "csv_load" instead. '''
+def super_json_dump(*args: Any, **kwargs: Any) -> Any:
+    ''' Deprecated function, use "json_dump" instead. '''
+def super_json_load(*args: Any, **kwargs: Any) -> Any:
+    ''' Deprecated function, use "json_load" instead. '''

stouputils/stouputils/all_doctests.pyi

@@ -0,0 +1,46 @@
+from . import decorators as decorators
+from .decorators import measure_time as measure_time
+from .io import clean_path as clean_path, relative_path as relative_path
+from .print import error as error, info as info, progress as progress, warning as warning
+from doctest import TestResults as TestResults
+from types import ModuleType
+
+def launch_tests(root_dir: str, strict: bool = True) -> int:
+    ''' Main function to launch tests for all modules in the given directory.
+
+\tArgs:
+\t\troot_dir\t\t\t\t(str):\t\t\tRoot directory to search for modules
+\t\tstrict\t\t\t\t\t(bool):\t\t\tModify the force_raise_exception variable to True in the decorators module
+
+\tReturns:
+\t\tint: The number of failed tests
+
+\tExamples:
+\t\t>>> launch_tests("unknown_dir")
+\t\tTraceback (most recent call last):
+\t\t\t...
+\t\tValueError: No modules found in \'unknown_dir\'
+
+\t.. code-block:: python
+
+\t\t> if launch_tests("/path/to/source") > 0:
+\t\t\tsys.exit(1)
+\t\t[PROGRESS HH:MM:SS] Importing module \'module1\'\ttook 0.001s
+\t\t[PROGRESS HH:MM:SS] Importing module \'module2\'\ttook 0.002s
+\t\t[PROGRESS HH:MM:SS] Importing module \'module3\'\ttook 0.003s
+\t\t[PROGRESS HH:MM:SS] Importing module \'module4\'\ttook 0.004s
+\t\t[INFO HH:MM:SS] Testing 4 modules...
+\t\t[PROGRESS HH:MM:SS] Testing module \'module1\'\ttook 0.005s
+\t\t[PROGRESS HH:MM:SS] Testing module \'module2\'\ttook 0.006s
+\t\t[PROGRESS HH:MM:SS] Testing module \'module3\'\ttook 0.007s
+\t\t[PROGRESS HH:MM:SS] Testing module \'module4\'\ttook 0.008s
+\t'''
+def test_module_with_progress(module: ModuleType, separator: str) -> TestResults:
+    """ Test a module with testmod and measure the time taken with progress printing.
+
+\tArgs:
+\t\tmodule\t\t(ModuleType):\tModule to test
+\t\tseparator\t(str):\t\t\tSeparator string for alignment in output
+\tReturns:
+\t\tTestResults: The results of the tests
+\t"""

stouputils/stouputils/applications/__init__.pyi

@@ -0,0 +1,2 @@
+from .automatic_docs import *
+from .upscaler import *

stouputils/stouputils/applications/automatic_docs.pyi

@@ -0,0 +1,106 @@
+from ..continuous_delivery import version_to_float as version_to_float
+from ..decorators import LogLevels as LogLevels, handle_error as handle_error, simple_cache as simple_cache
+from ..io import clean_path as clean_path, json_dump as json_dump, super_open as super_open
+from ..print import info as info
+from collections.abc import Callable as Callable
+
+REQUIREMENTS: list[str]
+
+def check_dependencies(html_theme: str) -> None:
+    ''' Check for each requirement if it is installed.
+
+\tArgs:
+\t\thtml_theme (str): HTML theme to use for the documentation, to check if it is installed (e.g. "breeze", "pydata_sphinx_theme", "furo", etc.)
+\t'''
+def get_sphinx_conf_content(project: str, project_dir: str, author: str, current_version: str, copyright: str, html_logo: str, html_favicon: str, html_theme: str = 'breeze', github_user: str = '', github_repo: str = '', version_list: list[str] | None = None, skip_undocumented: bool = True) -> str:
+    """ Get the content of the Sphinx configuration file.
+
+\tArgs:
+\t\tproject           (str):              Name of the project
+\t\tproject_dir       (str):              Path to the project directory
+\t\tauthor            (str):              Author of the project
+\t\tcurrent_version   (str):              Current version
+\t\tcopyright         (str):              Copyright information
+\t\thtml_logo         (str):              URL to the logo
+\t\thtml_favicon      (str):              URL to the favicon
+\t\tgithub_user       (str):              GitHub username
+\t\tgithub_repo       (str):              GitHub repository name
+\t\tversion_list      (list[str] | None): List of versions. Defaults to None
+\t\tskip_undocumented (bool):             Whether to skip undocumented members. Defaults to True
+
+\tReturns:
+\t\tstr: Content of the Sphinx configuration file
+\t"""
+def get_versions_from_github(github_user: str, github_repo: str, recent_minor_versions: int = 2) -> list[str]:
+    """ Get list of versions from GitHub gh-pages branch.
+\tOnly shows detailed versions for the last N minor versions, and keeps only
+\tthe latest patch version for older minor versions.
+
+\tArgs:
+\t\tgithub_user             (str): GitHub username
+\t\tgithub_repo             (str): GitHub repository name
+\t\trecent_minor_versions   (int): Number of recent minor versions to show all patches for (-1 for all).
+
+\tReturns:
+\t\tlist[str]: List of versions, with 'latest' as first element
+\t"""
+def markdown_to_rst(markdown_content: str) -> str:
+    """ Convert markdown content to RST format.
+
+\tArgs:
+\t\tmarkdown_content (str): Markdown content
+
+\tReturns:
+\t\tstr: RST content
+\t"""
+def generate_index_rst(readme_path: str, index_path: str, project: str, github_user: str, github_repo: str, get_versions_function: Callable[[str, str, int], list[str]] = ..., recent_minor_versions: int = 2) -> None:
+    """ Generate index.rst from README.md content.
+
+\tArgs:
+\t\treadme_path            (str): Path to the README.md file
+\t\tindex_path             (str): Path where index.rst should be created
+\t\tproject                (str): Name of the project
+\t\tgithub_user            (str): GitHub username
+\t\tgithub_repo            (str): GitHub repository name
+\t\tget_versions_function  (Callable[[str, str, int], list[str]]): Function to get versions from GitHub
+\t\trecent_minor_versions  (int): Number of recent minor versions to show all patches for. Defaults to 2
+\t"""
+def generate_documentation(source_dir: str, modules_dir: str, project_dir: str, build_dir: str) -> None:
+    """ Generate documentation using Sphinx.
+
+\tArgs:
+\t\tsource_dir        (str): Source directory
+\t\tmodules_dir       (str): Modules directory
+\t\tproject_dir       (str): Project directory
+\t\tbuild_dir         (str): Build directory
+\t"""
+def generate_redirect_html(filepath: str) -> None:
+    """ Generate HTML content for redirect page.
+
+\tArgs:
+\t\tfilepath (str): Path to the file where the HTML content should be written
+\t"""
+def update_documentation(root_path: str, project: str, project_dir: str = '', author: str = 'Author', copyright: str = '2025, Author', html_logo: str = '', html_favicon: str = '', html_theme: str = 'breeze', github_user: str = '', github_repo: str = '', version: str | None = None, skip_undocumented: bool = True, recent_minor_versions: int = 2, get_versions_function: Callable[[str, str, int], list[str]] = ..., generate_index_function: Callable[..., None] = ..., generate_docs_function: Callable[..., None] = ..., generate_redirect_function: Callable[[str], None] = ..., get_conf_content_function: Callable[..., str] = ...) -> None:
+    ''' Update the Sphinx documentation.
+
+\tArgs:
+\t\troot_path                  (str): Root path of the project
+\t\tproject                    (str): Name of the project
+\t\tproject_dir                (str): Path to the project directory (to be used with generate_docs_function)
+\t\tauthor                     (str): Author of the project
+\t\tcopyright                  (str): Copyright information
+\t\thtml_logo                  (str): URL to the logo
+\t\thtml_favicon               (str): URL to the favicon
+\t\thtml_theme                 (str): Theme to use for the documentation. Defaults to "breeze"
+\t\tgithub_user                (str): GitHub username
+\t\tgithub_repo                (str): GitHub repository name
+\t\tversion                    (str | None): Version to build documentation for (e.g. "1.0.0", defaults to "latest")
+\t\tskip_undocumented          (bool): Whether to skip undocumented members. Defaults to True
+\t\trecent_minor_versions      (int): Number of recent minor versions to show all patches for. Defaults to 2
+
+\t\tget_versions_function      (Callable[[str, str, int], list[str]]): Function to get versions from GitHub
+\t\tgenerate_index_function    (Callable[..., None]): Function to generate index.rst
+\t\tgenerate_docs_function     (Callable[..., None]): Function to generate documentation
+\t\tgenerate_redirect_function (Callable[[str], None]): Function to create redirect file
+\t\tget_conf_content_function  (Callable[..., str]): Function to get Sphinx conf.py content
+\t'''

stouputils/stouputils/applications/upscaler/__init__.pyi

@@ -0,0 +1,3 @@
+from .config import *
+from .image import *
+from .video import *

stouputils/stouputils/applications/upscaler/config.pyi

@@ -0,0 +1,18 @@
+WAIFU2X_NCNN_VULKAN_RELEASES: dict[str, str]
+FFMPEG_RELEASES: dict[str, str]
+YOUTUBE_BITRATE_RECOMMENDATIONS: dict[str, dict[str, dict[int, int]]]
+
+class Config:
+    """ Configuration class for the upscaler. """
+    JPG_QUALITY: int
+    VIDEO_FINAL_BITRATE: int
+    FFMPEG_EXECUTABLE: str
+    FFMPEG_ARGS: tuple[str, ...]
+    FFPROBE_EXECUTABLE: str
+    FFMPEG_CHECK_HELP_TEXT: str
+    UPSCALER_EXECUTABLE: str
+    UPSCALER_ARGS: tuple[str, ...]
+    UPSCALER_EXECUTABLE_HELP_TEXT: str
+    SLIGHTLY_FASTER_MODE: bool
+    upscaler_executable_checked: bool
+    ffmpeg_executable_checked: bool