xixu-me/tzst
1
0 Fork 0
Code Issues Pull Requests Actions 7 Packages Projects Releases Wiki Activity

docs(readme): align multilingual readmes

Browse Source
This commit is contained in:
xixu-me committed 2026-04-11 21:59:25 +08:00
1 parent 33aae43b40
commit 5774eddbbb
10 files changed
+1048 -1038
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

README.ru.md
+105 -104
View File
@@ -13,24 +13,25 @@
[🇺🇸 English](./README.md) | [🇨🇳 汉语](./README.zh.md) | [🇪🇸 español](./README.es.md) | [🇯🇵 日本語](./README.ja.md) | [🇦🇪 العربية](./README.ar.md) | **🇷🇺 русский** | [🇩🇪 Deutsch](./README.de.md) | [🇫🇷 français](./README.fr.md) | [🇰🇷 한국어](./README.ko.md) | [🇧🇷 português](./README.pt.md)
**tzst** — это библиотека Python нового поколения, разработанная для современного управления архивами, использующая передовое сжатие Zstandard для обеспечения превосходной производительности, безопасности и надёжности. Созданная исключительно для Python 3.12+, это корпоративное решение объединяет атомарные операции, эффективность потоковой передачи и тщательно разработанный API для переосмысления того, как разработчики работают с архивами `.tzst`/`.tar.zst` в производственных средах. 🚀
**tzst** — это библиотека и CLI для Python 3.12+, предназначенные для создания, извлечения, просмотра и проверки архивов `.tzst` и `.tar.zst`. Она объединяет совместимость с tar, сжатие Zstandard, потоковый режим, атомарную запись и безопасное извлечение по умолчанию в компактном интерфейсе для production.
Опубликована статья с углублённым техническим анализом: **[Deep Dive into tzst: A Modern Python Archiving Library Based on Zstandard](https://blog.xi-xu.me/2025/11/01/deep-dive-into-tzst-en.html)**.
> [!NOTE]
> Подробная техническая статья: **[Deep Dive into tzst: A Modern Python Archiving Library Based on Zstandard](https://blog.xi-xu.me/2025/11/01/deep-dive-into-tzst-en.html)**.
## ✨ Особенности
## Особенности
- **🗜️ Высокое сжатие**: Сжатие Zstandard для отличных коэффициентов сжатия и скорости
- **📁 Совместимость с Tar**: Создаёт стандартные tar-архивы, сжатые с помощью Zstandard
- **💻 Интерфейс командной строки**: Интуитивный CLI с поддержкой потоковой передачи и всесторонними опциями
- **🐍 Python API**: Чистый, pythonic API для программного использования
- **🌍 Кроссплатформенность**: Работает на Windows, macOS и Linux
- **📂 Множественные расширения**: Поддерживает как `.tzst`, так и `.tar.zst` расширения
- **💾 Эффективность памяти**: Режим потоковой передачи для обработки больших архивов с минимальным использованием памяти
- **⚡ Атомарные операции**: Безопасные файловые операции с автоматической очисткой при прерывании
- **🔒 Безопасность по умолчанию**: Использует фильтр 'data' для максимальной безопасности при извлечении
- **🚨 Улучшенная обработка ошибок**: Чёткие сообщения об ошибках с полезными альтернативами
- **Высокое сжатие**: Сжатие Zstandard для отличных коэффициентов сжатия и скорости
- **Совместимость с Tar**: Создаёт стандартные tar-архивы, сжатые с помощью Zstandard
- **Интерфейс командной строки**: Интуитивный CLI с поддержкой потоковой передачи и всесторонними опциями
- **Python API**: Чистый, pythonic API для программного использования
- **Кроссплатформенность**: Работает на Windows, macOS и Linux
- **Множественные расширения**: Поддерживает как `.tzst`, так и `.tar.zst` расширения
- **Эффективность памяти**: Режим потоковой передачи для обработки больших архивов с минимальным использованием памяти
- **Атомарные операции**: Безопасные файловые операции с автоматической очисткой при прерывании
- **Безопасность по умолчанию**: Использует фильтр 'data' для максимальной безопасности при извлечении
- **Улучшенная обработка ошибок**: Чёткие сообщения об ошибках с полезными альтернативами
## 📥 Установка
## Установка
### Из релизов GitHub
@@ -40,30 +41,30 @@
| Платформа | Архитектура | Файл |
|----------|-------------|------|
| **🐧 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` |
| **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` |
#### 🛠️ Шаги установки
#### Шаги установки
1. **📥 Скачайте** подходящий архив для вашей платформы со [страницы последних релизов](https://github.com/xixu-me/tzst/releases/latest)
2. **📦 Извлеките** архив, чтобы получить исполняемый файл `tzst` (или `tzst.exe` на Windows)
3. **📂 Переместите** исполняемый файл в директорию в вашем PATH:
- **🐧 Linux/macOS**: `sudo mv tzst /usr/local/bin/`
- **🪟 Windows**: Добавьте директорию, содержащую `tzst.exe`, в переменную окружения PATH
4. **✅ Проверьте** установку: `tzst --help`
1. **Скачайте** подходящий архив для вашей платформы со [страницы последних релизов](https://github.com/xixu-me/tzst/releases/latest)
2. **Извлеките** архив, чтобы получить исполняемый файл `tzst` (или `tzst.exe` на Windows)
3. **Переместите** исполняемый файл в директорию в вашем PATH:
- **Linux/macOS**: `sudo mv tzst /usr/local/bin/`
- **Windows**: Добавьте директорию, содержащую `tzst.exe`, в переменную окружения PATH
4. **Проверьте** установку: `tzst --help`
#### 🎯 Преимущества бинарной установки
#### Преимущества бинарной установки
- ✅ **Python не требуется** - Автономный исполняемый файл
- ✅ **Быстрый запуск** - Нет накладных расходов интерпретатора Python
- ✅ **Лёгкое развёртывание** - Распространение одним файлом
- ✅ **Последовательное поведение** - Встроенные зависимости
- **Python не требуется** - Автономный исполняемый файл
- **Быстрый запуск** - Нет накладных расходов интерпретатора Python
- **Лёгкое развёртывание** - Распространение одним файлом
- **Последовательное поведение** - Встроенные зависимости
### 📦 Из PyPI
### Из PyPI
Используя pip:
@@ -77,7 +78,7 @@ pip install tzst
uv tool install tzst
```
### 🔧 Из исходного кода
### Из исходного кода
```bash
git clone https://github.com/xixu-me/tzst.git
@@ -85,7 +86,7 @@ cd tzst
pip install .
```
### 🚀 Установка для разработки
### Установка для разработки
Этот проект использует современные стандарты упаковки Python:
@@ -95,25 +96,25 @@ cd tzst
pip install -e .[dev]
```
## 🚀 Быстрый старт
## Быстрый старт
### 💻 Использование командной строки
### Использование командной строки
```bash
# 📁 Создать архив
# Создать архив
tzst a archive.tzst file1.txt file2.txt directory/
# 📤 Извлечь архив
# Извлечь архив
tzst x archive.tzst
# 📋 Список содержимого архива
# Список содержимого архива
tzst l archive.tzst
# 🧪 Проверить целостность архива
# Проверить целостность архива
tzst t archive.tzst
```
### 🐍 Использование Python API
### Использование Python API
```python
from tzst import create_archive, extract_archive, list_archive
@@ -130,11 +131,11 @@ for item in contents:
print(f"{item['name']}: {item['size']} bytes")
```
## 💻 Интерфейс командной строки
## Интерфейс командной строки
### 📁 Операции с архивами
### Операции с архивами
#### ➕ Создать архив
#### Создать архив
```bash
# Базовое использование
@@ -148,7 +149,7 @@ tzst add archive.tzst files/
tzst create archive.tzst files/
```
#### 📤 Извлечь архив
#### Извлечь архив
```bash
# Извлечь с полной структурой директорий
@@ -167,7 +168,7 @@ tzst e archive.tzst -o output/
tzst x archive.tzst --streaming -o output/
```
#### 📋 Список содержимого
#### Список содержимого
```bash
# Простой список
@@ -180,7 +181,7 @@ tzst l archive.tzst -v
tzst l archive.tzst --streaming -v
```
#### 🧪 Проверка целостности
#### Проверка целостности
```bash
# Проверить целостность архива
@@ -190,7 +191,7 @@ tzst t archive.tzst
tzst t archive.tzst --streaming
```
### 📊 Справочник команд
### Справочник команд
| Команда | Псевдонимы | Описание | Поддержка потоковой передачи |
|---------|---------|-------------|-------------------|
@@ -200,7 +201,7 @@ tzst t archive.tzst --streaming
| `l` | `list` | Список содержимого архива | ✓ `--streaming` |
| `t` | `test` | Проверить целостность архива | ✓ `--streaming` |
### ⚙️ Опции CLI
### Опции CLI
- `-v, --verbose`: Включить подробный вывод
- `-o, --output DIR`: Указать выходную директорию (команды извлечения)
@@ -209,7 +210,7 @@ tzst t archive.tzst --streaming
- `--filter FILTER`: Фильтр безопасности для извлечения (data/tar/fully_trusted)
- `--no-atomic`: Отключить атомарные файловые операции (не рекомендуется)
### 🔒 Фильтры безопасности
### Фильтры безопасности
```bash
# Извлечь с максимальной безопасностью (по умолчанию)
@@ -222,15 +223,15 @@ tzst x archive.tzst --filter tar
tzst x archive.tzst --filter fully_trusted
```
**🔐 Опции фильтра безопасности:**
**Опции фильтра безопасности:**
- `data` (по умолчанию): Наиболее безопасно. Блокирует опасные файлы, абсолютные пути и пути вне директории извлечения
- `tar`: Стандартная совместимость tar. Блокирует абсолютные пути и обход директорий
- `fully_trusted`: Никаких ограничений безопасности. Используйте только с полностью доверенными архивами
## 🐍 Python API
## Python API
### 📦 Класс TzstArchive
### Класс TzstArchive
```python
from tzst import TzstArchive
@@ -256,13 +257,13 @@ with TzstArchive("large_archive.tzst", "r", streaming=True) as archive:
archive.extract(path="output/")
```
**⚠️ Важные ограничения:**
**Важные ограничения:**
- **❌ Режим добавления не поддерживается**: Создавайте множественные архивы или пересоздавайте весь архив вместо этого
- **Режим добавления не поддерживается**: Создавайте множественные архивы или пересоздавайте весь архив вместо этого
### 🎯 Удобные функции
### Удобные функции
#### 📁 create_archive()
#### create_archive()
```python
from tzst import create_archive
@@ -275,7 +276,7 @@ create_archive(
)
```
#### 📤 extract_archive()
#### extract_archive()
```python
from tzst import extract_archive
@@ -293,7 +294,7 @@ extract_archive("backup.tzst", "restore/", flatten=True)
extract_archive("large_backup.tzst", "restore/", streaming=True)
```
#### 📋 list_archive()
#### list_archive()
```python
from tzst import list_archive
@@ -308,7 +309,7 @@ files = list_archive("backup.tzst", verbose=True)
files = list_archive("large_backup.tzst", streaming=True)
```
#### 🧪 test_archive()
#### test_archive()
```python
from tzst import test_archive
@@ -322,9 +323,9 @@ if test_archive("large_backup.tzst", streaming=True):
print("Большой архив действителен")
```
## 🔧 Продвинутые возможности
## Продвинутые возможности
### 📂 Расширения файлов
### Расширения файлов
Библиотека автоматически обрабатывает расширения файлов с интеллектуальной нормализацией:
@@ -341,7 +342,7 @@ create_archive("backup", files) # Создаёт backup.tzst
create_archive("backup.txt", files) # Создаёт backup.tzst (нормализовано)
```
### 🗜️ Уровни сжатия
### Уровни сжатия
Уровни сжатия Zstandard варьируются от 1 (самый быстрый) до 22 (лучшее сжатие):
@@ -350,17 +351,17 @@ create_archive("backup.txt", files) # Создаёт backup.tzst (норм
- **Уровень 10-15**: Лучшее сжатие, медленнее
- **Уровень 20-22**: Максимальное сжатие, намного медленнее
### 🌊 Режим потоковой передачи
### Режим потоковой передачи
Используйте режим потоковой передачи для эффективной обработки больших архивов в памяти:
**✅ Преимущества:**
**Преимущества:**
- Значительно сниженное использование памяти
- Лучшая производительность для архивов, которые не помещаются в память
- Автоматическая очистка ресурсов
**🎯 Когда использовать:**
**Когда использовать:**
- Архивы больше 100MB
- Среды с ограниченной памятью
@@ -378,7 +379,7 @@ contents = list_archive(large_archive, streaming=True, verbose=True)
extract_archive(large_archive, "restore/", streaming=True)
```
### ⚡ Атомарные операции
### Атомарные операции
Все операции создания файлов используют атомарные файловые операции по умолчанию:
@@ -395,7 +396,7 @@ create_archive("important.tzst", files) # Безопасно от прерыв
create_archive("test.tzst", files, use_temp_file=False)
```
### 🚨 Обработка ошибок
### Обработка ошибок
```python
from tzst import TzstArchive
@@ -419,43 +420,43 @@ except KeyboardInterrupt:
# Очистка обрабатывается автоматически
```
## 🚀 Производительность и сравнение
## Производительность и сравнение
### 💡 Советы по производительности
### Советы по производительности
1. **🗜️ Уровни сжатия**: Уровень 3 оптимален для большинства случаев использования
2. **🌊 Потоковая передача**: Используйте для архивов больше 100MB
3. **📦 Пакетные операции**: Добавляйте множественные файлы в одной сессии
4. **📄 Типы файлов**: Уже сжатые файлы не будут сжиматься намного дальше
1. **Уровни сжатия**: Уровень 3 оптимален для большинства случаев использования
2. **Потоковая передача**: Используйте для архивов больше 100MB
3. **Пакетные операции**: Добавляйте множественные файлы в одной сессии
4. **Типы файлов**: Уже сжатые файлы не будут сжиматься намного дальше
### 🆚 против других инструментов
### против других инструментов
**против tar + gzip:**
- ✅ Лучшие коэффициенты сжатия
- ⚡ Быстрее распаковка
- 🔄 Современный алгоритм
- Лучшие коэффициенты сжатия
- Быстрее распаковка
- Современный алгоритм
**против tar + xz:**
- 🚀 Значительно быстрее сжатие
- 📊 Похожие коэффициенты сжатия
- ⚖️ Лучший компромисс скорость/сжатие
- Значительно быстрее сжатие
- Похожие коэффициенты сжатия
- Лучший компромисс скорость/сжатие
**против zip:**
- 🗜️ Лучшее сжатие
- 🔐 Сохраняет разрешения Unix и метаданные
- 🌊 Лучшая поддержка потоковой передачи
- Лучшее сжатие
- Сохраняет разрешения Unix и метаданные
- Лучшая поддержка потоковой передачи
## 📋 Требования
## Требования
- 🐍 Python 3.12 или выше
- 📦 zstandard >= 0.19.0
- Python 3.12 или выше
- zstandard >= 0.19.0
## 🛠️ Разработка
## Разработка
### 🚀 Настройка среды разработки
### Настройка среды разработки
Этот проект использует современные стандарты упаковки Python:
@@ -465,7 +466,7 @@ cd tzst
pip install -e .[dev]
```
### 🧪 Запуск тестов
### Запуск тестов
```bash
# Запустить тесты с покрытием
@@ -475,7 +476,7 @@ pytest --cov=tzst --cov-report=html
pytest
```
### ✨ Качество кода
### Качество кода
```bash
# Проверить качество кода
@@ -485,16 +486,16 @@ ruff check src tests
ruff format src tests
```
## 🤝 Вклад
## Вклад
Мы приветствуем вклады! Пожалуйста, прочитайте наше [Руководство по вкладу](CONTRIBUTING.md) для:
- Настройки разработки и структуры проекта
- Руководящих принципов стиля кода и лучших практик
- Руководящих принципов стиля кода и лучших практик
- Требований к тестированию и написанию тестов
- Процесса pull request'ов и рабочего процесса обзора
### 🚀 Быстрый старт для участников
### Быстрый старт для участников
```bash
git clone https://github.com/xixu-me/tzst.git
@@ -503,22 +504,22 @@ pip install -e .[dev]
python -m pytest tests/
```
### 🎯 Типы приветствуемых вкладов
### Типы приветствуемых вкладов
- 🐛 **Исправления ошибок** - Исправить проблемы в существующей функциональности
- ✨ **Возможности** - Добавить новые возможности в библиотеку
- 📚 **Документация** - Улучшить или добавить документацию
- 🧪 **Тесты** - Добавить или улучшить покрытие тестами
- ⚡ **Производительность** - Оптимизировать существующий код
- 🔒 **Безопасность** - Устранить уязвимости безопасности
- **Исправления ошибок** - Исправить проблемы в существующей функциональности
- **Возможности** - Добавить новые возможности в библиотеку
- **Документация** - Улучшить или добавить документацию
- **Тесты** - Добавить или улучшить покрытие тестами
- **Производительность** - Оптимизировать существующий код
- **Безопасность** - Устранить уязвимости безопасности
## 🙏 Благодарности
## Благодарности
- [Meta Zstandard](https://github.com/facebook/zstd) за отличный алгоритм сжатия
- [python-zstandard](https://github.com/indygreg/python-zstandard) за связи Python
- Сообществу Python за вдохновение и обратную связь
## 📄 Лицензия
## Лицензия
Авторские права © [Си Сюй](https://xi-xu.me). Все права защищены.