tzst/README.ko.md at 4a5b423e7c438abe7f9605febb26723e4f61ad78

xixu-me/tzst

0 Fork 0

Files

T

xixu-me 5774eddbbb docs(readme): align multilingual readmes

2026-04-11 21:59:25 +08:00

15 KiB

Raw Blame History

tzst는 Python 3.12+에서 .tzst 및 .tar.zst 아카이브를 생성, 추출, 나열, 검사하기 위한 라이브러리이자 CLI입니다. tar 호환성, Zstandard 압축, 스트리밍 처리, 원자적 쓰기, 기본 안전 추출을 운영 환경에 적합한 간결한 인터페이스로 제공합니다.

Note

상세 기술 문서: Deep Dive into tzst: A Modern Python Archiving Library Based on Zstandard.

기능

고압축률: 우수한 압축률과 속도를 위한 Zstandard 압축
Tar 호환성: Zstandard로 압축된 표준 tar 아카이브 생성
명령줄 인터페이스: 스트리밍 지원과 포괄적인 옵션을 갖춘 직관적인 CLI
Python API: 프로그램적 사용을 위한 깔끔하고 Python 스타일의 API
크로스 플랫폼: Windows, macOS, Linux에서 작동
다중 확장자: .tzst 및 .tar.zst 확장자 모두 지원
메모리 효율적: 최소 메모리 사용으로 대용량 아카이브 처리 가능한 스트리밍 모드
원자적 작업: 중단 시 자동 정리 기능을 통한 안전한 파일 작업
기본 보안: 추출 시 최대 보안을 위해 'data' 필터 사용
향상된 오류 처리: 유용한 대안 제시와 함께 명확한 오류 메시지

설치

GitHub 릴리스에서

Python 설치가 필요 없는 독립형 실행 파일 다운로드:

지원 플랫폼

플랫폼	아키텍처	파일
Linux	x86_64	`tzst-{버전}-linux-amd64.zip`
Linux	ARM64	`tzst-{버전}-linux-arm64.zip`
Windows	x64	`tzst-{버전}-windows-amd64.zip`
Windows	ARM64	`tzst-{버전}-windows-arm64.zip`
macOS	Intel	`tzst-{버전}-darwin-amd64.zip`
macOS	Apple Silicon	`tzst-{버전}-darwin-arm64.zip`

설치 단계

최신 릴리스 페이지에서 플랫폼에 맞는 아카이브 다운로드
아카이브를 추출하여 tzst 실행 파일 획득 (Windows는 tzst.exe)
실행 파일을 PATH 환경 변수 디렉터리로 이동:
- Linux/macOS: sudo mv tzst /usr/local/bin/
- Windows: tzst.exe가 포함된 디렉터리를 PATH 환경 변수에 추가
설치 확인: tzst --help

바이너리 설치의 장점

Python 불필요 - 독립형 실행 파일
빠른 시작 - Python 인터프리터 오버헤드 없음
쉬운 배포 - 단일 파일 배포
일관된 동작 - 번들링된 의존성

PyPI에서

pip 사용:

pip install tzst

또는 uv 사용 (권장):

uv tool install tzst

소스에서

git clone https://github.com/xixu-me/tzst.git
cd tzst
pip install .

개발 설치

최신 Python 패키징 표준 사용:

git clone https://github.com/xixu-me/tzst.git
cd tzst
pip install -e .[dev]

빠른 시작

명령줄 사용법

# 아카이브 생성
tzst a archive.tzst file1.txt file2.txt directory/

# 아카이브 추출
tzst x archive.tzst

# 아카이브 내용 목록
tzst l archive.tzst

# 아카이브 무결성 테스트
tzst t archive.tzst

Python API 사용법

from tzst import create_archive, extract_archive, list_archive

# 아카이브 생성
create_archive("archive.tzst", ["file1.txt", "file2.txt", "directory/"])

# 아카이브 추출
extract_archive("archive.tzst", "output_directory/")

# 아카이브 내용 목록
contents = list_archive("archive.tzst", verbose=True)
for item in contents:
    print(f"{item['name']}: {item['size']} bytes")

명령줄 인터페이스

아카이브 작업

아카이브 생성

# 기본 사용법
tzst a archive.tzst file1.txt file2.txt

