computertool

ComputerTool is a pure Python 3, command-line utility designed to disc, organize, and launch native system administration, diagnostic, and configuration tools across Windows, Linux, and macOS.

Comment

Technical Documentation: ComputerTool - Cross-Platform System Utilities Launcher

1. Executive Summary

ComputerTool is a pure Python 3, zero-dependency, cross-platform command-line utility designed to discover, organize, and launch native system administration, diagnostic, and configuration tools across Windows, Linux, and macOS. By abstracting platform-specific binaries, control panel URIs, and terminal execution models into a unified object-oriented framework, the application provides an interactive, colorized menu system with dynamic tool discovery, real-time system telemetry, and intelligent terminal routing.

This document provides a comprehensive technical breakdown of the application's architecture, class hierarchy, execution flow, platform adaptation layer, security model, extensibility guidelines, and optimization pathways.

2. System Architecture & Design Principles

2.1 Core Architectural Patterns

  • Platform Abstraction Layer: OS-specific tool registries are isolated into provider classes (WindowsToolProvider, LinuxToolProvider, MacOSToolProvider), enabling clean separation of platform logic.
  • Factory Pattern: SystemInfo and ToolMenu dynamically instantiate appropriate components based on runtime OS detection.
  • Strategy Pattern: Tool execution delegates to Tool.launch(), which routes to OS-specific terminal wrappers or direct subprocess.Popen calls based on the run_in_terminal flag.
  • Data-Driven UI: Menu rendering and category grouping are driven entirely by in-memory object lists, eliminating hardcoded UI templates.

2.2 Runtime Behavior

  1. Initialization: Prints ASCII banner, instantiates SystemInfo, performs environment scan.
  2. System Telemetry: Detects OS family, kernel version, desktop environment, Linux distro, memory, and disk usage.
  3. Tool Loading: Invokes the appropriate ToolProvider to build categorized Tool instances. Filters unavailable tools via shutil.which.
  4. Interactive Loop: Enters TUI-style menu. Handles navigation, category selection, tool launch, and graceful exit.
  5. Execution: Spawns child processes or terminal windows, provides launch feedback, and returns to menu.

3. Build Environment & Dependencies

3.1 Supported Runtimes

  • Python: 3.6+ (utilizes type hints, typing module, f-strings)
  • Platforms: Windows 10+, macOS 10.14+, Linux (systemd & non-systemd)

3.2 Dependency Matrix

Module Purpose Standard Library?
os, sys, platform OS detection, environment access, runtime control ✅
subprocess Child process management, terminal launching ✅
shutil Binary availability checks, disk usage ✅
re, time Regex parsing for distro/desktop, delays ✅
ctypes, json Windows memory API, PowerShell JSON parsing ✅
typing, abc Static type hints, abstract base classes ✅

3.3 Execution Command

python computertool.py              # Interactive menu
python computertool.py --list       # Static tool inventory
python computertool.py --info       # System telemetry only

4. Core Data Structures & Class Hierarchy

4.1 Class Diagram Overview

Colors (Static Helpers)
SystemInfo (Environment Scanner)
├─ _detect_linux_distro()
├─ _detect_desktop_environment()
├─ _display_disk_usage()
└─ _get_windows_memory() / _display_memory_info()

Tool (Executable Unit)
├─ launch()
└─ _launch_in_terminal() [OS-specific routing]

ToolCategory (Grouping Container)
├─ add(tool: Tool)
└─ display()

WindowsToolProvider / LinuxToolProvider / MacOSToolProvider
└─ get_tools() -> List[ToolCategory]

ToolMenu (UI Controller)
├─ _load_tools()
├─ run() [Main Loop]
├─ _handle_category_choice()
└─ _launch_tool()

4.2 Key Structures

Class Responsibility Notable Attributes/Methods
Colors Terminal styling & VT100/Windows API capability check supports_color(), colorize(), ANSI constants
SystemInfo Cross-platform hardware/OS detection os_name, is_windows/linux/macos, display(), /proc & ctypes parsers
Tool Represents a single launchable command name, command, args, run_in_terminal, requires_admin, launch()
ToolCategory Visual & logical grouping tools: List[Tool], add(), display()
ToolProvider (x3) Platform-specific tool registries @staticmethod get_tools() returns pre-filtered categories
ToolMenu Event loop & navigation engine run(), _clear_screen(), _get_choice(), input validation

5. Execution Engine & Command Routing Logic

5.1 Tool Launch Mechanism

The Tool.launch() method handles execution via two pathways:

Mode Implementation Behavior
Direct Execution subprocess.Popen(cmd_parts, stdout/stderr/stdin=DEVNULL) Non-blocking, silent launch for GUI apps (.exe, .app, open -a)
Terminal Execution _launch_in_terminal() Opens OS-native terminal, runs command with persistent shell (cmd /k, bash -c, osascript)

