gpuq 1.3.0__tar.gz

gpuq-1.3.0/LICENSE

@@ -0,0 +1,19 @@
+Copyright © 2025 Mako
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the “Software”), to deal in
+the Software without restriction, including without limitation the rights to
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies
+of the Software, and to permit persons to whom the Software is furnished to do
+so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

gpuq-1.3.0/PKG-INFO

@@ -0,0 +1,121 @@
+Metadata-Version: 2.4
+Name: gpuq
+Version: 1.3.0
+Summary: A multi-vendor GPU querying utility with minimal dependencies
+Home-page: https://github.com/makodevai/gpuq
+Download-URL: https://github.com/makodevai/gpuq
+Author: Mako
+Author-email: support@mako.dev
+Requires-Python: >=3.10.0
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: dev
+Requires-Dist: GitPython; extra == "dev"
+Requires-Dist: mypy; extra == "dev"
+Requires-Dist: black; extra == "dev"
+Requires-Dist: pytest; extra == "dev"
+Dynamic: author
+Dynamic: author-email
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: download-url
+Dynamic: home-page
+Dynamic: license-file
+Dynamic: provides-extra
+Dynamic: requires-python
+Dynamic: summary
+
+# *gpuq* - multi-vendor *GPU* *q*uerying utility with minimal dependencies
+
+This small library is a direct answer to the lack of a lightweight, cross-compatible utility to query available GPUs - regardless of what vendor, distro, or overall environment one might be using.
+
+In particular, the implementation meets the following requirements:
+ - works with multiple downstream runtimes (currently supported: CUDA and HIP)
+    - will also work if you have multiple present at the same time (do you really, though?)
+ - no build- or install-time dependencies (including any python packages)
+ - any runtime dependencies are soft - unless the user explicitly asks for the status/presence of a particular downstream runtime, most methods will fail silently
+ - consequently, the package should install and run on pretty much any machine
+    - your laptop does not have a GPU? -> the package will report 0 GPUs available (duh), no exceptions, linker errors, etc.
+ - allows for easy mocking (for unit tests, etc.)
+ - fully typed (conforms to `mypy --strict` checking)
+
+Compared to some existing alternatives, it has the following differences:
+ - `torch.cuda` - not lightweight, also requires a different wheel for NVidia and HIP
+ - `gputil` - NVidia specific, also broken dependencies (as of 2025)
+ - `gpuinfo` - NVidia specific, broken `import gpuinfo`...
+ - `gpuinfonv` - NVidia specific, requires pynvml
+ - `pyamdgpuinfo` - AMD specific
+ - `igpu` - NVidia specific, broken installation (as of 2025)
+ - and so on...
+
+The primary functionality offered is:
+ - check how many GPUs are available
+ - query properties for each available device - will tell you some basic info about the provider (CUDA/HIP) and other info similar to `cudaGetDeviceProperties`
+    - the returned list is not comprehensive, though
+ - respects `*_VISIBLE_DEVICES` and provides mapping between local (visible) and global indices
+    - **NOTE: this temporarily modifies env variables and therefore is not thread-safe**
+ - if requested, lazily provides some runtime information about each GPU as well
+    - in particular, PIDs of processes using the GPU will be returned
+    - NOTE: this is currently done rather naively by parsing outputs of tools like `nvidia-smi` or `rocm-smi`
+ - allows to check for runtime errors that might have occurred while trying to load 
+
+### How it works:
+
+The implementation will attempt to dynamically lazy-load `libcudart.so` and `libamdhip64.so` at runtime.
+For GPUs to be properly reported, the libraries have to be found by the dynamic linker at the moment any relevant function call is made for the first time.
+(If a library fails to load, loading will be retried every time a function call is made).
+
+## Examples
+
+Install with:
+```bash
+pip install gpu
+```
+
+Return the number of available GPUs:
+```python
+import gpuq as G
+
+print(G.count()) # this includes GPUs from all providers, disregarding *_VISIBLE_DEVICES
+print(G.count(visible_only=True)) # only visible GPUs from all providers
+print(G.count(provider=G.Provider.HIP, visible_only=True)) # only visible HIP devices
+# etc.
+```
+
+Return a list of gpu properties:
+```python
+import gpuq as G
+
+for gpu in G.query(visible_only=True, provider=G.Provider.ANY):
+    print(gpu.name)
+
+# return all visible GPUs, raise an error if no CUDA devices are present
+# (note: the required check if done against the global set, not the return set - see the docs)
+gpus = G.query(visible_only=True, provider=G.Provider.ANY, required=G.Provider.CUDA)
+```
+
+Provide mapping between local and global GPU indices:
+```python
+import gpuq as G
+
+# assume a system with 8 GPUs and CUDA_VISIBLE_DEVICES=1,7
+for gpu in G.query(): # by default return visible GPUs only
+    print(gpu.index, gpu.system_index)
+
+# should print:
+# 0 1
+# 1 7
+
+for gpu in G.query(visible_only=False):
+    print(gpu.index, gpu.system_index, gpu.is_visible)
+
+# should print:
+# None 0 False
+# 0 1 True
+# None 2 False
+# None 3 False
+# None 4 False
+# None 5 False
+# None 6 False
+# 1 7 True
+```

