System Module¶

The rite.system module provides system-level operations including process management, environment variables, and platform detection.

Overview¶

system ¶

System Module¶

System-level operations and utilities.

This module provides comprehensive utilities for system operations including process management, environment variables, platform detection, path operations, and shell command handling.

Submodules¶

process: Process and subprocess management
environment: Environment variable operations
platform: Platform and OS detection
path: Path operations and queries
shell: Shell command utilities

Examples¶

from rite.system import process_run, env_get, platform_name code, out, err = process_run(["ls"], Path.cwd()) home = env_get("HOME") os_name = platform_name()

Notes¶

Legacy functions run_command and get_escaped_command_arg are still available for backward compatibility.

Modules¶

env_delete ¶

Environment Delete¶

Delete environment variable.

Examples¶

from rite.system.environment import env_delete env_delete("MY_VAR")

Functions¶

env_delete ¶

env_delete(key: str) -> None

Delete environment variable.

Parameters:

Name	Type	Description	Default
`key`	`str`	Environment variable name.	required

Returns:

Type	Description
`None`	None

Examples:

>>> env_delete("MY_VAR")

Notes

Silently ignores if variable doesn't exist.

env_get ¶

Environment Get¶

Get environment variable value.

Examples¶

from rite.system.environment import env_get env_get("PATH")

Functions¶

env_get ¶

env_get(key: str, default: str | None = None) -> str | None

Get environment variable value.

Parameters:

Name	Type	Description	Default
`key`	`str`	Environment variable name.	required
`default`	`str \| None`	Default value if not found.	`None`

Returns:

Type	Description
`str \| None`	Variable value or default.

Examples:

>>> env_get("PATH")
'/usr/bin:/bin'
>>> env_get("MISSING", "default")
'default'

Notes

Returns None if not found and no default.

env_list ¶

Environment List¶

Get all environment variables.

Examples¶

from rite.system.environment import env_list env_list()

Functions¶

env_list ¶

env_list() -> dict[str, str]

Get all environment variables as dictionary.

Returns:

Type	Description
`dict[str, str]`	Dictionary of environment variables.

Examples:

>>> env_list()
{'PATH': '/usr/bin', 'HOME': '/home/user', ...}

Notes

Returns a copy, modifications don't affect environment.

env_set ¶

Environment Set¶

Set environment variable value.

Examples¶

from rite.system.environment import env_set env_set("MY_VAR", "value")

Functions¶

env_set ¶

env_set(key: str, value: str) -> None

Set environment variable value.

Parameters:

Name	Type	Description	Default
`key`	`str`	Environment variable name.	required
`value`	`str`	Value to set.	required

Returns:

Type	Description
`None`	None

Examples:

>>> env_set("MY_VAR", "value")
>>> env_get("MY_VAR")
'value'

Notes

Affects current process and children.

environment ¶

Environment Module¶

Environment variable operations.

This submodule provides utilities for reading and modifying environment variables.

Examples¶

from rite.system.environment import env_get, env_set env_set("MY_VAR", "value") env_get("MY_VAR") 'value'

Modules¶

env_delete ¶

Environment Delete¶

Delete environment variable.

Examples¶

from rite.system.environment import env_delete env_delete("MY_VAR")

Functions¶

env_delete ¶

env_delete(key: str) -> None

Delete environment variable.

Parameters:

Name	Type	Description	Default
`key`	`str`	Environment variable name.	required

Returns:

Type	Description
`None`	None

Examples:

>>> env_delete("MY_VAR")

Notes

Silently ignores if variable doesn't exist.

env_get ¶

Environment Get¶

Get environment variable value.

Examples¶

from rite.system.environment import env_get env_get("PATH")

Functions¶

env_get ¶

env_get(key: str, default: str | None = None) -> str | None

Get environment variable value.

Parameters:

Name	Type	Description	Default
`key`	`str`	Environment variable name.	required
`default`	`str \| None`	Default value if not found.	`None`

Returns:

Type	Description
`str \| None`	Variable value or default.

Examples:

>>> env_get("PATH")
'/usr/bin:/bin'
>>> env_get("MISSING", "default")
'default'

Notes

Returns None if not found and no default.

env_list ¶

Environment List¶

Get all environment variables.

Examples¶

from rite.system.environment import env_list env_list()

Functions¶

env_list ¶

env_list() -> dict[str, str]

Get all environment variables as dictionary.

Returns:

Type	Description
`dict[str, str]`	Dictionary of environment variables.

Examples:

>>> env_list()
{'PATH': '/usr/bin', 'HOME': '/home/user', ...}

Notes

Returns a copy, modifications don't affect environment.

env_set ¶

Environment Set¶

Set environment variable value.

Examples¶

from rite.system.environment import env_set env_set("MY_VAR", "value")

Functions¶

env_set ¶

env_set(key: str, value: str) -> None

Set environment variable value.

Parameters:

Name	Type	Description	Default
`key`	`str`	Environment variable name.	required
`value`	`str`	Value to set.	required

Returns:

Type	Description
`None`	None

Examples:

>>> env_set("MY_VAR", "value")
>>> env_get("MY_VAR")
'value'

Notes

Affects current process and children.

get_escaped_command_arg ¶

Command Argument Escaping¶

Escape command line arguments for safe shell usage.

