From 5774eddbbb00706aebe8bcc400aa02c8fbb3d0e2 Mon Sep 17 00:00:00 2001 From: Xi Xu Date: Sat, 11 Apr 2026 21:59:25 +0800 Subject: [PATCH] docs(readme): align multilingual readmes --- README.ar.md | 209 ++++++++++++++++++++++++++------------------------- README.de.md | 209 ++++++++++++++++++++++++++------------------------- README.es.md | 207 +++++++++++++++++++++++++------------------------- README.fr.md | 209 ++++++++++++++++++++++++++------------------------- README.ja.md | 209 ++++++++++++++++++++++++++------------------------- README.ko.md | 209 ++++++++++++++++++++++++++------------------------- README.md | 209 ++++++++++++++++++++++++++------------------------- README.pt.md | 209 ++++++++++++++++++++++++++------------------------- README.ru.md | 209 ++++++++++++++++++++++++++------------------------- README.zh.md | 207 +++++++++++++++++++++++++------------------------- 10 files changed, 1048 insertions(+), 1038 deletions(-) diff --git a/README.ar.md b/README.ar.md index 3438ec8..f79c403 100644 --- a/README.ar.md +++ b/README.ar.md @@ -15,24 +15,25 @@
-**tzst** هي مكتبة Python من الجيل التالي مُطورة لإدارة الأرشيف الحديث، تستفيد من ضغط Zstandard المتطور لتقديم أداء وأمان وموثوقية فائقة. مبنية حصرياً لـ Python 3.12+، هذا الحل على مستوى المؤسسة يدمج العمليات الذرية وكفاءة التدفق ووواجهة برمجة التطبيقات المصممة بعناية فائقة لإعادة تعريف كيفية تعامل المطورين مع أرشيف `.tzst`/`.tar.zst` في بيئات الإنتاج. 🚀 +**tzst** هي مكتبة وأداة سطر أوامر لـ Python 3.12+ لإنشاء أرشيفات `.tzst` و`.tar.zst` واستخراجها وعرض محتوياتها والتحقق منها. تجمع بين توافق tar وضغط Zstandard ووضع التدفق والكتابة الذرية والاستخراج الآمن افتراضياً ضمن واجهة موجزة جاهزة للاستخدام الإنتاجي. -تم نشر مقال التحليل الفني المتعمق: **[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 للاستخدام البرمجي -- **🌍 متعدد المنصات**: يعمل على Windows وmacOS وLinux -- **📂 امتدادات متعددة**: يدعم كلاً من امتدادات `.tzst` و `.tar.zst` -- **💾 فعال في الذاكرة**: وضع التدفق للتعامل مع الأرشيف الكبير باستخدام أقل للذاكرة -- **⚡ عمليات ذرية**: عمليات ملف آمنة مع تنظيف تلقائي عند المقاطعة -- **🔒 آمن افتراضياً**: يستخدم مرشح 'data' للحد الأقصى من الأمان أثناء الاستخراج -- **🚨 معالجة أخطاء محسنة**: رسائل خطأ واضحة مع بدائل مفيدة +- **ضغط عالي**: ضغط Zstandard لنسب ضغط وسرعة ممتازة +- **توافق Tar**: ينشئ أرشيف tar قياسي مضغوط بـ Zstandard +- **واجهة سطر الأوامر**: واجهة CLI بديهية مع دعم التدفق وخيارات شاملة +- **Python API**: واجهة برمجة تطبيقات نظيفة وpythonic للاستخدام البرمجي +- **متعدد المنصات**: يعمل على Windows وmacOS وLinux +- **امتدادات متعددة**: يدعم كلاً من امتدادات `.tzst` و `.tar.zst` +- **فعال في الذاكرة**: وضع التدفق للتعامل مع الأرشيف الكبير باستخدام أقل للذاكرة +- **عمليات ذرية**: عمليات ملف آمنة مع تنظيف تلقائي عند المقاطعة +- **آمن افتراضياً**: يستخدم مرشح 'data' للحد الأقصى من الأمان أثناء الاستخراج +- **معالجة أخطاء محسنة**: رسائل خطأ واضحة مع بدائل مفيدة -## 📥 التثبيت +## التثبيت ### من إصدارات GitHub @@ -42,30 +43,30 @@ | المنصة | المعمارية | الملف | |----------|-------------|------| -| **🐧 Linux** | x86_64 | `tzst-{version}-linux-amd64.zip` | -| **🐧 Linux** | ARM64 | `tzst-{version}-linux-arm64.zip` | -| **🪟 Windows** | x64 | `tzst-{version}-windows-amd64.zip` | -| **🪟 Windows** | ARM64 | `tzst-{version}-windows-arm64.zip` | -| **🍎 macOS** | Intel | `tzst-{version}-darwin-amd64.zip` | -| **🍎 macOS** | Apple Silicon | `tzst-{version}-darwin-arm64.zip` | +| **Linux** | x86_64 | `tzst-{version}-linux-amd64.zip` | +| **Linux** | ARM64 | `tzst-{version}-linux-arm64.zip` | +| **Windows** | x64 | `tzst-{version}-windows-amd64.zip` | +| **Windows** | ARM64 | `tzst-{version}-windows-arm64.zip` | +| **macOS** | Intel | `tzst-{version}-darwin-amd64.zip` | +| **macOS** | Apple Silicon | `tzst-{version}-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: @@ -79,7 +80,7 @@ pip install tzst uv tool install tzst ``` -### 🔧 من المصدر +### من المصدر ```bash git clone https://github.com/xixu-me/tzst.git @@ -87,7 +88,7 @@ cd tzst pip install . ``` -### 🚀 تثبيت التطوير +### تثبيت التطوير يستخدم هذا المشروع معايير تعبئة Python الحديثة: @@ -97,25 +98,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 @@ -132,11 +133,11 @@ for item in contents: print(f"{item['name']}: {item['size']} bytes") ``` -## 💻 واجهة سطر الأوامر +## واجهة سطر الأوامر -### 📁 عمليات الأرشيف +### عمليات الأرشيف -#### ➕ إنشاء أرشيف +#### إنشاء أرشيف ```bash # الاستخدام الأساسي @@ -150,7 +151,7 @@ tzst add archive.tzst files/ tzst create archive.tzst files/ ``` -#### 📤 استخراج أرشيف +#### استخراج أرشيف ```bash # استخراج مع هيكل المجلد الكامل @@ -169,7 +170,7 @@ tzst e archive.tzst -o output/ tzst x archive.tzst --streaming -o output/ ``` -#### 📋 قائمة المحتويات +#### قائمة المحتويات ```bash # قائمة بسيطة @@ -182,7 +183,7 @@ tzst l archive.tzst -v tzst l archive.tzst --streaming -v ``` -#### 🧪 اختبار السلامة +#### اختبار السلامة ```bash # اختبار سلامة الأرشيف @@ -192,7 +193,7 @@ tzst t archive.tzst tzst t archive.tzst --streaming ``` -### 📊 مرجع الأوامر +### مرجع الأوامر | الأمر | البدائل | الوصف | دعم التدفق | |---------|---------|-------------|-------------------| @@ -202,7 +203,7 @@ tzst t archive.tzst --streaming | `l` | `list` | قائمة محتويات الأرشيف | ✓ `--streaming` | | `t` | `test` | اختبار سلامة الأرشيف | ✓ `--streaming` | -### ⚙️ خيارات CLI +### خيارات CLI - `-v, --verbose`: تمكين الإخراج المفصل - `-o, --output DIR`: تحديد مجلد الإخراج (أوامر الاستخراج) @@ -211,7 +212,7 @@ tzst t archive.tzst --streaming - `--filter FILTER`: مرشح الأمان للاستخراج (data/tar/fully_trusted) - `--no-atomic`: تعطيل العمليات الذرية للملفات (غير مستحسن) -### 🔒 مرشحات الأمان +### مرشحات الأمان ```bash # استخراج مع أقصى أمان (افتراضي) @@ -224,15 +225,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 @@ -258,13 +259,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 @@ -277,7 +278,7 @@ create_archive( ) ``` -#### 📤 extract_archive() +#### extract_archive() ```python from tzst import extract_archive @@ -295,7 +296,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 @@ -310,7 +311,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 @@ -324,9 +325,9 @@ if test_archive("large_backup.tzst", streaming=True): print("الأرشيف الكبير صالح") ``` -## 🔧 الميزات المتقدمة +## الميزات المتقدمة -### 📂 امتدادات الملفات +### امتدادات الملفات تتعامل المكتبة تلقائياً مع امتدادات الملفات مع التطبيع الذكي: @@ -343,7 +344,7 @@ create_archive("backup", files) # ينشئ backup.tzst create_archive("backup.txt", files) # ينشئ backup.tzst (مُطبع) ``` -### 🗜️ مستويات الضغط +### مستويات الضغط تتراوح مستويات ضغط Zstandard من 1 (الأسرع) إلى 22 (أفضل ضغط): @@ -352,17 +353,17 @@ create_archive("backup.txt", files) # ينشئ backup.tzst (مُطبع) - **المستوى 10-15**: ضغط أفضل، أبطأ - **المستوى 20-22**: أقصى ضغط، أبطأ بكثير -### 🌊 وضع التدفق +### وضع التدفق استخدم وضع التدفق للمعالجة الفعالة في الذاكرة للأرشيف الكبير: -**✅ الفوائد:** +**الفوائد:** - انخفاض كبير في استخدام الذاكرة - أداء أفضل للأرشيف الذي لا يناسب الذاكرة - تنظيف تلقائي للموارد -**🎯 متى تستخدم:** +**متى تستخدم:** - أرشيف أكبر من 100 ميجابايت - بيئات ذاكرة محدودة @@ -380,7 +381,7 @@ contents = list_archive(large_archive, streaming=True, verbose=True) extract_archive(large_archive, "restore/", streaming=True) ``` -### ⚡ العمليات الذرية +### العمليات الذرية جميع عمليات إنشاء الملفات تستخدم عمليات ملف ذرية افتراضياً: @@ -397,7 +398,7 @@ create_archive("important.tzst", files) # آمن من المقاطعة create_archive("test.tzst", files, use_temp_file=False) ``` -### 🚨 معالجة الأخطاء +### معالجة الأخطاء ```python from tzst import TzstArchive @@ -421,43 +422,43 @@ except KeyboardInterrupt: # التنظيف يتم تلقائياً ``` -## 🚀 الأداء والمقارنة +## الأداء والمقارنة -### 💡 نصائح الأداء +### نصائح الأداء -1. **🗜️ مستويات الضغط**: المستوى 3 هو الأمثل لمعظم حالات الاستخدام -2. **🌊 التدفق**: استخدم للأرشيف أكبر من 100 ميجابايت -3. **📦 عمليات الدفعات**: أضف ملفات متعددة في جلسة واحدة -4. **📄 أنواع الملفات**: الملفات المضغوطة مسبقاً لن تنضغط كثيراً أكثر +1. **مستويات الضغط**: المستوى 3 هو الأمثل لمعظم حالات الاستخدام +2. **التدفق**: استخدم للأرشيف أكبر من 100 ميجابايت +3. **عمليات الدفعات**: أضف ملفات متعددة في جلسة واحدة +4. **أنواع الملفات**: الملفات المضغوطة مسبقاً لن تنضغط كثيراً أكثر -### 🆚 مقابل أدوات أخرى +### مقابل أدوات أخرى **مقابل tar + gzip:** -- ✅ نسب ضغط أفضل -- ⚡ إلغاء ضغط أسرع -- 🔄 خوارزمية حديثة +- نسب ضغط أفضل +- إلغاء ضغط أسرع +- خوارزمية حديثة **مقابل tar + xz:** -- 🚀 ضغط أسرع بشكل كبير -- 📊 نسب ضغط مماثلة -- ⚖️ توازن سرعة/ضغط أفضل +- ضغط أسرع بشكل كبير +- نسب ضغط مماثلة +- توازن سرعة/ضغط أفضل **مقابل zip:** -- 🗜️ ضغط أفضل -- 🔐 يحافظ على أذونات Unix والبيانات الوصفية -- 🌊 دعم تدفق أفضل +- ضغط أفضل +- يحافظ على أذونات Unix والبيانات الوصفية +- دعم تدفق أفضل -## 📋 المتطلبات +## المتطلبات -- 🐍 Python 3.12 أو أعلى -- 📦 zstandard >= 0.19.0 +- Python 3.12 أو أعلى +- zstandard >= 0.19.0 -## 🛠️ التطوير +## التطوير -### 🚀 إعداد بيئة التطوير +### إعداد بيئة التطوير يستخدم هذا المشروع معايير تعبئة Python الحديثة: @@ -467,7 +468,7 @@ cd tzst pip install -e .[dev] ``` -### 🧪 تشغيل الاختبارات +### تشغيل الاختبارات ```bash # تشغيل الاختبارات مع التغطية @@ -477,7 +478,7 @@ pytest --cov=tzst --cov-report=html pytest ``` -### ✨ جودة الكود +### جودة الكود ```bash # فحص جودة الكود @@ -487,16 +488,16 @@ ruff check src tests ruff format src tests ``` -## 🤝 المساهمة +## المساهمة نرحب بالمساهمات! يرجى قراءة [دليل المساهمة](CONTRIBUTING.md) لـ: - إعداد التطوير وهيكل المشروع -- إرشادات أسلوب الكود وأفضل الممارسات +- إرشادات أسلوب الكود وأفضل الممارسات - متطلبات الاختبار وكتابة الاختبارات - عملية طلب السحب وسير عمل المراجعة -### 🚀 البداية السريعة للمساهمين +### البداية السريعة للمساهمين ```bash git clone https://github.com/xixu-me/tzst.git @@ -505,22 +506,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). جميع الحقوق محفوظة. diff --git a/README.de.md b/README.de.md index d79bedc..61aca3d 100644 --- a/README.de.md +++ b/README.de.md @@ -13,24 +13,25 @@ [🇺🇸 English](./README.md) | [🇨🇳 汉语](./README.zh.md) | [🇪🇸 español](./README.es.md) | [🇯🇵 日本語](./README.ja.md) | [🇦🇪 العربية](./README.ar.md) | [🇷🇺 русский](./README.ru.md) | **🇩🇪 Deutsch** | [🇫🇷 français](./README.fr.md) | [🇰🇷 한국어](./README.ko.md) | [🇧🇷 português](./README.pt.md) -**tzst** ist eine Python-Bibliothek der nächsten Generation, die für modernes Archivmanagement entwickelt wurde und hochmoderne Zstandard-Komprimierung nutzt, um überlegene Leistung, Sicherheit und Zuverlässigkeit zu bieten. Ausschließlich für Python 3.12+ entwickelt, kombiniert diese Unternehmenslösung atomare Operationen, Streaming-Effizienz und eine sorgfältig erstellte API, um die Art und Weise neu zu definieren, wie Entwickler mit `.tzst`/`.tar.zst`-Archiven in Produktionsumgebungen umgehen. 🚀 +**tzst** ist eine Python-3.12+-Bibliothek mit CLI zum Erstellen, Extrahieren, Auflisten und Prüfen von `.tzst`- und `.tar.zst`-Archiven. Sie bündelt tar-Kompatibilität, Zstandard-Komprimierung, Streaming, atomare Schreibvorgänge und standardmäßig sicheres Extrahieren in einer kompakten, produktionsreifen Oberfläche. -Veröffentlichter ausführlicher technischer Analyseartikel: **[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] +> Ausführlicher technischer Artikel: **[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)**. -## ✨ Funktionen +## Funktionen -- **🗜️ Hohe Komprimierung**: Zstandard-Komprimierung für ausgezeichnete Komprimierungsraten und Geschwindigkeit -- **📁 Tar-Kompatibilität**: Erstellt Standard-Tar-Archive, komprimiert mit Zstandard -- **💻 Kommandozeilenschnittstelle**: Intuitive CLI mit Streaming-Unterstützung und umfassenden Optionen -- **🐍 Python API**: Saubere, pythonische API für programmatische Nutzung -- **🌍 Plattformübergreifend**: Funktioniert auf Windows, macOS und Linux -- **📂 Mehrere Erweiterungen**: Unterstützt sowohl `.tzst` als auch `.tar.zst` Erweiterungen -- **💾 Speichereffizient**: Streaming-Modus für die Behandlung großer Archive mit minimalem Speicherverbrauch -- **⚡ Atomare Operationen**: Sichere Dateioperationen mit automatischer Bereinigung bei Unterbrechung -- **🔒 Standardmäßig sicher**: Verwendet den 'data' Filter für maximale Sicherheit beim Extrahieren -- **🚨 Verbesserte Fehlerbehandlung**: Klare Fehlermeldungen mit hilfreichen Alternativen +- **Hohe Komprimierung**: Zstandard-Komprimierung für ausgezeichnete Komprimierungsraten und Geschwindigkeit +- **Tar-Kompatibilität**: Erstellt Standard-Tar-Archive, komprimiert mit Zstandard +- **Kommandozeilenschnittstelle**: Intuitive CLI mit Streaming-Unterstützung und umfassenden Optionen +- **Python API**: Saubere, pythonische API für programmatische Nutzung +- **Plattformübergreifend**: Funktioniert auf Windows, macOS und Linux +- **Mehrere Erweiterungen**: Unterstützt sowohl `.tzst` als auch `.tar.zst` Erweiterungen +- **Speichereffizient**: Streaming-Modus für die Behandlung großer Archive mit minimalem Speicherverbrauch +- **Atomare Operationen**: Sichere Dateioperationen mit automatischer Bereinigung bei Unterbrechung +- **Standardmäßig sicher**: Verwendet den 'data' Filter für maximale Sicherheit beim Extrahieren +- **Verbesserte Fehlerbehandlung**: Klare Fehlermeldungen mit hilfreichen Alternativen -## 📥 Installation +## Installation ### Von GitHub Releases @@ -40,30 +41,30 @@ Lade eigenständige ausführbare Dateien herunter, die keine Python-Installation | Plattform | Architektur | Datei | |----------|-------------|------| -| **🐧 Linux** | x86_64 | `tzst-{version}-linux-amd64.zip` | -| **🐧 Linux** | ARM64 | `tzst-{version}-linux-arm64.zip` | -| **🪟 Windows** | x64 | `tzst-{version}-windows-amd64.zip` | -| **🪟 Windows** | ARM64 | `tzst-{version}-windows-arm64.zip` | -| **🍎 macOS** | Intel | `tzst-{version}-darwin-amd64.zip` | -| **🍎 macOS** | Apple Silicon | `tzst-{version}-darwin-arm64.zip` | +| **Linux** | x86_64 | `tzst-{version}-linux-amd64.zip` | +| **Linux** | ARM64 | `tzst-{version}-linux-arm64.zip` | +| **Windows** | x64 | `tzst-{version}-windows-amd64.zip` | +| **Windows** | ARM64 | `tzst-{version}-windows-arm64.zip` | +| **macOS** | Intel | `tzst-{version}-darwin-amd64.zip` | +| **macOS** | Apple Silicon | `tzst-{version}-darwin-arm64.zip` | -#### 🛠️ Installationsschritte +#### Installationsschritte -1. **📥 Lade** das entsprechende Archiv für deine Plattform von der [Seite der neuesten Releases](https://github.com/xixu-me/tzst/releases/latest) herunter -2. **📦 Extrahiere** das Archiv, um die ausführbare Datei `tzst` (oder `tzst.exe` unter Windows) zu erhalten -3. **📂 Verschiebe** die ausführbare Datei in ein Verzeichnis in deinem PATH: - - **🐧 Linux/macOS**: `sudo mv tzst /usr/local/bin/` - - **🪟 Windows**: Füge das Verzeichnis mit `tzst.exe` zu deiner PATH-Umgebungsvariable hinzu -4. **✅ Überprüfe** die Installation: `tzst --help` +1. **Lade** das entsprechende Archiv für deine Plattform von der [Seite der neuesten Releases](https://github.com/xixu-me/tzst/releases/latest) herunter +2. **Extrahiere** das Archiv, um die ausführbare Datei `tzst` (oder `tzst.exe` unter Windows) zu erhalten +3. **Verschiebe** die ausführbare Datei in ein Verzeichnis in deinem PATH: + - **Linux/macOS**: `sudo mv tzst /usr/local/bin/` + - **Windows**: Füge das Verzeichnis mit `tzst.exe` zu deiner PATH-Umgebungsvariable hinzu +4. **Überprüfe** die Installation: `tzst --help` -#### 🎯 Vorteile der Binärinstallation +#### Vorteile der Binärinstallation -- ✅ **Kein Python erforderlich** - Eigenständige ausführbare Datei -- ✅ **Schnellerer Start** - Kein Python-Interpreter-Overhead -- ✅ **Einfache Bereitstellung** - Einzeldatei-Distribution -- ✅ **Konsistentes Verhalten** - Gebündelte Abhängigkeiten +- **Kein Python erforderlich** - Eigenständige ausführbare Datei +- **Schnellerer Start** - Kein Python-Interpreter-Overhead +- **Einfache Bereitstellung** - Einzeldatei-Distribution +- **Konsistentes Verhalten** - Gebündelte Abhängigkeiten -### 📦 Von PyPI +### Von PyPI Mit pip: @@ -77,7 +78,7 @@ Oder mit uv (empfohlen): uv tool install tzst ``` -### 🔧 Aus dem Quellcode +### Aus dem Quellcode ```bash git clone https://github.com/xixu-me/tzst.git @@ -85,7 +86,7 @@ cd tzst pip install . ``` -### 🚀 Entwicklungsinstallation +### Entwicklungsinstallation Dieses Projekt verwendet moderne Python-Packaging-Standards: @@ -95,25 +96,25 @@ cd tzst pip install -e .[dev] ``` -## 🚀 Schnellstart +## Schnellstart -### 💻 Kommandozeilennutzung +### Kommandozeilennutzung ```bash -# 📁 Archiv erstellen +# Archiv erstellen tzst a archive.tzst file1.txt file2.txt directory/ -# 📤 Archiv extrahieren +# Archiv extrahieren tzst x archive.tzst -# 📋 Archivinhalt auflisten +# Archivinhalt auflisten tzst l archive.tzst -# 🧪 Archivintegrität testen +# Archivintegrität testen tzst t archive.tzst ``` -### 🐍 Python API Nutzung +### Python API Nutzung ```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") ``` -## 💻 Kommandozeilenschnittstelle +## Kommandozeilenschnittstelle -### 📁 Archivoperationen +### Archivoperationen -#### ➕ Archiv erstellen +#### Archiv erstellen ```bash # Grundlegende Nutzung @@ -148,7 +149,7 @@ tzst add archive.tzst files/ tzst create archive.tzst files/ ``` -#### 📤 Archiv extrahieren +#### Archiv extrahieren ```bash # Mit vollständiger Verzeichnisstruktur extrahieren @@ -167,7 +168,7 @@ tzst e archive.tzst -o output/ tzst x archive.tzst --streaming -o output/ ``` -#### 📋 Inhalt auflisten +#### Inhalt auflisten ```bash # Einfache Auflistung @@ -180,7 +181,7 @@ tzst l archive.tzst -v tzst l archive.tzst --streaming -v ``` -#### 🧪 Integrität testen +#### Integrität testen ```bash # Archivintegrität testen @@ -190,7 +191,7 @@ tzst t archive.tzst tzst t archive.tzst --streaming ``` -### 📊 Befehlsreferenz +### Befehlsreferenz | Befehl | Aliase | Beschreibung | Streaming-Unterstützung | |---------|---------|-------------|-------------------| @@ -200,7 +201,7 @@ tzst t archive.tzst --streaming | `l` | `list` | Archivinhalt auflisten | ✓ `--streaming` | | `t` | `test` | Archivintegrität testen | ✓ `--streaming` | -### ⚙️ CLI-Optionen +### CLI-Optionen - `-v, --verbose`: Ausführliche Ausgabe aktivieren - `-o, --output DIR`: Ausgabeverzeichnis spezifizieren (Extraktionsbefehle) @@ -209,7 +210,7 @@ tzst t archive.tzst --streaming - `--filter FILTER`: Sicherheitsfilter für Extraktion (data/tar/fully_trusted) - `--no-atomic`: Atomare Dateioperationen deaktivieren (nicht empfohlen) -### 🔒 Sicherheitsfilter +### Sicherheitsfilter ```bash # Mit maximaler Sicherheit extrahieren (Standard) @@ -222,15 +223,15 @@ tzst x archive.tzst --filter tar tzst x archive.tzst --filter fully_trusted ``` -**🔐 Sicherheitsfilter-Optionen:** +**Sicherheitsfilter-Optionen:** - `data` (Standard): Am sichersten. Blockiert gefährliche Dateien, absolute Pfade und Pfade außerhalb des Extraktionsverzeichnisses - `tar`: Standard-Tar-Kompatibilität. Blockiert absolute Pfade und Verzeichnisdurchquerung - `fully_trusted`: Keine Sicherheitsbeschränkungen. Nur bei vollständig vertrauenswürdigen Archiven verwenden -## 🐍 Python API +## Python API -### 📦 TzstArchive Klasse +### TzstArchive Klasse ```python from tzst import TzstArchive @@ -256,13 +257,13 @@ with TzstArchive("large_archive.tzst", "r", streaming=True) as archive: archive.extract(path="output/") ``` -**⚠️ Wichtige Einschränkungen:** +**Wichtige Einschränkungen:** -- **❌ Anhängemodus nicht unterstützt**: Erstelle mehrere Archive oder erstelle das gesamte Archiv neu +- **Anhängemodus nicht unterstützt**: Erstelle mehrere Archive oder erstelle das gesamte Archiv neu -### 🎯 Convenience-Funktionen +### Convenience-Funktionen -#### 📁 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("Großes Archiv ist gültig") ``` -## 🔧 Erweiterte Funktionen +## Erweiterte Funktionen -### 📂 Dateierweiterungen +### Dateierweiterungen Die Bibliothek behandelt Dateierweiterungen automatisch mit intelligenter Normalisierung: @@ -341,7 +342,7 @@ create_archive("backup", files) # Erstellt backup.tzst create_archive("backup.txt", files) # Erstellt backup.tzst (normalisiert) ``` -### 🗜️ Komprimierungsstufen +### Komprimierungsstufen Zstandard-Komprimierungsstufen reichen von 1 (schnellste) bis 22 (beste Komprimierung): @@ -350,17 +351,17 @@ Zstandard-Komprimierungsstufen reichen von 1 (schnellste) bis 22 (beste Komprimi - **Stufe 10-15**: Bessere Komprimierung, langsamer - **Stufe 20-22**: Maximale Komprimierung, viel langsamer -### 🌊 Streaming-Modus +### Streaming-Modus Verwende den Streaming-Modus für speichereffiziente Verarbeitung großer Archive: -**✅ Vorteile:** +**Vorteile:** - Deutlich reduzierter Speicherverbrauch - Bessere Leistung für Archive, die nicht in den Speicher passen - Automatische Bereinigung von Ressourcen -**🎯 Wann verwenden:** +**Wann verwenden:** - Archive größer als 100MB - Umgebungen mit begrenztem Speicher @@ -378,7 +379,7 @@ contents = list_archive(large_archive, streaming=True, verbose=True) extract_archive(large_archive, "restore/", streaming=True) ``` -### ⚡ Atomare Operationen +### Atomare Operationen Alle Dateierstellungsoperationen verwenden standardmäßig atomare Dateioperationen: @@ -395,7 +396,7 @@ create_archive("important.tzst", files) # Sicher vor Unterbrechung create_archive("test.tzst", files, use_temp_file=False) ``` -### 🚨 Fehlerbehandlung +### Fehlerbehandlung ```python from tzst import TzstArchive @@ -419,43 +420,43 @@ except KeyboardInterrupt: # Bereinigung wird automatisch durchgeführt ``` -## 🚀 Leistung und Vergleich +## Leistung und Vergleich -### 💡 Leistungstipps +### Leistungstipps -1. **🗜️ Komprimierungsstufen**: Stufe 3 ist optimal für die meisten Anwendungsfälle -2. **🌊 Streaming**: Verwende für Archive größer als 100MB -3. **📦 Batch-Operationen**: Füge mehrere Dateien in einer Sitzung hinzu -4. **📄 Dateitypen**: Bereits komprimierte Dateien werden nicht viel weiter komprimiert +1. **Komprimierungsstufen**: Stufe 3 ist optimal für die meisten Anwendungsfälle +2. **Streaming**: Verwende für Archive größer als 100MB +3. **Batch-Operationen**: Füge mehrere Dateien in einer Sitzung hinzu +4. **Dateitypen**: Bereits komprimierte Dateien werden nicht viel weiter komprimiert -### 🆚 vs Andere Tools +### vs Andere Tools **vs tar + gzip:** -- ✅ Bessere Komprimierungsraten -- ⚡ Schnellere Dekomprimierung -- 🔄 Moderner Algorithmus +- Bessere Komprimierungsraten +- Schnellere Dekomprimierung +- Moderner Algorithmus **vs tar + xz:** -- 🚀 Deutlich schnellere Komprimierung -- 📊 Ähnliche Komprimierungsraten -- ⚖️ Besserer Geschwindigkeit/Komprimierung-Kompromiss +- Deutlich schnellere Komprimierung +- Ähnliche Komprimierungsraten +- Besserer Geschwindigkeit/Komprimierung-Kompromiss **vs zip:** -- 🗜️ Bessere Komprimierung -- 🔐 Bewahrt Unix-Berechtigungen und Metadaten -- 🌊 Bessere Streaming-Unterstützung +- Bessere Komprimierung +- Bewahrt Unix-Berechtigungen und Metadaten +- Bessere Streaming-Unterstützung -## 📋 Anforderungen +## Anforderungen -- 🐍 Python 3.12 oder höher -- 📦 zstandard >= 0.19.0 +- Python 3.12 oder höher +- zstandard >= 0.19.0 -## 🛠️ Entwicklung +## Entwicklung -### 🚀 Entwicklungsumgebung einrichten +### Entwicklungsumgebung einrichten Dieses Projekt verwendet moderne Python-Packaging-Standards: @@ -465,7 +466,7 @@ cd tzst pip install -e .[dev] ``` -### 🧪 Tests ausführen +### Tests ausführen ```bash # Tests mit Coverage ausführen @@ -475,7 +476,7 @@ pytest --cov=tzst --cov-report=html pytest ``` -### ✨ Code-Qualität +### Code-Qualität ```bash # Code-Qualität prüfen @@ -485,16 +486,16 @@ ruff check src tests ruff format src tests ``` -## 🤝 Beitragen +## Beitragen Wir begrüßen Beiträge! Bitte lies unseren [Beitragsleitfaden](CONTRIBUTING.md) für: - Entwicklungssetup und Projektstruktur -- Code-Stil-Richtlinien und bewährte Praktiken +- Code-Stil-Richtlinien und bewährte Praktiken - Testanforderungen und Schreibtests - Pull-Request-Prozess und Review-Workflow -### 🚀 Schnellstart für Mitwirkende +### Schnellstart für Mitwirkende ```bash git clone https://github.com/xixu-me/tzst.git @@ -503,22 +504,22 @@ pip install -e .[dev] python -m pytest tests/ ``` -### 🎯 Arten willkommener Beiträge +### Arten willkommener Beiträge -- 🐛 **Fehlerbehebungen** - Probleme in vorhandener Funktionalität beheben -- ✨ **Funktionen** - Neue Fähigkeiten zur Bibliothek hinzufügen -- 📚 **Dokumentation** - Dokumentation verbessern oder hinzufügen -- 🧪 **Tests** - Testabdeckung hinzufügen oder verbessern -- ⚡ **Leistung** - Vorhandenen Code optimieren -- 🔒 **Sicherheit** - Sicherheitsschwachstellen beheben +- **Fehlerbehebungen** - Probleme in vorhandener Funktionalität beheben +- **Funktionen** - Neue Fähigkeiten zur Bibliothek hinzufügen +- **Dokumentation** - Dokumentation verbessern oder hinzufügen +- **Tests** - Testabdeckung hinzufügen oder verbessern +- **Leistung** - Vorhandenen Code optimieren +- **Sicherheit** - Sicherheitsschwachstellen beheben -## 🙏 Danksagungen +## Danksagungen - [Meta Zstandard](https://github.com/facebook/zstd) für den exzellenten Komprimierungsalgorithmus - [python-zstandard](https://github.com/indygreg/python-zstandard) für Python-Bindings - Der Python-Community für Inspiration und Feedback -## 📄 Lizenz +## Lizenz Urheberrecht © [Xi Xu](https://xi-xu.me). Alle Rechte vorbehalten. diff --git a/README.es.md b/README.es.md index 63c3510..c2aedbf 100644 --- a/README.es.md +++ b/README.es.md @@ -13,24 +13,25 @@ [🇺🇸 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** 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. 🚀 +**tzst** es una biblioteca y CLI para Python 3.12+ orientada a crear, extraer, listar y validar archivos `.tzst` y `.tar.zst`. Reúne compatibilidad con tar, compresión Zstandard, modo streaming, escrituras atómicas y extracción segura por defecto en una interfaz compacta lista para producción. -Artículo de análisis técnico en profundidad publicado: **[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] +> Artículo técnico detallado: **[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)**. -## ✨ Características +## 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. +- **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 +## Instalación ### Desde los Lanzamientos de GitHub @@ -40,30 +41,30 @@ Descarga ejecutables independientes que no requieren instalación de Python: | Plataforma | Arquitectura | Archivo | |--------------|---------------|---------------------------------------| -| **🐧 Linux** | x86_64 | `tzst-{versión}-linux-amd64.zip` | -| **🐧 Linux** | ARM64 | `tzst-{versión}-linux-arm64.zip` | -| **🪟 Windows**| x64 | `tzst-{versión}-windows-amd64.zip` | -| **🪟 Windows**| ARM64 | `tzst-{versión}-windows-arm64.zip` | -| **🍎 macOS** | Intel | `tzst-{versión}-darwin-amd64.zip` | -| **🍎 macOS** | Apple Silicon | `tzst-{versión}-darwin-arm64.zip` | +| **Linux** | x86_64 | `tzst-{versión}-linux-amd64.zip` | +| **Linux** | ARM64 | `tzst-{versión}-linux-arm64.zip` | +| **Windows**| x64 | `tzst-{versión}-windows-amd64.zip` | +| **Windows**| ARM64 | `tzst-{versión}-windows-arm64.zip` | +| **macOS** | Intel | `tzst-{versión}-darwin-amd64.zip` | +| **macOS** | Apple Silicon | `tzst-{versión}-darwin-arm64.zip` | -#### 🛠️ Pasos de Instalación +#### 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` +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 +#### 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. +- **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 +### Desde PyPI Usando pip: @@ -77,7 +78,7 @@ O usando uv (recomendado): uv tool install tzst ``` -### 🔧 Desde el Código Fuente +### Desde el Código Fuente ``` git clone https://github.com/xixu-me/tzst.git @@ -85,7 +86,7 @@ cd tzst pip install . ``` -### 🚀 Instalación para Desarrollo +### Instalación para Desarrollo Este proyecto utiliza estándares modernos de empaquetado de Python: @@ -95,25 +96,25 @@ cd tzst pip install -e .[dev] ``` -## 🚀 Inicio Rápido +## Inicio Rápido -### 💻 Uso desde la Línea de Comandos +### Uso desde la Línea de Comandos ``` -# 📁 Crear un archivo +# Crear un archivo tzst a archivo.tzst archivo1.txt archivo2.txt directorio/ -# 📤 Extraer un archivo +# Extraer un archivo tzst x archivo.tzst -# 📋 Listar el contenido del archivo +# Listar el contenido del archivo tzst l archivo.tzst -# 🧪 Probar la integridad del archivo +# Probar la integridad del archivo tzst t archivo.tzst ``` -### 🐍 Uso de la API de Python +### Uso de la API de 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") ``` -## 💻 Interfaz de Línea de Comandos +## Interfaz de Línea de Comandos -### 📁 Operaciones con Archivos +### Operaciones con Archivos -#### ➕ Crear Archivo +#### Crear Archivo ``` # Uso básico @@ -148,7 +149,7 @@ tzst add archivo.tzst archivos/ tzst create archivo.tzst archivos/ ``` -#### 📤 Extraer Archivo +#### Extraer Archivo ``` # Extraer con la estructura de directorios completa @@ -167,7 +168,7 @@ tzst e archivo.tzst -o salida/ tzst x archivo.tzst --streaming -o salida/ ``` -#### 📋 Listar Contenido +#### Listar Contenido ``` # Listado simple @@ -180,7 +181,7 @@ tzst l archivo.tzst -v tzst l archivo.tzst --streaming -v ``` -#### 🧪 Probar Integridad +#### Probar Integridad ``` # Probar la integridad del archivo @@ -190,7 +191,7 @@ tzst t archivo.tzst tzst t archivo.tzst --streaming ``` -### 📊 Referencia de Comandos +### Referencia de Comandos | Comando | Alias | Descripción | Soporte de Transmisión | |---------|--------------------|-------------------------------------------|------------------------| @@ -200,7 +201,7 @@ tzst t archivo.tzst --streaming | `l` | `list` | Listar el contenido del archivo | ✓ `--streaming` | | `t` | `test` | Probar la integridad del archivo | ✓ `--streaming` | -### ⚙️ Opciones de CLI +### Opciones de CLI - `-v, --verbose`: Habilitar salida detallada. - `-o, --output DIR`: Especificar directorio de salida (comandos de extracción). @@ -209,7 +210,7 @@ tzst t archivo.tzst --streaming - `--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 +### Filtros de Seguridad ``` # Extraer con máxima seguridad (por defecto) @@ -222,15 +223,15 @@ tzst x archivo.tzst --filter tar tzst x archivo.tzst --filter fully_trusted ``` -**🔐 Opciones de Filtro de Seguridad:** +**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 +## API de Python -### 📦 Clase TzstArchive +### Clase TzstArchive ``` from tzst import TzstArchive @@ -256,13 +257,13 @@ with TzstArchive("archivo_grande.tzst", "r", streaming=True) as archive: archive.extract(path="salida/") ``` -**⚠️ Limitaciones Importantes:** +**Limitaciones Importantes:** -- **❌ Modo de Añadir No Soportado**: Crea múltiples archivos o recrea el archivo completo en su lugar. +- **Modo de Añadir No Soportado**: Crea múltiples archivos o recrea el archivo completo en su lugar. -### 🎯 Funciones de Conveniencia +### Funciones de Conveniencia -#### 📁 create_archive() +#### create_archive() ``` from tzst import create_archive @@ -275,7 +276,7 @@ create_archive( ) ``` -#### 📤 extract_archive() +#### extract_archive() ``` from tzst import extract_archive @@ -293,7 +294,7 @@ extract_archive("backup.tzst", "restaurar/", flatten=True) extract_archive("backup_grande.tzst", "restaurar/", streaming=True) ``` -#### 📋 list_archive() +#### list_archive() ``` from tzst import list_archive @@ -308,7 +309,7 @@ files = list_archive("backup.tzst", verbose=True) files = list_archive("backup_grande.tzst", streaming=True) ``` -#### 🧪 test_archive() +#### test_archive() ``` from tzst import test_archive @@ -322,9 +323,9 @@ if test_archive("backup_grande.tzst", streaming=True): print("El archivo grande es válido") ``` -## 🔧 Características Avanzadas +## Características Avanzadas -### 📂 Extensiones de Archivo +### Extensiones de Archivo La biblioteca maneja automáticamente las extensiones de archivo con normalización inteligente: @@ -341,7 +342,7 @@ create_archive("backup", files) # Crea backup.tzst create_archive("backup.txt", files) # Crea backup.tzst (normalizado) ``` -### 🗜️ Niveles de Compresión +### Niveles de Compresión Los niveles de compresión de Zstandard van de 1 (más rápido) a 22 (mejor compresión): @@ -350,17 +351,17 @@ Los niveles de compresión de Zstandard van de 1 (más rápido) a 22 (mejor comp - **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) +### Modo de Transmisión (Streaming) Usa el modo de transmisión para el procesamiento eficiente en memoria de archivos grandes: -**✅ Beneficios:** +**Beneficios:** - Uso de memoria significativamente reducido. - Mejor rendimiento para archivos que no caben en memoria. - Limpieza automática de recursos. -**🎯 Cuándo Usar:** +**Cuándo Usar:** - Archivos mayores de 100MB. - Entornos con memoria limitada. @@ -378,7 +379,7 @@ contents = list_archive(large_archive, streaming=True, verbose=True) extract_archive(large_archive, "restore/", streaming=True) ``` -### ⚡ Operaciones Atómicas +### Operaciones Atómicas Todas las operaciones de creación de archivos utilizan operaciones de archivo atómicas por defecto: @@ -395,7 +396,7 @@ create_archive("importante.tzst", files) # Seguro contra interrupciones create_archive("test.tzst", files, use_temp_file=False) ``` -### 🚨 Manejo de Errores +### Manejo de Errores ``` from tzst import TzstArchive @@ -419,43 +420,43 @@ except KeyboardInterrupt: # La limpieza se maneja automáticamente ``` -## 🚀 Rendimiento y Comparación +## Rendimiento y Comparación -### 💡 Consejos de Rendimiento +### 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. +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 Otras Herramientas **vs tar + gzip:** -- ✅ Mejores ratios de compresión. -- ⚡ Descompresión más rápida. -- 🔄 Algoritmo moderno. +- 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. +- 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. +- Mejor compresión. +- Preserva permisos y metadatos de Unix. +- Mejor soporte para transmisión. -## 📋 Requisitos +## Requisitos -- 🐍 Python 3.12 o superior -- 📦 zstandard >= 0.19.0 +- Python 3.12 o superior +- zstandard >= 0.19.0 -## 🛠️ Desarrollo +## Desarrollo -### 🚀 Configuración del Entorno de Desarrollo +### Configuración del Entorno de Desarrollo Este proyecto utiliza estándares modernos de empaquetado de Python: @@ -465,7 +466,7 @@ cd tzst pip install -e .[dev] ``` -### 🧪 Ejecución de Pruebas +### Ejecución de Pruebas ``` # Ejecutar pruebas con cobertura @@ -475,7 +476,7 @@ pytest --cov=tzst --cov-report=html pytest ``` -### ✨ Calidad del Código +### Calidad del Código ``` # Comprobar la calidad del código @@ -485,7 +486,7 @@ ruff check src tests ruff format src tests ``` -## 🤝 Contribuir +## Contribuir ¡Aceptamos contribuciones! Por favor, lee nuestra [Guía de Contribución](CONTRIBUTING.md) para: @@ -494,7 +495,7 @@ ruff format src tests - Requisitos de prueba y escritura de pruebas. - Proceso de pull request y flujo de trabajo de revisión. -### 🚀 Inicio Rápido para Colaboradores +### Inicio Rápido para Colaboradores ``` git clone https://github.com/xixu-me/tzst.git @@ -503,22 +504,22 @@ pip install -e .[dev] python -m pytest tests/ ``` -### 🎯 Tipos de Contribuciones Bienvenidas +### 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. +- **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 +## 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 +## Licencia Copyright © [Xi Xu](https://xi-xu.me). Todos los derechos reservados. diff --git a/README.fr.md b/README.fr.md index de2446e..36491b6 100644 --- a/README.fr.md +++ b/README.fr.md @@ -13,24 +13,25 @@ [🇺🇸 English](./README.md) | [🇨🇳 汉语](./README.zh.md) | [🇪🇸 español](./README.es.md) | [🇯🇵 日本語](./README.ja.md) | [🇦🇪 العربية](./README.ar.md) | [🇷🇺 русский](./README.ru.md) | [🇩🇪 Deutsch](./README.de.md) | **🇫🇷 français** | [🇰🇷 한국어](./README.ko.md) | [🇧🇷 português](./README.pt.md) -**tzst** est une bibliothèque Python de nouvelle génération conçue pour la gestion moderne d'archives, exploitant la compression Zstandard de pointe pour offrir des performances, une sécurité et une fiabilité supérieures. Construite exclusivement pour Python 3.12+, cette solution de niveau entreprise combine des opérations atomiques, l'efficacité du streaming et une API méticuleusement conçue pour redéfinir la façon dont les développeurs gèrent les archives `.tzst`/`.tar.zst` dans les environnements de production. 🚀 +**tzst** est une bibliothèque et une CLI pour Python 3.12+ destinées à créer, extraire, lister et vérifier des archives `.tzst` et `.tar.zst`. Elle réunit la compatibilité tar, la compression Zstandard, le mode streaming, les écritures atomiques et une extraction sécurisée par défaut dans une interface compacte prête pour la production. -Article d'analyse technique approfondie publié : **[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] +> Article technique détaillé : **[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)**. -## ✨ Fonctionnalités +## Fonctionnalités -- **🗜️ Compression élevée** : Compression Zstandard pour d'excellents taux de compression et une vitesse remarquable -- **📁 Compatibilité Tar** : Crée des archives tar standard compressées avec Zstandard -- **💻 Interface en ligne de commande** : CLI intuitive avec support de streaming et options complètes -- **🐍 API Python** : API propre et pythonique pour un usage programmatique -- **🌍 Multi-plateforme** : Fonctionne sur Windows, macOS et Linux -- **📂 Extensions multiples** : Supporte les extensions `.tzst` et `.tar.zst` -- **💾 Efficace en mémoire** : Mode streaming pour gérer de grandes archives avec une utilisation mémoire minimale -- **⚡ Opérations atomiques** : Opérations de fichiers sécurisées avec nettoyage automatique en cas d'interruption -- **🔒 Sécurisé par défaut** : Utilise le filtre 'data' pour une sécurité maximale lors de l'extraction -- **🚨 Gestion d'erreurs améliorée** : Messages d'erreur clairs avec des alternatives utiles +- **Compression élevée** : Compression Zstandard pour d'excellents taux de compression et une vitesse remarquable +- **Compatibilité Tar** : Crée des archives tar standard compressées avec Zstandard +- **Interface en ligne de commande** : CLI intuitive avec support de streaming et options complètes +- **API Python** : API propre et pythonique pour un usage programmatique +- **Multi-plateforme** : Fonctionne sur Windows, macOS et Linux +- **Extensions multiples** : Supporte les extensions `.tzst` et `.tar.zst` +- **Efficace en mémoire** : Mode streaming pour gérer de grandes archives avec une utilisation mémoire minimale +- **Opérations atomiques** : Opérations de fichiers sécurisées avec nettoyage automatique en cas d'interruption +- **Sécurisé par défaut** : Utilise le filtre 'data' pour une sécurité maximale lors de l'extraction +- **Gestion d'erreurs améliorée** : Messages d'erreur clairs avec des alternatives utiles -## 📥 Installation +## Installation ### Depuis les Releases GitHub @@ -40,30 +41,30 @@ Téléchargez des exécutables autonomes qui ne nécessitent pas d'installation | Plateforme | Architecture | Fichier | |----------|-------------|------| -| **🐧 Linux** | x86_64 | `tzst-{version}-linux-amd64.zip` | -| **🐧 Linux** | ARM64 | `tzst-{version}-linux-arm64.zip` | -| **🪟 Windows** | x64 | `tzst-{version}-windows-amd64.zip` | -| **🪟 Windows** | ARM64 | `tzst-{version}-windows-arm64.zip` | -| **🍎 macOS** | Intel | `tzst-{version}-darwin-amd64.zip` | -| **🍎 macOS** | Apple Silicon | `tzst-{version}-darwin-arm64.zip` | +| **Linux** | x86_64 | `tzst-{version}-linux-amd64.zip` | +| **Linux** | ARM64 | `tzst-{version}-linux-arm64.zip` | +| **Windows** | x64 | `tzst-{version}-windows-amd64.zip` | +| **Windows** | ARM64 | `tzst-{version}-windows-arm64.zip` | +| **macOS** | Intel | `tzst-{version}-darwin-amd64.zip` | +| **macOS** | Apple Silicon | `tzst-{version}-darwin-arm64.zip` | -#### 🛠️ Étapes d'installation +#### Étapes d'installation -1. **📥 Téléchargez** l'archive appropriée pour votre plateforme depuis la [page des dernières versions](https://github.com/xixu-me/tzst/releases/latest) -2. **📦 Extrayez** l'archive pour obtenir l'exécutable `tzst` (ou `tzst.exe` sous Windows) -3. **📂 Déplacez** l'exécutable vers un répertoire dans votre PATH : - - **🐧 Linux/macOS** : `sudo mv tzst /usr/local/bin/` - - **🪟 Windows** : Ajoutez le répertoire contenant `tzst.exe` à votre variable d'environnement PATH -4. **✅ Vérifiez** l'installation : `tzst --help` +1. **Téléchargez** l'archive appropriée pour votre plateforme depuis la [page des dernières versions](https://github.com/xixu-me/tzst/releases/latest) +2. **Extrayez** l'archive pour obtenir l'exécutable `tzst` (ou `tzst.exe` sous Windows) +3. **Déplacez** l'exécutable vers un répertoire dans votre PATH : + - **Linux/macOS** : `sudo mv tzst /usr/local/bin/` + - **Windows** : Ajoutez le répertoire contenant `tzst.exe` à votre variable d'environnement PATH +4. **Vérifiez** l'installation : `tzst --help` -#### 🎯 Avantages de l'installation binaire +#### Avantages de l'installation binaire -- ✅ **Aucun Python requis** - Exécutable autonome -- ✅ **Démarrage plus rapide** - Aucune surcharge d'interpréteur Python -- ✅ **Déploiement facile** - Distribution en fichier unique -- ✅ **Comportement cohérent** - Dépendances intégrées +- **Aucun Python requis** - Exécutable autonome +- **Démarrage plus rapide** - Aucune surcharge d'interpréteur Python +- **Déploiement facile** - Distribution en fichier unique +- **Comportement cohérent** - Dépendances intégrées -### 📦 Depuis PyPI +### Depuis PyPI Avec pip : @@ -77,7 +78,7 @@ Ou avec uv (recommandé) : uv tool install tzst ``` -### 🔧 Depuis le code source +### Depuis le code source ```bash git clone https://github.com/xixu-me/tzst.git @@ -85,7 +86,7 @@ cd tzst pip install . ``` -### 🚀 Installation de développement +### Installation de développement Ce projet utilise les standards modernes d'empaquetage Python : @@ -95,25 +96,25 @@ cd tzst pip install -e .[dev] ``` -## 🚀 Démarrage rapide +## Démarrage rapide -### 💻 Utilisation en ligne de commande +### Utilisation en ligne de commande ```bash -# 📁 Créer une archive +# Créer une archive tzst a archive.tzst file1.txt file2.txt directory/ -# 📤 Extraire une archive +# Extraire une archive tzst x archive.tzst -# 📋 Lister le contenu d'une archive +# Lister le contenu d'une archive tzst l archive.tzst -# 🧪 Tester l'intégrité d'une archive +# Tester l'intégrité d'une archive tzst t archive.tzst ``` -### 🐍 Utilisation de l'API Python +### Utilisation de l'API Python ```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") ``` -## 💻 Interface en ligne de commande +## Interface en ligne de commande -### 📁 Opérations d'archives +### Opérations d'archives -#### ➕ Créer une archive +#### Créer une archive ```bash # Utilisation de base @@ -148,7 +149,7 @@ tzst add archive.tzst files/ tzst create archive.tzst files/ ``` -#### 📤 Extraire une archive +#### Extraire une archive ```bash # Extraire avec structure complète des répertoires @@ -167,7 +168,7 @@ tzst e archive.tzst -o output/ tzst x archive.tzst --streaming -o output/ ``` -#### 📋 Lister le contenu +#### Lister le contenu ```bash # Liste simple @@ -180,7 +181,7 @@ tzst l archive.tzst -v tzst l archive.tzst --streaming -v ``` -#### 🧪 Tester l'intégrité +#### Tester l'intégrité ```bash # Tester l'intégrité de l'archive @@ -190,7 +191,7 @@ tzst t archive.tzst tzst t archive.tzst --streaming ``` -### 📊 Référence des commandes +### Référence des commandes | Commande | Alias | Description | Support streaming | |---------|---------|-------------|-------------------| @@ -200,7 +201,7 @@ tzst t archive.tzst --streaming | `l` | `list` | Lister le contenu de l'archive | ✓ `--streaming` | | `t` | `test` | Tester l'intégrité de l'archive | ✓ `--streaming` | -### ⚙️ Options CLI +### Options CLI - `-v, --verbose` : Activer la sortie détaillée - `-o, --output DIR` : Spécifier le répertoire de sortie (commandes d'extraction) @@ -209,7 +210,7 @@ tzst t archive.tzst --streaming - `--filter FILTER` : Filtre de sécurité pour l'extraction (data/tar/fully_trusted) - `--no-atomic` : Désactiver les opérations de fichiers atomiques (non recommandé) -### 🔒 Filtres de sécurité +### Filtres de sécurité ```bash # Extraire avec sécurité maximale (défaut) @@ -222,15 +223,15 @@ tzst x archive.tzst --filter tar tzst x archive.tzst --filter fully_trusted ``` -**🔐 Options de filtre de sécurité :** +**Options de filtre de sécurité :** - `data` (défaut) : Le plus sécurisé. Bloque les fichiers dangereux, les chemins absolus et les chemins en dehors du répertoire d'extraction - `tar` : Compatibilité tar standard. Bloque les chemins absolus et la traversée de répertoires - `fully_trusted` : Aucune restriction de sécurité. À utiliser uniquement avec des archives entièrement fiables -## 🐍 API Python +## API Python -### 📦 Classe TzstArchive +### Classe TzstArchive ```python from tzst import TzstArchive @@ -256,13 +257,13 @@ with TzstArchive("large_archive.tzst", "r", streaming=True) as archive: archive.extract(path="output/") ``` -**⚠️ Limitations importantes :** +**Limitations importantes :** -- **❌ Mode d'ajout non supporté** : Créez plusieurs archives ou recréez l'archive entière à la place +- **Mode d'ajout non supporté** : Créez plusieurs archives ou recréez l'archive entière à la place -### 🎯 Fonctions de convenance +### Fonctions de convenance -#### 📁 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("La grande archive est valide") ``` -## 🔧 Fonctionnalités avancées +## Fonctionnalités avancées -### 📂 Extensions de fichiers +### Extensions de fichiers La bibliothèque gère automatiquement les extensions de fichiers avec normalisation intelligente : @@ -341,7 +342,7 @@ create_archive("backup", files) # Crée backup.tzst create_archive("backup.txt", files) # Crée backup.tzst (normalisé) ``` -### 🗜️ Niveaux de compression +### Niveaux de compression Les niveaux de compression Zstandard vont de 1 (le plus rapide) à 22 (meilleure compression) : @@ -350,17 +351,17 @@ Les niveaux de compression Zstandard vont de 1 (le plus rapide) à 22 (meilleure - **Niveau 10-15** : Meilleure compression, plus lent - **Niveau 20-22** : Compression maximale, beaucoup plus lent -### 🌊 Mode streaming +### Mode streaming Utilisez le mode streaming pour un traitement efficace en mémoire de grandes archives : -**✅ Avantages :** +**Avantages :** - Utilisation mémoire considérablement réduite - Meilleures performances pour les archives qui ne tiennent pas en mémoire - Nettoyage automatique des ressources -**🎯 Quand utiliser :** +**Quand utiliser :** - Archives supérieures à 100MB - Environnements à mémoire limitée @@ -378,7 +379,7 @@ contents = list_archive(large_archive, streaming=True, verbose=True) extract_archive(large_archive, "restore/", streaming=True) ``` -### ⚡ Opérations atomiques +### Opérations atomiques Toutes les opérations de création de fichiers utilisent des opérations de fichiers atomiques par défaut : @@ -395,7 +396,7 @@ create_archive("important.tzst", files) # Sûr contre les interruptions create_archive("test.tzst", files, use_temp_file=False) ``` -### 🚨 Gestion des erreurs +### Gestion des erreurs ```python from tzst import TzstArchive @@ -419,43 +420,43 @@ except KeyboardInterrupt: # Le nettoyage est géré automatiquement ``` -## 🚀 Performance et comparaison +## Performance et comparaison -### 💡 Conseils de performance +### Conseils de performance -1. **🗜️ Niveaux de compression** : Le niveau 3 est optimal pour la plupart des cas d'usage -2. **🌊 Streaming** : Utilisez pour les archives supérieures à 100MB -3. **📦 Opérations par lots** : Ajoutez plusieurs fichiers en une seule session -4. **📄 Types de fichiers** : Les fichiers déjà compressés ne se compresseront pas beaucoup plus +1. **Niveaux de compression** : Le niveau 3 est optimal pour la plupart des cas d'usage +2. **Streaming** : Utilisez pour les archives supérieures à 100MB +3. **Opérations par lots** : Ajoutez plusieurs fichiers en une seule session +4. **Types de fichiers** : Les fichiers déjà compressés ne se compresseront pas beaucoup plus -### 🆚 vs Autres outils +### vs Autres outils **vs tar + gzip :** -- ✅ Meilleurs taux de compression -- ⚡ Décompression plus rapide -- 🔄 Algorithme moderne +- Meilleurs taux de compression +- Décompression plus rapide +- Algorithme moderne **vs tar + xz :** -- 🚀 Compression significativement plus rapide -- 📊 Taux de compression similaires -- ⚖️ Meilleur compromis vitesse/compression +- Compression significativement plus rapide +- Taux de compression similaires +- Meilleur compromis vitesse/compression **vs zip :** -- 🗜️ Meilleure compression -- 🔐 Préserve les permissions Unix et métadonnées -- 🌊 Meilleur support de streaming +- Meilleure compression +- Préserve les permissions Unix et métadonnées +- Meilleur support de streaming -## 📋 Exigences +## Exigences -- 🐍 Python 3.12 ou supérieur -- 📦 zstandard >= 0.19.0 +- Python 3.12 ou supérieur +- zstandard >= 0.19.0 -## 🛠️ Développement +## Développement -### 🚀 Configuration de l'environnement de développement +### Configuration de l'environnement de développement Ce projet utilise les standards modernes d'empaquetage Python : @@ -465,7 +466,7 @@ cd tzst pip install -e .[dev] ``` -### 🧪 Exécution des tests +### Exécution des tests ```bash # Exécuter les tests avec couverture @@ -475,7 +476,7 @@ pytest --cov=tzst --cov-report=html pytest ``` -### ✨ Qualité du code +### Qualité du code ```bash # Vérifier la qualité du code @@ -485,16 +486,16 @@ ruff check src tests ruff format src tests ``` -## 🤝 Contribution +## Contribution Nous accueillons les contributions ! Veuillez lire notre [Guide de contribution](CONTRIBUTING.md) pour : - Configuration de développement et structure du projet -- Directives de style de code et meilleures pratiques +- Directives de style de code et meilleures pratiques - Exigences de test et écriture de tests - Processus de pull request et workflow de révision -### 🚀 Démarrage rapide pour les contributeurs +### Démarrage rapide pour les contributeurs ```bash git clone https://github.com/xixu-me/tzst.git @@ -503,22 +504,22 @@ pip install -e .[dev] python -m pytest tests/ ``` -### 🎯 Types de contributions bienvenues +### Types de contributions bienvenues -- 🐛 **Corrections de bugs** - Corriger les problèmes dans la fonctionnalité existante -- ✨ **Fonctionnalités** - Ajouter de nouvelles capacités à la bibliothèque -- 📚 **Documentation** - Améliorer ou ajouter de la documentation -- 🧪 **Tests** - Ajouter ou améliorer la couverture de tests -- ⚡ **Performance** - Optimiser le code existant -- 🔒 **Sécurité** - Traiter les vulnérabilités de sécurité +- **Corrections de bugs** - Corriger les problèmes dans la fonctionnalité existante +- **Fonctionnalités** - Ajouter de nouvelles capacités à la bibliothèque +- **Documentation** - Améliorer ou ajouter de la documentation +- **Tests** - Ajouter ou améliorer la couverture de tests +- **Performance** - Optimiser le code existant +- **Sécurité** - Traiter les vulnérabilités de sécurité -## 🙏 Remerciements +## Remerciements - [Meta Zstandard](https://github.com/facebook/zstd) pour l'excellent algorithme de compression - [python-zstandard](https://github.com/indygreg/python-zstandard) pour les liaisons Python - La communauté Python pour l'inspiration et les retours -## 📄 Licence +## Licence Droits d'auteur © [Xi Xu](https://xi-xu.me). Tous droits réservés. diff --git a/README.ja.md b/README.ja.md index 0e7f524..c610e69 100644 --- a/README.ja.md +++ b/README.ja.md @@ -13,24 +13,25 @@ [🇺🇸 English](./README.md) | [🇨🇳 汉语](./README.zh.md) | [🇪🇸 español](./README.es.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** は、最新の Zstandard 圧縮技術を活用した次世代 Python ライブラリで、優れたパフォーマンス、セキュリティ、信頼性を提供するモダンなアーカイブ管理を実現します。 Python 3.12+ 専用に構築されたこのエンタープライズグレードのソリューションは、アトミック操作、ストリーミング効率、厳密に設計された API を組み合わせ、本番環境における `.tzst` / `.tar.zst` アーカイブの扱い方を再定義します。 🚀 +**tzst** は、Python 3.12+ 向けに `.tzst` / `.tar.zst` アーカイブの作成、展開、一覧表示、整合性確認を行うためのライブラリ兼 CLI です。tar 互換性、Zstandard 圧縮、ストリーミング処理、アトミック書き込み、デフォルトで安全な展開を、運用向けの簡潔なインターフェースにまとめています。 -技術詳細分析記事が公開されました: **[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 互換性**: Zstandard で圧縮された標準 tar アーカイブを作成 -- **💻 コマンドラインインターフェース**: ストリーミング対応の直感的な CLI と包括的なオプション -- **🐍 Python API**: プログラム利用のためのクリーンで Pythonic な API -- **🌍 クロスプラットフォーム**: Windows 、 macOS 、 Linux で動作 -- **📂 複数拡張子対応**: `.tzst` と `.tar.zst` の両方の拡張子をサポート -- **💾 メモリ効率**: 大容量アーカイブを最小メモリ使用量で処理するストリーミングモード -- **⚡ アトミック操作**: 中断時にも安全な自動クリーンアップ付きファイル操作 -- **🔒 デフォルトで安全**: 展開時の最大セキュリティのために「data」フィルタを使用 -- **🚨 強化されたエラーハンドリング**: 代替案を示す明確なエラーメッセージ +- **高圧縮率**: Zstandard 圧縮による優れた圧縮率と速度 +- **Tar 互換性**: Zstandard で圧縮された標準 tar アーカイブを作成 +- **コマンドラインインターフェース**: ストリーミング対応の直感的な CLI と包括的なオプション +- **Python API**: プログラム利用のためのクリーンで Pythonic な API +- **クロスプラットフォーム**: Windows 、 macOS 、 Linux で動作 +- **複数拡張子対応**: `.tzst` と `.tar.zst` の両方の拡張子をサポート +- **メモリ効率**: 大容量アーカイブを最小メモリ使用量で処理するストリーミングモード +- **アトミック操作**: 中断時にも安全な自動クリーンアップ付きファイル操作 +- **デフォルトで安全**: 展開時の最大セキュリティのために「data」フィルタを使用 +- **強化されたエラーハンドリング**: 代替案を示す明確なエラーメッセージ -## 📥 インストール +## インストール ### GitHub リリースから @@ -40,30 +41,30 @@ 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` | +| **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` 実行ファイル（Windows の場合は `tzst.exe` ）を取得 -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` 実行ファイル（Windows の場合は `tzst.exe` ）を取得 +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 @@ Zstandard 圧縮レベルは 1 (最速) から 22 (最高圧縮) の範囲: - **レベル 10-15**: 高圧縮、低速 - **レベル 20-22**: 最高圧縮、大幅に低速 -### 🌊 ストリーミングモード +### ストリーミングモード 大容量アーカイブのメモリ効率処理にストリーミングモードを使用: -**✅ 利点:** +**利点:** - メモリ使用量の大幅削減 - メモリに収まらないアーカイブのパフォーマンス向上 - リソースの自動クリーンアップ -**🎯 使用推奨ケース:** +**使用推奨ケース:** - 100 MB を超えるアーカイブ - メモリ制限環境 @@ -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. **🌊 ストリーミング**: 100 MB を超えるアーカイブで使用 -3. **📦 バッチ操作**: 単一セッションで複数ファイル追加 -4. **📄 ファイルタイプ**: 既に圧縮されたファイルはそれ以上圧縮されない +1. **圧縮レベル**: ほとんどのユースケースでレベル 3 が最適 +2. **ストリーミング**: 100 MB を超えるアーカイブで使用 +3. **バッチ操作**: 単一セッションで複数ファイル追加 +4. **ファイルタイプ**: 既に圧縮されたファイルはそれ以上圧縮されない -### 🆚 他のツールとの比較 +### 他のツールとの比較 **vs tar + gzip:** -- ✅ より高い圧縮率 -- ⚡ 高速な解凍 -- 🔄 モダンなアルゴリズム +- より高い圧縮率 +- 高速な解凍 +- モダンなアルゴリズム **vs tar + xz:** -- 🚀 大幅に高速な圧縮 -- 📊 同等の圧縮率 -- ⚖️ 速度/圧縮率のトレードオフが優れる +- 大幅に高速な圧縮 +- 同等の圧縮率 +- 速度/圧縮率のトレードオフが優れる **vs 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)をお読みください: - 開発セットアップとプロジェクト構造 -- コードスタイルガイドラインとベストプラクティス +- コードスタイルガイドラインとベストプラクティス - テスト要件とテスト作成 - プルリクエストプロセスとレビューワークフロー -### 🚀 貢献者向けクイックスタート +### 貢献者向けクイックスタート ```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 コミュニティ -## 📄 ライセンス +## ライセンス 著作権 © [Xi Xu](https://xi-xu.me)。全著作権を保留します。 diff --git a/README.ko.md b/README.ko.md index af290f3..e5ec72e 100644 --- a/README.ko.md +++ b/README.ko.md @@ -13,24 +13,25 @@ [🇺🇸 English](./README.md) | [🇨🇳 汉语](./README.zh.md) | [🇪🇸 español](./README.es.md) | [🇯🇵 日本語](./README.ja.md) | [🇦🇪 العربية](./README.ar.md) | [🇷🇺 русский](./README.ru.md) | [🇩🇪 Deutsch](./README.de.md) | [🇫🇷 français](./README.fr.md) | **🇰🇷 한국어** | [🇧🇷 português](./README.pt.md) -**tzst**는 최신 Zstandard 압축 기술을 활용하여 우수한 성능, 보안 및 신뢰성을 제공하는 차세대 Python 라이브러리입니다. Python 3.12+ 전용으로 제작된 이 엔터프라이즈급 솔루션은 원자적 작업, 스트리밍 효율성 및 정교하게 설계된 API를 결합하여 `.tzst`/`.tar.zst` 아카이브를 프로덕션 환경에서 처리하는 방식을 재정의합니다. 🚀 +**tzst**는 Python 3.12+에서 `.tzst` 및 `.tar.zst` 아카이브를 생성, 추출, 나열, 검사하기 위한 라이브러리이자 CLI입니다. tar 호환성, Zstandard 압축, 스트리밍 처리, 원자적 쓰기, 기본 안전 추출을 운영 환경에 적합한 간결한 인터페이스로 제공합니다. -심층 기술 분석 기사가 게시되었습니다: **[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 호환성**: Zstandard로 압축된 표준 tar 아카이브 생성 -- **💻 명령줄 인터페이스**: 스트리밍 지원과 포괄적인 옵션을 갖춘 직관적인 CLI -- **🐍 Python API**: 프로그램적 사용을 위한 깔끔하고 Python 스타일의 API -- **🌍 크로스 플랫폼**: Windows, macOS, Linux에서 작동 -- **📂 다중 확장자**: `.tzst` 및 `.tar.zst` 확장자 모두 지원 -- **💾 메모리 효율적**: 최소 메모리 사용으로 대용량 아카이브 처리 가능한 스트리밍 모드 -- **⚡ 원자적 작업**: 중단 시 자동 정리 기능을 통한 안전한 파일 작업 -- **🔒 기본 보안**: 추출 시 최대 보안을 위해 'data' 필터 사용 -- **🚨 향상된 오류 처리**: 유용한 대안 제시와 함께 명확한 오류 메시지 +- **고압축률**: 우수한 압축률과 속도를 위한 Zstandard 압축 +- **Tar 호환성**: Zstandard로 압축된 표준 tar 아카이브 생성 +- **명령줄 인터페이스**: 스트리밍 지원과 포괄적인 옵션을 갖춘 직관적인 CLI +- **Python API**: 프로그램적 사용을 위한 깔끔하고 Python 스타일의 API +- **크로스 플랫폼**: Windows, macOS, Linux에서 작동 +- **다중 확장자**: `.tzst` 및 `.tar.zst` 확장자 모두 지원 +- **메모리 효율적**: 최소 메모리 사용으로 대용량 아카이브 처리 가능한 스트리밍 모드 +- **원자적 작업**: 중단 시 자동 정리 기능을 통한 안전한 파일 작업 +- **기본 보안**: 추출 시 최대 보안을 위해 'data' 필터 사용 +- **향상된 오류 처리**: 유용한 대안 제시와 함께 명확한 오류 메시지 -## 📥 설치 +## 설치 ### GitHub 릴리스에서 @@ -40,30 +41,30 @@ 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` | +| **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` 실행 파일 획득 (Windows는 `tzst.exe`) -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` 실행 파일 획득 (Windows는 `tzst.exe`) +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 @@ Zstandard 압축 레벨 범위: 1 (가장 빠름) ~ 22 (최대 압축): - **레벨 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. **파일 유형**: 이미 압축된 파일은 추가 압축이 거의 안됨 -### 🆚 다른 도구와 비교 +### 다른 도구와 비교 **vs tar + gzip:** -- ✅ 더 나은 압축률 -- ⚡ 더 빠른 압축 해제 -- 🔄 현대적인 알고리즘 +- 더 나은 압축률 +- 더 빠른 압축 해제 +- 현대적인 알고리즘 **vs tar + xz:** -- 🚀 현저히 빠른 압축 -- 📊 유사한 압축률 -- ⚖️ 더 나은 속도/압축률 균형 +- 현저히 빠른 압축 +- 유사한 압축률 +- 더 나은 속도/압축률 균형 **vs 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)를 읽어주세요: - 개발 설정 및 프로젝트 구조 -- 코드 스타일 가이드라인 및 모범 사례 +- 코드 스타일 가이드라인 및 모범 사례 - 테스트 요구 사항 및 테스트 작성 방법 - 풀 리퀘스트 프로세스 및 리뷰 워크플로 -### 🚀 기여자 빠른 시작 +### 기여자 빠른 시작 ```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 바인딩을 제공한 [python-zstandard](https://github.com/indygreg/python-zstandard) - 영감과 피드백을 준 Python 커뮤니티 -## 📄 라이선스 +## 라이선스 저작권 © [시 쉬](https://xi-xu.me). 모든 권리 보유. diff --git a/README.md b/README.md index 7916d45..c0349e5 100644 --- a/README.md +++ b/README.md @@ -16,24 +16,25 @@ **🇺🇸 English** | [🇨🇳 汉语](./README.zh.md) | [🇪🇸 español](./README.es.md) | [🇯🇵 日本語](./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** is a next-generation Python library engineered for modern archive management, leveraging cutting-edge Zstandard compression to deliver superior performance, security, and reliability. Built exclusively for Python 3.12+, this enterprise-grade solution combines atomic operations, streaming efficiency, and a meticulously crafted API to redefine how developers handle `.tzst`/`.tar.zst` archives in production environments. 🚀 +**tzst** is a Python 3.12+ library and CLI for creating, extracting, listing, and testing `.tzst` and `.tar.zst` archives. It combines tar compatibility, Zstandard compression, streaming support, atomic writes, and safe-by-default extraction in a compact, production-ready interface. -In-depth technical analysis article published: **[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] +> In-depth technical article: **[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)**. -## ✨ Features +## Features -- **🗜️ High Compression**: Zstandard compression for excellent compression ratios and speed -- **📁 Tar Compatibility**: Creates standard tar archives compressed with Zstandard -- **💻 Command Line Interface**: Intuitive CLI with streaming support and comprehensive options -- **🐍 Python API**: Clean, Pythonic API for programmatic use -- **🌍 Cross-Platform**: Works on Windows, macOS, and Linux -- **📂 Multiple Extensions**: Supports both `.tzst` and `.tar.zst` extensions -- **💾 Memory Efficient**: Streaming mode for handling large archives with minimal memory usage -- **⚡ Atomic Operations**: Safe file operations with automatic cleanup on interruption -- **🔒 Secure by Default**: Uses the 'data' filter for maximum security during extraction -- **🚨 Enhanced Error Handling**: Clear error messages with helpful alternatives +- **High Compression**: Zstandard compression for excellent compression ratios and speed +- **Tar Compatibility**: Creates standard tar archives compressed with Zstandard +- **Command Line Interface**: Intuitive CLI with streaming support and comprehensive options +- **Python API**: Clean, Pythonic API for programmatic use +- **Cross-Platform**: Works on Windows, macOS, and Linux +- **Multiple Extensions**: Supports both `.tzst` and `.tar.zst` extensions +- **Memory Efficient**: Streaming mode for handling large archives with minimal memory usage +- **Atomic Operations**: Safe file operations with automatic cleanup on interruption +- **Secure by Default**: Uses the 'data' filter for maximum security during extraction +- **Enhanced Error Handling**: Clear error messages with helpful alternatives -## 📥 Installation +## Installation ### From GitHub Releases @@ -43,30 +44,30 @@ Download standalone executables that don't require Python installation: | Platform | Architecture | File | |----------|-------------|------| -| **🐧 Linux** | x86_64 | `tzst-{version}-linux-amd64.zip` | -| **🐧 Linux** | ARM64 | `tzst-{version}-linux-arm64.zip` | -| **🪟 Windows** | x64 | `tzst-{version}-windows-amd64.zip` | -| **🪟 Windows** | ARM64 | `tzst-{version}-windows-arm64.zip` | -| **🍎 macOS** | Intel | `tzst-{version}-darwin-amd64.zip` | -| **🍎 macOS** | Apple Silicon | `tzst-{version}-darwin-arm64.zip` | +| **Linux** | x86_64 | `tzst-{version}-linux-amd64.zip` | +| **Linux** | ARM64 | `tzst-{version}-linux-arm64.zip` | +| **Windows** | x64 | `tzst-{version}-windows-amd64.zip` | +| **Windows** | ARM64 | `tzst-{version}-windows-arm64.zip` | +| **macOS** | Intel | `tzst-{version}-darwin-amd64.zip` | +| **macOS** | Apple Silicon | `tzst-{version}-darwin-arm64.zip` | -#### 🛠️ Installation Steps +#### Installation Steps -1. **📥 Download** the appropriate archive for your platform from the [latest releases page](https://github.com/xixu-me/tzst/releases/latest) -2. **📦 Extract** the archive to get the `tzst` executable (or `tzst.exe` on Windows) -3. **📂 Move** the executable to a directory in your PATH: - - **🐧 Linux/macOS**: `sudo mv tzst /usr/local/bin/` - - **🪟 Windows**: Add the directory containing `tzst.exe` to your PATH environment variable -4. **✅ Verify** installation: `tzst --help` +1. **Download** the appropriate archive for your platform from the [latest releases page](https://github.com/xixu-me/tzst/releases/latest) +2. **Extract** the archive to get the `tzst` executable (or `tzst.exe` on Windows) +3. **Move** the executable to a directory in your PATH: + - **Linux/macOS**: `sudo mv tzst /usr/local/bin/` + - **Windows**: Add the directory containing `tzst.exe` to your PATH environment variable +4. **Verify** installation: `tzst --help` -#### 🎯 Benefits of Binary Installation +#### Benefits of Binary Installation -- ✅ **No Python required** - Standalone executable -- ✅ **Faster startup** - No Python interpreter overhead -- ✅ **Easy deployment** - Single file distribution -- ✅ **Consistent behavior** - Bundled dependencies +- **No Python required** - Standalone executable +- **Faster startup** - No Python interpreter overhead +- **Easy deployment** - Single file distribution +- **Consistent behavior** - Bundled dependencies -### 📦 From PyPI +### From PyPI Using pip: @@ -80,7 +81,7 @@ Or using uv (recommended): uv tool install tzst ``` -### 🔧 From Source +### From Source ```bash git clone https://github.com/xixu-me/tzst.git @@ -88,7 +89,7 @@ cd tzst pip install . ``` -### 🚀 Development Installation +### Development Installation This project uses modern Python packaging standards: @@ -98,25 +99,25 @@ cd tzst pip install -e .[dev] ``` -## 🚀 Quick Start +## Quick Start -### 💻 Command Line Usage +### Command Line Usage ```bash -# 📁 Create an archive +# Create an archive tzst a archive.tzst file1.txt file2.txt directory/ -# 📤 Extract an archive +# Extract an archive tzst x archive.tzst -# 📋 List archive contents +# List archive contents tzst l archive.tzst -# 🧪 Test archive integrity +# Test archive integrity tzst t archive.tzst ``` -### 🐍 Python API Usage +### Python API Usage ```python from tzst import create_archive, extract_archive, list_archive @@ -133,11 +134,11 @@ for item in contents: print(f"{item['name']}: {item['size']} bytes") ``` -## 💻 Command Line Interface +## Command Line Interface -### 📁 Archive Operations +### Archive Operations -#### ➕ Create Archive +#### Create Archive ```bash # Basic usage @@ -151,7 +152,7 @@ tzst add archive.tzst files/ tzst create archive.tzst files/ ``` -#### 📤 Extract Archive +#### Extract Archive ```bash # Extract with full directory structure @@ -170,7 +171,7 @@ tzst e archive.tzst -o output/ tzst x archive.tzst --streaming -o output/ ``` -#### 📋 List Contents +#### List Contents ```bash # Simple listing @@ -183,7 +184,7 @@ tzst l archive.tzst -v tzst l archive.tzst --streaming -v ``` -#### 🧪 Test Integrity +#### Test Integrity ```bash # Test archive integrity @@ -193,7 +194,7 @@ tzst t archive.tzst tzst t archive.tzst --streaming ``` -### 📊 Command Reference +### Command Reference | Command | Aliases | Description | Streaming Support | |---------|---------|-------------|-------------------| @@ -203,7 +204,7 @@ tzst t archive.tzst --streaming | `l` | `list` | List archive contents | ✓ `--streaming` | | `t` | `test` | Test archive integrity | ✓ `--streaming` | -### ⚙️ CLI Options +### CLI Options - `-v, --verbose`: Enable verbose output - `-o, --output DIR`: Specify output directory (extract commands) @@ -212,7 +213,7 @@ tzst t archive.tzst --streaming - `--filter FILTER`: Security filter for extraction (data/tar/fully_trusted) - `--no-atomic`: Disable atomic file operations (not recommended) -### 🔒 Security Filters +### Security Filters ```bash # Extract with maximum security (default) @@ -225,15 +226,15 @@ tzst x archive.tzst --filter tar tzst x archive.tzst --filter fully_trusted ``` -**🔐 Security Filter Options:** +**Security Filter Options:** - `data` (default): Most secure. Blocks dangerous files, absolute paths, and paths outside extraction directory - `tar`: Standard tar compatibility. Blocks absolute paths and directory traversal - `fully_trusted`: No security restrictions. Only use with completely trusted archives -## 🐍 Python API +## Python API -### 📦 TzstArchive Class +### TzstArchive Class ```python from tzst import TzstArchive @@ -259,13 +260,13 @@ with TzstArchive("large_archive.tzst", "r", streaming=True) as archive: archive.extract(path="output/") ``` -**⚠️ Important Limitations:** +**Important Limitations:** -- **❌ Append Mode Not Supported**: Create multiple archives or recreate the entire archive instead +- **Append Mode Not Supported**: Create multiple archives or recreate the entire archive instead -### 🎯 Convenience Functions +### Convenience Functions -#### 📁 create_archive() +#### create_archive() ```python from tzst import create_archive @@ -278,7 +279,7 @@ create_archive( ) ``` -#### 📤 extract_archive() +#### extract_archive() ```python from tzst import extract_archive @@ -296,7 +297,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 @@ -311,7 +312,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 @@ -325,9 +326,9 @@ if test_archive("large_backup.tzst", streaming=True): print("Large archive is valid") ``` -## 🔧 Advanced Features +## Advanced Features -### 📂 File Extensions +### File Extensions The library automatically handles file extensions with intelligent normalization: @@ -344,7 +345,7 @@ create_archive("backup", files) # Creates backup.tzst create_archive("backup.txt", files) # Creates backup.tzst (normalized) ``` -### 🗜️ Compression Levels +### Compression Levels Zstandard compression levels range from 1 (fastest) to 22 (best compression): @@ -353,17 +354,17 @@ Zstandard compression levels range from 1 (fastest) to 22 (best compression): - **Level 10-15**: Better compression, slower - **Level 20-22**: Maximum compression, much slower -### 🌊 Streaming Mode +### Streaming Mode Use streaming mode for memory-efficient processing of large archives: -**✅ Benefits:** +**Benefits:** - Significantly reduced memory usage - Better performance for archives that don't fit in memory - Automatic cleanup of resources -**🎯 When to Use:** +**When to Use:** - Archives larger than 100MB - Limited memory environments @@ -381,7 +382,7 @@ contents = list_archive(large_archive, streaming=True, verbose=True) extract_archive(large_archive, "restore/", streaming=True) ``` -### ⚡ Atomic Operations +### Atomic Operations All file creation operations use atomic file operations by default: @@ -398,7 +399,7 @@ create_archive("important.tzst", files) # Safe from interruption create_archive("test.tzst", files, use_temp_file=False) ``` -### 🚨 Error Handling +### Error Handling ```python from tzst import TzstArchive @@ -422,43 +423,43 @@ except KeyboardInterrupt: # Cleanup handled automatically ``` -## 🚀 Performance and Comparison +## Performance and Comparison -### 💡 Performance Tips +### Performance Tips -1. **🗜️ Compression levels**: Level 3 is optimal for most use cases -2. **🌊 Streaming**: Use for archives larger than 100MB -3. **📦 Batch operations**: Add multiple files in single session -4. **📄 File types**: Already compressed files won't compress much further +1. **Compression levels**: Level 3 is optimal for most use cases +2. **Streaming**: Use for archives larger than 100MB +3. **Batch operations**: Add multiple files in single session +4. **File types**: Already compressed files won't compress much further -### 🆚 vs Other Tools +### vs Other Tools **vs tar + gzip:** -- ✅ Better compression ratios -- ⚡ Faster decompression -- 🔄 Modern algorithm +- Better compression ratios +- Faster decompression +- Modern algorithm **vs tar + xz:** -- 🚀 Significantly faster compression -- 📊 Similar compression ratios -- ⚖️ Better speed/compression trade-off +- Significantly faster compression +- Similar compression ratios +- Better speed/compression trade-off **vs zip:** -- 🗜️ Better compression -- 🔐 Preserves Unix permissions and metadata -- 🌊 Better streaming support +- Better compression +- Preserves Unix permissions and metadata +- Better streaming support -## 📋 Requirements +## Requirements -- 🐍 Python 3.12 or higher (tested on 3.12-3.14) -- 📦 zstandard >= 0.19.0 +- Python 3.12 or higher (tested on 3.12-3.14) +- zstandard >= 0.19.0 -## 🛠️ Development +## Development -### 🚀 Setting up Development Environment +### Setting up Development Environment This project uses modern Python packaging standards: @@ -468,7 +469,7 @@ cd tzst pip install -e .[dev] ``` -### 🧪 Running Tests +### Running Tests ```bash # Run tests with coverage @@ -478,7 +479,7 @@ pytest --cov=tzst --cov-report=html pytest ``` -### ✨ Code Quality +### Code Quality ```bash # Check code quality @@ -488,16 +489,16 @@ ruff check src tests ruff format src tests ``` -## 🤝 Contributing +## Contributing We welcome contributions! Please read our [Contributing Guide](CONTRIBUTING.md) for: - Development setup and project structure -- Code style guidelines and best practices +- Code style guidelines and best practices - Testing requirements and writing tests - Pull request process and review workflow -### 🚀 Quick Start for Contributors +### Quick Start for Contributors ```bash git clone https://github.com/xixu-me/tzst.git @@ -506,22 +507,22 @@ pip install -e .[dev] python -m pytest tests/ ``` -### 🎯 Types of Contributions Welcome +### Types of Contributions Welcome -- 🐛 **Bug fixes** - Fix issues in existing functionality -- ✨ **Features** - Add new capabilities to the library -- 📚 **Documentation** - Improve or add documentation -- 🧪 **Tests** - Add or improve test coverage -- ⚡ **Performance** - Optimize existing code -- 🔒 **Security** - Address security vulnerabilities +- **Bug fixes** - Fix issues in existing functionality +- **Features** - Add new capabilities to the library +- **Documentation** - Improve or add documentation +- **Tests** - Add or improve test coverage +- **Performance** - Optimize existing code +- **Security** - Address security vulnerabilities -## 🙏 Acknowledgments +## Acknowledgments - [Meta Zstandard](https://github.com/facebook/zstd) for the excellent compression algorithm - [python-zstandard](https://github.com/indygreg/python-zstandard) for Python bindings - The Python community for inspiration and feedback -## 📄 License +## License Copyright © [Xi Xu](https://xi-xu.me). All rights reserved. diff --git a/README.pt.md b/README.pt.md index c2fc8ea..caadf31 100644 --- a/README.pt.md +++ b/README.pt.md @@ -13,24 +13,25 @@ [🇺🇸 English](./README.md) | [🇨🇳 汉语](./README.zh.md) | [🇪🇸 español](./README.es.md) | [🇯🇵 日本語](./README.ja.md) | [🇦🇪 العربية](./README.ar.md) | [🇷🇺 русский](./README.ru.md) | [🇩🇪 Deutsch](./README.de.md) | [🇫🇷 français](./README.fr.md) | [🇰🇷 한국어](./README.ko.md) | **🇧🇷 português** -**tzst** é uma biblioteca Python de próxima geração projetada para gerenciamento moderno de arquivos, aproveitando a compressão Zstandard de ponta para oferecer desempenho, segurança e confiabilidade superiores. Construída exclusivamente para Python 3.12+, esta solução corporativa combina operações atômicas, eficiência de streaming e uma API meticulosamente elaborada para redefinir como os desenvolvedores lidam com arquivos `.tzst`/`.tar.zst` em ambientes de produção. 🚀 +**tzst** é uma biblioteca e CLI para Python 3.12+ voltada para criar, extrair, listar e validar arquivos `.tzst` e `.tar.zst`. Ela combina compatibilidade com tar, compressão Zstandard, modo streaming, gravações atômicas e extração segura por padrão em uma interface compacta pronta para produção. -Artigo de análise técnica aprofundada publicado: **[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] +> Artigo técnico detalhado: **[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)**. -## ✨ Recursos +## Recursos -- **🗜️ Alta Compressão**: Compressão Zstandard para excelentes taxas de compressão e velocidade -- **📁 Compatibilidade com Tar**: Cria arquivos tar padrão comprimidos com Zstandard -- **💻 Interface de Linha de Comando**: CLI intuitiva com suporte a streaming e opções abrangentes -- **🐍 API Python**: API limpa e pythônica para uso programático -- **🌍 Multiplataforma**: Funciona no Windows, macOS e Linux -- **📂 Múltiplas Extensões**: Suporta tanto extensões `.tzst` quanto `.tar.zst` -- **💾 Eficiente em Memória**: Modo streaming para lidar com grandes arquivos com uso mínimo de memória -- **⚡ Operações Atômicas**: Operações de arquivo seguras com limpeza automática em caso de interrupção -- **🔒 Seguro por Padrão**: Usa o filtro 'data' para máxima segurança durante a extração -- **🚨 Tratamento de Erros Aprimorado**: Mensagens de erro claras com alternativas úteis +- **Alta Compressão**: Compressão Zstandard para excelentes taxas de compressão e velocidade +- **Compatibilidade com Tar**: Cria arquivos tar padrão comprimidos com Zstandard +- **Interface de Linha de Comando**: CLI intuitiva com suporte a streaming e opções abrangentes +- **API Python**: API limpa e pythônica para uso programático +- **Multiplataforma**: Funciona no Windows, macOS e Linux +- **Múltiplas Extensões**: Suporta tanto extensões `.tzst` quanto `.tar.zst` +- **Eficiente em Memória**: Modo streaming para lidar com grandes arquivos com uso mínimo de memória +- **Operações Atômicas**: Operações de arquivo seguras com limpeza automática em caso de interrupção +- **Seguro por Padrão**: Usa o filtro 'data' para máxima segurança durante a extração +- **Tratamento de Erros Aprimorado**: Mensagens de erro claras com alternativas úteis -## 📥 Instalação +## Instalação ### Dos Releases do GitHub @@ -40,30 +41,30 @@ Baixe executáveis independentes que não requerem instalação do Python: | Plataforma | Arquitetura | Arquivo | |----------|-------------|------| -| **🐧 Linux** | x86_64 | `tzst-{versão}-linux-amd64.zip` | -| **🐧 Linux** | ARM64 | `tzst-{versão}-linux-arm64.zip` | -| **🪟 Windows** | x64 | `tzst-{versão}-windows-amd64.zip` | -| **🪟 Windows** | ARM64 | `tzst-{versão}-windows-arm64.zip` | -| **🍎 macOS** | Intel | `tzst-{versão}-darwin-amd64.zip` | -| **🍎 macOS** | Apple Silicon | `tzst-{versão}-darwin-arm64.zip` | +| **Linux** | x86_64 | `tzst-{versão}-linux-amd64.zip` | +| **Linux** | ARM64 | `tzst-{versão}-linux-arm64.zip` | +| **Windows** | x64 | `tzst-{versão}-windows-amd64.zip` | +| **Windows** | ARM64 | `tzst-{versão}-windows-arm64.zip` | +| **macOS** | Intel | `tzst-{versão}-darwin-amd64.zip` | +| **macOS** | Apple Silicon | `tzst-{versão}-darwin-arm64.zip` | -#### 🛠️ Passos de Instalação +#### Passos de Instalação -1. **📥 Baixe** o arquivo apropriado para sua plataforma da [página de releases mais recentes](https://github.com/xixu-me/tzst/releases/latest) -2. **📦 Extraia** o arquivo para obter o executável `tzst` (ou `tzst.exe` no Windows) -3. **📂 Mova** o executável para um diretório em seu PATH: - - **🐧 Linux/macOS**: `sudo mv tzst /usr/local/bin/` - - **🪟 Windows**: Adicione o diretório contendo `tzst.exe` à sua variável de ambiente PATH -4. **✅ Verifique** a instalação: `tzst --help` +1. **Baixe** o arquivo apropriado para sua plataforma da [página de releases mais recentes](https://github.com/xixu-me/tzst/releases/latest) +2. **Extraia** o arquivo para obter o executável `tzst` (ou `tzst.exe` no Windows) +3. **Mova** o executável para um diretório em seu PATH: + - **Linux/macOS**: `sudo mv tzst /usr/local/bin/` + - **Windows**: Adicione o diretório contendo `tzst.exe` à sua variável de ambiente PATH +4. **Verifique** a instalação: `tzst --help` -#### 🎯 Benefícios da Instalação Binária +#### Benefícios da Instalação Binária -- ✅ **Python não é necessário** - Executável independente -- ✅ **Inicialização mais rápida** - Sem overhead do interpretador Python -- ✅ **Implantação fácil** - Distribuição de arquivo único -- ✅ **Comportamento consistente** - Dependências incluídas +- **Python não é necessário** - Executável independente +- **Inicialização mais rápida** - Sem overhead do interpretador Python +- **Implantação fácil** - Distribuição de arquivo único +- **Comportamento consistente** - Dependências incluídas -### 📦 Do PyPI +### Do PyPI Usando pip: @@ -77,7 +78,7 @@ Ou usando uv (recomendado): uv tool install tzst ``` -### 🔧 Do Código Fonte +### Do Código Fonte ```bash git clone https://github.com/xixu-me/tzst.git @@ -85,7 +86,7 @@ cd tzst pip install . ``` -### 🚀 Instalação para Desenvolvimento +### Instalação para Desenvolvimento Este projeto usa padrões modernos de empacotamento Python: @@ -95,25 +96,25 @@ cd tzst pip install -e .[dev] ``` -## 🚀 Início Rápido +## Início Rápido -### 💻 Uso da Linha de Comando +### Uso da Linha de Comando ```bash -# 📁 Criar um arquivo +# Criar um arquivo tzst a archive.tzst file1.txt file2.txt directory/ -# 📤 Extrair um arquivo +# Extrair um arquivo tzst x archive.tzst -# 📋 Listar conteúdo do arquivo +# Listar conteúdo do arquivo tzst l archive.tzst -# 🧪 Testar integridade do arquivo +# Testar integridade do arquivo tzst t archive.tzst ``` -### 🐍 Uso da API Python +### Uso da API Python ```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") ``` -## 💻 Interface de Linha de Comando +## Interface de Linha de Comando -### 📁 Operações de Arquivo +### Operações de Arquivo -#### ➕ Criar Arquivo +#### Criar Arquivo ```bash # Uso básico @@ -148,7 +149,7 @@ tzst add archive.tzst files/ tzst create archive.tzst files/ ``` -#### 📤 Extrair Arquivo +#### Extrair Arquivo ```bash # Extrair com estrutura completa de diretórios @@ -167,7 +168,7 @@ tzst e archive.tzst -o output/ tzst x archive.tzst --streaming -o output/ ``` -#### 📋 Listar Conteúdo +#### Listar Conteúdo ```bash # Listagem simples @@ -180,7 +181,7 @@ tzst l archive.tzst -v tzst l archive.tzst --streaming -v ``` -#### 🧪 Testar Integridade +#### Testar Integridade ```bash # Testar integridade do arquivo @@ -190,7 +191,7 @@ tzst t archive.tzst tzst t archive.tzst --streaming ``` -### 📊 Referência de Comandos +### Referência de Comandos | Comando | Aliases | Descrição | Suporte a Streaming | |---------|---------|-------------|-------------------| @@ -200,7 +201,7 @@ tzst t archive.tzst --streaming | `l` | `list` | Listar conteúdo do arquivo | ✓ `--streaming` | | `t` | `test` | Testar integridade do arquivo | ✓ `--streaming` | -### ⚙️ Opções da CLI +### Opções da CLI - `-v, --verbose`: Ativar saída detalhada - `-o, --output DIR`: Especificar diretório de saída (comandos de extração) @@ -209,7 +210,7 @@ tzst t archive.tzst --streaming - `--filter FILTER`: Filtro de segurança para extração (data/tar/fully_trusted) - `--no-atomic`: Desativar operações de arquivo atômicas (não recomendado) -### 🔒 Filtros de Segurança +### Filtros de Segurança ```bash # Extrair com máxima segurança (padrão) @@ -222,15 +223,15 @@ tzst x archive.tzst --filter tar tzst x archive.tzst --filter fully_trusted ``` -**🔐 Opções de Filtro de Segurança:** +**Opções de Filtro de Segurança:** - `data` (padrão): Mais seguro. Bloqueia arquivos perigosos, caminhos absolutos e caminhos fora do diretório de extração - `tar`: Compatibilidade tar padrão. Bloqueia caminhos absolutos e travessia de diretórios - `fully_trusted`: Sem restrições de segurança. Use apenas com arquivos completamente confiáveis -## 🐍 API Python +## API Python -### 📦 Classe TzstArchive +### Classe TzstArchive ```python from tzst import TzstArchive @@ -256,13 +257,13 @@ with TzstArchive("large_archive.tzst", "r", streaming=True) as archive: archive.extract(path="output/") ``` -**⚠️ Limitações Importantes:** +**Limitações Importantes:** -- **❌ Modo de anexação não suportado**: Crie múltiplos arquivos ou recrie o arquivo inteiro em vez disso +- **Modo de anexação não suportado**: Crie múltiplos arquivos ou recrie o arquivo inteiro em vez disso -### 🎯 Funções de Conveniência +### Funções de Conveniência -#### 📁 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("Grande arquivo é válido") ``` -## 🔧 Recursos Avançados +## Recursos Avançados -### 📂 Extensões de Arquivo +### Extensões de Arquivo A biblioteca automaticamente lida com extensões de arquivo com normalização inteligente: @@ -341,7 +342,7 @@ create_archive("backup", files) # Cria backup.tzst create_archive("backup.txt", files) # Cria backup.tzst (normalizado) ``` -### 🗜️ Níveis de Compressão +### Níveis de Compressão Os níveis de compressão Zstandard variam de 1 (mais rápido) a 22 (melhor compressão): @@ -350,17 +351,17 @@ Os níveis de compressão Zstandard variam de 1 (mais rápido) a 22 (melhor comp - **Nível 10-15**: Melhor compressão, mais lento - **Nível 20-22**: Compressão máxima, muito mais lento -### 🌊 Modo Streaming +### Modo Streaming Use o modo streaming para processamento eficiente em memória de grandes arquivos: -**✅ Benefícios:** +**Benefícios:** - Uso de memória significativamente reduzido - Melhor desempenho para arquivos que não cabem na memória - Limpeza automática de recursos -**🎯 Quando usar:** +**Quando usar:** - Arquivos maiores que 100MB - Ambientes com memória limitada @@ -378,7 +379,7 @@ contents = list_archive(large_archive, streaming=True, verbose=True) extract_archive(large_archive, "restore/", streaming=True) ``` -### ⚡ Operações Atômicas +### Operações Atômicas Todas as operações de criação de arquivo usam operações de arquivo atômicas por padrão: @@ -395,7 +396,7 @@ create_archive("important.tzst", files) # Seguro contra interrupção create_archive("test.tzst", files, use_temp_file=False) ``` -### 🚨 Tratamento de Erros +### Tratamento de Erros ```python from tzst import TzstArchive @@ -419,43 +420,43 @@ except KeyboardInterrupt: # Limpeza é tratada automaticamente ``` -## 🚀 Desempenho e Comparação +## Desempenho e Comparação -### 💡 Dicas de Desempenho +### Dicas de Desempenho -1. **🗜️ Níveis de compressão**: Nível 3 é ótimo para a maioria dos casos de uso -2. **🌊 Streaming**: Use para arquivos maiores que 100MB -3. **📦 Operações em lote**: Adicione múltiplos arquivos em uma única sessão -4. **📄 Tipos de arquivo**: Arquivos já comprimidos não comprimirão muito mais +1. **Níveis de compressão**: Nível 3 é ótimo para a maioria dos casos de uso +2. **Streaming**: Use para arquivos maiores que 100MB +3. **Operações em lote**: Adicione múltiplos arquivos em uma única sessão +4. **Tipos de arquivo**: Arquivos já comprimidos não comprimirão muito mais -### 🆚 vs Outras Ferramentas +### vs Outras Ferramentas **vs tar + gzip:** -- ✅ Melhores taxas de compressão -- ⚡ Descompressão mais rápida -- 🔄 Algoritmo moderno +- Melhores taxas de compressão +- Descompressão mais rápida +- Algoritmo moderno **vs tar + xz:** -- 🚀 Compressão significativamente mais rápida -- 📊 Taxas de compressão similares -- ⚖️ Melhor compromisso velocidade/compressão +- Compressão significativamente mais rápida +- Taxas de compressão similares +- Melhor compromisso velocidade/compressão **vs zip:** -- 🗜️ Melhor compressão -- 🔐 Preserva permissões Unix e metadados -- 🌊 Melhor suporte a streaming +- Melhor compressão +- Preserva permissões Unix e metadados +- Melhor suporte a streaming -## 📋 Requisitos +## Requisitos -- 🐍 Python 3.12 ou superior -- 📦 zstandard >= 0.19.0 +- Python 3.12 ou superior +- zstandard >= 0.19.0 -## 🛠️ Desenvolvimento +## Desenvolvimento -### 🚀 Configurando Ambiente de Desenvolvimento +### Configurando Ambiente de Desenvolvimento Este projeto usa padrões modernos de empacotamento Python: @@ -465,7 +466,7 @@ cd tzst pip install -e .[dev] ``` -### 🧪 Executando Testes +### Executando Testes ```bash # Executar testes com cobertura @@ -475,7 +476,7 @@ pytest --cov=tzst --cov-report=html pytest ``` -### ✨ Qualidade do Código +### Qualidade do Código ```bash # Verificar qualidade do código @@ -485,16 +486,16 @@ ruff check src tests ruff format src tests ``` -## 🤝 Contribuindo +## Contribuindo Nós recebemos contribuições! Por favor, leia nosso [Guia de Contribuição](CONTRIBUTING.md) para: - Configuração de desenvolvimento e estrutura do projeto -- Diretrizes de estilo de código e melhores práticas +- Diretrizes de estilo de código e melhores práticas - Requisitos de teste e escrita de testes - Processo de pull request e fluxo de revisão -### 🚀 Início Rápido para Colaboradores +### Início Rápido para Colaboradores ```bash git clone https://github.com/xixu-me/tzst.git @@ -503,22 +504,22 @@ pip install -e .[dev] python -m pytest tests/ ``` -### 🎯 Tipos de Contribuições Bem-vindas +### Tipos de Contribuições Bem-vindas -- 🐛 **Correções de bugs** - Corrigir problemas na funcionalidade existente -- ✨ **Recursos** - Adicionar novas capacidades à biblioteca -- 📚 **Documentação** - Melhorar ou adicionar documentação -- 🧪 **Testes** - Adicionar ou melhorar cobertura de testes -- ⚡ **Desempenho** - Otimizar código existente -- 🔒 **Segurança** - Abordar vulnerabilidades de segurança +- **Correções de bugs** - Corrigir problemas na funcionalidade existente +- **Recursos** - Adicionar novas capacidades à biblioteca +- **Documentação** - Melhorar ou adicionar documentação +- **Testes** - Adicionar ou melhorar cobertura de testes +- **Desempenho** - Otimizar código existente +- **Segurança** - Abordar vulnerabilidades de segurança -## 🙏 Agradecimentos +## Agradecimentos - [Meta Zstandard](https://github.com/facebook/zstd) pelo excelente algoritmo de compressão - [python-zstandard](https://github.com/indygreg/python-zstandard) pelas ligações Python - A comunidade Python pela inspiração e feedback -## 📄 Licença +## Licença Direitos autorais © [Xi Xu](https://xi-xu.me). Todos os direitos reservados. diff --git a/README.ru.md b/README.ru.md index d63d7df..819a2c7 100644 --- a/README.ru.md +++ b/README.ru.md @@ -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). Все права защищены. diff --git a/README.zh.md b/README.zh.md index 347a84f..904a658 100644 --- a/README.zh.md +++ b/README.zh.md @@ -16,24 +16,25 @@ [🇺🇸 English](./README.md) | **🇨🇳 汉语** | [🇪🇸 español](./README.es.md) | [🇯🇵 日本語](./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** 是一个面向现代归档管理的新一代 Python 库，利用前沿的 Zstandard 压缩技术，提供卓越的性能、安全性和可靠性。专为 Python 3.12+ 打造，这个企业级解决方案结合原子操作、流式处理效率和精心设计的 API，重新定义了开发者在生产环境中处理 `.tzst`/`.tar.zst` 归档文件的方式。🚀 +**tzst** 是一个面向 Python 3.12+ 的归档库和命令行工具，用于创建、提取、列出和校验 `.tzst` 与 `.tar.zst` 归档。它将 tar 兼容性、Zstandard 压缩、流式处理、原子写入和默认安全提取整合为一套适合生产环境的简洁接口。 -技术深度解析文章已发布：**[《深入解析 tzst：一个基于 Zstandard 的现代 Python 归档库》](https://blog.xi-xu.me/2025/11/01/deep-dive-into-tzst.html)**。 +> [!NOTE] +> 技术深度解析：**[《深入解析 tzst：一个基于 Zstandard 的现代 Python 归档库》](https://blog.xi-xu.me/2025/11/01/deep-dive-into-tzst.html)**。 -## ✨ 功能特性 +## 功能特性 -- **🗜️ 高效压缩**：采用 Zstandard 压缩算法，实现优异的压缩率和速度 -- **📁 Tar 兼容性**：创建符合标准的 tar 归档并使用 Zstandard 压缩 -- **💻 命令行界面**：直观的 CLI，支持流式处理和全面选项 -- **🐍 Python API**：简洁、符合 Python 风格的编程接口 -- **🌍 跨平台支持**：兼容 Windows、macOS 和 Linux -- **📂 多扩展名支持**：同时支持 `.tzst` 和 `.tar.zst` 扩展名 -- **💾 内存高效**：流模式可高效处理大型归档文件 -- **⚡ 原子操作**：安全的文件操作，中断时自动清理 -- **🔒 默认安全**：提取时使用 'data' 过滤器确保最高安全性 -- **🚨 增强的错误处理**：清晰的错误信息和实用建议 +- **高效压缩**：采用 Zstandard 压缩算法，实现优异的压缩率和速度 +- **Tar 兼容性**：创建符合标准的 tar 归档并使用 Zstandard 压缩 +- **命令行界面**：直观的 CLI，支持流式处理和全面选项 +- **Python API**：简洁、符合 Python 风格的编程接口 +- **跨平台支持**：兼容 Windows、macOS 和 Linux +- **多扩展名支持**：同时支持 `.tzst` 和 `.tar.zst` 扩展名 +- **内存高效**：流模式可高效处理大型归档文件 +- **原子操作**：安全的文件操作，中断时自动清理 +- **默认安全**：提取时使用 'data' 过滤器确保最高安全性 +- **增强的错误处理**：清晰的错误信息和实用建议 -## 📥 安装指南 +## 安装指南 ### 从 GitHub Releases 安装 @@ -43,30 +44,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` 可执行文件（Windows 为 `tzst.exe`） -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` 可执行文件（Windows 为 `tzst.exe`） +3. **移动**：将可执行文件添加到 PATH 环境变量： + - **Linux/macOS**：`sudo mv tzst /usr/local/bin/` + - **Windows**：将包含 `tzst.exe` 的目录添加到 PATH +4. **验证**：运行 `tzst --help` 确认安装成功 -#### 🎯 二进制安装优势 +#### 二进制安装优势 -- ✅ **无需 Python** - 独立可执行文件 -- ✅ **启动更快** - 无 Python 解释器开销 -- ✅ **易于部署** - 单文件分发 -- ✅ **行为一致** - 依赖项已打包 +- **无需 Python** - 独立可执行文件 +- **启动更快** - 无 Python 解释器开销 +- **易于部署** - 单文件分发 +- **行为一致** - 依赖项已打包 -### 📦 通过 PyPI 安装 +### 通过 PyPI 安装 使用 pip： @@ -80,7 +81,7 @@ pip install tzst uv tool install tzst ``` -### 🔧 从源码安装 +### 从源码安装 ```bash git clone https://github.com/xixu-me/tzst.git @@ -88,7 +89,7 @@ cd tzst pip install . ``` -### 🚀 开发环境安装 +### 开发环境安装 ```bash git clone https://github.com/xixu-me/tzst.git @@ -96,25 +97,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 @@ -131,11 +132,11 @@ for item in contents: print(f"{item['name']}: {item['size']} bytes") ``` -## 💻 命令行接口 +## 命令行接口 -### 📁 归档操作 +### 归档操作 -#### ➕ 创建归档 +#### 创建归档 ```bash # 基本用法 @@ -149,7 +150,7 @@ tzst add archive.tzst files/ tzst create archive.tzst files/ ``` -#### 📤 提取归档 +#### 提取归档 ```bash # 完整目录结构提取 @@ -168,7 +169,7 @@ tzst e archive.tzst -o output_dir/ tzst x archive.tzst --streaming -o output_dir/ ``` -#### 📋 列出内容 +#### 列出内容 ```bash # 简单列表 @@ -181,7 +182,7 @@ tzst l archive.tzst -v tzst l archive.tzst --streaming -v ``` -#### 🧪 测试完整性 +#### 测试完整性 ```bash # 测试归档完整性 @@ -191,7 +192,7 @@ tzst t archive.tzst tzst t archive.tzst --streaming ``` -### 📊 命令参考 +### 命令参考 | 命令 | 等效命令 | 描述 | 是否支持流模式 | |------|----------|------|----------------| @@ -201,7 +202,7 @@ tzst t archive.tzst --streaming | `l` | `list` | 列出归档内容 | ✓ `--streaming` | | `t` | `test` | 测试归档完整性 | ✓ `--streaming` | -### ⚙️ CLI 选项 +### CLI 选项 - `-v, --verbose`：启用详细输出 - `-o, --output DIR`：指定输出目录（提取命令） @@ -210,7 +211,7 @@ tzst t archive.tzst --streaming - `--filter FILTER`：提取安全过滤器（data/tar/fully_trusted） - `--no-atomic`：禁用原子文件操作（不推荐） -### 🔒 安全过滤器 +### 安全过滤器 ```bash # 最高安全性提取（默认） @@ -223,15 +224,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 @@ -257,13 +258,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 @@ -276,7 +277,7 @@ create_archive( ) ``` -#### 📤 extract_archive() +#### extract_archive() ```python from tzst import extract_archive @@ -294,7 +295,7 @@ extract_archive("backup.tzst", "restore_dir/", flatten=True) extract_archive("large_backup.tzst", "restore_dir/", streaming=True) ``` -#### 📋 list_archive() +#### list_archive() ```python from tzst import list_archive @@ -309,7 +310,7 @@ file_details = list_archive("backup.tzst", verbose=True) large_list = list_archive("large_backup.tzst", streaming=True) ``` -#### 🧪 test_archive() +#### test_archive() ```python from tzst import test_archive @@ -323,9 +324,9 @@ if test_archive("large_backup.tzst", streaming=True): print("Large archive is valid") ``` -## 🔧 高级功能 +## 高级功能 -### 📂 文件扩展名 +### 文件扩展名 库自动处理文件扩展名并智能标准化： @@ -342,7 +343,7 @@ create_archive("backup", files) # 创建 backup.tzst create_archive("backup.txt", files) # 创建 backup.tzst (标准化) ``` -### 🗜️ 压缩级别 +### 压缩级别 Zstandard 压缩级别范围从 1（最快）到 22（最佳压缩）： @@ -351,17 +352,17 @@ Zstandard 压缩级别范围从 1（最快）到 22（最佳压缩）： - **级别 10-15**：更好的压缩率，速度较慢 - **级别 20-22**：最高压缩率，速度显著变慢 -### 🌊 流模式 +### 流模式 使用流模式实现大归档文件的内存高效处理： -**✅ 优势：** +**优势：** - 显著降低内存使用 - 对内存无法容纳的大文件性能更好 - 资源自动清理 -**🎯 适用场景：** +**适用场景：** - 大于 100MB 的归档文件 - 内存有限的环境 @@ -379,7 +380,7 @@ contents = list_archive(large_archive, streaming=True, verbose=True) extract_archive(large_archive, "restore_dir/", streaming=True) ``` -### ⚡ 原子操作 +### 原子操作 所有文件创建操作默认使用原子操作： @@ -396,7 +397,7 @@ create_archive("important.tzst", files) # 中断时安全 create_archive("test.tzst", files, use_temp_file=False) ``` -### 🚨 错误处理 +### 错误处理 ```python from tzst import TzstArchive @@ -420,43 +421,43 @@ except KeyboardInterrupt: # Cleanup handled automatically ``` -## 🚀 性能与对比 +## 性能与对比 -### 💡 性能优化建议 +### 性能优化建议 -1. **🗜️ 压缩级别**：级别 3 适用于大多数场景 -2. **🌊 流模式**：归档大于 100MB 时使用 -3. **📦 批量操作**：单次会话添加多个文件 -4. **📄 文件类型**：已压缩文件不会进一步压缩 +1. **压缩级别**：级别 3 适用于大多数场景 +2. **流模式**：归档大于 100MB 时使用 +3. **批量操作**：单次会话添加多个文件 +4. **文件类型**：已压缩文件不会进一步压缩 -### 🆚 与其他工具对比 +### 与其他工具对比 **对比 tar + gzip：** -- ✅ 更好的压缩率 -- ⚡ 更快的解压速度 -- 🔄 现代算法 +- 更好的压缩率 +- 更快的解压速度 +- 现代算法 **对比 tar + xz：** -- 🚀 显著更快的压缩速度 -- 📊 相似的压缩率 -- ⚖️ 更好的速度/压缩率平衡 +- 显著更快的压缩速度 +- 相似的压缩率 +- 更好的速度/压缩率平衡 **对比 zip：** -- 🗜️ 更好的压缩率 -- 🔐 保留 Unix 权限和元数据 -- 🌊 更好的流处理支持 +- 更好的压缩率 +- 保留 Unix 权限和元数据 +- 更好的流处理支持 -## 📋 系统要求 +## 系统要求 -- 🐍 Python 3.12 或更高版本（已测试 3.12-3.14） -- 📦 zstandard >= 0.19.0 +- Python 3.12 或更高版本（已测试 3.12-3.14） +- zstandard >= 0.19.0 -## 🛠️ 开发指南 +## 开发指南 -### 🚀 设置开发环境 +### 设置开发环境 ```bash git clone https://github.com/xixu-me/tzst.git @@ -464,7 +465,7 @@ cd tzst pip install -e .[dev] ``` -### 🧪 运行测试 +### 运行测试 ```bash # 带覆盖率的测试 @@ -474,7 +475,7 @@ pytest --cov=tzst --cov-report=html pytest ``` -### ✨ 代码质量 +### 代码质量 ```bash # 代码检查 @@ -484,7 +485,7 @@ ruff check src tests ruff format src tests ``` -## 🤝 贡献指南 +## 贡献指南 欢迎贡献！请阅读[贡献指南](CONTRIBUTING.md)了解： @@ -493,7 +494,7 @@ ruff format src tests - 测试要求和编写测试 - PR流程和审核规范 -### 🚀 贡献者快速入门 +### 贡献者快速入门 ```bash git clone https://github.com/xixu-me/tzst.git @@ -502,22 +503,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 社区的宝贵反馈和启发 -## 📄 许可证 +## 许可证 版权所有 © [Xi Xu](https://xi-xu.me)。保留所有权利。