stouputils 1.12.1__py3-none-any.whl

stouputils/__init__.py

@@ -0,0 +1,40 @@
+""" A collection of utility modules designed to simplify and enhance the development process.
+
+This package provides various tools and utilities for common development tasks including:
+
+Key Features:
+- Continuous delivery utilities (GitHub, PyPI)
+- Display and logging utilities (print)
+- File and I/O management (io)
+- Decorators for common patterns
+- Context managers
+- Archive and backup tools
+- Parallel processing helpers
+- Collection utilities
+- Doctests utilities
+
+"""
+# ruff: noqa: F403
+
+# Version (handle case where the package is not installed)
+from importlib.metadata import PackageNotFoundError, version
+
+# Imports
+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 *
+
+try:
+	__version__: str = version("stouputils")
+except PackageNotFoundError:
+	__version__: str = "0.0.0-dev"
+

stouputils/__init__.pyi

@@ -0,0 +1,14 @@
+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 *
+
+__version__: str

stouputils/__main__.py

@@ -0,0 +1,81 @@
+
+
+# PYTHON_ARGCOMPLETE_OK
+# Imports
+import argparse
+import sys
+
+import argcomplete
+
+from .all_doctests import launch_tests
+from .archive import archive_cli
+from .backup import backup_cli
+from .decorators import handle_error
+from .print import CYAN, GREEN, RESET, show_version
+
+# Argument Parser Setup for Auto-Completion
+parser = argparse.ArgumentParser(prog="stouputils", add_help=False)
+parser.add_argument("command", nargs="?", choices=[
+	"--version", "-v", "version", "show_version", "all_doctests", "archive", "backup"
+])
+parser.add_argument("args", nargs="*")
+argcomplete.autocomplete(parser)
+
+
+@handle_error(message="Error while running 'stouputils'")
+def main() -> None:
+	second_arg: str = sys.argv[1].lower() if len(sys.argv) >= 2 else ""
+
+	# Print the version of stouputils and its dependencies
+	if second_arg in ("--version", "-v", "version", "show_version"):
+		if len(sys.argv) >= 3:
+			return show_version(sys.argv[2])
+		return show_version()
+
+	# Handle "all_doctests" command
+	if second_arg == "all_doctests":
+		if launch_tests("." if len(sys.argv) == 2 else sys.argv[2]) > 0:
+			sys.exit(1)
+		return
+
+	# Handle "archive" command
+	if second_arg == "archive":
+		sys.argv.pop(1)  # Remove "archive" from argv so archive_cli gets clean arguments
+		return archive_cli()
+
+	# Handle "backup" command
+	if second_arg == "backup":
+		sys.argv.pop(1)  # Remove "backup" from argv so backup_cli gets clean arguments
+		return backup_cli()
+
+	# Check if the command is any package name
+	if second_arg in (): # type: ignore
+		return
+
+	# Get version
+	from importlib.metadata import version
+	try:
+		pkg_version = version("stouputils")
+	except Exception:
+		pkg_version = "unknown"
+
+	# Print help with nice formatting
+	separator: str = "─" * 60
+	print(f"""
+{CYAN}{separator}{RESET}
+{CYAN}stouputils {GREEN}CLI {CYAN}v{pkg_version}{RESET}
+{CYAN}{separator}{RESET}
+{CYAN}Usage:{RESET} stouputils <command> [options]
+
+{CYAN}Available commands:{RESET}
+  {GREEN}--version, -v{RESET} [pkg]  Show version information (optionally for a specific package)
+  {GREEN}all_doctests{RESET} [dir]   Run all doctests in the specified directory
+  {GREEN}archive{RESET} --help       Archive utilities (make, repair)
+  {GREEN}backup{RESET} --help        Backup utilities (delta, consolidate, limit)
+{CYAN}{separator}{RESET}
+""".strip())
+	return
+
+if __name__ == "__main__":
+	main()
+

stouputils/_deprecated.py

