Referencia del paquete de Python
base64hub en PyPI es un módulo para Python 3.9 y posteriores que solo usa la biblioteca estándar, con cinco funciones, una excepción y el comando b64.
Instalación
pip install base64hub # library, inside a virtual environment
pipx install base64hub # b64 command
from base64hub import encode, decode, validate, data_uri, sniff_mime, Base64Error
El paquete incluye anotaciones de tipos (py.typed).
encode(data, *, url=False, pad=True, wrap=0)
Codifica bytes, o un str como UTF-8, y devuelve un str.
| Argumento | Por defecto | Efecto |
|---|---|---|
url | False | Alfabeto URL-safe (- y _). |
pad | True | Añade el relleno =. |
wrap | 0 | Inserta \n cada N caracteres, ninguno al final; 76 es 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 a bytes. Acepta espacios, tabuladores y saltos de línea, un prefijo data:...;base64,, la falta de relleno y los dos alfabetos. Una entrada no válida lanza Base64Error, una subclase de ValueError; si el problema es un carácter incorrecto, position y char dicen dónde está y cuál es.
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 es un ValueError, los bloques except ValueError que ya tengas siguen funcionando.
validate(text)
Comprueba un texto sin lanzar excepciones y devuelve siempre un dict con las mismas claves.
validate("-_-_")
# {'valid': True, 'variant': 'url', 'padded': True, 'bytes': 3, 'error': None}
validate("Zm9v!")["error"]
# "invalid character '!' at position 4"
| Clave | Significado |
|---|---|
valid | True exactamente cuando decode tendría éxito. |
variant | standard, url, mixed o either; None si no es válido. |
padded | La longitud limpia, = incluidos, es múltiplo de 4; None si no es válido. |
bytes | Tamaño decodificado; None si no es válido. |
error | El motivo si no es válido; si no, None. |
data_uri(data, mime=None) y sniff_mime(data)
data_uri construye una cadena data:<mime>;base64,<payload>, con alfabeto estándar, con relleno y sin cortes de línea. Sin mime, sniff_mime elige el tipo: PNG, JPEG, GIF, WebP, PDF y SVG por su firma, text/plain;charset=utf-8 para texto UTF-8 y, si no, 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'
El comando b64
pipx install base64hub instala b64. Las opciones, los mensajes y los códigos de salida coinciden con la referencia de la CLI. La versión de Python lee toda la entrada en memoria antes de procesarla; para archivos muy grandes usa la versión de Go.
Comparado con el módulo base64
La biblioteca estándar rechaza la entrada sin relleno (binascii.Error: Incorrect padding), descarta sin avisar los caracteres fuera del alfabeto salvo que pases validate=True y necesita una función aparte para la entrada URL-safe. base64hub acepta lo que es seguro aceptar y lanza una excepción con el resto. Más sobre el módulo estándar en Base64 en Python.
Actualizado 22 nov 2026