github-starred/nvitop
2
0
Fork 0
mirror of https://github.com/XuehaiPan/nvitop.git synced 2026-05-21 06:45:24 -06:00
Code Issues 29 Projects Packages Wiki Activity Actions

docs: resolve code cross-reference

Browse source 
Signed-off-by: Xuehai Pan <XuehaiPan@pku.edu.cn>
This commit is contained in:
Xuehai Pan 2022-07-11 15:11:57 +08:00
parent 4b69a71eac
commit 75a7f7c0a6
10 changed files with 211 additions and 190 deletions
Download patch file Download diff file Expand all files Collapse all files

1
docs/source/apis/core/process.rst
View file

@ -3,6 +3,7 @@ nvitop.core.process module
.. automodule:: nvitop.core.process
:members:
:inherited-members:
:undoc-members:
:show-inheritance:
:member-order: bysource

1
docs/source/apis/core/utils.rst
View file

@ -6,3 +6,4 @@ nvitop.core.utils module
:undoc-members:
:show-inheritance:
:member-order: bysource
:exclude-members: NA, NaType, NotApplicable, NotApplicableType

17
docs/source/apis/index.rst
View file

@ -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

22
nvitop/callbacks/keras.py
View file

@ -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:

22
nvitop/callbacks/pytorch_lightning.py
View file

@ -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:

2
nvitop/core/collector.py
View file

@ -172,6 +172,8 @@ class ResourceMetricCollector: # pylint: disable=too-many-instance-attributes
Core methods:
.. code-block:: python
collector.activate(tag='<tag>') # alias: start
collector.deactivate() # alias: stop
collector.reset(tag='<tag>')

196
nvitop/core/device.py
View file

@ -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 <https://docs.nvidia.com/datacenter/tesla/mig-user-guide/index.html#cuda-visible-devices>`_
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
<function PhysicalDevice.cuda_compute_capability at 0x7fbfddf5d9d0>
@ -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<int>``, or ``nvitop.NA`` (str: ``'N/A'``) when not applicable.
The current performance state in format ``P<int>``, 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=<IDENTIFIER> --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 <https://docs.nvidia.com/cuda/cuda-c-programming-guide/index.html#env-vars>`_
- `CUDA Device Enumeration for MIG Device <https://docs.nvidia.com/datacenter/tesla/mig-user-guide/index.html#cuda-visible-devices>`_
``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):

8
nvitop/core/libnvml.py
View file

@ -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

80
nvitop/core/process.py
View file

@ -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 = {}

52
nvitop/core/utils.py
View file

@ -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', {})