Functions¶

get_escaped_command_arg ¶

get_escaped_command_arg(arg: str) -> str

Escapes a command line argument to make it safe for shell usage.

Parameters:

Name	Type	Description	Default
`arg`	`str`	The argument to escape.	required

Returns:

Name	Type	Description
`str`	`str`	The escaped argument.

path ¶

Path Module¶

Path operation utilities.

This submodule provides utilities for path operations and queries using pathlib.

Examples¶

from rite.system.path import path_exists, path_join path_exists("/tmp") True path_join("/tmp", "file.txt") '/tmp/file.txt'

Modules¶

path_absolute ¶

Path Absolute¶

Get absolute path.

Examples¶

from rite.system.path import path_absolute path_absolute(".") '/current/working/directory'

Functions¶

path_absolute ¶

path_absolute(path: str | Path) -> str

Get absolute path as string.

Parameters:

Name	Type	Description	Default
`path`	`str \| Path`	Relative or absolute path.	required

Returns:

Type	Description
`str`	Absolute path string.

Examples:

>>> path_absolute(".")
'/current/working/directory'
>>> path_absolute("../parent")
'/parent/directory'

Notes

Resolves symlinks and relative paths.

path_exists ¶

Path Exists¶

Check if path exists.

Examples¶

from rite.system.path import path_exists path_exists("/tmp") True

Functions¶

path_exists ¶

path_exists(path: str | Path) -> bool

Check if path exists.

Parameters:

Name	Type	Description	Default
`path`	`str \| Path`	Path to check.	required

Returns:

Type	Description
`bool`	True if exists, False otherwise.

Examples:

>>> path_exists("/tmp")
True
>>> path_exists("/nonexistent")
False

Notes

Works for files and directories.

path_is_dir ¶

Path Is Directory¶

Check if path is a directory.

Examples¶

from rite.system.path import path_is_dir path_is_dir("/tmp") True

Functions¶

path_is_dir ¶

path_is_dir(path: str | Path) -> bool

Check if path is a directory.

Parameters:

Name	Type	Description	Default
`path`	`str \| Path`	Path to check.	required

Returns:

Type	Description
`bool`	True if directory, False otherwise.

Examples:

>>> path_is_dir("/tmp")
True
>>> path_is_dir("/etc/hosts")
False

Notes

Returns False if path doesn't exist.

path_is_file ¶

Path Is File¶

Check if path is a file.

Examples¶

from rite.system.path import path_is_file path_is_file("/etc/hosts") True

Functions¶

path_is_file ¶

path_is_file(path: str | Path) -> bool

Check if path is a file.

Parameters:

Name	Type	Description	Default
`path`	`str \| Path`	Path to check.	required

Returns:

Type	Description
`bool`	True if file, False otherwise.

Examples:

>>> path_is_file("/etc/hosts")
True
>>> path_is_file("/tmp")
False

Notes

Returns False if path doesn't exist.

path_join ¶

Path Join¶

Join path components.

Examples¶

from rite.system.path import path_join path_join("/tmp", "file.txt") '/tmp/file.txt'

Functions¶

path_join ¶

path_join(*parts: str) -> str

Join path components into single path.

Parameters:

Name	Type	Description	Default
`*parts`	`str`	Path components to join.	`()`

Returns:

Type	Description
`str`	Joined path string.

Examples:

>>> path_join("/tmp", "dir", "file.txt")
'/tmp/dir/file.txt'
>>> path_join(".", "file.txt")
'./file.txt'

Notes

Uses platform-specific separator.

path_absolute ¶

Path Absolute¶

Get absolute path.

Examples¶

from rite.system.path import path_absolute path_absolute(".") '/current/working/directory'

Functions¶

path_absolute ¶

path_absolute(path: str | Path) -> str

Get absolute path as string.

Parameters:

Name	Type	Description	Default
`path`	`str \| Path`	Relative or absolute path.	required

Returns:

Type	Description
`str`	Absolute path string.

Examples:

>>> path_absolute(".")
'/current/working/directory'
>>> path_absolute("../parent")
'/parent/directory'

Notes

Resolves symlinks and relative paths.

path_exists ¶

Path Exists¶

Check if path exists.

Examples¶

from rite.system.path import path_exists path_exists("/tmp") True

Functions¶

path_exists ¶

path_exists(path: str | Path) -> bool

Check if path exists.

Parameters:

Name	Type	Description	Default
`path`	`str \| Path`	Path to check.	required

Returns:

Type	Description
`bool`	True if exists, False otherwise.

Examples:

>>> path_exists("/tmp")
True
>>> path_exists("/nonexistent")
False

Notes

Works for files and directories.

path_is_dir ¶

Path Is Directory¶

Check if path is a directory.

Examples¶

from rite.system.path import path_is_dir path_is_dir("/tmp") True

Functions¶

path_is_dir ¶

path_is_dir(path: str | Path) -> bool

Check if path is a directory.

Parameters:

Name	Type	Description	Default
`path`	`str \| Path`	Path to check.	required

Returns:

Type	Description
`bool`	True if directory, False otherwise.

Examples:

>>> path_is_dir("/tmp")
True
>>> path_is_dir("/etc/hosts")
False

Notes

Returns False if path doesn't exist.

path_is_file ¶

Path Is File¶

