`gzip` — gzip 파일 지원¶

소스 코드: Lib/gzip.py

이 모듈은 GNU 프로그램 gzip과 gunzip처럼 파일을 압축하고 압축을 푸는 간단한 인터페이스를 제공합니다.

이것은 :term:`optional module`입니다. 만약 CPython 버전에서 이 모듈이 누락되었다면, 배포처(즉, 여러분에게 Python을 제공한 곳)의 문서를 확인하십시오. 본인이 배포자라면 :ref:`optional-module-requirements`를 참조하십시오.

데이터 압축은 zlib 모듈에 의해 제공됩니다.

The gzip 모듈은 GzipFile 클래스와 더불어, open(), compress(), decompress() 편리 함수들을 제공합니다. GzipFile 클래스는 gzip -형식 파일을 읽고 쓰며, 데이터를 자동으로 압축하거나 해제하여 일반적인 file object 처럼 보이게 합니다.

compress와 pack 프로그램에서 생성된 것과 같은, gzip과 gunzip 프로그램으로 압축을 풀 수 있는 추가 파일 형식은 이 모듈에서 지원하지 않습니다.

이 모듈은 다음 항목을 정의합니다:

gzip.open(filename, mode='rb', compresslevel=6, encoding=None, errors=None, newline=None, *, mtime=None)¶

바이너리나 텍스트 모드로 gzip으로 압축된 파일을 열고, 파일 객체를 반환합니다.

filename 인자는 실제 파일명(str이나 bytes 객체)이나, 읽거나 쓸 기존 파일 객체가 될 수 있습니다.

mode 인자는 바이너리 모드의 경우 'r', 'rb', 'a', 'ab', 'w', 'wb', 'x' 또는 'xb', 또는 텍스트 모드의 경우 'rt', 'at', 'wt' 또는 'xt' 중 하나일 수 있습니다. 기본값은 'rb'입니다.

compresslevel 인자는 GzipFile 생성자와 마찬가지로 0에서 9 사이의 정수입니다.

키워드 전용 인자 mtime 은 Unix 타임스탬프를 나타냅니다.

바이너리 모드의 경우, 이 함수는 GzipFile 생성자 GzipFile(filename, mode, compresslevel, mtime=mtime) 와 동일합니다. 이 경우, encoding, errors 및 newline 인자를 제공해서는 안 됩니다.

텍스트 모드의 경우, GzipFile 객체가 만들어지고, 지정된 인코딩, 에러 처리 동작 및 줄 종료를 갖는 io.TextIOWrapper 인스턴스로 감싸집니다.

버전 3.3에서 변경: 파일 객체인 filename 지원, 텍스트 모드 지원 및 encoding, errors 및 newline 인자가 추가되었습니다.

버전 3.4에서 변경: 'x', 'xb' 및 'xt' 모드에 대한 지원이 추가되었습니다.

버전 3.6에서 변경: 경로류 객체를 받아들입니다.

버전 3.15에서 변경: 기본 압축 수준이 6으로 낮아졌습니다(기존 9에서 변경). 이는 대부분의 압축 도구에서 기본값으로 사용되는 수준이며, 속도와 성능 사이의 더 나은 절충점입니다.

버전 3.16.0a0 (unreleased)에서 변경: GzipFile 클래스 생성자에 전달되는 키워드 전용 인자 mtime 이 추가되었습니다.

exception gzip.BadGzipFile¶: 유효하지 않은 gzip 파일에 대한 예외. OSError를 상속합니다. EOFError와 zlib.error도 유효하지 않은 gzip 파일에 대해서 발생할 수 있습니다.

Added in version 3.8.

class gzip.GzipFile(filename=None, mode=None, compresslevel=6, fileobj=None, mtime=None)¶

truncate() 메서드를 제외하고, 대부분 파일 객체 메서드를 흉내 내는 GzipFile 클래스의 생성자입니다. fileobj와 filename 중 적어도 하나는 의미 있는 값을 부여해야 합니다.

새 클래스 인스턴스는 fileobj를 기반으로 하는데, 일반 파일, io.BytesIO 객체 또는 파일을 흉내 내는 다른 객체가 될 수 있습니다. 기본값은 None이며, 이 경우 파일 객체를 제공하기 위해 filename이 열립니다.

fileobj가 None이 아닐 때, filename 인자는 gzip 파일 헤더에 포함되는 데만 사용되며, 이 헤더에는 압축되지 않은 파일의 원래 파일명이 포함될 수 있습니다. 보고 알 수 있다면, fileobj의 파일명을 기본값으로 사용합니다; 그렇지 않으면, 기본값은 빈 문자열이며, 이 경우 원래 파일명은 헤더에 포함되지 않습니다.