@@ -0,0 +1,37 @@
+""" Deprecated functions and classes.
+
+This module contains deprecated functions that have been replaced by new implementations
+These functions are retained for backward compatibility and will log deprecation warnings when used.
+"""
+
+# Imports
+from typing import Any
+
+from .decorators import LogLevels, deprecated
+from .io import csv_dump, csv_load, json_dump, json_load
+
+
+# Deprecated functions
+@deprecated(message="super_csv_dump has been renamed to csv_dump.", version="v1.8.0", error_log=LogLevels.WARNING)
+def super_csv_dump(*args: Any, **kwargs: Any) -> Any:
+	""" Deprecated function, use "csv_dump" instead. """
+	return csv_dump(*args, **kwargs)
+
+
+@deprecated(message="super_csv_load has been renamed to csv_load.", version="v1.8.0", error_log=LogLevels.WARNING)
+def super_csv_load(*args: Any, **kwargs: Any) -> Any:
+	""" Deprecated function, use "csv_load" instead. """
+	return csv_load(*args, **kwargs)
+
+
+@deprecated(message="super_json_dump has been renamed to json_dump.", version="v1.8.0", error_log=LogLevels.WARNING)
+def super_json_dump(*args: Any, **kwargs: Any) -> Any:
+	""" Deprecated function, use "json_dump" instead. """
+	return json_dump(*args, **kwargs)
+
+
+@deprecated(message="super_json_load has been renamed to json_load.", version="v1.8.0", error_log=LogLevels.WARNING)
+def super_json_load(*args: Any, **kwargs: Any) -> Any:
+	""" Deprecated function, use "json_load" instead. """
+	return json_load(*args, **kwargs)
+

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/all_doctests.py

