stouputils 1.5.4__tar.gz → 1.6.1__tar.gz

{stouputils-1.5.4 → stouputils-1.6.1}/.gitignore

@@ -9,6 +9,9 @@ output.log
 logfile.txt
 .vscode
 
+# Type stubs
+*.pyi
+
 # Documentation
 docs/source/_static/
 docs/source/_templates/

{stouputils-1.5.4 → stouputils-1.6.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: stouputils
-Version: 1.5.4
+Version: 1.6.1
 Summary: Stouputils is a collection of utility modules designed to simplify and enhance the development process. It includes a range of tools for tasks such as execution of doctests, display utilities, decorators, as well as context managers, and many more.
 Project-URL: Homepage, https://github.com/Stoupy51/stouputils
 Project-URL: Issues, https://github.com/Stoupy51/stouputils/issues
@@ -10,6 +10,7 @@ Classifier: License :: OSI Approved :: MIT License
 Classifier: Operating System :: OS Independent
 Classifier: Programming Language :: Python :: 3
 Requires-Python: >=3.10
+Requires-Dist: mypy>=1.18.2
 Requires-Dist: numpy
 Requires-Dist: opencv-python>=4.0.0
 Requires-Dist: orjson>=3.0.0

{stouputils-1.5.4 → stouputils-1.6.1}/pyproject.toml

@@ -5,7 +5,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "stouputils"
-version = "1.5.4"
+version = "1.6.1"
 description = "Stouputils is a collection of utility modules designed to simplify and enhance the development process. It includes a range of tools for tasks such as execution of doctests, display utilities, decorators, as well as context managers, and many more."
 readme = "README.md"
 requires-python = ">=3.10"
@@ -14,7 +14,7 @@ classifiers = [
 	"License :: OSI Approved :: MIT License",
 	"Operating System :: OS Independent",
 ]
-dependencies = [ "tqdm>=4.0.0", "requests>=2.20.0", "pyyaml>=6.0.0", "toml>=0.10.0", "pillow>=10.0.0", "numpy", "opencv-python>=4.0.0", "orjson>=3.0.0", "pyfastcopy>=1.0.0", "python-box[all]>=7.0.0", "zarr>=2.18.3",]
+dependencies = [ "tqdm>=4.0.0", "requests>=2.20.0", "pyyaml>=6.0.0", "toml>=0.10.0", "pillow>=10.0.0", "numpy", "opencv-python>=4.0.0", "orjson>=3.0.0", "pyfastcopy>=1.0.0", "python-box[all]>=7.0.0", "zarr>=2.18.3", "mypy>=1.18.2",]
 [[project.authors]]
 name = "Stoupy51"
 email = "stoupy51@gmail.com"
@@ -57,6 +57,7 @@ exclude = [
 	".cursor",
 	"build",
 	"dist",
+	"*.pyi",
 ]
 line-length = 200
 
@@ -84,4 +85,5 @@ ignore = [
 
 [tool.hatch.build]
 include = ["stouputils"]
+ignore-vcs = true
 

stouputils-1.6.1/stouputils/__init__.pyi

@@ -0,0 +1,13 @@
+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-1.5.4 → stouputils-1.6.1}/stouputils/__main__.py

@@ -10,7 +10,7 @@ from .print import CYAN, GREEN, RESET, show_version
 
 
 @handle_error(message="Error while running 'stouputils'")
-def main():
+def main() -> None:
 	second_arg: str = sys.argv[1].lower() if len(sys.argv) >= 2 else ""
 	if not second_arg:
 		# Get version

stouputils-1.6.1/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-1.6.1/stouputils/applications/__init__.pyi

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

stouputils-1.6.1/stouputils/applications/automatic_docs.pyi

@@ -0,0 +1,101 @@
+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, super_json_dump as super_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) -> list[str]:
+    """ Get list of versions from GitHub gh-pages branch.
+
+\tArgs:
+\t\tgithub_user    (str): GitHub username
+\t\tgithub_repo    (str): GitHub repository name
+
+\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], list[str]] = ...) -> 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], list[str]]): Function to get versions from GitHub
+\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, get_versions_function: Callable[[str, str], 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\tget_versions_function      (Callable[[str, str], 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-1.6.1/stouputils/applications/upscaler/__init__.pyi

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

stouputils-1.6.1/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-1.6.1/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-1.5.4 → stouputils-1.6.1}/stouputils/applications/upscaler/video.py

@@ -191,7 +191,8 @@ def upscale_video(video_file: str, input_folder: str, progress_folder: str, outp
 				else:
 					error(
 						"No upscaling ratio provided with --upscale flag. "
-						"Please provide a ratio after the flag. (1/2/4/8/16/32)"
+						"Please provide a ratio after the flag. (1/2/4/8/16/32)",
+						exit=True
 					)
 			else:
 				info("No upscaling ratio provided, please enter one (1/2/4/8/16/32, default=2):")

stouputils-1.6.1/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"""

{stouputils-1.5.4 → stouputils-1.6.1}/stouputils/archive.py

