🛠️ stouputils

Every utility you rewrite in each project, already written: colored logging, decorators, parallel maps, archives, backups, a CLI, and more.

Installation | Quick start | Modules | CLI | Documentation

📚 What is it?

One import gives you the utilities every project ends up rewriting. Logs are colored and timestamped, repeated lines collapse into (x3), decorators time and retry your functions, and multiprocessing gets a progress bar for free, and many more. Everything is strongly typed, doctested on Python 3.12 to 3.15 including the free threaded builds, and every submodule is declared lazy (PEP 810) so import stouputils costs almost nothing on Python 3.15.

🔧 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.

🚀 Quick start

import stouputils as stp

@stp.measure_time()
@stp.handle_error(message="Doubling failed")
def double(value: int) -> int:
	return value * 2

stp.info("Starting", 3, "jobs")
stp.info("Starting", 3, "jobs")	# A repeated line collapses instead of scrolling away
results: list[int] = stp.multithreading(double, [1, 2, 3], desc="Doubling")
stp.whatisit(results)
stp.warning("Two files were skipped")

[INFO  11:32:19] (x2) Starting 3 jobs
[PROGRESS 11:32:19] Execution time of double(): 0.003ms (2904ns)
[PROGRESS 11:32:19] Execution time of double(): 0.001ms (1031ns)
[PROGRESS 11:32:19] Execution time of double(): 0.003ms (2613ns)
Doubling: 100%|██████████| 3/3 [19358.33it/s, 00:00<00:00]
[What is it? 11:32:19] <class 'list'>, <id 127047922343936>: (length: 3, min: 2, max: 6) [2, 4, 6]
[WARNING 11:32:19] Two files were skipped

Colors, timestamps and the progress bar come from the defaults, they are configurable. Send the same logs to a file with with stp.LogToFile("run.log"):, silence a noisy library with with stp.Muffle():, and swap multithreading for multiprocessing when the work is CPU bound.

💻 From the command line

The same toolbox is available as a CLI, one example per 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.

🧰 Modules

Every name below links to its reference page.

<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); } .code-tree .paren { color: orange; } </style>

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 (Registry, 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, inheritable, overridable, hook)
├── 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
│   └── ...
│
├── compression/
│   ├── deadband                   # 📉 Thin a curve down to the points the line drawn through it needs (DeadbandFilter)
│   └── ...
│
├── 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
│   └── ...
└── ...

📖 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

⭐ Star History