`zipfile` — ZIP 아카이브 작업¶

소스 코드: Lib/zipfile/

ZIP 파일 형식은 흔히 쓰이는 아카이브와 압축 표준입니다. 이 모듈은 ZIP 파일을 만들고, 읽고, 쓰고, 추가하고, 나열하는 도구를 제공합니다. 이 모듈의 고급 사용을 위해서는 PKZIP Application Note에 정의된 형식의 이해가 필요합니다.

이 모듈은 멀티파트 ZIP 파일을 처리하지 않습니다. 이 모듈은 ZIP64 확장을 사용하는 ZIP 파일(즉, 크기가 4 GiB를 초과하는 ZIP 파일)을 처리할 수 있습니다. ZIP 아카이브 내 암호화된 파일의 복호화를 지원하지만, 암호화된 파일을 생성할 수는 없습니다. 복호화는 C가 아닌 네이티브 파이썬으로 구현되어 있어 매우 느립니다.

압축된 아카이브를 처리하려면 zlib, bz2, lzma, compression.zstd 와 같은 선택적 모듈 이 필요합니다. 사용하는 CPython에 이 중 하나라도 포함되어 있지 않다면, 배포처(즉, 파이썬을 제공한 업체)의 문서를 확인하십시오. 본인이 배포자인 경우, 선택적 모듈 요구사항 를 참조하십시오.

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

exception zipfile.BadZipFile¶: 잘못된 ZIP 파일로 인해 발생하는 에러.

Added in version 3.2.

exception zipfile.BadZipfile¶: 이전 파이썬 버전과의 호환성을 위한, BadZipFile의 별칭.

버전 3.2부터 폐지됨.

exception zipfile.LargeZipFile¶: ZIP 파일에 ZIP64 기능이 필요하지만 활성화되지 않았을 때 발생하는 에러.

class zipfile.ZipFile: ZIP 파일을 읽고 쓰는 클래스. 생성자 세부 사항은 ZipFile 객체 섹션을 참조하십시오.

class zipfile.Path: importlib.resources.abc.Traversable 인터페이스를 포함하여 pathlib.Path 가 제공하는 인터페이스의 일부를 구현하는 클래스입니다.

Added in version 3.8.

class zipfile.PyZipFile: 파이썬 라이브러리를 포함하는 ZIP 아카이브를 만들기 위한 클래스.

class zipfile.ZipInfo(filename='NoName', date_time=(1980, 1, 1, 0, 0, 0))¶

아카이브 멤버에 대한 정보를 나타내는 데 사용되는 클래스입니다. 이 클래스의 인스턴스는 ZipFile 객체의 getinfo() 및 infolist() 메서드에 의해 반환됩니다. zipfile 모듈의 대부분의 사용자는 이러한 인스턴스를 직접 생성할 필요가 없으며, 이 모듈에서 생성된 것들을 사용하기만 하면 됩니다. filename 은 아카이브 멤버의 전체 이름이어야 하며, date_time 은 파일을 마지막으로 수정한 시간을 설명하는 6개의 필드를 포함하는 튜플이어야 합니다. 각 필드는 ZipInfo 객체 섹션에 설명되어 있습니다.

버전 3.13에서 변경: 이전의 보호된 속성인 _compresslevel`을 노출하기 위해 공개 속성인 :attr:!compress_level`이 추가되었습니다. 이전의 보호된 이름은 하위 호환성을 위해 속성(property)으로 계속 작동합니다.

_for_archive(archive)¶

ZipFile.writestr() 에서 사용되는 것과 동일하게 date_time, 압축(compression), 외부 속성(external attributes)을 적절한 기본값으로 해석합니다.

체이닝을 위해 자기 자신(self)을 반환합니다.

Added in version 3.14.

zipfile.is_zipfile(filename)¶: filename이 매직 번호에 기반하여 유효한 ZIP 파일이면 True를, 그렇지 않으면 False를 반환합니다. filename은 파일이거나 파일류 객체일 수도 있습니다.

버전 3.1에서 변경: 파일과 파일류 객체를 지원합니다.

zipfile.ZIP_STORED¶: 압축되지 않은 아카이브 멤버를 위한 숫자 상수.

zipfile.ZIP_DEFLATED¶: 일반적인 ZIP 압축 방법을 위한 숫자 상수. zlib 모듈이 필요합니다.

zipfile.ZIP_BZIP2¶: BZIP2 압축 방법을 위한 숫자 상수. bz2 모듈이 필요합니다.

Added in version 3.3.

zipfile.ZIP_LZMA¶: LZMA 압축 방법을 위한 숫자 상수. lzma 모듈이 필요합니다.

Added in version 3.3.

zipfile.ZIP_ZSTANDARD¶: Zstandard 압축에 대한 숫자 상수입니다. 이 기능을 사용하려면 compression.zstd 모듈이 필요합니다.

참고

APPNOTE 6.3.7에서 메서드 ID 20 이 Zstandard 압축에 할당되었습니다. 이는 APPNOTE 6.3.8에서 충돌을 피하기 위해 메서드 ID 93 으로 변경되었으며, 메서드 ID 20 은 더 이상 권장되지 않습니다(deprecated). 호환성을 위해 zipfile 모듈은 두 메서드 ID를 모두 읽지만, 데이터를 쓸 때는 메서드 ID 93 만 사용합니다.

Added in version 3.14.

참고

ZIP 파일 형식 명세는 2001년부터 bzip2 압축, 2006년부터 LZMA 압축, 2020년부터 Zstandard 압축을 지원해 왔습니다. 그러나 일부 도구(이전 버전의 Python 포함)는 이러한 압축 방식을 지원하지 않으며, ZIP 파일 처리를 거부하거나 개별 파일을 추출하는 데 실패할 수 있습니다.