Check if path is a file.

Examples¶

from rite.system.path import path_is_file path_is_file("/etc/hosts") True

Functions¶

path_is_file ¶

path_is_file(path: str | Path) -> bool

Check if path is a file.

Parameters:

Name	Type	Description	Default
`path`	`str \| Path`	Path to check.	required

Returns:

Type	Description
`bool`	True if file, False otherwise.

Examples:

>>> path_is_file("/etc/hosts")
True
>>> path_is_file("/tmp")
False

Notes

Returns False if path doesn't exist.

path_join ¶

Path Join¶

Join path components.

Examples¶

from rite.system.path import path_join path_join("/tmp", "file.txt") '/tmp/file.txt'

Functions¶

path_join ¶

path_join(*parts: str) -> str

Join path components into single path.

Parameters:

Name	Type	Description	Default
`*parts`	`str`	Path components to join.	`()`

Returns:

Type	Description
`str`	Joined path string.

Examples:

>>> path_join("/tmp", "dir", "file.txt")
'/tmp/dir/file.txt'
>>> path_join(".", "file.txt")
'./file.txt'

Notes

Uses platform-specific separator.

platform ¶

Platform Module¶

Platform and OS detection utilities.

This submodule provides utilities for detecting the operating system, architecture, and platform information.

Examples¶

from rite.system.platform import platform_name, platform_is_linux platform_name() 'Linux' platform_is_linux() True

Modules¶

platform_architecture ¶

Platform Architecture¶

Get system architecture.

Examples¶

from rite.system.platform import platform_architecture platform_architecture() 'x86_64'

Functions¶

platform_architecture ¶

platform_architecture() -> str

Get system architecture.

Returns:

Type	Description
`str`	Architecture string (x86_64, arm64, etc).

Examples:

>>> platform_architecture()
'x86_64'
>>> platform_architecture()
'arm64'

Notes

Returns machine type from platform.machine().

platform_is_linux ¶

Platform Is Linux¶

Check if running on Linux.

Examples¶

from rite.system.platform import platform_is_linux platform_is_linux() True

Functions¶

platform_is_linux ¶

platform_is_linux() -> bool

Check if running on Linux.

Returns:

Type	Description
`bool`	True if Linux, False otherwise.

Examples:

>>> platform_is_linux()
True
>>> platform_is_linux()
False

Notes

Checks if platform.system() is 'Linux'.

platform_is_macos ¶

Platform Is MacOS¶

Check if running on macOS.

Examples¶

from rite.system.platform import platform_is_macos platform_is_macos() True

Functions¶

platform_is_macos ¶

platform_is_macos() -> bool

Check if running on macOS.

Returns:

Type	Description
`bool`	True if macOS, False otherwise.

Examples:

>>> platform_is_macos()
True
>>> platform_is_macos()
False

Notes

Checks if platform.system() is 'Darwin'.

platform_is_windows ¶

Platform Is Windows¶

Check if running on Windows.

Examples¶

from rite.system.platform import platform_is_windows platform_is_windows() False

Functions¶

platform_is_windows ¶

platform_is_windows() -> bool

Check if running on Windows.

Returns:

Type	Description
`bool`	True if Windows, False otherwise.

Examples:

>>> platform_is_windows()
False
>>> platform_is_windows()
True

Notes

Checks if platform.system() is 'Windows'.

platform_name ¶

Platform Name¶

Get operating system name.

Examples¶

from rite.system.platform import platform_name platform_name() 'Linux'

Functions¶

platform_name ¶

platform_name() -> str

Get operating system name.

Returns:

Type	Description
`str`	OS name (Linux, Darwin, Windows, etc).

Examples:

>>> platform_name()
'Linux'
>>> platform_name()
'Darwin'

Notes

Returns system name from platform.system().

platform_python_version ¶

Platform Python Version¶

Get Python version information.

Examples¶

from rite.system.platform import platform_python_version platform_python_version() '3.10.5'

Functions¶

platform_python_version ¶

platform_python_version() -> str

Get Python version string.

Returns:

Type	Description
`str`	Python version (e.g., '3.10.5').

Examples:

>>> platform_python_version()
'3.10.5'
>>> platform_python_version()
'3.11.2'

Notes

Returns version from platform.python_version().

platform_architecture ¶

Platform Architecture¶

Get system architecture.

Examples¶

from rite.system.platform import platform_architecture platform_architecture() 'x86_64'

Functions¶

platform_architecture ¶

platform_architecture() -> str

Get system architecture.

Returns:

Type	Description
`str`	Architecture string (x86_64, arm64, etc).

Examples:

>>> platform_architecture()
'x86_64'
>>> platform_architecture()
'arm64'

Notes

Returns machine type from platform.machine().

platform_is_linux ¶

Platform Is Linux¶

Check if running on Linux.

Examples¶

from rite.system.platform import platform_is_linux platform_is_linux() True

Functions¶

platform_is_linux ¶

platform_is_linux() -> bool

Check if running on Linux.

Returns:

Type	Description
`bool`	True if Linux, False otherwise.

Examples:

>>> platform_is_linux()
True
>>> platform_is_linux()
False

Notes

Checks if platform.system() is 'Linux'.

platform_is_macos ¶

Platform Is MacOS¶

Check if running on macOS.

Examples¶

