bz2 — bzip2 압축 지원

bz2 — bzip2 압축 지원 (Support for bzip2 compression)

bzip2 압축 알고리즘을 사용해 데이터를 압축·압축 해제하는 포괄적인 인터페이스를 제공하는 모듈이에요.

출처: Python 표준 라이브러리

본문

이 모듈은 bzip2 압축 알고리즘을 사용해 데이터를 압축·압축 해제하는 포괄적인 인터페이스를 제공해요. bz2 모듈은 다음을 포함해요:

압축된 파일을 읽고 쓰기 위한 open() 함수와 BZ2File 클래스.
점진적 (압축) 해제를 위한 BZ2Compressor와 BZ2Decompressor 클래스.
일회성 (압축) 해제를 위한 compress()와 decompress() 함수.

이것은 선택(optional) 모듈이에요. 주어진 CPython 사본에 없다면 배포자(즉, Python을 제공한 사람)의 문서를 찾아보세요. 배포자라면 선택 모듈에 대한 요구사항(Requirements for optional modules)을 참고하세요.

파일 (압축) 해제

`bz2.open(filename, mode='rb', compresslevel=9, encoding=None, errors=None, newline=None)`

bzip2로 압축된 파일을 이진 또는 텍스트 모드로 열고 파일 객체를 반환해요. BZ2File 생성자와 마찬가지로 filename 인자는 실제 파일 이름(str 또는 bytes 객체)이거나, 읽거나 쓸 기존 파일 객체일 수 있어요.

mode 인자는 이진 모드의 경우 'r', 'rb', 'w', 'wb', 'x', 'xb', 'a', 'ab' 중 하나, 텍스트 모드의 경우 'rt', 'wt', 'xt', 'at' 중 하나일 수 있어요. 기본값은 'rb'예요.

compresslevel 인자는 BZ2File 생성자와 마찬가지로 1~9의 정수예요.

이진 모드의 경우 이 함수는 BZ2File 생성자와 동일해요: BZ2File(filename, mode, compresslevel=compresslevel). 이 경우 encoding, errors, newline 인자는 제공하면 안 돼요.

텍스트 모드의 경우 BZ2File 객체가 생성되고, 지정된 encoding, 오류 처리 동작, 줄바꿈을 가진 io.TextIOWrapper 인스턴스로 감싸져요.

3.3 버전에서 추가.

3.4 버전 변경: 'x'(배타적 생성) 모드가 추가됐어요.

3.6 버전 변경: path-like 객체를 받아들여요.

`class bz2.BZ2File(filename, mode='r', *, compresslevel=9)`

bzip2로 압축된 파일을 이진 모드로 열어요. filename이 str 또는 bytes 객체이면 명명된 파일을 직접 열어요. 그렇지 않으면 filename은 압축 데이터를 읽거나 쓰는 데 사용될 파일 객체여야 해요.

mode 인자는 읽기용 'r'(기본값), 덮어쓰기용 'w', 배타적 생성용 'x', 추가용 'a' 중 하나일 수 있어요. 이들은 각각 'rb', 'wb', 'xb', 'ab'로 동일하게 줄 수 있어요.

filename이 (실제 파일 이름이 아닌) 파일 객체이면 'w' 모드는 파일을 잘라내지 않고 대신 'a'와 동일해요.

mode가 'w' 또는 'a'이면 compresslevel은 압축 수준을 지정하는 1~9 사이의 정수일 수 있어요. 1은 가장 적은 압축을, 9(기본값)는 가장 많은 압축을 생성해요.

mode가 'r'이면 입력 파일은 여러 압축 스트림의 연결일 수 있어요.

BZ2File은 detach()와 truncate()를 제외하고 io.BufferedIOBase가 지정한 모든 멤버를 제공해요. 반복과 with 문이 지원돼요.

BZ2File이 제공하는 추가 메서드와 속성:

peek([n]) — 파일 위치를 진행하지 않고 버퍼링된 데이터를 반환해요. (EOF가 아닌 한) 최소 한 바이트의 데이터가 반환돼요. 반환되는 정확한 바이트 수는 지정되지 않았어요. 참고: peek()을 호출해도 BZ2File의 파일 위치는 변하지 않지만, 밑의 파일 객체의 위치는 바뀔 수 있어요(예: filename에 파일 객체를 전달해 BZ2File을 만든 경우). 3.3 버전에서 추가.
fileno() — 밑의 파일에 대한 파일 디스크립터를 반환해요. 3.3 버전에서 추가.
readable() — 파일이 읽기용으로 열렸는지 여부를 반환해요. 3.3 버전에서 추가.
seekable() — 파일이 시킹을 지원하는지 여부를 반환해요. 3.3 버전에서 추가.
writable() — 파일이 쓰기용으로 열렸는지 여부를 반환해요. 3.3 버전에서 추가.
read1(size=-1) — 밑의 스트림에서 여러 번 읽기를 피하면서 최대 size개의 압축되지 않은 바이트를 읽어요. size가 음수이면 버퍼 하나 분량의 데이터까지 읽어요. 파일이 EOF이면 b''를 반환해요. 3.3 버전에서 추가.
readinto(b) — b에 바이트를 읽어요. 읽은 바이트 수를 반환해요(EOF는 0). 3.3 버전에서 추가.
mode — 읽기용이면 'rb', 쓰기용이면 'wb'. 3.13 버전에서 추가.
name — bzip2 파일 이름. 밑의 파일 객체의 name 속성과 동일해요. 3.13 버전에서 추가.

3.1 버전 변경: with 문 지원 추가.

3.3 버전 변경: filename이 실제 파일 이름 대신 파일 객체가 될 수 있는 지원 추가. 'a'(추가) 모드와 다중 스트림 파일 읽기 지원이 추가됐어요.

3.4 버전 변경: 'x'(배타적 생성) 모드 추가.

3.5 버전 변경: read() 메서드가 이제 None 인자를 받아들여요.

3.6 버전 변경: path-like 객체를 받아들여요.

3.9 버전 변경: buffering 매개변수가 제거됐어요. Python 3.0 이후 무시되고 deprecated였어요. 파일이 어떻게 열리는지 제어하려면 열린 파일 객체를 전달하세요. compresslevel 매개변수가 keyword-only가 됐어요.

3.10 버전 변경: 이 클래스는 gzip과 lzma의 동일한 클래스가 항상 그래왔던 것처럼, 여러 동시 읽기·쓰기에 직면하면 스레드 안전하지 않아요.

점진적 (압축) 해제

`class bz2.BZ2Compressor(compresslevel=9)`

새 압축기 객체를 만들어요. 이 객체는 데이터를 점진적으로 압축하는 데 사용될 수 있어요. 일회성 압축에는 compress() 함수를 대신 사용하세요. compresslevel은 주어지면 1~9 사이의 정수여야 해요. 기본값은 9예요.

compress(data) — 압축기 객체에 데이터를 제공해요. 가능하면 압축 데이터 덩어리를, 그렇지 않으면 빈 바이트 문자열을 반환해요. 압축기에 데이터 제공을 마쳤으면 flush() 메서드를 호출해 압축 과정을 끝내요.
flush() — 압축 과정을 끝내요. 내부 버퍼에 남은 압축 데이터를 반환해요. 이 메서드가 호출된 후에는 압축기 객체를 사용할 수 없어요.

`class bz2.BZ2Decompressor`

새 압축 해제기 객체를 만들어요. 이 객체는 데이터를 점진적으로 압축 해제하는 데 사용될 수 있어요. 일회성 압축에는 decompress() 함수를 대신 사용하세요.

참고: 이 클래스는 decompress()와 BZ2File과 달리 여러 압축 스트림을 포함한 입력을 투명하게 처리하지 않아요. BZ2Decompressor로 다중 스트림 입력을 압축 해제해야 한다면 각 스트림에 새 압축 해제기를 사용해야 해요.

decompress(data, max_length=-1) — data(bytes류 객체)를 압축 해제하고, 압축되지 않은 데이터를 bytes로 반환해요. data 중 일부는 나중에 decompress()를 호출할 때를 위해 내부적으로 버퍼링될 수 있어요. 반환된 데이터는 이전 decompress() 호출의 출력과 연결되어야 해요. max_length가 음수가 아니면 최대 max_length 바이트의 압축 해제된 데이터를 반환해요. 이 제한에 도달하고 더 많은 출력을 생성할 수 있다면 needs_input 속성이 False로 설정돼요. 이 경우 다음 decompress() 호출은 b''로 데이터를 제공해 더 많은 출력을 얻을 수 있어요. 모든 입력 데이터가 압축 해제되고 반환됐다면(max_length 바이트보다 적었거나 max_length가 음수였기 때문에), needs_input 속성이 True로 설정돼요. 스트림 끝에 도달한 후 데이터를 압축 해제하려고 시도하면 EOFError가 발생해요. 스트림 끝 뒤에 발견된 데이터는 무시되고 unused_data 속성에 저장돼요. 3.5 버전 변경: max_length 매개변수 추가.
eof — end-of-stream 마커에 도달했으면 True. 3.3 버전에서 추가.
unused_data — 압축된 스트림 끝 뒤에 발견된 데이터. 스트림 끝에 도달하기 전에 이 속성에 접근하면 값은 b''예요.
needs_input — 새 압축되지 않은 입력이 필요하기 전에 decompress() 메서드가 더 많은 압축 해제된 데이터를 제공할 수 있으면 False. 3.5 버전에서 추가.

