Python

tarfile — tar 아카이브 파일 읽기와 쓰기

소스 코드: Lib/tarfile.py

tarfile 모듈은 gzip, bz2 및 lzma 압축을 사용하는 것을 포함하여 tar 아카이브를 읽고 쓸 수 있게 합니다. .zip 파일을 읽거나 쓰려면 zipfile 모듈이나 :ref:`shutil <archiving-operations>`에 있는 고수준 함수를 사용하십시오.

몇 가지 세부 사항:

  • 해당 모듈이 사용 가능한 경우 gzip, bz2, compression.zstd, 및 lzma 압축 아카이브를 읽고 씁니다.

    현재 CPython 사본에 다음 선택적 모듈 중 일부가 누락된 경우, 배포사(즉, Python을 제공한 사람)의 문서를 확인하십시오. 배포사인 경우에는 :ref:`optional-module-requirements`를 참조하십시오.

  • POSIX.1-1988 (ustar) 형식에 대한 읽기/쓰기 지원.

  • longname과 longlink 확장을 포함한 GNU tar 형식에 대한 읽기/쓰기 지원, 스파스(sparse) 파일 복원을 포함하여 모든 sparse 확장 변형에 대한 읽기 전용 지원.

  • POSIX.1-2001 (pax) 형식에 대한 읽기/쓰기 지원.

  • 디렉터리, 일반 파일, 하드 링크, 심볼릭 링크, fifo, 문자 장치 및 블록 장치를 처리하고 타임 스탬프, 액세스 권한 및 소유자와 같은 파일 정보를 획득하고 복원할 수 있습니다.

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

버전 3.12에서 변경: 아카이브는 :ref:`filter <tarfile-extraction-filter>`를 사용하여 추출되며, 이를 통해 놀랍거나 위험한 기능을 제한하거나, 이러한 기능이 예상되었고 아카이브가 완전히 신뢰할 수 있음을 인정하는 것이 가능해집니다.

버전 3.14에서 변경: 기본 추출 필터를 :func:`data <data_filter>`로 설정하면 절대 경로 링크 또는 대상 외부의 경로와 같은 일부 위험한 기능이 비활성화됩니다. 이전에는 이 필터 전략이 :func:`fully_trusted <fully_trusted_filter>`와 동일했습니다.

버전 3.14에서 변경: :mod:`compression.zstd`를 사용하여 Zstandard 압축을 지원하도록 추가되었습니다.

tarfile.open(name=None, mode='r', fileobj=None, bufsize=10240, **kwargs)

경로명 name에 대한 TarFile 객체를 반환합니다. TarFile 객체와 허용되는 키워드 인자에 대한 자세한 정보는 TarFile 객체를 참조하십시오.

mode는 'filemode[:compression]' 형식의 문자열이어야 하며, 기본값은 'r'입니다. 다음은 mode 조합의 전체 목록입니다:

모드

동작

'r' 또는 'r:*'

투명한 압축으로 읽기 위해 엽니다 (권장합니다).

'r:'

압축하지 않고 독점적으로 읽기 위해 엽니다.

'r:gz'

gzip 압축으로 읽기 위해 엽니다.

'r:bz2'

bzip2 압축으로 읽기 위해 엽니다.

'r:xz'

lzma 압축으로 읽기 위해 엽니다.

'r:zst'

Zstandard 압축으로 읽기 위해 엽니다.

'x' 또는 'x:'

압축하지 않고 독점적으로 tar 파일을 만듭니다. 이미 있으면 FileExistsError 예외를 발생시킵니다.

'x:gz'

gzip 압축으로 tar 파일을 만듭니다. 이미 있으면 FileExistsError 예외를 발생시킵니다.

'x:bz2'

bzip2 압축으로 tar 파일을 만듭니다. 이미 있으면 FileExistsError 예외를 발생시킵니다.

'x:xz'

lzma 압축으로 tar 파일을 만듭니다. 이미 있으면 FileExistsError 예외를 발생시킵니다.

'x:zst'

Zstandard 압축으로 tar 파일을 생성합니다. 이미 존재하는 경우 FileExistsError 예외를 발생시킵니다.

'a' 또는 'a:'

압축하지 않고 추가하기 위해 엽니다. 파일이 없으면 만들어집니다.

'w' 또는 'w:'

압축되지 않은 쓰기를 위해 엽니다.

'w:gz'

gzip 압축 쓰기를 위해 엽니다.

'w:bz2'

bzip2 압축 쓰기를 위해 엽니다.

'w:xz'

lzma 압축 쓰기를 위해 엽니다.

'w:zst'

Zstandard 압축 쓰기를 위해 엽니다.

'a:gz', 'a:bz2' 또는 'a:xz'는 불가능함에 유의하십시오. mode가 특정 (압축된) 파일을 읽기 위해 여는 데 적합하지 않으면 ReadError가 발생합니다. 이것을 피하려면 mode 'r'을 사용하십시오. 압축 방법이 지원되지 않으면, CompressionError가 발생합니다.

fileobj가 지정되면, name에 대해 바이너리 모드로 열린 파일 객체의 대안으로 사용됩니다. 위치 0에 있다고 가정합니다.

모드 'w:gz', 'x:gz', 'w|gz', 'w:bz2', 'x:bz2', 'w|bz2'``의 경우, :func:`tarfile.open`은 파일의 압축 수준을 지정하는 키워드 인자 *compresslevel*(기본값 ``6)를 허용합니다.

모드 'w:xz', 'x:xz' 및 'w|xz' 의 경우, tarfile.open() 은 파일의 압축 수준을 지정하는 키워드 인자 preset 을 허용합니다.

For modes 'w:zst', 'x:zst' and 'w|zst', tarfile.open() accepts the keyword argument level to specify the compression level of the file. The keyword argument options may also be passed, providing advanced Zstandard compression parameters described by CompressionParameter. The keyword argument zstd_dict can be passed to provide a ZstdDict, a Zstandard dictionary used to improve compression of smaller amounts of data.

모드 'w:gz' 및 'w|gz' 의 경우, tarfile.open() 은 해당 mtime으로 gzip 아카이브 헤더를 생성하는 키워드 인자 mtime 을 허용합니다. 기본적으로 mtime은 아카이브가 생성된 시간으로 설정됩니다. 재현 가능한 출력을 위해 생성을 시간에 의존하지 않는 압축 스트림을 생성하려면 mtime 0 을 사용하십시오.

특별한 목적으로, mode에는 두 번째 형식이 있습니다: 'filemode|[compression]'. tarfile.open()은 데이터를 블록 스트림으로 처리하는 TarFile 객체를 반환합니다. 파일에서 무작위 탐색(random seeking)을 수행하지 않습니다. 주어지면,, fileobj는 (mode에 따라) 바이트열과 호환되는 read()나 write() 메서드가 있는 임의의 객체일 수 있습니다. bufsize는 블록 크기를 지정하고 기본값은 20 * 512 바이트입니다. 이 변형을 예를 들어 sys.stdin.buffer, 소켓 파일 객체 또는 테이프 장치와 함께 사용하십시오. 그러나, 이러한 TarFile 객체는 무작위 액세스를 허용하지 않는다는 제한이 있습니다 (예를 참조하십시오). 현재 가능한 모드는 다음과 같습니다:

모드

동작

'r|*'

투명한 압축으로 읽기 위해 tar 블록의 스트림을 엽니다.

'r|'

읽기 위해 압축되지 않은 tar 블록의 스트림을 엽니다.

'r|gz'

읽기 위해 gzip 압축 스트림을 엽니다.

'r|bz2'

읽기 위해 bzip2 압축 스트림을 엽니다.

'r|xz'

읽기 위해 lzma 압축 스트림을 엽니다.

'r|zst'

Zstandard 압축 스트림 을 읽기 위해 엽니다.

'w|'

쓰기 위해 압축되지 않은 스트림을 엽니다.

'w|gz'

쓰기 위해 gzip 압축 스트림을 엽니다.

'w|bz2'

쓰기 위해 bzip2 압축 스트림을 엽니다.

'w|xz'

쓰기 위해 lzma 압축 스트림을 엽니다.

'w|zst'

Zstandard 압축 스트림 을 쓰기 위해 엽니다.

버전 3.5에서 변경: 'x' (독점 생성) 모드가 추가되었습니다.

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

버전 3.12에서 변경: compresslevel 키워드 인자는 스트림에도 적용됩니다.

버전 3.14에서 변경: preset 키워드 인자 또한 스트림에 적용됩니다.

버전 3.15에서 변경: 기본 압축 수준이 9에서 6으로 낮춰졌습니다. 이 수준은 대부분의 압축 도구에서 사용되는 기본 수준이며 속도와 성능 간에 더 나은 균형을 제공합니다.

class tarfile.TarFile

tar 아카이브를 읽고 쓰는 클래스. 이 클래스를 직접 사용하지 마십시오: 대신 tarfile.open()을 사용하십시오. TarFile 객체를 참조하십시오.

tarfile.is_tarfile(name)

만약 name 이 tarfile 모듈에서 읽을 수 있는 tar 아카이브 파일이면 True 를 반환합니다. name 은 str, 파일 또는 파일류 객체일 수 있습니다.

버전 3.9에서 변경: 파일과 파일류 객체 지원.

tarfile 모듈은 다음 예외들을 정의합니다:

exception tarfile.TarError

모든 tarfile 예외들의 베이스 클래스입니다.

exception tarfile.ReadError

tarfile 모듈에서 처리할 수 없거나 어떤 식으로든 유효하지 않은 tar 아카이브가 열릴 때 발생합니다.

exception tarfile.CompressionError

압축 방법이 지원되지 않거나 데이터를 올바르게 디코딩할 수 없을 때 발생합니다.

exception tarfile.StreamError

스트림류 TarFile 객체에 일반적인 제한 사항으로 인해 발생합니다.

exception tarfile.ExtractError

TarFile.extract()를 사용할 때 치명적이지 않은 에러에 대해 발생하지만, TarFile.errorlevel== 2일 때만 발생합니다.

exception tarfile.HeaderError

버퍼가 유효하지 않을 때 TarInfo.frombuf()에 의해 발생합니다.

exception tarfile.FilterError

필터에 의해 거부된 멤버의 베이스 클래스입니다.

tarinfo

필터가 추출을 거부한 멤버에 대한 정보는 TarInfo 형식으로 제공됩니다.

exception tarfile.AbsolutePathError

절대 경로를 가진 멤버의 추출을 거부할 때 발생합니다.

exception tarfile.OutsideDestinationError

대상 디렉터리 외부에 있는 멤버의 추출을 거부할 때 발생합니다.

exception tarfile.SpecialFileError

특별한 파일(예: 장치 또는 파이프)의 추출을 거부할 때 발생합니다.

exception tarfile.AbsoluteLinkError

절대 경로를 가진 심볼릭 링크의 추출을 거부할 때 발생합니다.

exception tarfile.LinkOutsideDestinationError

대상 디렉터리 외부를 가리키는 심볼릭 링크의 추출을 거부할 때 발생합니다.

exception tarfile.LinkFallbackError

링크를 에뮬레이션하여 다른 아카이브 멤버를 추출하는 것을 거부할 때 발생합니다 (하드 링크 또는 심볼릭 링크). 이 멤버가 필터 위치에서 거부될 경우에 해당하며, 대체된 멤버를 거절하기 위해 발생한 예외는 :attr:`!BaseException.__context__`에서 확인할 수 있습니다.

Added in version 3.15.

모듈 수준에서 다음 상수를 사용할 수 있습니다:

tarfile.ENCODING

기본 문자 인코딩: 윈도우의 경우 'utf-8', 그렇지 않으면 sys.getfilesystemencoding() 이 반환하는 값.

tarfile.REGTYPE
tarfile.AREGTYPE

일반 파일 type.

tarfile.LNKTYPE

링크 (tarfile 내부) type.

tarfile.SYMTYPE

심볼릭 링크 type.

tarfile.CHRTYPE

문자 특수 장치 type.

tarfile.BLKTYPE

블록 특수 장치 type.

tarfile.DIRTYPE

디렉터리 type.

tarfile.FIFOTYPE

FIFO 특수 장치 type.

tarfile.CONTTYPE

연속 파일 type.

tarfile.GNUTYPE_LONGNAME

GNU tar 긴 이름: type.

GNU tar 긴 링크: type.

tarfile.GNUTYPE_SPARSE

GNU tar 희소 파일 type.

다음의 각 상수는 tarfile 모듈이 생성할 수 있는 tar 아카이브 형식을 정의합니다. 자세한 내용은 지원되는 tar 형식 섹션을 참조하십시오.

tarfile.USTAR_FORMAT

POSIX.1-1988 (ustar) 형식.

tarfile.GNU_FORMAT

GNU tar 형식.

tarfile.PAX_FORMAT

POSIX.1-2001 (pax) 형식.

tarfile.DEFAULT_FORMAT

아카이브를 만들기 위한 기본 형식. 이것은 현재 PAX_FORMAT입니다.

버전 3.8에서 변경: 새 아카이브의 기본 형식이 GNU_FORMAT에서 PAX_FORMAT으로 변경되었습니다.

더 보기

모듈 zipfile

zipfile 표준 모듈의 설명서.

아카이브 연산

표준 shutil 모듈이 제공하는 고수준 아카이브 기능에 대한 설명서.

GNU tar manual, Basic Tar Format

GNU tar 확장을 포함한, tar 아카이브 파일에 대한 설명서.

TarFile 객체

TarFile 객체는 tar 아카이브에 대한 인터페이스를 제공합니다. tar 아카이브는 블록의 시퀀스입니다. 아카이브 멤버(저장된 파일)는 헤더 블록과 그 뒤에 오는 데이터 블록으로 구성됩니다. tar 아카이브에 파일을 여러 번 저장할 수 있습니다. 각 아카이브 멤버는 TarInfo 객체로 표현됩니다. 세부 사항은 TarInfo 객체를 참조하십시오.