PKZIP Application Note: 사용된 형식과 알고리즘의 저자인 Phil Katz의 ZIP 파일 형식에 대한 설명서.
Info-ZIP 홈페이지: Info-ZIP 프로젝트의 ZIP 아카이브 프로그램과 개발 라이브러리에 관한 정보.

ZipFile 객체¶

class zipfile.ZipFile(file, mode='r', compression=ZIP_STORED, allowZip64=True, compresslevel=None, *, strict_timestamps=True, metadata_encoding=None)¶

ZIP 파일을 엽니다, 여기서 file은 파일에 대한 경로 (문자열), 파일류 객체 또는 경로류 객체일 수 있습니다.

mode 매개 변수는 기존 파일을 읽으려면 'r', 새 파일을 자르고 쓰려면 'w', 기존 파일에 추가하려면 'a', 새 파일을 독점적으로 작성하고 쓰려면 'x' 이어야 합니다. mode가 'x'이고 file이 기존 파일을 참조하면, FileExistsError 가 발생합니다. mode가 'a'이고 file이 기존 ZIP 파일을 참조하면, 추가 파일이 이곳으로 추가됩니다. file이 ZIP 파일을 참조하지 않으면, 새 ZIP 아카이브를 파일에 덧붙입니다(append). 이는 ZIP 아카이브를 다른 파일(가령 python.exe)에 추가하기 위한 것입니다. mode가 'a'이고 파일이 아예 존재하지 않으면, 파일이 만들어집니다. mode가 'r'이나 'a'이면, 파일은 탐색 가능(seekable)해야 합니다.

compression 은 아카이브를 쓸 때 사용할 ZIP 압축 방식이며, ZIP_STORED, ZIP_DEFLATED, ZIP_BZIP2, ZIP_LZMA, 또는 ZIP_ZSTANDARD 중 하나여야 합니다. 인식할 수 없는 값이 제공되면 NotImplementedError 가 발생합니다. 만약 ZIP_DEFLATED, ZIP_BZIP2, ZIP_LZMA, 또는 ZIP_ZSTANDARD 이 지정되었으나 해당 모듈(zlib, bz2, lzma, 또는 compression.zstd)을 사용할 수 없는 경우, RuntimeError 가 발생합니다. 기본값은 ZIP_STORED 입니다.

allowZip64 가 True (기본값)인 경우, zipfile이 4 GiB보다 크면 ZIP64 확장을 사용하는 ZIP 파일을 생성합니다. 만약 이 값이 false 이면 ZIP 파일에 ZIP64 확장이 필요한 경우 zipfile 이 예외를 발생시킵니다.

compresslevel 매개 변수는 아카이브에 파일을 쓸 때 사용할 압축 수준을 제어합니다. ZIP_STORED 또는 ZIP_LZMA 를 사용할 때는 아무런 영향이 없습니다. ZIP_DEFLATED 를 사용할 때는 0 에서 9 사이의 정수를 허용하며(자세한 내용은 zlib 참조), ZIP_BZIP2 를 사용할 때는 1 에서 9 사이의 정수를 허용합니다(자세한 내용은 bz2 참조). ZIP_ZSTANDARD 를 사용하는 경우 일반적으로 -131072 에서 22 사이의 정수가 허용됩니다(유효한 값과 그 의미에 대한 자세한 내용은 CompressionParameter.compression_level 참조).

strict_timestamps 인자를 False로 설정하면, 1980-01-01 이전의 zip 파일을 허용하는 대신 타임 스탬프를 1980-01-01로 설정합니다. 2107-12-31 이후의 파일에 대해서도 비슷한 동작이 발생하며, 타임 스탬프는 역시 한곗값으로 설정됩니다.

모드가 'r' 인 경우, metadata_encoding 을 코덱 이름으로 설정할 수 있으며, 이는 멤버 이름이나 ZIP 주석과 같은 메타데이터를 디코딩하는 데 사용됩니다.

파일이 'w', 'x' 또는 'a' 모드로 만들어졌고 아카이브에 아무런 파일도 추가하지 않고 닫히면, 비어있는 아카이브에 적합한 ZIP 구조가 파일에 기록됩니다.

ZipFile은 또한 컨텍스트 관리자이므로 with 문을 지원합니다. 이 예에서, myzip은 with 문 스위트가 완료된 후에 닫힙니다 – 예외가 발생할 때조차 그렇습니다:

with ZipFile('spam.zip', 'w') as myzip:
    myzip.write('eggs.txt')

참고

metadata_encoding 은 ZipFile에 대한 인스턴스 전체 설정입니다. 이를 멤버별로 개별 설정하는 것은 불가능합니다.

이 속성은 현재 로캘 인코딩이나 코드 페이지(주로 Windows 환경)를 사용하여 아카이브 이름을 생성하는 이전 구현체들을 위한 해결책입니다. .ZIP 표준에 따르면, 아카이브 헤더의 플래그에 의해 메타데이터의 인코딩을 IBM 코드 페이지(기본값) 또는 UTF-8으로 지정할 수 있습니다. 이 플래그는 Python 전용 확장 기능인 metadata_encoding 보다 우선합니다.

버전 3.2에서 변경: ZipFile을 컨텍스트 관리자로 사용하는 기능이 추가되었습니다.

버전 3.3에서 변경: bzip2와 lzma 압축에 대한 지원이 추가되었습니다.

버전 3.4에서 변경: ZIP64 확장은 기본적으로 활성화됩니다.

버전 3.5에서 변경: 탐색할 수 없는(unseekable) 스트림으로의 쓰기 지원을 추가했습니다. 'x' 모드에 대한 지원이 추가되었습니다.

버전 3.6에서 변경: 이전에는, 인식할 수 없는 compression 값에 대해 평범한 RuntimeError가 발생했습니다.

