os-helper 1.4.2__tar.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.
@@ -0,0 +1,29 @@
1
+ BSD 3-Clause License
2
+
3
+ Copyright (c) 2026, Warith HARCHAOUI
4
+ All rights reserved.
5
+
6
+ Redistribution and use in source and binary forms, with or without
7
+ modification, are permitted provided that the following conditions are met:
8
+
9
+ 1. Redistributions of source code must retain the above copyright notice, this
10
+ list of conditions and the following disclaimer.
11
+
12
+ 2. Redistributions in binary form must reproduce the above copyright notice,
13
+ this list of conditions and the following disclaimer in the documentation
14
+ and/or other materials provided with the distribution.
15
+
16
+ 3. Neither the name of the copyright holder nor the names of its
17
+ contributors may be used to endorse or promote products derived from
18
+ this software without specific prior written permission.
19
+
20
+ THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
21
+ AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
22
+ IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
23
+ DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
24
+ FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
25
+ DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
26
+ SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
27
+ CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
28
+ OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
29
+ OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
@@ -0,0 +1,270 @@
1
+ Metadata-Version: 2.4
2
+ Name: os-helper
3
+ Version: 1.4.2
4
+ Summary: 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.
5
+ Author-email: Warith HARCHAOUI <warithmetics@deraison.ai>
6
+ License: BSD-3-Clause
7
+ Project-URL: Homepage, https://github.com/warith-harchaoui/os-helper
8
+ Project-URL: Issues, https://github.com/warith-harchaoui/os-helper/issues
9
+ Keywords: utilities,filesystem,config,hashing,timing,profiling,cross-platform
10
+ Classifier: Development Status :: 5 - Production/Stable
11
+ Classifier: Intended Audience :: Developers
12
+ Classifier: License :: OSI Approved :: BSD License
13
+ Classifier: Operating System :: OS Independent
14
+ Classifier: Programming Language :: Python :: 3
15
+ Classifier: Programming Language :: Python :: 3.10
16
+ Classifier: Programming Language :: Python :: 3.11
17
+ Classifier: Programming Language :: Python :: 3.12
18
+ Classifier: Programming Language :: Python :: 3.13
19
+ Classifier: Topic :: Software Development :: Libraries :: Python Modules
20
+ Classifier: Topic :: System :: Filesystems
21
+ Requires-Python: <3.14,>=3.10
22
+ Description-Content-Type: text/markdown
23
+ License-File: LICENSE
24
+ Requires-Dist: requests<3,>=2.32.3
25
+ Requires-Dist: python-dotenv<2,>=1.0.1
26
+ Requires-Dist: pyyaml<7,>=6.0.2
27
+ Requires-Dist: validators<1,>=0.34.0
28
+ Provides-Extra: cli
29
+ Requires-Dist: click<9,>=8.1; extra == "cli"
30
+ Provides-Extra: api
31
+ Requires-Dist: fastapi<1,>=0.111; extra == "api"
32
+ Requires-Dist: uvicorn<1,>=0.30; extra == "api"
33
+ Requires-Dist: python-multipart<1,>=0.0.9; extra == "api"
34
+ Provides-Extra: mcp
35
+ Requires-Dist: fastapi-mcp<1,>=0.3; extra == "mcp"
36
+ Requires-Dist: fastapi<1,>=0.111; extra == "mcp"
37
+ Requires-Dist: uvicorn<1,>=0.30; extra == "mcp"
38
+ Requires-Dist: python-multipart<1,>=0.0.9; extra == "mcp"
39
+ Provides-Extra: dev
40
+ Requires-Dist: pytest>=8; extra == "dev"
41
+ Requires-Dist: httpx>=0.27; extra == "dev"
42
+ Requires-Dist: click<9,>=8.1; extra == "dev"
43
+ Requires-Dist: fastapi<1,>=0.111; extra == "dev"
44
+ Requires-Dist: python-multipart<1,>=0.0.9; extra == "dev"
45
+ Requires-Dist: fastapi-mcp<1,>=0.3; extra == "dev"
46
+ Dynamic: license-file
47
+
48
+ # OS Helper
49
+
50
+ [๐Ÿ‡ซ๐Ÿ‡ท](https://github.com/warith-harchaoui/os-helper/blob/main/LISEZMOI.md) ยท [๐Ÿ‡ฌ๐Ÿ‡ง](https://github.com/warith-harchaoui/os-helper/blob/main/README.md)
51
+
52
+ [![CI](https://github.com/warith-harchaoui/os-helper/actions/workflows/ci.yml/badge.svg)](https://github.com/warith-harchaoui/os-helper/actions/workflows/ci.yml) [![License: BSD-3-Clause](https://img.shields.io/badge/License-BSD%203--Clause-blue.svg)](LICENSE) [![Python](https://img.shields.io/badge/python-3.10%E2%80%933.13-blue.svg)](#)
53
+
54
+ `OS Helper` belongs to a collection of libraries called `AI Helpers` developped for building Artificial Intelligence
55
+
56
+ [๐ŸŒ AI Helpers](https://harchaoui.org/warith/ai-helpers)
57
+
58
+ [![logo](https://raw.githubusercontent.com/warith-harchaoui/os-helper/main/assets/logo.png)](https://harchaoui.org/warith/ai-helpers)
59
+
60
+ OS Helper is a Python library that provides utility functions for working with different operating systems.
61
+
62
+ It offers a set of tools to simplify common system operations, file handling, and OS-specific tasks.
63
+
64
+ # Features
65
+
66
+ - Operating system detection (Windows, Linux, macOS, Unix)
67
+ - File system operations (create, delete, move, copy)
68
+ - System information retrieval (CPU, memory, disk usage)
69
+ - Cross-platform path handling
70
+ - File hashing and string hashing utilities
71
+ - Process management and execution
72
+
73
+ # Documentation
74
+
75
+ [๐Ÿ‘ฉโ€๐Ÿ’ป Documentation](https://harchaoui.org/warith/ai-helpers/docs/os-helper-doc/)
76
+
77
+ [๐Ÿ“‹ Examples](https://github.com/warith-harchaoui/os-helper/blob/main/EXAMPLES.md)
78
+
79
+ # Installation
80
+
81
+ **Prerequisites** โ€” **Python 3.10โ€“3.13** and **git**, cross-platform:
82
+
83
+ - ๐ŸŽ **macOS** ([Homebrew](https://brew.sh)): `brew install python git`
84
+ - ๐Ÿง **Ubuntu/Debian**: `sudo apt update && sudo apt install -y python3 python3-pip git`
85
+ - ๐ŸชŸ **Windows** (PowerShell): `winget install Python.Python.3.12 Git.Git`
86
+
87
+ Then install the package:
88
+
89
+
90
+ ## Install Package
91
+
92
+ We can recommand python environments. Check this link if you don't know how
93
+
94
+ [๐Ÿฅธ Tech tips](https://harchaoui.org/warith/4ml/#install)
95
+
96
+ We still discuss between different python package managers and try to support as much as possible
97
+
98
+ ```bash
99
+ pip install --force-reinstall --no-cache-dir git+https://github.com/warith-harchaoui/os-helper.git@v1.4.2
100
+ ```
101
+
102
+ ## Usage
103
+
104
+ Below are examples demonstrating how to use various features of the `os_helper` library. Make sure to import the library as `osh` before starting.
105
+
106
+ ```python
107
+ import os_helper as osh
108
+ ```
109
+
110
+ 1. Set Verbosity and Check Operating System
111
+
112
+ ```python
113
+ # Set verbosity level to display debugging messages
114
+ osh.verbosity(3)
115
+
116
+ # Check if the system is Unix-based (Linux or macOS)
117
+ if osh.unix():
118
+ osh.info("You are running on a Unix-based system.")
119
+ else:
120
+ osh.info("You are not running on a Unix-based system.")
121
+ ```
122
+
123
+ 2. Timestamp and File Existence Check
124
+ ```python
125
+ # Generate a formatted timestamp for logging
126
+ timestamp = osh.now_string("log")
127
+ osh.info(f"Current timestamp (log format): {timestamp}")
128
+
129
+ # Check if a file exists and is not empty
130
+ test_file = "example.txt"
131
+ if osh.file_exists(test_file, check_empty=True):
132
+ osh.info(f"File {test_file} exists and is not empty.")
133
+ else:
134
+ osh.error(f"File {test_file} does not exist or is empty.")
135
+ ```
136
+
137
+ 3. Directory Creation and File Search
138
+ ```python
139
+ # Create a directory
140
+ test_dir = "test_directory"
141
+ osh.make_directory(test_dir)
142
+ osh.info(f"Directory {test_dir} created.")
143
+
144
+ # Perform recursive search for '.txt' files in the directory
145
+ matching_files = osh.recursive_glob(test_dir, "*.txt")
146
+ osh.info(f"Matching files: {matching_files}")
147
+ ```
148
+
149
+ 4. Copy and Remove Files
150
+ ```python
151
+ # Copy a file from source to destination
152
+ source_file = "source.txt"
153
+ destination_file = "backup_source.txt"
154
+ osh.copyfile(source_file, destination_file)
155
+ osh.info(f"File {source_file} copied to {destination_file}")
156
+
157
+ # Remove the copied file (each removal is logged at INFO level)
158
+ osh.remove_files([destination_file])
159
+ ```
160
+
161
+ 5. Decompose a Path and Temporary File Creation
162
+ ```python
163
+ # Decompose a file path into folder, basename, and extension
164
+ folder, basename, ext = osh.folder_name_ext("/path/to/myfile.tar.gz")
165
+ osh.info(f"Folder: {folder}, Basename: {basename}, Extension: {ext}")
166
+
167
+ # Create and write to a temporary file
168
+ with osh.temporary_filename(suffix=".log") as temp_log:
169
+ osh.info(f"Temporary file created at: {temp_log}")
170
+ with open(temp_log, "w") as log_file:
171
+ log_file.write("This is a temporary log entry.")
172
+
173
+ ```
174
+
175
+ 6. Running System Commands
176
+ ```python
177
+ # Execute a system command and capture its output
178
+ cmd_output = osh.system("echo 'Hello, World!'")
179
+ osh.info(f"Command output: {cmd_output['out']}")
180
+
181
+ ```
182
+
183
+ 7. Hashing Files and Strings
184
+ ```python
185
+ # Hash the contents of a file
186
+ file_to_hash = "testfile.txt"
187
+ if osh.file_exists(file_to_hash):
188
+ file_hash = osh.hashfile(file_to_hash)
189
+ osh.info(f"Hash of {file_to_hash}: {file_hash}")
190
+
191
+ # Hash a string with a specific length
192
+ hashed_string = osh.hash_string("MyTestString", size=8)
193
+ osh.info(f"Hashed string: {hashed_string}")
194
+ ```
195
+
196
+ 8. ASCII String Conversion and Process ID
197
+ ```python
198
+ # Convert a string into a safe ASCII format
199
+ safe_string = osh.asciistring("Cafรฉ-Con-Leche!", replacement_char="_")
200
+ osh.info(f"Safe ASCII string: {safe_string}")
201
+
202
+ # Get the current process ID
203
+ pid = osh.getpid()
204
+ osh.info(f"Current Process ID: {pid}")
205
+ ```
206
+
207
+ 9. Check URL Validity and Zip Folder
208
+ ```python
209
+ # Check if a URL is valid and reachable
210
+ url = "https://www.example.com"
211
+ if osh.is_working_url(url):
212
+ osh.info(f"The URL {url} is valid and reachable.")
213
+ else:
214
+ osh.error(f"The URL {url} is not reachable.")
215
+
216
+ # Zip a folder
217
+ folder_to_zip = "my_folder"
218
+ zip_output = "my_folder_backup.zip"
219
+ osh.zip_folder(folder_to_zip, zip_output)
220
+ osh.info(f"Folder {folder_to_zip} zipped into {zip_output}")
221
+ ```
222
+
223
+ # Multi-surface exposure
224
+
225
+ `os-helper` is not just a library โ€” the same functions are exposed as a
226
+ CLI, a FastAPI HTTP surface, and an MCP tool set:
227
+
228
+ ```bash
229
+ # Python library (default)
230
+ import os_helper as osh
231
+
232
+ # argparse-based CLI (installed automatically)
233
+ os-helper os system
234
+ os-helper path exists ~/.zshrc
235
+ os-helper hash string hello --size 8
236
+ os-helper misc format-size 12345678
237
+ os-helper misc now --fmt filename
238
+
239
+ # click-based CLI twin (needs the [cli] extra)
240
+ pip install 'os-helper[cli] @ git+https://github.com/warith-harchaoui/os-helper.git@v1.4.2'
241
+ os-helper-click hash file ./pyproject.toml
242
+
243
+ # FastAPI HTTP surface (needs the [api] extra)
244
+ pip install 'os-helper[api] @ git+https://github.com/warith-harchaoui/os-helper.git@v1.4.2'
245
+ uvicorn os_helper.api:app --port 8000
246
+ # โ†’ OpenAPI docs at http://localhost:8000/docs
247
+
248
+ # MCP tools over FastAPI (needs the [api,mcp] extras)
249
+ pip install 'os-helper[api,mcp] @ git+https://github.com/warith-harchaoui/os-helper.git@v1.4.2'
250
+ os-helper-mcp # serves FastAPI + MCP on port 8000
251
+ ```
252
+
253
+ Docker image (light โ€” API + MCP enabled by default):
254
+
255
+ ```bash
256
+ docker build -t os-helper .
257
+ docker run --rm -p 8000:8000 os-helper
258
+ ```
259
+
260
+ An innovative GUI plan (Tree Radar treemap, Dedupe Lens, Config
261
+ Explorer) lives in [GUI.md](https://github.com/warith-harchaoui/os-helper/blob/main/GUI.md).
262
+
263
+ The competitive landscape (stdlib, pathlib, click, python-dotenv,
264
+ psutil, fsspec, โ€ฆ) is analysed in [LANDSCAPE.md](https://github.com/warith-harchaoui/os-helper/blob/main/LANDSCAPE.md).
265
+
266
+ # Author
267
+ [Warith HARCHAOUI](https://linkedin.com/in/warith-harchaoui)
268
+
269
+ # Acknowledgements
270
+ Special thanks to [Mohamed Chelali](https://mchelali.github.io) and [Bachir Zerroug](https://www.linkedin.com/in/bachirzerroug) for fruitful discussions.
@@ -0,0 +1,223 @@
1
+ # OS Helper
2
+
3
+ [๐Ÿ‡ซ๐Ÿ‡ท](https://github.com/warith-harchaoui/os-helper/blob/main/LISEZMOI.md) ยท [๐Ÿ‡ฌ๐Ÿ‡ง](https://github.com/warith-harchaoui/os-helper/blob/main/README.md)
4
+
5
+ [![CI](https://github.com/warith-harchaoui/os-helper/actions/workflows/ci.yml/badge.svg)](https://github.com/warith-harchaoui/os-helper/actions/workflows/ci.yml) [![License: BSD-3-Clause](https://img.shields.io/badge/License-BSD%203--Clause-blue.svg)](LICENSE) [![Python](https://img.shields.io/badge/python-3.10%E2%80%933.13-blue.svg)](#)
6
+
7
+ `OS Helper` belongs to a collection of libraries called `AI Helpers` developped for building Artificial Intelligence
8
+
9
+ [๐ŸŒ AI Helpers](https://harchaoui.org/warith/ai-helpers)
10
+
11
+ [![logo](https://raw.githubusercontent.com/warith-harchaoui/os-helper/main/assets/logo.png)](https://harchaoui.org/warith/ai-helpers)
12
+
13
+ OS Helper is a Python library that provides utility functions for working with different operating systems.
14
+
15
+ It offers a set of tools to simplify common system operations, file handling, and OS-specific tasks.
16
+
17
+ # Features
18
+
19
+ - Operating system detection (Windows, Linux, macOS, Unix)
20
+ - File system operations (create, delete, move, copy)
21
+ - System information retrieval (CPU, memory, disk usage)
22
+ - Cross-platform path handling
23
+ - File hashing and string hashing utilities
24
+ - Process management and execution
25
+
26
+ # Documentation
27
+
28
+ [๐Ÿ‘ฉโ€๐Ÿ’ป Documentation](https://harchaoui.org/warith/ai-helpers/docs/os-helper-doc/)
29
+
30
+ [๐Ÿ“‹ Examples](https://github.com/warith-harchaoui/os-helper/blob/main/EXAMPLES.md)
31
+
32
+ # Installation
33
+
34
+ **Prerequisites** โ€” **Python 3.10โ€“3.13** and **git**, cross-platform:
35
+
36
+ - ๐ŸŽ **macOS** ([Homebrew](https://brew.sh)): `brew install python git`
37
+ - ๐Ÿง **Ubuntu/Debian**: `sudo apt update && sudo apt install -y python3 python3-pip git`
38
+ - ๐ŸชŸ **Windows** (PowerShell): `winget install Python.Python.3.12 Git.Git`
39
+
40
+ Then install the package:
41
+
42
+
43
+ ## Install Package
44
+
45
+ We can recommand python environments. Check this link if you don't know how
46
+
47
+ [๐Ÿฅธ Tech tips](https://harchaoui.org/warith/4ml/#install)
48
+
49
+ We still discuss between different python package managers and try to support as much as possible
50
+
51
+ ```bash
52
+ pip install --force-reinstall --no-cache-dir git+https://github.com/warith-harchaoui/os-helper.git@v1.4.2
53
+ ```
54
+
55
+ ## Usage
56
+
57
+ Below are examples demonstrating how to use various features of the `os_helper` library. Make sure to import the library as `osh` before starting.
58
+
59
+ ```python
60
+ import os_helper as osh
61
+ ```
62
+
63
+ 1. Set Verbosity and Check Operating System
64
+
65
+ ```python
66
+ # Set verbosity level to display debugging messages
67
+ osh.verbosity(3)
68
+
69
+ # Check if the system is Unix-based (Linux or macOS)
70
+ if osh.unix():
71
+ osh.info("You are running on a Unix-based system.")
72
+ else:
73
+ osh.info("You are not running on a Unix-based system.")
74
+ ```
75
+
76
+ 2. Timestamp and File Existence Check
77
+ ```python
78
+ # Generate a formatted timestamp for logging
79
+ timestamp = osh.now_string("log")
80
+ osh.info(f"Current timestamp (log format): {timestamp}")
81
+
82
+ # Check if a file exists and is not empty
83
+ test_file = "example.txt"
84
+ if osh.file_exists(test_file, check_empty=True):
85
+ osh.info(f"File {test_file} exists and is not empty.")
86
+ else:
87
+ osh.error(f"File {test_file} does not exist or is empty.")
88
+ ```
89
+
90
+ 3. Directory Creation and File Search
91
+ ```python
92
+ # Create a directory
93
+ test_dir = "test_directory"
94
+ osh.make_directory(test_dir)
95
+ osh.info(f"Directory {test_dir} created.")
96
+
97
+ # Perform recursive search for '.txt' files in the directory
98
+ matching_files = osh.recursive_glob(test_dir, "*.txt")
99
+ osh.info(f"Matching files: {matching_files}")
100
+ ```
101
+
102
+ 4. Copy and Remove Files
103
+ ```python
104
+ # Copy a file from source to destination
105
+ source_file = "source.txt"
106
+ destination_file = "backup_source.txt"
107
+ osh.copyfile(source_file, destination_file)
108
+ osh.info(f"File {source_file} copied to {destination_file}")
109
+
110
+ # Remove the copied file (each removal is logged at INFO level)
111
+ osh.remove_files([destination_file])
112
+ ```
113
+
114
+ 5. Decompose a Path and Temporary File Creation
115
+ ```python
116
+ # Decompose a file path into folder, basename, and extension
117
+ folder, basename, ext = osh.folder_name_ext("/path/to/myfile.tar.gz")
118
+ osh.info(f"Folder: {folder}, Basename: {basename}, Extension: {ext}")
119
+
120
+ # Create and write to a temporary file
121
+ with osh.temporary_filename(suffix=".log") as temp_log:
122
+ osh.info(f"Temporary file created at: {temp_log}")
123
+ with open(temp_log, "w") as log_file:
124
+ log_file.write("This is a temporary log entry.")
125
+
126
+ ```
127
+
128
+ 6. Running System Commands
129
+ ```python
130
+ # Execute a system command and capture its output
131
+ cmd_output = osh.system("echo 'Hello, World!'")
132
+ osh.info(f"Command output: {cmd_output['out']}")
133
+
134
+ ```
135
+
136
+ 7. Hashing Files and Strings
137
+ ```python
138
+ # Hash the contents of a file
139
+ file_to_hash = "testfile.txt"
140
+ if osh.file_exists(file_to_hash):
141
+ file_hash = osh.hashfile(file_to_hash)
142
+ osh.info(f"Hash of {file_to_hash}: {file_hash}")
143
+
144
+ # Hash a string with a specific length
145
+ hashed_string = osh.hash_string("MyTestString", size=8)
146
+ osh.info(f"Hashed string: {hashed_string}")
147
+ ```
148
+
149
+ 8. ASCII String Conversion and Process ID
150
+ ```python
151
+ # Convert a string into a safe ASCII format
152
+ safe_string = osh.asciistring("Cafรฉ-Con-Leche!", replacement_char="_")
153
+ osh.info(f"Safe ASCII string: {safe_string}")
154
+
155
+ # Get the current process ID
156
+ pid = osh.getpid()
157
+ osh.info(f"Current Process ID: {pid}")
158
+ ```
159
+
160
+ 9. Check URL Validity and Zip Folder
161
+ ```python
162
+ # Check if a URL is valid and reachable
163
+ url = "https://www.example.com"
164
+ if osh.is_working_url(url):
165
+ osh.info(f"The URL {url} is valid and reachable.")
166
+ else:
167
+ osh.error(f"The URL {url} is not reachable.")
168
+
169
+ # Zip a folder
170
+ folder_to_zip = "my_folder"
171
+ zip_output = "my_folder_backup.zip"
172
+ osh.zip_folder(folder_to_zip, zip_output)
173
+ osh.info(f"Folder {folder_to_zip} zipped into {zip_output}")
174
+ ```
175
+
176
+ # Multi-surface exposure
177
+
178
+ `os-helper` is not just a library โ€” the same functions are exposed as a
179
+ CLI, a FastAPI HTTP surface, and an MCP tool set:
180
+
181
+ ```bash
182
+ # Python library (default)
183
+ import os_helper as osh
184
+
185
+ # argparse-based CLI (installed automatically)
186
+ os-helper os system
187
+ os-helper path exists ~/.zshrc
188
+ os-helper hash string hello --size 8
189
+ os-helper misc format-size 12345678
190
+ os-helper misc now --fmt filename
191
+
192
+ # click-based CLI twin (needs the [cli] extra)
193
+ pip install 'os-helper[cli] @ git+https://github.com/warith-harchaoui/os-helper.git@v1.4.2'
194
+ os-helper-click hash file ./pyproject.toml
195
+
196
+ # FastAPI HTTP surface (needs the [api] extra)
197
+ pip install 'os-helper[api] @ git+https://github.com/warith-harchaoui/os-helper.git@v1.4.2'
198
+ uvicorn os_helper.api:app --port 8000
199
+ # โ†’ OpenAPI docs at http://localhost:8000/docs
200
+
201
+ # MCP tools over FastAPI (needs the [api,mcp] extras)
202
+ pip install 'os-helper[api,mcp] @ git+https://github.com/warith-harchaoui/os-helper.git@v1.4.2'
203
+ os-helper-mcp # serves FastAPI + MCP on port 8000
204
+ ```
205
+
206
+ Docker image (light โ€” API + MCP enabled by default):
207
+
208
+ ```bash
209
+ docker build -t os-helper .
210
+ docker run --rm -p 8000:8000 os-helper
211
+ ```
212
+
213
+ An innovative GUI plan (Tree Radar treemap, Dedupe Lens, Config
214
+ Explorer) lives in [GUI.md](https://github.com/warith-harchaoui/os-helper/blob/main/GUI.md).
215
+
216
+ The competitive landscape (stdlib, pathlib, click, python-dotenv,
217
+ psutil, fsspec, โ€ฆ) is analysed in [LANDSCAPE.md](https://github.com/warith-harchaoui/os-helper/blob/main/LANDSCAPE.md).
218
+
219
+ # Author
220
+ [Warith HARCHAOUI](https://linkedin.com/in/warith-harchaoui)
221
+
222
+ # Acknowledgements
223
+ Special thanks to [Mohamed Chelali](https://mchelali.github.io) and [Bachir Zerroug](https://www.linkedin.com/in/bachirzerroug) for fruitful discussions.
@@ -0,0 +1,180 @@
1
+ """
2
+ OS Helper
3
+
4
+ A collection of cross-platform utility functions covering:
5
+ - file and directory handling
6
+ - system / OS detection and process helpers
7
+ - string manipulation and ASCII normalization
8
+ - temporary files and folders (including remote staging)
9
+ - hashing of strings, files, and folders
10
+ - configuration loading (JSON / YAML / .env / environment)
11
+ - URL checks, downloads, zipping
12
+ - logging and verbosity helpers
13
+
14
+ Usage Example
15
+ -------------
16
+ >>> import os_helper as osh
17
+ >>> osh.verbosity(1)
18
+ >>> if osh.unix():
19
+ ... osh.info("running on a Unix-based OS")
20
+ >>> osh.info(osh.now_string("filename"))
21
+ >>> h = osh.hash_string("hello", size=8)
22
+
23
+ The same helpers are also exposed as an argparse CLI (``os-helper``), a
24
+ click CLI (``os-helper-click``, install ``[cli]`` extra), a FastAPI HTTP
25
+ surface (``os_helper.api``, install ``[api]`` extra) and an MCP tool set
26
+ (``os-helper-mcp``, install ``[api,mcp]`` extras). See the README and
27
+ ``GUI.md`` for the multi-surface story.
28
+
29
+ Author
30
+ ------
31
+ Warith Harchaoui, Ph.D. โ€” https://linkedin.com/in/warith-harchaoui/
32
+ """
33
+
34
+ __author__ = "Warith Harchaoui, Ph.D."
35
+ __email__ = "warithmetics@deraison.ai"
36
+
37
+ from .config_utils import (
38
+ get_config,
39
+ )
40
+ from .hash_utils import (
41
+ hash_string,
42
+ hashfile,
43
+ hashfolder,
44
+ )
45
+ from .logging_utils import (
46
+ check,
47
+ critical,
48
+ debug,
49
+ error,
50
+ info,
51
+ init_logging,
52
+ verbosity,
53
+ warning,
54
+ )
55
+ from .misc_utils import (
56
+ download_file,
57
+ folder_description,
58
+ format_size,
59
+ get_user_ip,
60
+ is_working_url,
61
+ now_string,
62
+ str2time,
63
+ time2str,
64
+ zip_folder,
65
+ )
66
+ from .path_utils import (
67
+ absolute2relative_path,
68
+ checkfile,
69
+ copyfile,
70
+ dir_exists,
71
+ file_exists,
72
+ folder_name_ext,
73
+ join,
74
+ make_directory,
75
+ path_without_home,
76
+ recursive_glob,
77
+ relative2absolute_path,
78
+ remove_directory,
79
+ remove_files,
80
+ size_file,
81
+ )
82
+ from .profile_utils import (
83
+ cpu_timer,
84
+ gpu_timer,
85
+ tic,
86
+ toc,
87
+ wall_timer,
88
+ )
89
+ from .string_utils import (
90
+ asciistring,
91
+ emptystring,
92
+ )
93
+ from .system_utils import (
94
+ get_nb_workers,
95
+ getpid,
96
+ linux,
97
+ macos,
98
+ openfile,
99
+ system,
100
+ unix,
101
+ windows,
102
+ )
103
+ from .temp_utils import (
104
+ temporary_filename,
105
+ temporary_folder,
106
+ temporary_remote_file,
107
+ )
108
+
109
+ __all__ = [
110
+ # system_utils
111
+ "windows",
112
+ "linux",
113
+ "macos",
114
+ "unix",
115
+ "get_nb_workers",
116
+ "system",
117
+ "openfile",
118
+ "getpid",
119
+
120
+ # logging_utils
121
+ "init_logging",
122
+ "debug",
123
+ "info",
124
+ "warning",
125
+ "error",
126
+ "critical",
127
+ "check",
128
+ "verbosity",
129
+
130
+ # temp_utils
131
+ "temporary_filename",
132
+ "temporary_folder",
133
+ "temporary_remote_file",
134
+
135
+ # path_utils
136
+ "file_exists",
137
+ "dir_exists",
138
+ "absolute2relative_path",
139
+ "relative2absolute_path",
140
+ "path_without_home",
141
+ "recursive_glob",
142
+ "size_file",
143
+ "checkfile",
144
+ "copyfile",
145
+ "remove_directory",
146
+ "remove_files",
147
+ "make_directory",
148
+ "join",
149
+ "folder_name_ext",
150
+
151
+ # hash_utils
152
+ "hash_string",
153
+ "hashfile",
154
+ "hashfolder",
155
+
156
+ # config_utils
157
+ "get_config",
158
+
159
+ # string_utils
160
+ "emptystring",
161
+ "asciistring",
162
+
163
+ # misc_utils
164
+ "now_string",
165
+ "format_size",
166
+ "folder_description",
167
+ "is_working_url",
168
+ "zip_folder",
169
+ "download_file",
170
+ "time2str",
171
+ "str2time",
172
+ "get_user_ip",
173
+
174
+ # profile_utils
175
+ "wall_timer",
176
+ "cpu_timer",
177
+ "gpu_timer",
178
+ "tic",
179
+ "toc",
180
+ ]