stouputils 1.14.0__py3-none-any.whl → 1.14.2__py3-none-any.whl

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/_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.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__.pyi

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

stouputils/applications/automatic_docs.py

@@ -286,6 +286,7 @@ def get_versions_from_github(github_user: str, github_repo: str, recent_minor_ve
 					if d["type"] == "dir" and d["name"].startswith("v")
 				], key=version_to_float, reverse=True
 			)
+			info(f"Found versions from GitHub: {all_versions}")
 
 			# Group versions by major.minor
 			from collections import defaultdict
@@ -295,9 +296,11 @@ def get_versions_from_github(github_user: str, github_repo: str, recent_minor_ve
 				if len(parts) >= 2:
 					minor_key = f"{parts[0]}.{parts[1]}"
 					minor_versions[minor_key].append(version)
+			info(f"Grouped minor versions: {dict(minor_versions)}")
 
 			# Get the sorted minor version keys
 			sorted_minors = sorted(minor_versions.keys(), key=version_to_float, reverse=True)
+			info(f"Sorted minor versions: {sorted_minors}")
 
 			# Build final version list
 			final_versions: list[str] = []

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

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

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/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/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/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 CYAN as CYAN, GREEN as GREEN, RESET as RESET, 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/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"""

stouputils/collections.pyi

@@ -0,0 +1,86 @@
+import polars as pl
+import zarr
+from collections.abc import Iterable
+from numpy.typing import NDArray as NDArray
+from typing import Any, Literal, TypeVar
+
+T = TypeVar('T')
+
+def unique_list[T](list_to_clean: Iterable[T], method: Literal['id', 'hash', 'str'] = 'str') -> list[T]:
+    ''' Remove duplicates from the list while keeping the order using ids (default) or hash or str
+
+\tArgs:
+\t\tlist_to_clean\t(Iterable[T]):\t\t\t\t\tThe list to clean
+\t\tmethod\t\t\t(Literal["id", "hash", "str"]):\tThe method to use to identify duplicates
+\tReturns:
+\t\tlist[T]: The cleaned list
+
+\tExamples:
+\t\t>>> unique_list([1, 2, 3, 2, 1], method="id")
+\t\t[1, 2, 3]
+
+\t\t>>> s1 = {1, 2, 3}
+\t\t>>> s2 = {2, 3, 4}
+\t\t>>> s3 = {1, 2, 3}
+\t\t>>> unique_list([s1, s2, s1, s1, s3, s2, s3], method="id")
+\t\t[{1, 2, 3}, {2, 3, 4}, {1, 2, 3}]
+
+\t\t>>> s1 = {1, 2, 3}
+\t\t>>> s2 = {2, 3, 4}
+\t\t>>> s3 = {1, 2, 3}
+\t\t>>> unique_list([s1, s2, s1, s1, s3, s2, s3], method="str")
+\t\t[{1, 2, 3}, {2, 3, 4}]
+\t'''
+def sort_dict_keys[T](dictionary: dict[T, Any], order: list[T], reverse: bool = False) -> dict[T, Any]:
+    ''' Sort dictionary keys using a given order list (reverse optional)
+
+\tArgs:
+\t\tdictionary\t(dict[T, Any]):\tThe dictionary to sort
+\t\torder\t\t(list[T]):\t\tThe order list
+\t\treverse\t\t(bool):\t\t\tWhether to sort in reverse order (given to sorted function which behaves differently than order.reverse())
+\tReturns:
+\t\tdict[T, Any]: The sorted dictionary
+
+\tExamples:
+\t\t>>> sort_dict_keys({\'b\': 2, \'a\': 1, \'c\': 3}, order=["a", "b", "c"])
+\t\t{\'a\': 1, \'b\': 2, \'c\': 3}
+
+\t\t>>> sort_dict_keys({\'b\': 2, \'a\': 1, \'c\': 3}, order=["a", "b", "c"], reverse=True)
+\t\t{\'c\': 3, \'b\': 2, \'a\': 1}
+
+\t\t>>> sort_dict_keys({\'b\': 2, \'a\': 1, \'c\': 3, \'d\': 4}, order=["c", "b"])
+\t\t{\'c\': 3, \'b\': 2, \'a\': 1, \'d\': 4}
+\t'''
+def upsert_in_dataframe(df: pl.DataFrame, new_entry: dict[str, Any], primary_keys: dict[str, Any] | None = None) -> pl.DataFrame:
+    """ Insert or update a row in the Polars DataFrame based on primary keys.
+
+\tArgs:
+\t\tdf\t\t\t\t(pl.DataFrame):\t\tThe Polars DataFrame to update.
+\t\tnew_entry\t\t(dict[str, Any]):\tThe new entry to insert or update.
+\t\tprimary_keys\t(dict[str, Any]):\tThe primary keys to identify the row (default: empty).
+\tReturns:
+\t\tpl.DataFrame: The updated Polars DataFrame.
+\t"""
+def array_to_disk(data: NDArray[Any] | zarr.Array, delete_input: bool = True, more_data: NDArray[Any] | zarr.Array | None = None) -> tuple['zarr.Array', str, int]:
+    """ Easily handle large numpy arrays on disk using zarr for efficient storage and access.
+
+\tZarr provides a simpler and more efficient alternative to np.memmap with better compression
+\tand chunking capabilities.
+
+\tArgs:
+\t\tdata\t\t\t(NDArray | zarr.Array):\tThe data to save/load as a zarr array
+\t\tdelete_input\t(bool):\tWhether to delete the input data after creating the zarr array
+\t\tmore_data\t\t(NDArray | zarr.Array | None): Additional data to append to the zarr array
+\tReturns:
+\t\ttuple[zarr.Array, str, int]: The zarr array, the directory path, and the total size in bytes
+
+\tExamples:
+\t\t>>> import numpy as np
+\t\t>>> data = np.random.rand(1000, 1000)
+\t\t>>> zarr_array = array_to_disk(data)[0]
+\t\t>>> zarr_array.shape
+\t\t(1000, 1000)
+
+\t\t>>> more_data = np.random.rand(500, 1000)
+\t\t>>> longer_array, dir_path, total_size = array_to_disk(zarr_array, more_data=more_data)
+\t"""