# aistore.sdk.utils
> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.nvidia.com/aistore/python/aistore/sdk/llms.txt.
> For full documentation content, see https://docs.nvidia.com/aistore/python/aistore/sdk/llms-full.txt.
## Module Contents
### Classes
| Name | Description |
| ------------------------------------------- | ---------------------------------------- |
| [`HttpError`](#aistore-sdk-utils-HttpError) | Represents an error returned by the API. |
### Functions
| Name | Description |
| --------------------------------------------------------------------------- | ------------------------------------------------------------------------------------- |
| [`_check_path_exists`](#aistore-sdk-utils-_check_path_exists) | - |
| [`convert_to_seconds`](#aistore-sdk-utils-convert_to_seconds) | Converts a time value (e.g., '5s', '10m', '2h', '3d', or 10) to seconds. |
| [`decode_response`](#aistore-sdk-utils-decode_response) | Parse response content from the cluster into a Python class, |
| [`expand_braces`](#aistore-sdk-utils-expand_braces) | Given a string template, apply bash-style brace expansion to return a list of strings |
| [`extract_and_parse_url`](#aistore-sdk-utils-extract_and_parse_url) | Extract provider, bucket, and whether an object is present from raw string. |
| [`get_digest`](#aistore-sdk-utils-get_digest) | Get the xxhash digest of a given string. |
| [`get_file_size`](#aistore-sdk-utils-get_file_size) | Get the size of a file and return it in human-readable format |
| [`get_logger`](#aistore-sdk-utils-get_logger) | Create or retrieve a logger with the specified configuration. |
| [`get_provider_from_request`](#aistore-sdk-utils-get_provider_from_request) | Given either a Request or PreparedRequest, return an AIS bucket provider. |
| [`is_read_timeout`](#aistore-sdk-utils-is_read_timeout) | Check if a given ConnectionError was caused by an underlying ReadTimeoutError |
| [`parse_url`](#aistore-sdk-utils-parse_url) | Parse AIS URLs for bucket and object names. |
| [`probing_frequency`](#aistore-sdk-utils-probing_frequency) | Given a timeout, return an interval to wait between retries |
| [`read_file_bytes`](#aistore-sdk-utils-read_file_bytes) | Given a filepath, read the content as bytes |
| [`validate_directory`](#aistore-sdk-utils-validate_directory) | Validate that a directory exists and is a directory |
| [`validate_file`](#aistore-sdk-utils-validate_file) | Validate that a file exists and is a file |
| [`xoshiro256_hash`](#aistore-sdk-utils-xoshiro256_hash) | Xoshiro256-inspired hash function with 64-bit overflow behavior. |
### Data
[`BUCKET_CHARS`](#aistore-sdk-utils-BUCKET_CHARS)
[`CONST1`](#aistore-sdk-utils-CONST1)
[`CONST2`](#aistore-sdk-utils-CONST2)
[`GOLDEN_RATIO`](#aistore-sdk-utils-GOLDEN_RATIO)
[`MASK`](#aistore-sdk-utils-MASK)
[`MAX_BUCKET_PART_LEN`](#aistore-sdk-utils-MAX_BUCKET_PART_LEN)
[`ROTATION_BITS`](#aistore-sdk-utils-ROTATION_BITS)
[`T`](#aistore-sdk-utils-T)
[`URL_PROVIDERS`](#aistore-sdk-utils-URL_PROVIDERS)
### API
```python
class aistore.sdk.utils.HttpError()
```
**Bases:** `BaseModel`
Represents an error returned by the API.
```python
aistore.sdk.utils._check_path_exists(
path: pathlib.Path
) -> None
```
```python
aistore.sdk.utils.convert_to_seconds(
time_val: typing.Union[str, int]
) -> int
```
Converts a time value (e.g., '5s', '10m', '2h', '3d', or 10) to seconds.
If no unit is provided (e.g., '10' or 10), seconds are assumed.
**Parameters:**
The time value to convert.
**Returns:** `int`
The equivalent time in seconds.
**Raises:**
* `ValueError`: If the format or unit is invalid.
```python
aistore.sdk.utils.decode_response(
res_model: typing.Type[aistore.sdk.utils.T],
resp: requests.Response
) -> aistore.sdk.utils.T
```
Parse response content from the cluster into a Python class,
decoding with msgpack depending on content type in header
**Parameters:**
Resulting type to which the response should be deserialized
Response from the AIS cluster
```python
aistore.sdk.utils.expand_braces(
template: str
) -> typing.Iterator[str]
```
Given a string template, apply bash-style brace expansion to return a list of strings
Args:
template: Valid brace expansion input, e.g. prefix-\{0..10..2}-gap-\{11..15}-suffix
**Returns:** `Iterator[str]`
Iterator of brace expansion output
```python
aistore.sdk.utils.extract_and_parse_url(
msg: str
) -> typing.Optional[typing.Tuple[str, str, bool]]
```
Extract provider, bucket, and whether an object is present from raw string.
**Parameters:**
Any string that may contain an AIS FQN.
**Returns:** `Optional[Tuple[str, str, bool]]`
Optional\[Tuple\[str, str, bool]]: (prov, bck, has\_obj) if a FQN is found, otherwise None.
```python
aistore.sdk.utils.get_digest(
name: str
) -> int
```
Get the xxhash digest of a given string.
```python
aistore.sdk.utils.get_file_size(
file: pathlib.Path
) -> str
```
Get the size of a file and return it in human-readable format
Args:
file: File to read
**Returns:** `str`
Size of file as human-readable string
```python
aistore.sdk.utils.get_logger(
name: str,
log_format: str = DEFAULT_LOG_FORMAT
)
```
Create or retrieve a logger with the specified configuration.
**Parameters:**
The name of the logger.
Logging format.
**Returns:**
logging.Logger: Configured logger instance.
```python
aistore.sdk.utils.get_provider_from_request(
req: typing.Union[requests.Request, requests.PreparedRequest]
) -> aistore.sdk.provider.Provider
```
Given either a Request or PreparedRequest, return an AIS bucket provider.
The request property of a `requests.RequestException` can be either of these types,
so this can be used to find the bucket provider involved in the initial request.
**Parameters:**
Any request or prepared request.
**Returns:** `Provider`
Parsed AIS bucket Provider Enum.
```python
aistore.sdk.utils.is_read_timeout(
exc: requests.ConnectionError
) -> bool
```
Check if a given ConnectionError was caused by an underlying ReadTimeoutError
Args:
exc: Any requests.ConnectionError.
Returns: If ReadTimeoutError cause the exception.
```python
aistore.sdk.utils.parse_url(
url: str
) -> typing.Tuple[str, str, str]
```
Parse AIS URLs for bucket and object names.
**Parameters:**
Complete URL of the object (e.g., "ais\://bucket1/file.txt")
**Returns:** `Tuple[str, str, str]`
Tuple\[str, str, str]: Provider, bucket name, and object name
```python
aistore.sdk.utils.probing_frequency(
dur: int
) -> float
```
Given a timeout, return an interval to wait between retries
**Parameters:**
Duration of timeout
**Returns:** `float`
Frequency to probe
```python
aistore.sdk.utils.read_file_bytes(
filepath: str
) -> bytes
```
Given a filepath, read the content as bytes
Args:
filepath: Existing local filepath
Returns: Raw bytes
```python
aistore.sdk.utils.validate_directory(
path: typing.Union[str, pathlib.Path]
) -> None
```
Validate that a directory exists and is a directory
Args:
path (str or Path): Path to validate
Raises:
ValueError: If path does not exist or is not a directory
```python
aistore.sdk.utils.validate_file(
path: typing.Union[str, pathlib.Path]
) -> None
```
Validate that a file exists and is a file
Args:
path (str or Path): Path to validate
Raises:
ValueError: If path does not exist or is not a file
```python
aistore.sdk.utils.xoshiro256_hash(
seed: int
) -> int
```
Xoshiro256-inspired hash function with 64-bit overflow behavior.
```python
aistore.sdk.utils.BUCKET_CHARS = '[A-Za-z0-9@#._-]'
```
```python
aistore.sdk.utils.CONST1 = 13787848793156543929
```
```python
aistore.sdk.utils.CONST2 = 10723151780598845931
```
```python
aistore.sdk.utils.GOLDEN_RATIO = 11400714819323198485
```
```python
aistore.sdk.utils.MASK = 18446744073709551615
```
```python
aistore.sdk.utils.MAX_BUCKET_PART_LEN = 132
```
```python
aistore.sdk.utils.ROTATION_BITS = 7
```
```python
aistore.sdk.utils.T = TypeVar('T')
```
```python
aistore.sdk.utils.URL_PROVIDERS = '|'.join([(p.value) for p in Provider] + list(provider_aliases))
```