gpustat

import gpustat

from gpustat import new_query, print_gpustat, main
from gpustat import GPUStat, GPUStatCollection
from gpustat import __version__

import gpustat

# Query all GPUs and get collection
gpu_stats = gpustat.new_query()

# Print formatted output to stdout
gpustat.print_gpustat()

# Get GPU count
count = gpustat.gpu_count()
print(f"Found {count} GPUs")

# Check if GPUs are available
if gpustat.is_available():
    print("NVIDIA GPUs are available")

# Access individual GPU information
for gpu in gpu_stats:
    print(f"GPU {gpu.index}: {gpu.name}")
    print(f"  Memory: {gpu.memory_used}MB / {gpu.memory_total}MB")
    print(f"  Temperature: {gpu.temperature}°C")
    print(f"  Utilization: {gpu.utilization}%")

def new_query() -> GPUStatCollection:
    """
    Obtain a new GPUStatCollection instance by querying nvidia-smi
    to get the list of GPUs and running process information.
    
    Returns:
        GPUStatCollection: Collection of GPU status objects
    """

def gpu_count() -> int:
    """
    Return the number of available GPUs in the system.
    
    Returns:
        int: Number of GPUs available
    """

def is_available() -> bool:
    """
    Return True if the NVML library and GPU devices are available.
    
    Returns:
        bool: True if GPUs are available, False otherwise
    """

def print_gpustat(
    *,
    id=None,
    json=False,
    debug=False,
    **kwargs
) -> None:
    """
    Display the GPU query results into standard output.
    
    Parameters:
        id: Target specific GPU index or comma-separated indices
        json (bool): Print information in JSON format
        debug (bool): Print additional debug information
        **kwargs: Additional formatting options passed to print_formatted
    """

def main(*argv) -> None:
    """
    Main command-line interface entry point.
    
    Parameters:
        *argv: Command line arguments (defaults to sys.argv)
    """

class GPUStat:
    """
    Represents status information for a single GPU.
    """
    
    def __init__(self, entry: dict) -> None:
        """
        Initialize GPU status from entry dictionary.
        
        Parameters:
            entry (dict): GPU information dictionary
        """
    
    @property
    def available(self) -> bool:
        """GPU availability status."""
    
    @property
    def index(self) -> int:
        """GPU index as in nvidia-smi."""
    
    @property
    def uuid(self) -> str:
        """GPU UUID from nvidia-smi (e.g. GPU-12345678-abcd-abcd-uuid-123456abcdef)."""
    
    @property
    def name(self) -> str:
        """GPU card name (e.g. GeForce Titan X)."""
    
    @property
    def memory_total(self) -> int:
        """Total memory in MB as integer."""
    
    @property
    def memory_used(self) -> int:
        """Occupied memory in MB as integer."""
    
    @property
    def memory_free(self) -> int:
        """Free (available) memory in MB as integer."""
    
    @property
    def memory_available(self) -> int:
        """Available memory in MB as integer (alias of memory_free)."""
    
    @property
    def temperature(self) -> int | None:
        """GPU temperature in Celsius, or None if not available."""
    
    @property
    def fan_speed(self) -> int | None:
        """Fan speed percentage (0-100), or None if not available."""
    
    @property
    def utilization(self) -> int | None:
        """GPU utilization percentage, or None if not available."""
    
    @property
    def utilization_enc(self) -> int | None:
        """GPU encoder utilization percentage, or None if not available."""
    
    @property
    def utilization_dec(self) -> int | None:
        """GPU decoder utilization percentage, or None if not available."""
    
    @property
    def power_draw(self) -> int | None:
        """GPU power usage in Watts, or None if not available."""
    
    @property
    def power_limit(self) -> int | None:
        """Enforced GPU power limit in Watts, or None if not available."""
    
    @property
    def processes(self) -> list:
        """List of running processes on the GPU."""
    
    def print_to(
        self,
        fp,
        *,
        with_colors: bool = True,
        show_cmd: bool = False,
        show_full_cmd: bool = False,
        no_processes: bool = False,
        show_user: bool = False,
        show_pid: bool = False,
        show_fan_speed: bool | None = None,
        show_codec: str = "",
        show_power: bool | None = None,
        gpuname_width: int | None = None,
        eol_char: str = os.linesep,
        term=None
    ) -> object:
        """
        Print formatted GPU information to file pointer.
        
        Parameters:
            fp: File pointer to write to
            with_colors (bool): Enable colored output (deprecated)
            show_cmd (bool): Display command name of running processes
            show_full_cmd (bool): Display full command and CPU stats
            no_processes (bool): Do not display process information
            show_user (bool): Display username of running processes
            show_pid (bool): Display PID of running processes
            show_fan_speed (bool): Display GPU fan speed
            show_codec (str): Show encoder/decoder utilization ("enc", "dec", "enc,dec")
            show_power (bool): Show GPU power usage
            gpuname_width (int): Width for GPU name display
            eol_char (str): End of line character
            term: Terminal object for formatting
            
        Returns:
            File pointer object
        """
    
    def jsonify(self) -> dict:
        """
        Convert GPU status to JSON-serializable dictionary.
        
        Returns:
            dict: JSON-serializable GPU information
        """


