testgres.os_ops is a lightweight Python package that provides a unified, highly secure, and polymorphic interface (OsOperations) for interacting with the operating system environment either locally or on a remote machine.
While originally designed as an infrastructure core for the testgres PostgreSQL testing framework, this package is completely decoupled and can be installed and used independently in any automation pipeline.
- Unified API (
OsOperations): Write your automation logic once using a high-level abstract interface and switch transparently between local execution and remote SSH sessions. - Stateless and Stateful Environments: Smooth handling of environment variables across distinct execution contexts (
set_env,environ, and polymorphicreset_envwith clean state rollback). - Industrial-Grade Shell Security: Safe execution pipeline featuring bulletproof shell argument escaping (
join_command_arguments) and tilde tracking (~,~root), fully eliminating code injection vulnerabilities. - Cross-Platform Consistency: Extensively verified via a robust multi-container matrix across 12+ Linux distributions (including Ubuntu, Rocky Linux, Alt Linux, Astra Linux, and Alpine).
pip install testgres.os-ops
LocalOperations: Interacts with the host machine using native Python standard libraries (subprocess,psutil,os,pathlib).RemoteOperations: Controls remote Linux-based nodes by proxying commands over secure SSH connections (utilizing binary stream polling and automated environment replication).
Supported operation groups include:
- Safe shell command execution
- Persistent environment variable tracking
- File and directory tree management (
stat, exclusive creation, copying) - Process lifecycle and signal management
The following example demonstrates how the exact same generic automation code executes seamlessly on both a local host and a remote RHEL server.
import uuid from testgres.operations.os_ops import OsOperations from testgres.operations.os_ops import ConnectionParams from testgres.operations.local_ops import LocalOperations from testgres.operations.remote_ops import RemoteOperations def generic_pipeline(title: str, os_ops: OsOperations): """Polymorphic code that executes identically on any target platform.""" cmd = [ "sh", "-c", "echo whoami: $(whoami); " "echo \"------ os_info:\"; cat /etc/os-release; " "echo \"------ our env:\"; echo \"OS_OPS_ENV\": ${OS_OPS_ENV}; " ] print("[{}] -------------\n".format(title)) # Set stateful environment variable os_ops.set_env("OS_OPS_ENV", "HELLO WORLD!") # Safe execution with precise encoding cout = os_ops.exec_command(cmd, encoding="utf-8") print(cout) # Polymorphic state cleanup os_ops.reset_env("OS_OPS_ENV", None) return # 1. Run locally using Python API under the hood local_ops = LocalOperations() generic_pipeline("Local system", local_ops) # 2. Run remotely over an isolated SSH session remote_cn_params = ConnectionParams( host="192.168.122.85", port=22, username="test", ssh_key="./id_rsa_test", ) remote_ops = RemoteOperations(remote_cn_params) generic_pipeline("Remote system", remote_ops)
[Local system] -------------
whoami: dima
------ os_info:
PRETTY_NAME="Ubuntu 24.04.4 LTS"
NAME="Ubuntu"
VERSION_ID="24.04"
VERSION="24.04.4 LTS (Noble Numbat)"
VERSION_CODENAME=noble
ID=ubuntu
ID_LIKE=debian
HOME_URL="https://ubuntu.com"
SUPPORT_URL="https://ubuntu.com"
BUG_REPORT_URL="https://launchpad.net"
PRIVACY_POLICY_URL="https://ubuntu.comlegal/terms-and-policies/privacy-policy"
UBUNTU_CODENAME=noble
LOGO=ubuntu-logo
------ our env:
OS_OPS_ENV: HELLO WORLD!
[Remote system] -------------
whoami: test
------ os_info:
NAME="Red Hat Enterprise Linux"
VERSION="8.9 (Ootpa)"
ID="rhel"
ID_LIKE="fedora"
VERSION_ID="8.9"
PLATFORM_ID="platform:el8"
PRETTY_NAME="Red Hat Enterprise Linux 8.9 (Ootpa)"
ANSI_COLOR="0;31"
CPE_NAME="cpe:/o:redhat:enterprise_linux:8::baseos"
HOME_URL="https://redhat.com"
DOCUMENTATION_URL="https://redhat.com"
BUG_REPORT_URL="https://redhat.com"
REDHAT_BUGZILLA_PRODUCT="Red Hat Enterprise Linux 8"
REDHAT_BUGZILLA_PRODUCT_VERSION=8.9
REDHAT_SUPPORT_PRODUCT="Red Hat Enterprise Linux"
REDHAT_SUPPORT_PRODUCT_VERSION="8.9"
------ our env:
OS_OPS_ENV: HELLO WORLD!
The project includes an intensive full-scale test suite ensuring absolute behavior consistency between local and remote providers. The validation matrix automatically deploys multi-container Docker environments to stress-test concurrent setups, edge-case quoting anomalies, and thread isolation across distinct architectures.