gpuq-1.3.0/README.md

@@ -0,0 +1,94 @@
+# *gpuq* - multi-vendor *GPU* *q*uerying utility with minimal dependencies
+
+This small library is a direct answer to the lack of a lightweight, cross-compatible utility to query available GPUs - regardless of what vendor, distro, or overall environment one might be using.
+
+In particular, the implementation meets the following requirements:
+ - works with multiple downstream runtimes (currently supported: CUDA and HIP)
+    - will also work if you have multiple present at the same time (do you really, though?)
+ - no build- or install-time dependencies (including any python packages)
+ - any runtime dependencies are soft - unless the user explicitly asks for the status/presence of a particular downstream runtime, most methods will fail silently
+ - consequently, the package should install and run on pretty much any machine
+    - your laptop does not have a GPU? -> the package will report 0 GPUs available (duh), no exceptions, linker errors, etc.
+ - allows for easy mocking (for unit tests, etc.)
+ - fully typed (conforms to `mypy --strict` checking)
+
+Compared to some existing alternatives, it has the following differences:
+ - `torch.cuda` - not lightweight, also requires a different wheel for NVidia and HIP
+ - `gputil` - NVidia specific, also broken dependencies (as of 2025)
+ - `gpuinfo` - NVidia specific, broken `import gpuinfo`...
+ - `gpuinfonv` - NVidia specific, requires pynvml
+ - `pyamdgpuinfo` - AMD specific
+ - `igpu` - NVidia specific, broken installation (as of 2025)
+ - and so on...
+
+The primary functionality offered is:
+ - check how many GPUs are available
+ - query properties for each available device - will tell you some basic info about the provider (CUDA/HIP) and other info similar to `cudaGetDeviceProperties`
+    - the returned list is not comprehensive, though
+ - respects `*_VISIBLE_DEVICES` and provides mapping between local (visible) and global indices
+    - **NOTE: this temporarily modifies env variables and therefore is not thread-safe**
+ - if requested, lazily provides some runtime information about each GPU as well
+    - in particular, PIDs of processes using the GPU will be returned
+    - NOTE: this is currently done rather naively by parsing outputs of tools like `nvidia-smi` or `rocm-smi`
+ - allows to check for runtime errors that might have occurred while trying to load 
+
+### How it works:
+
+The implementation will attempt to dynamically lazy-load `libcudart.so` and `libamdhip64.so` at runtime.
+For GPUs to be properly reported, the libraries have to be found by the dynamic linker at the moment any relevant function call is made for the first time.
+(If a library fails to load, loading will be retried every time a function call is made).
+
+## Examples
+
+Install with:
+```bash
+pip install gpu
+```
+
+Return the number of available GPUs:
+```python
+import gpuq as G
+
+print(G.count()) # this includes GPUs from all providers, disregarding *_VISIBLE_DEVICES
+print(G.count(visible_only=True)) # only visible GPUs from all providers
+print(G.count(provider=G.Provider.HIP, visible_only=True)) # only visible HIP devices
+# etc.
+```
+
+Return a list of gpu properties:
+```python
+import gpuq as G
+
+for gpu in G.query(visible_only=True, provider=G.Provider.ANY):
+    print(gpu.name)
+
+# return all visible GPUs, raise an error if no CUDA devices are present
+# (note: the required check if done against the global set, not the return set - see the docs)
+gpus = G.query(visible_only=True, provider=G.Provider.ANY, required=G.Provider.CUDA)
+```
+
+Provide mapping between local and global GPU indices:
+```python
+import gpuq as G
+
+# assume a system with 8 GPUs and CUDA_VISIBLE_DEVICES=1,7
+for gpu in G.query(): # by default return visible GPUs only
+    print(gpu.index, gpu.system_index)
+
+# should print:
+# 0 1
+# 1 7
+
+for gpu in G.query(visible_only=False):
+    print(gpu.index, gpu.system_index, gpu.is_visible)
+
+# should print:
+# None 0 False
+# 0 1 True
+# None 2 False
+# None 3 False
+# None 4 False
+# None 5 False
+# None 6 False
+# 1 7 True
+```