5.2 Cross-Platform Terminal Routing (_launch_in_terminal)

if Windows:  cmd /c start "Title" cmd /k <command>
if macOS:    osascript -e 'tell application "Terminal" to do script "<command>"'
if Linux:    Iterates [gnome-terminal, konsole, xfce4-terminal, alacritty, kitty, ...]
             Fallback: Runs inline in current terminal

5.3 Dynamic Tool Filtering

  • Linux tools wrapped in if shutil.which("binary"): prevent menu pollution on unsupported distros.
  • Package managers (apt, dnf, pacman, zypper, snap, flatpak, brew) are conditionally loaded.
  • Desktop environment detection (XDG_CURRENT_DESKTOP, DESKTOP_SESSION) informs fallback terminal selection.

6. System Telemetry & Environment Detection

6.1 OS & Distribution Parsing

Platform Detection Method
Windows platform.system(), GetLogicalDrives(), GlobalMemoryStatusEx (ctypes), PowerShell WMI fallback
Linux lsb_release -a, /etc/os-release regex, shutil.which for DE detection (gnome-shell, plasmashell, etc.)
macOS platform.system() == "Darwin", Aqua desktop assumption

6.2 Resource Monitoring

Metric Windows Implementation Linux Implementation
Memory ctypes.windll.kernel32.GlobalMemoryStatusEx → Fallback to PowerShell Get-CimInstance Win32_OperatingSystem /proc/meminfo parsing (MemTotal, MemAvailable)
Disk ctypes.GetLogicalDrives() bitmask → shutil.disk_usage(drive) /proc/mounts filtering → os.statvfs(mp)
Visualization ASCII progress bar: _make_bar(pct, width=20) Same

7. Command-Line Interface & Menu System

7.1 Interactive Flow

[0] Exit
[i] Show System Information
[r] Refresh Tool List
[1..N] Enter Category
  └─ [0] Back to Main Menu
  └─ [1..M] Launch Tool

7.2 Input Handling & Safety

  • strip().lower() normalization
  • try/except ValueError for invalid numeric input
  • EOFError/KeyboardInterrupt caught → graceful exit
  • time.sleep(1) prevents rapid input loop flickering
  • Screen cleared via os.system("cls"|"clear") before each render cycle

8. Security, Privileges & Execution Context

8.1 Privilege Model

  • Runs at current user integrity level by default.
  • Tools requiring elevation are visually marked [ADMIN] via Colors.RED, but no built-in privilege escalation is implemented.
  • Administrative tools rely on underlying OS UAC/sudo prompts when launched.

8.2 Process Isolation & Safety

  • subprocess.Popen defaults to DEVNULL for stdout/stderr to prevent terminal flooding.
  • Terminal wrappers use cmd /k or bash -c to keep shells open for output review.
  • No network requests except optional curl/wget public IP check.
  • Input strings are never evaluated; all commands are statically defined or passed as list arguments.

8.3 Security Recommendations

  • Add subprocess.run(..., check=True) or stderr logging for debugging failed launches.
  • Implement optional --sudo/--runas flag to wrap elevated commands.
  • Sanitize os.environ access if integrating with untrusted configurations.

9. Extensibility, Customization & Integration Guide

9.1 Adding New Tools

# Inside appropriate Provider.get_tools()
cat.add(Tool(
    name="Custom Diagnostic",
    description="Runs custom health check",
    command="/usr/local/bin/healthcheck",
    args=["--verbose"],
    run_in_terminal=True,
    requires_admin=False,
    category="Diagnostics"
))

9.2 Adding New Platforms

  1. Create class XYZToolProvider
  2. Implement @staticmethod get_tools() -> List[ToolCategory]
  3. Update ToolMenu._load_tools(): python elif self.sys_info.os_name == "XYZ": self.categories = XYZToolProvider.get_tools()
  4. Add OS detection in SystemInfo._detect_desktop_environment()

9.3 Theme & Terminal Customization

  • Modify Colors class constants for new palettes.
  • Extend _launch_in_terminal terminal list or add environment variable overrides ($TERMINAL_EMULATOR).
  • Replace os.system("clear") with curses or prompt_toolkit for flicker-free TUI.

9.4 Library Integration

from computertool import SystemInfo, WindowsToolProvider, Tool

sys = SystemInfo()
sys.display()

for cat in WindowsToolProvider.get_tools():
    for tool in cat.tools:
        if tool.name == "Task Manager":
            tool.launch()

10. Technical Limitations & Optimization Recommendations

