PyPI - stouputils - Versions diffs - 1.5.0__tar.gz → 1.5.2__tar.gz - Mend

stouputils 1.5.0tar.gz → 1.5.2tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (108) hide show

{stouputils-1.5.0 → stouputils-1.5.2}/PKG-INFO RENAMED Viewed

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: stouputils
-Version: 1.5.0
+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.0 → stouputils-1.5.2}/README.md RENAMED Viewed

@@ -1,102 +1,102 @@
-# 🛠️ Project Badges
-[![GitHub](https://img.shields.io/github/v/release/Stoupy51/stouputils?logo=github&label=GitHub)](https://github.com/Stoupy51/stouputils/releases/latest)
-[![PyPI - Downloads](https://img.shields.io/pypi/dm/stouputils?logo=python&label=PyPI%20downloads)](https://pypi.org/project/stouputils/)
-[![Documentation](https://img.shields.io/github/v/release/Stoupy51/stouputils?logo=sphinx&label=Documentation&color=purple)](https://stoupy51.github.io/stouputils/latest/)
-<br>
-# 📚 Project Overview
-Stouputils is a collection of utility modules designed to simplify and enhance the development process.<br>
-It includes a range of tools for tasks such as execution of doctests, display utilities, decorators, as well as context managers.
-# 🚀 Project File Tree
-<html>
-<details style="display: none;">
-<summary></summary>
-<style>
-.code-tree {
-	border-radius: 6px;
-	padding: 16px;
-	font-family: monospace;
-	line-height: 1.45;
-	overflow: auto;
-	white-space: pre;
-	background-color:rgb(43, 43, 43);
-	color: #d4d4d4;
-}
-.code-tree a {
-	color: #569cd6;
-	text-decoration: none;
-}
-.code-tree a:hover {
-	text-decoration: underline;
-}
-.code-tree .comment {
-	color:rgb(231, 213, 48);
-}
-</style>
-</details>
-<pre class="code-tree">stouputils/
-├── <a href="https://stoupy51.github.io/stouputils/latest/modules/stouputils.applications.html">applications/</a>
-│   ├── <a href="https://stoupy51.github.io/stouputils/latest/modules/stouputils.applications.automatic_docs.html">automatic_docs.py</a>    <span class="comment"># 📚 Documentation generation utilities (used to create this documentation)</span>
-│   ├── <a href="https://stoupy51.github.io/stouputils/latest/modules/stouputils.applications.upscaler.html">upscaler/</a>            <span class="comment"># 🔎 Image & Video upscaler (configurable)</span>
-│   └── ...
-│
-├── <a href="https://stoupy51.github.io/stouputils/latest/modules/stouputils.continuous_delivery.html">continuous_delivery/</a>
-│   ├── <a href="https://stoupy51.github.io/stouputils/latest/modules/stouputils.continuous_delivery.cd_utils.html">cd_utils.py</a>          <span class="comment"># 🔧 Common utilities for continuous delivery</span>
-│   ├── <a href="https://stoupy51.github.io/stouputils/latest/modules/stouputils.continuous_delivery.github.html">github.py</a>            <span class="comment"># 📦 GitHub utilities (upload_to_github)</span>
-│   ├── <a href="https://stoupy51.github.io/stouputils/latest/modules/stouputils.continuous_delivery.pypi.html">pypi.py</a>              <span class="comment"># 📦 PyPI utilities (pypi_full_routine)</span>
-│   ├── <a href="https://stoupy51.github.io/stouputils/latest/modules/stouputils.continuous_delivery.pyproject.html">pyproject.py</a>         <span class="comment"># 📝 Pyproject.toml utilities</span>
-│   └── ...
-│
-├── <a href="https://stoupy51.github.io/stouputils/latest/modules/stouputils.data_science.html">data_science/</a>
-│   ├── <a href="https://stoupy51.github.io/stouputils/latest/modules/stouputils.data_science.config.html">config/</a>              <span class="comment"># ⚙️ Configuration utilities for data science</span>
-│   ├── <a href="https://stoupy51.github.io/stouputils/latest/modules/stouputils.data_science.dataset.html">dataset/</a>             <span class="comment"># 📊 Dataset handling (dataset, dataset_loader, grouping_strategy)</span>
-│   ├── <a href="https://stoupy51.github.io/stouputils/latest/modules/stouputils.data_science.data_processing.html">data_processing/</a>     <span class="comment"># 🔄 Data processing utilities (image augmentation, preprocessing)</span>
-│   │   ├── <a href="https://stoupy51.github.io/stouputils/latest/modules/stouputils.data_science.data_processing.image.html">image/</a>           <span class="comment"># 🖼️ Image processing techniques</span>
-│   │   └── ...
-│   ├── <a href="https://stoupy51.github.io/stouputils/latest/modules/stouputils.data_science.models.html">models/</a>              <span class="comment"># 🧠 ML/DL model interfaces and implementations</span>
-│   │   ├── <a href="https://stoupy51.github.io/stouputils/latest/modules/stouputils.data_science.models.keras.html">keras/</a>           <span class="comment"># 🤖 Keras model implementations</span>
-│   │   ├── <a href="https://stoupy51.github.io/stouputils/latest/modules/stouputils.data_science.models.keras_utils.html">keras_utils/</a>     <span class="comment"># 🛠️ Keras utilities (callbacks, losses, visualizations)</span>
-│   │   └── ...
-│   ├── <a href="https://stoupy51.github.io/stouputils/latest/modules/stouputils.data_science.scripts.html">scripts/</a>             <span class="comment"># 📜 Data science scripts (augment, preprocess, routine)</span>
-│   ├── <a href="https://stoupy51.github.io/stouputils/latest/modules/stouputils.data_science.metric_utils.html">metric_utils.py</a>      <span class="comment"># 📏 Metrics utilities for ML/DL models</span>
-│   ├── <a href="https://stoupy51.github.io/stouputils/latest/modules/stouputils.data_science.mlflow_utils.html">mlflow_utils.py</a>      <span class="comment"># 📊 MLflow integration utilities</span>
-│   └── ...
-│
-├── <a href="https://stoupy51.github.io/stouputils/latest/modules/stouputils.installer.html">installer/</a>
-│   ├── <a href="https://stoupy51.github.io/stouputils/latest/modules/stouputils.installer.common.html">common.py</a>            <span class="comment"># 🔧 Common installer utilities</span>
-│   ├── <a href="https://stoupy51.github.io/stouputils/latest/modules/stouputils.installer.downloader.html">downloader.py</a>        <span class="comment"># ⬇️ File download utilities</span>
-│   ├── <a href="https://stoupy51.github.io/stouputils/latest/modules/stouputils.installer.linux.html">linux.py</a>             <span class="comment"># 🐧 Linux-specific installer utilities</span>
-│   ├── <a href="https://stoupy51.github.io/stouputils/latest/modules/stouputils.installer.main.html">main.py</a>              <span class="comment"># 🚀 Main installer functionality</span>
-│   ├── <a href="https://stoupy51.github.io/stouputils/latest/modules/stouputils.installer.windows.html">windows.py</a>           <span class="comment"># 💻 Windows-specific installer utilities</span>
-│   └── ...
-│
-├── <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.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.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>
-├── <a href="https://stoupy51.github.io/stouputils/latest/modules/stouputils.print.html">print.py</a>                 <span class="comment"># 🖨️ Display utilities (info, debug, warning, error)</span>
-└── ...
-</pre>
-</html>
-## ⭐ Star History
-<html>
-	<a href="https://star-history.com/#Stoupy51/stouputils&Date">
-		<picture>
-			<source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/svg?repos=Stoupy51/stouputils&type=Date&theme=dark" />
-			<source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/svg?repos=Stoupy51/stouputils&type=Date" />
-			<img alt="Star History Chart" src="https://api.star-history.com/svg?repos=Stoupy51/stouputils&type=Date" />
-		</picture>
-	</a>
-</html>
+# 🛠️ Project Badges
+[![GitHub](https://img.shields.io/github/v/release/Stoupy51/stouputils?logo=github&label=GitHub)](https://github.com/Stoupy51/stouputils/releases/latest)
+[![PyPI - Downloads](https://img.shields.io/pypi/dm/stouputils?logo=python&label=PyPI%20downloads)](https://pypi.org/project/stouputils/)
+[![Documentation](https://img.shields.io/github/v/release/Stoupy51/stouputils?logo=sphinx&label=Documentation&color=purple)](https://stoupy51.github.io/stouputils/latest/)
+<br>
+# 📚 Project Overview
+Stouputils is a collection of utility modules designed to simplify and enhance the development process.<br>
+It includes a range of tools for tasks such as execution of doctests, display utilities, decorators, as well as context managers.
+# 🚀 Project File Tree
+<html>
+<details style="display: none;">
+<summary></summary>
+<style>
+.code-tree {
+	border-radius: 6px;
+	padding: 16px;
+	font-family: monospace;
+	line-height: 1.45;
+	overflow: auto;
+	white-space: pre;
+	background-color:rgb(43, 43, 43);
+	color: #d4d4d4;
+}
+.code-tree a {
+	color: #569cd6;
+	text-decoration: none;
+}
+.code-tree a:hover {
+	text-decoration: underline;
+}
+.code-tree .comment {
+	color:rgb(231, 213, 48);
+}
+</style>
+</details>
+<pre class="code-tree">stouputils/
+├── <a href="https://stoupy51.github.io/stouputils/latest/modules/stouputils.applications.html">applications/</a>
+│   ├── <a href="https://stoupy51.github.io/stouputils/latest/modules/stouputils.applications.automatic_docs.html">automatic_docs.py</a>    <span class="comment"># 📚 Documentation generation utilities (used to create this documentation)</span>
+│   ├── <a href="https://stoupy51.github.io/stouputils/latest/modules/stouputils.applications.upscaler.html">upscaler/</a>            <span class="comment"># 🔎 Image & Video upscaler (configurable)</span>
+│   └── ...
+│
+├── <a href="https://stoupy51.github.io/stouputils/latest/modules/stouputils.continuous_delivery.html">continuous_delivery/</a>
+│   ├── <a href="https://stoupy51.github.io/stouputils/latest/modules/stouputils.continuous_delivery.cd_utils.html">cd_utils.py</a>          <span class="comment"># 🔧 Common utilities for continuous delivery</span>
+│   ├── <a href="https://stoupy51.github.io/stouputils/latest/modules/stouputils.continuous_delivery.github.html">github.py</a>            <span class="comment"># 📦 GitHub utilities (upload_to_github)</span>
+│   ├── <a href="https://stoupy51.github.io/stouputils/latest/modules/stouputils.continuous_delivery.pypi.html">pypi.py</a>              <span class="comment"># 📦 PyPI utilities (pypi_full_routine)</span>
+│   ├── <a href="https://stoupy51.github.io/stouputils/latest/modules/stouputils.continuous_delivery.pyproject.html">pyproject.py</a>         <span class="comment"># 📝 Pyproject.toml utilities</span>
+│   └── ...
+│
+├── <a href="https://stoupy51.github.io/stouputils/latest/modules/stouputils.data_science.html">data_science/</a>
+│   ├── <a href="https://stoupy51.github.io/stouputils/latest/modules/stouputils.data_science.config.html">config/</a>              <span class="comment"># ⚙️ Configuration utilities for data science</span>
+│   ├── <a href="https://stoupy51.github.io/stouputils/latest/modules/stouputils.data_science.dataset.html">dataset/</a>             <span class="comment"># 📊 Dataset handling (dataset, dataset_loader, grouping_strategy)</span>
+│   ├── <a href="https://stoupy51.github.io/stouputils/latest/modules/stouputils.data_science.data_processing.html">data_processing/</a>     <span class="comment"># 🔄 Data processing utilities (image augmentation, preprocessing)</span>
+│   │   ├── <a href="https://stoupy51.github.io/stouputils/latest/modules/stouputils.data_science.data_processing.image.html">image/</a>           <span class="comment"># 🖼️ Image processing techniques</span>
+│   │   └── ...
+│   ├── <a href="https://stoupy51.github.io/stouputils/latest/modules/stouputils.data_science.models.html">models/</a>              <span class="comment"># 🧠 ML/DL model interfaces and implementations</span>
+│   │   ├── <a href="https://stoupy51.github.io/stouputils/latest/modules/stouputils.data_science.models.keras.html">keras/</a>           <span class="comment"># 🤖 Keras model implementations</span>
+│   │   ├── <a href="https://stoupy51.github.io/stouputils/latest/modules/stouputils.data_science.models.keras_utils.html">keras_utils/</a>     <span class="comment"># 🛠️ Keras utilities (callbacks, losses, visualizations)</span>
+│   │   └── ...
+│   ├── <a href="https://stoupy51.github.io/stouputils/latest/modules/stouputils.data_science.scripts.html">scripts/</a>             <span class="comment"># 📜 Data science scripts (augment, preprocess, routine)</span>
+│   ├── <a href="https://stoupy51.github.io/stouputils/latest/modules/stouputils.data_science.metric_utils.html">metric_utils.py</a>      <span class="comment"># 📏 Metrics utilities for ML/DL models</span>
+│   ├── <a href="https://stoupy51.github.io/stouputils/latest/modules/stouputils.data_science.mlflow_utils.html">mlflow_utils.py</a>      <span class="comment"># 📊 MLflow integration utilities</span>
+│   └── ...
+│
+├── <a href="https://stoupy51.github.io/stouputils/latest/modules/stouputils.installer.html">installer/</a>
+│   ├── <a href="https://stoupy51.github.io/stouputils/latest/modules/stouputils.installer.common.html">common.py</a>            <span class="comment"># 🔧 Common installer utilities</span>
+│   ├── <a href="https://stoupy51.github.io/stouputils/latest/modules/stouputils.installer.downloader.html">downloader.py</a>        <span class="comment"># ⬇️ File download utilities</span>
+│   ├── <a href="https://stoupy51.github.io/stouputils/latest/modules/stouputils.installer.linux.html">linux.py</a>             <span class="comment"># 🐧 Linux-specific installer utilities</span>
+│   ├── <a href="https://stoupy51.github.io/stouputils/latest/modules/stouputils.installer.main.html">main.py</a>              <span class="comment"># 🚀 Main installer functionality</span>
+│   ├── <a href="https://stoupy51.github.io/stouputils/latest/modules/stouputils.installer.windows.html">windows.py</a>           <span class="comment"># 💻 Windows-specific installer utilities</span>
+│   └── ...
+│
+├── <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, 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, 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>
+├── <a href="https://stoupy51.github.io/stouputils/latest/modules/stouputils.print.html">print.py</a>                 <span class="comment"># 🖨️ Display utilities (info, debug, warning, error)</span>
+└── ...
+</pre>
+</html>
+## ⭐ Star History
+<html>
+	<a href="https://star-history.com/#Stoupy51/stouputils&Date">
+		<picture>
+			<source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/svg?repos=Stoupy51/stouputils&type=Date&theme=dark" />
+			<source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/svg?repos=Stoupy51/stouputils&type=Date" />
+			<img alt="Star History Chart" src="https://api.star-history.com/svg?repos=Stoupy51/stouputils&type=Date" />
+		</picture>
+	</a>
+</html>

{stouputils-1.5.0 → stouputils-1.5.2}/pyproject.toml RENAMED Viewed

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

@@ -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.0 → stouputils-1.5.2}/stouputils/backup.py RENAMED Viewed

@@ -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.0 → stouputils-1.5.2}/stouputils/collections.py RENAMED Viewed

@@ -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.0 → stouputils-1.5.2}/stouputils/decorators.py RENAMED Viewed

@@ -233,16 +233,18 @@ def retry(
 	exceptions: tuple[type[BaseException], ...] | type[BaseException] = (Exception,),
 	max_attempts: int = 10,
 	delay: float = 1.0,
-	backoff: float = 1.0
+	backoff: float = 1.0,
+	message: str = ""
 ) -> Callable[..., Any]:
 	""" Decorator that retries a function when specific exceptions are raised.
 	Args:
-		func			(Callable[..., Any] | None):			Function to retry
-		exceptions		(tuple[type[BaseException], ...]):		Exceptions to catch and retry on
-		max_attempts	(int | None):							Maximum number of attempts (None for infinite retries)
-		delay			(float):								Initial delay in seconds between retries (default: 1.0)
-		backoff			(float):								Multiplier for delay after each retry (default: 1.0 for constant delay)
+		func			(Callable[..., Any] | None):		Function to retry
+		exceptions		(tuple[type[BaseException], ...]):	Exceptions to catch and retry on
+		max_attempts	(int | None):						Maximum number of attempts (None for infinite retries)
+		delay			(float):							Initial delay in seconds between retries (default: 1.0)
+		backoff			(float):							Multiplier for delay after each retry (default: 1.0 for constant delay)
+		message			(str):								Custom message to display before ", retrying" (default: "{ExceptionName} encountered while running {func_name}")
 	Returns:
 		Callable[..., Any]: Decorator that retries the function on specified exceptions
@@ -282,7 +284,10 @@ def retry(
 						raise e
 					# Log retry attempt
-					warning(f"{type(e).__name__} encountered while running {_get_func_name(func)}, retrying ({attempt + 1}/{max_attempts}): {e}")
+					if message:
+						warning(f"{message}, retrying ({attempt + 1}/{max_attempts}): {e}")
+					else:
+						warning(f"{type(e).__name__} encountered while running {_get_func_name(func)}, retrying ({attempt + 1}/{max_attempts}): {e}")
 					# Wait before next attempt
 					time.sleep(current_delay)

stouputils-1.5.0/stouputils/__main__.py DELETED Viewed

@@ -1,35 +0,0 @@
-# Imports
-import sys
-from .all_doctests import launch_tests
-from .decorators import handle_error
-from .print import 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:
-		# TODO
-		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
-	# Check if the command is any package name
-	if second_arg in (): # type: ignore
-		return
-if __name__ == "__main__":
-	main()