osn-system-utils 0.0.4

This library provides a set of Python abstractions for common system administration tasks on Linux and Windows, as well as utilities for network port management.

osn_system_utils: A comprehensive cross-platform library for system process and network management.

This library provides a high-level API for managing system processes, discovering network ports, and executing OS-specific commands like shutdown or socket statistics on both Linux and Windows.

Technologies

Name	Badge	Description
Python		The core language used for implementing the wrappers and logic.
Psutil		Used for retrieving network connection details and mapping PIDs to ports.
Subprocess		Used to execute the underlying system shell commands.
Socket		Used for binding checks to identify free ports on localhost.

Key Features

• Network Management
  • Find free ports on localhost using various strategies (min, max, random).
  • Map PIDs to active ports or formatted addresses.
  • Check for busy and free ports within specific ranges.
• Process Management
  • Kill processes by name or PID with support for process trees.
  • Query process tables with advanced filtering (regex, equality, numeric ranges).
  • Cross-platform check for process existence.
• OS-Specific Wrappers
  • Linux: High-level wrappers for pkill, kill, shutdown, and ss (socket statistics).
  • Windows: High-level wrappers for taskkill, shutdown, and netstat.

Installation

1. Install library:

   • With pip:

     pip install osn_system_utils
     

     With pip (beta versions):

     pip install -i https://test.pypi.org/simple/ osn_system_utils
     

   • With git:

     pip install git+https://github.com/oddshellnick/osn_system_utils.git
     

     (Ensure you have git installed)

2. Install the required Python packages using pip:

   pip install -r requirements.txt
   

Usage

Here are some examples of how to use osn_system_utils:

Network Port Discovery

from osn_system_utils.api.network import get_localhost_free_port_of

# Find the first available free port in the default range
port = get_localhost_free_port_of(on_candidates="min")
print(f"Available port: {port}")

# Find a random free port from a specific list
specific_port = get_localhost_free_port_of(ports_to_check=[8080, 8081, 9000], on_candidates="random")

Advanced Process Filtering

from osn_system_utils.api.process import get_process_table
import re

# Get all python processes using more than 100MB of memory
filters = {
    "memory_info.rss": 100 * 1024 * 1024
}
for proc in get_process_table(above_filter=filters):
    print(proc)

Linux Socket Statistics (ss)

from osn_system_utils.linux.ss import run_ss

# Get a summary of all listening TCP sockets
output = run_ss(mode="list", scope="listening", protocols=["tcp"])
print(output)

Classes and Functions

General Utilities (osn_system_utils.utils)

• validate_parameter(...): Validates that a value exists within a sequence of allowed values.
• run_command(...): Executes a shell command and returns the stdout.
• deduplicate_list(...): Removes duplicates from an iterable while maintaining order.
• CommandExecutionError: Exception raised when a system command fails.

Network API (osn_system_utils.api.network)

• get_random_localhost_free_port()
• get_localhost_pids_with_ports()
• get_localhost_pids_with_addresses()
• get_localhost_busy_ports()
• get_localhost_free_ports()
• get_localhost_free_port_of(...)

Process API (osn_system_utils.api.process)

• kill_processes_by_name(...)
• kill_process_by_pid(...)
• get_process_table(...)
• check_process_exists_by_pid(...)
• check_process_exists_by_name(...)

Linux System Wrappers (osn_system_utils.linux)

• kill:
  • run_pkill(...): Execute Linux pkill.
  • run_kill(...): Execute Linux kill for specific PIDs.
• shutdown:
  • run_shutdown(...): Manage system power (reboot, poweroff, etc.).
• ss:
  • run_ss(...): Execute socket statistics command.

Windows System Wrappers (osn_system_utils.windows)

• netstat:
  • run_netstat(...): Execute Windows netstat with various flags.
• shutdown:
  • run_shutdown(...): Manage Windows system power and restart behavior.
• taskkill:
  • run_taskkill(...): Terminate tasks by PID or Image Name.

Future Notes

• Implementation of MacOS specific command wrappers.
• Asynchronous versions of command execution functions.
• Wrappers for many other commands.
• Integration with remote command execution via SSH.