os_helper.system_utils module

System Utilities

A script that needs to know “which operating system am I running on” or “run this shell command and give me its output” would otherwise reach for sys.platform string comparisons and subprocess.run calls scattered across the codebase, each one slightly different. This module gives every helper in the suite the same answer to those two questions: a handful of one-line OS checks (windows(), linux(), macos(), unix()), and system(), a subprocess wrapper that never opens a shell (so a filename with a stray ; in it cannot be interpreted as a second command) and returns captured stdout/stderr as a plain dict instead of a CompletedProcess object the caller has to know how to unpack.

Usage example

>>> import os_helper as osh
>>> osh.unix()
True
>>> osh.system("echo hello")["out"].strip()
'hello'

Author

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

os_helper.system_utils.get_nb_workers(workers=-1)

Resolve a worker count, following scikit-learn’s n_jobs convention.

The default pool size is os.cpu_count() (or 1 if that returns None), overridable via the NB_WORKERS environment variable.

Parameters:

workers (int, optional) –

• 0 : use the full pool size.

• > 0: use exactly that many workers.

• < 0: use pool_size + workers + 1 (e.g. -1 → all CPUs, -2 → all but one), clamped to at least 1.

Returns:

The resolved worker count (always >= 1).

Return type:

int

Example

>>> get_nb_workers()  # -1 → all available CPU cores
4

os_helper.system_utils.getpid()

Return the current process ID as a string.

Returns:

str(os.getpid()).

Return type:

str

os_helper.system_utils.linux()

Determine if the current operating system is Linux.

Returns:

True if the operating system is Linux, False otherwise.

Return type:

bool

os_helper.system_utils.macos()

Determine if the current operating system is macOS.

Returns:

True if the operating system is macOS, False otherwise.

Return type:

bool

os_helper.system_utils.openfile(filename)

Open a file in the platform’s default application.

Uses os.startfile on Windows, open on macOS, and xdg-open on Linux. Exceptions from the underlying call are propagated as-is so the caller can react to them.

Parameters:

filename (str) – The path to the file to open.

Raises:

OSError – If the platform is unsupported or the underlying open call fails.

Return type:

None

os_helper.system_utils.system(cmd, expected_output='', check_exitcode=True, check_empty=False)

Run a shell-style command via subprocess and capture its output.

The command string is parsed with shlex.split() and executed without spawning an actual shell (shell=False), which avoids shell-injection pitfalls while still accepting a familiar command string.

Parameters:

• cmd (str) – Command line to execute (e.g., "ffmpeg -i in.mp4 out.mp3").

• expected_output (str, optional) – If non-empty, a file or directory path expected to be present once the command completes successfully.

• check_exitcode (bool, optional) – If True, assert that the process exit code is 0.

• check_empty (bool, optional) – If True, also assert that expected_output is non-empty (file size > 0 / directory not empty).

Returns:

{"out": <stdout as str>, "err": <stderr as str>}.

Return type:

dict

Raises:

AssertionError – If the exit code check or the expected-output check fails.

os_helper.system_utils.unix()

Determine if the current operating system is Unix-based (Linux or macOS).

Returns:

True if the operating system is Unix-based (Linux or macOS), False otherwise.

Return type:

bool

os_helper.system_utils.windows()

Determine if the current operating system is Windows.

Returns:

True if the operating system is Windows, False otherwise.

Return type:

bool