diff --git a/docs/source/apis/core/process.rst b/docs/source/apis/core/process.rst index 2b35aa8..6de6d05 100644 --- a/docs/source/apis/core/process.rst +++ b/docs/source/apis/core/process.rst @@ -3,6 +3,7 @@ nvitop.core.process module .. automodule:: nvitop.core.process :members: + :inherited-members: :undoc-members: :show-inheritance: :member-order: bysource diff --git a/docs/source/apis/core/utils.rst b/docs/source/apis/core/utils.rst index 254bda2..84dbbc7 100644 --- a/docs/source/apis/core/utils.rst +++ b/docs/source/apis/core/utils.rst @@ -6,3 +6,4 @@ nvitop.core.utils module :undoc-members: :show-inheritance: :member-order: bysource + :exclude-members: NA, NaType, NotApplicable, NotApplicableType diff --git a/docs/source/apis/index.rst b/docs/source/apis/index.rst index 20367c7..1ad9b4e 100644 --- a/docs/source/apis/index.rst +++ b/docs/source/apis/index.rst @@ -15,17 +15,30 @@ Subpackages core/utils callbacks +Module contents +--------------- + .. automodule:: nvitop.version :members: :undoc-members: :show-inheritance: :member-order: bysource -Module contents ---------------- +.. autoclass:: nvitop.NaType + :members: + :undoc-members: + :show-inheritance: + :member-order: bysource + +.. autodata:: nvitop.NA + +.. autoclass:: nvitop.NotApplicableType + +.. autodata:: nvitop.NotApplicable .. automodule:: nvitop :members: :undoc-members: :show-inheritance: :member-order: bysource + :exclude-members: NA, NaType, NotApplicable, NotApplicableType diff --git a/nvitop/callbacks/keras.py b/nvitop/callbacks/keras.py index dde73e2..a1aceb2 100644 --- a/nvitop/callbacks/keras.py +++ b/nvitop/callbacks/keras.py @@ -17,27 +17,27 @@ from nvitop.callbacks.utils import get_devices_by_logical_ids, get_gpu_stats # Ported version of .pytorch_lightning.GpuStatsLogger for Keras class GpuStatsLogger(Callback): # pylint: disable=too-many-instance-attributes r""" - Automatically log GPU stats during training stage. ``GpuStatsLogger`` is a + Automatically log GPU stats during training stage. :class:`GpuStatsLogger` is a callback and in order to use it you need to assign a TensorBoard callback or a CSVLogger callback to the model. Args: memory_utilization (bool): - Set to ``True`` to log used, free and the percentage of memory - utilization at the start and end of each step. Default: ``True``. + Set to :data:`True` to log used, free and the percentage of memory + utilization at the start and end of each step. Default: :data:`True`. gpu_utilization (bool): - Set to ``True`` to log the percentage of GPU utilization - at the start and end of each step. Default: ``True``. + Set to :data:`True` to log the percentage of GPU utilization + at the start and end of each step. Default: :data:`True`. intra_step_time (bool): - Set to ``True`` to log the time of each step. Default: ``False``. + Set to :data:`True` to log the time of each step. Default: :data:`False`. inter_step_time (bool): - Set to ``True`` to log the time between the end of one step - and the start of the next step. Default: ``False``. + Set to :data:`True` to log the time between the end of one step + and the start of the next step. Default: :data:`False`. fan_speed (bool): - Set to ``True`` to log percentage of fan speed. Default: ``False``. + Set to :data:`True` to log percentage of fan speed. Default: :data:`False`. temperature (bool): - Set to ``True`` to log the gpu temperature in degree Celsius. - Default: ``False``. + Set to :data:`True` to log the gpu temperature in degree Celsius. + Default: :data:`False`. Raises: ValueError: diff --git a/nvitop/callbacks/pytorch_lightning.py b/nvitop/callbacks/pytorch_lightning.py index 4d8d8e7..958c731 100644 --- a/nvitop/callbacks/pytorch_lightning.py +++ b/nvitop/callbacks/pytorch_lightning.py @@ -18,26 +18,26 @@ from nvitop.callbacks.utils import get_devices_by_logical_ids, get_gpu_stats # Modified from pytorch_lightning.callbacks.GPUStatsMonitor class GpuStatsLogger(Callback): # pylint: disable=too-many-instance-attributes r""" - Automatically log GPU stats during training stage. ``GpuStatsLogger`` is a + Automatically log GPU stats during training stage. :class:`GpuStatsLogger` is a callback and in order to use it you need to assign a logger in the ``Trainer``. Args: memory_utilization (bool): - Set to ``True`` to log used, free and the percentage of memory - utilization at the start and end of each step. Default: ``True``. + Set to :data:`True` to log used, free and the percentage of memory + utilization at the start and end of each step. Default: :data:`True`. gpu_utilization (bool): - Set to ``True`` to log the percentage of GPU utilization - at the start and end of each step. Default: ``True``. + Set to :data:`True` to log the percentage of GPU utilization + at the start and end of each step. Default: :data:`True`. intra_step_time (bool): - Set to ``True`` to log the time of each step. Default: ``False``. + Set to :data:`True` to log the time of each step. Default: :data:`False`. inter_step_time (bool): - Set to ``True`` to log the time between the end of one step - and the start of the next step. Default: ``False``. + Set to :data:`True` to log the time between the end of one step + and the start of the next step. Default: :data:`False`. fan_speed (bool): - Set to ``True`` to log percentage of fan speed. Default: ``False``. + Set to :data:`True` to log percentage of fan speed. Default: :data:`False`. temperature (bool): - Set to ``True`` to log the gpu temperature in degree Celsius. - Default: ``False``. + Set to :data:`True` to log the gpu temperature in degree Celsius. + Default: :data:`False`. Raises: MisconfigurationException: diff --git a/nvitop/core/collector.py b/nvitop/core/collector.py index 5f2e3b4..ab147b5 100644 --- a/nvitop/core/collector.py +++ b/nvitop/core/collector.py @@ -172,6 +172,8 @@ class ResourceMetricCollector: # pylint: disable=too-many-instance-attributes Core methods: + .. code-block:: python + collector.activate(tag='') # alias: start collector.deactivate() # alias: stop collector.reset(tag='') diff --git a/nvitop/core/device.py b/nvitop/core/device.py index a6dff4f..b21d1b5 100644 --- a/nvitop/core/device.py +++ b/nvitop/core/device.py @@ -3,7 +3,7 @@ """The live classes for GPU devices. -The core classes are ``Device`` and ``CudaDevice`` (also aliased as ``Device.cuda``). +The core classes are :class:`Device` and :class:`CudaDevice` (also aliased as :attr:`Device.cuda`). The type of returned instance created by ``Class(args)`` is depending on the given arguments. ``Device()`` returns: @@ -138,7 +138,7 @@ def _does_any_device_support_mig_mode() -> bool: def is_mig_device_uuid(uuid: Optional[str]) -> bool: - """Returns ``True`` if the argument is a MIG device UUID, otherwise, returns ``False``.""" + """Returns :data:`True` if the argument is a MIG device UUID, otherwise, returns :data:`False`.""" if isinstance(uuid, str): match = Device.UUID_PATTERN.match(uuid) @@ -150,7 +150,7 @@ def is_mig_device_uuid(uuid: Optional[str]) -> bool: class Device: # pylint: disable=too-many-instance-attributes,too-many-public-methods """Live class of the GPU devices, different from the device snapshots. - ``Device.__new__()`` returns different types depending on the given arguments. + :meth:`Device.__new__()` returns different types depending on the given arguments. .. code-block:: python @@ -215,7 +215,7 @@ class Device: # pylint: disable=too-many-instance-attributes,too-many-public-me GPU_PROCESS_CLASS = GpuProcess cuda = None # defined in below - """Shortcut for class ``CudaDevice``.""" + """Shortcut for class :class:`CudaDevice`.""" @staticmethod def driver_version() -> Union[str, NaType]: @@ -273,13 +273,13 @@ class Device: # pylint: disable=too-many-instance-attributes,too-many-public-me Args: indices (Iterable[Union[int, Tuple[int, int]]]): - Indices of the devices. For each index, get ``PhysicalDevice`` for single int - and ``MigDevice`` for tuple (int, int). That is: + Indices of the devices. For each index, get :class:`PhysicalDevice` for single int + and :class:`MigDevice` for tuple (int, int). That is: - (int) -> PhysicalDevice - ((int, int)) -> MigDevice Returns: List[Union[PhysicalDevice, MigDevice]] - A list of ``PhysicalDevice`` and/or ``MigDevice`` instances of the given indices. + A list of :class:`PhysicalDevice` and/or :class:`MigDevice` instances of the given indices. """ if indices is None: @@ -300,7 +300,7 @@ class Device: # pylint: disable=too-many-instance-attributes,too-many-public-me - `CUDA Device Enumeration for MIG Device `_ Returns: List[CudaDevice] - A list of ``CudaDevice`` instances. + A list of :class:`CudaDevice` instances. Raises: RuntimeError: @@ -331,7 +331,7 @@ class Device: # pylint: disable=too-many-instance-attributes,too-many-public-me The indices of the GPU in CUDA ordinal, if not given, returns all visible CUDA devices. Returns: List[CudaDevice] - A list of ``CudaDevice`` of the given CUDA indices. + A list of :class:`CudaDevice` of the given CUDA indices. Raises: RuntimeError: @@ -397,7 +397,7 @@ class Device: # pylint: disable=too-many-instance-attributes,too-many-public-me @ttl_cache(ttl=300.0) def _parse_cuda_visible_devices(cuda_visible_devices: str) -> Union[List[int], List[Tuple[int, int]]]: - """The underlining implementation for ``parse_cuda_visible_devices``. The result will be cached.""" + """The underlining implementation for :meth:`parse_cuda_visible_devices`. The result will be cached.""" def from_index_or_uuid(index_or_uuid: Union[int, str]) -> 'Device': nonlocal use_integer_identifiers @@ -462,7 +462,7 @@ class Device: # pylint: disable=too-many-instance-attributes,too-many-public-me Note: This method takes exact 1 non-None argument. Returns: Union[PhysicalDevice, MigDevice] - A ``PhysicalDevice`` instance or a ``MigDevice`` instance. + A :class:`PhysicalDevice` instance or a :class:`MigDevice` instance. Raises: TypeError: @@ -510,9 +510,9 @@ class Device: # pylint: disable=too-many-instance-attributes,too-many-public-me """Initializes the instance created by ``__new__()``. Raises: - NVMLError_NotFound: + nvml.NVMLError_NotFound: If the device is not found for the given NVML identifier. - NVMLError_InvalidArgument: + nvml.NVMLError_InvalidArgument: If the device index is out of range. """ @@ -590,11 +590,11 @@ class Device: # pylint: disable=too-many-instance-attributes,too-many-public-me >>> device = Device(0) - # Method `cuda_compute_capability` is not implemented in the class definition + >>> # Method `cuda_compute_capability` is not implemented in the class definition >>> PhysicalDevice.cuda_compute_capability AttributeError: type object 'Device' has no attribute 'cuda_compute_capability' - # Dynamically create a new method from `pynvml.nvmlDeviceGetCudaComputeCapability(device.handle, *args, **kwargs)` + >>> # Dynamically create a new method from `pynvml.nvmlDeviceGetCudaComputeCapability(device.handle, *args, **kwargs)` >>> device.cuda_compute_capability @@ -702,7 +702,7 @@ class Device: # pylint: disable=too-many-instance-attributes,too-many-public-me """The official product name of the GPU. This is an alphanumeric string. For all products. Returns: Union[str, NaType] - The official product name, or ``nvitop.NA`` (str: ``'N/A'``) when not applicable. + The official product name, or :const:`nvitop.NA` when not applicable. Command line equivalent: @@ -720,7 +720,7 @@ class Device: # pylint: disable=too-many-instance-attributes,too-many-public-me not correspond to any physical label on the board. Returns: Union[str, NaType] - The UUID of the device, or ``nvitop.NA`` (str: ``'N/A'``) when not applicable. + The UUID of the device, or :const:`nvitop.NA` when not applicable. Command line equivalent: @@ -737,7 +737,7 @@ class Device: # pylint: disable=too-many-instance-attributes,too-many-public-me """PCI bus ID as "domain:bus:device.function", in hex. Returns: Union[str, NaType] - The PCI bus ID of the device, or ``nvitop.NA`` (str: ``'N/A'``) when not applicable. + The PCI bus ID of the device, or :const:`nvitop.NA` when not applicable. Command line equivalent: @@ -755,7 +755,7 @@ class Device: # pylint: disable=too-many-instance-attributes,too-many-public-me unique immutable alphanumeric value. Returns: Union[str, NaType] - The serial number of the device, or ``nvitop.NA`` (str: ``'N/A'``) when not applicable. + The serial number of the device, or :const:`nvitop.NA` when not applicable. Command line equivalent: @@ -772,7 +772,7 @@ class Device: # pylint: disable=too-many-instance-attributes,too-many-public-me """Returns a named tuple with memory information (in bytes) for the device. Returns: MemoryInfo(total, free, used) - A named tuple with memory information, the item could be ``nvitop.NA`` (str: ``'N/A'``) when not applicable. + A named tuple with memory information, the item could be :const:`nvitop.NA` when not applicable. """ memory_info = nvml.nvmlQuery('nvmlDeviceGetMemoryInfo', self.handle) @@ -784,7 +784,7 @@ class Device: # pylint: disable=too-many-instance-attributes,too-many-public-me """Total installed GPU memory in bytes. Returns: Union[int, NaType] - Total installed GPU memory in bytes, or ``nvitop.NA`` (str: ``'N/A'``) when not applicable. + Total installed GPU memory in bytes, or :const:`nvitop.NA` when not applicable. Command line equivalent: @@ -801,7 +801,7 @@ class Device: # pylint: disable=too-many-instance-attributes,too-many-public-me """Total memory allocated by active contexts in bytes. Returns: Union[int, NaType] - Total memory allocated by active contexts in bytes, or ``nvitop.NA`` (str: ``'N/A'``) when not applicable. + Total memory allocated by active contexts in bytes, or :const:`nvitop.NA` when not applicable. Command line equivalent: @@ -816,7 +816,7 @@ class Device: # pylint: disable=too-many-instance-attributes,too-many-public-me """Total free memory in bytes. Returns: Union[int, NaType] - Total free memory in bytes, or ``nvitop.NA`` (str: ``'N/A'``) when not applicable. + Total free memory in bytes, or :const:`nvitop.NA` when not applicable. Command line equivalent: @@ -831,7 +831,7 @@ class Device: # pylint: disable=too-many-instance-attributes,too-many-public-me """Total installed GPU memory in human readable format. Returns: Union[str, NaType] - Total installed GPU memory in human readable format, or ``nvitop.NA`` (str: ``'N/A'``) when not applicable. + Total installed GPU memory in human readable format, or :const:`nvitop.NA` when not applicable. """ if self._memory_total_human is NA: @@ -842,7 +842,7 @@ class Device: # pylint: disable=too-many-instance-attributes,too-many-public-me """Total memory allocated by active contexts in human readable format. Returns: Union[int, NaType] - Total memory allocated by active contexts in human readable format, or ``nvitop.NA`` (str: ``'N/A'``) when not applicable. + Total memory allocated by active contexts in human readable format, or :const:`nvitop.NA` when not applicable. """ # pylint: disable=line-too-long return bytes2human(self.memory_used()) @@ -851,7 +851,7 @@ class Device: # pylint: disable=too-many-instance-attributes,too-many-public-me """Total free memory in human readable format. Returns: Union[int, NaType] - Total free memory in human readable format, or ``nvitop.NA`` (str: ``'N/A'``) when not applicable. + Total free memory in human readable format, or :const:`nvitop.NA` when not applicable. """ return bytes2human(self.memory_free()) @@ -860,7 +860,7 @@ class Device: # pylint: disable=too-many-instance-attributes,too-many-public-me """The percentage of used memory over total memory (0 <= p <= 100). Returns: Union[float, NaType] - The percentage of used memory over total memory, or ``nvitop.NA`` (str: ``'N/A'``) when not applicable. + The percentage of used memory over total memory, or :const:`nvitop.NA` when not applicable. """ memory_info = self.memory_info() @@ -872,8 +872,8 @@ class Device: # pylint: disable=too-many-instance-attributes,too-many-public-me """The used memory over total memory in human readable format. Returns: str - The used memory over total memory in human readable format, or 'N/A / N/A' when not applicable. - """ + The used memory over total memory in human readable format, or :const:`'N/A / N/A'` when not applicable. + """ # pylint: disable=line-too-long return '{} / {}'.format(self.memory_used_human(), self.memory_total_human()) @@ -883,7 +883,7 @@ class Device: # pylint: disable=too-many-instance-attributes,too-many-public-me """Returns a named tuple with BAR1 memory information (in bytes) for the device. Returns: MemoryInfo(total, free, used) - A named tuple with BAR1 memory information, the item could be ``nvitop.NA`` (str: ``'N/A'``) when not applicable. + A named tuple with BAR1 memory information, the item could be :const:`nvitop.NA` when not applicable. """ # pylint: disable=line-too-long memory_info = nvml.nvmlQuery('nvmlDeviceGetBAR1MemoryInfo', self.handle) @@ -895,7 +895,7 @@ class Device: # pylint: disable=too-many-instance-attributes,too-many-public-me """Total BAR1 memory in bytes. Returns: Union[int, NaType] - Total BAR1 memory in bytes, or ``nvitop.NA`` (str: ``'N/A'``) when not applicable. + Total BAR1 memory in bytes, or :const:`nvitop.NA` when not applicable. """ return self.bar1_memory_info().total @@ -904,7 +904,7 @@ class Device: # pylint: disable=too-many-instance-attributes,too-many-public-me """Total used BAR1 memory in bytes. Returns: Union[int, NaType] - Total used BAR1 memory in bytes, or ``nvitop.NA`` (str: ``'N/A'``) when not applicable. + Total used BAR1 memory in bytes, or :const:`nvitop.NA` when not applicable. """ return self.bar1_memory_info().used @@ -913,7 +913,7 @@ class Device: # pylint: disable=too-many-instance-attributes,too-many-public-me """Total free BAR1 memory in bytes. Returns: Union[int, NaType] - Total free BAR1 memory in bytes, or ``nvitop.NA`` (str: ``'N/A'``) when not applicable. + Total free BAR1 memory in bytes, or :const:`nvitop.NA` when not applicable. """ return self.bar1_memory_info().free @@ -922,7 +922,7 @@ class Device: # pylint: disable=too-many-instance-attributes,too-many-public-me """Total BAR1 memory in human readable format. Returns: Union[int, NaType] - Total BAR1 memory in human readable format, or ``nvitop.NA`` (str: ``'N/A'``) when not applicable. + Total BAR1 memory in human readable format, or :const:`nvitop.NA` when not applicable. """ return bytes2human(self.bar1_memory_total()) @@ -931,7 +931,7 @@ class Device: # pylint: disable=too-many-instance-attributes,too-many-public-me """Total used BAR1 memory in human readable format. Returns: Union[int, NaType] - Total used BAR1 memory in human readable format, or ``nvitop.NA`` (str: ``'N/A'``) when not applicable. + Total used BAR1 memory in human readable format, or :const:`nvitop.NA` when not applicable. """ return bytes2human(self.bar1_memory_used()) @@ -940,7 +940,7 @@ class Device: # pylint: disable=too-many-instance-attributes,too-many-public-me """Total free BAR1 memory in human readable format. Returns: Union[int, NaType] - Total free BAR1 memory in human readable format, or ``nvitop.NA`` (str: ``'N/A'``) when not applicable. + Total free BAR1 memory in human readable format, or :const:`nvitop.NA` when not applicable. """ return bytes2human(self.bar1_memory_free()) @@ -949,7 +949,7 @@ class Device: # pylint: disable=too-many-instance-attributes,too-many-public-me """The percentage of used BAR1 memory over total BAR1 memory (0 <= p <= 100). Returns: Union[float, NaType] - The percentage of used BAR1 memory over total BAR1 memory, or ``nvitop.NA`` (str: ``'N/A'``) when not applicable. + The percentage of used BAR1 memory over total BAR1 memory, or :const:`nvitop.NA` when not applicable. """ # pylint: disable=line-too-long memory_info = self.bar1_memory_info() @@ -961,8 +961,8 @@ class Device: # pylint: disable=too-many-instance-attributes,too-many-public-me """The used BAR1 memory over total BAR1 memory in human readable format. Returns: str - The used BAR1 memory over total BAR1 memory in human readable format, or 'N/A / N/A' when not applicable. - """ + The used BAR1 memory over total BAR1 memory in human readable format, or :const:`'N/A / N/A'` when not applicable. + """ # pylint: disable=line-too-long return '{} / {}'.format(self.bar1_memory_used_human(), self.bar1_memory_total_human()) @@ -972,7 +972,7 @@ class Device: # pylint: disable=too-many-instance-attributes,too-many-public-me """Returns a named tuple with GPU utilization rates (in percentage) for the device. Returns: UtilizationRates(gpu, memory, encoder, decoder) - A named tuple with GPU utilization rates (in percentage) for the device, the item could be ``nvitop.NA`` (str: ``'N/A'``) when not applicable. + A named tuple with GPU utilization rates (in percentage) for the device, the item could be :const:`nvitop.NA` when not applicable. """ # pylint: disable=line-too-long gpu, memory, encoder, decoder = NA, NA, NA, NA @@ -996,7 +996,7 @@ class Device: # pylint: disable=too-many-instance-attributes,too-many-public-me The sample period may be between 1 second and 1/6 second depending on the product. Returns: Union[int, NaType] - The GPU utilization rate in percentage, or ``nvitop.NA`` (str: ``'N/A'``) when not applicable. + The GPU utilization rate in percentage, or :const:`nvitop.NA` when not applicable. Command line equivalent: @@ -1014,7 +1014,7 @@ class Device: # pylint: disable=too-many-instance-attributes,too-many-public-me The sample period may be between 1 second and 1/6 second depending on the product. Returns: Union[int, NaType] - The memory bandwidth utilization rate of the GPU in percentage, or ``nvitop.NA`` (str: ``'N/A'``) when not applicable. + The memory bandwidth utilization rate of the GPU in percentage, or :const:`nvitop.NA` when not applicable. Command line equivalent: @@ -1029,7 +1029,7 @@ class Device: # pylint: disable=too-many-instance-attributes,too-many-public-me """The encoder utilization rate in percentage. Returns: Union[int, NaType] - The encoder utilization rate in percentage, or ``nvitop.NA`` (str: ``'N/A'``) when not applicable. + The encoder utilization rate in percentage, or :const:`nvitop.NA` when not applicable. """ return self.utilization_rates().encoder @@ -1038,7 +1038,7 @@ class Device: # pylint: disable=too-many-instance-attributes,too-many-public-me """The decoder utilization rate in percentage. Returns: Union[int, NaType] - The decoder utilization rate in percentage, or ``nvitop.NA`` (str: ``'N/A'``) when not applicable. + The decoder utilization rate in percentage, or :const:`nvitop.NA` when not applicable. """ return self.utilization_rates().decoder @@ -1049,7 +1049,7 @@ class Device: # pylint: disable=too-many-instance-attributes,too-many-public-me """Returns a named tuple with current clock speeds (in MHz) for the device. Returns: ClockInfos(graphics, sm, memory, video) - A named tuple with current clock speeds (in MHz) for the device, the item could be ``nvitop.NA`` (str: ``'N/A'``) when not applicable. + A named tuple with current clock speeds (in MHz) for the device, the item could be :const:`nvitop.NA` when not applicable. """ # pylint: disable=line-too-long return ClockInfos( @@ -1067,7 +1067,7 @@ class Device: # pylint: disable=too-many-instance-attributes,too-many-public-me """Returns a named tuple with maximum clock speeds (in MHz) for the device. Returns: ClockInfos(graphics, sm, memory, video) - A named tuple with maximum clock speeds (in MHz) for the device, the item could be ``nvitop.NA`` (str: ``'N/A'``) when not applicable. + A named tuple with maximum clock speeds (in MHz) for the device, the item could be :const:`nvitop.NA` when not applicable. """ # pylint: disable=line-too-long clock_infos = self._max_clock_infos._asdict() @@ -1094,7 +1094,7 @@ class Device: # pylint: disable=too-many-instance-attributes,too-many-public-me """Current frequency of graphics (shader) clock in MHz. Returns: Union[int, NaType] - The current frequency of graphics (shader) clock in MHz, or ``nvitop.NA`` (str: ``'N/A'``) when not applicable. + The current frequency of graphics (shader) clock in MHz, or :const:`nvitop.NA` when not applicable. Command line equivalent: @@ -1109,7 +1109,7 @@ class Device: # pylint: disable=too-many-instance-attributes,too-many-public-me """Current frequency of SM (Streaming Multiprocessor) clock in MHz. Returns: Union[int, NaType] - The current frequency of SM (Streaming Multiprocessor) clock in MHz, or ``nvitop.NA`` (str: ``'N/A'``) when not applicable. + The current frequency of SM (Streaming Multiprocessor) clock in MHz, or :const:`nvitop.NA` when not applicable. Command line equivalent: @@ -1124,7 +1124,7 @@ class Device: # pylint: disable=too-many-instance-attributes,too-many-public-me """Current frequency of memory clock in MHz. Returns: Union[int, NaType] - The current frequency of memory clock in MHz, or ``nvitop.NA`` (str: ``'N/A'``) when not applicable. + The current frequency of memory clock in MHz, or :const:`nvitop.NA` when not applicable. Command line equivalent: @@ -1139,7 +1139,7 @@ class Device: # pylint: disable=too-many-instance-attributes,too-many-public-me """Current frequency of video encoder/decoder clock in MHz. Returns: Union[int, NaType] - The current frequency of video encoder/decoder clock in MHz, or ``nvitop.NA`` (str: ``'N/A'``) when not applicable. + The current frequency of video encoder/decoder clock in MHz, or :const:`nvitop.NA` when not applicable. Command line equivalent: @@ -1154,7 +1154,7 @@ class Device: # pylint: disable=too-many-instance-attributes,too-many-public-me """Maximum frequency of graphics (shader) clock in MHz. Returns: Union[int, NaType] - The maximum frequency of graphics (shader) clock in MHz, or ``nvitop.NA`` (str: ``'N/A'``) when not applicable. + The maximum frequency of graphics (shader) clock in MHz, or :const:`nvitop.NA` when not applicable. Command line equivalent: @@ -1169,7 +1169,7 @@ class Device: # pylint: disable=too-many-instance-attributes,too-many-public-me """Maximum frequency of SM (Streaming Multiprocessor) clock in MHz. Returns: Union[int, NaType] - The maximum frequency of SM (Streaming Multiprocessor) clock in MHz, or ``nvitop.NA`` (str: ``'N/A'``) when not applicable. + The maximum frequency of SM (Streaming Multiprocessor) clock in MHz, or :const:`nvitop.NA` when not applicable. Command line equivalent: @@ -1184,7 +1184,7 @@ class Device: # pylint: disable=too-many-instance-attributes,too-many-public-me """Maximum frequency of memory clock in MHz. Returns: Union[int, NaType] - The maximum frequency of memory clock in MHz, or ``nvitop.NA`` (str: ``'N/A'``) when not applicable. + The maximum frequency of memory clock in MHz, or :const:`nvitop.NA` when not applicable. Command line equivalent: @@ -1199,7 +1199,7 @@ class Device: # pylint: disable=too-many-instance-attributes,too-many-public-me """Maximum frequency of video encoder/decoder clock in MHz. Returns: Union[int, NaType] - The maximum frequency of video encoder/decoder clock in MHz, or ``nvitop.NA`` (str: ``'N/A'``) when not applicable. + The maximum frequency of video encoder/decoder clock in MHz, or :const:`nvitop.NA` when not applicable. Command line equivalent: @@ -1219,7 +1219,7 @@ class Device: # pylint: disable=too-many-instance-attributes,too-many-public-me because they rely on cooling via fans in the surrounding enclosure. Returns: Union[int, NaType] - The fan speed value in percentage, or ``nvitop.NA`` (str: ``'N/A'``) when not applicable. + The fan speed value in percentage, or :const:`nvitop.NA` when not applicable. Command line equivalent: @@ -1235,7 +1235,7 @@ class Device: # pylint: disable=too-many-instance-attributes,too-many-public-me """Core GPU temperature. in degrees C. Returns: Union[int, NaType] - The core GPU temperature in Celsius degrees, or ``nvitop.NA`` (str: ``'N/A'``) when not applicable. + The core GPU temperature in Celsius degrees, or :const:`nvitop.NA` when not applicable. Command line equivalent: @@ -1252,7 +1252,7 @@ class Device: # pylint: disable=too-many-instance-attributes,too-many-public-me """The last measured power draw for the entire board in milliwatts. Returns: Union[int, NaType] - The power draw for the entire board in milliwatts, or ``nvitop.NA`` (str: ``'N/A'``) when not applicable. + The power draw for the entire board in milliwatts, or :const:`nvitop.NA` when not applicable. Command line equivalent: @@ -1271,7 +1271,7 @@ class Device: # pylint: disable=too-many-instance-attributes,too-many-public-me """The software power limit in milliwatts. Set by software like nvidia-smi. Returns: Union[int, NaType] - The software power limit in milliwatts, or ``nvitop.NA`` (str: ``'N/A'``) when not applicable. + The software power limit in milliwatts, or :const:`nvitop.NA` when not applicable. Command line equivalent: @@ -1286,8 +1286,8 @@ class Device: # pylint: disable=too-many-instance-attributes,too-many-public-me """The string of power usage over power limit in watts. Returns: str - The string of power usage over power limit in watts, or 'N/A / N/A' when not applicable. - """ + The string of power usage over power limit in watts, or :const:`'N/A / N/A'` when not applicable. + """ # pylint: disable=line-too-long power_usage = self.power_usage() power_limit = self.power_limit() @@ -1304,9 +1304,9 @@ class Device: # pylint: disable=too-many-instance-attributes,too-many-public-me physically attached. "Enabled" indicates an active display. "Disabled" indicates otherwise. Returns: Union[str, NaType] - - 'Disabled': if not an active display device. - - 'Enabled': if an active display device. - - ``nvitop.NA`` (str: ``'N/A'``): if not applicable. + - :const:`'Disabled'`: if not an active display device. + - :const:`'Enabled'`: if an active display device. + - :const:`nvitop.NA`: if not applicable. Command line equivalent: @@ -1324,9 +1324,9 @@ class Device: # pylint: disable=too-many-instance-attributes,too-many-public-me otherwise. Returns: Union[str, NaType] - - 'Disabled': if the display mode is disabled. - - 'Enabled': if the display mode is enabled. - - ``nvitop.NA`` (str: ``'N/A'``): if not applicable. + - :const:`'Disabled'`: if the display mode is disabled. + - :const:`'Enabled'`: if the display mode is enabled. + - :const:`nvitop.NA`: if not applicable. Command line equivalent: @@ -1346,9 +1346,9 @@ class Device: # pylint: disable=too-many-instance-attributes,too-many-public-me Linux does not support multiple driver models, and will always have the value of "N/A". Returns: Union[str, NaType] - - 'WDDM': for WDDM driver model on Windows. - - 'WDM': for TTC (WDM) driver model on Windows. - - ``nvitop.NA`` (str: ``'N/A'``): if not applicable, e.g. on Linux. + - :const:`'WDDM'`: for WDDM driver model on Windows. + - :const:`'WDM'`: for TTC (WDM) driver model on Windows. + - :const:`nvitop.NA`: if not applicable, e.g. on Linux. Command line equivalent: @@ -1372,9 +1372,9 @@ class Device: # pylint: disable=too-many-instance-attributes,too-many-public-me load latency associated with running dependent apps, such as CUDA programs. Linux only. Returns: Union[str, NaType] - - 'Disabled': if the persistence mode is disabled. - - 'Enabled': if the persistence mode is enabled. - - ``nvitop.NA`` (str: ``'N/A'``): if not applicable. + - :const:`'Disabled'`: if the persistence mode is disabled. + - :const:`'Enabled'`: if the persistence mode is enabled. + - :const:`nvitop.NA`: if not applicable. Command line equivalent: @@ -1391,7 +1391,7 @@ class Device: # pylint: disable=too-many-instance-attributes,too-many-public-me P12 (minimum performance). Returns: Union[str, NaType] - The current performance state in format ``P``, or ``nvitop.NA`` (str: ``'N/A'``) when not applicable. + The current performance state in format ``P``, or :const:`nvitop.NA` when not applicable. Command line equivalent: @@ -1410,7 +1410,7 @@ class Device: # pylint: disable=too-many-instance-attributes,too-many-public-me """Total errors detected across entire chip. Returns: Union[int, NaType] - The total number of uncorrected errors in volatile ECC memory, or ``nvitop.NA`` (str: ``'N/A'``) when not applicable. + The total number of uncorrected errors in volatile ECC memory, or :const:`nvitop.NA` when not applicable. Command line equivalent: @@ -1429,18 +1429,18 @@ class Device: # pylint: disable=too-many-instance-attributes,too-many-public-me run on the GPU. Returns: Union[str, NaType] - - 'Default': means multiple contexts are allowed per device. - - 'Exclusive Thread': deprecated, use Exclusive Process instead - - 'Prohibited': means no contexts are allowed per device (no compute apps). - - 'Exclusive Process': means only one context is allowed per device, usable from multiple threads at a time. - - ``nvitop.NA`` (str: ``'N/A'``): if not applicable. + - :const:`'Default'`: means multiple contexts are allowed per device. + - :const:`'Exclusive Thread'`: deprecated, use Exclusive Process instead + - :const:`'Prohibited'`: means no contexts are allowed per device (no compute apps). + - :const:`'Exclusive Process'`: means only one context is allowed per device, usable from multiple threads at a time. + - :const:`nvitop.NA`: if not applicable. Command line equivalent: .. code:: bash nvidia-smi --id= --format=csv,noheader,nounits --query-gpu=compute_mode - """ + """ # pylint: disable=line-too-long return { nvml.NVML_COMPUTEMODE_DEFAULT: 'Default', @@ -1463,9 +1463,9 @@ class Device: # pylint: disable=too-many-instance-attributes,too-many-public-me """The MIG mode that the GPU is currently operating under. Returns: Union[str, NaType] - - 'Disabled': if the MIG mode is disabled. - - 'Enabled': if the MIG mode is enabled. - - ``nvitop.NA`` (str: ``'N/A'``): if not applicable, e.g. the GPU does not support MIG mode. + - :const:`'Disabled'`: if the MIG mode is disabled. + - :const:`'Enabled'`: if the MIG mode is enabled. + - :const:`nvitop.NA`: if not applicable, e.g. the GPU does not support MIG mode. Command line equivalent: @@ -1482,7 +1482,7 @@ class Device: # pylint: disable=too-many-instance-attributes,too-many-public-me return {0: 'Disabled', 1: 'Enabled'}.get(mig_mode, NA) def is_mig_mode_enabled(self) -> bool: - """Returns whether the MIG mode is enabled on the device. Returns ``False`` if MIG mode is + """Returns whether the MIG mode is enabled on the device. Returns :data:`False` if MIG mode is disabled or the device does not support MIG mode. """ @@ -1503,8 +1503,8 @@ class Device: # pylint: disable=too-many-instance-attributes,too-many-public-me return [] # implemented in PhysicalDevice def is_leaf_device(self) -> bool: - """Returns ``True`` if the device is a physical device with MIG mode disabled or a MIG device. - Otherwise returns ``False`` if the device is a physical device with MIG mode enabled. + """Returns :data:`True` if the device is a physical device with MIG mode disabled or a MIG device. + Otherwise returns :data:`False` if the device is a physical device with MIG mode enabled. """ return (self.is_mig_device() or not self.is_mig_mode_enabled()) @@ -1550,7 +1550,7 @@ class Device: # pylint: disable=too-many-instance-attributes,too-many-public-me return processes def as_snapshot(self) -> Snapshot: - """Returns a onetime snapshot of the device. The attributes are defined in ``SNAPSHOT_KEYS``.""" + """Returns a onetime snapshot of the device. The attributes are defined in :attr:`SNAPSHOT_KEYS`.""" with self.oneshot(): return Snapshot(real=self, index=self.index, physical_index=self.physical_index, @@ -1752,7 +1752,7 @@ class MigDevice(Device): # pylint: disable=too-many-instance-attributes Indices of the MIG devices. Each index is a tuple of two integers. Returns: List[MigDevice] - A list of ``MigDevice`` instances of the given indices. + A list of :class:`MigDevice` instances of the given indices. """ return list(map(cls, indices)) @@ -1839,7 +1839,7 @@ class MigDevice(Device): # pylint: disable=too-many-instance-attributes """The gpu instance ID of the MIG device. Returns: Union[int, NaType] - The gpu instance ID of the MIG device, or ``nvitop.NA`` (str: ``'N/A'``) when not applicable. + The gpu instance ID of the MIG device, or :const:`nvitop.NA` when not applicable. """ if self._gpu_instance_id is NA: @@ -1853,7 +1853,7 @@ class MigDevice(Device): # pylint: disable=too-many-instance-attributes """The compute instance ID of the MIG device. Returns: Union[int, NaType] - The compute instance ID of the MIG device, or ``nvitop.NA`` (str: ``'N/A'``) when not applicable. + The compute instance ID of the MIG device, or :const:`nvitop.NA` when not applicable. """ if self._compute_instance_id is NA: @@ -1864,7 +1864,7 @@ class MigDevice(Device): # pylint: disable=too-many-instance-attributes return self._compute_instance_id def as_snapshot(self) -> Snapshot: - """Returns a onetime snapshot of the device. The attributes are defined in ``SNAPSHOT_KEYS``.""" + """Returns a onetime snapshot of the device. The attributes are defined in :attr:`SNAPSHOT_KEYS`.""" snapshot = super().as_snapshot() snapshot.mig_index = self.mig_index @@ -1882,7 +1882,7 @@ class CudaDevice(Device): - `CUDA Environment Variables `_ - `CUDA Device Enumeration for MIG Device `_ - ``CudaDevice.__new__()`` returns different types depending on the given arguments. + :meth:`CudaDevice.__new__()` returns different types depending on the given arguments. .. code-block:: python @@ -1960,7 +1960,7 @@ class CudaDevice(Device): The indices of the GPU in CUDA ordinal, if not given, returns all visible CUDA devices. Returns: List[CudaDevice] - A list of ``CudaDevice`` of the given CUDA indices. + A list of :class:`CudaDevice` of the given CUDA indices. Raises: RuntimeError: @@ -1986,7 +1986,7 @@ class CudaDevice(Device): Note: This method takes exact 1 non-None argument. Returns: Union[CudaDevice, CudaMigDevice] - A ``CudaDevice`` instance or a ``CudaMigDevice`` instance. + A :class:`CudaDevice` instance or a :class:`CudaMigDevice` instance. Raises: TypeError: @@ -2016,9 +2016,9 @@ class CudaDevice(Device): """Initializes the instance created by ``__new__()``. Raises: - NVMLError_NotFound: + nvml.NVMLError_NotFound: If the device is not found for the given NVML identifier. - NVMLError_InvalidArgument: + nvml.NVMLError_InvalidArgument: If the NVML index is out of range. RuntimeError: The given device is not visible to CUDA applications. @@ -2051,7 +2051,7 @@ class CudaDevice(Device): return self.__class__, (self._cuda_index,) def as_snapshot(self) -> Snapshot: - """Returns a onetime snapshot of the device. The attributes are defined in ``SNAPSHOT_KEYS``.""" + """Returns a onetime snapshot of the device. The attributes are defined in :attr:`SNAPSHOT_KEYS`.""" snapshot = super().as_snapshot() snapshot.cuda_index = self.cuda_index @@ -2060,7 +2060,7 @@ class CudaDevice(Device): Device.cuda = CudaDevice -"""Shortcut for class ``CudaDevice``.""" +"""Shortcut for class :class:`CudaDevice`.""" class CudaMigDevice(CudaDevice, MigDevice): diff --git a/nvitop/core/libnvml.py b/nvitop/core/libnvml.py index 7d8dcab..70c019d 100644 --- a/nvitop/core/libnvml.py +++ b/nvitop/core/libnvml.py @@ -36,7 +36,7 @@ class libnvml: c_nvmlDevice_t = pynvml.c_nvmlDevice_t def __new__(cls) -> 'libnvml': - """Gets the singleton instance of ``libnvml``.""" + """Gets the singleton instance of :class:`libnvml`.""" if not hasattr(cls, '_instance'): instance = cls._instance = super().__new__(cls) @@ -210,7 +210,7 @@ class libnvml: Whether to ignore errors and return the default value. ignore_function_not_found (bool): Whether to ignore function not found errors and return the - default value. If set to ``False``, a error message will be logged + default value. If set to :data:`False`, a error message will be logged to the logger. *args: Positional arguments to pass to the query function. @@ -260,7 +260,7 @@ class libnvml: @staticmethod def nvmlCheckReturn(retval: Any, types: Optional[Union[type, Tuple[type, ...]]] = None) -> bool: - """Checks the return value is not ``nvitop.NA`` and is one of the given types.""" + """Checks the return value is not :const:`nvitop.NA` and is one of the given types.""" if types is None: return retval != NA @@ -268,7 +268,7 @@ class libnvml: nvml = libnvml() -"""The singleton instance of class ``libnvml``.""" +"""The singleton instance of class :class:`libnvml`.""" nvmlCheckReturn = nvml.nvmlCheckReturn diff --git a/nvitop/core/process.py b/nvitop/core/process.py index 8c3c4ce..d4713eb 100644 --- a/nvitop/core/process.py +++ b/nvitop/core/process.py @@ -3,7 +3,7 @@ """The live classes for process running on the host and the GPU devices.""" -# pylint: disable=invalid-name +# pylint: disable=invalid-name,too-many-lines import contextlib import datetime @@ -82,7 +82,7 @@ _USE_FALLBACK_WHEN_RAISE = threading.local() # see also `GpuProcess.failsafe` def auto_garbage_clean(fallback=_RAISE): """Removes the object references in the instance cache if the method call fails (the process is gone). - The fallback value will be used with ``GpuProcess.failsafe`` context manager, otherwise raises an + The fallback value will be used with `:meth:`GpuProcess.failsafe`` context manager, otherwise raises an exception when falls. """ @@ -120,7 +120,7 @@ def auto_garbage_clean(fallback=_RAISE): class HostProcess(host.Process, metaclass=ABCMeta): """Represents an OS process with the given PID. - If PID is omitted current process PID (os.getpid()) is used. + If PID is omitted current process PID (:func:`os.getpid`) is used. The instance will be cache during the lifetime of the process. Examples: @@ -162,7 +162,7 @@ class HostProcess(host.Process, metaclass=ABCMeta): INSTANCES = WeakValueDictionary() def __new__(cls, pid: Optional[int] = None) -> 'HostProcess': - """Returns the cached instance of ``HostProcess``.""" + """Returns the cached instance of :class:`HostProcess`.""" if pid is None: pid = os.getpid() @@ -275,7 +275,7 @@ class HostProcess(host.Process, metaclass=ABCMeta): @memoize_when_activated def running_time(self) -> datetime.timedelta: - """The elapsed time this process has been running in ``datetime.timedelta``. + """The elapsed time this process has been running in :class:`datetime.timedelta`. Raises: host.NoSuchProcess: @@ -327,7 +327,7 @@ class HostProcess(host.Process, metaclass=ABCMeta): return self.memory_info().rss def parent(self) -> Union['HostProcess', None]: - """Returns the parent process as a ``HostProcess`` instance. Returns ``None`` if there is no parent. + """Returns the parent process as a :class:`HostProcess` instance. Returns :data:`None` if there is no parent. Raises: host.NoSuchProcess: @@ -342,8 +342,8 @@ class HostProcess(host.Process, metaclass=ABCMeta): return None def children(self, recursive: bool = False) -> List['HostProcess']: - """Return the children of this process as a list of ``HostProcess`` instances. - If *recursive* is ``True`` return all the descendants. + """Return the children of this process as a list of :class:`HostProcess` instances. + If *recursive* is :data:`True` return all the descendants. Raises: host.NoSuchProcess: @@ -372,8 +372,8 @@ class HostProcess(host.Process, metaclass=ABCMeta): >>> from nvitop import HostProcess >>> p = HostProcess() >>> with p.oneshot(): - ... p.name() # collect multiple info - ... p.cpu_times() # return cached value + ... p.name() # collect multiple info + ... p.cpu_times() # return cached value ... p.cpu_percent() # return cached value ... p.create_time() # return cached value """ @@ -413,7 +413,7 @@ class GpuProcess: # pylint: disable=too-many-instance-attributes,too-many-publi """Represents a process with the given PID running on the given GPU device. The instance will be cache during the lifetime of the process. - The same host process can use multiple GPU devices. The ``GpuProcess`` instances representing the + The same host process can use multiple GPU devices. The :class:`GpuProcess` instances representing the same PID on the host but different GPU devices are different. """ @@ -426,7 +426,7 @@ class GpuProcess: # pylint: disable=too-many-instance-attributes,too-many-publi gpu_instance_id: Optional[Union[int, NaType]] = None, compute_instance_id: Optional[Union[int, NaType]] = None, type: Optional[Union[str, NaType]] = None) -> 'GpuProcess': # pylint: disable=redefined-builtin - """Returns the cached instance of ``GpuProcess``.""" + """Returns the cached instance of :class:`GpuProcess`.""" if pid is None: pid = os.getpid() @@ -510,7 +510,7 @@ class GpuProcess: # pylint: disable=too-many-instance-attributes,too-many-publi Raises: AttributeError: - If the attribute is not defined in either ``GpuProcess`` nor ``HostProcess``. + If the attribute is not defined in either :class:`GpuProcess` nor :class:`HostProcess`. host.NoSuchProcess: If the process is gone. host.AccessDenied: @@ -544,54 +544,54 @@ class GpuProcess: # pylint: disable=too-many-instance-attributes,too-many-publi """The GPU device the process running on. The same host process can use multiple GPU devices. - The ``GpuProcess`` instances representing the same PID on the host + The :class:`GpuProcess` instances representing the same PID on the host but different GPU devices are different. """ return self._device def gpu_instance_id(self) -> Union[int, NaType]: - """The GPU instance ID of the MIG device, or ``nvitop.NA`` if not applicable.""" + """The GPU instance ID of the MIG device, or :const:`nvitop.NA` if not applicable.""" return self._gpu_instance_id def compute_instance_id(self) -> Union[int, NaType]: - """The compute instance ID of the MIG device, or ``nvitop.NA`` if not applicable.""" + """The compute instance ID of the MIG device, or :const:`nvitop.NA` if not applicable.""" return self._compute_instance_id def gpu_memory(self) -> Union[int, NaType]: # in bytes - """The used GPU memory in bytes, or ``nvitop.NA`` if not applicable.""" + """The used GPU memory in bytes, or :const:`nvitop.NA` if not applicable.""" return self._gpu_memory def gpu_memory_human(self) -> Union[str, NaType]: # in human readable - """The used GPU memory in human readable format, or ``nvitop.NA`` if not applicable.""" + """The used GPU memory in human readable format, or :const:`nvitop.NA` if not applicable.""" return self._gpu_memory_human def gpu_memory_percent(self) -> Union[float, NaType]: # in percentage - """The percentage of used GPU memory by the process, or ``nvitop.NA`` if not applicable.""" + """The percentage of used GPU memory by the process, or :const:`nvitop.NA` if not applicable.""" return self._gpu_memory_percent def gpu_sm_utilization(self) -> Union[int, NaType]: # in percentage - """The utilization rate of SM (Streaming Multiprocessor), or ``nvitop.NA`` if not applicable.""" + """The utilization rate of SM (Streaming Multiprocessor), or :const:`nvitop.NA` if not applicable.""" return self._gpu_sm_utilization def gpu_memory_utilization(self) -> Union[int, NaType]: # in percentage - """The utilization rate of GPU memory bandwidth, or ``nvitop.NA`` if not applicable.""" + """The utilization rate of GPU memory bandwidth, or :const:`nvitop.NA` if not applicable.""" return self._gpu_memory_utilization def gpu_encoder_utilization(self) -> Union[int, NaType]: # in percentage - """The utilization rate of the encoder, or ``nvitop.NA`` if not applicable.""" + """The utilization rate of the encoder, or :const:`nvitop.NA` if not applicable.""" return self._gpu_encoder_utilization def gpu_decoder_utilization(self) -> Union[int, NaType]: # in percentage - """The utilization rate of the decoder, or ``nvitop.NA`` if not applicable.""" + """The utilization rate of the decoder, or :const:`nvitop.NA` if not applicable.""" return self._gpu_decoder_utilization @@ -671,7 +671,7 @@ class GpuProcess: # pylint: disable=too-many-instance-attributes,too-many-publi Note: To return the fallback value rather than raise an exception, please use the context - manager `GpuProcess.failsafe`. See also :meth:`take_snapshots` and :meth:`failsafe`. + manager :meth:`GpuProcess.failsafe`. See also :meth:`take_snapshots` and :meth:`failsafe`. """ return self.host.status() @@ -689,14 +689,14 @@ class GpuProcess: # pylint: disable=too-many-instance-attributes,too-many-publi Note: To return the fallback value rather than raise an exception, please use the context - manager `GpuProcess.failsafe`. See also :meth:`take_snapshots` and :meth:`failsafe`. + manager :meth:`GpuProcess.failsafe`. See also :meth:`take_snapshots` and :meth:`failsafe`. """ return self.host.create_time() @auto_garbage_clean(fallback=NA) def running_time(self) -> Union[datetime.timedelta, NaType]: - """The elapsed time this process has been running in ``datetime.timedelta``. + """The elapsed time this process has been running in :class:`datetime.timedelta`. Raises: host.NoSuchProcess: @@ -707,7 +707,7 @@ class GpuProcess: # pylint: disable=too-many-instance-attributes,too-many-publi Note: To return the fallback value rather than raise an exception, please use the context - manager `GpuProcess.failsafe`. See also :meth:`take_snapshots` and :meth:`failsafe`. + manager :meth:`GpuProcess.failsafe`. See also :meth:`take_snapshots` and :meth:`failsafe`. """ return self.host.running_time() @@ -724,7 +724,7 @@ class GpuProcess: # pylint: disable=too-many-instance-attributes,too-many-publi Note: To return the fallback value rather than raise an exception, please use the context - manager `GpuProcess.failsafe`. See also :meth:`take_snapshots` and :meth:`failsafe`. + manager :meth:`GpuProcess.failsafe`. See also :meth:`take_snapshots` and :meth:`failsafe`. """ return timedelta2human(self.running_time()) @@ -741,7 +741,7 @@ class GpuProcess: # pylint: disable=too-many-instance-attributes,too-many-publi Note: To return the fallback value rather than raise an exception, please use the context - manager `GpuProcess.failsafe`. See also :meth:`take_snapshots` and :meth:`failsafe`. + manager :meth:`GpuProcess.failsafe`. See also :meth:`take_snapshots` and :meth:`failsafe`. """ running_time = self.running_time() @@ -766,7 +766,7 @@ class GpuProcess: # pylint: disable=too-many-instance-attributes,too-many-publi Note: To return the fallback value rather than raise an exception, please use the context - manager `GpuProcess.failsafe`. See also :meth:`take_snapshots` and :meth:`failsafe`. + manager :meth:`GpuProcess.failsafe`. See also :meth:`take_snapshots` and :meth:`failsafe`. """ if self._username is None: # pylint: disable=access-member-before-definition @@ -786,7 +786,7 @@ class GpuProcess: # pylint: disable=too-many-instance-attributes,too-many-publi Note: To return the fallback value rather than raise an exception, please use the context - manager `GpuProcess.failsafe`. See also :meth:`take_snapshots` and :meth:`failsafe`. + manager :meth:`GpuProcess.failsafe`. See also :meth:`take_snapshots` and :meth:`failsafe`. """ return self.host.name() @@ -804,7 +804,7 @@ class GpuProcess: # pylint: disable=too-many-instance-attributes,too-many-publi Note: To return the fallback value rather than raise an exception, please use the context - manager `GpuProcess.failsafe`. See also :meth:`take_snapshots` and :meth:`failsafe`. + manager :meth:`GpuProcess.failsafe`. See also :meth:`take_snapshots` and :meth:`failsafe`. """ return self.host.cpu_percent() @@ -823,7 +823,7 @@ class GpuProcess: # pylint: disable=too-many-instance-attributes,too-many-publi Note: To return the fallback value rather than raise an exception, please use the context - manager `GpuProcess.failsafe`. See also :meth:`take_snapshots` and :meth:`failsafe`. + manager :meth:`GpuProcess.failsafe`. See also :meth:`take_snapshots` and :meth:`failsafe`. """ return self.host.memory_percent() @@ -843,7 +843,7 @@ class GpuProcess: # pylint: disable=too-many-instance-attributes,too-many-publi Note: To return the fallback value rather than raise an exception, please use the context - manager `GpuProcess.failsafe`. See also :meth:`take_snapshots` and :meth:`failsafe`. + manager :meth:`GpuProcess.failsafe`. See also :meth:`take_snapshots` and :meth:`failsafe`. """ return self.host.rss_memory() @@ -860,7 +860,7 @@ class GpuProcess: # pylint: disable=too-many-instance-attributes,too-many-publi Note: To return the fallback value rather than raise an exception, please use the context - manager `GpuProcess.failsafe`. See also :meth:`take_snapshots` and :meth:`failsafe`. + manager :meth:`GpuProcess.failsafe`. See also :meth:`take_snapshots` and :meth:`failsafe`. """ return bytes2human(self.host_memory()) @@ -880,7 +880,7 @@ class GpuProcess: # pylint: disable=too-many-instance-attributes,too-many-publi Note: To return the fallback value rather than raise an exception, please use the context - manager `GpuProcess.failsafe`. See also :meth:`take_snapshots` and :meth:`failsafe`. + manager :meth:`GpuProcess.failsafe`. See also :meth:`take_snapshots` and :meth:`failsafe`. """ cmdline = self.host.cmdline() @@ -900,7 +900,7 @@ class GpuProcess: # pylint: disable=too-many-instance-attributes,too-many-publi Note: To return the fallback value rather than raise an exception, please use the context - manager `GpuProcess.failsafe`. See also :meth:`take_snapshots` and :meth:`failsafe`. + manager :meth:`GpuProcess.failsafe`. See also :meth:`take_snapshots` and :meth:`failsafe`. """ return command_join(self.cmdline()) @@ -979,10 +979,10 @@ class GpuProcess: # pylint: disable=too-many-instance-attributes,too-many-publi @classmethod def take_snapshots(cls, gpu_processes: Iterable['GpuProcess'], *, # batched version of `as_snapshot` failsafe=False) -> List[Snapshot]: - """Takes snapshots for a list of ``GpuProcess`` instances. + """Takes snapshots for a list of :class:`GpuProcess` instances. - If *failsafe* is ``True``, then if any method fails, the fallback value in - ``auto_garbage_clean(fallback)`` will be used. + If *failsafe* is :data:`True`, then if any method fails, the fallback value in + :func:`auto_garbage_clean` will be used. """ cache = {} diff --git a/nvitop/core/utils.py b/nvitop/core/utils.py index 60a53cc..8f4fdbc 100644 --- a/nvitop/core/utils.py +++ b/nvitop/core/utils.py @@ -15,7 +15,9 @@ from psutil import WINDOWS __all__ = [ - 'NA', 'NaType', 'KiB', 'MiB', 'GiB', 'TiB', 'PiB', + 'NA', 'NaType', + 'NotApplicable', 'NotApplicableType', + 'KiB', 'MiB', 'GiB', 'TiB', 'PiB', 'bytes2human', 'timedelta2human', 'utilization2string', 'colored', 'set_color', 'boolify', 'Snapshot' @@ -70,54 +72,54 @@ def colored(text, color=None, on_color=None, attrs=None): return text -class NotApplicableType(str): - """A singleton (str: 'N/A') class represents a not applicable value.""" +class NaType(str): + """A singleton (:const:`str: 'N/A'`) class represents a not applicable value.""" def __new__(cls): - """Gets the singleton instance.""" + """Gets the singleton instance (:const:`nvitop.NA`).""" if not hasattr(cls, '_instance'): cls._instance = super().__new__(cls, 'N/A') return cls._instance def __bool__(self): - """bool(NA) -> False""" + """``bool(NA)`` -> :data:`False`""" return False def __int__(self): - """int(NA) -> 0""" + """``int(NA)`` -> :data:`0`""" return 0 def __float__(self): - """float(NA) -> math.nan""" + """``float(NA)`` -> :data:`math.nan`""" return math.nan def __lt__(self, x): - """The ``NA`` is always greater than any number. Use the dictionary order for string.""" + """The :const:`nvitop.NA` is always greater than any number. Use the dictionary order for string.""" if isinstance(x, (int, float)): return False return super().__lt__(x) def __le__(self, x): - """The ``NA`` is always greater than any number. Use the dictionary order for string.""" + """The :const:`nvitop.NA` is always greater than any number. Use the dictionary order for string.""" if isinstance(x, (int, float)): return False return super().__le__(x) def __gt__(self, x): - """The ``NA`` is always greater than any number. Use the dictionary order for string.""" + """The :const:`nvitop.NA` is always greater than any number. Use the dictionary order for string.""" if isinstance(x, (int, float)): return True return super().__gt__(x) def __ge__(self, x): - """The ``NA`` is always greater than any number. Use the dictionary order for string.""" + """The :const:`nvitop.NA` is always greater than any number. Use the dictionary order for string.""" if isinstance(x, (int, float)): return True @@ -130,13 +132,15 @@ class NotApplicableType(str): return format(math.nan, format_spec) -# isinstance(NA, str) -> True -# NA == 'N/A' -> True -# NA is NotApplicableType() -> True (NotApplicableType is a singleton class) -NaType = NotApplicableType -NA = NotApplicable = NotApplicableType() -"""The singleton instance of ``NotApplicableType``. The actual value is 'NA'.""" +NotApplicableType = NaType +# isinstance(NA, str) -> True +# NA == 'N/A' -> True +# NA is NaType() -> True (`NaType` is a singleton class) +NA = NaType() +NA.__doc__ = """The singleton instance of :class:`NaType`. The actual value is :const:`str: 'N/A'`.""" # pylint: disable=attribute-defined-outside-init + +NotApplicable = NA KiB = 1 << 10 """Kibibyte (1024)""" @@ -186,7 +190,7 @@ def bytes2human(x): # pylint: disable=too-many-return-statements def timedelta2human(dt): - """Converts ``datetime.timedelta`` instance to a human readable string.""" + """Converts :class:`datetime.timedelta` instance to a human readable string.""" if isinstance(dt, (int, float)): dt = datetime.timedelta(seconds=dt) @@ -287,10 +291,9 @@ class Snapshot: # Modified from psutil (https://github.com/giampaolo/psutil) def memoize_when_activated(func): - """A memoize decorator which is disabled by default. It can be - activated and deactivated on request. - For efficiency reasons it can be used only against class methods - accepting no arguments. + """A memoize decorator which is disabled by default. It can be activated and + deactivated on request. For efficiency reasons it can be used only against + class methods accepting no arguments. """ @functools.wraps(func) @@ -314,8 +317,9 @@ def memoize_when_activated(func): return ret def cache_activate(self): - """Activate cache. Expects a Process instance. Cache will be - stored as a "_cache" instance attribute.""" + """Activate cache. Expects a Process instance. Cache will be stored as + a "_cache" instance attribute. + """ if not hasattr(self, '_cache'): setattr(self, '_cache', {})