버전 3.6.2에서 변경: file 매개 변수는 경로류 객체를 받아들입니다.

버전 3.7에서 변경: compresslevel 매개 변수를 추가했습니다.

버전 3.8에서 변경: strict_timestamps 키워드 전용 매개 변수

버전 3.11에서 변경: zipfile의 디렉터리 및 파일 헤더에서 메타데이터를 읽을 때 멤버 이름 인코딩을 지정하는 기능을 추가했습니다.

ZipFile.close()¶: 아카이브 파일을 닫습니다. 프로그램을 종료하기 전에 close()를 호출해야 합니다. 그렇지 않으면 필수 레코드가 기록되지 않습니다.

ZipFile.getinfo(name)¶: 아카이브 멤버 name에 관한 정보가 있는 ZipInfo 객체를 반환합니다. 현재 아카이브에 포함되지 않은 이름에 대해 getinfo()를 호출하면 KeyError가 발생합니다.

ZipFile.infolist()¶: 아카이브의 각 멤버에 대한 ZipInfo 객체를 포함하는 리스트를 반환합니다. 기존 아카이브가 열린 경우 객체는 디스크의 실제 ZIP 파일에 있는 항목과 순서가 같습니다.

ZipFile.namelist()¶: 아카이브 멤버의 리스트를 이름으로 반환합니다.

ZipFile.open(name, mode='r', pwd=None, *, force_zip64=False)¶

아카이브 멤버를 바이너리 파일류 객체로 액세스합니다. name은 아카이브 내의 파일 이름이거나 ZipInfo 객체일 수 있습니다. 포함될 때 mode 매개 변수는 'r'(기본값)이거나 'w' 이어야 합니다. pwd는 암호화된 ZIP 파일을 해독하는 데 사용되는 bytes 객체인 비밀번호입니다.

open()은 컨텍스트 관리자이기도 하므로 with 문을 지원합니다:

with ZipFile('spam.zip') as myzip:
    with myzip.open('eggs.txt') as myfile:
        print(myfile.read())

mode 'r'에서 파일류 객체(ZipExtFile)는 읽기 전용이며 다음 메서드를 제공합니다: read(), readline(), readlines(), seek(), tell(), __iter__(), __next__(). 이러한 객체는 ZipFile과 독립적으로 작동할 수 있습니다.

mode='w'에서, write() 메서드를 지원하는 쓰기 가능한 파일 핸들이 반환됩니다. 쓰기 가능한 파일 핸들이 열려있는 동안, ZIP 파일에서 다른 파일을 읽거나 쓰려고 시도하면 ValueError가 발생합니다.

두 경우 모두 파일류 객체는 아카이브 내 파일의 이름과 동일한 name 속성과 입력 모드에 따라 'rb'' 또는 'wb'' 인 mode 속성을 가집니다.

파일을 기록할 때, 파일 크기를 미리 알 수 없지만 2GiB를 초과할 수 있으면, 헤더 형식이 큰 파일을 지원할 수 있도록 force_zip64=True를 전달하십시오. 파일 크기가 미리 알려졌으면, file_size가 설정된 ZipInfo 객체를 구성하고, 이를 name 매개 변수로 사용하십시오.

참고

open(), read() 및 extract() 메서드는 파일명이나 ZipInfo 객체를 취할 수 있습니다. 중복 이름을 가진 멤버가 포함된 ZIP 파일을 읽으려고 할 때 이 점에 감사할 것입니다.

버전 3.6에서 변경: mode='U' 지원이 제거되었습니다. 유니버설 줄 넘김 모드로 압축된 텍스트 파일을 읽으려면 io.TextIOWrapper를 사용하십시오.

버전 3.6에서 변경: 이제 ZipFile.open()은 이제 mode='w' 옵션으로 파일을 아카이브에 기록하는 데 사용될 수 있습니다.

버전 3.6에서 변경: 닫힌 ZipFile에 open()을 호출하면 ValueError가 발생합니다. 이전에는, RuntimeError가 발생했습니다.

버전 3.13에서 변경: 쓰기 가능한 파일 같은 객체에 name 과 mode 속성이 추가되었습니다. 읽기 가능한 파일 같은 객체에 대한 mode 속성 값이 'r' 에서 'rb' 로 변경되었습니다.

ZipFile.extract(member, path=None, pwd=None)¶

아카이브에서 현재 작업 디렉터리로 멤버를 추출합니다. member는 전체 이름이거나 ZipInfo 객체여야 합니다. 파일 정보는 최대한 정확하게 추출됩니다. path는 추출할 다른 디렉터리를 지정합니다. member는 파일 이름이나 ZipInfo 객체일 수 있습니다. pwd는 암호화된 파일에 사용되는 bytes 객체인 비밀번호입니다.

만들어진 정규화된 경로(디렉터리나 새 파일)를 반환합니다.

참고

멤버 파일명이 절대 경로이면, 드라이브/UNC 공유 지점(sharepoint)과 선행 (역) 슬래시가 제거됩니다, 예를 들어: ///foo/bar는 유닉스에서 foo/bar가 되고, 윈도우에서 C:\foo\bar는 foo\bar가 됩니다. 그리고 멤버 파일명의 모든 ".." 구성 요소가 제거됩니다, 예를 들어: ../../foo../../ba..r은 foo../ba..r이 됩니다. 윈도우에서 잘못된 문자(:, <, >, |, ", ? 및 *)는 밑줄(_)로 대체됩니다.

버전 3.6에서 변경: 닫힌 ZipFile에서 extract()를 호출하면 ValueError가 발생합니다. 이전에는 RuntimeError가 발생했습니다.

버전 3.6.2에서 변경: path 매개 변수는 경로류 객체를 받아들입니다.

