- base64hub
- Документация
- Пакет для Python
Справочник по пакету для Python
base64hub в PyPI – модуль для 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)
Кодирует байты или str как UTF-8 и возвращает str.
| Аргумент | По умолчанию | Действие |
|---|---|---|
url | False | URL-safe алфавит (- и _). |
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 | True ровно тогда, когда decode выполнился бы успешно. |
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 по сигнатуре, text/plain;charset=utf-8 для текста 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-safe данных. base64hub принимает то, что безопасно принять, и выбрасывает исключение на всём остальном. Подробнее о стандартном модуле рассказано в статье Base64 в Python.
Обновлено 22 нояб. 2026 г.