GitHub

API reference for base64.

Base64 with the standard alphabet and padding (Effect's encoding/Base64). encode takes bytes or text (encoded as UTF-8); decode ignores CR and LF and returns a Result::

base64.encode("hello")          # "aGVsbG8="
base64.decode("aGVsbG8=")       # Ok(b"hello")
base64.decode_string("8J+Riw==")  # Ok("👋")

encode_unpadded leaves the = padding out, and decode_lenient reads either alphabet, padded or not (protobuf's JSON bytes, Connect)::

base64.encode_unpadded("hello")  # "aGVsbG8"
base64.decode_lenient("-_8")     # Ok(b"ûÿ")

Types

TypeDefinitionDescription
Binarytype Binary = bytes | bytearray | memoryview | str

Functions

decode_string

decode_string(text) -> Result[str, EncodingError]

decode, then the bytes as UTF-8 (bad bytes replaced, a leading U+FEFF kept).

ParameterTypeDescription
textstr

Returns Result[str, EncodingError]

def decode_string(text: str) -> Result[str, EncodingError]:
    """``decode``, then the bytes as UTF-8 (bad bytes replaced, a leading U+FEFF kept)."""
    return decoded_text(decode(text))

base64_decode

base64_decode(text) -> Result[bytes, EncodingError]

CR and LF are ignored; the length must be a multiple of 4 and = only ends it.

ParameterTypeDescription
textstr

Returns Result[bytes, EncodingError]

def base64_decode(text: str) -> Result[bytes, EncodingError]:
    """CR and LF are ignored; the length must be a multiple of 4 and ``=``
    only ends it."""
    stripped = _strip_crlf(text)
    length = len(stripped)
    if length % 4:
        return _fail("Base64", stripped, f"Length must be a multiple of 4, but is {length}")
    index = stripped.find("=")
    if index != -1 and (index < length - 2 or (index == length - 2 and stripped[-1] != "=")):
        return _fail("Base64", stripped, "Found a '=' character, but it is not at the end")
    if not _BASE64_CHARS.fullmatch(stripped):
        bad = next(c for c in stripped if not _BASE64_CHAR.fullmatch(c))
        return _fail("Base64", stripped, f"Invalid character {bad}")
    return Ok(binascii.a2b_base64(stripped))

base64_decode_lenient

base64_decode_lenient(text) -> Result[bytes, EncodingError]

Either alphabet, padded or not; CR and LF are ignored, other whitespace is rejected. One input uses one alphabet; a failure names Base64 and holds text as given.

ParameterTypeDescription
textstr

Returns Result[bytes, EncodingError]

def base64_decode_lenient(text: str) -> Result[bytes, EncodingError]:
    """Either alphabet, padded or not; CR and LF are ignored, other whitespace is
    rejected. One input uses one alphabet; a failure names ``Base64`` and holds
    ``text`` as given."""
    if "-" in text or "_" in text:
        decoded = base64_url_decode(text)
    else:
        decoded = base64_decode(_add_padding(_strip_crlf(text)))
    return decoded.map_error(
        lambda error: EncodingError(
            kind="Decode", module="Base64", input=text, message=error.message
        )
    )

base64_encode

base64_encode(value) -> str
ParameterTypeDescription
valueBinary

Returns str

def base64_encode(value: Binary) -> str:
    return base64.b64encode(_bytes(value)).decode("ascii")

base64_encode_unpadded

base64_encode_unpadded(value) -> str

encode without the = padding.

ParameterTypeDescription
valueBinary

Returns str

def base64_encode_unpadded(value: Binary) -> str:
    """``encode`` without the ``=`` padding."""
    return base64_encode(value).rstrip("=")