ZipFile.extractall(path=None, members=None, pwd=None)¶: 아카이브에서 현재 작업 디렉터리로 모든 멤버를 추출합니다. path는 추출할 다른 디렉터리를 지정합니다. members는 선택적이며 namelist()가 반환한 리스트의 부분 집합이어야 합니다. pwd는 암호화된 파일에 사용되는 bytes 객체인 비밀번호입니다.

경고

사전 검사 없이 신뢰할 수 없는 출처에서 아카이브를 추출하지 마십시오. 파일이 path 외부에 생성될 가능성이 있습니다(예: 절대 경로를 포함하거나 “..” 요소를 포함하는 파일명이 있는 멤버). 이 모듈은 이를 방지하려고 시도합니다. extract() 참고를 확인하십시오.

버전 3.6에서 변경: 닫힌 ZipFile에서 extractall()을 호출하면 ValueError가 발생합니다. 이전에는 RuntimeError가 발생했습니다.

버전 3.6.2에서 변경: path 매개 변수는 경로류 객체를 받아들입니다.

ZipFile.printdir()¶: 아카이브의 목차를 sys.stdout으로 인쇄합니다.

ZipFile.setpassword(pwd)¶: 암호화된 파일을 추출하기 위해 pwd(bytes 객체)를 기본 비밀번호로 설정합니다.

ZipFile.read(name, pwd=None)¶: 아카이브 내 파일 name 의 바이트를 반환합니다. name 은 아카이브 내 파일의 이름 또는 ZipInfo 객체입니다. 아카이브는 읽기 또는 추가 모드로 열려 있어야 합니다. pwd 는 암호화된 파일에 사용되는 bytes 타입의 비밀번호이며, 지정될 경우 setpassword() 로 설정된 기본 비밀번호를 대체합니다. ZIP_STORED, ZIP_DEFLATED, ZIP_BZIP2, ZIP_LZMA, 또는 ZIP_ZSTANDARD 이외의 압축 방식을 사용하는 ZipFile에서 read() 를 호출하면 NotImplementedError 가 발생합니다. 해당 압축 모듈을 사용할 수 없는 경우에도 오류가 발생합니다.

버전 3.6에서 변경: 닫힌 ZipFile에서 read()를 호출하면 ValueError가 발생합니다. 이전에는 RuntimeError가 발생했습니다.

ZipFile.testzip()¶: 아카이브의 모든 파일을 읽고 CRC와 파일 헤더를 확인합니다. 첫 번째 불량 파일의 이름을 반환하거나, None을 반환합니다.

버전 3.6에서 변경: 닫힌 ZipFile에서 testzip()을 호출하면 ValueError가 발생합니다. 이전에는 RuntimeError가 발생했습니다.

ZipFile.write(filename, arcname=None, compress_type=None, compresslevel=None)¶: filename이라는 파일을 아카이브에 기록하고, 아카이브 이름으로 arcname을 지정합니다 (기본적으로, filename과 같지만, 드라이브 문자가 없고 선행 경로 구분 기호가 제거됩니다). 주어지면, compress_type은 새 항목에 대해 생성자의 compression 매개 변수에 제공된 값을 대체합니다. 마찬가지로, compresslevel은 주어지면 생성자를 대체합니다. 아카이브는 'w', 'x' 또는 'a' 모드로 열려 있어야 합니다.

참고

ZIP 파일 표준은 역사적으로 메타데이터 인코딩을 명시하지 않았으나 상호 운용성을 위해 CP437(원본 IBM PC 인코딩)을 강력히 권장해 왔습니다. 최신 버전에서는 UTF-8만 사용할 수 있습니다. 이 모듈에서는 멤버 이름에 비ASCII 문자가 포함된 경우 UTF-8이 자동으로 사용됩니다. ASCII 또는 UTF-8 이외의 다른 인코딩으로 멤버 이름을 작성하는 것은 불가능합니다.

참고

아카이브 이름은 아카이브 루트에 상대적이어야 합니다. 즉, 경로 구분 기호로 시작해서는 안 됩니다.

참고

arcname(또는 arcname이 제공되지 않으면 filename)에 널 바이트가 포함되어 있으면, 아카이브의 파일 이름이 널 바이트에서 잘립니다.

참고

파일 이름 앞부분에 슬래시(/)가 있으면 일부 윈도우 시스템의 ZIP 프로그램에서 아카이브를 열 수 없는 문제가 발생할 수 있습니다.

버전 3.6에서 변경: 'r' 모드로 만들어진 ZipFile이나 닫힌 ZipFile에서 write()를 호출하면 ValueError가 발생합니다. 이전에는 RuntimeError가 발생했습니다.

ZipFile.writestr(zinfo_or_arcname, data, compress_type=None, compresslevel=None)¶

파일을 아카이브에 기록합니다. 내용은 data이며, str이나 bytes 인스턴스일 수 있습니다; str이면 먼저 UTF-8로 인코딩됩니다. zinfo_or_arcname은 아카이브에 제공될 파일 이름이거나 ZipInfo 인스턴스입니다. 인스턴스이면 최소한 파일명, 날짜 및 시간을 지정해야 합니다. 이름이면, 날짜와 시간이 현재 날짜와 시간으로 설정됩니다. 아카이브는 'w', 'x' 또는 'a' 모드로 열려 있어야 합니다.

주어지면, compress_type은 새 항목에 대해 생성자의 compression 매개 변수에 제공되거나 zinfo_or_arcname(ZipInfo 인스턴스인 경우)의 값을 대체합니다. 마찬가지로, compresslevel은 주어지면 생성자를 대체합니다.

참고

ZipInfo 인스턴스를 zinfo_or_arcname 매개 변수로 전달할 때, 사용되는 압축 방법은 주어진 ZipInfo 인스턴스의 compress_type 멤버에 지정된 압축 방법입니다. 기본적으로, ZipInfo 생성자는 이 멤버를 ZIP_STORED로 설정합니다.

