Python

binascii — 바이너리와 ASCII 간의 변환


binascii 모듈에는 바이너리와 다양한 ASCII 인코딩된 바이너리 표현 사이를 변환하는 여러 방법이 포함되어 있습니다. 일반적으로 이러한 함수들을 직접 사용하지 않고, 대신 base64`와 같은 래퍼(wrapper) 모듈을 사용합니다. :mod:!binascii` 모듈은 더 높은 성능을 위해 C로 작성된 저수준 함수들을 포함하며, 이는 고수준 모듈에서 활용됩니다.

참고

a2b_* 함수는 ASCII 문자만 포함하는 유니코드 문자열을 받아들입니다. 다른 함수는 바이트열류 객체(가령 bytes, bytearray 및 버퍼 프로토콜을 지원하는 다른 객체)만 받아들입니다.

버전 3.3에서 변경: ASCII로만 이루어진 유니코드 문자열은 이제 a2b_* 함수에서 허용됩니다.

binascii 모듈은 다음 함수들을 정의합니다.

binascii.a2b_uu(string)

한 줄의 UU 인코딩된 데이터 string을 바이너리로 역변환하고 바이너리 데이터를 반환합니다. 마지막 줄을 제외하고는, 줄은 보통 45 (바이너리) 바이트를 포함합니다. 줄 데이터 뒤에는 공백 문자가 올 수 있습니다.

binascii.b2a_uu(data, *, backtick=False)

바이너리 data를 ASCII 문자의 줄로 변환합니다, 반환 값은 개행 문자를 포함하는 변환 된 줄입니다. data의 길이는 최대 45이어야 합니다. backtick가 참이면, 0은 스페이스 대신 '`'으로 표현됩니다.

버전 3.7에서 변경: backtick 매개 변수가 추가되었습니다.

binascii.a2b_base64(string, /, *, padded=True, alphabet=BASE64_ALPHABET, strict_mode=False, canonical=False)
binascii.a2b_base64(string, /, *, ignorechars, padded=True, alphabet=BASE64_ALPHABET, strict_mode=True, canonical=False)

base64 데이터 블록을 바이너리로 역변환하고 바이너리 데이터를 반환합니다. 한 번에 한 줄 이상을 전달할 수 있습니다.

선택적 alphabet 은 대체 알파벳을 지정하는 길이가 64인 bytes 객체여야 합니다.

padded 이 참인 경우, 마지막 4개의 base 64 알파벳 문자 그룹은 ‘=’ 문자로 채워져야(padded) 합니다. padded 가 거짓인 경우, 패딩은 필요하지도 인식되지도 않습니다. 즉, ‘=’ 문자는 패딩으로 취급되지 않고 비-알파벳 문자로 처리되며, 이 경우 strict_mode 가 거짓이면 무시되고, strict_mode 가 참이고 ignorechars 에 b’=’이 포함되어 있지 않으면 Error 를 발생시킵니다.

ignorechars 가 지정된 경우, 이는 strict_mode 가 참일 때 입력에서 무시할 문자들이 포함된 bytes-like object 여야 합니다. 만약 ignorechars 에 패딩 문자 '=' 가 포함되어 있다면, 인코딩된 데이터의 끝부분 앞에 나타나는 패딩 문자들과 초과분 패딩 문자들이 무시됩니다. strict_mode 의 기본값은 ignorechars 가 지정되면 True, 그렇지 않으면 False 입니다.

strict_mode 가 참인 경우, 유효한 base64 데이터만 변환됩니다. 유효하지 않은 base64 데이터는 binascii.Error 를 발생시킵니다.

유효한 base64:

  • RFC 4648 을 준수합니다.

  • base64 알파벳에 포함된 문자만 포함합니다.

  • 패딩 이후의 불필요한 데이터(초과 패딩, 줄 바꿈 등 포함)가 포함되지 않습니다.

  • 패딩으로 시작하지 않습니다.

canonical 이 true인 경우, 마지막 그룹의 비정규 패딩 비트는 binascii.Error 를 발생시켜 RFC 4648 섹션 3.5에 정의된 정규 인코딩을 강제합니다. 이 검사는 strict_mode 와 독립적입니다.

버전 3.11에서 변경: strict_mode 매개 변수가 추가되었습니다.