@@ -248,7 +248,7 @@ def make_archive(
 
 
 # Main entry point for command line usage
-def archive_cli():
+def archive_cli() -> None:
 	""" Main entry point for command line usage.
 
 	Examples:

stouputils-1.6.1/stouputils/archive.pyi

@@ -0,0 +1,67 @@
+from .decorators import LogLevels as LogLevels, handle_error as handle_error
+from .io import clean_path as clean_path, super_copy as super_copy
+from .print import debug as debug, error as error, info as info
+
+def repair_zip_file(file_path: str, destination: str) -> bool:
+    ''' Try to repair a corrupted zip file by ignoring some of the errors
+
+\tThis function manually parses the ZIP file structure to extract files
+\teven when the ZIP file is corrupted. It reads the central directory
+\tentries and attempts to decompress each file individually.
+
+\tArgs:
+\t\tfile_path\t\t(str):\tPath of the zip file to repair
+\t\tdestination\t\t(str):\tDestination of the new file
+\tReturns:
+\t\tbool: Always returns True unless any strong error
+
+\tExamples:
+
+\t.. code-block:: python
+
+\t\t> repair_zip_file("/path/to/source.zip", "/path/to/destination.zip")
+\t'''
+def make_archive(source: str, destinations: list[str] | str | None = None, override_time: None | tuple[int, int, int, int, int, int] = None, create_dir: bool = False, ignore_patterns: str | None = None) -> bool:
+    ''' Create a zip archive from a source directory with consistent file timestamps.
+\t(Meaning deterministic zip file each time)
+
+\tCreates a zip archive from the source directory and copies it to one or more destinations.
+\tThe archive will have consistent file timestamps across runs if override_time is specified.
+\tUses maximum compression level (9) with ZIP_DEFLATED algorithm.
+
+\tArgs:
+\t\tsource\t\t\t\t(str):\t\t\t\t\t\tThe source folder to archive
+\t\tdestinations\t\t(list[str]|str):\t\t\tThe destination folder(s) or file(s) to copy the archive to
+\t\toverride_time\t\t(None | tuple[int, ...]):\tThe constant time to use for the archive
+\t\t\t(e.g. (2024, 1, 1, 0, 0, 0) for 2024-01-01 00:00:00)
+\t\tcreate_dir\t\t\t(bool):\t\t\t\t\t\tWhether to create the destination directory if it doesn\'t exist
+\t\tignore_patterns\t\t(str | None):\t\t\t\tGlob pattern(s) to ignore files. Can be a single pattern or comma-separated patterns (e.g. "*.pyc" or "*.pyc,__pycache__,*.log")
+\tReturns:
+\t\tbool: Always returns True unless any strong error
+\tExamples:
+
+\t.. code-block:: python
+
+\t\t> make_archive("/path/to/source", "/path/to/destination.zip")
+\t\t> make_archive("/path/to/source", ["/path/to/destination.zip", "/path/to/destination2.zip"])
+\t\t> make_archive("src", "hello_from_year_2085.zip", override_time=(2085,1,1,0,0,0))
+\t\t> make_archive("src", "output.zip", ignore_patterns="*.pyc")
+\t\t> make_archive("src", "output.zip", ignore_patterns="__pycache__")
+\t\t> make_archive("src", "output.zip", ignore_patterns="*.pyc,__pycache__,*.log")
+\t'''
+def archive_cli() -> None:
+    ''' Main entry point for command line usage.
+
+\tExamples:
+
+\t.. code-block:: bash
+
+\t\t# Repair a corrupted zip file
+\t\tpython -m stouputils.archive repair /path/to/corrupted.zip /path/to/repaired.zip
+
+\t\t# Create a zip archive
+\t\tpython -m stouputils.archive make /path/to/source /path/to/destination.zip
+
+\t\t# Create a zip archive with ignore patterns
+\t\tpython -m stouputils.archive make /path/to/source /path/to/destination.zip --ignore "*.pyc,__pycache__"
+\t'''

{stouputils-1.5.4 → stouputils-1.6.1}/stouputils/backup.py

@@ -33,7 +33,7 @@ LARGE_CHUNK_SIZE = 8388608  # 8MB chunks for large file operations
 
 
 # Main entry point for command line usage
-def backup_cli():
+def backup_cli() -> None:
 	""" Main entry point for command line usage.
 
 	Examples:

stouputils-1.6.1/stouputils/backup.pyi

@@ -0,0 +1,109 @@
+import zipfile
+from .decorators import handle_error as handle_error, measure_time as measure_time
+from .io import clean_path as clean_path
+from .print import CYAN as CYAN, GREEN as GREEN, RESET as RESET, colored_for_loop as colored_for_loop, info as info, warning as warning
+
+CHUNK_SIZE: int
+LARGE_CHUNK_SIZE: int
+
+def backup_cli() -> None:
+    ''' Main entry point for command line usage.
+
+\tExamples:
+
+\t.. code-block:: bash
+
+\t\t# Create a delta backup, excluding libraries and cache folders
+\t\tpython -m stouputils.backup delta /path/to/source /path/to/backups -x "libraries/*" "cache/*"
+
+\t\t# Consolidate backups into a single file
+\t\tpython -m stouputils.backup consolidate /path/to/backups/latest.zip /path/to/consolidated.zip
+
+\t\t# Limit the number of delta backups to 5
+\t\tpython -m stouputils.backup limit 5 /path/to/backups
+\t'''
+def create_delta_backup(source_path: str, destination_folder: str, exclude_patterns: list[str] | None = None) -> None:
+    ''' Creates a ZIP delta backup, saving only modified or new files while tracking deleted files.
+
+\tArgs:
+\t\tsource_path (str): Path to the source file or directory to back up
+\t\tdestination_folder (str): Path to the folder where the backup will be saved
+\t\texclude_patterns (list[str] | None): List of glob patterns to exclude from backup
+\tExamples:
+
+\t.. code-block:: python
+
+\t\t> create_delta_backup("/path/to/source", "/path/to/backups", exclude_patterns=["libraries/*", "cache/*"])
+\t\t[INFO HH:MM:SS] Creating ZIP backup
+\t\t[INFO HH:MM:SS] Backup created: \'/path/to/backups/backup_2025_02_18-10_00_00.zip\'
+\t'''
+def consolidate_backups(zip_path: str, destination_zip: str) -> None:
+    ''' Consolidates the files from the given backup and all previous ones into a new ZIP file,
+\tensuring that the most recent version of each file is kept and deleted files are not restored.
+
+\tArgs:
+\t\tzip_path (str): Path to the latest backup ZIP file (If endswith "/latest.zip" or "/", the latest backup will be used)
+\t\tdestination_zip (str): Path to the destination ZIP file where the consolidated backup will be saved
+\tExamples:
+
+\t.. code-block:: python
+
+\t\t> consolidate_backups("/path/to/backups/latest.zip", "/path/to/consolidated.zip")
+\t\t[INFO HH:MM:SS] Consolidating backups
+\t\t[INFO HH:MM:SS] Consolidated backup created: \'/path/to/consolidated.zip\'
+\t'''
+def limit_backups(max_backups: int, backup_folder: str, keep_oldest: bool = True) -> None:
+    ''' Limits the number of delta backups by consolidating the oldest ones.
+
+\tIf the number of backups exceeds max_backups, the oldest backups are consolidated
+\tinto a single backup file, then deleted, until the count is within the limit.
+
+\tArgs:
+\t\tmax_backups (int): Maximum number of delta backups to keep
+\t\tbackup_folder (str): Path to the folder containing backups
+\t\tkeep_oldest (bool): If True, never delete the oldest backup (default: True)
+\tExamples:
+
+\t.. code-block:: python
+
+\t\t> limit_backups(5, "/path/to/backups")
+\t\t[INFO HH:MM:SS] Limiting backups
+\t\t[INFO HH:MM:SS] Consolidated 3 oldest backups into \'/path/to/backups/consolidated_YYYY_MM_DD-HH_MM_SS.zip\'
+\t\t[INFO HH:MM:SS] Deleted 3 old backups
+\t'''
+def get_file_hash(file_path: str) -> str | None:
+    """ Computes the SHA-256 hash of a file.
+
+\tArgs:
+\t\tfile_path (str): Path to the file
+\tReturns:
+\t\tstr | None: SHA-256 hash as a hexadecimal string or None if an error occurs
+\t"""
+def extract_hash_from_zipinfo(zip_info: zipfile.ZipInfo) -> str | None:
+    """ Extracts the stored hash from a ZipInfo object's comment.
+
+\tArgs:
+\t\tzip_info (zipfile.ZipInfo): The ZipInfo object representing a file in the ZIP
+\tReturns:
+\t\tstr | None: The stored hash if available, otherwise None
+\t"""
+def get_all_previous_backups(backup_folder: str, all_before: str | None = None) -> dict[str, dict[str, str]]:
+    ''' Retrieves all previous backups in a folder and maps each backup to a dictionary of file paths and their hashes.
+
+\tArgs:
+\t\tbackup_folder (str): The folder containing previous backup zip files
+\t\tall_before (str | None): Path to the latest backup ZIP file
+\t\t\t(If endswith "/latest.zip" or "/", the latest backup will be used)
+\tReturns:
+\t\tdict[str, dict[str, str]]: Dictionary mapping backup file paths to dictionaries of {file_path: file_hash}
+\t'''
+def is_file_in_any_previous_backup(file_path: str, file_hash: str, previous_backups: dict[str, dict[str, str]]) -> bool:
+    """ Checks if a file with the same hash exists in any previous backup.
+
+\tArgs:
+\t\tfile_path (str): The relative path of the file
+\t\tfile_hash (str): The SHA-256 hash of the file
+\t\tprevious_backups (dict[str, dict[str, str]]): Dictionary mapping backup zip paths to their stored file hashes
+\tReturns:
+\t\tbool: True if the file exists unchanged in any previous backup, False otherwise
+\t"""