버전 3.2에서 변경: compress_type 인자.

버전 3.6에서 변경: 'r' 모드로 만들어진 ZipFile이나 닫힌 ZipFile에서 writestr()을 호출하면, ValueError가 발생합니다. 이전에는 RuntimeError가 발생했습니다.

버전 3.14에서 변경: 이제 SOURCE_DATE_EPOCH 환경 변수를 따릅니다. 이 변수가 설정되어 있으면 현재 시간 대신 이 값을 ZIP 아카이브에 쓰이는 파일의 수정 타임스탬프로 사용합니다.

ZipFile.mkdir(zinfo_or_directory, mode=511)¶

아카이브 내에 디렉터리를 생성합니다. zinfo_or_directory 가 문자열인 경우, mode 인수에 지정된 모드로 아카이브 내에 디렉터리가 생성됩니다. 그러나 zinfo_or_directory 이 ZipInfo 인스턴스인 경우에는 mode 인수를 무시합니다.

아카이브는 'w'', 'x'' 또는 'a'' 모드로 열려야 합니다.

Added in version 3.11.

ZipFile.remove(zinfo_or_arcname)¶

아카이브의 중앙 디렉터리에서 멤버 항목을 제거합니다. zinfo_or_arcname 은 멤버의 전체 경로이거나 ZipInfo 인스턴스일 수 있습니다. 여러 멤버가 동일한 전체 경로를 공유하고 해당 경로가 문자열로 제공되는 경우, 그 중 하나만 제거되며 어떤 것이 제거될지는 지정되지 않으므로 이를 신뢰해서는 안 됩니다. 특정 멤버를 제거하려면 구체적인 ZipInfo 인스턴스를 전달하십시오.

아카이브는 'w'', 'x'' 또는 'a'' 모드로 열려야 합니다.

제거된 ZipInfo 인스턴스를 반환합니다.

닫힌 ZipFile에 대해 remove() 를 호출하면 ValueError 가 발생합니다.

참고

이 메서드는 중앙 디렉터리에서만 멤버 항목을 제거하여 대부분의 도구에서 접근할 수 없게 만듭니다. 내용과 메타데이터를 포함한 해당 멤버의 로컬 파일 항목은 아카이브에 남아 있으며 포렌식 도구를 사용하여 복구할 수 있습니다. 로컬 파일 항목을 제거하고 공간을 회수하려면 이후에 repack() 을 호출하십시오. 데이터가 어떤 방식으로 작성되었든 상관없이 삭제되도록 보장하려면 repack() 에 반환된 ZipInfo 를 전달하십시오.

Added in version 3.16.0a0 (unreleased).

ZipFile.repack(removed=None, *, strict_descriptor=True[, chunk_size])¶

참조되지 않는 로컬 파일 항목을 제거하기 위해 아카이브를 다시 쓰며, 파일 크기를 줄입니다. 아카이브는 'a'' 모드로 열려야 합니다.

removed 가 제공된 경우, 이는 최근에 제거된 멤버를 나타내는 ZipInfo 객체들의 시퀀스여야 하며, 이들 중 해당 로컬 파일 항목만 제거됩니다. 그렇지 않은 경우, 중앙 디렉터리에서 더 이상 참조되지 않는 로컬 파일 항목을 찾아 삭제하기 위해 아카이브를 스캔합니다.

removed*를 전달하는 것이 공간을 회수하는 가장 확실한 방법입니다. 해당 로컬 파일 항목이 중앙 디렉터리에서 직접 찾아져 작성 방식에 관계없이 제거되기 때문입니다. 반면, *removed*가 생략된 경우 수행되는 스캔은 일부 항목이 그대로 남겨질 수 있습니다(아래의 *strict_descriptor 참조). 멤버를 제거하고 공간을 한 번에 회수하려면:

with ZipFile('spam.zip', 'a') as myzip:
    removed = [myzip.remove(name) for name in ('ham.txt', 'eggs.txt')]
    myzip.repack(removed)

스캔 시, strict_descriptor 는 서명되지 않은(unsigned) data descriptor 로 작성된 항목을 처리하는 방식을 제어합니다. 데이터 디스크립터는 항목의 CRC와 크기를 담고 있는 선택적 레코드로, 항목 데이터 바로 뒤에 저장됩니다. 이는 아카이브가 탐색 불가능한 스트림에 쓰일 때 사용되며, 마커 서명으로 시작하면 서명된(signed) 것이고 그렇지 않으면 서명되지 않은 것으로 간주합니다. 서명되지 않은 디스크립터는 버전 6.3.0(2006년 출시)부터 PKZIP Application Note 에 의해 더 이상 권장되지 않으며 일부 오래된 도구에 의해서만 작성됩니다. Python 및 기타 현대적인 도구에 의해 작성되는 서명된 디스크립터는 항상 감지됩니다. strict_descriptor 가 true(기본값)인 경우, 서명된 데이터 디스크립터만 감지되므로 서명되지 않은 디스크립터로 작성된 참조 없는 항목은 발견되지 않으며 스캔을 통해 공간이 회수되지 않습니다. strict_descriptor=False 로 설정하면 서명되지 않은 디스크립터도 감지하지만, 스캔 속도가 현저히 느려질 수 있습니다(최악의 경우 약 100~1000배). 이는 신뢰할 수 없는 입력에 대한 서비스 거부(DoS) 공격 벡터로 악용될 수 있습니다. 이 설정은 데이터 디스크립터가 없는 항목에는 영향을 미치지 않으며, removed 가 제공되는 경우에는 필요하지 않습니다.

chunk_size 를 지정하여 항목 데이터를 이동할 때의 버퍼 크기를 제어할 수 있습니다(기본값은 1 MiB).