class GPUStatCollection:
    """
    Collection of GPU status objects with system information.
    Implements Sequence[GPUStat] interface.
    """
    
    def __init__(self, gpu_list: list, driver_version: str | None = None) -> None:
        """
        Initialize GPU collection.
        
        Parameters:
            gpu_list (list): List of GPUStat objects
            driver_version (str): NVIDIA driver version
        """
    
    @staticmethod
    def new_query(debug: bool = False, id=None) -> 'GPUStatCollection':
        """
        Query the information of all GPUs on local machine.
        
        Parameters:
            debug (bool): Enable debug output
            id: Target specific GPU index/indices (int, str, or Sequence)
            
        Returns:
            GPUStatCollection: New collection with current GPU status
        """
    
    @staticmethod
    def clean_processes() -> None:
        """Clean up cached process information for non-existent PIDs."""
    
    def __len__(self) -> int:
        """Return number of GPUs in collection."""
    
    def __iter__(self):
        """Iterate over GPU status objects."""
    
    def __getitem__(self, index: int) -> GPUStat:
        """Get GPU status by index."""
    
    def print_formatted(
        self,
        fp=sys.stdout,
        *,
        force_color: bool = False,
        no_color: bool = False,
        show_cmd: bool = False,
        show_full_cmd: bool = False,
        show_user: bool = False,
        show_pid: bool = False,
        show_fan_speed: bool | None = None,
        show_codec: str = "",
        show_power: bool | None = None,
        gpuname_width: int | None = None,
        show_header: bool = True,
        no_processes: bool = False,
        eol_char: str = os.linesep
    ) -> None:
        """
        Print formatted GPU information with various display options.
        
        Parameters:
            fp: File pointer to write to (default: sys.stdout)
            force_color (bool): Force colored output
            no_color (bool): Suppress colored output
            show_cmd (bool): Display command names of processes
            show_full_cmd (bool): Display full command and CPU stats
            show_user (bool): Display usernames of processes
            show_pid (bool): Display PIDs of processes
            show_fan_speed (bool): Display GPU fan speeds
            show_codec (str): Show encoder/decoder utilization
            show_power (bool): Show GPU power usage
            gpuname_width (int): Width for GPU name display
            show_header (bool): Show header with hostname and timestamp
            no_processes (bool): Hide process information
            eol_char (str): End of line character
        """
    
    def jsonify(self) -> dict:
        """
        Convert collection to JSON-serializable dictionary.
        
        Returns:
            dict: Complete system and GPU information
        """
    
    def print_json(self, fp=sys.stdout) -> None:
        """
        Print JSON representation to file pointer.
        
        Parameters:
            fp: File pointer to write to (default: sys.stdout)
        """
    
    @property
    def hostname(self) -> str:
        """System hostname."""
    
    @property
    def query_time(self) -> datetime:
        """Timestamp when query was performed."""
    
    @property
    def driver_version(self) -> str | None:
        """NVIDIA driver version string."""

class InvalidGPU(GPUStat):
    """
    Internal class representing a GPU that encountered an error during querying.
    Inherits from GPUStat but returns fallback values for most properties.
    Not part of public API but may appear in collections during error conditions.
    """
    
    class FallbackDict(dict):
        """Internal dictionary that returns '?' for missing keys."""
        def __missing__(self, key: str) -> str:
            return "?"
    
    def __init__(self, gpu_index: int, message: str, ex: Exception) -> None:
        """
        Initialize invalid GPU with error information.
        
        Parameters:
            gpu_index (int): GPU index that failed
            message (str): Error message  
            ex (Exception): Original exception that caused the failure
        """
    
    @property
    def available(self) -> bool:
        """Always returns False for invalid GPUs."""
    
    @property  
    def exception(self) -> Exception:
        """Original exception that caused GPU to be invalid."""

from typing import Sequence
from datetime import datetime
import os
import sys

# Process information dictionary structure
ProcessInfo = dict[str, any]  # Contains: username, command, full_command, 
                             # gpu_memory_usage, cpu_percent, cpu_memory_usage, pid

# GPU entry dictionary structure  
GPUEntry = dict[str, any]  # Contains: index, uuid, name, temperature.gpu,
                          # fan.speed, utilization.gpu, utilization.enc,
                          # utilization.dec, power.draw, enforced.power.limit,
                          # memory.used, memory.total, processes

# Exception types used in error handling
NVMLError = Exception  # NVIDIA Management Library errors
AccessDenied = Exception  # Process access denied errors  
NoSuchProcess = Exception  # Process no longer exists errors

__version__: str  # Package version string
NOT_SUPPORTED: str = 'Not Supported'
MB: int = 1024 * 1024  # Bytes to MB conversion factor
DEFAULT_GPUNAME_WIDTH: int = 16
IS_WINDOWS: bool  # True if running on Windows platform

# Basic usage
gpustat

# JSON output
gpustat --json

# Watch mode (update every 2 seconds)  
gpustat --interval 2

# Show all information
gpustat --show-all

# Show specific information
gpustat --show-cmd --show-user --show-pid --show-fan-speed --show-power

# Target specific GPUs
gpustat --id 0,1

# Colored output
gpustat --force-color

# No processes
gpustat --no-processes

# No header
gpustat --no-header

# Custom GPU name width
gpustat --gpuname-width 20

# Debug mode
gpustat --debug

# Show encoder/decoder utilization
gpustat --show-codec enc,dec

# Show power usage with limits
gpustat --show-power draw,limit