버전 3.15에서 변경: alphabet, canonical, ignorechars, padded 매개변수를 추가했습니다.

binascii.b2a_base64(data, *, padded=True, alphabet=BASE64_ALPHABET, wrapcol=0, newline=True)

RFC 4648 에 명시된 바이트 데이터를 base64 코딩의 ASCII 문자 줄로 변환합니다.

padded 이 참인 경우(기본값), 인코딩된 데이터를 ‘=’ 문자로 채워 크기를 4의 배수로 맞춥니다. padded 가 거짓이면 패딩 문자를 추가하지 않습니다.

wrapcol 이 0이 아닌 경우, 최대 wrapcol 문자마다 줄 바꿈(b'\n') 문자를 삽입합니다. wrapcol 이 0인 경우(기본값)는 줄 바꿈을 삽입하지 않습니다.

newline 이 참인 경우(기본값), 출력 끝에 줄 바꿈 문자가 추가됩니다.

버전 3.6에서 변경: newline 매개 변수가 추가되었습니다.

버전 3.15에서 변경: alphabet, padded, wrapcol 매개변수를 추가했습니다.

binascii.a2b_ascii85(string, /, *, foldspaces=False, adobe=False, ignorechars=b'', canonical=False)

Ascii85 데이터를 바이너리로 다시 변환하고 바이너리 데이터를 반환합니다.

유효한 Ascii85 데이터는 5개씩으로 묶인 Ascii85 알파벳 문자를 포함합니다(마지막 그룹은 2~5개의 문자가 있을 수 있음). 각 그룹은 0``에서 ``2 ** 32 - 1 사이의 범위에 있는 32비트 바이너리 데이터를 인코딩합니다. 특수 문자 z``는 네 개의 연속된 널 바이트를 인코딩하는 ``!!!!! 그룹의 단축형으로 허용됩니다. 단일 문자로 구성된 마지막 그룹은 항상 인코딩 위반으로 간주되어 거부됩니다.

foldspaces 는 4개의 연속된 공백(ASCII 0x20)을 대체하는 단축형으로 ‘y’ 짧은 시퀀스를 허용할지 여부를 지정하는 플래그입니다. 이 기능은

adobe 는 인코딩된 바이트 시퀀스가 PostScript base-85 문자열 리터럴과 같이 <~ 및 ~> 로 프레임화되는지 여부를 제어합니다. adobe 가 참이면 앞의 <~ 는 선택적으로 허용되지만, 뒤의 ~> 는 필수이며 이를 찾을 수 없는 경우 binascii.Error 를 발생시킵니다.

ignorechars 는 입력에서 무시할 문자가 포함된 바이트열류 객체 여야 합니다. 여기에는 공백 문자만 포함되어야 합니다.

canonical 이 true인 경우, 비정규 인코딩은 binascii.Error 를 발생시켜 거부됩니다. 여기서 “정규”라는 것은 b2a_ascii85() 가 생성할 인코딩을 의미합니다. 즉, 모든 0 그룹에는 !!!!! 대신 z 약어가 사용되어야 하고, 부분적인 최종 그룹은 인코더와 동일한 패딩 숫자를 사용해야 합니다.

유효하지 않은 Ascii85 데이터는 binascii.Error 를 발생시킵니다.

Added in version 3.15.

binascii.b2a_ascii85(data, /, *, foldspaces=False, wrapcol=0, pad=False, adobe=False)

바이너리 데이터를 Ascii85 코딩의 포맷된 ASCII 문자 시퀀스로 변환합니다. 반환 값은 변환된 데이터입니다.

foldspaces 는 ‘btoa’가 지원하는 것처럼 4개의 연속된 공백(ASCII 0x20) 대신 특수한 짧은 시퀀스 ‘y’를 사용하는 선택적 플래그입니다. 이 기능은

wrapcol 이 0이 아닌 경우, 최대 wrapcol 문자마다 줄 바꿈(b'\n') 문자를 삽입합니다. wrapcol 이 0인 경우(기본값)는 줄 바꿈을 삽입하지 않습니다.

