os-helper 1.4.2

Cross-platform Python utility functions for file handling, system operations, string manipulation, folder management, hashing, configuration loading, and timing/profiling primitives — exposed as library, argparse CLI, click CLI, FastAPI HTTP surface and MCP tools.

OS Helper

🇫🇷 · 🇬🇧

OS Helper belongs to a collection of libraries called AI Helpers developped for building Artificial Intelligence

🌍 AI Helpers

OS Helper is a Python library that provides utility functions for working with different operating systems.

It offers a set of tools to simplify common system operations, file handling, and OS-specific tasks.

Features

• Operating system detection (Windows, Linux, macOS, Unix)
• File system operations (create, delete, move, copy)
• System information retrieval (CPU, memory, disk usage)
• Cross-platform path handling
• File hashing and string hashing utilities
• Process management and execution

Documentation

👩‍💻 Documentation

📋 Examples

Installation

Prerequisites — Python 3.10–3.13 and git, cross-platform:

• 🍎 macOS (Homebrew): brew install python git
• 🐧 Ubuntu/Debian: sudo apt update && sudo apt install -y python3 python3-pip git
• 🪟 Windows (PowerShell): winget install Python.Python.3.12 Git.Git

Then install the package:

Install Package

We can recommand python environments. Check this link if you don't know how

🥸 Tech tips

We still discuss between different python package managers and try to support as much as possible

pip install --force-reinstall --no-cache-dir git+https://github.com/warith-harchaoui/os-helper.git@v1.4.2

Usage

Below are examples demonstrating how to use various features of the os_helper library. Make sure to import the library as osh before starting.

import os_helper as osh

1. Set Verbosity and Check Operating System

# Set verbosity level to display debugging messages
osh.verbosity(3)

# Check if the system is Unix-based (Linux or macOS)
if osh.unix():
    osh.info("You are running on a Unix-based system.")
else:
    osh.info("You are not running on a Unix-based system.")

2. Timestamp and File Existence Check

# Generate a formatted timestamp for logging
timestamp = osh.now_string("log")
osh.info(f"Current timestamp (log format): {timestamp}")

# Check if a file exists and is not empty
test_file = "example.txt"
if osh.file_exists(test_file, check_empty=True):
    osh.info(f"File {test_file} exists and is not empty.")
else:
    osh.error(f"File {test_file} does not exist or is empty.")

3. Directory Creation and File Search

# Create a directory
test_dir = "test_directory"
osh.make_directory(test_dir)
osh.info(f"Directory {test_dir} created.")

# Perform recursive search for '.txt' files in the directory
matching_files = osh.recursive_glob(test_dir, "*.txt")
osh.info(f"Matching files: {matching_files}")

4. Copy and Remove Files

# Copy a file from source to destination
source_file = "source.txt"
destination_file = "backup_source.txt"
osh.copyfile(source_file, destination_file)
osh.info(f"File {source_file} copied to {destination_file}")

# Remove the copied file (each removal is logged at INFO level)
osh.remove_files([destination_file])

5. Decompose a Path and Temporary File Creation

# Decompose a file path into folder, basename, and extension
folder, basename, ext = osh.folder_name_ext("/path/to/myfile.tar.gz")
osh.info(f"Folder: {folder}, Basename: {basename}, Extension: {ext}")

# Create and write to a temporary file
with osh.temporary_filename(suffix=".log") as temp_log:
    osh.info(f"Temporary file created at: {temp_log}")
    with open(temp_log, "w") as log_file:
        log_file.write("This is a temporary log entry.")

6. Running System Commands

# Execute a system command and capture its output
cmd_output = osh.system("echo 'Hello, World!'")
osh.info(f"Command output: {cmd_output['out']}")

7. Hashing Files and Strings

# Hash the contents of a file
file_to_hash = "testfile.txt"
if osh.file_exists(file_to_hash):
    file_hash = osh.hashfile(file_to_hash)
    osh.info(f"Hash of {file_to_hash}: {file_hash}")

# Hash a string with a specific length
hashed_string = osh.hash_string("MyTestString", size=8)
osh.info(f"Hashed string: {hashed_string}")

8. ASCII String Conversion and Process ID

# Convert a string into a safe ASCII format
safe_string = osh.asciistring("Café-Con-Leche!", replacement_char="_")
osh.info(f"Safe ASCII string: {safe_string}")

# Get the current process ID
pid = osh.getpid()
osh.info(f"Current Process ID: {pid}")

9. Check URL Validity and Zip Folder

# Check if a URL is valid and reachable
url = "https://www.example.com"
if osh.is_working_url(url):
    osh.info(f"The URL {url} is valid and reachable.")
else:
    osh.error(f"The URL {url} is not reachable.")

# Zip a folder
folder_to_zip = "my_folder"
zip_output = "my_folder_backup.zip"
osh.zip_folder(folder_to_zip, zip_output)
osh.info(f"Folder {folder_to_zip} zipped into {zip_output}")

Multi-surface exposure

os-helper is not just a library — the same functions are exposed as a CLI, a FastAPI HTTP surface, and an MCP tool set:

# Python library (default)
import os_helper as osh

# argparse-based CLI (installed automatically)
os-helper os system
os-helper path exists ~/.zshrc
os-helper hash string hello --size 8
os-helper misc format-size 12345678
os-helper misc now --fmt filename

# click-based CLI twin (needs the [cli] extra)
pip install 'os-helper[cli] @ git+https://github.com/warith-harchaoui/os-helper.git@v1.4.2'
os-helper-click hash file ./pyproject.toml

# FastAPI HTTP surface (needs the [api] extra)
pip install 'os-helper[api] @ git+https://github.com/warith-harchaoui/os-helper.git@v1.4.2'
uvicorn os_helper.api:app --port 8000
# → OpenAPI docs at http://localhost:8000/docs

# MCP tools over FastAPI (needs the [api,mcp] extras)
pip install 'os-helper[api,mcp] @ git+https://github.com/warith-harchaoui/os-helper.git@v1.4.2'
os-helper-mcp                    # serves FastAPI + MCP on port 8000

Docker image (light — API + MCP enabled by default):

docker build -t os-helper .
docker run --rm -p 8000:8000 os-helper

An innovative GUI plan (Tree Radar treemap, Dedupe Lens, Config Explorer) lives in GUI.md.

The competitive landscape (stdlib, pathlib, click, python-dotenv, psutil, fsspec, …) is analysed in LANDSCAPE.md.

Author

Warith HARCHAOUI

Acknowledgements

Special thanks to Mohamed Chelali and Bachir Zerroug for fruitful discussions.