from rite.system.platform import platform_is_macos platform_is_macos() True

Functions¶

platform_is_macos ¶

platform_is_macos() -> bool

Check if running on macOS.

Returns:

Type	Description
`bool`	True if macOS, False otherwise.

Examples:

>>> platform_is_macos()
True
>>> platform_is_macos()
False

Notes

Checks if platform.system() is 'Darwin'.

platform_is_windows ¶

Platform Is Windows¶

Check if running on Windows.

Examples¶

from rite.system.platform import platform_is_windows platform_is_windows() False

Functions¶

platform_is_windows ¶

platform_is_windows() -> bool

Check if running on Windows.

Returns:

Type	Description
`bool`	True if Windows, False otherwise.

Examples:

>>> platform_is_windows()
False
>>> platform_is_windows()
True

Notes

Checks if platform.system() is 'Windows'.

platform_name ¶

Platform Name¶

Get operating system name.

Examples¶

from rite.system.platform import platform_name platform_name() 'Linux'

Functions¶

platform_name ¶

platform_name() -> str

Get operating system name.

Returns:

Type	Description
`str`	OS name (Linux, Darwin, Windows, etc).

Examples:

>>> platform_name()
'Linux'
>>> platform_name()
'Darwin'

Notes

Returns system name from platform.system().

platform_python_version ¶

Platform Python Version¶

Get Python version information.

Examples¶

from rite.system.platform import platform_python_version platform_python_version() '3.10.5'

Functions¶

platform_python_version ¶

platform_python_version() -> str

Get Python version string.

Returns:

Type	Description
`str`	Python version (e.g., '3.10.5').

Examples:

>>> platform_python_version()
'3.10.5'
>>> platform_python_version()
'3.11.2'

Notes

Returns version from platform.python_version().

process ¶

Process Module¶

Process and subprocess management.

This submodule provides utilities for executing system commands and managing subprocess operations.

Examples¶

from rite.system.process import process_run code, out, err = process_run(["ls"], Path.cwd())

Modules¶

process_call ¶

Process Call¶

Execute command and wait for completion.

Examples¶

from rite.system.process import process_call exit_code = process_call(["ls", "-la"])

Functions¶

process_call ¶

process_call(cmd: list[str], cwd: Path | str | None = None) -> int

Execute command and return exit code.

Parameters:

Name	Type	Description	Default
`cmd`	`list[str]`	Command as list of strings.	required
`cwd`	`Path \| str \| None`	Working directory. Defaults to current.	`None`

Returns:

Type	Description
`int`	Command exit code.

Examples:

>>> process_call(["echo", "hello"])
0
>>> process_call(["false"])
1

Notes

Does not capture output. Output goes to terminal.

process_check_output ¶

Process Check Output¶

Execute command and return output.

Examples¶

from rite.system.process import process_check_output output = process_check_output(["echo", "hello"])

Functions¶

process_check_output ¶

process_check_output(cmd: list[str], cwd: Path | str | None = None) -> str

Execute command and return stdout.

Parameters:

Name	Type	Description	Default
`cmd`	`list[str]`	Command as list of strings.	required
`cwd`	`Path \| str \| None`	Working directory. Defaults to current.	`None`

Returns:

Type	Description
`str`	Command stdout as string.

Raises:

Type	Description
`CalledProcessError`	If command fails.

Examples:

>>> process_check_output(["echo", "hello"])
'hello'

Notes

Raises exception on non-zero exit. Uses check_output for subprocess execution.

process_run ¶

Process Run Command¶

Execute command in subprocess.

Examples¶

from rite.system.process import process_run code, out, err = process_run(["ls", "-la"], Path.cwd())

Functions¶

process_run ¶

process_run(cmd: list[str], cwd: Path | str | None = None, check: bool = False) -> tuple[int, str, str]

Run command in subprocess and return result.

Parameters:

Name	Type	Description	Default
`cmd`	`list[str]`	Command as list of strings.	required
`cwd`	`Path \| str \| None`	Working directory. Defaults to current.	`None`
`check`	`bool`	Raise exception on non-zero exit.	`False`

Returns:

Type	Description
`tuple[int, str, str]`	Tuple of (return_code, stdout, stderr).

Raises:

Type	Description
`CalledProcessError`	If check=True and command fails.

Examples:

>>> process_run(["echo", "hello"])
(0, 'hello', '')
>>> process_run(["ls"], Path("/tmp"))
(0, '...', '')

Notes

Uses Popen for subprocess execution. Output is text mode with UTF-8 encoding.

process_call ¶

Process Call¶

Execute command and wait for completion.

Examples¶

from rite.system.process import process_call exit_code = process_call(["ls", "-la"])

Functions¶

process_call ¶

process_call(cmd: list[str], cwd: Path | str | None = None) -> int

Execute command and return exit code.

Parameters:

Name	Type	Description	Default
`cmd`	`list[str]`	Command as list of strings.	required
`cwd`	`Path \| str \| None`	Working directory. Defaults to current.	`None`

Returns:

Type	Description
`int`	Command exit code.

Examples:

>>> process_call(["echo", "hello"])
0
>>> process_call(["false"])
1

Notes

Does not capture output. Output goes to terminal.

process_check_output ¶

Process Check Output¶

Execute command and return output.

Examples¶

