tzst/README.ru.md at 988cdc03060ef87a946ec575082df04dde4909a3

xixu-me/tzst

0 Fork 0

Files

T

xixu-me 988cdc0306 Update PyPI downloads badge links to PyPIStats

Changed the PyPI downloads badge links in all README translations and documentation from pypi.org to pypistats.org for more accurate download statistics.

2025-11-12 17:59:36 +08:00

23 KiB

Raw Blame History

tzst — это библиотека Python нового поколения, разработанная для современного управления архивами, использующая передовое сжатие Zstandard для обеспечения превосходной производительности, безопасности и надёжности. Созданная исключительно для Python 3.12+, это корпоративное решение объединяет атомарные операции, эффективность потоковой передачи и тщательно разработанный API для переосмысления того, как разработчики работают с архивами .tzst/.tar.zst в производственных средах. 🚀

Опубликована статья с углублённым техническим анализом: 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

🛠️ Разработка

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