"gzip" --- **gzip** 파일 지원
*****************************

**소스 코드:** Lib/gzip.py

======================================================================

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

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

"gzip" 모듈은 "open()", "compress()" 및 "decompress()" 편리 함수뿐만
아니라 "GzipFile" 클래스도 제공합니다. "GzipFile" 클래스는 **gzip**-형
식 파일을 읽고 쓰는데, 자동으로 데이터를 압축하거나 압축을 풀어서 일반
적인 *파일 객체*처럼 보이게 합니다.

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

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

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

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

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

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

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

   바이너리 모드의 경우, 이 함수는 "GzipFile" 생성자
   "GzipFile(filename, mode, compresslevel)"와 동등합니다. 이 경우,
   *encoding*, *errors* 및 *newline* 인자를 제공하면 안 됩니다.

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

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

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

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

exception gzip.BadGzipFile

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

   Added in version 3.8.

class gzip.GzipFile(filename=None, mode=None, compresslevel=9, 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"입니다
   .

   The optional *mtime* argument is the timestamp requested by gzip.
   The time is in Unix format, i.e., seconds since 00:00:00 UTC,
   January 1, 1970. If *mtime* is omitted or "None", the current time
   is used. Use *mtime* = 0 to generate a compressed stream that does
   not depend on creation time.

   See below for the "mtime" attribute that is set when decompressing.

   "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'" for reading and "'wb'" for writing.

      버전 3.13에서 변경: In previous versions it was an integer "1"
      or "2".

   mtime

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

   name

      The path to the gzip file on disk, as a "str" or "bytes".
      Equivalent to the output of "os.fspath()" on the original input
      path, with no other normalization, resolution or expansion.

   버전 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에서 변경: Remove the "filename" attribute, use the "name"
   attribute instead.

gzip.compress(data, compresslevel=9, *, mtime=0)

   Compress the *data*, returning a "bytes" object containing the
   compressed data.  *compresslevel* and *mtime* have the same meaning
   as in the "GzipFile" constructor above, but *mtime* defaults to 0
   for reproducible output.

   Added in version 3.2.

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

   버전 3.11에서 변경: Speed is improved by compressing all data at
   once instead of in a streamed fashion. Calls with *mtime* set to
   "0" are delegated to "zlib.compress()" for better speed. In this
   situation the output may contain a gzip header "OS" byte value
   other than 255 "unknown" as supplied by the underlying zlib
   implementation.

   버전 3.13에서 변경: The gzip header OS byte is guaranteed to be set
   to 255 when this function is used as was the case in 3.10 and
   earlier.

   버전 3.14에서 변경: The *mtime* parameter now defaults to 0 for
   reproducible output. For the previous behaviour of using the
   current time, pass "None" to *mtime*.

gzip.decompress(data)

   Decompress the *data*, returning a "bytes" object containing the
   uncompressed data. This function is capable of decompressing multi-
   member gzip data (multiple gzip blocks concatenated together). When
   the data is certain to contain only one member the
   "zlib.decompress()" function with *wbits* set to 31 is faster.

   Added in version 3.2.

   버전 3.11에서 변경: Speed is improved by decompressing members at
   once in memory instead of in a streamed fashion.


사용 예
=======

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

   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** 파일 형식을 지원하는 데 필요한 기본 데이터 압축 모듈.

  In case gzip (de)compression is a bottleneck, the python-isal
  package speeds up (de)compression with a mostly compatible API.


명령 줄 인터페이스
==================

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

일단 실행되면 "gzip" 모듈은 입력 파일을 유지합니다.

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


명령 줄 옵션
------------

file

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

--fast

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

--best

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

-d, --decompress

   주어진 파일의 압축을 풉니다.

-h, --help

   도움말 메시지를 표시합니다.
