"""
Base64 encoding and decoding utilities.
This module provides lightweight wrapper functions around Python's
:mod:`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:
* :func:`base64_encode` - Encode binary data into a base64 string.
* :func:`base64_decode` - Decode a base64 string into binary data.
.. note::
When ``urlsafe=True`` is used, any value provided in ``altchars`` is
ignored and a :class:`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='
"""
import base64
import warnings
from typing import Optional
__all__ = [
'base64_encode', 'base64_decode',
]
[docs]
def base64_encode(data: bytes, altchars: Optional[bytes] = None, urlsafe: bool = False) -> str:
r"""
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.
:param data: Binary data to be encoded.
:type data: bytes
:param altchars: Characters to be altered in standard base64 encoding. This parameter is
ignored when ``urlsafe`` is ``True``. Default is ``None``.
:type altchars: Optional[bytes]
:param urlsafe: Enable URL-safe mode. When ``True``, uses URL-safe base64 encoding which
replaces '+' with '-' and '/' with '_'. Default is ``False``.
:type urlsafe: bool
:return: Base64-encoded string representation of the input data.
:rtype: 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='
"""
if urlsafe and altchars:
warnings.warn(UserWarning('Urlsafe enabled in base64_encode, '
'value altchars argument will be ignored.'), stacklevel=2)
if urlsafe:
return base64.urlsafe_b64encode(data).decode()
else:
return base64.b64encode(data, altchars).decode()
[docs]
def base64_decode(base64_str: str, altchars: Optional[bytes] = None, urlsafe: bool = False) -> bytes:
r"""
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 '/'.
:param base64_str: Base64-encoded string to be decoded.
:type base64_str: str
:param altchars: Characters to be altered in standard base64 decoding. This parameter is
ignored when ``urlsafe`` is ``True``. Default is ``None``.
:type altchars: Optional[bytes]
:param urlsafe: Enable URL-safe mode. When ``True``, uses URL-safe base64 decoding which
handles '-' and '_' characters. Default is ``False``.
:type urlsafe: bool
:return: Decoded binary data from the base64 string.
:rtype: 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>'
"""
if urlsafe and altchars:
warnings.warn(UserWarning('Urlsafe enabled in base64_decode, '
'value altchars argument will be ignored.'), stacklevel=2)
if urlsafe:
return base64.urlsafe_b64decode(base64_str)
else:
return base64.b64decode(base64_str, altchars)