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)
bytes, 또는 UTF-8로 변환한 str을 인코딩해 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, 접두사, 빠진 패딩, 두 알파벳 모두 받아들입니다. 잘못된 입력에는 ValueError의 하위 클래스인 Base64Error를 발생시키며, 잘못된 문자일 때는 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)
예외를 발생시키지 않고 텍스트를 검사하며, 항상 같은 키를 가진 dict를 반환합니다.
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-safe 입력에는 별도의 함수가 필요합니다. base64hub는 받아들여도 안전한 것은 받아들이고 나머지에는 예외를 발생시킵니다. 표준 모듈은 Python에서 Base64 사용하기에서 더 자세히 다룹니다.
업데이트 2026. 11. 22.