ps-mem: Per-Program Memory Usage Reporter

Warnings

• gotcha ps-mem typically requires root privileges (e.g., running with `sudo`) to accurately access `/proc/$pid/smaps` and other system files for comprehensive memory reporting.
  Fix: Execute the `ps_mem` command with `sudo` or ensure the script is run with appropriate permissions. For programmatic use via `subprocess`, ensure the command includes `sudo` if necessary, e.g., `subprocess.run(['sudo', 'ps_mem', ...])`.
• gotcha ps-mem is a Linux-specific utility due to its reliance on the `/proc` filesystem (e.g., `/proc/$pid/smaps`) for memory information. It will not work on other operating systems like macOS or Windows.
  Fix: Only use ps-mem on Linux systems. Consider cross-platform alternatives like `psutil` if OS compatibility is required.
• gotcha The library is primarily designed as a standalone command-line script, not a Python library with a traditional programmatic API of classes and functions. Directly importing `ps_mem` and calling internal functions like `ps_mem.main()` requires careful manipulation of `sys.argv` and `sys.stdout`.
  Fix: For most programmatic uses, consider running `ps_mem` as a subprocess and parsing its standard output. If direct import is necessary, be prepared to mock `sys.argv` and redirect `sys.stdout`.
• gotcha The developer notes that the name 'ps_mem' is for backwards compatibility, and 'coremem' would be a more accurate description of what the tool does (reports core memory usage per *program*, not per *process*).
  Fix: Understand that the tool aggregates memory usage by program name, not by individual process IDs, which is a key distinction from other memory reporting utilities like `ps`.

Install

• pip install ps-mem Install with pip

Imports

• main

  import ps_mem
  # Then call ps_mem.main() after preparing sys.argv and redirecting stdout

  ps-mem is primarily a command-line tool. While you can import and call its 'main' function, it is designed to parse command-line arguments (sys.argv) and print directly to sys.stdout. Programmatic interaction often involves running it as a subprocess to capture output or carefully mocking sys.argv and stdout for direct calls.

Quickstart

The primary way to use ps-mem programmatically is to execute it as an external command using `subprocess`, mimicking its typical command-line usage. A more advanced method involves directly calling `ps_mem.main()`, but this requires careful handling of `sys.argv` and `sys.stdout`.

import subprocess
import os

# Example 1: Run ps_mem as a command to get total memory usage
# Note: ps_mem often requires root privileges for full accuracy.
# This example tries without sudo first.

try:
    # Using a common flag like -t for total or no flags for default output
    result = subprocess.run(['ps_mem', '-t'], capture_output=True, text=True, check=True)
    print("\n--- ps_mem (total) output ---")
    print(result.stdout)
except FileNotFoundError:
    print("Error: 'ps_mem' command not found. Ensure it's installed and in your PATH.")
except subprocess.CalledProcessError as e:
    print(f"Error running ps_mem: {e}")
    print(f"Stderr: {e.stderr}")
    print("Note: ps_mem often requires root privileges. Try running with sudo if you encounter permission errors.")

# Example 2: Programmatic call to ps_mem's main function (more advanced, requires mocking)
# This is illustrative and not typically recommended for simple use cases due to sys.argv/stdout manipulation.
import sys
from io import StringIO
from unittest.mock import patch

# Assuming ps_mem is installed and available in your Python environment
try:
    import ps_mem

    # Capture stdout and mock sys.argv
    captured_output = StringIO()
    with patch('sys.argv', ['ps_mem', '-S']), \
         patch('sys.stdout', captured_output):
        # Call the main function with desired arguments (e.g., -S for swap info)
        # ps_mem.main() might call sys.exit(), so wrap it if needed or catch SystemExit.
        try:
            ps_mem.main()
        except SystemExit as e:
            if e.code != 0: # 0 means successful exit
                print(f"ps_mem.main() exited with error code {e.code}")

    output_from_main = captured_output.getvalue()
    print("\n--- ps_mem.main() programmatic output ---")
    print(output_from_main)

except ImportError:
    print("Error: 'ps_mem' module not found. Install with 'pip install ps-mem'.")
except Exception as e:
    print(f"An unexpected error occurred during programmatic call: {e}")