닫힌 ZipFile에서 repack() 을 호출하면 ValueError 가 발생합니다.

참고

스캔 알고리즘은 휴리스틱 기반이며 ZIP 파일이 일반적인 구조를 따르고 있다고 가정합니다. 예를 들어, 로컬 파일 항목이 겹치거나 바이너리 데이터가 섞이지 않고 연속적으로 저장된 경우입니다. 셀프 추출기 스텁과 같은 앞에 추가된(prepended) 바이너리 데이터는 우연히 여러 측면에서 유효한 로컬 파일 항목과 유사한 바이트를 포함하는 아주 드문 경우를 제외하고는 인식되고 유지됩니다. 내장된 ZIP 페이로드는 일반적인 구조를 따르는 한 올바르게 처리됩니다. 그러나 이 알고리즘은 신뢰할 수 없거나 의도적으로 조작된 입력에 대한 정확성이나 안전성을 보장하지 않습니다. 더 나은 신뢰성과 성능을 위해 removed 인자를 제공하는 것이 일반적으로 권장됩니다.

Added in version 3.16.0a0 (unreleased).

다음과 같은 데이터 어트리뷰트도 사용할 수 있습니다:

ZipFile.filename¶: ZIP 파일의 이름.

ZipFile.debug¶: 사용할 디버그 출력 수준. 이것은 0(기본값, 출력 없음)에서 3(가장 많은 출력)으로 설정될 수 있습니다. 디버깅 정보는 sys.stdout에 기록됩니다.

ZipFile.comment¶: ZIP 파일에 연관되는 주석은 bytes 객체입니다. 'w', 'x' 또는 'a' 모드로 만들어진 ZipFile 인스턴스에 주석을 대입하면, 65535바이트를 넘지 않아야 합니다. 이보다 긴 주석은 잘립니다.

Path 객체¶

class zipfile.Path(root, at='')¶

root zip 파일(ZipFile 생성자에 전달하기에 적합한 ZipFile 인스턴스나 file일 수 있습니다)에서 Path 객체를 생성합니다.

at은 zip 파일 내에서 이 Path의 위치를 지정합니다, 예를 들어 ‘dir/file.txt’, ‘dir/’ 또는 ‘’. 기본값은 빈 문자열이며, 루트를 나타냅니다.

참고

Path 클래스는 ZIP 아카이브 내의 파일 이름을 정제(sanitize)하지 않습니다. ZipFile.extract() 및 ZipFile.extractall() 메서드와 달리, 경로 탐색 취약점(예: 절대 경로 또는 “..” 구성 요소가 포함된 경로)을 방지하기 위해 파일 이름을 검증하거나 정제하는 것은 호출자의 책임입니다. 신뢰할 수 없는 아카이브를 처리할 때는 os.path.abspath() 를 사용하여 파일 이름을 해소하고, os.path.commonpath() 로 대상 디렉터리와 대조하는 것을 고려하십시오.

Path 객체는 pathlib.Path 객체의 다음 기능을 노출합니다:

/ 연산자나 joinpath를 사용하여 Path 객체를 순회할 수 있습니다.

Path.name¶: 최종 경로 구성 요소.

Path.open(mode='r', *, pwd, **)¶: 현재 경로에서 ZipFile.open()을 호출합니다. 지원되는 모드를 통해 읽기 또는 쓰기, 텍스트 또는 바이너리로 여는 것을 허락합니다: ‘r’, ‘w’, ‘rb’, ‘wb’. 위치와 키워드 인자는 텍스트로 열 때 io.TextIOWrapper로 전달되고 그렇지 않으면 무시됩니다. pwd는 ZipFile.open()에 대한 pwd 매개 변수입니다.

버전 3.9에서 변경: open에 텍스트와 바이너리 모드에 대한 지원이 추가되었습니다. 기본 모드는 이제 텍스트입니다.

버전 3.11.2에서 변경: encoding 파라미터는 위치 인수로 제공해도 TypeError 를 발생시키지 않습니다. 이는 3.9 버전과 동일합니다. 패치되지 않은 3.10 및 3.11 버전과 호환되어야 하는 코드는 encoding 을 포함한 모든 io.TextIOWrapper 인자를 키워드 인자로 전달해야 합니다.

Path.iterdir()¶: 현재 디렉터리의 자식을 열거합니다.

Path.is_dir()¶: 현재 컨텍스트가 디렉터리를 참조하면 True를 반환합니다.

Path.is_file()¶: 현재 컨텍스트가 파일을 참조하면 True를 반환합니다.

Path.is_symlink()¶: 현재 컨텍스트가 심볼릭 링크를 참조하면 True를 반환합니다.

Added in version 3.12.

버전 3.13에서 변경: 이전에는 is_symlink 가 무조건 False 를 반환했습니다.

Path.exists()¶: 현재 컨텍스트가 zip 파일에 있는 파일이나 디렉터리를 참조하면 True를 반환합니다.

Path.suffix¶: 마지막 구성 요소에서 마침표로 구분된 마지막 부분입니다(있는 경우). 이는 일반적으로 파일 확장자라고 불립니다.

Added in version 3.11: Path.suffix 속성이 추가되었습니다.

Path.stem¶: 접미사(suffix)가 없는 최종 경로 구성 요소.

Added in version 3.11: Path.stem 속성이 추가되었습니다.

Path.suffixes¶: 경로의 접미사 리스트로, 일반적으로 파일 확장자라고 불립니다.

Added in version 3.11: Path.suffixes 속성이 추가되었습니다.

Path.read_text(*, **)¶: 현재 파일을 유니코드 텍스트로 읽습니다. 위치와 키워드 인자는 io.TextIOWrapper로 전달됩니다 (컨텍스트에 의해 암시되는 buffer 제외).