gpuq-1.3.0/gpuq/C.pyi

@@ -0,0 +1,25 @@
+class Properties:
+    ord: int
+    uuid: str
+    provider: str
+    index: int
+    name: str
+    major: int
+    minor: int
+    total_memory: int
+    sms_count: int
+    sm_threads: int
+    sm_shared_memory: int
+    sm_blocks: int
+    block_threads: int
+    block_shared_memory: int
+    warp_size: int
+    l2_cache_size: int
+    concurrent_threads: bool
+    async_engines_count: int
+    cooperative: bool
+
+def checkcuda() -> str: ...
+def checkamd() -> str: ...
+def count() -> int: ...
+def get(index: int) -> Properties: ...

gpuq-1.3.0/gpuq/__init__.py

@@ -0,0 +1,376 @@
+import os
+from threading import local
+from contextlib import contextmanager
+from typing import Generator, Literal
+
+from .datatypes import Provider, Properties
+from .impl import Implementation, GenuineImplementation, MockImplementation
+from .utils import add_module_properties, staticproperty, default, int_or_none, int_list
+
+
+_current_implementation = local()
+_default_impl = None
+
+
+default_impl: Implementation
+
+
+def _get_default_impl() -> Implementation:
+    global _default_impl
+    if _default_impl is not None:
+        return _default_impl
+
+    _impl_name = os.environ.get("MAKO_MOCK_GPU", "").strip().lower()
+    if not _impl_name or _impl_name in ["0", "false", "no", "none"]:
+        _default_impl = genuine()
+    else:
+        _default_impl = mock()
+
+    return _default_impl
+
+
+def _get_impl() -> Implementation:
+    return getattr(_current_implementation, "value", _get_default_impl())
+
+
+def _set_impl(impl: Implementation | None) -> Implementation:
+    current = _get_impl()
+    _current_implementation.value = impl if impl is not None else _get_default_impl()
+    return current
+
+
+@contextmanager
+def _with_impl(impl: Implementation | None) -> Generator[Implementation, None, None]:
+    if impl is None:
+        impl = _get_default_impl()
+    curr = _set_impl(impl)
+    try:
+        yield impl
+    finally:
+        _set_impl(curr)
+
+
+def _global_to_visible(system_index: int, visible: list[int] | None) -> int | None:
+    if visible is None:
+        return system_index
+
+    try:
+        return visible.index(system_index)
+    except ValueError:
+        return None
+
+
+def query(
+    provider: Provider = Provider.any(),
+    required: Provider | None | Literal[True] = None,
+    visible_only: bool = True,
+    impl: Implementation | None = None,
+) -> list[Properties]:
+    """Return a list of all GPUs matching the provided criteria.
+
+    ``provider`` should be a bitwise-or'ed mask of providers whose GPUs should
+    be returned. The values of ``ALL``, ``ANY`` and ``None`` all mean that
+    all providers should be included when returning GPUs.
+
+    ``required`` is another bitwise-or'ed mask of providers that can additionally
+    be used to make the function raise an error (RuntimeError) if GPUs of
+    a particular provider are not present:
+         - ``None`` means nothing is required
+         - ``True`` means that at least one GPU should be returned
+         - ``ANY`` means at least one GPU should be present (but not necessarily returned,
+            see the note below)
+         - `anything else (including ``ALL``) means that at least one GPU of each provider
+            included in the mask has to be present.
+
+    > **Note:** ``required`` and ``provider`` are mostly independent. For example,
+    > a call like ``query(provider=CUDA, required=HIP)`` is valid and will raise an
+    > error if there are no HIP devices but will only return CUDA devices (potentially
+    > an empty list). This means, ``required=ANY`` might be a bit counter-intuitive,
+    > since it will only fail if there are no GPUs whatsoever on the system.
+    > The only exception to this rule is the ``required=True`` case, which
+    > could be understood as "make sure at least one GPU is returned", while
+    > taking into account the provided ``providers`` value.
+
+    If ``visible_only`` is True, any processing of GPU by function (including checking
+    for providers and GPUs as described above) will only consider GPUs that are visible
+    according to the relevant *_VISIBLE_DEVICES environmental variable. Otherwise
+    the variables are ignored and all GPUs are always considered.
+
+    > **Note:** the implementation will temporarily remove any *_VISIBLE_DEVICES variables
+    > when obtaining information about GPUs, regardless of ``visible_only`` argument.
+    > This might cause race conditions if the variables are also used/modified by other
+    > parts of the system at the same time. Please keep this in mind when using it.
+    """
+    nonempty = False
+    if required is True:
+        required = Provider.any()
+        nonempty = True
+
+    if provider == Provider.any() or provider is None:
+        provider = Provider.all()
+
+    if impl is None:
+        impl = _get_impl()
+
+    if required:
+        for p in Provider:
+            if p & required:
+                if err := impl.provider_check(p):
+                    raise RuntimeError(
+                        f"Provider {p.name} is required but the relevant runtime is missing from the system or failed to load, error: {err}!"
+                    )
+
+    with impl.save_visible() as visible:
+        num = impl.c_count()
+
+        if not num:
+            if required is not None or nonempty:
+                raise RuntimeError("No GPUs detected")
+            return []
+
+        ret = []
+
+        for idx in range(num):
+            dev = impl.c_get(idx)
+            prov = Provider[dev.provider]
+
+            visible_set = visible.get(prov)
+            local_index = _global_to_visible(dev.index, visible_set)
+            if visible_only and local_index is None:  # not visible
+                continue
+
+            if required is not None and prov & required:
+                required &= ~prov  # mark the current provider as no longer required
+
+            if provider & prov:
+                ret.append(Properties(dev, local_index, impl))
+
+        if required:
+            missing = [p for p in Provider if p & required]
+            raise RuntimeError(
+                f"GPUs of the following required providers could not be found: {missing}"
+            )
+
+        if not ret and nonempty:
+            raise RuntimeError("No suitable GPUs detected")
+
+        return ret
+
+
+def count(
+    provider: Provider = Provider.all(),
+    visible_only: bool = False,
+    impl: Implementation | None = None,
+) -> int:
+    """Return the overall amount of GPUs for the specified provider (by default all providers).
+
+    ``providers`` can be a bitwise mask of valid providers.
+    if ``visible_only`` is True, return the number of matching GPUs that visible according to
+    *_VISIBLE_DEVICES environment variables. Otherwise the number of all GPUs matching the
+    criteria is returned.
+
+    > **Note:** the implementation will temporarily remove any *_VISIBLE_DEVICES variables
+    > when obtaining information about GPUs, if ``visible_only`` is False.
+    > This might cause race conditions if the variables are also used/modified by other
+    > parts of the system at the same time. Please keep this in mind when using it.
+    """
+    if provider == Provider.any() or provider is None:
+        provider = Provider.all()
+
+    if impl is None:
+        impl = _get_impl()
+
+    if provider == Provider.all():
+        if visible_only:
+            return impl.c_count()
+        else:
+            with impl.save_visible():
+                return impl.c_count()
+    else:
+        return len(
+            query(
+                provider=provider, required=None, visible_only=visible_only, impl=impl
+            )
+        )
+
+
+def get(
+    idx: int,
+    provider: Provider = Provider.all(),
+    visible_only: bool = False,
+    impl: Implementation | None = None,
+) -> Properties:
+    """Return the ``idx``-th GPU from the list of GPus for the specified provider(s).
+    If ``visible_only`` is True, only visible devices according to *_VISIBLE_DEVICES
+    environment variables are considered for indexing (see ``count``).
+
+    > **Note:** the implementation will temporarily remove any *_VISIBLE_DEVICES variables
+    > when obtaining information about GPUs, regardless of ``visible_only`` argument.
+    > This might cause race conditions if the variables are also used/modified by other
+    > parts of the system at the same time. Please keep this in mind when using it.
+    """
+    if provider == Provider.any() or provider is None:
+        provider = Provider.all()
+
+    if impl is None:
+        impl = _get_impl()
+
+    if provider == Provider.all() and not visible_only:
+        with impl.save_visible() as visible:
+            cobj = impl.c_get(idx)
+            prov = Provider[cobj.provider]
+            visible_set = visible.get(prov)
+            local_index = _global_to_visible(cobj.index, visible_set)
+            return Properties(cobj, local_index, impl)
+    else:
+        ret: list[Properties] = query(
+            provider=provider, required=None, visible_only=visible_only, impl=impl
+        )
+        if not ret:
+            raise RuntimeError("No GPUs available")
+        if idx < 0 or idx >= len(ret):
+            raise IndexError("Invalid GPU index")
+
+        return ret[idx]
+
+
+def checkprovider(p: Provider, impl: Implementation | None = None) -> str:
+    """Return error string if a runtime error occurred while checking for
+    the presence of a given provider. Otherwise returns an empty string.
+
+    Runtime errors include any dynamic linker errors or errors
+    originating from a relevant downstream runtime, which occurred
+    while querying the number of available GPUs.
+    """
+    if impl is None:
+        impl = _get_impl()
+    return impl.provider_check(p)
+
+
+def checkcuda(impl: Implementation | None = None) -> str:
+    """Shorthand for `checkprovider(Provider.CUDA)`"""
+    if impl is None:
+        impl = _get_impl()
+    return impl.provider_check(Provider.CUDA)
+
+
+def checkamd(impl: Implementation | None = None) -> str:
+    """Shorthand for `checkprovider(Provider.HIP)`"""
+    if impl is None:
+        impl = _get_impl()
+    return impl.provider_check(Provider.HIP)
+
+
+def hasprovider(p: Provider, impl: Implementation | None = None) -> bool:
+    """Return true if the given provider is available on the system.
+    This does not yet mean that any devices from that provider are present.
+
+    Calling this function is equivalent to checking `checkprovider(p) == ""`
+    """
+    return not checkprovider(p, impl)
+
+
+def hascuda(impl: Implementation | None = None) -> bool:
+    return not checkcuda(impl)
+
+
+def hasamd(impl: Implementation | None = None) -> bool:
+    return not checkamd(impl)
+
+
+def mock(
+    cuda_count: int | None | default = default(1, "MAKO_MOCK_GPU_CUDA", int_or_none),
+    hip_count: int | None | default = default(None, "MAKO_MOCK_GPU_HIP", int_or_none),
+    cuda_visible: list[int] | None | default = default(
+        None, "CUDA_VISIBLE_DEVICES", int_list
+    ),
+    hip_visible: list[int] | None | default = default(
+        None, "HIP_VISIBLE_DEVICES", int_list
+    ),
+    name: str | default = default("{} Mock Device", "MAKO_MOCK_GPU_NAME", str),
+    major: int = 1,
+    minor: int = 2,
+    total_memory: int = 8 * 1024**3,
+    sms_count: int = 12,
+    sm_threads: int = 2048,
+    sm_shared_memory: int = 16 * 1024,
+    sm_registers: int = 512,
+    sm_blocks: int = 4,
+    block_threads: int = 1024,
+    block_shared_memory: int = 8 * 1024,
+    block_registers: int = 256,
+    warp_size: int = 32,
+    l2_cache_size: int = 8 * 1024**2,
+    concurrent_kernels: bool = True,
+    async_engines_count: int = 0,
+    cooperative: bool = True,
+    # cuda runtime args
+    cuda_utilisation: int = 0,
+    cuda_memory: int = 1,
+    cuda_pids: list[int] = [],
+    # hip runtime args
+    hip_gfx: str = "942",
+    hip_drm: int = 128,
+    hip_node_idx: int = 2,
+    hip_pids: list[int] = [],
+    _hip_drm_stride: int = 8,
+) -> Implementation:
+    args = {
+        name: (arg if not isinstance(arg, default) else arg.get())
+        for name, arg in locals().items()
+    }
+    return MockImplementation(**args)
+
+
+def genuine() -> Implementation:
+    return GenuineImplementation()
+
+
+def _get_version() -> str:
+    from . import version
+
+    return version.version
+
+
+def _get_has_repo() -> bool:
+    from . import version
+
+    return version.has_repo
+
+
+def _get_repo() -> str:
+    from . import version
+
+    return version.repo
+
+
+def _get_commit() -> str:
+    from . import version
+
+    return version.commit
+
+
+add_module_properties(
+    __name__,
+    {
+        "__version__": staticproperty(staticmethod(_get_version)),
+        "__has_repo__": staticproperty(staticmethod(_get_has_repo)),
+        "__repo__": staticproperty(staticmethod(_get_repo)),
+        "__commit__": staticproperty(staticmethod(_get_commit)),
+        "default_impl": staticproperty(staticmethod(_get_default_impl)),
+    },
+)
+
+
+__all__ = [
+    "Properties",
+    "Provider",
+    "query",
+    "count",
+    "get",
+    "hasprovider",
+    "hascuda",
+    "hasamd",
+    "mock",
+    "genuine",
+]

gpuq-1.3.0/gpuq/_dist_info.py

@@ -0,0 +1,4 @@
+version = '1.3.0'
+repo = 'git@github.com:a2labs-ai/gpuinfo.git'
+commit = '51e6d202bf9ca60302cc903947addc4b582e93f8'
+has_repo = True