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.
- os_helper-1.4.2/LICENSE +29 -0
- os_helper-1.4.2/PKG-INFO +270 -0
- os_helper-1.4.2/README.md +223 -0
- os_helper-1.4.2/os_helper/__init__.py +180 -0
- os_helper-1.4.2/os_helper/api.py +430 -0
- os_helper-1.4.2/os_helper/cli_argparse.py +757 -0
- os_helper-1.4.2/os_helper/cli_click.py +585 -0
- os_helper-1.4.2/os_helper/config_utils.py +209 -0
- os_helper-1.4.2/os_helper/hash_utils.py +160 -0
- os_helper-1.4.2/os_helper/logging_utils.py +339 -0
- os_helper-1.4.2/os_helper/mcp.py +88 -0
- os_helper-1.4.2/os_helper/misc_utils.py +434 -0
- os_helper-1.4.2/os_helper/path_utils.py +460 -0
- os_helper-1.4.2/os_helper/profile_utils.py +290 -0
- os_helper-1.4.2/os_helper/string_utils.py +113 -0
- os_helper-1.4.2/os_helper/system_utils.py +209 -0
- os_helper-1.4.2/os_helper/temp_utils.py +275 -0
- os_helper-1.4.2/os_helper.egg-info/PKG-INFO +270 -0
- os_helper-1.4.2/os_helper.egg-info/SOURCES.txt +27 -0
- os_helper-1.4.2/os_helper.egg-info/dependency_links.txt +1 -0
- os_helper-1.4.2/os_helper.egg-info/entry_points.txt +4 -0
- os_helper-1.4.2/os_helper.egg-info/requires.txt +26 -0
- os_helper-1.4.2/os_helper.egg-info/top_level.txt +1 -0
- os_helper-1.4.2/pyproject.toml +99 -0
- os_helper-1.4.2/setup.cfg +4 -0
- os_helper-1.4.2/tests/test_api.py +99 -0
- os_helper-1.4.2/tests/test_cli.py +155 -0
- os_helper-1.4.2/tests/test_mcp.py +39 -0
- os_helper-1.4.2/tests/test_os_helpers.py +569 -0
os_helper-1.4.2/LICENSE
ADDED
|
@@ -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.
|
os_helper-1.4.2/PKG-INFO
ADDED
|
@@ -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
|
+
[](https://github.com/warith-harchaoui/os-helper/actions/workflows/ci.yml) [](LICENSE) [](#)
|
|
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
|
+
[](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
|
+
[](https://github.com/warith-harchaoui/os-helper/actions/workflows/ci.yml) [](LICENSE) [](#)
|
|
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
|
+
[](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
|
+
]
|