버전 3.11.2에서 변경: encoding 파라미터는 위치 인수로 제공해도 TypeError 를 발생시키지 않습니다. 이는 3.9 버전과 동일합니다. 패치되지 않은 3.10 및 3.11 버전과 호환되어야 하는 코드는 encoding 을 포함한 모든 io.TextIOWrapper 인자를 키워드 인자로 전달해야 합니다.

Path.read_bytes()¶: 현재 파일을 바이트열로 읽습니다.

Path.joinpath(*other)¶

다른 인자들을 각각 결합한 새 Path 객체를 반환합니다. 다음은 동일하게 동작합니다:

>>> Path(...).joinpath('child').joinpath('grandchild')
>>> Path(...).joinpath('child', 'grandchild')
>>> Path(...) / 'child' / 'grandchild'

버전 3.10에서 변경: 3.10 이전 버전에서 joinpath 는 문서화되지 않았으며 정확히 하나의 파라미터만 수용했습니다.

zipp 프로젝트는 이전 Python 버전에서도 최신 경로 객체 기능을 사용할 수 있도록 백포트를 제공합니다. 변경 사항을 조기에 적용하려면 zipfile.Path 대신 zipp.Path 를 사용하십시오.

PyZipFile 객체¶

PyZipFile 생성자는 ZipFile 생성자와 같은 매개 변수와 하나의 추가 매개 변수 optimize를 취합니다.

class zipfile.PyZipFile(file, mode='r', compression=ZIP_STORED, allowZip64=True, optimize=-1)¶

버전 3.2에서 변경: optimize 매개 변수를 추가했습니다.

버전 3.4에서 변경: ZIP64 확장은 기본적으로 활성화됩니다.

인스턴스에는 ZipFile 객체의 메서드들 외에 한 가지 추가 메서드가 있습니다:

writepy(pathname, basename='', filterfunc=None)¶

파일 *.py를 검색하고 해당 파일을 아카이브에 추가합니다.

PyZipFile에 대한 optimize 매개 변수가 제공되지 않았거나 -1이면, 해당 파일은 *.pyc 파일이며, 필요하면 컴파일합니다.

PyZipFile에 대한 optimize 매개 변수가 0, 1 또는 2이면, 해당 최적화 수준(compile()을 참조하십시오)의 파일 만 아카이브에 추가되며, 필요하면 컴파일합니다.

pathname이 파일이면, 파일 이름은 .py로 끝나야하며, 단지 그 (해당 *.pyc) 파일 만 최상위 수준에 추가됩니다 (경로 정보 없음). pathname이 .py로 끝나지 않는 파일이면, RuntimeError가 발생합니다. 디렉터리이고, 디렉터리가 패키지 디렉터리가 아니면, 모든 파일 *.pyc가 최상위 수준에 추가됩니다. 디렉터리가 패키지 디렉터리이면, 모든 *.pyc가 패키지 이름의 파일 경로 아래에 추가되고, 서브 디렉터리가 패키지 디렉터리이면, 이들 모두도 재귀적으로 정렬된 순서로 추가됩니다.

basename은 내부 전용입니다.

filterfunc가 주어지면, 단일 문자열 인자를 취하는 함수여야 합니다. 아카이브에 추가되기 전에 각 경로(개별 전체 파일 경로를 포함합니다)를 전달합니다. filterfunc가 거짓 값을 반환하면, 경로가 추가되지 않으며, 디렉터리이면 내용이 무시됩니다. 예를 들어, 테스트 파일이 모두 test 디렉터리에 있거나 문자열 test_로 시작하면, filterfunc를 사용하여 해당 파일들을 제외할 수 있습니다:

>>> zf = PyZipFile('myprog.zip')
>>> def notests(s):
...     fn = os.path.basename(s)
...     return (not (fn == 'test' or fn.startswith('test_')))
...
>>> zf.writepy('myprog', filterfunc=notests)

writepy() 메서드는 다음과 같은 파일 이름으로 아카이브를 만듭니다:

string.pyc                   # 최상위 이름
test/__init__.pyc            # 패키지 디렉터리
test/testall.pyc             # 모듈 test.testall
test/bogus/__init__.pyc      # 서브 패키지 디렉터리
test/bogus/myfile.pyc        # 서브 모듈 test.bogus.myfile

버전 3.4에서 변경: filterfunc 매개 변수를 추가했습니다.

버전 3.6.2에서 변경: pathname 매개 변수는 경로류 객체를 받아들입니다.

버전 3.7에서 변경: 재귀는 디렉터리 항목을 정렬합니다.

ZipInfo 객체¶

ZipInfo 클래스의 인스턴스는 ZipFile 객체의 getinfo()와 infolist() 메서드가 반환합니다. 각 객체는 ZIP 아카이브의 단일 멤버에 대한 정보를 저장합니다.

파일 시스템 파일의 ZipInfo 인스턴스를 만드는 클래스 메서드가 하나 있습니다:

classmethod ZipInfo.from_file(filename, arcname=None, *, strict_timestamps=True)¶

zip 파일에 파일을 추가할 수 있도록, 파일 시스템의 파일에 대한 ZipInfo 인스턴스를 생성합니다.

filename은 파일 시스템에서 파일이나 디렉터리의 경로여야 합니다.

arcname이 지정되면, 아카이브 내에서의 이름으로 사용됩니다. arcname을 지정하지 않으면, 이름은 filename과 같지만, 드라이브 문자와 선행 경로 구분 기호가 제거됩니다.

Added in version 3.6.

버전 3.6.2에서 변경: filename 매개 변수는 경로류 객체를 받아들입니다.

버전 3.8에서 변경: strict_timestamps 키워드 전용 매개 변수를 추가했습니다.

인스턴스에는 다음과 같은 메서드와 어트리뷰트가 있습니다:

ZipInfo.is_dir()¶

