zipfile — ZIP 아카이브 작업

zipfile — ZIP 아카이브 작업

ZIP 파일 형식은 흔한 아카이브 및 압축 표준이에요. 이 모듈은 ZIP 파일을 생성, 읽기, 쓰기, 추가(append), 나열하는 도구를 제공해요. 이 모듈의 고급 사용은 PKZIP Application Note에 정의된 대로 형식에 대한 이해를 요구해요.

이 모듈은 멀티파트 ZIP 파일을 처리하지 않아요. ZIP64 확장(즉 4 GiB보다 큰 ZIP 파일)을 사용하는 ZIP 파일은 처리할 수 있어요. 압축된 아카이브 처리에는 zlib, bz2, lzma, compression.zstd 같은 선택적 모듈이 필요해요.

출처: Python documentation

본문

exceptionzipfile.BadZipFile

나쁜 ZIP 파일에 대해 발생하는 오류. (BadZipfile은 이전 Python과의 호환을 위한 별칭)

exceptionzipfile.LargeZipFile

ZIP 파일에 ZIP64 기능이 필요하지만 활성화되지 않았을 때 발생하는 오류.

주요 클래스:

  • classzipfile.ZipFile — ZIP 파일을 읽고 쓰는 클래스
  • classzipfile.Path — pathlib.Path가 제공하는 인터페이스의 하위 집합을 구현하는 클래스. importlib.resources.abc.Traversable 전체 인터페이스 포함
  • classzipfile.PyZipFile — Python 라이브러리를 포함하는 ZIP 아카이브를 만드는 클래스
  • classzipfile.ZipInfo(filename='NoName', date_time=(1980,1,1,0,0,0)) — 아카이브 멤버에 대한 정보를 나타내는 클래스. getinfo()와 infolist() 메서드가 반환해요.

함수/상수:

  • zipfile.is_zipfile(filename) — filename이 매직 넘버 기준 유효한 ZIP 파일이면 True, 아니면 False 반환
  • zipfile.ZIP_STORED — 압축되지 않은 아카이브 멤버의 숫자 상수
  • zipfile.ZIP_DEFLATED — 일반 ZIP 압축 방법의 숫자 상수. zlib 모듈 필요
  • zipfile.ZIP_BZIP2 — BZIP2 압축 방법. bz2 모듈 필요
  • zipfile.ZIP_LZMA — LZMA 압축 방법. lzma 모듈 필요
  • zipfile.ZIP_ZSTANDARD — Zstandard 압축. compression.zstd 모듈 필요

ZipFile 객체 (ZipFile objects)

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

ZIP 파일을 열어요. file은 파일 경로(문자열), 파일류 객체 또는 path-like 객체일 수 있어요. mode 매개변수는 기존 파일을 읽는 'r', 자르고 쓰는 'w', 기존 파일에 추가하는 'a', 배타적으로 생성·쓰는 'x'여야 해요. compression은 ZIP 압축 방법이고 기본은 ZIP_STORED예요. allowZip64가 True(기본)이면 zipfile이 4 GiB보다 큰 파일에 ZIP64 확장을 사용해요.

ZipFile은 컨텍스트 매니저이므로 with 문을 지원해요:

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

