https://github.com/oddshellnick/osn-system-utils
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.
https://github.com/oddshellnick/osn-system-utils
cmd linux os psutil windows
Last synced: 5 months ago
JSON representation
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.
- Host: GitHub
- URL: https://github.com/oddshellnick/osn-system-utils
- Owner: oddshellnick
- Created: 2026-01-10T19:17:47.000Z (5 months ago)
- Default Branch: main
- Last Pushed: 2026-01-12T19:29:25.000Z (5 months ago)
- Last Synced: 2026-01-12T21:25:48.276Z (5 months ago)
- Topics: cmd, linux, os, psutil, windows
- Language: Python
- Homepage:
- Size: 16.6 KB
- Stars: 1
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# 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 | [](https://www.python.org/) | The core language used for implementing the wrappers and logic. |
| Psutil | [](https://pypi.org/project/psutil/) | Used for retrieving network connection details and mapping PIDs to ports. |
| Subprocess | [](https://docs.python.org/3/library/subprocess.html) | Used to execute the underlying system shell commands. |
| Socket | [](https://docs.python.org/3/library/socket.html) | 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:**
```bash
pip install osn_system_utils
```
**With pip (beta versions):**
```bash
pip install -i https://test.pypi.org/simple/ osn_system_utils
```
* **With git:**
```bash
pip install git+https://github.com/oddshellnick/osn_system_utils.git
```
*(Ensure you have git installed)*
2. **Install the required Python packages using pip:**
```bash
pip install -r requirements.txt
```
## Usage
Here are some examples of how to use `osn_system_utils`:
### Network Port Discovery
```python
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
```python
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)
```python
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.