stouputils 1.14.0__py3-none-any.whl

stouputils/print.py

@@ -0,0 +1,482 @@
+"""
+This module provides utility functions for printing messages with different levels of importance.
+
+If a message is printed multiple times, it will be displayed as "(xN) message"
+where N is the number of times the message has been printed.
+
+.. image:: https://raw.githubusercontent.com/Stoupy51/stouputils/refs/heads/main/assets/print_module.gif
+  :alt: stouputils print examples
+"""
+
+# Imports
+import os
+import sys
+import time
+from collections.abc import Callable, Iterable, Iterator
+from typing import IO, Any, TextIO, TypeVar, cast
+
+# Colors constants
+RESET: str   = "\033[0m"
+RED: str     = "\033[91m"
+GREEN: str   = "\033[92m"
+YELLOW: str  = "\033[93m"
+BLUE: str    = "\033[94m"
+MAGENTA: str = "\033[95m"
+CYAN: str    = "\033[96m"
+LINE_UP: str = "\033[1A"
+
+# Constants
+BAR_FORMAT: str = "{l_bar}{bar}" + MAGENTA + "| {n_fmt}/{total_fmt} [{rate_fmt}{postfix}, {elapsed}<{remaining}]" + RESET
+T = TypeVar("T")
+
+# Enable colors on Windows 10 terminal if applicable
+if os.name == "nt":
+	os.system("color")
+
+# Print functions
+previous_args_kwards: tuple[Any, Any] = ((), {})
+nb_values: int = 1
+import_time: float = time.time()
+
+# Colored for loop function
+def colored_for_loop[T](
+	iterable: Iterable[T],
+	desc: str = "Processing",
+	color: str = MAGENTA,
+	bar_format: str = BAR_FORMAT,
+	ascii: bool = False,
+	smooth_tqdm: bool = True,
+	**kwargs: Any
+) -> Iterator[T]:
+	""" Function to iterate over a list with a colored TQDM progress bar like the other functions in this module.
+
+	Args:
+		iterable	(Iterable):			List to iterate over
+		desc		(str):				Description of the function execution displayed in the progress bar
+		color		(str):				Color of the progress bar (Defaults to MAGENTA)
+		bar_format	(str):				Format of the progress bar (Defaults to BAR_FORMAT)
+		ascii		(bool):				Whether to use ASCII or Unicode characters for the progress bar (Defaults to False)
+		smooth_tqdm	(bool):				Whether to enable smooth progress bar updates by setting miniters=1 and mininterval=0.0 (Defaults to True)
+		**kwargs:						Additional arguments to pass to the TQDM progress bar
+
+	Yields:
+		T: Each item of the iterable
+
+	Examples:
+		>>> for i in colored_for_loop(range(10), desc="Time sleeping loop"):
+		...     time.sleep(0.01)
+		>>> # Time sleeping loop: 100%|██████████████████| 10/10 [ 95.72it/s, 00:00<00:00]
+	"""
+	if bar_format == BAR_FORMAT:
+		bar_format = bar_format.replace(MAGENTA, color)
+	desc = color + desc
+
+	if smooth_tqdm:
+		kwargs.setdefault("mininterval", 0.0)
+		try:
+			total = len(iterable) # type: ignore
+			import shutil
+			width = shutil.get_terminal_size().columns
+			kwargs.setdefault("miniters", max(1, total // width))
+		except (TypeError, OSError):
+			kwargs.setdefault("miniters", 1)
+
+	from tqdm.auto import tqdm
+	yield from tqdm(iterable, desc=desc, bar_format=bar_format, ascii=ascii, **kwargs)
+
+def info(
+	*values: Any,
+	color: str = GREEN,
+	text: str = "INFO ",
+	prefix: str = "",
+	file: TextIO | list[TextIO] | None = None,
+	**print_kwargs: Any,
+) -> None:
+	""" Print an information message looking like "[INFO HH:MM:SS] message" in green by default.
+
+	Args:
+		values			(Any):					Values to print (like the print function)
+		color			(str):					Color of the message (default: GREEN)
+		text			(str):					Text of the message (default: "INFO ")
+		prefix			(str):					Prefix to add to the values
+		file			(TextIO|list[TextIO]):	File(s) to write the message to (default: sys.stdout)
+		print_kwargs	(dict):					Keyword arguments to pass to the print function
+	"""
+	# Use stdout if no file is specified
+	if file is None:
+		file = sys.stdout
+
+	# If file is a list, recursively call info() for each file
+	if isinstance(file, list):
+		for f in file:
+			info(*values, color=color, text=text, prefix=prefix, file=f, **print_kwargs)
+	else:
+		# Build the message with prefix, color, text and timestamp
+		message: str = f"{prefix}{color}[{text} {current_time()}]"
+
+		# If this is a repeated print, add a line up and counter
+		if is_same_print(*values, color=color, text=text, prefix=prefix, **print_kwargs):
+			message = f"{LINE_UP}{message} (x{nb_values})"
+
+		# Print the message with the values and reset color
+		print(message, *values, RESET, file=file, **print_kwargs)
+
+def debug(*values: Any, **print_kwargs: Any) -> None:
+	""" Print a debug message looking like "[DEBUG HH:MM:SS] message" in cyan by default. """
+	if "text" not in print_kwargs:
+		print_kwargs["text"] = "DEBUG"
+	if "color" not in print_kwargs:
+		print_kwargs["color"] = CYAN
+	info(*values, **print_kwargs)
+
+def alt_debug(*values: Any, **print_kwargs: Any) -> None:
+	""" Print a debug message looking like "[DEBUG HH:MM:SS] message" in blue by default. """
+	if "text" not in print_kwargs:
+		print_kwargs["text"] = "DEBUG"
+	if "color" not in print_kwargs:
+		print_kwargs["color"] = BLUE
+	info(*values, **print_kwargs)
+
+def suggestion(*values: Any, **print_kwargs: Any) -> None:
+	""" Print a suggestion message looking like "[SUGGESTION HH:MM:SS] message" in cyan by default. """
+	if "text" not in print_kwargs:
+		print_kwargs["text"] = "SUGGESTION"
+	if "color" not in print_kwargs:
+		print_kwargs["color"] = CYAN
+	info(*values, **print_kwargs)
+
+def progress(*values: Any, **print_kwargs: Any) -> None:
+	""" Print a progress message looking like "[PROGRESS HH:MM:SS] message" in magenta by default. """
+	if "text" not in print_kwargs:
+		print_kwargs["text"] = "PROGRESS"
+	if "color" not in print_kwargs:
+		print_kwargs["color"] = MAGENTA
+	info(*values, **print_kwargs)
+
+def warning(*values: Any, **print_kwargs: Any) -> None:
+	""" Print a warning message looking like "[WARNING HH:MM:SS] message" in yellow by default and in sys.stderr. """
+	if "file" not in print_kwargs:
+		print_kwargs["file"] = sys.stderr
+	if "text" not in print_kwargs:
+		print_kwargs["text"] = "WARNING"
+	if "color" not in print_kwargs:
+		print_kwargs["color"] = YELLOW
+	info(*values, **print_kwargs)
+
+def error(*values: Any, exit: bool = False, **print_kwargs: Any) -> None:
+	""" Print an error message (in sys.stderr and in red by default)
+	and optionally ask the user to continue or stop the program.
+
+	Args:
+		values			(Any):		Values to print (like the print function)
+		exit			(bool):		Whether to ask the user to continue or stop the program,
+			false to ignore the error automatically and continue
+		print_kwargs	(dict):		Keyword arguments to pass to the print function
+	"""
+	file: TextIO = sys.stderr
+	if "file" in print_kwargs:
+		if isinstance(print_kwargs["file"], list):
+			file = cast(TextIO, print_kwargs["file"][0])
+		else:
+			file = print_kwargs["file"]
+	if "text" not in print_kwargs:
+		print_kwargs["text"] = "ERROR"
+	if "color" not in print_kwargs:
+		print_kwargs["color"] = RED
+	info(*values, **print_kwargs)
+	if exit:
+		try:
+			print("Press enter to ignore error and continue, or 'CTRL+C' to stop the program... ", file=file)
+			input()
+		except (KeyboardInterrupt, EOFError):
+			print(file=file)
+			sys.exit(1)
+
+def whatisit(
+	*values: Any,
+	print_function: Callable[..., None] = debug,
+	max_length: int = 250,
+	color: str = CYAN,
+	**print_kwargs: Any,
+) -> None:
+	""" Print the type of each value and the value itself, with its id and length/shape.
+
+	The output format is: "type, <id id_number>:	(length/shape) value"
+
+	Args:
+		values			(Any):		Values to print
+		print_function	(Callable):	Function to use to print the values (default: debug())
+		max_length		(int):		Maximum length of the value string to print (default: 250)
+		color			(str):		Color of the message (default: CYAN)
+		print_kwargs	(dict):		Keyword arguments to pass to the print function
+	"""
+	def _internal(value: Any) -> str:
+		""" Get the string representation of the value, with length or shape instead of length if shape is available """
+
+		# Build metadata parts list
+		metadata_parts: list[str] = []
+
+		# Get the dtype if available
+		try:
+			metadata_parts.append(f"dtype: {value.dtype}")
+		except (AttributeError, TypeError):
+			pass
+
+		# Get the shape or length of the value
+		try:
+			metadata_parts.append(f"shape: {value.shape}")
+		except (AttributeError, TypeError):
+			try:
+				metadata_parts.append(f"length: {len(value)}")
+			except (AttributeError, TypeError):
+				pass
+
+		# Get the min and max if available (Iterable of numbers)
+		try:
+			if not isinstance(value, str | bytes | bytearray | dict | int | float):
+				import numpy as np
+				mini, maxi = np.min(value), np.max(value)
+				if mini != maxi:
+					metadata_parts.append(f"min: {mini}")
+					metadata_parts.append(f"max: {maxi}")
+		except (Exception):
+			pass
+
+		# Combine metadata into a single parenthesized string
+		metadata_str: str = f"({', '.join(metadata_parts)}) " if metadata_parts else ""
+
+		# Get the string representation of the value
+		value = cast(Any, value)
+		value_str: str = str(value)
+		if len(value_str) > max_length:
+			value_str = value_str[:max_length] + "..."
+		if "\n" in value_str:
+			value_str = "\n" + value_str	# Add a newline before the value if there is a newline in it.
+
+		# Return the formatted string
+		return f"{type(value)}, <id {id(value)}>: {metadata_str}{value_str}"
+
+	# Add the color to the message
+	if "color" not in print_kwargs:
+		print_kwargs["color"] = color
+
+	# Set text to "What is it?" if not already set
+	if "text" not in print_kwargs:
+		print_kwargs["text"] = "What is it?"
+
+	# Print the values
+	if len(values) > 1:
+		print_function("".join(f"\n  {_internal(value)}" for value in values), **print_kwargs)
+	elif len(values) == 1:
+		print_function(_internal(values[0]), **print_kwargs)
+
+def breakpoint(*values: Any, print_function: Callable[..., None] = warning, **print_kwargs: Any) -> None:
+	""" Breakpoint function, pause the program and print the values.
+
+	Args:
+		values			(Any):		Values to print
+		print_function	(Callable):	Function to use to print the values (default: warning())
+		print_kwargs	(dict):		Keyword arguments to pass to the print function
+	"""
+	if "text" not in print_kwargs:
+		print_kwargs["text"] = "BREAKPOINT (press Enter)"
+	file: TextIO = sys.stderr
+	if "file" in print_kwargs:
+		if isinstance(print_kwargs["file"], list):
+			file = cast(TextIO, print_kwargs["file"][0])
+		else:
+			file = print_kwargs["file"]
+	whatisit(*values, print_function=print_function, **print_kwargs)
+	try:
+		input()
+	except (KeyboardInterrupt, EOFError):
+		print(file=file)
+		sys.exit(1)
+
+
+# TeeMultiOutput class to duplicate output to multiple file-like objects
+class TeeMultiOutput:
+	""" File-like object that duplicates output to multiple file-like objects.
+
+	Args:
+		*files         (IO[Any]):  One or more file-like objects that have write and flush methods
+		strip_colors   (bool):     Strip ANSI color codes from output sent to non-stdout/stderr files
+		ascii_only     (bool):     Replace non-ASCII characters with their ASCII equivalents for non-stdout/stderr files
+		ignore_lineup  (bool):     Ignore lines containing LINE_UP escape sequence in non-terminal outputs
+
+	Examples:
+		>>> f = open("logfile.txt", "w")
+		>>> sys.stdout = TeeMultiOutput(sys.stdout, f)
+		>>> print("Hello World")  # Output goes to both console and file
+		Hello World
+		>>> f.close()	# TeeMultiOutput will handle any future writes to closed files gracefully
+	"""
+	def __init__(
+		self, *files: IO[Any], strip_colors: bool = True, ascii_only: bool = True, ignore_lineup: bool = True
+	) -> None:
+		# Flatten any TeeMultiOutput instances in files
+		flattened_files: list[IO[Any]] = []
+		for file in files:
+			if isinstance(file, TeeMultiOutput):
+				flattened_files.extend(file.files)
+			else:
+				flattened_files.append(file)
+
+		self.files: tuple[IO[Any], ...] = tuple(flattened_files)
+		""" File-like objects to write to """
+		self.strip_colors: bool = strip_colors
+		""" Whether to strip ANSI color codes from output sent to non-stdout/stderr files """
+		self.ascii_only: bool = ascii_only
+		""" Whether to replace non-ASCII characters with their ASCII equivalents for non-stdout/stderr files """
+		self.ignore_lineup: bool = ignore_lineup
+		""" Whether to ignore lines containing LINE_UP escape sequence in non-terminal outputs """
+
+	@property
+	def encoding(self) -> str:
+		""" Get the encoding of the first file, or "utf-8" as fallback.
+
+		Returns:
+			str: The encoding, ex: "utf-8", "ascii", "latin1", etc.
+		"""
+		try:
+			return self.files[0].encoding	# type: ignore
+		except (IndexError, AttributeError):
+			return "utf-8"
+
+	def write(self, obj: str) -> int:
+		""" Write the object to all files while stripping colors if needed.
+
+		Args:
+			obj (str): String to write
+		Returns:
+			int: Number of characters written to the first file
+		"""
+		files_to_remove: list[IO[Any]] = []
+		num_chars_written: int = 0
+		for i, f in enumerate(self.files):
+			try:
+				# Check if file is closed
+				if hasattr(f, "closed") and f.closed:
+					files_to_remove.append(f)
+					continue
+
+				# Check if this file is a terminal/console or a regular file
+				content: str = obj
+				if not (hasattr(f, "isatty") and f.isatty()):
+					# Non-terminal files get processed content (stripped colors, ASCII-only, etc.)
+
+					# Skip content if it contains LINE_UP and ignore_lineup is True
+					if self.ignore_lineup and (LINE_UP in content or "\r" in content):
+						continue
+
+					# Strip colors if needed
+					if self.strip_colors:
+						content = remove_colors(content)
+
+					# Replace Unicode block characters with ASCII equivalents
+					# Replace other problematic Unicode characters as needed
+					if self.ascii_only:
+						content = content.replace('█', '#')
+						content = ''.join(c if ord(c) < 128 else '?' for c in content)
+
+				# Write content to file
+				if i == 0:
+					num_chars_written = f.write(content)
+				else:
+					f.write(content)
+
+			except ValueError:
+				# ValueError is raised when writing to a closed file
+				files_to_remove.append(f)
+			except Exception:
+				pass
+
+		# Remove closed files from the list
+		if files_to_remove:
+			self.files = tuple(f for f in self.files if f not in files_to_remove)
+		return num_chars_written
+
+	def flush(self) -> None:
+		""" Flush all files. """
+		for f in self.files:
+			try:
+				f.flush()
+			except Exception:
+				pass
+
+	def fileno(self) -> int:
+		""" Return the file descriptor of the first file. """
+		return self.files[0].fileno() if hasattr(self.files[0], "fileno") else 0
+
+
+# Utility functions
+def remove_colors(text: str) -> str:
+	""" Remove the colors from a text """
+	for color in [RESET, RED, GREEN, YELLOW, BLUE, MAGENTA, CYAN, LINE_UP]:
+		text = text.replace(color, "")
+	return text
+
+def is_same_print(*args: Any, **kwargs: Any) -> bool:
+	""" Checks if the current print call is the same as the previous one. """
+	global previous_args_kwards, nb_values
+	try:
+		if previous_args_kwards == (args, kwargs):
+			nb_values += 1
+			return True
+	except Exception:
+		# Comparison failed (e.g., comparing DataFrames or other complex objects)
+		# Use str() for comparison instead
+		current_str: str = str((args, kwargs))
+		previous_str: str = str(previous_args_kwards)
+		if previous_str == current_str:
+			nb_values += 1
+			return True
+	# Else, update previous args and reset counter
+	previous_args_kwards = (args, kwargs)
+	nb_values = 1
+	return False
+
+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" """
+	# If the import time is more than 24 hours, return the full datetime
+	if (time.time() - import_time) > (24 * 60 * 60):
+		return time.strftime("%Y-%m-%d %H:%M:%S")
+	else:
+		return time.strftime("%H:%M:%S")
+
+
+# Test the print functions
+if __name__ == "__main__":
+	info("Hello", "World")
+	time.sleep(0.5)
+	info("Hello", "World")
+	time.sleep(0.5)
+	info("Hello", "World")
+	time.sleep(0.5)
+	info("Not Hello World !")
+	time.sleep(0.5)
+	info("Hello", "World")
+	time.sleep(0.5)
+	info("Hello", "World")
+
+	# All remaining print functions
+	alt_debug("Hello", "World")
+	debug("Hello", "World")
+	suggestion("Hello", "World")
+	progress("Hello", "World")
+	warning("Hello", "World")
+	error("Hello", "World", exit=False)
+	whatisit("Hello")
+	whatisit("Hello", "World")
+
+	# Test whatisit with different types
+	import numpy as np
+	print()
+	whatisit(
+		123,
+		"Hello World",
+		[1, 2, 3, 4, 5],
+		np.array([[1, 2, 3], [4, 5, 6]]),
+		{"a": 1, "b": 2},
+	)
+

stouputils/py.typed

@@ -0,0 +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 *