pyzpaqlib 0.1.0

A modern and easy-to-use Python wrapper for the ZPAQ archiver.

pyzpaqlib

pyzpaqlib는 강력한 zpaq 아카이버를 Python에서 쉽게 사용할 수 있도록 만든 라이브러리입니다. zpaq 명령줄 도구를 감싸서 파일 압축, 추출, 목록 보기 등 다양한 기능을 Python 코드 내에서 직접 실행할 수 있게 해줍니다.

목차

• 주요 기능
• 설치
• 사용법
• 고급 사용법 (버전 관리)
• API 참조
  • Zpaq.add
  • Zpaq.extract
  • Zpaq.list
• 기여 방법
• 라이선스

주요 기능

• zpaq 실행 파일 자동 탐지: 라이브러리에 포함된 zpaq.exe 또는 zpaq64.exe를 자동으로 찾아 사용합니다. 시스템 PATH에 설치된 경우에도 탐지할 수 있습니다.
• 간결한 API: add, extract, list 등 직관적인 메서드를 제공하여 zpaq의 기능을 손쉽게 활용할 수 있습니다.
• 상세한 파일 정보: 아카이브 내 파일의 이름, 크기, 수정 시간 등 상세 정보를 FileInfo 객체로 제공합니다.
• 버전 관리: zpaq의 장점인 버전 관리 기능을 활용하여 여러 버전의 파일을 아카이브에 저장하고 특정 버전으로 복원할 수 있습니다.
• 오류 처리: zpaq 실행 중 발생하는 오류를 ZpaqError 예외로 처리하여 안정적인 코드를 작성할 수 있도록 돕습니다.

설치

pip를 사용하여 간단하게 설치할 수 있습니다.

pip install pyzpaqlib

사용법

다음은 pyzpaqlib를 사용하여 파일을 압축하고, 목록을 보고, 압축을 해제하는 기본적인 예제입니다.

import os
from pyzpaqlib.zpaqlib import Zpaq, ZpaqError

# 테스트용 파일 생성
test_filename = "testfile.txt"
if not os.path.exists(test_filename):
    with open(test_filename, "w", encoding="utf-8") as f:
        f.write("ZPAQ Python 예제 파일입니다.\n")

archive_name = "test.zpaq"
zpaq = Zpaq()

try:
    # 1. 파일을 아카이브에 추가
    print(f"'{test_filename}' 파일을 '{archive_name}'에 추가합니다...")
    zpaq.add(archive=archive_name, files=test_filename)
    print("추가 완료.")

    # 2. 아카이브 내용 목록 출력
    print(f"'{archive_name}'의 파일 목록:")
    file_list = zpaq.list(archive=archive_name)
    for info in file_list:
        print(f"- {info.filename} (크기: {info.size}, 날짜: {info.mtime})")

    # 3. 파일 추출 (다른 이름으로)
    extract_name = "extracted_" + test_filename
    print(f"'{archive_name}'에서 '{extract_name}'로 파일 추출...")
    zpaq.extract(archive=archive_name, files=test_filename, to=extract_name, force=True)
    print("추출 완료.")

except ZpaqError as e:
    print("ZPAQ 오류 발생:", e)
except Exception as e:
    print("예상치 못한 오류:", e)

고급 사용법 (버전 관리)

zpaq의 강력한 기능 중 하나는 파일의 여러 버전을 하나의 아카이브에 저장하는 것입니다. pyzpaqlib를 통해 이 기능을 쉽게 사용할 수 있습니다.

파일의 여러 버전 저장하기

파일을 수정한 후 zpaq.add()를 다시 호출하면, zpaq는 이전 버전은 그대로 두고 변경된 내용을 새로운 버전으로 추가합니다.

# testfile.txt를 수정하고 다시 추가하여 버전 2를 만듭니다.
with open(test_filename, "a", encoding="utf-8") as f:
    f.write("두 번째 버전입니다.\n")

print(f"'{test_filename}' 파일을 '{archive_name}'에 다시 추가합니다 (버전 2)...")
zpaq.add(archive=archive_name, files=test_filename)
print("두 번째 버전 추가 완료.")

모든 버전의 파일 목록 보기

zpaq.list() 메서드에 all=True 옵션을 주면 아카이브에 저장된 모든 버전의 파일 목록을 확인할 수 있습니다.

# 아카이브의 모든 버전 목록 출력
print(f"'{archive_name}'의 모든 버전 파일 목록:")
file_list = zpaq.list(archive=archive_name, all=True)
for info in file_list:
    print(f"- {info.filename} (크기: {info.size}, 날짜: {info.mtime}, 상태: {info.status})")

특정 버전으로 파일 복원하기

zpaq.extract() 메서드에서 until 옵션을 사용하여 특정 버전의 파일을 추출할 수 있습니다. until=1은 가장 오래된 첫 번째 버전을 의미합니다.

