os_helper.api module

os_helper.api — HTTP surface for the safe, side-effect-free os_helper utilities.

Exposes a deliberately narrow slice of the library over FastAPI: OS/ hardware detection, hashing, ASCII normalization, size/time formatting, a URL reachability check, and config loading. All read-only or purely computational — nothing here mutates the filesystem (no mkdir/rm/cp/download endpoint). Those stay library/CLI-only: a general-purpose “delete this path over HTTP” endpoint is a different risk profile than what the rest of the suite’s [api] surfaces expose (bucket/sftp mutate a REMOTE store the caller already has credentials for; a bare filesystem-mutation endpoint here would let any HTTP caller touch the local disk). Widen deliberately, not by default.

FastAPI is an optional dependency (the [api] extra) — importing os_helper itself never requires it; only importing this module does.

Run it

uvicorn os_helper.api:app or the console entry point os-helper-api (docs at /docs).

Author

Warith HARCHAOUI, https://linkedin.com/in/warith-harchaoui

class os_helper.api.AsciiRequest(*, text, replacement_char='-', lower=True, allow_digits=True)

Bases: BaseModel

Body for POST /str/ascii.

Parameters:

• text (str)

• replacement_char (str)

• lower (bool)

• allow_digits (bool)

allow_digits: bool

lower: bool

model_config = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

replacement_char: str

text: str

class os_helper.api.ConfigRequest(*, keys, config_type, path=None, env_files=None)

Bases: BaseModel

Body for POST /config.

Mirrors os_helper.get_config()’s fallback order (file/folder -> .env files), minus the ambient-process-environment step (see config_endpoint()’s notes). path/env_files are paths on the SERVER’s filesystem — this is a local-first tool, not a place to read someone else’s config over the network.

Parameters:

• keys (list[str])

• config_type (str)

• path (str | None)

• env_files (list[str] | None)

config_type: str

env_files: list[str] | None

keys: list[str]

model_config = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

path: str | None

class os_helper.api.HashStringRequest(*, text, size=-1)

Bases: BaseModel

Body for POST /hash/string.

Parameters:

• text (str)

• size (int)

model_config = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

size: int

text: str

os_helper.api.ascii_endpoint(req)

Normalize a string into a filesystem-safe ASCII slug.

Parameters:

req (AsciiRequest) – The text to normalize and the slugging options (replacement character, lower-casing, digit handling).

Returns:

{"result": <slug>}.

Return type:

dict[str, str]

os_helper.api.config_endpoint(req)

Load a set of keys via os_helper.get_config() and return them.

Parameters:

req (ConfigRequest) – The keys to resolve plus the fallback-order inputs (config_type, path, env_files).

Returns:

Mapping with one entry per requested key.

Return type:

dict[str, Any]

Notes

Calls os_helper.get_config() with allow_ambient_env=False: a key can only resolve here from path or the requested env_files’ own contents, never by falling through to whatever the server process happened to inherit from its own environment at start-up. Without this, any network caller could name an arbitrary environment-variable key (AWS_SECRET_ACCESS_KEY, …) and get its live value back — a credential-exposure shape that a local CLI/library caller doesn’t have, since they already have direct access to that same process environment.

os_helper.api.format_size_endpoint(size)

Format a byte count as a human-readable string (e.g. ‘11.8 MB’).

Parameters:

size (int) – Byte count to format.

Returns:

{"formatted": <human-readable size>}.

Return type:

dict[str, str]

os_helper.api.hardware()

Return this machine’s hardware snapshot (CPU, RAM, GPU) as JSON.

Return type:

dict[str, Any]

os_helper.api.hash_string_endpoint(req)

Hash a string; size truncates the digest to that many hex characters.

Parameters:

req (HashStringRequest) – The text to hash and the optional truncation size.

Returns:

{"hash": <digest>}.

Return type:

dict[str, str]

os_helper.api.health()

Report that the server is up.

Return type:

dict[str, Any]

os_helper.api.main()

Console entry point (os-helper-api): serve the HTTP surface.

Local-first: binds to loopback by default (override with OS_HELPER_HOST / OS_HELPER_PORT).

Return type:

None

os_helper.api.now_endpoint(fmt='log')

Return a formatted timestamp.

Parameters:

fmt (str) – Timestamp style: 'log' or 'filename'.

Returns:

{"timestamp": <formatted timestamp>}.

Return type:

dict[str, str]

os_helper.api.os_system()

Return the current OS short name (macos / linux / windows / unknown).

Return type:

dict[str, str]

os_helper.api.url_ok_endpoint(url)

Check whether a URL is syntactically valid and reachable.

Parameters:

url (str) – URL to check.

Returns:

{"ok": <True if reachable>}.

Return type:

dict[str, bool]