주요 메서드:

  • close() — 아카이브 파일을 닫아요. 프로그램을 종료하기 전에 close()를 호출해야 핵심 레코드가 기록돼요.
  • getinfo(name) — 아카이브 멤버 name에 대한 정보가 있는 ZipInfo 객체를 반환해요.
  • infolist() — 아카이브 각 멤버에 대한 ZipInfo 객체를 담은 목록 반환
  • namelist() — 아카이브 멤버를 이름별로 목록 반환
  • *open(name, mode='r', pwd=None, , force_zip64=False) — 아카이브 멤버를 바이너리 파일류 객체로 접근해요. mode는 'r'(기본) 또는 'w'여야 해요. open()은 컨텍스트 매니저이기도 해요.
  • extract(member, path=None, pwd=None) — 아카이브에서 멤버를 현재 작업 디렉터리로 추출해요. 보안을 위해 멤버 파일 이름의 절대 경로와 드라이브/UNC 공유 지점, 선행 슬래시가 제거되고 모든 ".." 구성 요소가 제거돼요.
  • extractall(path=None, members=None, pwd=None) — 아카이브에서 모든 멤버를 현재 작업 디렉터리로 추출해요.
  • printdir() — sys.stdout에 아카이브의 목차를 출력해요.
  • setpassword(pwd) — 암호화된 파일을 추출할 기본 비밀번호로 pwd(bytes 객체) 설정
  • read(name, pwd=None) — 아카이브의 파일 name의 bytes를 반환해요.
  • testzip() — 아카이브의 모든 파일을 읽고 CRC와 파일 헤더를 확인해요.
  • write(filename, arcname=None, compress_type=None, compresslevel=None) — filename 파일을 아카이브에 써요.
  • writestr(zinfo_or_arcname, data, compress_type=None, compresslevel=None) — 파일을 아카이브에 써요. data는 str 또는 bytes일 수 있어요.
  • mkdir(zinfo_or_directory, mode=511) — 아카이브 안에 디렉터리를 만들어요.

데이터 속성:

  • filename — ZIP 파일의 이름
  • debug — 사용할 디버그 출력 수준(0~3)
  • comment — ZIP 파일과 연결된 주석(bytes 객체)

Path 객체 (Path objects)

classzipfile.Path(root, at='')

루트 zipfile에서 Path 객체를 구성해요. at은 zipfile 안에서 이 Path의 위치를 지정해요.

주의: Path 클래스는 ZIP 아카이브 안의 파일 이름을 정화(sanitize)하지 않아요. ZipFile.extract()와 extractall()과 달리 경로 탐색 취약점을 방지하려면 파일 이름을 검증하거나 정화하는 것이 호출자의 책임이에요.

Path 객체는 pathlib.Path 객체의 다음 기능을 노출해요: / 연산자 또는 joinpath로 이동, Path.name, Path.open(), Path.iterdir(), Path.is_dir(), Path.is_file(), Path.is_symlink(), Path.exists(), Path.suffix, Path.stem, Path.suffixes, Path.read_text(), Path.read_bytes(), Path.joinpath().

PyZipFile 객체 (PyZipFile objects)

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

ZipFile 생성자와 같은 매개변수와 optimize 추가 매개변수를 받아요.

  • writepy(pathname, basename='', filterfunc=None) — *.py 파일을 찾아 해당 파일을 아카이브에 추가해요.

ZipInfo 객체 (ZipInfo objects)

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

  • *classmethod ZipInfo.from_file(filename, arcname=None, , strict_timestamps=True) — 파일 시스템의 파일에 대한 ZipInfo 인스턴스를 구성해요.

주요 메서드/속성: is_dir(), filename, date_time, compress_type, comment, extra, create_system, create_version, extract_version, flag_bits, internal_attr, external_attr, header_offset, CRC, compress_size, file_size.

명령줄 인터페이스 (Command-line interface)

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

$ python -m zipfile -c monty.zip spam.txt eggs.txt   # 생성
$ python -m zipfile -e monty.zip target-dir/         # 추출
$ python -m zipfile -l monty.zip                     # 목록

옵션: -l/--list, -c/--create, -e/--extract, -t/--test, --metadata-encoding.

압축 해제 함정 (Decompression pitfalls)

zipfile 모듈의 추출은 여러 함정으로 인해 실패할 수 있어요: 잘못된 비밀번호/CRC 체크섬/ZIP 형식 또는 지원되지 않는 압축 방법/복호화(파일 자체), 다양한 파일 시스템의 한계 초과(파일 시스템 제한), 메모리나 디스크 용량 부족(자원 제한, 압축 해제 폭탄 등), 압축 해제 중 중단(control-C나 프로세스 종료), 그리고 기본 추출 동작을 모르는 것(예: 같은 아카이브를 두 번 추출하면 확인 없이 파일을 덮어씀).

더 알아보기 (Learn more)