Create a delta backup

June 23, 2026 · View on GitHub

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.
Start now by installing the package: pip install stouputils.

📖 Want to see examples? Check out our Google Colab notebook with practical usage examples!

🚀 CLI Quick Reference

Stouputils provides a powerful command-line interface. Here's a quick example for each subcommand:

# Show version information of polars with dependency tree of depth 3
stouputils --version polars -t 3

# Run all doctests in a directory with pattern filter (fnmatch)
stouputils all_doctests "./src" "*_test"

# Repair a corrupted/obstructed zip archive
stouputils archive repair "./input.zip" "./output.zip"

# Create a delta backup
stouputils backup delta "./source" "./backups"

# Build and publish to PyPI (with minor version bump and no stubs)
stouputils build minor --no_stubs

# Generate changelog from git history (since a specific date, with commit URLs from origin remote, output to file)
stouputils changelog date "2026-01-01" -r origin -o "CHANGELOG.md"

# Redirect (move) a folder and create a junction/symlink at the original location
stouputils redirect "C:/Games/MyGame" "D:/Games/" --hardlink

📖 See the Extensive CLI Documentation section below for detailed usage and all available options.

🚀 Project File Tree

stouputils/
├── print         # 🖨️ Utility functions for printing (info, debug, warning, error, whatisit, breakpoint, progress_bar, ...)
├── decorators    # 🎯 Decorators (measure_time, handle_error, timeout, retry, simple_cache, abstract, deprecated, silent)
├── ctx           # 🔇 Context managers (LogToFile, MeasureTime, Muffle, DoNothing, SetMPStartMethod)
├── io            # 💾 Utilities for file management (json_dump, json_load, csv_dump, csv_load, read_file, super_copy, super_open, clean_path, redirect_folder, ...)
├── parallel      # 🔀 Utility functions for parallel processing (multiprocessing, multithreading, run_in_subprocess)
├── image         # 🖼️ Little utilities for image processing (image_resize, auto_crop, numpy_to_gif, numpy_to_obj)
├── collections   # 🧰 Utilities for collection manipulation (unique_list, at_least_n, sort_dict_keys, upsert_in_dataframe, array_to_disk)
├── typing        # 📝 Utilities for typing enhancements (IterAny, JsonDict, JsonList, ..., convert_to_serializable)
├── all_doctests  # ✅ Run all doctests for all modules in a given directory (launch_tests, test_module_with_progress)
├── backup        # 💾 Utilities for backup management (delta backup, consolidate)
├── lock          # 🔒 Inter-process FIFO locks (LockFifo, RLockFifo, RedisLockFifo)
├── archive       # 📦 Functions for creating and managing archives (create, repair)
├── config        # ⚙️ Global configuration (StouputilsConfig: global options)
│
├── applications/
│   ├── automatic_docs    # 📚 Documentation generation utilities (used to create this documentation)
│   ├── upscaler          # 🔎 Image & Video upscaler (configurable)
│   └── ...
│
├── continuous_delivery/
│   ├── cd_utils          # 🔧 Utilities for continuous delivery
│   ├── git               # 📜 Utilities for local git changelog generation
│   ├── github            # 📦 Utilities for continuous delivery on GitHub (upload_to_github)
│   ├── pypi              # 📦 Utilities for PyPI (pypi_full_routine)
│   ├── pyproject         # 📝 Utilities for reading, writing and managing pyproject.toml files
│   ├── stubs             # 📝 Utilities for generating stub files using stubgen
│   └── ...
│
├── mlflow/
│   ├── process_metrics_monitor    # 📊 Monitor CPU, memory, I/O, and thread metrics for a specific process tree and log them to MLflow
│   └── ...
│
├── installer/
│   ├── common            # 🔧 Common functions used by the Linux and Windows installers modules
│   ├── downloader        # ⬇️ Functions for downloading and installing programs from URLs
│   ├── linux             # 🐧 Linux/macOS specific implementations for installation
│   ├── main              # 🚀 Core installation functions for installing programs from zip files or URLs
│   ├── windows           # 💻 Windows specific implementations for installation
│   └── ...
└── ...

🔧 Installation

pip install stouputils

✨ Enable Tab Completion on Linux (Optional)

For a better CLI experience, enable bash tab completion:

# Option 1: Using argcomplete's global activation
activate-global-python-argcomplete --user

# Option 2: Manual setup for bash
register-python-argcomplete stouputils >> ~/.bashrc
source ~/.bashrc

After enabling completion, you can use <TAB> to autocomplete commands:

