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。
| 参数 | 默认值 | 作用 |
|---|---|---|
url | False | URL 安全字母表(- 和 _)。 |
pad | True | 添加 = 填充。 |
wrap | 0 | 每 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。 |
variant | standard、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日