os-helper 1.4.2__py3-none-any.whl

os_helper/__init__.py

@@ -0,0 +1,180 @@
+"""
+OS Helper
+
+A collection of cross-platform utility functions covering:
+- file and directory handling
+- system / OS detection and process helpers
+- string manipulation and ASCII normalization
+- temporary files and folders (including remote staging)
+- hashing of strings, files, and folders
+- configuration loading (JSON / YAML / .env / environment)
+- URL checks, downloads, zipping
+- logging and verbosity helpers
+
+Usage Example
+-------------
+>>> import os_helper as osh
+>>> osh.verbosity(1)
+>>> if osh.unix():
+...     osh.info("running on a Unix-based OS")
+>>> osh.info(osh.now_string("filename"))
+>>> h = osh.hash_string("hello", size=8)
+
+The same helpers are also exposed as an argparse CLI (``os-helper``), a
+click CLI (``os-helper-click``, install ``[cli]`` extra), a FastAPI HTTP
+surface (``os_helper.api``, install ``[api]`` extra) and an MCP tool set
+(``os-helper-mcp``, install ``[api,mcp]`` extras). See the README and
+``GUI.md`` for the multi-surface story.
+
+Author
+------
+Warith Harchaoui, Ph.D. — https://linkedin.com/in/warith-harchaoui/
+"""
+
+__author__ = "Warith Harchaoui, Ph.D."
+__email__ = "warithmetics@deraison.ai"
+
+from .config_utils import (
+    get_config,
+)
+from .hash_utils import (
+    hash_string,
+    hashfile,
+    hashfolder,
+)
+from .logging_utils import (
+    check,
+    critical,
+    debug,
+    error,
+    info,
+    init_logging,
+    verbosity,
+    warning,
+)
+from .misc_utils import (
+    download_file,
+    folder_description,
+    format_size,
+    get_user_ip,
+    is_working_url,
+    now_string,
+    str2time,
+    time2str,
+    zip_folder,
+)
+from .path_utils import (
+    absolute2relative_path,
+    checkfile,
+    copyfile,
+    dir_exists,
+    file_exists,
+    folder_name_ext,
+    join,
+    make_directory,
+    path_without_home,
+    recursive_glob,
+    relative2absolute_path,
+    remove_directory,
+    remove_files,
+    size_file,
+)
+from .profile_utils import (
+    cpu_timer,
+    gpu_timer,
+    tic,
+    toc,
+    wall_timer,
+)
+from .string_utils import (
+    asciistring,
+    emptystring,
+)
+from .system_utils import (
+    get_nb_workers,
+    getpid,
+    linux,
+    macos,
+    openfile,
+    system,
+    unix,
+    windows,
+)
+from .temp_utils import (
+    temporary_filename,
+    temporary_folder,
+    temporary_remote_file,
+)
+
+__all__ = [
+    # system_utils
+    "windows",
+    "linux",
+    "macos",
+    "unix",
+    "get_nb_workers",
+    "system",
+    "openfile",
+    "getpid",
+
+    # logging_utils
+    "init_logging",
+    "debug",
+    "info",
+    "warning",
+    "error",
+    "critical",
+    "check",
+    "verbosity",
+
+    # temp_utils
+    "temporary_filename",
+    "temporary_folder",
+    "temporary_remote_file",
+
+    # path_utils
+    "file_exists",
+    "dir_exists",
+    "absolute2relative_path",
+    "relative2absolute_path",
+    "path_without_home",
+    "recursive_glob",
+    "size_file",
+    "checkfile",
+    "copyfile",
+    "remove_directory",
+    "remove_files",
+    "make_directory",
+    "join",
+    "folder_name_ext",
+
+    # hash_utils
+    "hash_string",
+    "hashfile",
+    "hashfolder",
+
+    # config_utils
+    "get_config",
+
+    # string_utils
+    "emptystring",
+    "asciistring",
+
+    # misc_utils
+    "now_string",
+    "format_size",
+    "folder_description",
+    "is_working_url",
+    "zip_folder",
+    "download_file",
+    "time2str",
+    "str2time",
+    "get_user_ip",
+
+    # profile_utils
+    "wall_timer",
+    "cpu_timer",
+    "gpu_timer",
+    "tic",
+    "toc",
+]

os_helper/api.py