stouputils <TAB>        # Shows: --version, -v, all_doctests, backup
stouputils all_<TAB>    # Completes to: all_doctests

Note: Tab completion works best in bash, zsh, Git Bash, or WSL on Windows.

📖 Extensive CLI Documentation

The stouputils CLI provides several powerful commands for common development tasks.

⚡ General Usage

stouputils <command> [options]

Running stouputils without arguments displays help with all available commands.

📌 `--version` / `-v` — Show Version Information

Display the version of stouputils and its dependencies, along with the used Python version.

# Basic usage - show stouputils version
stouputils --version
stouputils -v

# Show version for a specific package
stouputils --version numpy
stouputils -v requests

# Show dependency tree (depth 3+)
stouputils --version -t 3
stouputils -v stouputils --tree 4

Options:

Option	Description
`[package]`	Optional package name to show version for (default: stouputils)
`-t`, `--tree <depth>`	Show dependency tree with specified depth (≤2 for flat list, ≥3 for tree view)

✅ `all_doctests` — Run Doctests

Execute all doctests in Python files within a directory.

# Run doctests in current directory
stouputils all_doctests

# Run doctests in specific directory
stouputils all_doctests ./src

# Run doctests with file pattern filter
stouputils all_doctests ./src "*image/*.py"
stouputils all_doctests . "*utils*"

Arguments:

Argument	Description
`[directory]`	Directory to search for Python files (default: `.`)
`[pattern]`	Glob pattern to filter files (default: `*`)

Exit codes:

0: All tests passed
1: One or more tests failed

📦 `archive` — Archive Utilities

Create and repair ZIP archives.

# Show archive help
stouputils archive --help

`archive make` — Create Archive

# Basic archive creation
stouputils archive make ./my_folder ./backup.zip

# Create archive with ignore patterns
stouputils archive make ./project ./project.zip --ignore "*.pyc,__pycache__,*.log"

# Create destination directory if needed
stouputils archive make ./source ./backups/archive.zip --create-dir

Arguments & Options:

Argument/Option	Description
`<source>`	Source directory to archive
`<destination>`	Destination zip file path
`--ignore <patterns>`	Comma-separated glob patterns to exclude
`--create-dir`	Create destination directory if it doesn't exist

`archive repair` — Repair Corrupted ZIP

# Repair with auto-generated output name
stouputils archive repair ./corrupted.zip

# Repair with custom output name
stouputils archive repair ./corrupted.zip ./fixed.zip

Arguments:

Argument	Description
`<input_file>`	Path to the corrupted zip file
`[output_file]`	Path for repaired file (default: adds `_repaired` suffix)

💾 `backup` — Backup Utilities

Create delta backups, consolidate existing backups, and manage backup retention.

# Show backup help
stouputils backup --help

`backup delta` — Create Delta Backup

Create an incremental backup containing only new or modified files since the last backup.

# Basic delta backup
stouputils backup delta ./my_project ./backups

# Delta backup with exclusions
stouputils backup delta ./project ./backups -x "*.pyc" "__pycache__/*" "node_modules/*"
stouputils backup delta ./source ./backups --exclude "*.log" "temp/*"

Arguments & Options:

Argument/Option	Description
`<source>`	Source directory or file to back up
`<destination>`	Destination folder for backups
`-x`, `--exclude <patterns>`	Glob patterns to exclude (space-separated)

`backup consolidate` — Consolidate Backups

Merge multiple delta backups into a single complete backup.

# Consolidate all backups up to latest.zip into one file
stouputils backup consolidate ./backups/latest.zip ./consolidated.zip

Arguments:

Argument	Description
`<backup_zip>`	Path to the latest backup ZIP file
`<destination_zip>`	Path for the consolidated output file

`backup limit` — Limit Backup Count

Limit the number of delta backups by consolidating the oldest ones.

# Keep only the 5 most recent backups
stouputils backup limit 5 ./backups

# Allow deletion of the oldest backup (not recommended)
stouputils backup limit 5 ./backups --no-keep-oldest

Arguments & Options:

Argument/Option	Description
`<max_backups>`	Maximum number of backups to keep
`<backup_folder>`	Path to the folder containing backups
`--no-keep-oldest`	Allow deletion of the oldest backup (default: keep it)

🏗️ `build` — Build and Publish to PyPI

Build and publish a Python package to PyPI using the uv tool. This runs a complete routine including version bumping, stub generation, building, and publishing.

# Standard build and publish (bumps patch by default)
stouputils build

# Build without generating stubs and without bumping version
stouputils build --no_stubs --no_bump

