hbutils.encoding.base64

Base64 encoding and decoding utilities.

This module provides lightweight wrapper functions around Python’s base64 library for encoding binary data to base64 strings and decoding base64 strings back into bytes. Both standard and URL-safe base64 formats are supported, with optional alternative character mappings.

The module contains the following public functions:

• base64_encode() - Encode binary data into a base64 string.

• base64_decode() - Decode a base64 string into binary data.

Note

When urlsafe=True is used, any value provided in altchars is ignored and a UserWarning is emitted to signal this behavior.

Example:

>>> from hbutils.encoding.base64 import base64_encode, base64_decode
>>> encoded = base64_encode(b'hello world')
>>> encoded
'aGVsbG8gd29ybGQ='
>>> base64_decode(encoded)
b'hello world'
>>> base64_encode(b'hello world', urlsafe=True)
'aGVsbG8gd29ybGQ='

__all__

hbutils.encoding.base64.__all__ = ['base64_encode', 'base64_decode']

Built-in mutable sequence.

If no argument is given, the constructor creates a new empty list. The argument must be an iterable if specified.

base64_encode

hbutils.encoding.base64.base64_encode(data: bytes, altchars: bytes | None = None, urlsafe: bool = False) → str

Encoding the given binary data to base64 string.

This function encodes binary data into a base64-encoded string. It supports both standard base64 encoding and URL-safe base64 encoding. When URL-safe mode is enabled, the characters ‘+’ and ‘/’ in standard base64 are replaced with ‘-’ and ‘_’ respectively.

Parameters:

• data (bytes) – Binary data to be encoded.

• altchars (Optional[bytes]) – Characters to be altered in standard base64 encoding. This parameter is ignored when urlsafe is True. Default is None.

• urlsafe (bool) – Enable URL-safe mode. When True, uses URL-safe base64 encoding which replaces ‘+’ with ‘-’ and ‘/’ with ‘_’. Default is False.

Returns:

Base64-encoded string representation of the input data.

Return type:

str

Raises:

UserWarning – When both urlsafe is True and altchars is provided, a warning is issued indicating that altchars will be ignored.

Examples:

>>> base64_encode(b'jvMIQ?K;]kNn2?1KD5H>')
'anZNSVE/Sztda05uMj8xS0Q1SD4='
>>> base64_encode(b'jvMIQ?K;]kNn2?1KD5H>', urlsafe=True)
'anZNSVE_Sztda05uMj8xS0Q1SD4='

base64_decode

hbutils.encoding.base64.base64_decode(base64_str: str, altchars: bytes | None = None, urlsafe: bool = False) → bytes

Decode the given base64 string back to binary data.

This function decodes a base64-encoded string back into its original binary form. It supports both standard base64 decoding and URL-safe base64 decoding. When URL-safe mode is enabled, it properly handles the URL-safe characters ‘-’ and ‘_’ used in place of ‘+’ and ‘/’.

Parameters:

• base64_str (str) – Base64-encoded string to be decoded.

• altchars (Optional[bytes]) – Characters to be altered in standard base64 decoding. This parameter is ignored when urlsafe is True. Default is None.

• urlsafe (bool) – Enable URL-safe mode. When True, uses URL-safe base64 decoding which handles ‘-’ and ‘_’ characters. Default is False.

Returns:

Decoded binary data from the base64 string.

Return type:

bytes

Raises:

UserWarning – When both urlsafe is True and altchars is provided, a warning is issued indicating that altchars will be ignored.

Examples:

>>> base64_decode('anZNSVE/Sztda05uMj8xS0Q1SD4=')
b'jvMIQ?K;]kNn2?1KD5H>'
>>> base64_decode('anZNSVE_Sztda05uMj8xS0Q1SD4=', urlsafe=True)
b'jvMIQ?K;]kNn2?1KD5H>'