psutil-home-assistant Wrapper

0.0.1 · active · verified Thu Apr 16

psutil-home-assistant is a Python wrapper for the `psutil` library, designed to allow `psutil` to be used multiple times within the same process without conflicts arising from `psutil`'s reliance on global variables for state management. This library provides an object-oriented interface, encapsulating `psutil` functionality for isolated usage. It is currently at version 0.0.1 and has a slow release cadence, with the initial release over a year ago.

Common errors

```
AttributeError: 'PsutilWrapper' object has no attribute 'non_existent_function'
```
cause Attempting to call a `psutil` function or attribute that does not exist or is misspelled via the `PsutilWrapper` instance.

fix Verify the exact function name and arguments against the official `psutil` documentation. The `PsutilWrapper` exposes the same API as `psutil` itself.
```
TypeError: cpu_percent() missing 1 required positional argument: 'interval' (when calling psutil_wrapper.cpu_percent())
```
cause The `cpu_percent` method (and similar `psutil` methods) requires an `interval` argument for the first call to calculate percentage. If `interval=None` is passed, it returns a non-blocking instant value, but subsequent calls *without* a specified interval will return 0.0 unless an interval *was* provided on the first call.

fix For the first call to `cpu_percent`, `cpu_times_percent`, etc., specify a numerical `interval` (e.g., `ps_wrapper.cpu_percent(interval=1)`). For non-blocking instant results, ensure `interval=None` is passed explicitly, but be aware of its behavior regarding subsequent calls. The `PsutilWrapper` resets its internal `psutil` state upon instantiation, so the first call always needs an interval.

Warnings

breaking As a 0.0.1 version library, any future releases are likely to introduce breaking changes as the API stabilizes. Direct consumption of `psutil`'s internal structure via the wrapper should be avoided as it might change.
Fix: Always pin the exact version in `requirements.txt` (e.g., `psutil-home-assistant==0.0.1`) and review release notes carefully before upgrading.
gotcha This wrapper addresses `psutil`'s reliance on global state. Mixing calls to the `PsutilWrapper` instance with direct calls to top-level `psutil` functions (e.g., `psutil.cpu_percent()`) can lead to unexpected behavior and negate the benefits of using the wrapper, potentially reintroducing global state issues.
Fix: Consistently use the `PsutilWrapper` instance for all `psutil`-related operations within a context where isolated state is desired. Avoid direct `import psutil` if `psutil-home-assistant` is being used to manage global state.

Install

pip install psutil-home-assistant Install latest version

Imports

PsutilWrapper
```
from psutil_home_assistant import PsutilWrapper
```
The primary class to instantiate for wrapped psutil functionality.

Quickstart

This quickstart demonstrates how to instantiate `PsutilWrapper` and access common `psutil` functions like `cpu_percent`, `virtual_memory`, and `disk_usage` through the wrapper instance. The wrapper isolates `psutil`'s state, allowing multiple instances to operate independently within the same process.

from psutil_home_assistant import PsutilWrapper

# Create an instance of the wrapper
ps_wrapper = PsutilWrapper()

# Access psutil functions through the wrapper instance

# Get CPU usage
cpu_percent = ps_wrapper.cpu_percent(interval=None)
print(f"CPU Percent (non-blocking): {cpu_percent}%")

# Get virtual memory info
mem_info = ps_wrapper.virtual_memory()
print(f"Total Memory: {mem_info.total / (1024**3):.2f} GB")
print(f"Available Memory: {mem_info.available / (1024**3):.2f} GB")

# Get disk usage for a specific path
# Note: On some systems, you might need to specify a valid path, e.g., '/'
disk_usage = ps_wrapper.disk_usage('/')
print(f"Disk Usage (root): {disk_usage.percent}%")

view raw JSON →