# 압축 레벨 지정 (1-22, 기본값: 3)
tzst a archive.tzst files/ -l 15

# 대체 명령어
tzst add archive.tzst files/
tzst create archive.tzst files/

아카이브 추출

# 전체 디렉터리 구조 유지하며 추출
tzst x archive.tzst

# 특정 디렉터리로 추출
tzst x archive.tzst -o output/

# 특정 파일 추출
tzst x archive.tzst file1.txt dir/file2.txt

# 디렉터리 구조 없이 추출 (플랫)
tzst e archive.tzst -o output/

# 대용량 아카이브에 스트리밍 모드 사용
tzst x archive.tzst --streaming -o output/

내용 목록

# 간단한 목록
tzst l archive.tzst

# 상세 정보 포함 목록
tzst l archive.tzst -v

# 대용량 아카이브에 스트리밍 모드 사용
tzst l archive.tzst --streaming -v

무결성 테스트

# 아카이브 무결성 테스트
tzst t archive.tzst

# 스트리밍 모드로 테스트
tzst t archive.tzst --streaming

명령어 참조

명령어	별칭	설명	스트리밍 지원
`a`	`add`, `create`	아카이브 생성 또는 추가	N/A
`x`	`extract`	전체 경로로 추출	✓ `--streaming`
`e`	`extract-flat`	디렉터리 구조 없이 추출	✓ `--streaming`
`l`	`list`	아카이브 내용 목록	✓ `--streaming`
`t`	`test`	아카이브 무결성 테스트	✓ `--streaming`

CLI 옵션

-v, --verbose: 상세 출력 활성화
-o, --output DIR: 출력 디렉터리 지정 (추출 명령어)
-l, --level LEVEL: 압축 레벨 1-22 설정 (생성 명령어)
--streaming: 메모리 효율적 처리를 위한 스트리밍 모드 활성화
--filter FILTER: 추출을 위한 보안 필터 (data/tar/fully_trusted)
--no-atomic: 원자적 파일 작업 비활성화 (권장하지 않음)

보안 필터

# 최대 보안으로 추출 (기본값)
tzst x archive.tzst --filter data

# 표준 tar 호환성으로 추출
tzst x archive.tzst --filter tar

# 완전 신뢰 모드로 추출 (위험 - 신뢰할 수 있는 아카이브 전용)
tzst x archive.tzst --filter fully_trusted

보안 필터 옵션:

data (기본값): 가장 안전. 위험한 파일, 절대 경로, 추출 디렉터리 외부 경로 차단
tar: 표준 tar 호환성. 절대 경로 및 디렉터리 순회 차단
fully_trusted: 보안 제한 없음. 완전히 신뢰할 수 있는 아카이브에서만 사용

Python API

TzstArchive 클래스

from tzst import TzstArchive

# 새 아카이브 생성
with TzstArchive("archive.tzst", "w", compression_level=5) as archive:
    archive.add("file.txt")
    archive.add("directory/", recursive=True)

# 기존 아카이브 읽기
with TzstArchive("archive.tzst", "r") as archive:
    # 내용 목록
    contents = archive.list(verbose=True)
    
    # 보안 필터 적용 추출
    archive.extract("file.txt", "output/", filter="data")
    
    # 무결성 테스트
    is_valid = archive.test()

# 대용량 아카이브에 스트리밍 모드 사용
with TzstArchive("large_archive.tzst", "r", streaming=True) as archive:
    archive.extract(path="output/")

중요한 제한 사항:

추가 모드 미지원: 여러 아카이브 생성 또는 전체 아카이브 재생성 필요

편의 함수

create_archive()

from tzst import create_archive

# 원자적 작업으로 생성 (기본값)
create_archive(
    archive_path="backup.tzst",
    files=["documents/", "photos/", "config.txt"],
    compression_level=10
)

extract_archive()

from tzst import extract_archive

# 보안 추출 (기본값: 'data' 필터)
extract_archive("backup.tzst", "restore/")

# 특정 파일 추출
extract_archive("backup.tzst", "restore/", members=["config.txt"])

# 디렉터리 구조 평탄화
extract_archive("backup.tzst", "restore/", flatten=True)

# 대용량 아카이브에 스트리밍 사용
extract_archive("large_backup.tzst", "restore/", streaming=True)