# Bump minor version before build
stouputils build minor

# Bump major version before build
stouputils build major

Options:

Option	Description
`--no_stubs`	Skip stub file generation
`--no_bump`	Skip version bumping (use current version)
`minor`	Bump minor version (e.g., 1.2.0 → 1.3.0)
`major`	Bump major version (e.g., 1.2.0 → 2.0.0)

📜 `changelog` — Generate Changelog

Generate a formatted changelog from local git history.

# Show changelog help
stouputils changelog --help

# Generate changelog since latest tag (default)
stouputils changelog

# Generate changelog since a specific tag
stouputils changelog tag v1.9.0

# Generate changelog since a specific date
stouputils changelog date 2026/01/05
stouputils changelog date "2026-01-15 14:30:00"

# Generate changelog since a specific commit
stouputils changelog commit 847b27e

# Include commit URLs from a remote
stouputils changelog --remote origin
stouputils changelog tag v2.0.0 -r origin

# Output to a file
stouputils changelog -o CHANGELOG.md
stouputils changelog tag v1.0.0 --output docs/CHANGELOG.md

Arguments & Options:

Argument/Option	Description
`[mode]`	Mode for selecting commits: `tag`, `date`, or `commit` (default: `tag`)
`[value]`	Value for the mode (tag name, date, or commit SHA)
`-r`, `--remote <name>`	Remote name for commit URLs (e.g., `origin`)
`-o`, `--output <file>`	Output file path (default: stdout)

Supported date formats:

YYYY/MM/DD or YYYY-MM-DD
DD/MM/YYYY or DD-MM-YYYY
YYYY-MM-DD HH:MM:SS
ISO 8601: YYYY-MM-DDTHH:MM:SS

🔗 `redirect` — Redirect a Folder

Move a folder to a new location and create a junction or symlink at the original path. Useful for redirecting game installs, large data folders, etc. across drives.

# Show redirect help
stouputils redirect --help

# Redirect with auto-detected basename (destination ends with /)
stouputils redirect "C:/Games/MyGame" "D:/Games/" --hardlink

# Redirect with explicit destination name
stouputils redirect "C:/Games/MyGame" "D:/Storage/MyGame" --symlink

# Interactive mode (asks for link type)
stouputils redirect "./my_folder" "/mnt/external/"

Arguments & Options:

Argument/Option	Description
`<source>`	Source folder to redirect
`<destination>`	Destination path (append `/` to auto-use source basename)
`--hardlink` / `--junction`	Use NTFS junction (Windows) or fallback to symlink (Linux/macOS)
`--symlink`	Use a symbolic link (may need admin on Windows)

Notes:

If --hardlink fails (e.g., unsupported OS), it automatically falls back to symlink
If the source is already a symlink or junction, the operation is skipped
On Linux/macOS, junctions are not available so --hardlink uses a symlink instead

📋 Examples Summary

Command	Description
`stouputils -v`	Show version
`stouputils -v numpy -t 3`	Show numpy version with dependency tree
`stouputils all_doctests ./src`	Run doctests in src directory
`stouputils archive make ./proj ./proj.zip`	Create archive
`stouputils archive repair ./bad.zip`	Repair corrupted zip
`stouputils backup delta ./src ./bak -x "*.pyc"`	Create delta backup
`stouputils backup consolidate ./bak/latest.zip ./full.zip`	Consolidate backups
`stouputils backup limit 5 ./bak`	Keep only 5 backups
`stouputils build minor`	Build with minor version bump
`stouputils changelog tag v1.0.0 -r origin -o CHANGELOG.md`	Generate changelog to file
`stouputils redirect "C:/Games/MyGame" "D:/Games/" --hardlink`	Redirect folder with junction

Create a delta backup

🛠️ Project Badges

📚 Project Overview

🚀 CLI Quick Reference

🚀 Project File Tree

🔧 Installation

✨ Enable Tab Completion on Linux (Optional)

📖 Extensive CLI Documentation

⚡ General Usage

📌 `--version` / `-v` — Show Version Information

✅ `all_doctests` — Run Doctests

📦 `archive` — Archive Utilities

`archive make` — Create Archive

`archive repair` — Repair Corrupted ZIP

💾 `backup` — Backup Utilities

`backup delta` — Create Delta Backup

`backup consolidate` — Consolidate Backups

`backup limit` — Limit Backup Count

🏗️ `build` — Build and Publish to PyPI

📜 `changelog` — Generate Changelog

🔗 `redirect` — Redirect a Folder

📋 Examples Summary

⭐ Star History