stouputils 1.12.2__py3-none-any.whl → 1.13.1__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/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

stouputils/stouputils/applications/upscaler/image.pyi

@@ -0,0 +1,109 @@
+from ...installer import check_executable as check_executable
+from ...io import clean_path as clean_path
+from ...parallel import multithreading as multithreading
+from ...print import colored_for_loop as colored_for_loop, debug as debug, info as info
+from .config import Config as Config, WAIFU2X_NCNN_VULKAN_RELEASES as WAIFU2X_NCNN_VULKAN_RELEASES
+from tempfile import TemporaryDirectory
+
+def convert_frame(frame_path: str, delete_png: bool = True) -> None:
+    ''' Convert a PNG frame to JPG format to take less space.
+
+\tArgs:
+\t\tframe_path  (str):   Path to the PNG frame to convert.
+\t\tdelete_png  (bool):  Whether to delete the original PNG file after conversion.
+
+\tReturns:
+\t\tNone: This function doesn\'t return anything.
+
+\tExample:
+\t\t.. code-block:: python
+
+\t\t\t> convert_frame("input.png", delete_png=True)
+\t\t\t> # input.png will be converted to input.jpg and the original file will be deleted
+
+\t\t\t> convert_frame("input.png", delete_png=False)
+\t\t\t> # input.png will be converted to input.jpg and the original file will be kept
+\t'''
+def get_all_files(folder: str, suffix: str | tuple[str, ...] = '') -> list[str]:
+    ''' Get all files paths in a folder, with a specific suffix if provided.
+
+\tArgs:
+\t\tfolder     (str):                    Path to the folder containing the files.
+\t\tsuffix     (str | tuple[str, ...]):  Suffix of the files to get (e.g. ".png", ".jpg", etc.).
+
+\tReturns:
+\t\tlist[str]: List of all files paths in the folder.
+
+\tExample:
+\t\t>>> files: list[str] = get_all_files("some_folder", ".png")
+\t\t>>> len(files)
+\t\t0
+\t'''
+def create_temp_dir_for_not_upscaled(input_path: str, output_path: str) -> TemporaryDirectory[str] | None:
+    """ Creates a temporary directory containing only images that haven't been upscaled yet.
+
+    Args:
+        input_path  (str):  Path to the folder containing input images.
+        output_path (str):  Path to the folder where upscaled images are saved.
+
+    Returns:
+        TemporaryDirectory[str] | None: A temporary directory object if there are images to process,
+                                        None if all images are already upscaled.
+    """
+def check_upscaler_executable() -> None: ...
+def upscale(input_path: str, output_path: str, upscale_ratio: int) -> None:
+    ''' Upscale an input image (or a directory of images) with the upscaler executable.
+
+\tArgs:
+\t\tinput_path     (str):  Path to the image to upscale (or a directory).
+\t\toutput_path    (str):  Path to the output image (or a directory).
+\t\tupscale_ratio  (int):  Upscaling ratio.
+
+\tExample:
+\t\t.. code-block:: python
+
+\t\t\t> upscale("folder", "folder", 2)
+\t\t\tTraceback (most recent call last):
+\t\t\t\t...
+\t\t\tAssertionError: Input and output paths cannot be the same, got \'folder\'
+
+\t\t\t> upscale("stouputils", "stouputils/output.jpg", 2)
+\t\t\tTraceback (most recent call last):
+\t\t\t\t...
+\t\t\tAssertionError: If input is a directory, output must be a directory too, got \'stouputils/output.jpg\'
+
+
+\t\t\t> upscale("input.jpg", "output.jpg", 2)
+\t\t\t> # The input.jpg will be upscaled to output.jpg with a ratio of 2
+
+\t\t\t> upscale("input_folder", "output_folder", 2)
+\t\t\t> # The input_folder will be upscaled to output_folder with a ratio of 2
+\t'''
+def upscale_images(images: list[str], output_folder: str, upscale_ratio: int, desc: str = 'Upscaling images') -> None:
+    """ Upscale multiple images from a list.
+
+\tArgs:
+\t\timages        (list[str]): List of paths to the images to upscale.
+\t\toutput_folder (str):       Path to the output folder where the upscaled images will be saved.
+\t\tupscale_ratio (int):       Upscaling ratio.
+\t\tdesc          (str):       Description of the function execution displayed in the progress bar.
+\t\t\tNo progress bar will be displayed if desc is empty.
+
+\tReturns:
+\t\tNone: This function doesn't return anything.
+\t"""
+def upscale_folder(input_folder: str, output_folder: str, upscale_ratio: int, slightly_faster_mode: bool = True, desc: str = 'Upscaling folder') -> None:
+    """ Upscale all images in a folder.
+
+\tArgs:
+\t\tinput_folder          (str):   Path to the input folder containing the images to upscale.
+\t\toutput_folder         (str):   Path to the output folder where the upscaled images will be saved.
+\t\tupscale_ratio         (int):   Upscaling ratio.
+\t\tslightly_faster_mode  (bool):  Whether to use the slightly faster mode (no progress bar),
+\t\t\tone call to the upscaler executable.
+\t\tdesc                  (str):   Description of the function execution displayed in the progress bar.
+\t\t\tNo progress bar will be displayed if desc is empty.
+
+\tReturns:
+\t\tNone: This function doesn't return anything.
+\t"""