TarFile 객체는 with 문에서 컨텍스트 관리자로 사용될 수 있습니다. 블록이 완료되면 자동으로 닫힙니다. 예외가 있는 경우, 쓰기 위해 열린 아카이브는 마무리되지 않음에 유의하십시오; 내부적으로 사용된 파일 객체만 닫힙니다. 사용 사례는 예 섹션을 참조하십시오.

Added in version 3.2: 컨텍스트 관리 프로토콜에 대한 지원이 추가되었습니다.

class tarfile.TarFile(name=None, mode='r', fileobj=None, format=DEFAULT_FORMAT, tarinfo=TarInfo, dereference=False, ignore_zeros=False, encoding=ENCODING, errors='surrogateescape', pax_headers=None, debug=0, errorlevel=1, stream=False)

다음의 모든 인자는 선택적이며 인스턴스 어트리뷰트로도 액세스 할 수 있습니다.

name은 아카이브의 경로명입니다. name은 경로류 객체일 수 있습니다. fileobj가 주어지면 생략할 수 있습니다. 이 경우, 파일 객체의 name 어트리뷰트가 있다면 사용됩니다.

mode는 기존 아카이브에서 읽는 'r', 기존 파일에 데이터를 추가하는 'a', 기존 파일을 덮어쓰는 새 파일을 만드는 'w' 또는 존재하지 않을 때만 새 파일을 만드는 'x'입니다.

fileobj가 주어지면, 데이터를 읽거나 쓰는 데 사용됩니다. 그것이 결정될 수 있다면, mode는 fileobj의 모드에 의해 재정의됩니다. fileobj는 위치 0에서 사용됩니다.

참고

TarFile이 닫힐 때, fileobj는 닫히지 않습니다.

format은 쓰기를 위한 아카이브 형식을 제어합니다. 모듈 수준에서 정의되는 상수 USTAR_FORMAT, GNU_FORMAT 또는 PAX_FORMAT 중 하나여야 합니다. 읽을 때, 형식은 자동 감지됩니다, 단일 아카이브에 다른 형식이 존재할 때조차 그렇습니다.

tarinfo 인자를 사용하여 기본 TarInfo 클래스를 다른 클래스로 바꿀 수 있습니다.

dereference가 False이면, 아카이브에 심볼릭과 하드 링크를 추가합니다. True이면, 대상 파일의 내용을 아카이브에 추가합니다. 이는 심볼릭 링크를 지원하지 않는 시스템에는 영향을 미치지 않습니다.

ignore_zeros가 False이면, 빈 블록을 아카이브의 끝으로 처리합니다. True이면, 비어있는 (그래서 잘못된) 블록을 건너뛰고 최대한 많은 멤버를 확보하려고 합니다. 이어붙였거나 손상된 아카이브를 읽을 때만 유용합니다.

debug는 0(디버그 메시지 없음)에서 3(모든 디버그 메시지)까지 설정할 수 있습니다. 메시지는 sys.stderr에 기록됩니다.

errorlevel 은 추출 오류 처리를 제어하며, 이와 관련된 속성인 the corresponding attribute 를 참조하십시오.

encoding과 errors 인자는 아카이브를 읽거나 쓰는 데 사용되는 문자 인코딩과 변환 에러 처리 방법을 정의합니다. 기본 설정은 대부분의 사용자에게 적용됩니다. 자세한 정보는 유니코드 문제 섹션을 참조하십시오.

pax_headers 인자는 선택적인 문자열의 딕셔너리로, format이 PAX_FORMAT이면 pax 전역 헤더로 추가됩니다.

stream 이 True 로 설정되면 아카이브 파일 정보는 캐시되지 않아 메모리를 절약할 수 있습니다.

버전 3.2에서 변경: errors 인자의 기본값으로 'surrogateescape'를 사용합니다.

버전 3.5에서 변경: 'x' (독점 생성) 모드가 추가되었습니다.

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

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

classmethod TarFile.open(...)

대체 생성자. tarfile.open() 함수는 실제로 이 클래스 메서드의 바로 가기입니다.

TarFile.getmember(name)

멤버 name에 대한 TarInfo 객체를 반환합니다. 아카이브에서 name을 찾을 수 없으면 KeyError가 발생합니다.

참고

아카이브에서 멤버가 두 번 이상 등장하면, 마지막 등장을 최신 버전으로 간주합니다.

TarFile.getmembers()

아카이브 멤버를 TarInfo 객체의 리스트로 반환합니다. 리스트는 아카이브의 멤버와 순서가 같습니다.

TarFile.getnames()

멤버를 이름의 리스트로 반환합니다. getmembers()가 반환하는 리스트와 순서가 같습니다.

TarFile.list(verbose=True, *, members=None)

목차를 sys.stdout으로 인쇄합니다. verbose가 False이면, 멤버 이름만 인쇄됩니다. True이면, ls -l과 유사한 출력이 생성됩니다. 선택적 members가 제공되면, getmembers()가 반환한 리스트의 부분집합이어야 합니다.

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

TarFile.next()

TarFile을 읽기 위해 열었을 때, 아카이브의 다음 멤버를 TarInfo 객체로 반환합니다. 더는 없으면, None을 반환합니다.

TarFile.extractall(path='.', members=None, *, numeric_owner=False, filter=None)

아카이브의 모든 멤버(members)를 현재 작업 디렉터리나 디렉터리 path로 추출합니다. 선택적 members가 제공되면, getmembers()가 반환하는 리스트의 부분집합이어야 합니다. 소유자, 수정 시간 및 권한과 같은 디렉터리 정보는 모든 멤버가 추출된 후에 설정됩니다. 이것은 두 가지 문제를 해결하기 위한 것입니다: 디렉터리의 수정 시간은 파일이 생성될 때마다 재설정됩니다. 또한 디렉터리의 권한이 쓰기를 허용하지 않으면, 파일 추출이 실패합니다.

numeric_owner가 True이면, tar 파일의 uid와 gid 번호는 추출된 파일의 소유자/그룹을 설정하는 데 사용됩니다. 그렇지 않으면, tar 파일의 이름값이 사용됩니다.

filter 인수는 추출 전에 members 가 수정되거나 거부되는 방식을 지정합니다. 자세한 내용은 추출 필터입니다. 를 참조하십시오. 특정 tar 기능이 필요하거나, 보안 수준이 낮은 기본값(3.13 이하)을 지원하기 위해 filter='data' 로 설정하는 경우에만 명시적으로 설정하는 것이 좋습니다.

경고

사전 검사 없이 신뢰할 수 없는 출처의 아카이브를 추출하지 마십시오.

Python 3.14부터 기본값인 (data)는 가장 위험한 보안 문제를 방지합니다. 그러나 모든 의도치 않거나 안전하지 않은 동작을 막지는 못합니다. 자세한 내용은 추출 필터입니다. 섹션을 참조하십시오.

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

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

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

버전 3.14에서 변경: filter 매개 변수의 기본값이 이제 'data' 로 설정됩니다.

