Skip to content
Reference of plugins_api 2.0.1, an older major version. See this page for plugins_api 3.0.0.

plugins_api.utils.format_utils

Format and conversion utilities for plugins_api.

Functions

NameDescription
extract_file_extensionDerive a normalized file extension from a filename or path.
is_file_extension_supportedReturn whether file_extension is allowed by supported_extensions.
normalize_file_extensionNormalize a stored or declared file extension.
size_to_bytesConvert a size value with unit to bytes.

extract_file_extensionfunction#

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

NameTypeDescription
filenamestr or NoneFile 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

>>> 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

is_file_extension_supportedfunction#

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

NameTypeDescription
file_extensionstr or NoneExtension stored on a data object.
supported_extensionslist[str] | tuple[str, ...] | set[str]Plugin-declared supported extensions. Empty means unrestricted.

Returns

bool
True if the extension is accepted.

normalize_file_extensionfunction#

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

NameTypeDescription
extensionstr or NoneRaw extension (e.g. ".FASTQ", "fastq.gz", "").

Returns

str or None
Normalized extension without a leading dot, or None if missing.

size_to_bytesfunction#

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

Convert a size value with unit to bytes.

Parameters

NameTypeDefaultDescription
sizefloatrequiredThe size value to convert.
unitstr'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:

>>> size_to_bytes(100, "MB")
100000000
>>> size_to_bytes(50, "GB")
50000000000

Binary (IEC) conversion:

>>> size_to_bytes(1024, "KiB")
1048576
>>> size_to_bytes(100, "MiB")
104857600
>>> size_to_bytes(50, "GiB")
53687091200