Enviar um arquivo
  1. base64hub
  2. Docs
  3. Pacote Python

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.

ArgumentoPadrãoEfeito
urlFalseAlfabeto URL-safe (- e _).
padTrueAcrescenta o preenchimento =.
wrap0Insere \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"
ChaveSignificado
validTrue exatamente quando o decode daria certo.
variantstandard, url, mixed ou either; None quando inválido.
paddedO tamanho da entrada limpa, = incluído, é múltiplo de 4; None quando inválido.
bytesTamanho decodificado; None quando inválido.
errorO 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