上传文件
  1. base64hub
  2. 文档
  3. Python 包

Python 包参考

PyPI 上的 base64hub 是一个只依赖标准库的模块,适用于 Python 3.9 及更高版本,包含五个函数、一个异常和 b64 命令。

安装

pip install base64hub      # library, inside a virtual environment
pipx install base64hub     # b64 command
from base64hub import encode, decode, validate, data_uri, sniff_mime, Base64Error

这个包附带类型提示(py.typed)。

encode(data, *, url=False, pad=True, wrap=0)

编码字节,或者按 UTF-8 编码 str,返回 str。

参数默认值作用
urlFalseURL 安全字母表(- 和 _)。
padTrue添加 = 填充。
wrap0每 N 个字符后插入 \n,结尾不加;76 对应 MIME。
encode("Hello, hub!")                  # 'SGVsbG8sIGh1YiE='
encode("Привет", url=True, pad=False)  # '0J_RgNC40LLQtdGC'
encode(b"foobar", wrap=4)              # 'Zm9v\nYmFy'
encode(b"\xfb\xff\xbf")                # '+/+/'

decode(text)

把 Base64 解码为 bytes。空格、制表符和换行,data:...;base64, 前缀,缺失的填充,以及两种字母表都接受。无效输入会抛出 Base64Error,它是 ValueError 的子类;遇到有问题的字符时,position 和 char 会说明位置和字符。

decode("SGVsbG8sIGh1YiE")               # b'Hello, hub!'
decode("Zm9v YmFy")                     # b'foobar'
decode("data:text/plain;base64,SGk=")   # b'Hi'

try:
    decode("Zm9v!")
except Base64Error as e:
    print(e, e.position)                # invalid character '!' at position 4 4

由于 Base64Error 就是 ValueError,现有的 except ValueError 代码块照样有效。

validate(text)

检查文本,不抛出异常,每次都返回键相同的字典。

validate("-_-_")
# {'valid': True, 'variant': 'url', 'padded': True, 'bytes': 3, 'error': None}
validate("Zm9v!")["error"]
# "invalid character '!' at position 4"
键含义
valid恰好在 decode 能成功时为 True。
variantstandard、url、mixed 或 either;无效时为 None。
padded清理后的长度(含 =)是 4 的倍数;无效时为 None。
bytes解码后的大小;无效时为 None。
error无效时为原因,否则为 None。

data_uri(data, mime=None) 和 sniff_mime(data)

data_uri 生成 data:<mime>;base64,<payload> 字符串:标准字母表,带填充,从不换行。不传 mime 时,由 sniff_mime 选择类型:PNG、JPEG、GIF、WebP、PDF 和 SVG 按文件签名识别,UTF-8 文本识别为 text/plain;charset=utf-8,其他为 application/octet-stream。

data_uri(b"Hi")                         # 'data:text/plain;charset=utf-8;base64,SGk='
data_uri(b"a,b", mime="text/csv")       # 'data:text/csv;base64,YSxi'
sniff_mime(b"\x89PNG\r\n\x1a\n")        # 'image/png'

b64 命令

pipx install base64hub 会安装 b64。参数、消息和退出码与 CLI 参考 一致。Python 版本会先把全部输入读入内存再处理;非常大的文件请用 Go 版本。

与 base64 模块对比

标准库会拒绝没有填充的输入(binascii.Error: Incorrect padding);除非传入 validate=True,否则会静默丢弃字母表以外的字符;处理 URL 安全的输入还需要另一个函数。base64hub 接受可以安全接受的内容,其余的一律抛出异常。关于标准模块的更多内容,见 Python 中的 Base64。

更新于 2026年11月22日