일회성 (압축) 해제

`bz2.compress(data, compresslevel=9)`

bytes류 객체 data를 압축해요. compresslevel은 주어지면 1~9 사이의 정수여야 해요. 기본값은 9예요. 점진적 압축에는 BZ2Compressor를 대신 사용하세요.

`bz2.decompress(data)`

bytes류 객체 data를 압축 해제해요. data가 여러 압축 스트림의 연결이면 모든 스트림을 압축 해제해요. 점진적 압축 해제에는 BZ2Decompressor를 대신 사용하세요. 3.3 버전 변경: 다중 스트림 입력 지원 추가.

사용 예시

bz2 모듈의 일반적인 사용 예시 몇가지를 아래에 보여드릴게요.

compress()와 decompress()를 사용한 라운드트립 압축:

>>> import bz2
>>> data = b"""\
... Donec rhoncus quis sapien sit amet molestie. Fusce scelerisque vel augue
... nec ullamcorper. Nam rutrum pretium placerat. Aliquam vel tristique lorem,
... sit amet cursus ante. In interdum laoreet mi, sit amet ultrices purus
... pulvinar a. Nam gravida euismod magna, non varius justo tincidunt feugiat.
... Aliquam pharetra lacus non risus vehicula rutrum. Maecenas aliquam leo
... felis. Pellentesque semper nunc sit amet nibh ullamcorper, ac elementum
... dolor luctus. Curabitur lacinia mi ornare consectetur vestibulum."""
>>> c = bz2.compress(data)
>>> len(data) / len(c)  # Data compression ratio
1.513595166163142
>>> d = bz2.decompress(c)
>>> data == d  # Check equality to original object after round-trip
True

BZ2Compressor를 사용한 점진적 압축:

>>> import bz2
>>> def gen_data(chunks=10, chunksize=1000):
...     """Yield incremental blocks of chunksize bytes."""
...     for _ in range(chunks):
...         yield b"z" * chunksize
...
>>> comp = bz2.BZ2Compressor()
>>> out = b""
>>> for chunk in gen_data():
...     # Provide data to the compressor object
...     out = out + comp.compress(chunk)
...
>>> # Finish the compression process.  Call this once you have
>>> # finished providing data to the compressor.
>>> out = out + comp.flush()

위 예시는 매우 "비무작위" 데이터 스트림(bz 청크의 스트림)을 사용해요. 무작위 데이터는 압축이 잘 안 되는 경향이 있는 반면, 정렬되고 반복적인 데이터는 보통 높은 압축 비율을 만들어요.

이진 모드로 bzip2 압축 파일 쓰기와 읽기:

>>> import bz2
>>> data = b"""\
... Donec rhoncus quis sapien sit amet molestie. Fusce scelerisque vel augue
... nec ullamcorper. Nam rutrum pretium placerat. Aliquam vel tristique lorem,
... sit amet cursus ante. In interdum laoreet mi, sit amet ultrices purus
... pulvinar a. Nam gravida euismod magna, non varius justo tincidunt feugiat.
... Aliquam pharetra lacus non risus vehicula rutrum. Maecenas aliquam leo
... felis. Pellentesque semper nunc sit amet nibh ullamcorper, ac elementum
... dolor luctus. Curabitur lacinia mi ornare consectetur vestibulum."""
>>> with bz2.open("myfile.bz2", "wb") as f:
...     # Write compressed data to file
...     unused = f.write(data)
...
>>> with bz2.open("myfile.bz2", "rb") as f:
...     # Decompress data from file
...     content = f.read()
...
>>> content == data  # Check equality to original object after round-trip
True