from rite.system.process import process_check_output output = process_check_output(["echo", "hello"])

Functions¶

process_check_output ¶

process_check_output(cmd: list[str], cwd: Path | str | None = None) -> str

Execute command and return stdout.

Parameters:

Name	Type	Description	Default
`cmd`	`list[str]`	Command as list of strings.	required
`cwd`	`Path \| str \| None`	Working directory. Defaults to current.	`None`

Returns:

Type	Description
`str`	Command stdout as string.

Raises:

Type	Description
`CalledProcessError`	If command fails.

Examples:

>>> process_check_output(["echo", "hello"])
'hello'

Notes

Raises exception on non-zero exit. Uses check_output for subprocess execution.

process_run ¶

Process Run Command¶

Execute command in subprocess.

Examples¶

from rite.system.process import process_run code, out, err = process_run(["ls", "-la"], Path.cwd())

Functions¶

process_run ¶

process_run(cmd: list[str], cwd: Path | str | None = None, check: bool = False) -> tuple[int, str, str]

Run command in subprocess and return result.

Parameters:

Name	Type	Description	Default
`cmd`	`list[str]`	Command as list of strings.	required
`cwd`	`Path \| str \| None`	Working directory. Defaults to current.	`None`
`check`	`bool`	Raise exception on non-zero exit.	`False`

Returns:

Type	Description
`tuple[int, str, str]`	Tuple of (return_code, stdout, stderr).

Raises:

Type	Description
`CalledProcessError`	If check=True and command fails.

Examples:

>>> process_run(["echo", "hello"])
(0, 'hello', '')
>>> process_run(["ls"], Path("/tmp"))
(0, '...', '')

Notes

Uses Popen for subprocess execution. Output is text mode with UTF-8 encoding.

run_command ¶

Command Execution¶

Execute system commands in subprocess.

Functions¶

run_command ¶

run_command(cmd: list[str], cwd: Path, check: bool = False) -> tuple[int, str, str]

Run a command in a subprocess and return the result.

Parameters:

Name	Type	Description	Default
`cmd`	`list[str]`	The command to run.	required
`cwd`	`Path`	The working directory to run the command in.	required
`check`	`bool`	Whether to check the return code.	`False`

Returns:

Type	Description
`tuple[int, str, str]`	A tuple containing the return code, stdout, and stderr.

shell ¶

Shell Module¶

Shell command utilities.

This submodule provides utilities for safely handling shell commands, arguments, and escaping.

Examples¶

from rite.system.shell import shell_escape, shell_split shell_escape("file name.txt") "'file name.txt'" shell_split("ls -la '/tmp/file.txt'") ['ls', '-la', '/tmp/file.txt']

Modules¶

shell_escape ¶

Shell Escape¶

Escape shell argument.

Examples¶

from rite.system.shell import shell_escape shell_escape("file name.txt") "'file name.txt'"

Functions¶

shell_escape ¶

shell_escape(arg: str) -> str

Escape shell argument for safe usage.

Parameters:

Name	Type	Description	Default
`arg`	`str`	Argument to escape.	required

Returns:

Type	Description
`str`	Escaped argument string.

Examples:

>>> shell_escape("file name.txt")
"'file name.txt'"
>>> shell_escape("simple")
'simple'

Notes

Uses shlex.quote for proper escaping. Safe for shell command construction.

shell_join ¶

Shell Join¶

Join command arguments into shell string.

Examples¶

from rite.system.shell import shell_join shell_join(["ls", "-la", "file name.txt"]) "ls -la 'file name.txt'"

Functions¶

shell_join ¶

shell_join(args: list[str]) -> str

Join command arguments into shell string.

Parameters:

Name	Type	Description	Default
`args`	`list[str]`	List of command arguments.	required

Returns:

Type	Description
`str`	Shell command string.

Examples:

>>> shell_join(["ls", "-la"])
'ls -la'
>>> shell_join(["echo", "hello world"])
"echo 'hello world'"

Notes

Uses shlex.join for proper escaping. Python 3.8+ required for shlex.join.

shell_split ¶

Shell Split¶

Split shell command string.

Examples¶

from rite.system.shell import shell_split shell_split("ls -la '/tmp/file name.txt'") ['ls', '-la', '/tmp/file name.txt']

Functions¶

shell_split ¶

shell_split(cmd: str) -> list[str]

Split shell command string into arguments.

Parameters:

Name	Type	Description	Default
`cmd`	`str`	Command string to split.	required

Returns:

Type	Description
`list[str]`	List of command arguments.

Examples:

>>> shell_split("ls -la")
['ls', '-la']
>>> shell_split("echo 'hello world'")
['echo', 'hello world']

Notes

Uses shlex.split for proper parsing. Handles quoted arguments correctly.

shell_escape ¶

Shell Escape¶

Escape shell argument.

Examples¶

from rite.system.shell import shell_escape shell_escape("file name.txt") "'file name.txt'"

Functions¶

shell_escape ¶

shell_escape(arg: str) -> str

Escape shell argument for safe usage.

Parameters:

Name	Type	Description	Default
`arg`	`str`	Argument to escape.	required

Returns:

Type	Description
`str`	Escaped argument string.

Examples:

>>> shell_escape("file name.txt")
"'file name.txt'"
>>> shell_escape("simple")
'simple'