mode 인자는 파일을 읽을지 쓸지에 따라 'r', 'rb', 'a', 'ab', 'w', 'wb', 'x' 또는 'xb' 중 하나일 수 있습니다. 보고 알 수 있다면, 기본값은 fileobj의 모드입니다; 그렇지 않으면, 기본값은 'rb'입니다. 향후 파이썬 릴리스에서는 fileobj의 모드가 사용되지 않습니다. 항상 쓰기를 위해서는 mode를 지정하는 것이 좋습니다.

파일이 항상 바이너리 모드로 열림에 유의하십시오. 텍스트 모드로 압축 파일을 열려면, open()을 사용하십시오 (또는 GzipFile을 io.TextIOWrapper로 감싸십시오).

compresslevel 인자는 압축 수준을 제어하는 0에서 9까지의 정수입니다; 1은 가장 빠르고 압축률이 가장 낮으며, 9는 가장 느리고 압축률이 가장 높습니다. 0은 압축하지 않습니다. 기본값은 9입니다.

선택적 인자 mtime 은 gzip이 요청하는 타임스탬프입니다. 시간은 Unix 형식(즉, 1970년 1월 1일 00:00:00 UTC 이후 경과된 초)으로 표현됩니다. 생성 시간에 의존하지 않는 압축 스트림을 생성하려면 mtime 을 0 으로 설정하십시오. mtime 이 생략되거나 None 인 경우 현재 시간이 사용됩니다. 다만, 현재 시간이 1970년 1월 1일 00:00:00 UTC부터 2106년 2월 7일 06:28:15 UTC 사이의 범위를 벗어나거나, 명시적으로 전달된 mtime 인자가 0 에서 2**32-1 범위를 벗어나는 경우 대신 0 이 사용됩니다.

압축 해제 시 설정되는 mtime 속성은 아래를 참조하십시오.

GzipFile 객체의 close() 메서드를 호출해도 fileobj를 닫지 않습니다, 압축된 데이터 뒤에 뭔가 추가하기를 원할 수 있기 때문입니다. 또한, 이는 fileobj로 쓰기 위해 열린 io.BytesIO 객체를 전달하고, io.BytesIO 객체의 getvalue() 메서드를 사용하여 결과 메모리 버퍼를 얻을 수 있도록 합니다.

GzipFile은 이터레이션과 with 문을 포함하여 io.BufferedIOBase 인터페이스를 지원합니다. truncate() 메서드 만 구현되지 않습니다.

GzipFile은 다음 메서드와 어트리뷰트도 제공합니다:

peek(n)¶: 파일 위치를 전진시키지 않고 압축되지 않은 n 바이트를 읽습니다. 반환된 바이트 수는 요청한 것보다 많거나 적을 수 있습니다.

참고

peek()를 호출할 때 GzipFile의 파일 위치가 변경되지는 않지만, 하부 파일 객체의 위치는 변경될 수 있습니다 (예를 들어, GzipFile이 fileobj 매개 변수로 생성된 경우).

Added in version 3.2.

mode¶: 읽기용은 'rb', 쓰기용은 'wb' 입니다.

버전 3.13에서 변경: 이전 버전에서는 정수 1 또는 2 였습니다.

mtime¶: 압축을 풀 때, 이 어트리뷰트는 가장 최근에 읽은 헤더의 마지막 타임스탬프로 설정됩니다. 유닉스 에포크 (1970-01-01 00:00:00 UTC) 이후의 시간(초)를 나타내는 정수입니다. 헤더를 읽기 전의 초깃값은 None입니다.

name¶: 디스크에 있는 gzip 파일의 경로로, str 또는 bytes 타입입니다. 다른 정규화, 해결 또는 확장 없이 원본 입력 경로에 대한 os.fspath() 호출 결과와 동일합니다.

버전 3.1에서 변경: mtime 생성자 인자와 mtime 어트리뷰트와 함께 with 문에 대한 지원이 추가되었습니다.

버전 3.2에서 변경: 제로 패딩(zero-padded)된 파일과 위치 변경할 수 없는(unseekable) 파일에 대한 지원이 추가되었습니다.

버전 3.3에서 변경: io.BufferedIOBase.read1() 메서드가 이제 구현됩니다.

버전 3.4에서 변경: 'x' 및 'xb' 모드에 대한 지원이 추가되었습니다.

버전 3.5에서 변경: 임의의 바이트열류 객체를 쓰는 지원이 추가되었습니다. 이제 read() 메서드는 None 인자를 받아들입니다.

