tzst/README.ru.md at main

xixu-me/tzst

0 Fork 0

Files

T

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

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

22 KiB

Raw Permalink Blame History

tzst — это библиотека и CLI для Python 3.12+, предназначенные для создания, извлечения, просмотра и проверки архивов .tzst и .tar.zst. Она объединяет совместимость с tar, сжатие Zstandard, потоковый режим, атомарную запись и безопасное извлечение по умолчанию в компактном интерфейсе для production.

Note

Подробная техническая статья: Deep Dive into tzst: A Modern Python Archiving Library Based on Zstandard.

Особенности

Высокое сжатие: Сжатие Zstandard для отличных коэффициентов сжатия и скорости
Совместимость с Tar: Создаёт стандартные tar-архивы, сжатые с помощью Zstandard
Интерфейс командной строки: Интуитивный CLI с поддержкой потоковой передачи и всесторонними опциями
Python API: Чистый, pythonic 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 (или tzst.exe на Windows)
Переместите исполняемый файл в директорию в вашем 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
Пакетные операции: Добавляйте множественные файлы в одной сессии
Типы файлов: Уже сжатые файлы не будут сжиматься намного дальше

против других инструментов

против tar + gzip:

Лучшие коэффициенты сжатия
Быстрее распаковка
Современный алгоритм

против tar + xz:

Значительно быстрее сжатие
Похожие коэффициенты сжатия
Лучший компромисс скорость/сжатие

против zip:

Лучшее сжатие
Сохраняет разрешения Unix и метаданные
Лучшая поддержка потоковой передачи

Требования

Python 3.12 или выше
zstandard >= 0.19.0

Разработка

Настройка среды разработки