Notes

Uses shlex.quote for proper escaping. Safe for shell command construction.

shell_join ¶

Shell Join¶

Join command arguments into shell string.

Examples¶

from rite.system.shell import shell_join shell_join(["ls", "-la", "file name.txt"]) "ls -la 'file name.txt'"

Functions¶

shell_join ¶

shell_join(args: list[str]) -> str

Join command arguments into shell string.

Parameters:

Name	Type	Description	Default
`args`	`list[str]`	List of command arguments.	required

Returns:

Type	Description
`str`	Shell command string.

Examples:

>>> shell_join(["ls", "-la"])
'ls -la'
>>> shell_join(["echo", "hello world"])
"echo 'hello world'"

Notes

Uses shlex.join for proper escaping. Python 3.8+ required for shlex.join.

shell_split ¶

Shell Split¶

Split shell command string.

Examples¶

from rite.system.shell import shell_split shell_split("ls -la '/tmp/file name.txt'") ['ls', '-la', '/tmp/file name.txt']

Functions¶

shell_split ¶

shell_split(cmd: str) -> list[str]

Split shell command string into arguments.

Parameters:

Name	Type	Description	Default
`cmd`	`str`	Command string to split.	required

Returns:

Type	Description
`list[str]`	List of command arguments.

Examples:

>>> shell_split("ls -la")
['ls', '-la']
>>> shell_split("echo 'hello world'")
['echo', 'hello world']

Notes

Uses shlex.split for proper parsing. Handles quoted arguments correctly.

Submodules¶

Process¶

Run and manage system processes.

Process Module¶

Process and subprocess management.

This submodule provides utilities for executing system commands and managing subprocess operations.

Examples¶

from rite.system.process import process_run code, out, err = process_run(["ls"], Path.cwd())

Modules¶

process_run ¶

Process Run Command¶

Execute command in subprocess.

Examples¶

from rite.system.process import process_run code, out, err = process_run(["ls", "-la"], Path.cwd())

Functions¶

process_run ¶

process_run(cmd: list[str], cwd: Path | str | None = None, check: bool = False) -> tuple[int, str, str]

Run command in subprocess and return result.

Parameters:

Name	Type	Description	Default
`cmd`	`list[str]`	Command as list of strings.	required
`cwd`	`Path \| str \| None`	Working directory. Defaults to current.	`None`
`check`	`bool`	Raise exception on non-zero exit.	`False`

Returns:

Type	Description
`tuple[int, str, str]`	Tuple of (return_code, stdout, stderr).

Raises:

Type	Description
`CalledProcessError`	If check=True and command fails.

Examples:

>>> process_run(["echo", "hello"])
(0, 'hello', '')
>>> process_run(["ls"], Path("/tmp"))
(0, '...', '')

Notes

Uses Popen for subprocess execution. Output is text mode with UTF-8 encoding.

process_call ¶

Process Call¶

Execute command and wait for completion.

Examples¶

from rite.system.process import process_call exit_code = process_call(["ls", "-la"])

Functions¶

process_call ¶

process_call(cmd: list[str], cwd: Path | str | None = None) -> int

Execute command and return exit code.

Parameters:

Name	Type	Description	Default
`cmd`	`list[str]`	Command as list of strings.	required
`cwd`	`Path \| str \| None`	Working directory. Defaults to current.	`None`

Returns:

Type	Description
`int`	Command exit code.

Examples:

>>> process_call(["echo", "hello"])
0
>>> process_call(["false"])
1

Notes

Does not capture output. Output goes to terminal.

process_check_output ¶

Process Check Output¶

Execute command and return output.

Examples¶

from rite.system.process import process_check_output output = process_check_output(["echo", "hello"])

Functions¶

process_check_output ¶

process_check_output(cmd: list[str], cwd: Path | str | None = None) -> str

Execute command and return stdout.

Parameters:

Name	Type	Description	Default
`cmd`	`list[str]`	Command as list of strings.	required
`cwd`	`Path \| str \| None`	Working directory. Defaults to current.	`None`

Returns:

Type	Description
`str`	Command stdout as string.

Raises:

Type	Description
`CalledProcessError`	If command fails.

Examples:

>>> process_check_output(["echo", "hello"])
'hello'

Notes

Raises exception on non-zero exit. Uses check_output for subprocess execution.

Environment¶

Manage environment variables.

Environment Module¶

Environment variable operations.

This submodule provides utilities for reading and modifying environment variables.

Examples¶

from rite.system.environment import env_get, env_set env_set("MY_VAR", "value") env_get("MY_VAR") 'value'

Modules¶

env_get ¶

Environment Get¶

Get environment variable value.

Examples¶

from rite.system.environment import env_get env_get("PATH")

Functions¶

env_get ¶

env_get(key: str, default: str | None = None) -> str | None

Get environment variable value.

Parameters:

Name	Type	Description	Default
`key`	`str`	Environment variable name.	required
`default`	`str \| None`	Default value if not found.	`None`

Returns:

Type	Description
`str \| None`	Variable value or default.

Examples:

>>> env_get("PATH")
'/usr/bin:/bin'
>>> env_get("MISSING", "default")
'default'

Notes

Returns None if not found and no default.

env_set ¶

Environment Set¶

Set environment variable value.

