process-inspector 0.2.4

A Python package for cross-platform process management, providing process data as dicts/JSON and allowing process control (start, stop, kill) on Windows, Mac, and Linux.

Process Inspector

Overview

A Python package for cross-platform process management, providing process data as dicts/JSON and allowing process/service control (start, stop, kill) on Windows, Mac, and Linux (Raspberry Pi).

Installation

Use uv or pip.

uv add process-inspector
python3 -m pip install process-inspector

Development

To get a list of all commands with descriptions simply run just.

just env
just pip-install-editable
just check
just api-check

Testing

just pytest
just coverage
just open-coverage

Issues

If you experience any issues, please create an issue.

Example Usage

from process_inspector import NativeApp
from process_inspector import Service
from process_inspector import Teamviewer
from process_inspector import OperatingSystem
from process_inspector.teamviewer import get_teamviewer_info
from pathlib import Path

# App control
app = NativeApp(Path("C:/Program Files (x86)/Microsoft/Edge/Application/msedge.exe"))
app.open()
app.is_running()
app.get_version()
app.as_dict()
app.process_info()
app.close()

# Teamviewer
tv = Teamviewer()
tv.open()
tv.is_running()
tv.close()
get_teamviewer_info()

# This operation requires sudo privileges on Linux and Mac
# Service control
service = Service("Spooler")
service.start()
service.is_running()
service.stop()

# This operation requires sudo privileges on Linux and Mac
OperatingSystem().reboot()

Use with Caution!

To control system services we need to allow passwordless use of specific executables. You should know the security implications of doing this so use at your own risk.

Linux

Use sudo visudo to add the following lines:

%sudo ALL=(ALL) NOPASSWD: /usr/bin/supervisorctl
%sudo ALL=(ALL) NOPASSWD: /usr/bin/systemctl
%sudo ALL=(ALL) NOPASSWD: /usr/sbin/reboot

Save and exit the file (:wq!). Then do:

sudo nano /etc/supervisor/supervisord.conf

Adjust the config so your user can access it:

[unix_http_server]
chmod=0770
chown=root:pi

Then restart supervisor:

sudo systemctl restart supervisor

macOS

Use sudo visudo to add the following lines:

%admin ALL=(ALL) NOPASSWD: /opt/homebrew/bin/supervisorctl
%admin ALL=(ALL) NOPASSWD: /sbin/reboot

Save and exit the file (:wq!).

History

All notable changes to this project will be documented in this file. This project adheres to Semantic Versioning.

0.2.4 (2026-03-14)

• CHANGED - Refactored subdomains into layered DDD/SRP structure (domain, application, infrastructure, interface) while preserving public API contract symbols.
• ADDED - Contract-driven release checks for public API stability via api/public_api.contract.json and snapshot verification.
• ADDED - Expanded test coverage for layered subdomain services and adapters.
• CHANGED - Updated README development/testing workflow to use just commands instead of legacy make commands.

0.2.3 (2025-12-09)

• FIXED - Wrong Service init signature for Windows.

0.2.2 (2025-12-03)

• ADDED - More test coverage and tox
• ADDED - Script basic control (run) of a script file. Currently only supports bash on Mac/Linux and Powershell on Windows.

0.2.1 (2025-11-26)

• FIXED - Correctly return false if invalid app name on Mac

0.2.0 (2025-11-13)

• ADDED - Allow Service to accept a state_change_callback which is called when the is_running status changes (if monitoring).

0.1.9 (2025-11-10)

• ADDED - Remove log event for ScheduledTask commands. Too verbose.
• ADDED - On macOS, "ask" the app to quit gracefully via osascript, then if it does not, force kill the process via psutil. This addresses an issue where apps like TeamViewer, which have watchdog processes, will try to restart the app if killed via SIGTERM/SIGKILL.
• FIXED - Bug with invalidating stale PID/Process cache
• ADDED - Allow NativeApp and TeamViewer to accept a state_change_callback which is called when the is_running status changes (if monitoring).

0.1.8 (2025-11-04)

• ADDED - ScheduledTask basic control (start, stop) for Windows only.

0.1.7 (2025-10-10)

• ADDED - Added UnityApp class which is just an extended NativeApp class with some additional getters to make things easier when working with Unity builds.
• Added last_seen to process_info for Service and NativeApp

0.1.6 (2025-10-02)

• CHANGED - Service class on Mac/Linux defaults to supervisorctl
• ADDED - If you want to use systemctl on Linux you can do from process_inspector.servicecontrol import service_class_factory and then instantiate with Service = service_class_factory('systemctl').

0.1.5 (2025-09-29)

• CHANGED - get_process_info can fail if the process was killed by the user within Windows/Mac. This fix handles that by resetting the cache so the process is looked up again.

0.1.4 (2025-09-23)

• CHANGED - Fixed failing Linux tests

0.1.3 (2025-09-16)

• CHANGED - Improved query times for process running and process info

0.1.2 (2025-09-11)

• ADDED - Service control (Windows Services or Linux/ Mac supervisorctl processes)
• ADDED - TeamViewer status and basic control (start, stop)

0.1.1 (2025-09-11)

• ADDED - more test coverage

0.1.0 (2025-09-11)

• First release