{"id":7519,"library":"psutil-home-assistant","title":"psutil-home-assistant Wrapper","description":"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.","status":"active","version":"0.0.1","language":"en","source_language":"en","source_url":"https://github.com/home-assistant-libs/psutil-home-assistant","tags":["psutil","system monitoring","home assistant","wrapper","globals"],"install":[{"cmd":"pip install psutil-home-assistant","lang":"bash","label":"Install latest version"}],"dependencies":[{"reason":"This library is a wrapper around `psutil` and re-exports its functionality. `psutil` is a mandatory runtime dependency.","package":"psutil"}],"imports":[{"note":"The primary class to instantiate for wrapped psutil functionality.","symbol":"PsutilWrapper","correct":"from psutil_home_assistant import PsutilWrapper"}],"quickstart":{"code":"from psutil_home_assistant import PsutilWrapper\n\n# Create an instance of the wrapper\nps_wrapper = PsutilWrapper()\n\n# Access psutil functions through the wrapper instance\n\n# Get CPU usage\ncpu_percent = ps_wrapper.cpu_percent(interval=None)\nprint(f\"CPU Percent (non-blocking): {cpu_percent}%\")\n\n# Get virtual memory info\nmem_info = ps_wrapper.virtual_memory()\nprint(f\"Total Memory: {mem_info.total / (1024**3):.2f} GB\")\nprint(f\"Available Memory: {mem_info.available / (1024**3):.2f} GB\")\n\n# Get disk usage for a specific path\n# Note: On some systems, you might need to specify a valid path, e.g., '/'\ndisk_usage = ps_wrapper.disk_usage('/')\nprint(f\"Disk Usage (root): {disk_usage.percent}%\")","lang":"python","description":"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."},"warnings":[{"fix":"Always pin the exact version in `requirements.txt` (e.g., `psutil-home-assistant==0.0.1`) and review release notes carefully before upgrading.","message":"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.","severity":"breaking","affected_versions":"0.0.1"},{"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.","message":"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.","severity":"gotcha","affected_versions":"0.0.1"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Verify the exact function name and arguments against the official `psutil` documentation. The `PsutilWrapper` exposes the same API as `psutil` itself.","cause":"Attempting to call a `psutil` function or attribute that does not exist or is misspelled via the `PsutilWrapper` instance.","error":"AttributeError: 'PsutilWrapper' object has no attribute 'non_existent_function'"},{"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.","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.","error":"TypeError: cpu_percent() missing 1 required positional argument: 'interval' (when calling psutil_wrapper.cpu_percent())"}]}