TarFile.extract(member, path='', set_attrs=True, *, numeric_owner=False, filter=None)

전체 이름을 사용하여, 아카이브에서 현재 작업 디렉터리로 멤버(member)를 추출합니다. 파일 정보는 최대한 정확하게 추출됩니다. member는 파일명이나 TarInfo 객체일 수 있습니다. path를 사용하여 다른 디렉터리를 지정할 수 있습니다. path는 경로류 객체일 수 있습니다. set_attrs가 거짓이 아닌 한 파일 어트리뷰트(소유자, 수정 시간, 모드)가 설정됩니다.

numeric_owner 및 filter 인수는 :meth:`extractall`과 동일합니다.

참고

extract() 메서드는 여러 추출 문제를 처리하지 않습니다. 대부분의 경우 extractall() 메서드 사용을 고려해야 합니다.

경고

사전 검사 없이 신뢰할 수 없는 출처의 아카이브를 추출하지 마십시오. 자세한 내용은 :meth:`extractall`의 경고 메시지를 참조하십시오.

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

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

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

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

TarFile.extractfile(member)

아카이브에서 멤버(member)를 파일 객체로 추출합니다. member는 파일명이나 TarInfo 객체일 수 있습니다. member가 일반 파일이나 링크이면, io.BufferedReader 객체가 반환됩니다. 다른 모든 기존 멤버에 대해서는, None이 반환됩니다. member가 아카이브에 없으면, KeyError가 발생합니다.

버전 3.3에서 변경: io.BufferedReader 객체를 반환합니다.

버전 3.13에서 변경: 반환되는 io.BufferedReader 객체는 항상 'rb' 와 같은 mode 속성을 가지고 있습니다.

TarFile.errorlevel: int

errorlevel이 0이면, TarFile.extract()와 TarFile.extractall()를 사용할 때 에러가 무시됩니다. 그런데도, debug이 0보다 크면, 디버그 출력에 에러 메시지로 나타납니다. 1이면 (기본값), 모든 치명적 에러가 OSError나 FilterError 예외로 발생합니다. 2이면, 모든 치명적이지 않은 에러도 TarError 예외로 발생합니다.

잘못된 인자 유형이나 데이터 손상으로 인해 발생하는 등의 일부 예외는 항상 발생합니다.

사용자 정의 :ref:`추출 필터 <tarfile-extraction-filter>`는 fatal 오류의 경우 :exc:`FilterError`를, non-fatal 오류의 경우 :exc:`ExtractError`를 발생시켜야 합니다.

예외가 발생할 때 아카이브가 부분적으로 추출될 수 있다는 점에 유념하십시오. 정리하는 것은 사용자 책임입니다.

TarFile.extraction_filter

Added in version 3.12.

extract() 및 ~TarFile.extractall`의 *filter* 인수에 기본값으로 사용되는 :ref:`추출 필터.

이 속성은 None 일 수 있거나 호출 가능한 객체일 수 있습니다. 이 속성은 extract() 의 filter 인자와 달리 문자열 이름은 허용되지 않습니다.

extraction_filter 가 None (기본값)이면, 추출 메서드가 기본적으로 data_ 필터를 사용합니다.

이 속성은 인스턴스에 설정되거나 서브클래스에서 재정의될 수 있습니다. 또한, 전역 기본값을 설정하기 위해 TarFile 클래스 자체에 설정하는 것도 가능하지만, tarfile 의 모든 사용에 영향을 미치므로, 최상위 애플리케이션이나 site configuration 에서만 하는 것이 가장 좋습니다. 이 방식으로 전역 기본값을 설정하려면, 인자 self 가 주입되는 것을 방지하기 위해 필터 함수를 @staticmethod 로 감싸야 합니다.