pad 이 참인 경우, 입력 끝에 적용된 제로 패딩이 btoa 와 마찬가지로 출력 인코딩에 완전히 유지되어 결과가 정확히 5바이트의 배수가 됩니다. 이는 데이터 길이를 보존하지 않으므로 PDF에서 사용하는 표준 인코딩에 포함되지 않습니다.

adobe 는 인코딩된 바이트 시퀀스가 PostScript base-85 문자열 리터럴과 같이 <~ 및 ~> 로 프레임화되는지 여부를 제어합니다. PDF 문서의 ASCII85Decode 스트림은 반드시 ~> 로 끝나야 하지만, 앞부분에 <~ 를 사용해서는 안 된다는 점에 유의하십시오.

Added in version 3.15.

binascii.a2b_base85(string, /, *, alphabet=BASE85_ALPHABET, ignorechars=b'', canonical=False)

Base85 데이터를 바이너리로 다시 변환하고 바이너리 데이터를 반환합니다. 한 번에 하나 이상의 줄을 전달할 수 있습니다.

유효한 Base85 데이터는 5개씩 묶인 Base85 알파벳 문자를 포함합니다(마지막 그룹은 2~5개의 문자가 있을 수 있음). 각 그룹은 0``에서 ``2 ** 32 - 1 사이의 범위에 있는 32비트 바이너리 데이터를 인코딩합니다. 단일 문자로 구성된 마지막 그룹은 항상 인코딩 위반으로 간주되어 거부됩니다.

선택적 alphabet 은 대체 알파벳을 지정하는 길이가 85인 bytes 객체여야 합니다.

ignorechars 는 입력에서 무시할 문자를 포함하는 bytes-like object 여야 합니다.

canonical 이 참인 경우, 비표준(non-canonical) 인코딩은 binascii.Error 로 거부됩니다. 여기서 “표준”이란 b2a_base85() 가 생성하는 방식의 인코딩을 의미하며, 부분적인 마지막 그룹은 인코더와 동일한 패딩 숫자를 사용해야 합니다.

유효하지 않은 Base85 데이터는 binascii.Error 를 발생시킵니다.

Added in version 3.15.

binascii.b2a_base85(data, /, *, alphabet=BASE85_ALPHABET, wrapcol=0, pad=False)

바이너리 데이터를 Base85 코딩의 ASCII 문자로 구성된 한 줄로 변환합니다. 반환 값은 변환된 줄입니다.

선택적 alphabet 은 대체 알파벳을 지정하는 길이가 85인 바이트열류 객체 여야 합니다.

wrapcol 이 0이 아닌 경우, 최대 wrapcol 문자마다 줄 바꿈(b'\n') 문자를 삽입합니다. wrapcol 이 0인 경우(기본값)는 줄 바꿈을 삽입하지 않습니다.

pad 이 참인 경우, 입력 끝에 적용된 제로 패딩이 출력에 유지됩니다. 이때 결과는 항상 5바이트의 배수가 되므로 디코딩 시 데이터의 길이가 보존되지 않을 수 있습니다.

Added in version 3.15.

binascii.a2b_base32(string, /, *, padded=True, alphabet=BASE32_ALPHABET, ignorechars=b'', canonical=False)

base32 데이터를 바이너리로 다시 변환하고 바이너리 데이터를 반환합니다.

유효한 base32 데이터는 RFC 4648 에 명시된 base32 알파벳 문자들을 8개씩 그룹으로 포함하며 (필요한 경우 마지막 그룹은 = 로 8자까지 채워집니다). 각 그룹은 0 에서 2 ** 40 - 1 사이의 범위 내에 있는 40비트 바이너리 데이터를 인코딩합니다.

참고

이 함수는 소문자(표준 base32에서 유효하지 않음)를 대문자로 매핑하지 않으며, RFC 4648 이 허용하는 대로 0 을 O 로, 1 을 I/L 로 문맥에 따라 매핑하지도 않습니다.

선택적 alphabet 은 대체 알파벳을 지정하는 길이가 32인 bytes 객체여야 합니다.

padded 이 true이면 마지막 8개의 base 32 알파벳 문자 그룹이 ‘=’ 문자로 채워져야 합니다. padded 가 false이면 ‘=’ 문자는 다른 비알파벳 문자로 취급됩니다(이때 ignorechars 의 값에 따라 달라집니다).