Limitation Impact Recommended Fix
Blocking input() UI freezes during long operations or network calls Migrate to asyncio + aioconsole or curses
Hardcoded Terminal List May fail on niche Linux DEs (Wayland compositors, tiling WMs) Use $TERMINAL, xdg-terminal-exec, or dynamic dbus discovery
Silent Failures DEVNULL hides command errors Add --verbose flag, log stderr to file, or capture output
No Persistent State No favorites, recent tools, or custom configs Add config.json with json module support
Synchronous System Scan Blocks startup on slow disks/networks Cache telemetry with TTL, use background threads
No Package Distribution Requires manual python computertool.py Package via setup.py/pyproject.toml, publish to PyPI
Terminal Color Fallback Legacy Windows CMD lacks VT100 by default Use colorama or call kernel32.SetConsoleMode with ENABLE_VIRTUAL_TERMINAL_PROCESSING

10.1 Performance Optimization

  • Cache shutil.which results in @lru_cache to avoid repeated filesystem checks.
  • Pre-compile regex patterns in SystemInfo._detect_linux_distro().
  • Use subprocess.DEVNULL strategically; redirect to tempfile for debug mode.

11. Troubleshooting & Debugging

Symptom Likely Cause Resolution
Colors not rendering Terminal doesn't support ANSI, or Windows legacy console Run in Windows Terminal/PowerShell, enable VT100 in registry, or install colorama
Tool launches but closes instantly GUI app executed in terminal without open/start wrapper Ensure run_in_terminal=False for GUI tools, or use proper launcher
Linux distro shows "Unknown" /etc/os-release missing or malformed Install lsb-release package, or fallback to uname -r
Terminal emulator not found Minimal server install, no GUI Fallback runs inline; add tmux/screen support if needed
Memory/Disk stats fail Insufficient permissions, /proc restricted Run with standard user privileges; avoid sandboxed containers

Debugging Flags

  • Add import logging; logging.basicConfig(level=logging.DEBUG) to trace tool discovery.
  • Use python -m pdb computertool.py for step-through execution.
  • Temporarily replace subprocess.Popen with subprocess.run(..., capture_output=True, text=True) to inspect output.

12. Appendix A: Class & Method Reference Matrix

Component Key Methods Return Type Complexity
Colors.supports_color() Checks sys.stdout.isatty() + Windows GetConsoleMode bool O(1)
SystemInfo.display() Prints formatted OS/Disk/Memory table None O(N) mounts
Tool.launch() Spawns process via Popen or terminal wrapper bool O(1) spawn
ToolMenu.run() Main event loop, input routing None Infinite loop
WindowsToolProvider.get_tools() Returns 8 categories, ~70 tools List[ToolCategory] O(1) static
LinuxToolProvider.get_tools() Returns 12 categories, 80+ conditional tools List[ToolCategory] O(B) binaries checked
MacOSToolProvider.get_tools() Returns 7 categories, ~60 tools List[ToolCategory] O(1) static

13. Appendix B: Platform Coverage Matrix

Domain Windows Linux macOS
Process Monitoring taskmgr, resmon, perfmon top, htop, glances, ps, pstree Activity Monitor, top, ps
Disk/Storage cleanmgr, dfrgui, diskmgmt.msc df, du, lsblk, ncdu, fdisk Disk Utility, diskutil, df, du
Network ncpa.cpl, wf.msc, ping, nslookup ip, ss, netstat, nmap, ufw/iptables ifconfig, networksetup, netstat
Services services.msc, taskschd.msc systemctl, journalctl, timedatectl launchctl, softwareupdate
Package Management N/A (Settings/Apps) apt, dnf, pacman, snap, flatpak brew, mas (optional)
Security secpol.msc, firewall.cpl, Defender fail2ban, aa-status, sestatus spctl, Gatekeeper
Terminal Emulation cmd /c start, wt 10+ DE terminals, fallback inline osascript Terminal

14. Conclusion & Future Roadmap

ComputerTool demonstrates a robust, production-ready approach to cross-platform system utility aggregation using pure Python. Its architecture prioritizes maintainability, dynamic discovery, and clean separation of concerns, making it highly suitable for DevOps workstations, sysadmin toolkits, and educational environments.

Recommended Enhancements

  1. TUI Framework Migration: Replace input()/os.system("clear") with textual, prompt_toolkit, or curses for responsive, flicker-free interfaces.
  2. Configuration System: Add ~/.computertool/config.json for favorites, aliases, custom commands, and terminal overrides.
  3. Async Execution: Use asyncio.create_subprocess_exec for concurrent tool discovery and non-blocking launches.
  4. Plugin Architecture: Allow external *.py modules to register Tool instances via entry points.
  5. Packaging & Distribution: Publish to PyPI, generate standalone binaries via PyInstaller or Nuitka.
  6. Internationalization: Implement gettext or babel for multi-language menu support.
  7. Audit Logging: Add structured JSON logging for compliance, debugging, and usage analytics.

This utility serves as a highly adaptable foundation for system administration automation, portable diagnostics, and cross-platform workflow standardization.

Built With

Share this project:

Updates