# general

Python API: `modelconverter.utils.general`

General-purpose helpers shared across modelconverter.

Holds the small utilities that fit nowhere more specific: sanitizing model names into something the conversion tools accept, and
formatting or parsing the byte sizes used to report on and bound the disk cache.

## Functions

### dir_stats

```python
def dir_stats(path: Path) -> tuple[int, int]:
```

Return the total size (bytes) and number of files under `path`.

Entries that cannot be stat'ed are skipped: a container run killed before its entrypoint could chown the mounts back leaves
root-owned files behind, and neither reporting on the cache nor keeping it within its budget must be what breaks.

### human_size

```python
def human_size(num: float) -> str:
```

Format a number of bytes for display.

> **Example**
> ```pycon
>>> human_size(1536)
'1.5 KiB'
>>> human_size(5 * 1024**3)
'5.0 GiB'
```

Parameters

 * `num` (`float`): Size in bytes.

Returns

 * `str`: The size with one decimal place and a binary unit, such as `"1.5 GiB"`.

### parse_size

```python
def parse_size(value: str | int) -> int:
```

Parse a human-written byte size such as `"50GiB"` into bytes.

The unit is optional and its prefixes are binary, matching [human_size](https://docs.luxonis.com/software-v3/ai-inference/conversion/rvc-conversion/offline/modelconverter/modelconverter-api-reference/utils/general.md) on the way out and Docker's own byte values on the way in: `50G`, `50GB` and `50GiB` all mean the same 50 * 1024^3 bytes, and a bare number is a count of bytes.

> **Example**
> ```pycon
>>> parse_size("50GiB")
53687091200
>>> parse_size("50GB")
53687091200
>>> parse_size("512m")
536870912
>>> parse_size(1024)
1024
```

Parameters

 * `value` (`str | int`): Size to parse. An integer is returned unchanged.

Returns

 * `int`: The size in bytes.

Raises

 * `ValueError`: If `value` is not a size.

### sanitize_net_name

```python
def sanitize_net_name(name: str, with_suffix: bool = False) -> str:
```

Sanitize net name or path.

If input is a path, only sanitize the basename. If input is a name, sanitize the whole string. Collapse multiple underscores.

> **Example**
> ```pycon
>>> sanitize_net_name("my model!.onnx")
'my_model_onnx'
>>> sanitize_net_name("my model!.onnx", with_suffix=True)
'my_model_.onnx'
>>> sanitize_net_name("a/b/my model!.onnx")
'a/b/my_model_onnx'
```

Parameters

 * `name` (`str`): The name or path to sanitize.
 * `with_suffix` (`bool`): If `True`, the suffix (file extension) is preserved and not sanitized.

Returns

 * `str`: The sanitized name or path.