{"id":39494834,"url":"https://github.com/oddshellnick/osn-system-utils","last_synced_at":"2026-01-25T05:01:17.557Z","repository":{"id":332129042,"uuid":"1131828494","full_name":"oddshellnick/osn-system-utils","owner":"oddshellnick","description":"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.","archived":false,"fork":false,"pushed_at":"2026-01-12T19:29:25.000Z","size":17,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-01-12T21:25:48.276Z","etag":null,"topics":["cmd","linux","os","psutil","windows"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/oddshellnick.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-01-10T19:17:47.000Z","updated_at":"2026-01-12T15:09:44.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/oddshellnick/osn-system-utils","commit_stats":null,"previous_names":["oddshellnick/osn-system-utils"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/oddshellnick/osn-system-utils","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/oddshellnick%2Fosn-system-utils","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/oddshellnick%2Fosn-system-utils/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/oddshellnick%2Fosn-system-utils/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/oddshellnick%2Fosn-system-utils/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/oddshellnick","download_url":"https://codeload.github.com/oddshellnick/osn-system-utils/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/oddshellnick%2Fosn-system-utils/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28744419,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-25T02:46:29.005Z","status":"ssl_error","status_checked_at":"2026-01-25T02:44:29.968Z","response_time":113,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cmd","linux","os","psutil","windows"],"created_at":"2026-01-18T05:41:11.755Z","updated_at":"2026-01-25T05:01:17.541Z","avatar_url":"https://github.com/oddshellnick.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# osn_system_utils: A comprehensive cross-platform library for system process and network management.\n\nThis 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.\n\n## Technologies\n\n| Name           | Badge                                                                                                                                               | Description                                                               |\n|----------------|-----------------------------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------|\n| Python         | [![Python](https://img.shields.io/badge/Python%2DPython?style=flat\u0026logo=python\u0026color=%231f4361)](https://www.python.org/)                           | The core language used for implementing the wrappers and logic.           |\n| Psutil         | [![Psutil](https://img.shields.io/badge/psutil%2Dpsutil?style=flat\u0026color=%230f90a1)](https://pypi.org/project/psutil/)                              | Used for retrieving network connection details and mapping PIDs to ports. |\n| Subprocess     | [![Subprocess](https://img.shields.io/badge/subprocess%2Dsubprocess?style=flat\u0026color=%23a3c910)](https://docs.python.org/3/library/subprocess.html) | Used to execute the underlying system shell commands.                     |\n| Socket         | [![Socket](https://img.shields.io/badge/socket%2Dsocket?style=flat\u0026color=%230f53b5)](https://docs.python.org/3/library/socket.html)                 | Used for binding checks to identify free ports on localhost.              |\n\n## Key Features\n\n*   **Network Management**\n    *   Find free ports on localhost using various strategies (min, max, random).\n    *   Map PIDs to active ports or formatted addresses.\n    *   Check for busy and free ports within specific ranges.\n*   **Process Management**\n    *   Kill processes by name or PID with support for process trees.\n    *   Query process tables with advanced filtering (regex, equality, numeric ranges).\n    *   Cross-platform check for process existence.\n*   **OS-Specific Wrappers**\n    *   **Linux:** High-level wrappers for `pkill`, `kill`, `shutdown`, and `ss` (socket statistics).\n    *   **Windows:** High-level wrappers for `taskkill`, `shutdown`, and `netstat`.\n\n## Installation\n\n1. Install library:\n    *   **With pip:**\n        ```bash\n        pip install osn_system_utils\n        ```\n\n        **With pip (beta versions):**\n        ```bash\n        pip install -i https://test.pypi.org/simple/ osn_system_utils\n        ```\n\n    *   **With git:**\n        ```bash\n        pip install git+https://github.com/oddshellnick/osn_system_utils.git\n        ```\n        *(Ensure you have git installed)*\n\n2. **Install the required Python packages using pip:**\n\n    ```bash\n    pip install -r requirements.txt\n    ```\n\n## Usage\n\nHere are some examples of how to use `osn_system_utils`:\n\n### Network Port Discovery\n\n```python\nfrom osn_system_utils.api.network import get_localhost_free_port_of\n\n# Find the first available free port in the default range\nport = get_localhost_free_port_of(on_candidates=\"min\")\nprint(f\"Available port: {port}\")\n\n# Find a random free port from a specific list\nspecific_port = get_localhost_free_port_of(ports_to_check=[8080, 8081, 9000], on_candidates=\"random\")\n```\n\n### Advanced Process Filtering\n\n```python\nfrom osn_system_utils.api.process import get_process_table\nimport re\n\n# Get all python processes using more than 100MB of memory\nfilters = {\n    \"memory_info.rss\": 100 * 1024 * 1024\n}\nfor proc in get_process_table(above_filter=filters):\n    print(proc)\n```\n\n### Linux Socket Statistics (ss)\n\n```python\nfrom osn_system_utils.linux.ss import run_ss\n\n# Get a summary of all listening TCP sockets\noutput = run_ss(mode=\"list\", scope=\"listening\", protocols=[\"tcp\"])\nprint(output)\n```\n\n## Classes and Functions\n\n### General Utilities (`osn_system_utils.utils`)\n*   `validate_parameter(...)`: Validates that a value exists within a sequence of allowed values.\n*   `run_command(...)`: Executes a shell command and returns the stdout.\n*   `deduplicate_list(...)`: Removes duplicates from an iterable while maintaining order.\n*   `CommandExecutionError`: Exception raised when a system command fails.\n\n### Network API (`osn_system_utils.api.network`)\n*   `get_random_localhost_free_port()`\n*   `get_localhost_pids_with_ports()`\n*   `get_localhost_pids_with_addresses()`\n*   `get_localhost_busy_ports()`\n*   `get_localhost_free_ports()`\n*   `get_localhost_free_port_of(...)`\n\n### Process API (`osn_system_utils.api.process`)\n*   `kill_processes_by_name(...)`\n*   `kill_process_by_pid(...)`\n*   `get_process_table(...)`\n*   `check_process_exists_by_pid(...)`\n*   `check_process_exists_by_name(...)`\n\n### Linux System Wrappers (`osn_system_utils.linux`)\n*   `kill`:\n    *   `run_pkill(...)`: Execute Linux `pkill`.\n    *   `run_kill(...)`: Execute Linux `kill` for specific PIDs.\n*   `shutdown`:\n    *   `run_shutdown(...)`: Manage system power (reboot, poweroff, etc.).\n*   `ss`:\n    *   `run_ss(...)`: Execute socket statistics command.\n\n### Windows System Wrappers (`osn_system_utils.windows`)\n*   `netstat`:\n    *   `run_netstat(...)`: Execute Windows `netstat` with various flags.\n*   `shutdown`:\n    *   `run_shutdown(...)`: Manage Windows system power and restart behavior.\n*   `taskkill`:\n    *   `run_taskkill(...)`: Terminate tasks by PID or Image Name.\n\n## Future Notes\n\n*   Implementation of MacOS specific command wrappers.\n*   Asynchronous versions of command execution functions.\n*   Wrappers for many other commands.\n*   Integration with remote command execution via SSH.","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Foddshellnick%2Fosn-system-utils","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Foddshellnick%2Fosn-system-utils","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Foddshellnick%2Fosn-system-utils/lists"}