# 첫 번째 버전으로 롤백하여 추출
extract_name = "rollback_" + test_filename
print(f"'{archive_name}'에서 첫 번째 버전으로 파일 추출...")
# until=1: 첫 번째 버전 기준으로 추출
zpaq.extract(archive=archive_name, files=test_filename, to=extract_name, until=1, force=True)
print(f"'{extract_name}'로 첫 번째 버전 추출 완료.")

API 참조

Zpaq.add(archive, files, **options)

아카이브에 파일을 추가하거나 업데이트합니다.

파라미터	타입	설명
archive	str	아카이브 파일 경로.
files	str or list	추가할 파일 또는 디렉토리 목록.
key	str	(선택) 암호화 키.
method	int	(선택) 압축 수준 (0=가장 빠름, 5=가장 좋음). 기본값: 1.
force	bool	(선택) 파일 내용이 변경된 경우에만 추가합니다. 기본값: False.
until	str or int	(선택) 추가하기 전에 아카이브를 지정된 날짜 또는 버전으로 롤백합니다.
to	str or list	(선택) 외부 파일을 아카이브에 다른 이름으로 저장합니다.
not	str or list	(선택) 지정된 패턴과 일치하는 파일을 제외합니다.
only	str or list	(선택) 지정된 패턴과 일치하는 파일만 포함합니다.
progress_callback	callable	(선택) 실시간 진행 상황을 처리할 콜백 함수.
summary	int	(선택) 0보다 크면 간단한 진행 상황만 표시합니다.
threads	int	(선택) 사용할 스레드 수 (0=자동).
noattributes	bool	(선택) 파일 속성/권한을 저장하지 않습니다.
index	str	(선택) 아카이브에 대한 인덱스 파일을 생성하고 업데이트합니다.

Zpaq.extract(archive, **options)

아카이브에서 파일을 추출합니다.

파라미터	타입	설명
archive	str	아카이브 파일 경로.
files	str or list	(선택) 추출할 특정 파일. 지정하지 않으면 모두 추출.
key	str	(선택) 암호화된 아카이브 접근 키.
force	bool	(선택) 추출 시 기존 파일을 덮어씁니다. 기본값: False.
to	str or list	(선택) 파일을 다른 이름이나 위치로 추출합니다.
test	bool	(선택) 디스크에 쓰지 않고 추출을 테스트합니다. 기본값: False.
until	str or int	(선택) 지정된 날짜 또는 버전의 파일을 추출합니다.
all	int	(선택) 모든 버전의 파일을 N자리 디렉토리에 추출합니다.
progress_callback	callable	(선택) 실시간 진행 상황을 처리할 콜백 함수.
summary	int	(선택) 0보다 크면 간단한 진행 상황만 표시합니다.
repack	str	(선택) 추출 대신 새 아카이브 파일로 다시 압축합니다.
threads	int	(선택) 사용할 스레드 수 (0=자동).
noattributes	bool	(선택) 저장된 파일 속성을 무시하고 기본값을 사용합니다.
not	str or list	(선택) 지정된 패턴과 일치하는 파일을 제외합니다.
only	str or list	(선택) 지정된 패턴과 일치하는 파일만 포함합니다.
index	str	(선택) 아카이브에 대한 인덱스 파일을 생성합니다.

Zpaq.list(archive, **options)

아카이브의 파일 목록을 보여줍니다. 반환값은 FileInfo 객체의 리스트입니다.

파라미터	타입	설명
archive	str	아카이브 파일 경로.
files	str or list	(선택) 목록을 볼 특정 파일.
key	str	(선택) 암호화된 아카이브 접근 키.
all	bool	(선택) 삭제된 파일을 포함한 모든 버전을 표시합니다. 기본값: False.
until	str or int	(선택) 지정된 날짜 또는 버전의 아카이브 내용을 표시합니다.
not	str or list	(선택) 지정된 패턴과 일치하는 파일 또는 비교 결과에 따라 제외합니다.
only	str or list	(선택) 지정된 패턴과 일치하는 파일만 포함합니다.
force	bool	(선택) 날짜/속성 대신 파일 내용을 비교합니다.
to	str or list	(선택) 외부 파일을 아카이브의 다른 이름 아래 파일과 비교합니다.
summary	int	(선택) 크기별 상위 N개 파일/디렉토리만 표시합니다. -1은 프래그먼트 ID를 표시합니다.

기여 및 유지보수 안내

이 라이브러리는 개인 사용 목적(primary for personal use)으로 작성되었습니다. 기여(Pull Request)나 이슈(issues) 등록은 언제든 환영하지만, 응답이나 처리가 오래 걸리거나(혹은) 불가능할 수 있습니다. 빠른 대응이나 적극적인 유지보수는 보장되지 않습니다. 참고 부탁드립니다.

라이선스

이 프로젝트는 MIT 라이선스를 따릅니다.