Examples¶

from rite.system.environment import env_set env_set("MY_VAR", "value")

Functions¶

env_set ¶

env_set(key: str, value: str) -> None

Set environment variable value.

Parameters:

Name	Type	Description	Default
`key`	`str`	Environment variable name.	required
`value`	`str`	Value to set.	required

Returns:

Type	Description
`None`	None

Examples:

>>> env_set("MY_VAR", "value")
>>> env_get("MY_VAR")
'value'

Notes

Affects current process and children.

env_delete ¶

Environment Delete¶

Delete environment variable.

Examples¶

from rite.system.environment import env_delete env_delete("MY_VAR")

Functions¶

env_delete ¶

env_delete(key: str) -> None

Delete environment variable.

Parameters:

Name	Type	Description	Default
`key`	`str`	Environment variable name.	required

Returns:

Type	Description
`None`	None

Examples:

>>> env_delete("MY_VAR")

Notes

Silently ignores if variable doesn't exist.

env_list ¶

Environment List¶

Get all environment variables.

Examples¶

from rite.system.environment import env_list env_list()

Functions¶

env_list ¶

env_list() -> dict[str, str]

Get all environment variables as dictionary.

Returns:

Type	Description
`dict[str, str]`	Dictionary of environment variables.

Examples:

>>> env_list()
{'PATH': '/usr/bin', 'HOME': '/home/user', ...}

Notes

Returns a copy, modifications don't affect environment.

Platform¶

Detect platform and system information.

Platform Module¶

Platform and OS detection utilities.

This submodule provides utilities for detecting the operating system, architecture, and platform information.

Examples¶

from rite.system.platform import platform_name, platform_is_linux platform_name() 'Linux' platform_is_linux() True

Modules¶

platform_name ¶

Platform Name¶

Get operating system name.

Examples¶

from rite.system.platform import platform_name platform_name() 'Linux'

Functions¶

platform_name ¶

platform_name() -> str

Get operating system name.

Returns:

Type	Description
`str`	OS name (Linux, Darwin, Windows, etc).

Examples:

>>> platform_name()
'Linux'
>>> platform_name()
'Darwin'

Notes

Returns system name from platform.system().

platform_architecture ¶

Platform Architecture¶

Get system architecture.

Examples¶

from rite.system.platform import platform_architecture platform_architecture() 'x86_64'

Functions¶

platform_architecture ¶

platform_architecture() -> str

Get system architecture.

Returns:

Type	Description
`str`	Architecture string (x86_64, arm64, etc).

Examples:

>>> platform_architecture()
'x86_64'
>>> platform_architecture()
'arm64'

Notes

Returns machine type from platform.machine().

platform_is_windows ¶

Platform Is Windows¶

Check if running on Windows.

Examples¶

from rite.system.platform import platform_is_windows platform_is_windows() False

Functions¶

platform_is_windows ¶

platform_is_windows() -> bool

Check if running on Windows.

Returns:

Type	Description
`bool`	True if Windows, False otherwise.

Examples:

>>> platform_is_windows()
False
>>> platform_is_windows()
True

Notes

Checks if platform.system() is 'Windows'.

platform_is_linux ¶

Platform Is Linux¶

Check if running on Linux.

Examples¶

from rite.system.platform import platform_is_linux platform_is_linux() True

Functions¶

platform_is_linux ¶

platform_is_linux() -> bool

Check if running on Linux.

Returns:

Type	Description
`bool`	True if Linux, False otherwise.

Examples:

>>> platform_is_linux()
True
>>> platform_is_linux()
False

Notes

Checks if platform.system() is 'Linux'.

platform_is_macos ¶

Platform Is MacOS¶

Check if running on macOS.

Examples¶

from rite.system.platform import platform_is_macos platform_is_macos() True

Functions¶

platform_is_macos ¶

platform_is_macos() -> bool

Check if running on macOS.

Returns:

Type	Description
`bool`	True if macOS, False otherwise.

Examples:

>>> platform_is_macos()
True
>>> platform_is_macos()
False

Notes

Checks if platform.system() is 'Darwin'.

platform_python_version ¶

Platform Python Version¶

Get Python version information.

Examples¶

from rite.system.platform import platform_python_version platform_python_version() '3.10.5'

Functions¶

platform_python_version ¶

platform_python_version() -> str

Get Python version string.

Returns:

Type	Description
`str`	Python version (e.g., '3.10.5').

Examples:

>>> platform_python_version()
'3.10.5'
>>> platform_python_version()
'3.11.2'

Notes

Returns version from platform.python_version().

Path¶

System path operations.

Path Module¶

Path operation utilities.

This submodule provides utilities for path operations and queries using pathlib.

Examples¶

from rite.system.path import path_exists, path_join path_exists("/tmp") True path_join("/tmp", "file.txt") '/tmp/file.txt'

Modules¶

path_exists ¶

Path Exists¶

Check if path exists.

Examples¶

from rite.system.path import path_exists path_exists("/tmp") True

Functions¶

path_exists ¶

path_exists(path: str | Path) -> bool

Check if path exists.

Parameters:

Name	Type	Description	Default
`path`	`str \| Path`	Path to check.	required

Returns:

Type	Description
`bool`	True if exists, False otherwise.

Examples:

>>> path_exists("/tmp")
True
>>> path_exists("/nonexistent")
False

Notes

Works for files and directories.

path_is_file ¶

Path Is File¶

Check if path is a file.

Examples¶

from rite.system.path import path_is_file path_is_file("/etc/hosts") True

Functions¶

path_is_file ¶

path_is_file(path: str | Path) -> bool

Check if path is a file.

Parameters:

Name	Type	Description	Default
`path`	`str \| Path`	Path to check.	required

Returns:

Type	Description
`bool`	True if file, False otherwise.

Examples:

>>> path_is_file("/etc/hosts")
True
>>> path_is_file("/tmp")
False

Notes

Returns False if path doesn't exist.

path_is_dir ¶

Path Is Directory¶

Check if path is a directory.

Examples¶

from rite.system.path import path_is_dir path_is_dir("/tmp") True

Functions¶

path_is_dir ¶

path_is_dir(path: str | Path) -> bool

Check if path is a directory.

Parameters:

Name	Type	Description	Default
`path`	`str \| Path`	Path to check.	required

Returns:

Type	Description
`bool`	True if directory, False otherwise.

Examples:

>>> path_is_dir("/tmp")
True
>>> path_is_dir("/etc/hosts")
False

Notes

Returns False if path doesn't exist.

path_absolute ¶

Path Absolute¶

Get absolute path.

Examples¶

from rite.system.path import path_absolute path_absolute(".") '/current/working/directory'

Functions¶

path_absolute ¶

path_absolute(path: str | Path) -> str

Get absolute path as string.

Parameters:

Name	Type	Description	Default
`path`	`str \| Path`	Relative or absolute path.	required

Returns:

Type	Description
`str`	Absolute path string.

Examples:

>>> path_absolute(".")
'/current/working/directory'
>>> path_absolute("../parent")
'/parent/directory'

Notes

Resolves symlinks and relative paths.

path_join ¶

Path Join¶

Join path components.

Examples¶

from rite.system.path import path_join path_join("/tmp", "file.txt") '/tmp/file.txt'

Functions¶

path_join ¶

path_join(*parts: str) -> str

Join path components into single path.

Parameters:

Name	Type	Description	Default
`*parts`	`str`	Path components to join.	`()`

Returns:

Type	Description
`str`	Joined path string.

Examples:

>>> path_join("/tmp", "dir", "file.txt")
'/tmp/dir/file.txt'
>>> path_join(".", "file.txt")
'./file.txt'

Notes

Uses platform-specific separator.

Shell¶

Shell command utilities.

Shell Module¶

Shell command utilities.

This submodule provides utilities for safely handling shell commands, arguments, and escaping.

Examples¶

from rite.system.shell import shell_escape, shell_split shell_escape("file name.txt") "'file name.txt'" shell_split("ls -la '/tmp/file.txt'") ['ls', '-la', '/tmp/file.txt']

Modules¶

shell_escape ¶

Shell Escape¶

Escape shell argument.

Examples¶

from rite.system.shell import shell_escape shell_escape("file name.txt") "'file name.txt'"

Functions¶

shell_escape ¶

shell_escape(arg: str) -> str

Escape shell argument for safe usage.

Parameters:

Name	Type	Description	Default
`arg`	`str`	Argument to escape.	required

Returns:

Type	Description
`str`	Escaped argument string.

Examples:

>>> shell_escape("file name.txt")
"'file name.txt'"
>>> shell_escape("simple")
'simple'

Notes

Uses shlex.quote for proper escaping. Safe for shell command construction.

shell_split ¶

Shell Split¶

Split shell command string.

Examples¶

from rite.system.shell import shell_split shell_split("ls -la '/tmp/file name.txt'") ['ls', '-la', '/tmp/file name.txt']

Functions¶

shell_split ¶

shell_split(cmd: str) -> list[str]

Split shell command string into arguments.

Parameters:

Name	Type	Description	Default
`cmd`	`str`	Command string to split.	required

Returns:

Type	Description
`list[str]`	List of command arguments.

Examples:

>>> shell_split("ls -la")
['ls', '-la']
>>> shell_split("echo 'hello world'")
['echo', 'hello world']

Notes

Uses shlex.split for proper parsing. Handles quoted arguments correctly.

shell_join ¶

Shell Join¶

Join command arguments into shell string.

Examples¶

from rite.system.shell import shell_join shell_join(["ls", "-la", "file name.txt"]) "ls -la 'file name.txt'"

Functions¶

shell_join ¶

shell_join(args: list[str]) -> str

Join command arguments into shell string.

Parameters:

Name	Type	Description	Default
`args`	`list[str]`	List of command arguments.	required

Returns:

Type	Description
`str`	Shell command string.

Examples:

>>> shell_join(["ls", "-la"])
'ls -la'
>>> shell_join(["echo", "hello world"])
"echo 'hello world'"

Notes

Uses shlex.join for proper escaping. Python 3.8+ required for shlex.join.

Examples¶

from rite.system import (
    process_run,
    env_get,
    platform_is_linux,
    shell_escape
)

# Run process
result = process_run(["ls", "-la"])

# Get environment variable
home = env_get("HOME")

# Platform detection
if platform_is_linux():
    print("Running on Linux")

# Escape shell argument
safe_arg = shell_escape("file with spaces.txt")