stouputils 1.5.1__tar.gz → 1.5.2__tar.gz

{stouputils-1.5.1 → stouputils-1.5.2}/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2024 Alexandre Collignon
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+MIT License
+
+Copyright (c) 2024 Alexandre Collignon
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

{stouputils-1.5.1 → stouputils-1.5.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: stouputils
-Version: 1.5.1
+Version: 1.5.2
 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
@@ -117,9 +117,9 @@ It includes a range of tools for tasks such as execution of doctests, display ut
 ├── <a href="https://stoupy51.github.io/stouputils/latest/modules/stouputils.all_doctests.html">all_doctests.py</a>          <span class="comment"># ✅ Execution of all doctests for a given path</span>
 ├── <a href="https://stoupy51.github.io/stouputils/latest/modules/stouputils.archive.html">archive.py</a>               <span class="comment"># 📦 Archive utilities (zip, repair_zip)</span>
 ├── <a href="https://stoupy51.github.io/stouputils/latest/modules/stouputils.backup.html">backup.py</a>                <span class="comment"># 📦 Backup utilities (delta backup, consolidate)</span>
-├── <a href="https://stoupy51.github.io/stouputils/latest/modules/stouputils.collections.html">collections.py</a>           <span class="comment"># 🧰 Collection utilities (unique_list)</span>
+├── <a href="https://stoupy51.github.io/stouputils/latest/modules/stouputils.collections.html">collections.py</a>           <span class="comment"># 🧰 Collection utilities (unique_list, sort_dict_keys, array_to_disk)</span>
 ├── <a href="https://stoupy51.github.io/stouputils/latest/modules/stouputils.ctx.html">ctx.py</a>                   <span class="comment"># 🚫 Context managers (Muffle, LogToFile)</span>
-├── <a href="https://stoupy51.github.io/stouputils/latest/modules/stouputils.decorators.html">decorators.py</a>            <span class="comment"># 🎯 Decorators (silent, measure_time, error_handler, simple_cache)</span>
+├── <a href="https://stoupy51.github.io/stouputils/latest/modules/stouputils.decorators.html">decorators.py</a>            <span class="comment"># 🎯 Decorators (silent, measure_time, error_handler, simple_cache, retry)</span>
 ├── <a href="https://stoupy51.github.io/stouputils/latest/modules/stouputils.image.html">image.py</a>                 <span class="comment"># 🖼️ Image utilities (image_resize)</span>
 ├── <a href="https://stoupy51.github.io/stouputils/latest/modules/stouputils.io.html">io.py</a>                    <span class="comment"># 💻 I/O utilities (file management, json)</span>
 ├── <a href="https://stoupy51.github.io/stouputils/latest/modules/stouputils.parallel.html">parallel.py</a>              <span class="comment"># 🧑‍🤝‍🧑 Parallel processing (multiprocessing, multithreading)</span>

{stouputils-1.5.1 → stouputils-1.5.2}/README.md

@@ -77,9 +77,9 @@ It includes a range of tools for tasks such as execution of doctests, display ut
 ├── <a href="https://stoupy51.github.io/stouputils/latest/modules/stouputils.all_doctests.html">all_doctests.py</a>          <span class="comment"># ✅ Execution of all doctests for a given path</span>
 ├── <a href="https://stoupy51.github.io/stouputils/latest/modules/stouputils.archive.html">archive.py</a>               <span class="comment"># 📦 Archive utilities (zip, repair_zip)</span>
 ├── <a href="https://stoupy51.github.io/stouputils/latest/modules/stouputils.backup.html">backup.py</a>                <span class="comment"># 📦 Backup utilities (delta backup, consolidate)</span>
-├── <a href="https://stoupy51.github.io/stouputils/latest/modules/stouputils.collections.html">collections.py</a>           <span class="comment"># 🧰 Collection utilities (unique_list)</span>
+├── <a href="https://stoupy51.github.io/stouputils/latest/modules/stouputils.collections.html">collections.py</a>           <span class="comment"># 🧰 Collection utilities (unique_list, sort_dict_keys, array_to_disk)</span>
 ├── <a href="https://stoupy51.github.io/stouputils/latest/modules/stouputils.ctx.html">ctx.py</a>                   <span class="comment"># 🚫 Context managers (Muffle, LogToFile)</span>
-├── <a href="https://stoupy51.github.io/stouputils/latest/modules/stouputils.decorators.html">decorators.py</a>            <span class="comment"># 🎯 Decorators (silent, measure_time, error_handler, simple_cache)</span>
+├── <a href="https://stoupy51.github.io/stouputils/latest/modules/stouputils.decorators.html">decorators.py</a>            <span class="comment"># 🎯 Decorators (silent, measure_time, error_handler, simple_cache, retry)</span>
 ├── <a href="https://stoupy51.github.io/stouputils/latest/modules/stouputils.image.html">image.py</a>                 <span class="comment"># 🖼️ Image utilities (image_resize)</span>
 ├── <a href="https://stoupy51.github.io/stouputils/latest/modules/stouputils.io.html">io.py</a>                    <span class="comment"># 💻 I/O utilities (file management, json)</span>
 ├── <a href="https://stoupy51.github.io/stouputils/latest/modules/stouputils.parallel.html">parallel.py</a>              <span class="comment"># 🧑‍🤝‍🧑 Parallel processing (multiprocessing, multithreading)</span>

{stouputils-1.5.1 → stouputils-1.5.2}/pyproject.toml

@@ -5,7 +5,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "stouputils"
-version = "1.5.1"
+version = "1.5.2"
 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"

stouputils-1.5.2/stouputils/__main__.py

@@ -0,0 +1,58 @@
+
+
+# Imports
+import sys
+
+from .all_doctests import launch_tests
+from .backup import backup_cli
+from .decorators import handle_error
+from .print import CYAN, GREEN, RESET, show_version
+
+
+@handle_error(message="Error while running 'stouputils'")
+def main():
+	second_arg: str = sys.argv[1].lower() if len(sys.argv) >= 2 else ""
+	if not second_arg:
+		# 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}")
+		print(f"{CYAN}stouputils {GREEN}CLI {CYAN}v{pkg_version}{RESET}")
+		print(f"{CYAN}{separator}{RESET}")
+		print(f"\n{CYAN}Usage:{RESET} stouputils <command> [options]")
+		print(f"\n{CYAN}Available commands:{RESET}")
+		print(f"  {GREEN}--version, -v{RESET}       Show version information")
+		print(f"  {GREEN}all_doctests{RESET} [dir]  Run all doctests in the specified directory")
+		print(f"  {GREEN}backup{RESET} --help       Backup utilities (delta, consolidate, limit)")
+		print(f"{CYAN}{separator}{RESET}")
+		return
+
+	# Print the version of stouputils and its dependencies
+	if second_arg in ("--version","-v"):
+		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 "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
+
+
+if __name__ == "__main__":
+	main()
+

{stouputils-1.5.1 → stouputils-1.5.2}/stouputils/backup.py

@@ -4,6 +4,7 @@ This module provides utilities for backup management.
 - backup_cli: Main entry point for command line usage
 - create_delta_backup: Creates a ZIP delta backup, saving only modified or new files while tracking deleted files
 - consolidate_backups: Consolidates the files from the given backup and all previous ones into a new ZIP file
+- limit_backups: Limits the number of delta backups by consolidating the oldest ones
 - get_file_hash: Computes the SHA-256 hash of a file
 - extract_hash_from_zipinfo: Extracts the stored hash from a ZipInfo object's comment
 - get_all_previous_backups: Retrieves all previous backups in a folder and maps each backup to a dictionary of file paths and their hashes
@@ -24,7 +25,7 @@ import zipfile
 # Local imports
 from .decorators import handle_error, measure_time
 from .io import clean_path
-from .print import colored_for_loop, info, progress, warning
+from .print import CYAN, GREEN, RESET, colored_for_loop, info, warning
 
 # Constants
 CHUNK_SIZE = 1048576  # 1MB chunks for I/O operations
@@ -32,7 +33,6 @@ LARGE_CHUNK_SIZE = 8388608  # 8MB chunks for large file operations
 
 
 # Main entry point for command line usage
-@measure_time(progress)
 def backup_cli():
 	""" Main entry point for command line usage.
 
@@ -45,14 +45,22 @@ def backup_cli():
 
 		# Consolidate backups into a single file
 		python -m stouputils.backup consolidate /path/to/backups/latest.zip /path/to/consolidated.zip
+
+		# Limit the number of delta backups to 5
+		python -m stouputils.backup limit 5 /path/to/backups
 	"""
 	import argparse
 
 	# Setup command line argument parser
 	parser: argparse.ArgumentParser = argparse.ArgumentParser(
-		description="Backup and consolidate files using delta compression."
+		description="Backup and consolidate files using delta compression.",
+		formatter_class=argparse.RawDescriptionHelpFormatter,
+		epilog=f"""{CYAN}Examples:{RESET}
+  stouputils backup delta /path/to/source /path/to/backups -x "*.pyc"
+  stouputils backup consolidate /path/to/backups/latest.zip /path/to/output.zip
+  stouputils backup limit 5 /path/to/backups"""
 	)
-	subparsers = parser.add_subparsers(dest="command", required=True)
+	subparsers = parser.add_subparsers(dest="command", required=False)
 
 	# Create delta command and its arguments
 	delta_psr = subparsers.add_parser("delta", help="Create a new delta backup")
@@ -65,13 +73,37 @@ def backup_cli():
 	consolidate_psr.add_argument("backup_zip", type=str, help="Path to the latest backup ZIP file")
 	consolidate_psr.add_argument("destination_zip", type=str, help="Path to the destination consolidated ZIP file")
 
+	# Create limit command and its arguments
+	limit_psr = subparsers.add_parser("limit", help="Limit the number of delta backups by consolidating the oldest ones")
+	limit_psr.add_argument("max_backups", type=int, help="Maximum number of delta backups to keep")
+	limit_psr.add_argument("backup_folder", type=str, help="Path to the folder containing backups")
+	limit_psr.add_argument("--no-keep-oldest", dest="keep_oldest", action="store_false", default=True, help="Allow deletion of the oldest backup (default: keep it)")
+
 	# Parse arguments and execute appropriate command
 	args: argparse.Namespace = parser.parse_args()
 
+	# Show custom help if no command is provided
+	if not args.command:
+		separator: str = "─" * 60
+		print(f"{CYAN}{separator}{RESET}")
+		print(f"{CYAN}Backup Utilities{RESET}")
+		print(f"{CYAN}{separator}{RESET}")
+		print(f"\n{CYAN}Usage:{RESET} stouputils backup <command> [options]")
+		print(f"\n{CYAN}Available commands:{RESET}")
+		print(f"  {GREEN}delta{RESET}         Create a new delta backup")
+		print(f"  {GREEN}consolidate{RESET}   Consolidate existing backups into one")
+		print(f"  {GREEN}limit{RESET}         Limit the number of delta backups")
+		print(f"\n{CYAN}For detailed help on a specific command:{RESET}")
+		print("  stouputils backup <command> --help")
+		print(f"{CYAN}{separator}{RESET}")
+		return
+
 	if args.command == "delta":
 		create_delta_backup(args.source, args.destination, args.exclude)
 	elif args.command == "consolidate":
 		consolidate_backups(args.backup_zip, args.destination_zip)
+	elif args.command == "limit":
+		limit_backups(args.max_backups, args.backup_folder, keep_oldest=args.keep_oldest)
 
 # Main backup function that creates a delta backup (only changed files)
 @measure_time(message="Creating ZIP backup")
@@ -263,6 +295,10 @@ def consolidate_backups(zip_path: str, destination_zip: str) -> None:
 				except Exception as e:
 					warning(f"Error copying file {filename} from {backup_path}: {e}")
 					continue
+
+			# Add accumulated deleted files to the consolidated backup
+			if deleted_files:
+				zipf_out.writestr("__deleted_files__.txt", "\n".join(sorted(deleted_files)), compress_type=zipfile.ZIP_DEFLATED)
 	finally:
 		# Clean up open ZIP files
 		for zipf in open_zips.values():
@@ -273,6 +309,84 @@ def consolidate_backups(zip_path: str, destination_zip: str) -> None:
 
 	info(f"Consolidated backup created: {destination_zip}")
 
+# Function to limit the number of delta backups by consolidating the oldest ones
+@measure_time(message="Limiting backups")
+@handle_error()
+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.
+
+	If the number of backups exceeds max_backups, the oldest backups are consolidated
+	into a single backup file, then deleted, until the count is within the limit.
+
+	Args:
+		max_backups (int): Maximum number of delta backups to keep
+		backup_folder (str): Path to the folder containing backups
+		keep_oldest (bool): If True, never delete the oldest backup (default: True)
+	Examples:
+
+	.. code-block:: python
+
+		> limit_backups(5, "/path/to/backups")
+		[INFO HH:MM:SS] Limiting backups
+		[INFO HH:MM:SS] Consolidated 3 oldest backups into '/path/to/backups/consolidated_YYYY_MM_DD-HH_MM_SS.zip'
+		[INFO HH:MM:SS] Deleted 3 old backups
+	"""
+	backup_folder = clean_path(os.path.abspath(backup_folder))
+	if max_backups < 1:
+		raise ValueError("max_backups must be at least 1")
+
+	# Get all backup files sorted by date (oldest first), including consolidated ones
+	# Sort by timestamp (removing "consolidated_" prefix for proper chronological ordering)
+	def get_sort_key(filename: str) -> str:
+		basename = os.path.basename(filename)
+		return basename.replace("consolidated_", "")
+
+	backup_files: list[str] = sorted([
+		clean_path(os.path.join(backup_folder, f))
+		for f in os.listdir(backup_folder)
+		if f.endswith(".zip")
+	], key=get_sort_key)
+
+	backup_count: int = len(backup_files)
+
+	# Check if we need to consolidate
+	if backup_count <= max_backups:
+		info(f"Current backup count ({backup_count}) is within limit ({max_backups}). No action needed.")
+		return
+
+	# Calculate how many backups to consolidate
+	num_to_consolidate: int = backup_count - max_backups + 1
+
+	# If keep_oldest is True, exclude the oldest backup from consolidation
+	if keep_oldest and backup_count > 1:
+		# Start from index 1 instead of 0 to skip the oldest backup
+		backups_to_consolidate: list[str] = backup_files[1:num_to_consolidate+1]
+	else:
+		backups_to_consolidate: list[str] = backup_files[:num_to_consolidate]
+
+	latest_to_consolidate: str = backups_to_consolidate[-1]
+
+	info(f"Found {backup_count} backups, consolidating {num_to_consolidate} oldest backups...")
+
+	# Extract timestamp from the most recent backup being consolidated (last in list)
+	latest_backup: str = os.path.basename(backups_to_consolidate[-1])
+	latest_timestamp: str = latest_backup.replace("consolidated_", "").replace(".zip", "")
+
+	# Create consolidated backup filename with the most recent consolidated backup's timestamp
+	consolidated_filename: str = f"consolidated_{latest_timestamp}.zip"
+	consolidated_path: str = clean_path(os.path.join(backup_folder, consolidated_filename))	# Consolidate the oldest backups
+	consolidate_backups(latest_to_consolidate, consolidated_path)
+
+	# Delete the old backups that were consolidated
+	for backup_path in backups_to_consolidate:
+		try:
+			os.remove(backup_path)
+			info(f"Deleted old backup: {os.path.basename(backup_path)}")
+		except Exception as e:
+			warning(f"Error deleting backup {backup_path}: {e}")
+
+	info(f"Successfully limited backups to {max_backups}. Consolidated backup: {consolidated_filename}")
+
 # Function to compute the SHA-256 hash of a file
 def get_file_hash(file_path: str) -> str | None:
 	""" Computes the SHA-256 hash of a file.

{stouputils-1.5.1 → stouputils-1.5.2}/stouputils/collections.py

@@ -2,6 +2,7 @@
 This module provides utilities for collection manipulation:
 
 - unique_list: Remove duplicates from a list while preserving order using object id, hash or str
+- sort_dict_keys: Sort dictionary keys using a given order list (ascending or descending)
 - array_to_disk: Easily handle large numpy arrays on disk using zarr for efficient storage and access.
 
 .. image:: https://raw.githubusercontent.com/Stoupy51/stouputils/refs/heads/main/assets/collections_module.gif
@@ -13,12 +14,14 @@ import atexit
 import os
 import shutil
 import tempfile
-from typing import Any, Literal
+from typing import Any, Literal, TypeVar
 
 import numpy as np
 import zarr  # pyright: ignore[reportMissingTypeStubs]
 from numpy.typing import NDArray
 
+# Typing
+T = TypeVar("T")
 
 # Functions
 def unique_list(list_to_clean: list[Any], method: Literal["id", "hash", "str"] = "str") -> list[Any]:
@@ -69,6 +72,28 @@ def unique_list(list_to_clean: list[Any], method: Literal["id", "hash", "str"] =
 	# Return the cleaned list
 	return result
 
+def sort_dict_keys(dictionary: dict[T, Any], order: list[T], reverse: bool = False) -> dict[T, Any]:
+	""" Sort dictionary keys using a given order list (reverse optional)
+
+	Args:
+		dictionary	(dict[T, Any]):	The dictionary to sort
+		order		(list[T]):		The order list
+		reverse		(bool):			Whether to sort in reverse order (given to sorted function which behaves differently than order.reverse())
+	Returns:
+		dict[T, Any]: The sorted dictionary
+
+	Examples:
+		>>> sort_dict_keys({'b': 2, 'a': 1, 'c': 3}, order=["a", "b", "c"])
+		{'a': 1, 'b': 2, 'c': 3}
+
+		>>> sort_dict_keys({'b': 2, 'a': 1, 'c': 3}, order=["a", "b", "c"], reverse=True)
+		{'c': 3, 'b': 2, 'a': 1}
+
+		>>> sort_dict_keys({'b': 2, 'a': 1, 'c': 3, 'd': 4}, order=["c", "b"])
+		{'c': 3, 'b': 2, 'a': 1, 'd': 4}
+	"""
+	return dict(sorted(dictionary.items(), key=lambda x: order.index(x[0]) if x[0] in order else len(order), reverse=reverse))
+
 def array_to_disk(
 	data: NDArray[Any] | zarr.Array,
 	delete_input: bool = True,

{stouputils-1.5.1 → stouputils-1.5.2}/stouputils/continuous_delivery/__init__.py

@@ -1,25 +1,25 @@
-""" Continuous delivery and deployment utilities.
-
-This module provides tools for automating software delivery and deployment:
-
-Key Features:
-- GitHub release management and uploads
-- PyPI package publishing utilities
-- pyproject.toml file management
-- Common CD/CI utilities
-
-Components:
-- cd_utils: Common utilities for continuous delivery
-- github: GitHub-specific utilities (upload_to_github)
-- pypi: PyPI publishing tools (pypi_full_routine)
-- pyproject: pyproject.toml file management
-
-"""
-# ruff: noqa: F403
-
-# Imports
-from .cd_utils import *
-from .github import *
-from .pypi import *
-from .pyproject import *
-
+""" Continuous delivery and deployment utilities.
+
+This module provides tools for automating software delivery and deployment:
+
+Key Features:
+- GitHub release management and uploads
+- PyPI package publishing utilities
+- pyproject.toml file management
+- Common CD/CI utilities
+
+Components:
+- cd_utils: Common utilities for continuous delivery
+- github: GitHub-specific utilities (upload_to_github)
+- pypi: PyPI publishing tools (pypi_full_routine)
+- pyproject: pyproject.toml file management
+
+"""
+# ruff: noqa: F403
+
+# Imports
+from .cd_utils import *
+from .github import *
+from .pypi import *
+from .pyproject import *
+