process-inspector 0.2.3
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.
Requires Python: >=3.11

# Process Inspector

![Coverage](https://img.shields.io/badge/coverage-72%25-brightgreen)

## 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`.

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

## Development

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

```bash
make env
make pip_install_editable
```

## Testing

```bash
make pytest
make coverage
make open_coverage
```

## Issues

If you experience any issues, please create an [issue](https://github.com/tsantor/process-inspector/issues) on Github.

## Example Usage

```python
from process_inspector import NativeApp
from process_inspector import Service
from process_inspector import Teamviewer
from process_inpsector import OperatingSystem

# App control
app = NativeApp('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()
tv.get_teamviewer_info()

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

# This operation requires sudo priveleges 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:

```ini
%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:

```bash
sudo nano /etc/supervisor/supervisord.conf
```

Adjust the config so your user can access it:

```ini
[unix_http_server]
chmod=0770
chown=root:pi
```

Then restart supervisor:

```bash
sudo systemctl restart supervisor
```

### macOS

Use `sudo visudo` to add the following lines:

```ini
%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](http://semver.org/).

### 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