@@ -0,0 +1,160 @@
+"""
+This module is used to run all the doctests for all the modules in a given directory.
+
+- launch_tests: Main function to launch tests for all modules in the given directory.
+- test_module_with_progress: Test a module with testmod and measure the time taken with progress printing.
+
+.. image:: https://raw.githubusercontent.com/Stoupy51/stouputils/refs/heads/main/assets/all_doctests_module.gif
+  :alt: stouputils all_doctests examples
+"""
+
+# Imports
+import importlib
+import os
+import pkgutil
+import sys
+from types import ModuleType
+from typing import TYPE_CHECKING
+
+from . import decorators
+from .decorators import measure_time
+from .io import clean_path, relative_path
+from .print import error, info, progress, warning
+
+if TYPE_CHECKING:
+	from doctest import TestResults
+
+
+# Main program
+def launch_tests(root_dir: str, strict: bool = True) -> int:
+	""" Main function to launch tests for all modules in the given directory.
+
+	Args:
+		root_dir				(str):			Root directory to search for modules
+		strict					(bool):			Modify the force_raise_exception variable to True in the decorators module
+
+	Returns:
+		int: The number of failed tests
+
+	Examples:
+		>>> launch_tests("unknown_dir")
+		Traceback (most recent call last):
+			...
+		ValueError: No modules found in 'unknown_dir'
+
+	.. code-block:: python
+
+		> if launch_tests("/path/to/source") > 0:
+			sys.exit(1)
+		[PROGRESS HH:MM:SS] Importing module 'module1'	took 0.001s
+		[PROGRESS HH:MM:SS] Importing module 'module2'	took 0.002s
+		[PROGRESS HH:MM:SS] Importing module 'module3'	took 0.003s
+		[PROGRESS HH:MM:SS] Importing module 'module4'	took 0.004s
+		[INFO HH:MM:SS] Testing 4 modules...
+		[PROGRESS HH:MM:SS] Testing module 'module1'	took 0.005s
+		[PROGRESS HH:MM:SS] Testing module 'module2'	took 0.006s
+		[PROGRESS HH:MM:SS] Testing module 'module3'	took 0.007s
+		[PROGRESS HH:MM:SS] Testing module 'module4'	took 0.008s
+	"""
+	if strict:
+		old_value: bool = strict
+		decorators.force_raise_exception = True
+		strict = old_value
+
+	# Get the path of the directory to check modules from
+	working_dir: str = clean_path(os.getcwd())
+	root_dir = clean_path(os.path.abspath(root_dir))
+	dir_to_check: str = os.path.dirname(root_dir) if working_dir != root_dir else root_dir
+
+	# Get all modules from folder
+	sys.path.insert(0, dir_to_check)
+	modules_file_paths: list[str] = []
+	for directory_path, _, _ in os.walk(root_dir):
+		directory_path = clean_path(directory_path)
+		for module_info in pkgutil.walk_packages([directory_path]):
+
+			# Extract root and module name
+			module_root: str = str(module_info.module_finder.path)	# type: ignore
+			module_name: str = module_info.name.split(".")[-1]
+
+			# Get the absolute path
+			absolute_module_path: str = clean_path(os.path.join(module_root, module_name))
+
+			# Check if the module is in the root directory that we want to check
+			if root_dir in absolute_module_path:
+
+				# Get the path of the module like 'stouputils.io'
+				path: str = absolute_module_path.split(dir_to_check, 1)[1].replace("/", ".")[1:]
+
+				# If the module is not already in the list, add it
+				if path not in modules_file_paths:
+					modules_file_paths.append(path)
+
+	# If no modules are found, raise an error
+	if not modules_file_paths:
+		raise ValueError(f"No modules found in '{relative_path(root_dir)}'")
+
+	# Find longest module path for alignment
+	max_length: int = max(len(path) for path in modules_file_paths)
+
+	# Dynamically import all modules from iacob package recursively using pkgutil and importlib
+	modules: list[ModuleType] = []
+	separators: list[str] = []
+	for module_path in modules_file_paths:
+		separator: str = " " * (max_length - len(module_path))
+
+		@measure_time(message=f"Importing module '{module_path}' {separator}took")
+		def internal(a: str = module_path, b: str = separator) -> None:
+			modules.append(importlib.import_module(a))
+			separators.append(b)
+
+		try:
+			internal()
+		except Exception as e:
+			warning(f"Failed to import module '{module_path}': ({type(e).__name__}) {e}")
+
+	# Run tests for each module
+	info(f"Testing {len(modules)} modules...")
+	separators = [s + " "*(len("Importing") - len("Testing")) for s in separators]
+	results: list[TestResults] = [
+		test_module_with_progress(module, separator)
+		for module, separator in zip(modules, separators, strict=False)
+	]
+
+	# Display any error lines for each module at the end of the script
+	total_failed: int = 0
+	for module, result in zip(modules, results, strict=False):
+		if result.failed > 0:
+			successful_tests: int = result.attempted - result.failed
+			error(f"Errors in module {module.__name__} ({successful_tests}/{result.attempted} tests passed)", exit=False)
+			total_failed += result.failed
+
+	# Reset force_raise_exception back
+	decorators.force_raise_exception = strict
+
+	# Final info
+	total_tests: int = sum(result.attempted for result in results)
+	successful_tests: int = total_tests - total_failed
+	if total_failed == 0:
+		info(f"All tests passed for all {len(modules)} modules! ({total_tests}/{total_tests} tests passed)")
+	else:
+		error(f"Some tests failed: {successful_tests}/{total_tests} tests passed in total across {len(modules)} modules", exit=False)
+	# Return the number of failed tests
+	return total_failed
+
+
+def test_module_with_progress(module: ModuleType, separator: str) -> "TestResults":
+	""" Test a module with testmod and measure the time taken with progress printing.
+
+	Args:
+		module		(ModuleType):	Module to test
+		separator	(str):			Separator string for alignment in output
+	Returns:
+		TestResults: The results of the tests
+	"""
+	from doctest import TestResults, testmod
+	@measure_time(message=f"Testing module '{module.__name__}' {separator}took")
+	def internal() -> TestResults:
+		return testmod(m=module)
+	return internal()
+

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/applications/__init__.py

@@ -0,0 +1,22 @@
+""" Application-specific utilities and tools.
+
+This module provides higher-level utilities for specific application needs:
+
+Automatic Documentation:
+
+- Automatic documentation generation with Sphinx: `update_documentation(...)`
+- Support for multi-version documentation
+- GitHub Pages integration
+- Markdown to RST conversion
+
+Upscaler:
+
+- TODO
+
+"""
+# ruff: noqa: F403
+
+# Imports
+from .automatic_docs import *
+from .upscaler import *
+

stouputils/applications/__init__.pyi

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