Referência do pacote Python
O base64hub no PyPI é um módulo só com a biblioteca padrão, para Python 3.9 ou mais novo, com cinco funções, uma exceção e o comando b64.
Instalação
pip install base64hub # library, inside a virtual environment
pipx install base64hub # b64 command
from base64hub import encode, decode, validate, data_uri, sniff_mime, Base64Error
O pacote inclui type hints (py.typed).
encode(data, *, url=False, pad=True, wrap=0)
Codifica bytes, ou uma str como UTF-8, e retorna uma str.
| Argumento | Padrão | Efeito |
|---|---|---|
url | False | Alfabeto URL-safe (- e _). |
pad | True | Acrescenta o preenchimento =. |
wrap | 0 | Insere \n a cada N caracteres, nenhum no final; 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)
Decodifica Base64 para bytes. Espaços, tabulações e quebras de linha, um prefixo data:...;base64,, preenchimento ausente e os dois alfabetos são aceitos. Uma entrada inválida lança Base64Error, uma subclasse de ValueError; no caso de um caractere inválido, position e char dizem onde e qual.
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
Como Base64Error é um ValueError, os blocos except ValueError que você já tem continuam funcionando.
validate(text)
Confere o texto sem lançar exceção e sempre retorna um dict com as mesmas chaves.
validate("-_-_")
# {'valid': True, 'variant': 'url', 'padded': True, 'bytes': 3, 'error': None}
validate("Zm9v!")["error"]
# "invalid character '!' at position 4"
| Chave | Significado |
|---|---|
valid | True exatamente quando o decode daria certo. |
variant | standard, url, mixed ou either; None quando inválido. |
padded | O tamanho da entrada limpa, = incluído, é múltiplo de 4; None quando inválido. |
bytes | Tamanho decodificado; None quando inválido. |
error | O motivo quando inválido; None nos outros casos. |
data_uri(data, mime=None) e sniff_mime(data)
O data_uri monta uma string data:<mime>;base64,<payload>, com alfabeto padrão, com preenchimento e nunca quebrada. Sem mime, o sniff_mime escolhe o tipo: PNG, JPEG, GIF, WebP, PDF e SVG pela assinatura, text/plain;charset=utf-8 para texto UTF-8, e application/octet-stream nos outros casos.
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'
O comando b64
pipx install base64hub instala o b64. As flags, mensagens e códigos de saída são os da referência da CLI. A versão em Python lê a entrada inteira para a memória antes de processá-la; para arquivos muito grandes, use a versão em Go.
Comparado com o módulo base64
A biblioteca padrão rejeita entradas sem preenchimento (binascii.Error: Incorrect padding), descarta em silêncio os caracteres fora do alfabeto, a menos que você passe validate=True, e precisa de uma função separada para entradas URL-safe. O base64hub aceita o que é seguro aceitar e lança exceção para o resto. Mais sobre o módulo padrão em Base64 em Python.
Atualizado 22 de nov. de 2026