이 아카이브 멤버가 디렉터리이면 True를 반환합니다.

이것은 항목 이름을 사용합니다: 디렉터리는 항상 /로 끝나야 합니다.

Added in version 3.6.

ZipInfo.filename¶: 아카이브에서의 파일의 이름.

ZipInfo.date_time¶

아카이브 멤버의 마지막 수정 시간과 날짜입니다. 이는 ZIP 파일의 중앙 디렉터리에서

해당 튜플은 다음을 포함합니다:

인덱스	값
`0`	연도 (>= 1980)
`1`	월 (1에서 시작)
`2`	월 중 일 (1에서 시작)
`3`	시간 (0에서 시작)
`4`	분 (0에서 시작)
`5`	초 (0에서 시작)

참고

ZIP 형식은 여러 위치(중앙 디렉터리, NTFS/UNIX 시스템용 추가 필드 등)에 여러 타임스탬프 필드를 지원합니다. 이 속성은 특히 중앙 디렉터리의 타임스탬프를 반환합니다. ZIP 파일의 중앙 디렉터리 타임스탬프 형식은 1980년 이전의 타임스탬프를 지원하지 않습니다. 일부 추가 필드 형식(UNIX 타임스탬프 등)은 더 과거의 날짜를 나타낼 수 있지만, 이 속성은 중앙 디렉터리의 타임스탬프만 반환합니다.

중앙 디렉터리 타임스탬프는 다른 ZIP 도구의 동작과 일치하도록 UTC 시간이 아닌 로컬 시간으로 해석됩니다.

ZipInfo.compress_type¶: 아카이브 멤버의 압축 유형.

ZipInfo.comment¶: bytes 객체로 제공되는 개별 아카이브 멤버에 대한 주석.

ZipInfo.extra¶: 확장 필드 데이터. PKZIP Application Note는 이 bytes 객체에 포함된 데이터의 내부 구조에 대한 주석을 포함합니다.

ZipInfo.create_system¶: ZIP 아카이브를 만든 시스템.

ZipInfo.create_version¶: ZIP 아카이브를 만든 PKZIP 버전.

ZipInfo.extract_version¶: 아카이브를 추출하기 위해 필요한 PKZIP 버전.

ZipInfo.reserved¶: 반드시 0이어야 합니다.

ZipInfo.flag_bits¶: ZIP 플래그 비트.

ZipInfo.volume¶: 파일 헤더의 볼륨 번호.

ZipInfo.internal_attr¶: 내부 어트리뷰트.

ZipInfo.external_attr¶: 외부 파일 어트리뷰트.

ZipInfo.header_offset¶: 파일 헤더의 바이트 오프셋.

ZipInfo.CRC¶: 압축되지 않은 파일의 CRC-32.

ZipInfo.compress_size¶: 압축된 데이터의 크기.

ZipInfo.file_size¶: 압축되지 않은 파일의 크기.

명령 줄 인터페이스¶

zipfile 모듈은 ZIP 아카이브와 상호 작용하기 위한 간단한 명령 줄 인터페이스를 제공합니다.

새 ZIP 아카이브를 만들려면 -c 옵션 뒤에 이름을 지정한 다음 포함해야 할 파일 이름을 나열하십시오:

$ python -m zipfile -c monty.zip spam.txt eggs.txt

디렉터리 전달도 허용됩니다:

$ python -m zipfile -c monty.zip life-of-brian_1979/

ZIP 아카이브를 지정된 디렉터리로 추출하려면, -e 옵션을 사용하십시오:

$ python -m zipfile -e monty.zip target-dir/

ZIP 아카이브에 있는 파일 목록을 보려면, -l 옵션을 사용하십시오:

$ python -m zipfile -l monty.zip

명령 줄 옵션¶

-l <zipfile>¶
--list <zipfile>¶: zip 파일에 있는 파일을 나열합니다.

-c <zipfile> <source1> ... <sourceN>¶
--create <zipfile> <source1> ... <sourceN>¶: 소스 파일로 zip 파일을 만듭니다.

-e <zipfile> <output_dir>¶
--extract <zipfile> <output_dir>¶: zip 파일을 대상 디렉터리로 추출합니다.

-t <zipfile>¶
--test <zipfile>¶: zip 파일이 유효한지 테스트합니다.

--metadata-encoding <encoding>¶: -l, -e, -t 에 대한 멤버 이름의 인코딩을 지정합니다.

Added in version 3.11.

압축 해제 함정¶

아래 나열된 일부 함정으로 인해 zipfile 모듈에서의 추출이 실패할 수 있습니다.

파일 자체에서¶

잘못된 암호 / CRC 체크섬 / ZIP 형식 또는 지원되지 않는 압축 방법 / 암호 해독으로 인해 압축 해제에 실패할 수 있습니다.

파일 시스템 제한¶

다른 파일 시스템의 제한을 초과하면 압축 해제에 실패할 수 있습니다. 가령 디렉터리 항목에 허용되는 문자, 파일 이름 길이, 경로명 길이, 단일 파일 크기 및 파일 수 등.

자원 제한¶

메모리나 디스크 볼륨이 부족하면 압축 해제에 실패합니다. 예를 들어, 압축 해제 폭탄(일명 ZIP bomb)을 zipfile 라이브러리에 적용하면 디스크 볼륨이 소진될 수 있습니다.

중단¶

Ctrl-C 누르기나 압축 해제 프로세스를 죽이는 것과 같은 압축 해제 중 중단으로 인해 아카이브 압축 해제가 불완전할 수 있습니다.

추출의 기본 동작¶

기본 추출 동작을 모르면 예기치 않은 압축 해제 결과가 발생할 수 있습니다. 예를 들어, 같은 아카이브를 두 번 추출하면, 묻지 않고 파일을 덮어씁니다.