@@ -0,0 +1,430 @@
+"""
+OS Helper — FastAPI HTTP surface.
+
+Exposes the read-and-compute helpers of ``os_helper`` as HTTP endpoints
+so the toolkit can be dropped behind any reverse proxy and consumed by
+other services. Kept intentionally minimal:
+
+- **Reads** (JSON in, JSON out) for cheap, side-effect-free helpers:
+  OS detection, path predicates, string / hash utilities, misc
+  formatting, etc.
+- **Actions** (multipart in, ``FileResponse`` / ``StreamingResponse``
+  out) for helpers that produce artifacts (``/hash/file``,
+  ``/hash/folder``, ``/zip``, ``/describe``, ``/download``).
+- ``BackgroundTasks`` cleans temp files after the response has been
+  streamed — no leftover garbage on disk after a request.
+
+Install the extra to get the runtime dependencies::
+
+    pip install 'os-helper[api]'
+
+Then run the app with any ASGI server::
+
+    uvicorn os_helper.api:app --host 0.0.0.0 --port 8000
+
+Usage Example
+-------------
+>>> # Start the server:
+>>> #   uvicorn os_helper.api:app --reload
+>>> # Hash a string:
+>>> #   curl -s -X POST 'http://localhost:8000/hash/string' \\
+>>> #        -H 'Content-Type: application/json' \\
+>>> #        -d '{"value": "hello", "size": 8}'
+>>> # Zip an uploaded folder (multi-file upload):
+>>> #   curl -F 'files=@a.txt' -F 'files=@b.txt' -o out.zip \\
+>>> #        http://localhost:8000/zip
+>>> # Full OpenAPI docs at http://localhost:8000/docs
+
+Author
+------
+Warith Harchaoui, Ph.D. — https://linkedin.com/in/warith-harchaoui/
+"""
+
+from __future__ import annotations
+
+import io
+import shutil
+import tempfile
+import zipfile
+from pathlib import Path
+
+try:
+    from fastapi import BackgroundTasks, FastAPI, File, HTTPException, UploadFile
+    from fastapi.responses import FileResponse, JSONResponse, StreamingResponse
+    from pydantic import BaseModel, Field
+except ImportError as exc:  # pragma: no cover
+    raise ImportError(
+        "The FastAPI HTTP surface requires the [api] extra. "
+        "Install with: pip install 'os-helper[api]'"
+    ) from exc
+
+from . import (
+    asciistring,
+    download_file,
+    emptystring,
+    folder_description,
+    folder_name_ext,
+    format_size,
+    get_nb_workers,
+    get_user_ip,
+    getpid,
+    hash_string,
+    hashfile,
+    hashfolder,
+    is_working_url,
+    join,
+    linux,
+    macos,
+    now_string,
+    path_without_home,
+    size_file,
+    str2time,
+    time2str,
+    unix,
+    windows,
+    zip_folder,
+)
+
+# ---------------------------------------------------------------------------
+# App factory + shared plumbing
+# ---------------------------------------------------------------------------
+
+
+app = FastAPI(
+    title="OS Helper API",
+    description=(
+        "HTTP surface for the os-helper utilities: OS detection, path "
+        "manipulation, hashing, string normalization, misc formatting, "
+        "URL checks, zipping."
+    ),
+    version="1.4.2",
+    docs_url="/docs",
+    redoc_url="/redoc",
+)
+
+
+def _cleanup(*paths) -> None:
+    """Best-effort cleanup — never let a tidy-up failure kill a response."""
+    for p in paths:
+        try:
+            path = Path(p)
+            if path.is_dir():
+                shutil.rmtree(path, ignore_errors=True)
+            elif path.exists():
+                path.unlink(missing_ok=True)
+        except Exception:
+            pass
+
+
+def _new_tmpdir() -> Path:
+    """Create a request-scoped temp directory under the system temp root."""
+    return Path(tempfile.mkdtemp(prefix="os-helper-"))
+
+
+def _spool(upload: UploadFile, dest: Path) -> Path:
+    """Persist an UploadFile to disk without loading it into memory."""
+    with dest.open("wb") as fp:
+        shutil.copyfileobj(upload.file, fp)
+    return dest
+
+
+# ---------------------------------------------------------------------------
+# Meta
+# ---------------------------------------------------------------------------
+
+
+@app.get("/health", tags=["meta"])
+def health() -> dict:
+    """Simple liveness probe — no dependency check, just proves the app is up."""
+    return {"status": "ok"}
+
+
+# ---------------------------------------------------------------------------
+# OS detection
+# ---------------------------------------------------------------------------
+
+
+@app.get("/os/system", tags=["os"])
+def api_os_system() -> dict:
+    """Return the current OS name."""
+    if windows():
+        name = "windows"
+    elif macos():
+        name = "macos"
+    elif linux():
+        name = "linux"
+    else:
+        name = "unknown"
+    return {"system": name, "unix": unix()}
+
+
+@app.get("/os/flags", tags=["os"])
+def api_os_flags() -> dict:
+    """Return every OS-detection boolean at once."""
+    return {
+        "windows": windows(),
+        "linux": linux(),
+        "macos": macos(),
+        "unix": unix(),
+    }
+
+
+@app.get("/os/pid", tags=["os"])
+def api_os_pid() -> dict:
+    """Return the current process ID."""
+    return {"pid": getpid()}
+
+
+@app.get("/os/workers", tags=["os"])
+def api_os_workers(n: int = -1) -> dict:
+    """Resolve a worker count following sklearn's n_jobs convention."""
+    return {"workers": get_nb_workers(n)}
+
+
+# ---------------------------------------------------------------------------
+# Path helpers (all pure — POST body carries the string paths)
+# ---------------------------------------------------------------------------
+
+
+class PathIn(BaseModel):
+    """Envelope carrying a single filesystem path string."""
+    path: str = Field(..., description="Filesystem path (absolute or relative).")
+
+
+class JoinIn(BaseModel):
+    """Envelope carrying the components to join."""
+    parts: list[str] = Field(..., description="Path components to join into a single absolute path.")
+
+
+class RelIn(BaseModel):
+    """Envelope carrying the target path plus an optional base."""
+    path: str
+    base: str | None = None
+
+
+@app.post("/path/join", tags=["path"])
+def api_path_join(body: JoinIn) -> dict:
+    """Join components into an absolute, normalized path."""
+    return {"path": join(*body.parts)}
+
+
+@app.post("/path/no-home", tags=["path"])
+def api_path_no_home(body: PathIn) -> dict:
+    """Replace the user's home prefix with '~'."""
+    return {"path": path_without_home(body.path)}
+
+
+@app.post("/path/size", tags=["path"])
+def api_path_size(body: PathIn) -> dict:
+    """Return the size of a file in bytes (-1 when it does not exist)."""
+    return {"size": size_file(body.path)}
+
+
+@app.post("/path/split", tags=["path"])
+def api_path_split(body: PathIn) -> dict:
+    """Decompose a path into folder / name / ext."""
+    folder, name, ext = folder_name_ext(body.path)
+    return {"folder": folder, "name": name, "ext": ext}
+
+
+# ---------------------------------------------------------------------------
+# String helpers
+# ---------------------------------------------------------------------------
+
+
+class StringIn(BaseModel):
+    """Envelope carrying a single string value."""
+    value: str
+
+
+class AsciiIn(BaseModel):
+    """Envelope for the asciistring options."""
+    value: str
+    replacement_char: str = "-"
+    lower: bool = True
+    allow_digits: bool = True
+
+
+@app.post("/str/empty", tags=["str"])
+def api_str_empty(body: StringIn) -> dict:
+    """Check if VALUE is None / whitespace-only."""
+    return {"empty": emptystring(body.value)}
+
+
+@app.post("/str/ascii", tags=["str"])
+def api_str_ascii(body: AsciiIn) -> dict:
+    """Normalize a string to a filesystem-safe ASCII slug."""
+    return {"ascii": asciistring(
+        body.value,
+        replacement_char=body.replacement_char,
+        lower=body.lower,
+        allow_digits=body.allow_digits,
+    )}
+
+
+# ---------------------------------------------------------------------------
+# Hashing
+# ---------------------------------------------------------------------------
+
+
+class HashStringIn(BaseModel):
+    """Envelope for the hash_string call."""
+    value: str
+    size: int = -1
+
+
+@app.post("/hash/string", tags=["hash"])
+def api_hash_string(body: HashStringIn) -> dict:
+    """Hash a string; ``size`` truncates the digest to N chars when > 0."""
+    return {"hash": hash_string(body.value, size=body.size)}
+
+
+@app.post("/hash/file", tags=["hash"])
+def api_hash_file(
+    background: BackgroundTasks,
+    file: UploadFile = File(...),
+    date: bool = False,
+) -> JSONResponse:
+    """Hash an uploaded file's content."""
+    tmp = _new_tmpdir()
+    try:
+        src = _spool(file, tmp / (file.filename or "upload.bin"))
+        digest = hashfile(str(src), hash_content=True, date=date)
+    finally:
+        background.add_task(_cleanup, tmp)
+    return JSONResponse({"hash": digest})
+
+
+@app.post("/hash/folder", tags=["hash"])
+def api_hash_folder(
+    background: BackgroundTasks,
+    files: list[UploadFile] = File(...),
+    include_path: bool = False,
+    date: bool = False,
+) -> JSONResponse:
+    """Hash a set of uploaded files as if they lived in the same folder."""
+    tmp = _new_tmpdir()
+    try:
+        for f in files:
+            _spool(f, tmp / (f.filename or "upload.bin"))
+        digest = hashfolder(str(tmp), hash_content=True, hash_path=include_path, date=date)
+    finally:
+        background.add_task(_cleanup, tmp)
+    return JSONResponse({"hash": digest})
+
+
+# ---------------------------------------------------------------------------
+# Misc
+# ---------------------------------------------------------------------------
+
+
+@app.get("/misc/now", tags=["misc"])
+def api_misc_now(fmt: str = "log") -> dict:
+    """Return the current timestamp using the requested format."""
+    return {"now": now_string(fmt)}
+
+
+@app.get("/misc/format-size", tags=["misc"])
+def api_misc_format_size(nb_bytes: int) -> dict:
+    """Format a byte count as a human-readable string."""
+    return {"formatted": format_size(nb_bytes)}
+
+
+@app.get("/misc/time2str", tags=["misc"])
+def api_misc_time2str(seconds: float, no_space: bool = False) -> dict:
+    """Convert a duration in seconds to a readable string."""
+    return {"text": time2str(seconds, no_space=no_space)}
+
+
+@app.post("/misc/str2time", tags=["misc"])
+def api_misc_str2time(body: StringIn) -> dict:
+    """Parse a duration string into seconds."""
+    return {"seconds": str2time(body.value)}
+
+
+@app.get("/misc/url-ok", tags=["misc"])
+def api_misc_url_ok(url: str) -> dict:
+    """Check whether a URL is syntactically valid + reachable."""
+    return {"ok": is_working_url(url)}
+
+
+@app.get("/misc/ip", tags=["misc"])
+def api_misc_ip() -> dict:
+    """Fetch the caller's public IPv4 / IPv6 addresses."""
+    return get_user_ip()
+
+
+@app.post("/misc/describe", tags=["misc"])
+def api_misc_describe(
+    background: BackgroundTasks,
+    files: list[UploadFile] = File(...),
+    recursive: bool = True,
+) -> JSONResponse:
+    """Describe an uploaded set of files (relative path -> size)."""
+    tmp = _new_tmpdir()
+    try:
+        for f in files:
+            _spool(f, tmp / (f.filename or "upload.bin"))
+        # No side-effect files here — HTTP callers do not need html/json on disk.
+        result = folder_description(str(tmp), recursive=recursive, index_html=False, description_json=False)
+    finally:
+        background.add_task(_cleanup, tmp)
+    return JSONResponse(result)
+
+
+class DownloadIn(BaseModel):
+    """Envelope for the download endpoint."""
+    url: str
+
+
+@app.post("/misc/download", tags=["misc"])
+def api_misc_download(background: BackgroundTasks, body: DownloadIn):
+    """Download a URL and return the resulting file."""
+    tmp = _new_tmpdir()
+    filename = body.url.rstrip("/").split("/")[-1].split("?")[0] or "download.bin"
+    dst = tmp / filename
+    try:
+        download_file(body.url, file_path=str(dst))
+    except Exception as exc:
+        _cleanup(tmp)
+        raise HTTPException(status_code=502, detail=str(exc)) from exc
+    background.add_task(_cleanup, tmp)
+    return FileResponse(str(dst), filename=filename, media_type="application/octet-stream")
+
+
+# ---------------------------------------------------------------------------
+# Zip endpoint — takes a batch of uploads, returns a single .zip archive.
+# ---------------------------------------------------------------------------
+
+
+def _zip_folder_to_bytes(folder: Path) -> io.BytesIO:
+    """Bundle ``folder``'s contents into an in-memory ZIP for streaming."""
+    buf = io.BytesIO()
+    with zipfile.ZipFile(buf, "w", compression=zipfile.ZIP_DEFLATED) as zf:
+        for p in folder.rglob("*"):
+            if p.is_file():
+                zf.write(p, arcname=p.relative_to(folder))
+    buf.seek(0)
+    return buf
+
+
+@app.post("/zip", tags=["actions"])
+def api_zip(background: BackgroundTasks, files: list[UploadFile] = File(...)):
+    """Zip a batch of uploaded files and stream the archive back."""
+    if not files:
+        raise HTTPException(status_code=400, detail="need at least 1 file")
+    tmp = _new_tmpdir()
+    for f in files:
+        _spool(f, tmp / (f.filename or "upload.bin"))
+    # We call the library's zip_folder to keep the on-disk behavior identical
+    # with the CLI, then stream the resulting archive back.
+    zip_path = tmp.with_suffix(".zip")
+    zip_folder(str(tmp), zip_file_path=str(zip_path))
+    with zip_path.open("rb") as fp:
+        payload = io.BytesIO(fp.read())
+    background.add_task(_cleanup, tmp, zip_path)
+    return StreamingResponse(
+        payload,
+        media_type="application/zip",
+        headers={"Content-Disposition": 'attachment; filename="os-helper.zip"'},
+    )