ignorechars 는 입력에서 무시할 문자가 포함된 bytes-like object 여야 합니다. ignorechars 에 패딩 문자 '=' 가 포함되어 있으면, 인코딩된 데이터 끝부분 앞에 나오는 패딩 문자와 초과된 패딩 문자가 모두 무시됩니다.

canonical 이 true인 경우, 마지막 그룹의 비제로(non-zero) 패딩 비트는 binascii.Error 와 함께 거부되며, RFC 4648 섹션 3.5에 정의된 표준 인코딩을 강제합니다.

유효하지 않은 base32 데이터는 binascii.Error 를 발생시킵니다.

Added in version 3.15.

binascii.b2a_base32(data, /, *, padded=True, alphabet=BASE32_ALPHABET, wrapcol=0)

바이너리 데이터를 RFC 4648 에 명시된 대로 base32 코딩을 사용하여 ASCII 문자의 한 줄로 변환합니다. 반환 값은 변환된 줄입니다.

선택적 alphabet 은 대체 알파벳을 지정하는 길이가 32인 bytes-like object 여야 합니다.

padded 이 true(기본값)이면 인코딩된 데이터를 ‘=’ 문자로 채워 크기를 8의 배수로 맞춥니다. padded 가 false이면 패딩 문자를 추가하지 않습니다.

wrapcol 이 0이 아닌 경우, 최대 wrapcol 문자마다 줄 바꿈(b'\n') 문자를 삽입합니다. wrapcol 이 0인 경우(기본값)는 줄 바꿈을 삽입하지 않습니다.

Added in version 3.15.

binascii.a2b_qp(data, header=False, *, strip_ws=False)

quoted-printable 데이터 블록을 바이너리로 변환하고 바이너리 데이터를 반환합니다. 한 번에 한 줄 이상을 전달할 수 있습니다. 선택적 인자 header 가 존재하고 참이면, 밑줄(_)은 공백으로 디코딩됩니다. 선택적 인자 strip_ws 가 참이면, RFC 2045 에서 요구하는 대로 각 줄의 꼬리 공백이 제거됩니다.

버전 3.16에서 변경: strip_ws 매개변수가 추가되었습니다.

binascii.b2a_qp(data, quotetabs=False, istext=True, header=False)

바이너리 데이터를 quoted-printable 인코딩의 ASCII 문자열로 변환합니다. 반환 값은 변환된 줄입니다. 선택적 인자 quotetabs 가 있고 참이면 모든 탭과 공백이 인코딩됩니다. 선택적 인자 istext 가 있고 참이면 개행 문자는 인코딩되지 않지만 후행 공백은 인코딩됩니다. 선택적 인자 istext 가 있고 거짓이면 개행 문자도 인코딩됩니다. 그렇지 않으면 linefeed 변환이 바이너리 데이터 스트림을 손상시킬 수 있습니다. 선택적 인자 header 가 있고 참이면 RFC 1522 에 따라 공백을 밑줄로 인코딩합니다.

binascii.crc_hqx(data, value)

초기 CRC value로 시작하는, data의 16비트 CRC 값을 계산하고 결과를 반환합니다. 종종 0x1021로 표시되는, CRC-CCITT 다항식 x16 + x12 + x5 + 1을 사용합니다. 이 CRC는 binhex4 형식에서 사용됩니다.

binascii.crc32(data[, value])

초기 CRC value로 시작하는, data의 부호 없는 32비트 체크섬인 CRC-32를 계산합니다. 기본 초기 CRC는 0입니다. 이 알고리즘은 ZIP 파일 체크섬과 일치합니다. 이 알고리즘은 체크섬 알고리즘으로 사용하도록 설계되었으므로, 일반 해시 알고리즘으로 사용하기에 적합하지 않습니다. 다음과 같이 사용하십시오:

print(binascii.crc32(b"hello world"))
# 또는, 두 조각으로:
crc = binascii.crc32(b"hello")
crc = binascii.crc32(b" world", crc)
print('crc32 = {:#010x}'.format(crc))

버전 3.0에서 변경: 결과는 항상 부호 없는(unsigned) 값입니다.

binascii.b2a_hex(data[, sep[, bytes_per_sep=1]])
binascii.hexlify(data[, sep[, bytes_per_sep=1]])