stouputils/stouputils/applications/upscaler/video.pyi

@@ -0,0 +1,60 @@
+from ...installer import check_executable as check_executable
+from ...io import clean_path as clean_path
+from ...parallel import multithreading as multithreading
+from ...print import colored_for_loop as colored_for_loop, debug as debug, error as error, info as info, warning as warning
+from .config import Config as Config, FFMPEG_RELEASES as FFMPEG_RELEASES, YOUTUBE_BITRATE_RECOMMENDATIONS as YOUTUBE_BITRATE_RECOMMENDATIONS
+from .image import convert_frame as convert_frame, get_all_files as get_all_files, upscale_folder as upscale_folder
+from typing import Literal
+
+def get_recommended_bitrate(resolution: tuple[int, int], frame_rate: int = 60, upload_type: Literal['SDR', 'HDR'] = 'SDR') -> int:
+    ''' Get the recommended bitrate (in kbps) for the output video based on the video resolution.
+
+\tArgs:
+\t\tresolution  (tuple[int, int]):       Video resolution (width, height).
+\t\tframe_rate  (int):                   Frame rate of the video, default is 60.
+\t\tupload_type (Literal["SDR","HDR"]):  Upload type from which the recommendation is made, default is "SDR".
+
+\tReturns:
+\t\tint:     The recommended bitrate for the output video (in kbps)
+
+\tSource: https://support.google.com/youtube/answer/1722171?hl=en#zippy=%2Cbitrate
+
+\tExamples:
+\t\t>>> # Valid examples
+\t\t>>> get_recommended_bitrate((3840, 2160), 60, "SDR")
+\t\t68000
+\t\t>>> get_recommended_bitrate((1920, 1080), 60, "HDR")
+\t\t15000
+\t\t>>> get_recommended_bitrate((1920, 1080), 60, "SDR")
+\t\t12000
+\t\t>>> get_recommended_bitrate((1920, 1080), 30, "SDR")
+\t\t8000
+
+\t\t>>> # Invalid examples
+\t\t>>> get_recommended_bitrate((1920, 1080), 60, "Ratio")
+\t\tTraceback (most recent call last):
+\t\t\t...
+\t\tAssertionError: Invalid upload type: \'Ratio\'
+\t\t>>> get_recommended_bitrate("1920x1080", 60, "SDR")
+\t\tTraceback (most recent call last):
+\t\t\t...
+\t\tAssertionError: Invalid resolution: 1920x1080, must be a tuple of two integers
+\t\t>>> get_recommended_bitrate((1920, 1080), -10, "SDR")
+\t\tTraceback (most recent call last):
+\t\t\t...
+\t\tAssertionError: Invalid frame rate: -10, must be a positive integer
+\t'''
+def check_ffmpeg_executable() -> None: ...
+def upscale_video(video_file: str, input_folder: str, progress_folder: str, output_folder: str) -> None:
+    """ Handles a video file. """
+def video_upscaler_cli(input_folder: str, progress_folder: str, output_folder: str) -> None:
+    """ Upscales videos from an input folder and saves them to an output folder.
+
+\tUses intermediate folders for extracted and upscaled frames within the progress folder.
+\t**Handles resuming partially processed videos.**
+
+\tArgs:
+\t\tinput_folder    (str): Path to the folder containing input videos.
+\t\tprogress_folder (str): Path to the folder for storing intermediate files (frames).
+\t\toutput_folder   (str): Path to the folder where upscaled videos will be saved.
+\t"""