list_archive()

from tzst import list_archive

# 간단한 목록
files = list_archive("backup.tzst")

# 상세 목록
files = list_archive("backup.tzst", verbose=True)

# 대용량 아카이브에 스트리밍 사용
files = list_archive("large_backup.tzst", streaming=True)

test_archive()

from tzst import test_archive

# 기본 무결성 테스트
if test_archive("backup.tzst"):
    print("아카이브가 유효합니다")

# 스트리밍으로 테스트
if test_archive("large_backup.tzst", streaming=True):
    print("대용량 아카이브가 유효합니다")

고급 기능

파일 확장자

라이브러리는 지능적인 정규화로 파일 확장자를 자동 처리합니다:

.tzst - tar+zstandard 아카이브의 기본 확장자
.tar.zst - 대체 표준 확장자
기존 아카이브 열 때 자동 감지
아카이브 생성 시 자동 확장자 추가

# 모두 유효한 아카이브 생성
create_archive("backup.tzst", files)      # backup.tzst 생성
create_archive("backup.tar.zst", files)  # backup.tar.zst 생성  
create_archive("backup", files)          # backup.tzst 생성
create_archive("backup.txt", files)      # backup.tzst 생성 (정규화됨)

압축 레벨

Zstandard 압축 레벨 범위: 1 (가장 빠름) ~ 22 (최대 압축):

레벨 1-3: 빠른 압축, 파일 크기 큼
레벨 3 (기본값): 속도와 압축률의 균형
레벨 10-15: 더 나은 압축, 느림
레벨 20-22: 최대 압축, 매우 느림

스트리밍 모드

대용량 아카이브의 메모리 효율적 처리를 위해 스트리밍 모드 사용:

장점:

메모리 사용량 현저히 감소
메모리에 맞지 않는 대용량 아카이브 처리 성능 향상
리소스 자동 정리

사용 시기:

100MB 이상의 아카이브
메모리가 제한된 환경
대용량 파일이 많은 아카이브 처리

# 예제: 대용량 백업 아카이브 처리
from tzst import extract_archive, list_archive, test_archive

large_archive = "backup_500gb.tzst"

# 메모리 효율적 작업
is_valid = test_archive(large_archive, streaming=True)
contents = list_archive(large_archive, streaming=True, verbose=True)
extract_archive(large_archive, "restore/", streaming=True)

원자적 작업

모든 파일 생성 작업은 기본적으로 원자적 파일 작업을 사용합니다:

임시 파일에 먼저 생성 후 원자적 이동
프로세스 중단 시 자동 정리
손상되거나 불완전한 아카이브 위험 없음
크로스 플랫폼 호환성

# 기본적으로 원자적 작업 활성화
create_archive("important.tzst", files)  # 중단으로부터 안전

# 필요한 경우 비활성화 가능 (권장하지 않음)
create_archive("test.tzst", files, use_temp_file=False)

오류 처리

from tzst import TzstArchive
from tzst.exceptions import (
    TzstError,
    TzstArchiveError,
    TzstCompressionError,
    TzstDecompressionError,
    TzstFileNotFoundError
)

try:
    with TzstArchive("archive.tzst", "r") as archive:
        archive.extract()
except TzstDecompressionError:
    print("아카이브 압축 해제 실패")
except TzstFileNotFoundError:
    print("아카이브 파일을 찾을 수 없음")
except KeyboardInterrupt:
    print("사용자에 의해 작업 중단됨")
    # 자동으로 정리됨

성능 및 비교

성능 팁

압축 레벨: 대부분의 경우 레벨 3이 최적
스트리밍: 100MB 이상 아카이브에 사용
일괄 작업: 단일 세션에서 여러 파일 추가
파일 유형: 이미 압축된 파일은 추가 압축이 거의 안됨

다른 도구와 비교

vs tar + gzip:

더 나은 압축률
더 빠른 압축 해제
현대적인 알고리즘

vs tar + xz:

현저히 빠른 압축
유사한 압축률
더 나은 속도/압축률 균형

vs zip:

더 나은 압축
Unix 권한 및 메타데이터 보존
더 나은 스트리밍 지원

요구 사항

Python 3.12 이상
zstandard >= 0.19.0

개발

개발 환경 설정