바이너리 data의 16진수 표현을 반환합니다. data의 모든 바이트는 해당 2자리 16진수 표현으로 변환됩니다. 따라서 반환된 바이트열 객체의 길이는 data 의 두 배입니다.

비슷한 기능(하지만 텍스트 문자열을 반환하는)을 bytes.hex() 메서드를 사용하여 편리하게 액세스할 수도 있습니다.

sep이 지정되면, 단일 문자 문자열이나 바이트열 객체여야 합니다. bytes_per_sep 입력 바이트마다 출력에 삽입됩니다. 구분자 배치는 기본적으로 출력의 오른쪽 끝에서부터 계산됩니다. 왼쪽부터 계산하려면, 음수의 bytes_per_sep 값을 제공하십시오.

>>> import binascii
>>> binascii.b2a_hex(b'\xb9\x01\xef')
b'b901ef'
>>> binascii.hexlify(b'\xb9\x01\xef', '-')
b'b9-01-ef'
>>> binascii.b2a_hex(b'\xb9\x01\xef', b'_', 2)
b'b9_01ef'
>>> binascii.b2a_hex(b'\xb9\x01\xef', b' ', -2)
b'b901 ef'

버전 3.8에서 변경: sep과 bytes_per_sep 매개 변수가 추가되었습니다.

binascii.a2b_hex(hexstr, *, ignorechars=b'')
binascii.unhexlify(hexstr, *, ignorechars=b'')

16진수 문자열 hexstr로 표현된 바이너리 데이터를 반환합니다. 이 함수는 b2a_hex()의 역함수입니다. hexstr는 짝수개의 16진수(대소문자 모두 가능합니다)를 포함해야 하며, 그렇지 않으면 Error 예외가 발생합니다.

ignorechars 는 입력에서 무시할 문자를 포함하는 bytes-like object 여야 합니다.

유사한 기능(단, 공백에 대해 더 관대함)을 bytes.fromhex() 클래스 메서드를 사용하여 사용할 수도 있습니다.

버전 3.15에서 변경: ignorechars 매개변수가 추가되었습니다.

exception binascii.Error

에러 시 발생하는 예외. 이들은 대개 프로그래밍 에러입니다.

exception binascii.Incomplete

불완전한 데이터에서 발생하는 예외. 이들은 일반적으로 프로그래밍 에러가 아니지만, 조금 더 많은 데이터를 읽고 다시 시도하면 처리될 수 있습니다.

binascii.BASE64_ALPHABET

RFC 4648 에 따른 Base 64 알파벳입니다.

Added in version 3.15.

binascii.URLSAFE_BASE64_ALPHABET

RFC 4648 에 따른 “URL 및 파일 이름 안전”(URL and filename safe) Base 64 알파벳입니다.

Added in version 3.15.

binascii.UU_ALPHABET

uuencoding 알파벳입니다.

Added in version 3.15.

binascii.CRYPT_ALPHABET

crypt(3) 루틴과 GEDCOM 형식에서 사용되는 Base 64 알파벳입니다.

Added in version 3.15.

binascii.BINHEX_ALPHABET

클래식 Mac OS 내의 BinHex 4 (HQX)에서 사용되는 Base 64 알파벳입니다.

Added in version 3.15.

binascii.BASE85_ALPHABET

Base85 알파벳입니다.

Added in version 3.15.

binascii.ASCII85_ALPHABET

Ascii85 알파벳입니다.

Added in version 3.15.

binascii.Z85_ALPHABET

Z85 알파벳입니다.

Added in version 3.15.

binascii.BASE32_ALPHABET

RFC 4648 에 따른 Base 32 알파벳입니다.

Added in version 3.15.

binascii.BASE32HEX_ALPHABET

RFC 4648 에 따른 “Extended Hex” Base 32 알파벳입니다. 이 알파벳으로 인코딩된 데이터는 비트 연산 비교 시 정렬 순서를 유지합니다.

Added in version 3.15.

더 보기

모듈 base64

RFC 호환 base64 스타일 인코딩으로, 베이스 16, 32, 64 및 85를 지원합니다.

모듈 quopri

MIME 전자 우편 메시지에 사용되는 quoted-printable 인코딩 지원.

분실물 보관소