Utils Module

Memory conversion utility functions for arraybridge.

This module provides utility functions for memory conversion operations, supporting Clause 251 (Declarative Memory Conversion Interface) and Clause 65 (Fail Loudly).

optional_import(module_name)[source]

Import a module if available, otherwise return a placeholder that handles attribute access gracefully for type annotations but fails on actual use.

This function allows for graceful handling of optional dependencies. It can be used to import libraries that may not be installed, particularly GPU-related libraries like torch, tensorflow, and cupy.

Parameters:: module_name (str) – Name of the module to import
Return type:: Optional[Any]
Returns:: The imported module if available, a placeholder otherwise

Example

```python # Import torch if available torch = optional_import(“torch”)

# Check if torch is available before using it if torch:

# Use torch tensor = torch.tensor([1, 2, 3])

else:: # Handle the case where torch is not available raise ImportError(“PyTorch is required for this function”)

```

Utility Functions

Module Import

optional_import(module_name)[source]

Import a module if available, otherwise return a placeholder that handles attribute access gracefully for type annotations but fails on actual use.

This function allows for graceful handling of optional dependencies. It can be used to import libraries that may not be installed, particularly GPU-related libraries like torch, tensorflow, and cupy.

Parameters:: module_name (str) – Name of the module to import
Return type:: Optional[Any]
Returns:: The imported module if available, a placeholder otherwise

Example

```python # Import torch if available torch = optional_import(“torch”)

# Check if torch is available before using it if torch:

# Use torch tensor = torch.tensor([1, 2, 3])

else:: # Handle the case where torch is not available raise ImportError(“PyTorch is required for this function”)

```

Support Checks

_supports_cuda_array_interface(obj)[source]

Check if an object supports the CUDA Array Interface.

Parameters:: obj (Any) – The object to check
Return type:: bool
Returns:: True if the object supports the CUDA Array Interface, False otherwise

_supports_dlpack(obj)[source]

Check if an object supports DLPack.

Parameters:: obj (Any) – The object to check
Return type:: bool
Returns:: True if the object supports DLPack, False otherwise

Note

For TensorFlow tensors, this function enforces Clause 88 (No Inferred Capabilities) by explicitly checking: 1. TensorFlow version must be 2.12+ for stable DLPack support 2. Tensor must be on GPU (CPU tensors might succeed even without proper DLPack support) 3. tf.experimental.dlpack module must exist

Module Management

_ensure_module(module_name)[source]

Ensure a module is imported and meets version requirements.

Parameters:

module_name (str) – The name of the module to import

Return type:

Any

Returns:

The imported module

Raises:

ImportError – If the module cannot be imported or does not meet version requirements
RuntimeError – If the module has known issues with specific versions

Helper Classes

ModulePlaceholder

class _ModulePlaceholder(module_name)[source]

Placeholder for missing optional modules that allows attribute access for type annotations while still being falsy and failing on actual use.

__init__(module_name)[source]

Examples

Optional Imports

from arraybridge.utils import optional_import

# Import with graceful fallback
torch = optional_import('torch')

if torch:
    # PyTorch is available
    tensor = torch.tensor([1, 2, 3])
else:
    # PyTorch not available
    print("PyTorch not installed")

Checking Framework Support

from arraybridge.utils import _supports_dlpack
import numpy as np

data = np.array([1, 2, 3])
if _supports_dlpack(data):
    print("DLPack conversion available")
else:
    print("Using fallback conversion")