514 lines
17 KiB
Markdown
514 lines
17 KiB
Markdown
[🇺🇸 English](./README.md) | [🇨🇳 汉语](./README.zh.md) | **🇪🇸 español** | [🇯🇵 日本語](./README.ja.md) | [🇦🇪 العربية](./README.ar.md) | [🇷🇺 русский](./README.ru.md) | [🇩🇪 Deutsch](./README.de.md) | [🇫🇷 français](./README.fr.md) | [🇰🇷 한국어](./README.ko.md) | [🇧🇷 português](./README.pt.md)
|
||
|
||
# tzst
|
||
|
||
[](https://codecov.io/gh/xixu-me/tzst)
|
||
[](https://github.com/xixu-me/tzst/actions/workflows/github-code-scanning/codeql)
|
||
[](https://github.com/xixu-me/tzst/actions/workflows/ci.yml)
|
||
[](https://pypi.org/project/tzst/)
|
||
[](LICENSE)
|
||
[](https://xi-xu.me/#sponsorships)
|
||
|
||
**tzst** es una biblioteca de Python de próxima generación diseñada para la gestión moderna de archivos, aprovechando la compresión Zstandard de vanguardia para ofrecer un rendimiento, seguridad y fiabilidad superiores. Construida exclusivamente para Python 3.12+, esta solución de nivel empresarial combina operaciones atómicas, eficiencia de transmisión (streaming) y una API meticulosamente elaborada para redefinir cómo los desarrolladores manejan los archivos `.tzst`/`.tar.zst` en entornos de producción. 🚀
|
||
|
||
## ✨ Características
|
||
|
||
- **🗜️ Alta Compresión**: Compresión Zstandard para excelentes ratios de compresión y velocidad.
|
||
- **📁 Compatibilidad con Tar**: Crea archivos tar estándar comprimidos con Zstandard.
|
||
- **💻 Interfaz de Línea de Comandos**: CLI intuitiva con soporte para transmisión y opciones completas.
|
||
- **🐍 API de Python**: API limpia y pitónica para uso programático.
|
||
- **🌍 Multiplataforma**: Funciona en Windows, macOS y Linux.
|
||
- **📂 Múltiples Extensiones**: Soporta las extensiones `.tzst` y `.tar.zst`.
|
||
- **💾 Eficiente en Memoria**: Modo de transmisión para manejar archivos grandes con un uso mínimo de memoria.
|
||
- **⚡ Operaciones Atómicas**: Operaciones de archivo seguras con limpieza automática en caso de interrupción.
|
||
- **🔒 Seguro por Defecto**: Utiliza el filtro 'data' para máxima seguridad durante la extracción.
|
||
- **🚨 Manejo de Errores Mejorado**: Mensajes de error claros con alternativas útiles.
|
||
|
||
## 📥 Instalación
|
||
|
||
### Desde los Lanzamientos de GitHub
|
||
|
||
Descarga ejecutables independientes que no requieren instalación de Python:
|
||
|
||
#### Plataformas Soportadas
|
||
|
||
| Plataforma | Arquitectura | Archivo |
|
||
|--------------|---------------|---------------------------------------|
|
||
| **🐧 Linux** | x86_64 | `tzst-v{versión}-linux-x86_64.zip` |
|
||
| **🐧 Linux** | ARM64 | `tzst-v{versión}-linux-aarch64.zip` |
|
||
| **🪟 Windows**| x64 | `tzst-v{versión}-windows-amd64.zip` |
|
||
| **🪟 Windows**| ARM64 | `tzst-v{versión}-windows-arm64.zip` |
|
||
| **🍎 macOS** | Intel | `tzst-v{versión}-macos-x86_64.zip` |
|
||
| **🍎 macOS** | Apple Silicon | `tzst-v{versión}-macos-arm64.zip` |
|
||
|
||
#### 🛠️ Pasos de Instalación
|
||
|
||
1. **📥 Descarga** el archivo apropiado para tu plataforma desde la [página de lanzamientos más recientes](https://github.com/xixu-me/tzst/releases/latest).
|
||
2. **📦 Extrae** el archivo para obtener el ejecutable `tzst` (o `tzst.exe` en Windows).
|
||
3. **📂 Mueve** el ejecutable a un directorio en tu PATH:
|
||
- **🐧 Linux/macOS**: `sudo mv tzst /usr/local/bin/`
|
||
- **🪟 Windows**: Añade el directorio que contiene `tzst.exe` a tu variable de entorno PATH.
|
||
4. **✅ Verifica** la instalación: `tzst --help`
|
||
|
||
#### 🎯 Beneficios de la Instalación Binaria
|
||
|
||
- ✅ **No requiere Python** - Ejecutable independiente.
|
||
- ✅ **Inicio más rápido** - Sin la sobrecarga del intérprete de Python.
|
||
- ✅ **Despliegue fácil** - Distribución en un solo archivo.
|
||
- ✅ **Comportamiento consistente** - Dependencias incluidas.
|
||
|
||
### 📦 Desde PyPI
|
||
|
||
```
|
||
pip install tzst
|
||
```
|
||
|
||
### 🔧 Desde el Código Fuente
|
||
|
||
```
|
||
git clone https://github.com/xixu-me/tzst.git
|
||
cd tzst
|
||
pip install .
|
||
```
|
||
|
||
### 🚀 Instalación para Desarrollo
|
||
|
||
Este proyecto utiliza estándares modernos de empaquetado de Python:
|
||
|
||
```
|
||
git clone https://github.com/xixu-me/tzst.git
|
||
cd tzst
|
||
pip install -e .[dev]
|
||
```
|
||
|
||
## 🚀 Inicio Rápido
|
||
|
||
### 💻 Uso desde la Línea de Comandos
|
||
|
||
> **Nota**: Descarga el [binario independiente](#desde-los-lanzamientos-de-github) para obtener el mejor rendimiento y no depender de Python. Alternativamente, usa `uvx tzst` para ejecutar sin instalación. Consulta la [documentación de uv](https://docs.astral.sh/uv/) para más detalles.
|
||
|
||
```
|
||
# 📁 Crear un archivo
|
||
tzst a archivo.tzst archivo1.txt archivo2.txt directorio/
|
||
|
||
# 📤 Extraer un archivo
|
||
tzst x archivo.tzst
|
||
|
||
# 📋 Listar el contenido del archivo
|
||
tzst l archivo.tzst
|
||
|
||
# 🧪 Probar la integridad del archivo
|
||
tzst t archivo.tzst
|
||
```
|
||
|
||
### 🐍 Uso de la API de Python
|
||
|
||
```
|
||
from tzst import create_archive, extract_archive, list_archive
|
||
|
||
# Crear un archivo
|
||
create_archive("archivo.tzst", ["archivo1.txt", "archivo2.txt", "directorio/"])
|
||
|
||
# Extraer un archivo
|
||
extract_archive("archivo.tzst", "directorio_salida/")
|
||
|
||
# Listar el contenido del archivo
|
||
contents = list_archive("archivo.tzst", verbose=True)
|
||
for item in contents:
|
||
print(f"{item['name']}: {item['size']} bytes")
|
||
```
|
||
|
||
## 💻 Interfaz de Línea de Comandos
|
||
|
||
### 📁 Operaciones con Archivos
|
||
|
||
#### ➕ Crear Archivo
|
||
|
||
```
|
||
# Uso básico
|
||
tzst a archivo.tzst archivo1.txt archivo2.txt
|
||
|
||
# Con nivel de compresión (1-22, por defecto: 3)
|
||
tzst a archivo.tzst archivos/ -l 15
|
||
|
||
# Comandos alternativos
|
||
tzst add archivo.tzst archivos/
|
||
tzst create archivo.tzst archivos/
|
||
```
|
||
|
||
#### 📤 Extraer Archivo
|
||
|
||
```
|
||
# Extraer con la estructura de directorios completa
|
||
tzst x archivo.tzst
|
||
|
||
# Extraer a un directorio específico
|
||
tzst x archivo.tzst -o salida/
|
||
|
||
# Extraer archivos específicos
|
||
tzst x archivo.tzst archivo1.txt dir/archivo2.txt
|
||
|
||
# Extraer sin estructura de directorios (plano)
|
||
tzst e archivo.tzst -o salida/
|
||
|
||
# Usar modo de transmisión para archivos grandes
|
||
tzst x archivo.tzst --streaming -o salida/
|
||
```
|
||
|
||
#### 📋 Listar Contenido
|
||
|
||
```
|
||
# Listado simple
|
||
tzst l archivo.tzst
|
||
|
||
# Listado detallado con detalles
|
||
tzst l archivo.tzst -v
|
||
|
||
# Usar modo de transmisión para archivos grandes
|
||
tzst l archivo.tzst --streaming -v
|
||
```
|
||
|
||
#### 🧪 Probar Integridad
|
||
|
||
```
|
||
# Probar la integridad del archivo
|
||
tzst t archivo.tzst
|
||
|
||
# Probar con modo de transmisión
|
||
tzst t archivo.tzst --streaming
|
||
```
|
||
|
||
### 📊 Referencia de Comandos
|
||
|
||
| Comando | Alias | Descripción | Soporte de Transmisión |
|
||
|---------|--------------------|-------------------------------------------|------------------------|
|
||
| `a` | `add`, `create` | Crear o añadir a un archivo | N/A |
|
||
| `x` | `extract` | Extraer con rutas completas | ✓ `--streaming` |
|
||
| `e` | `extract-flat` | Extraer sin estructura de directorios | ✓ `--streaming` |
|
||
| `l` | `list` | Listar el contenido del archivo | ✓ `--streaming` |
|
||
| `t` | `test` | Probar la integridad del archivo | ✓ `--streaming` |
|
||
|
||
### ⚙️ Opciones de CLI
|
||
|
||
- `-v, --verbose`: Habilitar salida detallada.
|
||
- `-o, --output DIR`: Especificar directorio de salida (comandos de extracción).
|
||
- `-l, --level NIVEL`: Establecer nivel de compresión 1-22 (comando de creación).
|
||
- `--streaming`: Habilitar modo de transmisión para procesamiento eficiente en memoria.
|
||
- `--filter FILTRO`: Filtro de seguridad para extracción (data/tar/fully_trusted).
|
||
- `--no-atomic`: Deshabilitar operaciones de archivo atómicas (no recomendado).
|
||
|
||
### 🔒 Filtros de Seguridad
|
||
|
||
```
|
||
# Extraer con máxima seguridad (por defecto)
|
||
tzst x archivo.tzst --filter data
|
||
|
||
# Extraer con compatibilidad estándar de tar
|
||
tzst x archivo.tzst --filter tar
|
||
|
||
# Extraer con confianza total (peligroso - solo para archivos de confianza)
|
||
tzst x archivo.tzst --filter fully_trusted
|
||
```
|
||
|
||
**🔐 Opciones de Filtro de Seguridad:**
|
||
|
||
- `data` (por defecto): El más seguro. Bloquea archivos peligrosos, rutas absolutas y rutas fuera del directorio de extracción.
|
||
- `tar`: Compatibilidad estándar con tar. Bloquea rutas absolutas y recorrido de directorios (directory traversal).
|
||
- `fully_trusted`: Sin restricciones de seguridad. Usar solo con archivos completamente confiables.
|
||
|
||
## 🐍 API de Python
|
||
|
||
### 📦 Clase TzstArchive
|
||
|
||
```
|
||
from tzst import TzstArchive
|
||
|
||
# Crear un nuevo archivo
|
||
with TzstArchive("archivo.tzst", "w", compression_level=5) as archive:
|
||
archive.add("archivo.txt")
|
||
archive.add("directorio/", recursive=True)
|
||
|
||
# Leer un archivo existente
|
||
with TzstArchive("archivo.tzst", "r") as archive:
|
||
# Listar contenido
|
||
contents = archive.list(verbose=True)
|
||
|
||
# Extraer con filtro de seguridad
|
||
archive.extract("archivo.txt", "salida/", filter="data")
|
||
|
||
# Probar integridad
|
||
is_valid = archive.test()
|
||
|
||
# Para archivos grandes, usar modo de transmisión
|
||
with TzstArchive("archivo_grande.tzst", "r", streaming=True) as archive:
|
||
archive.extract(path="salida/")
|
||
```
|
||
|
||
**⚠️ Limitaciones Importantes:**
|
||
|
||
- **❌ Modo de Añadir No Soportado**: Crea múltiples archivos o recrea el archivo completo en su lugar.
|
||
|
||
### 🎯 Funciones de Conveniencia
|
||
|
||
#### 📁 create_archive()
|
||
|
||
```
|
||
from tzst import create_archive
|
||
|
||
# Crear con operaciones atómicas (por defecto)
|
||
create_archive(
|
||
archive_path="backup.tzst",
|
||
files=["documentos/", "fotos/", "config.txt"],
|
||
compression_level=10
|
||
)
|
||
```
|
||
|
||
#### 📤 extract_archive()
|
||
|
||
```
|
||
from tzst import extract_archive
|
||
|
||
# Extraer con seguridad (por defecto: filtro 'data')
|
||
extract_archive("backup.tzst", "restaurar/")
|
||
|
||
# Extraer archivos específicos
|
||
extract_archive("backup.tzst", "restaurar/", members=["config.txt"])
|
||
|
||
# Aplanar estructura de directorios
|
||
extract_archive("backup.tzst", "restaurar/", flatten=True)
|
||
|
||
# Usar transmisión para archivos grandes
|
||
extract_archive("backup_grande.tzst", "restaurar/", streaming=True)
|
||
```
|
||
|
||
#### 📋 list_archive()
|
||
|
||
```
|
||
from tzst import list_archive
|
||
|
||
# Listado simple
|
||
files = list_archive("backup.tzst")
|
||
|
||
# Listado detallado
|
||
files = list_archive("backup.tzst", verbose=True)
|
||
|
||
# Transmisión para archivos grandes
|
||
files = list_archive("backup_grande.tzst", streaming=True)
|
||
```
|
||
|
||
#### 🧪 test_archive()
|
||
|
||
```
|
||
from tzst import test_archive
|
||
|
||
# Prueba de integridad básica
|
||
if test_archive("backup.tzst"):
|
||
print("El archivo es válido")
|
||
|
||
# Prueba con transmisión
|
||
if test_archive("backup_grande.tzst", streaming=True):
|
||
print("El archivo grande es válido")
|
||
```
|
||
|
||
## 🔧 Características Avanzadas
|
||
|
||
### 📂 Extensiones de Archivo
|
||
|
||
La biblioteca maneja automáticamente las extensiones de archivo con normalización inteligente:
|
||
|
||
- `.tzst` - Extensión principal para archivos tar+zstandard.
|
||
- `.tar.zst` - Extensión estándar alternativa.
|
||
- Autodetección al abrir archivos existentes.
|
||
- Adición automática de extensión al crear archivos.
|
||
|
||
```
|
||
# Todos estos crean archivos válidos
|
||
create_archive("backup.tzst", files) # Crea backup.tzst
|
||
create_archive("backup.tar.zst", files) # Crea backup.tar.zst
|
||
create_archive("backup", files) # Crea backup.tzst
|
||
create_archive("backup.txt", files) # Crea backup.tzst (normalizado)
|
||
```
|
||
|
||
### 🗜️ Niveles de Compresión
|
||
|
||
Los niveles de compresión de Zstandard van de 1 (más rápido) a 22 (mejor compresión):
|
||
|
||
- **Nivel 1-3**: Compresión rápida, archivos más grandes.
|
||
- **Nivel 3** (por defecto): Buen equilibrio entre velocidad y compresión.
|
||
- **Nivel 10-15**: Mejor compresión, más lento.
|
||
- **Nivel 20-22**: Máxima compresión, mucho más lento.
|
||
|
||
### 🌊 Modo de Transmisión (Streaming)
|
||
|
||
Usa el modo de transmisión para el procesamiento eficiente en memoria de archivos grandes:
|
||
|
||
**✅ Beneficios:**
|
||
|
||
- Uso de memoria significativamente reducido.
|
||
- Mejor rendimiento para archivos que no caben en memoria.
|
||
- Limpieza automática de recursos.
|
||
|
||
**🎯 Cuándo Usar:**
|
||
|
||
- Archivos mayores de 100MB.
|
||
- Entornos con memoria limitada.
|
||
- Procesamiento de archivos con muchos archivos grandes.
|
||
|
||
```
|
||
# Ejemplo: Procesando un archivo de copia de seguridad grande
|
||
from tzst import extract_archive, list_archive, test_archive
|
||
|
||
large_archive = "backup_500gb.tzst"
|
||
|
||
# Operaciones eficientes en memoria
|
||
is_valid = test_archive(large_archive, streaming=True)
|
||
contents = list_archive(large_archive, streaming=True, verbose=True)
|
||
extract_archive(large_archive, "restore/", streaming=True)
|
||
```
|
||
|
||
### ⚡ Operaciones Atómicas
|
||
|
||
Todas las operaciones de creación de archivos utilizan operaciones de archivo atómicas por defecto:
|
||
|
||
- Los archivos se crean primero en archivos temporales y luego se mueven atómicamente.
|
||
- Limpieza automática si el proceso se interrumpe.
|
||
- Sin riesgo de archivos corruptos o incompletos.
|
||
- Compatibilidad multiplataforma.
|
||
|
||
```
|
||
# Operaciones atómicas habilitadas por defecto
|
||
create_archive("importante.tzst", files) # Seguro contra interrupciones
|
||
|
||
# Se pueden deshabilitar si es necesario (no recomendado)
|
||
create_archive("test.tzst", files, use_temp_file=False)
|
||
```
|
||
|
||
### 🚨 Manejo de Errores
|
||
|
||
```
|
||
from tzst import TzstArchive
|
||
from tzst.exceptions import (
|
||
TzstError,
|
||
TzstArchiveError,
|
||
TzstCompressionError,
|
||
TzstDecompressionError,
|
||
TzstFileNotFoundError
|
||
)
|
||
|
||
try:
|
||
with TzstArchive("archivo.tzst", "r") as archive:
|
||
archive.extract()
|
||
except TzstDecompressionError:
|
||
print("Falló la descompresión del archivo")
|
||
except TzstFileNotFoundError:
|
||
print("Archivo no encontrado")
|
||
except KeyboardInterrupt:
|
||
print("Operación interrumpida por el usuario")
|
||
# La limpieza se maneja automáticamente
|
||
```
|
||
|
||
## 🚀 Rendimiento y Comparación
|
||
|
||
### 💡 Consejos de Rendimiento
|
||
|
||
1. **🗜️ Niveles de compresión**: El nivel 3 es óptimo para la mayoría de los casos de uso.
|
||
2. **🌊 Transmisión**: Usar para archivos mayores de 100MB.
|
||
3. **📦 Operaciones por lotes**: Añadir múltiples archivos en una sola sesión.
|
||
4. **📄 Tipos de archivo**: Los archivos ya comprimidos no se comprimirán mucho más.
|
||
|
||
### 🆚 vs Otras Herramientas
|
||
|
||
**vs tar + gzip:**
|
||
|
||
- ✅ Mejores ratios de compresión.
|
||
- ⚡ Descompresión más rápida.
|
||
- 🔄 Algoritmo moderno.
|
||
|
||
**vs tar + xz:**
|
||
|
||
- 🚀 Compresión significativamente más rápida.
|
||
- 📊 Ratios de compresión similares.
|
||
- ⚖️ Mejor equilibrio velocidad/compresión.
|
||
|
||
**vs zip:**
|
||
|
||
- 🗜️ Mejor compresión.
|
||
- 🔐 Preserva permisos y metadatos de Unix.
|
||
- 🌊 Mejor soporte para transmisión.
|
||
|
||
## 📋 Requisitos
|
||
|
||
- 🐍 Python 3.12 o superior
|
||
- 📦 zstandard >= 0.19.0
|
||
|
||
## 🛠️ Desarrollo
|
||
|
||
### 🚀 Configuración del Entorno de Desarrollo
|
||
|
||
Este proyecto utiliza estándares modernos de empaquetado de Python:
|
||
|
||
```
|
||
git clone https://github.com/xixu-me/tzst.git
|
||
cd tzst
|
||
pip install -e .[dev]
|
||
```
|
||
|
||
### 🧪 Ejecución de Pruebas
|
||
|
||
```
|
||
# Ejecutar pruebas con cobertura
|
||
pytest --cov=tzst --cov-report=html
|
||
|
||
# O usar el comando más simple (la configuración de cobertura está en pyproject.toml)
|
||
pytest
|
||
```
|
||
|
||
### ✨ Calidad del Código
|
||
|
||
```
|
||
# Comprobar la calidad del código
|
||
ruff check src tests
|
||
|
||
# Formatear el código
|
||
ruff format src tests
|
||
```
|
||
|
||
## 🤝 Contribuir
|
||
|
||
¡Aceptamos contribuciones! Por favor, lee nuestra [Guía de Contribución](CONTRIBUTING.md) para:
|
||
|
||
- Configuración del desarrollo y estructura del proyecto.
|
||
- Directrices de estilo de código y mejores prácticas.
|
||
- Requisitos de prueba y escritura de pruebas.
|
||
- Proceso de pull request y flujo de trabajo de revisión.
|
||
|
||
### 🚀 Inicio Rápido para Colaboradores
|
||
|
||
```
|
||
git clone https://github.com/xixu-me/tzst.git
|
||
cd tzst
|
||
pip install -e .[dev]
|
||
python -m pytest tests/
|
||
```
|
||
|
||
### 🎯 Tipos de Contribuciones Bienvenidas
|
||
|
||
- 🐛 **Corrección de errores** - Soluciona problemas en la funcionalidad existente.
|
||
- ✨ **Características** - Añade nuevas capacidades a la biblioteca.
|
||
- 📚 **Documentación** - Mejora o añade documentación.
|
||
- 🧪 **Pruebas** - Añade o mejora la cobertura de pruebas.
|
||
- ⚡ **Rendimiento** - Optimiza el código existente.
|
||
- 🔒 **Seguridad** - Aborda vulnerabilidades de seguridad.
|
||
|
||
## 🙏 Agradecimientos
|
||
|
||
- [Meta Zstandard](https://github.com/facebook/zstd) por el excelente algoritmo de compresión.
|
||
- [python-zstandard](https://github.com/indygreg/python-zstandard) por los bindings de Python.
|
||
- La comunidad de Python por la inspiración y los comentarios.
|
||
|
||
## 📄 Licencia
|
||
|
||
Copyright © 2025 [Xi Xu](https://xi-xu.me). Todos los derechos reservados.
|
||
|
||
Licenciado bajo la licencia [BSD 3-Clause](LICENSE).
|