버전 3.14에서 변경: 기본 필터는 :func:`data <data_filter>`로 설정되어 있으며, 이는 절대 경로 링크나 대상 외부의 경로와 같이 일부 위험한 기능을 비활성화합니다. 이전에 기본값은 :func:`fully_trusted <fully_trusted_filter>``과 동등했습니다.

TarFile.add(name, arcname=None, recursive=True, *, filter=None)

name 파일을 아카이브에 추가합니다. name은 모든 유형의 파일(디렉터리, fifo, 심볼릭 링크 등)일 수 있습니다. 지정되면, arcname은 아카이브에 있는 파일의 대체 이름을 지정합니다. 디렉터리는 기본적으로 재귀적으로 추가됩니다. recursive를 False로 설정하면, 이를 피할 수 있습니다. 재귀는 항목을 정렬된 순서로 추가합니다. filter가 제공되면, TarInfo 객체 인자를 취하고 변경된 TarInfo 객체를 반환하는 함수여야 합니다. 이것이 대신 None을 반환하면, TarInfo 객체가 아카이브에서 제외됩니다. 예는 예를 참조하십시오.

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

버전 3.7에서 변경: 재귀는 항목을 정렬된 순서로 추가합니다.

TarFile.addfile(tarinfo, fileobj=None)

TarInfo 객체 tarinfo를 아카이브에 추가합니다. tarinfo가 0이 아닌 크기의 일반 파일이면, fileobj 인자는 바이너리 파일이어야 하고, 여기서 tarinfo.size 바이트를 읽어서 아카이브에 추가합니다. TarInfo 객체를 직접 혹은 gettarinfo()를 사용하여 만들 수 있습니다.

버전 3.13에서 변경: 비-제로 크기의 일반 파일에는 fileobj 를 지정해야 합니다.

TarFile.gettarinfo(name=None, arcname=None, fileobj=None)

기존 파일에서 os.stat()이나 이와 동등한 것의 결과로부터 TarInfo 객체를 만듭니다. 파일은 name으로 이름을 지정하거나, 파일 기술자를 갖는 파일 객체 fileobj로 지정됩니다. name은 경로류 객체일 수 있습니다. 주어지면, arcname은 아카이브에 있는 파일의 대체 이름을 지정하고, 그렇지 않으면, 이름은 fileobj의 name 어트리뷰트나 name 인자에서 취합니다. 이름은 텍스트 문자열이어야 합니다.

addfile()을 사용하여 추가하기 전에 TarInfo의 일부 어트리뷰트를 수정할 수 있습니다. 파일 객체가 파일의 시작 부분에 위치한 일반 파일 객체가 아니면, size와 같은 어트리뷰트를 수정해야 할 수 있습니다. GzipFile과 같은 객체가 이 상황에 해당합니다. name도 수정될 수 있으며, 이 경우 arcname은 더미 문자열일 수 있습니다.

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

TarFile.close()

TarFile을 닫습니다. 쓰기 모드에서는, 두 개의 마무리 0블록이 아카이브에 추가됩니다.

TarFile.pax_headers: dict

pax 전역 헤더의 키-값 쌍을 포함하는 딕셔너리.

TarInfo 객체

TarInfo 객체는 TarFile에 있는 하나의 멤버를 나타냅니다. 파일의 모든 필수 어트리뷰트(파일 유형, 크기, 시간, 권한, 소유자 등과 같은)를 저장하는 것 외에도, 파일 유형을 결정하는 유용한 메서드를 제공합니다. 파일의 데이터 자체를 포함하지 않습니다.

TarInfo 객체는 TarFile의 메서드 getmember(), getmembers() 및 gettarinfo()에 의해 반환됩니다.

getmember() 또는 replace() 메서드를 호출하여 한 단계에서 수정된 복사본을 만드십시오.

None 이 설정할 수 있는 몇 가지 어트리뷰트는 해당 메타데이터가 사용되지 않거나 неизвест다는 것을 나타냅니다. 다양한 TarInfo 메서드는 None 을 다르게 처리합니다:

  • extract() 또는 extractall() 메서드는 해당 메타데이터를 무시하고 기본값으로 유지합니다.

  • addfile() 사용 시 실패합니다.

  • :meth:`~TarFile.list`는 플레이스홀더 문자열을 출력합니다.

class tarfile.TarInfo(name='')

TarInfo 객체를 만듭니다.

classmethod TarInfo.frombuf(buf, encoding, errors)

문자열 버퍼 buf에서 TarInfo 객체를 만들고 반환합니다.

버퍼가 유효하지 않으면 HeaderError를 발생시킵니다.

classmethod TarInfo.fromtarfile(tarfile)

TarFile 객체 tarfile에서 다음 멤버를 읽고 TarInfo 객체로 반환합니다.

TarInfo.tobuf(format=DEFAULT_FORMAT, encoding=ENCODING, errors='surrogateescape')

TarInfo 객체에서 문자열 버퍼를 만듭니다. 인자에 대한 정보는 TarFile 클래스의 생성자를 참조하십시오.

버전 3.2에서 변경: errors 인자의 기본값으로 'surrogateescape'를 사용합니다.

TarInfo 객체에는 다음과 같은 공개 데이터 어트리뷰트가 있습니다:

TarInfo.name: str

아카이브 멤버의 이름

TarInfo.size: int

바이트 단위의 크기.

TarInfo.mtime: int | float

epoch 이후 초 단위의 마지막 수정 시간입니다. 이는 :attr:`os.stat_result.st_mtime`에서 볼 수 있습니다.

버전 3.12에서 변경: extract() 및 extractall() 에 대해 None 으로 설정할 수 있으며, 이 경우 추출 시 해당 어트리뷰트를 적용하는 과정이 건너<0xEB><0x9C><0x81>니다.

TarInfo.mode: int

:func:`os.chmod`와 같은 권한 비트입니다.

버전 3.12에서 변경: extract() 및 extractall() 에 대해 None 으로 설정할 수 있으며, 이 경우 추출 시 해당 어트리뷰트를 적용하는 과정이 건너<0xEB><0x9C><0x81>니다.

TarInfo.type

파일 유형. type은 일반적으로 다음 상수 중 하나입니다: REGTYPE, AREGTYPE, LNKTYPE, SYMTYPE, DIRTYPE, FIFOTYPE, CONTTYPE, CHRTYPE, BLKTYPE, GNUTYPE_SPARSE. TarInfo 객체의 유형을 더 편리하게 결정하려면, 아래 is*() 메서드를 사용하십시오.

TarInfo.linkname: str

대상 파일 이름의 이름, LNKTYPE과 SYMTYPE 유형의 TarInfo 객체에만 존재합니다.

심볼릭 링크(SYMTYPE)의 경우, linkname 은 해당 링크가 포함된 디렉터리를 기준으로 합니다. 하드 링크(LNKTYPE)의 경우, linkname 은 아카이브 루트를 기준으로 합니다.

TarInfo.uid: int

이 멤버를 처음 저장한 사용자의 사용자 ID.

버전 3.12에서 변경: extract() 및 extractall() 에 대해 None 으로 설정할 수 있으며, 이 경우 추출 시 해당 어트리뷰트를 적용하는 과정이 건너<0xEB><0x9C><0x81>니다.

TarInfo.gid: int

이 멤버를 처음 저장한 사용자의 그룹 ID.

버전 3.12에서 변경: extract() 및 extractall() 에 대해 None 으로 설정할 수 있으며, 이 경우 추출 시 해당 어트리뷰트를 적용하는 과정이 건너<0xEB><0x9C><0x81>니다.

TarInfo.uname: str

사용자 이름.

버전 3.12에서 변경: extract() 및 extractall() 에 대해 None 으로 설정할 수 있으며, 이 경우 추출 시 해당 어트리뷰트를 적용하는 과정이 건너<0xEB><0x9C><0x81>니다.

TarInfo.gname: str

그룹 이름.

버전 3.12에서 변경: extract() 및 extractall() 에 대해 None 으로 설정할 수 있으며, 이 경우 추출 시 해당 어트리뷰트를 적용하는 과정이 건너<0xEB><0x9C><0x81>니다.

TarInfo.chksum: int

헤더 체크섬입니다.

TarInfo.devmajor: int

장치 주 번호입니다.

TarInfo.devminor: int

장치 부 번호입니다.

TarInfo.offset: int

tar 헤더는 여기서 시작합니다.

TarInfo.offset_data: int

파일 데이터는 여기서 시작합니다.

TarInfo.sparse

희소 멤버 정보입니다.

TarInfo.pax_headers: dict

연관된 pax 확장 헤더의 키-값 쌍을 포함하는 딕셔너리.

TarInfo.replace(name=..., mtime=..., mode=..., linkname=..., uid=..., gid=..., uname=..., gname=..., deep=True)

Added in version 3.12.

주어진 어트리뷰트를 사용하여 새 TarInfo 객체를 반환합니다. 예를 들어, 그룹 이름을 'staff' 로 설정하는 TarInfo 를 반환하려면 다음을 사용하십시오:

new_tarinfo = old_tarinfo.replace(gname='staff')

기본적으로 깊은 복사본이 생성됩니다. deep 이 false인 경우, 복사본은 얕은 복사이므로 pax_headers 및 기타 사용자 정의 어트리뷰트는 원본 TarInfo 객체와 공유됩니다.

TarInfo 객체는 편리한 조회 메서드도 제공합니다:

TarInfo.isfile()

TarInfo 객체가 일반 파일이면 True를 반환합니다.

TarInfo.isreg()

isfile()과 같습니다.

TarInfo.isdir()

디렉터리이면 True를 반환합니다.

TarInfo.issym()

심볼릭 링크이면 True를 반환합니다.

TarInfo.islnk()

하드 링크이면 True를 반환합니다.

TarInfo.ischr()

문자 장치이면 True를 반환합니다.

TarInfo.isblk()

블록 장치이면 True를 반환합니다.

TarInfo.isfifo()

FIFO이면 True를 반환합니다.

TarInfo.isdev()

문자 장치, 블록 장치 또는 FIFO 중 하나이면 True를 반환합니다.

추출 필터입니다.

Added in version 3.12.

tar 형식은 유닉스 계열 파일시스템의 모든 세부 사항을 캡처하도록 설계되었기 때문에 매우 강력합니다. 불행하게도, 이러한 기능들이 의도치 않거나 아닐 수 있는 – 그리고 잠재적으로 악의적인 – 영향을 주는 tar 파일을 만들기 쉽게 만듭니다. 예를 들어, tar 파일을 추출하는 것은 임의의 파일을 다양한 방식으로 덮어쓸 수 있습니다 (예: 절대 경로를 사용하거나, .. 경로 구성 요소를 사용하거나, 나중 멤버에 영향을 미치는 심볼릭 링크 등을 사용하는 경우).

대부분의 경우 전체 기능은 필요하지 않습니다. 따라서 tarfile 은 추출 필터(extraction filters)를 지원하며, 이는 기능을 제한하여 일부 보안 문제를 완화하는 메커니즘입니다.

경고

사용 가능한 필터 중 어느 것도 모든 위험한 아카이브 기능을 차단하지 못합니다. 사전 검사 없이 신뢰할 수 없는 출처의 아카이브를 추출하지 마십시오. :ref:`tarfile-further-verification`도 참조하십시오.

더 보기

PEP 706

설계에 대한 추가적인 동기 부여와 근거를 포함합니다.

TarFile.extract() 또는 :meth:`~TarFile.extractall`의 filter 인자는 다음과 같을 수 있습니다:

  • 문자열 'fully_trusted': 아카이브에 지정된 모든 메타데이터를 존중합니다. 사용자가 아카이브를 완전히 신뢰하거나 자체 복잡한 검증을 구현하는 경우 사용해야 합니다.

  • 문자열 'tar': 대부분의 tar 특정 기능(즉, 유닉스 계열 파일시스템의 기능)은 존중하지만, 놀랍거나 악의적일 가능성이 매우 높은 기능은 차단합니다. 자세한 내용은 :func:`tar_filter`를 참조하십시오.

  • 문자열 'data': 유닉스 계열 파일시스템에 특화된 대부분의 기능을 무시하거나 차단합니다. 크로스 플랫폼 데이터 아카이브 추출용으로 의도되었습니다. 자세한 내용은 :func:`data_filter`를 참조하십시오.

  • None (기본값): :attr:`TarFile.extraction_filter`을 사용합니다.

    이 또한 None``인 경우(기본값), ``'data' 필터가 사용됩니다.

    버전 3.14에서 변경: 기본 필터는 :func:`data <data_filter>`로 설정되어 있습니다. 이전에 기본값은 :func:`fully_trusted <fully_trusted_filter>`와 동등했습니다.

  • 추출된 각 멤버에 대해, 해당 멤버를 설명하는 :ref:`TarInfo <tarinfo-objects>`와 아카이브가 추출되는 대상 경로를 인수로 받는 콜러블입니다 (즉, 모든 멤버에 동일한 경로가 사용됨):

    filter(member: TarInfo, path: str, /) -> TarInfo | None

    이 콜러블은 각 멤버가 추출되기 직전에 호출되므로, 현재 디스크 상태를 고려할 수 있습니다. 다음 동작을 수행할 수 있습니다:

    • 아카이브의 메타데이터 대신 사용될 TarInfo 객체를 반환하거나, 또는

    • None 을 반환하여 멤버를 건너뛰게 할 수 있습니다. 또는

    • 예외를 발생시켜 작업을 중단하거나 멤버를 건너뛸 수 있으며, 이는 :attr:`~TarFile.errorlevel`에 따라 달라집니다. 추출이 중단될 경우, :meth:`~TarFile.extractall`은 아카이브가 부분적으로만 추출된 상태로 남을 수 있습니다. 정리 작업을 시도하지 않습니다.

기본 명명 필터입니다.

사전 정의된 명명 필터는 함수로 사용할 수 있어 사용자 정의 필터에 재사용할 수 있습니다:

tarfile.fully_trusted_filter(member, path)

member 를 변경 없이 반환합니다.

이는 'fully_trusted' 필터를 구현합니다.

tarfile.tar_filter(member, path)

'tar' 필터를 구현합니다.

  • 파일명에서 선행 슬래시(/ 및 os.sep)를 제거합니다.

  • Refuse 는 절대 경로 파일로의 추출을 거부합니다 (슬래시를 제거한 후에도 이름이 절대 경로인 경우, 예를 들어 Windows에서 C:/foo 와 같습니다). 이 때 AbsolutePathError 가 발생합니다.

  • :ref:`Refuse <tarfile-extraction-refuse>`는 추적하는 심볼릭 링크의 절대 경로가 대상 디렉터리 밖에 위치하게 되는 파일로의 추출을 거부합니다. 이 때 :class:`~tarfile.OutsideDestinationError`가 발생합니다.

  • 고성능 모드 비트(setuid, setgid, sticky) 및 그룹/기타 쓰기 비트(S_IWGRP | S_IWOTH)를 제거합니다.

수정된 TarInfo 멤버를 반환합니다.

tarfile.data_filter(member, path)

'data' 필터를 구현합니다. `tar_filter`가 하는 작업 외에 추가되는 사항:

  • 링크 대상(TarInfo.linkname)을 os.path.normpath`를 사용하여 정규화합니다. 이 과정에서 내부 `()..`` 구성요소가 제거될 수 있으며, 만약 :attr:`!TarInfo.linkname`의 경로가 심볼릭 링크를 순회하는 경우 링크의 의미가 변경될 수 있습니다.

  • :ref:`Refuse <tarfile-extraction-refuse>`는 절대 경로를 가리키거나 대상 디렉터리 외부를 가리키는 링크(하드 또는 소프트)의 추출을 거부합니다.

    이 경우 AbsoluteLinkError 또는 :class:`~tarfile.LinkOutsideDestinationError`가 발생합니다.

    이러한 파일은 심볼릭 링크를 지원하지 않는 플랫폼에서도 거부됩니다.

  • :ref:`Refuse <tarfile-extraction-refuse>`는 장치 파일(파이프 포함)의 추출을 거부합니다. 이 때 :class:`~tarfile.SpecialFileError`가 발생합니다.

  • 일반 파일, 하드 링크 포함:

    • 소유자의 읽기 및 쓰기 권한(S_IRUSR | S_IWUSR)을 설정합니다.

    • 소유자가 해당 권한(S_IXUSR)을 가지고 있지 않은 경우, 그룹 및 기타 실행 권한(S_IXGRP | S_IXOTH)을 제거합니다.

  • 다른 파일(디렉터리)의 경우, mode 를 None 으로 설정하여 추출 메서드가 권한 비트를 적용하는 것을 건너뛰게 합니다.

  • 사용자 및 그룹 정보 (uid, gid, uname, gname)를 None 으로 설정하여 추출 메서드가 이를 설정하는 것을 건너뛰게 합니다.

수정된 TarInfo 멤버를 반환합니다.

이 필터가 모든 위험한 아카이브 기능을 차단하는 것은 아니라는 점에 유의하십시오(all). 자세한 내용은 :ref:`tarfile-further-verification`을 참조하십시오.

버전 3.15에서 변경: 링크 대상은 이제 정규화됩니다.

필터 오류

필터가 파일을 추출하는 것을 거부할 경우, 적절한 예외를 발생시키며 이는 FilterError 의 하위 클래스입니다. 이 때 TarFile.errorlevel 이 1 이상이면 추출 작업이 중단됩니다. errorlevel=0 인 경우 오류는 기록되지만 멤버는 건너뛰고 추출은 계속 진행합니다.

추가 검증을 위한 힌트

filter='data' 를 사용하더라도 tarfile 은 사전 검사 없이 신뢰할 수 없는 파일을 추출하는 데 적합하지 않습니다. 기타 문제점들 중에서도, 사전에 정의된 필터는 서비스 거부 공격을 방지하지 못합니다. 사용자들은 추가적인 확인 절차를 수행해야 합니다.

고려할 수 있는 사항 목록은 다음과 같으며, 이는 불완전한 목록입니다:

  • 예를 들어, 사전에 존재하는 링크를 악용하는 것을 방지하고 실패한 추출 후 정리 작업을 더 쉽게 하기 위해 :func:`new temporary directory <tempfile.mkdtemp>`로 추출하십시오.

  • 기능이 필요하지 않다면 심볼릭 링크를 비허용합니다.

  • 신뢰할 수 없는 데이터를 다룰 때는 디스크, 메모리 및 CPU 사용량에 대한 외부적 (예: OS 수준) 제한을 사용하십시오.

  • 파일명이 문자 허용 목록(제어 문자, 혼동 가능 문자, 외국 경로 구분자 등의 필터링)과 일치하는지 확인합니다.

  • 파일 이름에 예상되는 확장자가 있는지 확인합니다 (사용자가 “클릭”할 때 실행되는 파일을 방지하거나, Windows의 특수 장치명과 같은 확장자 없는 파일들을 방지함).

  • 추출 파일 개수, 추출 데이터 총 크기, 파일 이름 길이(심볼릭 링크 길이 포함), 그리고 개별 파일의 크기를 제한합니다.

  • 대소문자 구분하지 않는 파일 시스템에서 섀도우될 수 있는 파일을 확인합니다.

또한 다음 사항에 유의하십시오:

  • Tar 파일에는 동일한 파일의 여러 버전이 포함될 수 있습니다. 나중에 생성된 버전들이 이전 버전을 덮어쓸 것으로 예상됩니다. 이 기능은 테이프 아카이브 업데이트를 허용하는 데 중요하지만, 악의적으로 오용될 수 있습니다.

  • tarfile 은 추출 또는 아카이빙 진행 중 대상(또는 원본) 디렉터리에서 공격자가 조작하는 것과 같은 “실시간” 데이터와 관련된 문제는 보호하지 못합니다.

구형 Python 버전 지원

Python 3.12에서는 추출 필터가 추가되었지만, 보안 업데이트로 인해 이전 버전에도 백포팅될 수 있습니다. 기능 사용 가능 여부를 확인하려면 Python 버전을 확인하는 대신 `hasattr(tarfile, ‘data_filter’)`와 같은 방식으로 사용하십시오.

다음 예제들은 기능 유무에 따라 파이썬 버전을 지원하는 방법을 보여줍니다. extraction_filter 를 설정하면 이후의 모든 작업에 영향을 미린다는 점에 유의하십시오.

  • 완전히 신뢰할 수 있는 아카이브:

    my_tarfile.extraction_filter = (lambda member, path: member)
my_tarfile.extractall()

  • 사용 가능한 경우 'data' 필터를 사용하되, 이 기능이 사용 가능하지 않은 경우에는 파이썬 3.11의 동작('fully_trusted')으로 돌아갑니다:

    my_tarfile.extraction_filter = getattr(tarfile, 'data_filter',
                                       (lambda member, path: member))
my_tarfile.extractall()

  • 'data' 필터를 사용하고, 그것을 사용할 수 없으면 실패 (fail)합니다:

    my_tarfile.extractall(filter=tarfile.data_filter)

    또는:

    my_tarfile.extraction_filter = tarfile.data_filter
my_tarfile.extractall()

  • 'data' 필터를 사용하고, 그것을 사용할 수 없으면 경고 (warn)합니다:

    if hasattr(tarfile, 'data_filter'):
    my_tarfile.extractall(filter='data')
else:
    # 더는 필요하지 않을 때 제거하세요
    warn_the_user('Extracting may be unsafe; consider updating Python')
    my_tarfile.extractall()

상태 유지 추출 필터 예제

tarfile ‘s 추출 메서드들은 간단한 필터 (filter) 콜러블을 사용하지만, 사용자 정의 필터는 내부 상태를 가진 더 복잡한 객체일 수 있습니다. 이런 경우 컨텍스트 관리자(context manager)로 작성하여 다음과 같이 사용하는 것이 유용할 수 있습니다:

with StatefulFilter() as filter_func:
    tar.extractall(path, filter=filter_func)

이러한 필터는 예를 들어 다음과 같이 작성될 수 있습니다:

class StatefulFilter:
    def __init__(self):
        self.file_count = 0

    def __enter__(self):
        return self

    def __call__(self, member, path):
        self.file_count += 1
        return member

    def __exit__(self, *exc_info):
        print(f'{self.file_count} files extracted')

명령 줄 인터페이스

Added in version 3.4.

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

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

$ python -m tarfile -c monty.tar  spam.txt eggs.txt

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

$ python -m tarfile -c monty.tar life-of-brian_1979/

tar 아카이브를 현재 디렉터리로 추출하려면, -e 옵션을 사용하십시오:

$ python -m tarfile -e monty.tar

디렉터리 이름을 전달하여 tar 아카이브를 다른 디렉터리로 추출할 수도 있습니다:

$ python -m tarfile -e monty.tar  other-dir/

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

$ python -m tarfile -l monty.tar

명령 줄 옵션

-l <tarfile>
--list <tarfile>

tarfile에 있는 파일을 나열합니다.

-c <tarfile> <source1> ... <sourceN>
--create <tarfile> <source1> ... <sourceN>

소스 파일에서 tarfile을 만듭니다.

-e <tarfile> [<output_dir>]
--extract <tarfile> [<output_dir>]

output_dir이 지정되지 않으면 tarfile을 현재 디렉터리로 추출합니다.

-t <tarfile>
--test <tarfile>

tarfile이 유효한지 테스트합니다.

-v, --verbose

상세한 출력.

--filter <filtername>

--extract``에 대한 *필터*(filter)를 지정합니다. 자세한 내용은 :ref:`tarfile-extraction-filter`를 참조하십시오. 문자열 이름만 허용됩니다 (즉, ``fully_trusted, tar, 그리고 data).

예

읽기 예제

전체 tar 아카이브를 현재 작업 디렉터리로 추출하는 방법:

import tarfile
tar = tarfile.open("sample.tar.gz")
tar.extractall(filter='data')
tar.close()

리스트 대신 제너레이터 함수를 사용하여 TarFile.extractall()로 tar 아카이브의 부분집합을 추출하는 방법:

import os
import tarfile

def py_files(members):
    for tarinfo in members:
        if os.path.splitext(tarinfo.name)[1] == ".py":
            yield tarinfo

tar = tarfile.open("sample.tar.gz")
tar.extractall(members=py_files(tar))
tar.close()

gzip 압축 tar 아카이브를 읽고 일부 멤버 정보를 표시하는 방법:

import tarfile
tar = tarfile.open("sample.tar.gz", "r:gz")
for tarinfo in tar:
    print(tarinfo.name, "is", tarinfo.size, "bytes in size and is ", end="")
    if tarinfo.isreg():
        print("a regular file.")
    elif tarinfo.isdir():
        print("a directory.")
    else:
        print("something else.")
tar.close()

쓰기 예제

파일명 리스트로 압축되지 않은 tar 아카이브를 만드는 방법:

import tarfile
tar = tarfile.open("sample.tar", "w")
for name in ["foo", "bar", "quux"]:
    tar.add(name)
tar.close()

with 문을 사용한 같은 예제:

import tarfile
with tarfile.open("sample.tar", "w") as tar:
    for name in ["foo", "bar", "quux"]:
        tar.add(name)

obj 매개변수에서 sys.stdout.buffer <sys.stdout>`를 사용하여 아카이브를 만들고 stdout으로 작성하는 방법 (:meth:`TarFile.add):

import sys
import tarfile
with tarfile.open("sample.tar.gz", "w|gz", fileobj=sys.stdout.buffer) as tar:
    for name in ["foo", "bar", "quux"]:
        tar.add(name)

TarFile.add()의 filter 매개 변수를 사용하여 아카이브를 만들고 사용자 정보를 재설정하는 방법:

import tarfile
def reset(tarinfo):
    tarinfo.uid = tarinfo.gid = 0
    tarinfo.uname = tarinfo.gname = "root"
    return tarinfo
tar = tarfile.open("sample.tar.gz", "w:gz")
tar.add("foo", filter=reset)
tar.close()

지원되는 tar 형식

tarfile 모듈로 만들 수 있는 tar 형식은 세 가지입니다:

  • POSIX.1-1988 ustar 형식 (USTAR_FORMAT). 최대 256자 길이의 파일명과 최대 100자 링크 이름을 지원합니다. 최대 파일 크기는 8 GiB입니다. 이것은 오래되고 제한적이지만 널리 지원되는 형식입니다.

  • GNU tar 형식 (GNU_FORMAT). 긴 파일명과 링크 이름, 8GiB보다 큰 파일 및 스파스 파일을 지원합니다. 이것은 GNU/Linux 시스템의 사실상 표준입니다. tarfile\은 긴 이름을 위한 GNU tar 확장을 완전히 지원하며, 스파스 파일 지원은 읽기 전용입니다.

  • POSIX.1-2001 pax 형식 (PAX_FORMAT). 사실상 제한이 없는 가장 유연한 형식입니다. 긴 파일명과 링크 이름, 큰 파일을 지원하며 경로명을 이식성 있는 방식으로 저장합니다. GNU tar, bsdtar/libarchive 및 star를 포함한 최신 tar 구현은 확장된 pax 기능을 완벽하게 지원합니다; 일부 오래되었거나 유지 관리되지 않는 라이브러리는 그렇지 않을 수 있지만, pax 아카이브를 마치 범용적으로 지원되는 ustar 형식인 것처럼 취급해야 합니다. 새 아카이브의 현재 기본 형식입니다.

    다른 방법으로 저장할 수 없는 정보를 위해 추가 헤더를 사용하여 기존 ustar 형식을 확장합니다. pax 헤더에는 두 가지 종류가 있습니다: 확장(extended) 헤더는 후속 파일 헤더에만 영향을 미치며, 전역(global) 헤더는 전체 아카이브에 유효하며 뒤따르는 파일 모두에 영향을 미칩니다. pax 헤더의 모든 데이터는 이식성의 이유로 UTF-8로 인코딩됩니다.

읽을 수는 있지만 만들 수 없는 tar 형식의 변형이 더 있습니다:

  • 고대 V7 형식. 이것은 일반 파일과 디렉터리 만 저장하는 유닉스 7판(Unix Seventh Edition)에서 온 첫 번째 tar 형식입니다. 이름은 100자 이하여야 합니다. 사용자/그룹 이름 정보는 없습니다. ASCII가 아닌 문자가 있는 필드의 경우 일부 아카이브에서 헤더 체크섬이 잘못 계산되었습니다.

  • SunOS tar 확장 형식. 이 형식은 POSIX.1-2001 pax 형식의 변형이지만, 호환되지 않습니다.

유니코드 문제

tar 형식은 원래 파일 시스템 정보 보존에 중점을 두고 테이프 드라이브에서 백업하기 위해 고안되었습니다. 현재 tar 아카이브는 일반적으로 파일 배포와 네트워크를 통한 아카이브 교환에 사용됩니다. 원래 형식(다른 모든 형식의 기초)의 한 가지 문제점은 다른 문자 인코딩을 지원한다는 개념이 없다는 것입니다. 예를 들어, UTF-8 시스템에서 만들어진 일반 tar 아카이브는 ASCII가 아닌 문자가 포함되면 Latin-1 시스템에서 올바르게 읽을 수 없습니다. (파일명, 링크 이름, 사용자/그룹 이름과 같은) 텍스트 메타 데이터가 손상된 것으로 나타납니다. 불행히도, 아카이브의 인코딩을 자동 감지하는 방법은 없습니다. pax 형식은 이 문제를 해결하도록 설계되었습니다. 범용 문자 인코딩 UTF-8을 사용하여 ASCII가 아닌 메타 데이터를 저장합니다.

tarfile`에서 문자 변환의 세부 사항 (*encoding*과 *errors*)은 :class:`TarFile 클래스의 해당 키워드 인자에 의해 제어됩니다.

encoding은 아카이브의 메타 데이터에 사용할 문자 인코딩을 정의합니다. 기본값은 sys.getfilesystemencoding() 이고, 또는 폴 백으로 'ascii'입니다. 아카이브를 읽거나 쓰는지에 따라, 메타 데이터를 디코딩하거나 인코딩해야 합니다. encoding이 올바르게 설정되지 않으면, 이 변환이 실패 할 수 있습니다.

errors 인자는 변환할 수 없는 문자를 처리하는 방법을 정의합니다. 가능한 값은 섹션 에러 처리기에 나열되어 있습니다. 기본 체계는 파이썬은 파일 시스템 호출에도 사용하는 'surrogateescape'입니다, 파일명, 명령 줄 인자 및 환경 변수를 참조하십시오.

PAX_FORMAT 아카이브(기본값)의 경우, 모든 메타 데이터가 UTF-8을 사용하여 저장기 때문에 encoding은 일반적으로 필요하지 않습니다. encoding은 바이너리 pax 헤더가 디코딩되거나 서로게이트 문자가 있는 문자열이 저장될 때와 같은 드문 경우에만 사용됩니다.

분실물 보관소