# plugins_api.utils.format_utils

*module*

Format and conversion utilities for plugins_api.

[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/plugins-api-v2.0.1/plugin_api/plugins_api/utils/format_utils.py#L1-1)

## plugins_api.utils.format_utils.extract_file_extension

*function*

```python
def extract_file_extension(filename: str | None) -> str | None
```

Derive a normalized file extension from a filename or path.

Uses the basename only. When the final segment is a known compression
suffix (``gz``, ``bz2``, ``xz``, ``zst``, ``zip``, ``z``) and a preceding
segment exists, returns a compound extension (e.g. ``fastq.gz``).

**Parameters**

- `filename` (`str or None`) — File name or path (e.g. ``"/data/sample.fastq.gz"``).

**Returns**

- (`str or None`) — Extension without a leading dot, or ``None`` when none can be derived.

**Examples**

```pycon
>>> extract_file_extension("sample.fastq.gz")
'fastq.gz'
>>> extract_file_extension("reads.fq")
'fq'
>>> extract_file_extension("archive.tar.gz")
'tar.gz'
>>> extract_file_extension("README")
None
```

[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/plugins-api-v2.0.1/plugin_api/plugins_api/utils/format_utils.py#L32-73)

## plugins_api.utils.format_utils.is_file_extension_supported

*function*

```python
def is_file_extension_supported(file_extension: str | None, supported_extensions: list[str] | tuple[str, ...] | set[str]) -> bool
```

Return whether ``file_extension`` is allowed by ``supported_extensions``.

An empty ``supported_extensions`` list means all extensions are allowed.
Missing / blank ``file_extension`` is never allowed when the list is
non-empty. Comparison is case-insensitive and ignores a leading dot.

**Parameters**

- `file_extension` (`str or None`) — Extension stored on a data object.
- `supported_extensions` (`list[str] | tuple[str, ...] | set[str]`) — Plugin-declared supported extensions. Empty means unrestricted.

**Returns**

- (`bool`) — ``True`` if the extension is accepted.

[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/plugins-api-v2.0.1/plugin_api/plugins_api/utils/format_utils.py#L76-110)

## plugins_api.utils.format_utils.normalize_file_extension

*function*

```python
def normalize_file_extension(extension: str | None) -> str | None
```

Normalize a stored or declared file extension.

Strips whitespace and a leading dot, lowercases the value, and maps empty
results to ``None``. Compound extensions such as ``fastq.gz`` are preserved.

**Parameters**

- `extension` (`str or None`) — Raw extension (e.g. ``".FASTQ"``, ``"fastq.gz"``, ``""``).

**Returns**

- (`str or None`) — Normalized extension without a leading dot, or ``None`` if missing.

[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/plugins-api-v2.0.1/plugin_api/plugins_api/utils/format_utils.py#L9-29)

## plugins_api.utils.format_utils.size_to_bytes

*function*

```python
def size_to_bytes(size: float, unit: str = 'bytes') -> int
```

Convert a size value with unit to bytes.

**Parameters**

- `size` (`float`) — The size value to convert.
- `unit` (`str`) (default: `'bytes'`) — The unit of the size. Must be one of: - SI (decimal) units: 'bytes', 'KB', 'MB', 'GB', 'TB' - Binary (IEC) units: 'KiB', 'MiB', 'GiB', 'TiB' Case-insensitive. Default is 'bytes'.

**Returns**

- (`int`) — The size in bytes.

**Raises**

- `ValueError` — If an invalid unit is provided.

**Examples**

Decimal (SI) conversion:

```pycon
>>> size_to_bytes(100, "MB")
100000000
```

```pycon
>>> size_to_bytes(50, "GB")
50000000000
```

Binary (IEC) conversion:

```pycon
>>> size_to_bytes(1024, "KiB")
1048576
```

```pycon
>>> size_to_bytes(100, "MiB")
104857600
```

```pycon
>>> size_to_bytes(50, "GiB")
53687091200
```

> **Notes**
>
> **Decimal (SI) conversion** (using KB, MB, GB, TB):
> - 1 KB = 1000 bytes
> - 1 MB = 1000 KB = 1,000,000 bytes
> - 1 GB = 1000 MB = 1,000,000,000 bytes
> - 1 TB = 1000 GB = 1,000,000,000,000 bytes
> 
> **Binary (IEC) conversion** (using KiB, MiB, GiB, TiB):
> - 1 KiB = 1024 bytes
> - 1 MiB = 1024 KiB = 1,048,576 bytes
> - 1 GiB = 1024 MiB = 1,073,741,824 bytes
> - 1 TiB = 1024 GiB = 1,099,511,627,776 bytes
> 
> Most APIs and cloud storage services use decimal (SI) conversion.
> Use binary (IEC) units when working with system-level file sizes.

[View source](https://gitlab.com/ifb-elixirfr/madbot/madbot/-/blob/plugins-api-v2.0.1/plugin_api/plugins_api/utils/format_utils.py#L113-195)