버전 3.6에서 변경: 경로류 객체를 받아들입니다.

버전 3.9부터 폐지됨: mode 인자를 지정하지 않고 쓰기 위해 GzipFile을 여는 것은 폐지되었습니다.

버전 3.12에서 변경: filename 속성을 제거하고 대신 name 속성을 사용하십시오.

gzip.compress(data, compresslevel=6, *, mtime=0)¶: data 를 압축하여 압축된 데이터를 포함하는 bytes 객체를 반환합니다. compresslevel 과 mtime 은 위에서 설명한 GzipFile 생성자와 동일한 의미를 가지며, mtime 은 재현 가능한 출력을 위해 기본값이 0으로 설정됩니다.

Added in version 3.2.

버전 3.8에서 변경: 재현성 있는 출력을 위한 mtime 매개 변수가 추가되었습니다.

버전 3.11에서 변경: 스트림 방식 대신 모든 데이터를 한 번에 압축하여 속도를 향상시켰습니다. mtime 이 0 으로 설정된 호출은 더 나은 성능을 위해 zlib.compress() 로 전달됩니다. 이 경우 출력 결과에 기반 zlib 구현이 제공하는 255 “unknown” 이외의 gzip 헤더 “OS” 바이트 값이 포함될 수 있습니다.

버전 3.13에서 변경: 이 함수를 사용할 때 gzip 헤더 OS 바이트가 3.10 이전 버전과 동일하게 255로 설정됨을 보장합니다.

버전 3.14에서 변경: mtime 매개 변수의 기본값이 재현 가능한 출력을 위해 이제 0으로 설정됩니다. 이전처럼 현재 시간을 사용하려면 mtime 에 None 을 전달하십시오.

버전 3.15에서 변경: 기본 압축 수준이 6으로 낮아졌습니다(기존 9에서 변경). 이는 대부분의 압축 도구에서 기본값으로 사용되는 수준이며, 속도와 성능 사이의 더 나은 절충점입니다.

gzip.decompress(data)¶: data 를 압축 해제하여 압축이 풀린 데이터를 포함하는 bytes 객체를 반환합니다. 이 함수는 멀티 멤버 gzip 데이터(여러 개의 gzip 블록이 연결된 것)를 압축 해제할 수 있습니다. 데이터에 단 하나의 멤버만 포함되어 있음이 확실한 경우에는 wbits 가 31로 설정된 zlib.decompress() 함수를 사용하는 것이 더 빠릅니다.

Added in version 3.2.

버전 3.11에서 변경: 스트림 방식 대신 메모리에서 멤버들을 한 번에 압축 해제하여 속도를 향상시켰습니다.

사용 예¶

압축된 파일을 읽는 방법의 예:

import gzip
with gzip.open('/home/joe/file.txt.gz', 'rb') as f:
    file_content = f.read()

압축된 GZIP 파일을 만드는 방법의 예:

import gzip
content = b"Lots of content here"
with gzip.open('/home/joe/file.txt.gz', 'wb') as f:
    f.write(content)

기존 파일을 GZIP 압축하는 방법의 예:

import gzip
import shutil
with open('/home/joe/file.txt', 'rb') as f_in:
    with gzip.open('/home/joe/file.txt.gz', 'wb') as f_out:
        shutil.copyfileobj(f_in, f_out)

바이너리 문자열을 GZIP 압축하는 방법의 예:

import gzip
s_in = b"Lots of content here"
s_out = gzip.compress(s_in)

모듈 zlib: gzip 파일 형식을 지원하는 데 필요한 기본 데이터 압축 모듈.

gzip (압축 해제)가 병목 현상이 되는 경우, python-isal 패키지는 거의 호환되는 API를 통해 (압축 해제) 속도를 높여줍니다.

명령 줄 인터페이스¶

gzip 모듈은 파일을 압축하거나 압축을 해제하는 간단한 명령 줄 인터페이스를 제공합니다.

실행이 완료된 후에도 gzip 모듈은 입력 파일을 유지합니다.

버전 3.8에서 변경: 새로운 명령 중 인터페이스를 사용법과 함께 추가합니다. 기본적으로, CLI를 실행할 때, 기본 압축 수준은 6입니다.

명령 줄 옵션¶

file¶: file이 지정되지 않으면, sys.stdin에서 읽습니다.

--fast¶: 가장 빠른 압축 방법(압축을 덜 함)을 나타냅니다.

--best¶: 가장 느린 압축 방법(최상의 압축)을 나타냅니다.

-d, --decompress¶: 주어진 파일의 압축을 풉니다.

-h, --help¶: 도움말 메시지를 표시합니다.