diff --git a/README.ar.md b/README.ar.md new file mode 100644 index 0000000..b114d47 --- /dev/null +++ b/README.ar.md @@ -0,0 +1,517 @@ +[🇬🇧 English](./README.md) | [🇨🇳 汉语](./README.zh.md) | [🇪🇸 español](./README.es.md) | [🇯🇵 日本語](./README.ja.md) | **🇦🇪 العربية** | [🇷🇺 русский](./README.ru.md) | [🇩🇪 Deutsch](./README.de.md) | [🇫🇷 français](./README.fr.md) | [🇰🇷 한국어](./README.ko.md) | [🇧🇷 português](./README.pt.md) + +
+ +# tzst + +[![codecov](https://codecov.io/gh/xixu-me/tzst/graph/badge.svg?token=2AIN1559WU)](https://codecov.io/gh/xixu-me/tzst) +[![CodeQL](https://github.com/xixu-me/tzst/actions/workflows/github-code-scanning/codeql/badge.svg)](https://github.com/xixu-me/tzst/actions/workflows/github-code-scanning/codeql) +[![CI/CD](https://github.com/xixu-me/tzst/actions/workflows/ci.yml/badge.svg)](https://github.com/xixu-me/tzst/actions/workflows/ci.yml) +[![PyPI - Version](https://img.shields.io/pypi/v/tzst)](https://pypi.org/project/tzst/) +[![GitHub License](https://img.shields.io/github/license/xixu-me/tzst)](LICENSE) +[![Sponsor](https://img.shields.io/badge/Sponsor-violet)](https://xi-xu.me/#sponsorships) + +**tzst** هي مكتبة Python من الجيل التالي مُطورة لإدارة الأرشيف الحديث، تستفيد من ضغط Zstandard المتطور لتقديم أداء وأمان وموثوقية فائقة. مبنية حصرياً لـ Python 3.12+، هذا الحل على مستوى المؤسسة يدمج العمليات الذرية وكفاءة التدفق ووواجهة برمجة التطبيقات المصممة بعناية فائقة لإعادة تعريف كيفية تعامل المطورين مع أرشيف `.tzst`/`.tar.zst` في بيئات الإنتاج. 🚀 + +## ✨ الميزات + +- **🗜️ ضغط عالي**: ضغط Zstandard لنسب ضغط وسرعة ممتازة +- **📁 توافق Tar**: ينشئ أرشيف tar قياسي مضغوط بـ Zstandard +- **💻 واجهة سطر الأوامر**: واجهة CLI بديهية مع دعم التدفق وخيارات شاملة +- **🐍 Python API**: واجهة برمجة تطبيقات نظيفة وpythonic للاستخدام البرمجي +- **🌍 متعدد المنصات**: يعمل على Windows وmacOS وLinux +- **📂 امتدادات متعددة**: يدعم كلاً من امتدادات `.tzst` و `.tar.zst` +- **💾 فعال في الذاكرة**: وضع التدفق للتعامل مع الأرشيف الكبير باستخدام أقل للذاكرة +- **⚡ عمليات ذرية**: عمليات ملف آمنة مع تنظيف تلقائي عند المقاطعة +- **🔒 آمن افتراضياً**: يستخدم مرشح 'data' للحد الأقصى من الأمان أثناء الاستخراج +- **🚨 معالجة أخطاء محسنة**: رسائل خطأ واضحة مع بدائل مفيدة + +## 📥 التثبيت + +### من إصدارات GitHub + +تحميل ملفات تنفيذية مستقلة لا تتطلب تثبيت Python: + +#### المنصات المدعومة + +| المنصة | المعمارية | الملف | +|----------|-------------|------| +| **🐧 Linux** | x86_64 | `tzst-v{هذه نسخة كبيرة}-linux-x86_64.zip` | +| **🐧 Linux** | ARM64 | `tzst-v{هذه نسخة كبيرة}-linux-aarch64.zip` | +| **🪟 Windows** | x64 | `tzst-v{هذه نسخة كبيرة}-windows-amd64.zip` | +| **🪟 Windows** | ARM64 | `tzst-v{هذه نسخة كبيرة}-windows-arm64.zip` | +| **🍎 macOS** | Intel | `tzst-v{هذه نسخة كبيرة}-macos-x86_64.zip` | +| **🍎 macOS** | Apple Silicon | `tzst-v{هذه نسخة كبيرة}-macos-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` + +#### 🎯 فوائد التثبيت الثنائي + +- ✅ **لا يتطلب Python** - ملف تنفيذي مستقل +- ✅ **بدء تشغيل أسرع** - بدون إضافة مفسر Python +- ✅ **نشر سهل** - توزيع ملف واحد +- ✅ **سلوك متسق** - تبعيات مجمعة + +### 📦 من PyPI + +```bash +pip install tzst +``` + +### 🔧 من المصدر + +```bash +git clone https://github.com/xixu-me/tzst.git +cd tzst +pip install . +``` + +### 🚀 تثبيت التطوير + +يستخدم هذا المشروع معايير تعبئة Python الحديثة: + +```bash +git clone https://github.com/xixu-me/tzst.git +cd tzst +pip install -e .[dev] +``` + +## 🚀 البداية السريعة + +### 💻 استخدام سطر الأوامر + +> **ملاحظة**: تحميل [الملف الثنائي المستقل](#من-إصدارات-github) للحصول على أفضل أداء وعدم الاعتماد على Python. بدلاً من ذلك، استخدم `uvx tzst` للتشغيل دون تثبيت. راجع [وثائق uv](https://docs.astral.sh/uv/) للتفاصيل. + +```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 +from tzst import create_archive, extract_archive, list_archive + +# إنشاء أرشيف +create_archive("archive.tzst", ["file1.txt", "file2.txt", "directory/"]) + +# استخراج أرشيف +extract_archive("archive.tzst", "output_directory/") + +# قائمة محتويات الأرشيف +contents = list_archive("archive.tzst", verbose=True) +for item in contents: + print(f"{item['name']}: {item['size']} bytes") +``` + +## 💻 واجهة سطر الأوامر + +### 📁 عمليات الأرشيف + +#### ➕ إنشاء أرشيف + +```bash +# الاستخدام الأساسي +tzst a archive.tzst file1.txt file2.txt + +# مع مستوى الضغط (1-22، افتراضي: 3) +tzst a archive.tzst files/ -l 15 + +# أوامر بديلة +tzst add archive.tzst files/ +tzst create archive.tzst files/ +``` + +#### 📤 استخراج أرشيف + +```bash +# استخراج مع هيكل المجلد الكامل +tzst x archive.tzst + +# استخراج إلى مجلد محدد +tzst x archive.tzst -o output/ + +# استخراج ملفات محددة +tzst x archive.tzst file1.txt dir/file2.txt + +# استخراج بدون هيكل المجلد (مسطح) +tzst e archive.tzst -o output/ + +# استخدام وضع التدفق للأرشيف الكبير +tzst x archive.tzst --streaming -o output/ +``` + +#### 📋 قائمة المحتويات + +```bash +# قائمة بسيطة +tzst l archive.tzst + +# قائمة مفصلة مع التفاصيل +tzst l archive.tzst -v + +# استخدام وضع التدفق للأرشيف الكبير +tzst l archive.tzst --streaming -v +``` + +#### 🧪 اختبار السلامة + +```bash +# اختبار سلامة الأرشيف +tzst t archive.tzst + +# اختبار مع وضع التدفق +tzst t archive.tzst --streaming +``` + +### 📊 مرجع الأوامر + +| الأمر | البدائل | الوصف | دعم التدفق | +|---------|---------|-------------|-------------------| +| `a` | `add`, `create` | إنشاء أو إضافة إلى أرشيف | N/A | +| `x` | `extract` | استخراج مع المسارات الكاملة | ✓ `--streaming` | +| `e` | `extract-flat` | استخراج بدون هيكل المجلد | ✓ `--streaming` | +| `l` | `list` | قائمة محتويات الأرشيف | ✓ `--streaming` | +| `t` | `test` | اختبار سلامة الأرشيف | ✓ `--streaming` | + +### ⚙️ خيارات CLI + +- `-v, --verbose`: تمكين الإخراج المفصل +- `-o, --output DIR`: تحديد مجلد الإخراج (أوامر الاستخراج) +- `-l, --level LEVEL`: تحديد مستوى الضغط 1-22 (أمر الإنشاء) +- `--streaming`: تمكين وضع التدفق للمعالجة الفعالة في الذاكرة +- `--filter FILTER`: مرشح الأمان للاستخراج (data/tar/fully_trusted) +- `--no-atomic`: تعطيل العمليات الذرية للملفات (غير مستحسن) + +### 🔒 مرشحات الأمان + +```bash +# استخراج مع أقصى أمان (افتراضي) +tzst x archive.tzst --filter data + +# استخراج مع توافق tar قياسي +tzst x archive.tzst --filter tar + +# استخراج مع ثقة كاملة (خطر - فقط للأرشيف الموثوق) +tzst x archive.tzst --filter fully_trusted +``` + +**🔐 خيارات مرشح الأمان:** + +- `data` (افتراضي): الأكثر أماناً. يحجب الملفات الخطيرة والمسارات المطلقة والمسارات خارج مجلد الاستخراج +- `tar`: توافق tar قياسي. يحجب المسارات المطلقة واجتياز المجلد +- `fully_trusted`: لا قيود أمان. استخدم فقط مع الأرشيف الموثوق تماماً + +## 🐍 Python API + +### 📦 فئة TzstArchive + +```python +from tzst import TzstArchive + +# إنشاء أرشيف جديد +with TzstArchive("archive.tzst", "w", compression_level=5) as archive: + archive.add("file.txt") + archive.add("directory/", recursive=True) + +# قراءة أرشيف موجود +with TzstArchive("archive.tzst", "r") as archive: + # قائمة المحتويات + contents = archive.list(verbose=True) + + # استخراج مع مرشح الأمان + archive.extract("file.txt", "output/", filter="data") + + # اختبار السلامة + is_valid = archive.test() + +# للأرشيف الكبير، استخدم وضع التدفق +with TzstArchive("large_archive.tzst", "r", streaming=True) as archive: + archive.extract(path="output/") +``` + +**⚠️ قيود مهمة:** + +- **❌ وضع الإلحاق غير مدعوم**: أنشئ أرشيف متعدد أو أعد إنشاء الأرشيف بالكامل بدلاً من ذلك + +### 🎯 دوال الراحة + +#### 📁 create_archive() + +```python +from tzst import create_archive + +# إنشاء مع عمليات ذرية (افتراضي) +create_archive( + archive_path="backup.tzst", + files=["documents/", "photos/", "config.txt"], + compression_level=10 +) +``` + +#### 📤 extract_archive() + +```python +from tzst import extract_archive + +# استخراج مع الأمان (افتراضي: مرشح 'data') +extract_archive("backup.tzst", "restore/") + +# استخراج ملفات محددة +extract_archive("backup.tzst", "restore/", members=["config.txt"]) + +# تسطيح هيكل المجلد +extract_archive("backup.tzst", "restore/", flatten=True) + +# استخدام التدفق للأرشيف الكبير +extract_archive("large_backup.tzst", "restore/", streaming=True) +``` + +#### 📋 list_archive() + +```python +from tzst import list_archive + +# قائمة بسيطة +files = list_archive("backup.tzst") + +# قائمة مفصلة +files = list_archive("backup.tzst", verbose=True) + +# تدفق للأرشيف الكبير +files = list_archive("large_backup.tzst", streaming=True) +``` + +#### 🧪 test_archive() + +```python +from tzst import test_archive + +# اختبار سلامة أساسي +if test_archive("backup.tzst"): + print("الأرشيف صالح") + +# اختبار مع التدفق +if test_archive("large_backup.tzst", streaming=True): + print("الأرشيف الكبير صالح") +``` + +## 🔧 الميزات المتقدمة + +### 📂 امتدادات الملفات + +تتعامل المكتبة تلقائياً مع امتدادات الملفات مع التطبيع الذكي: + +- `.tzst` - الامتداد الأساسي لأرشيف tar+zstandard +- `.tar.zst` - امتداد قياسي بديل +- الكشف التلقائي عند فتح الأرشيف الموجود +- إضافة الامتداد التلقائي عند إنشاء الأرشيف + +```python +# هذه كلها تنشئ أرشيف صالح +create_archive("backup.tzst", files) # ينشئ backup.tzst +create_archive("backup.tar.zst", files) # ينشئ backup.tar.zst +create_archive("backup", files) # ينشئ backup.tzst +create_archive("backup.txt", files) # ينشئ backup.tzst (مُطبع) +``` + +### 🗜️ مستويات الضغط + +تتراوح مستويات ضغط Zstandard من 1 (الأسرع) إلى 22 (أفضل ضغط): + +- **المستوى 1-3**: ضغط سريع، ملفات أكبر +- **المستوى 3** (افتراضي): توازن جيد بين السرعة والضغط +- **المستوى 10-15**: ضغط أفضل، أبطأ +- **المستوى 20-22**: أقصى ضغط، أبطأ بكثير + +### 🌊 وضع التدفق + +استخدم وضع التدفق للمعالجة الفعالة في الذاكرة للأرشيف الكبير: + +**✅ الفوائد:** + +- انخفاض كبير في استخدام الذاكرة +- أداء أفضل للأرشيف الذي لا يناسب الذاكرة +- تنظيف تلقائي للموارد + +**🎯 متى تستخدم:** + +- أرشيف أكبر من 100 ميجابايت +- بيئات ذاكرة محدودة +- معالجة أرشيف بملفات كبيرة كثيرة + +```python +# مثال: معالجة أرشيف نسخ احتياطي كبير +from tzst import extract_archive, list_archive, test_archive + +large_archive = "backup_500gb.tzst" + +# عمليات فعالة في الذاكرة +is_valid = test_archive(large_archive, streaming=True) +contents = list_archive(large_archive, streaming=True, verbose=True) +extract_archive(large_archive, "restore/", streaming=True) +``` + +### ⚡ العمليات الذرية + +جميع عمليات إنشاء الملفات تستخدم عمليات ملف ذرية افتراضياً: + +- الأرشيف منشأ في ملفات مؤقتة أولاً، ثم نُقل ذرياً +- تنظيف تلقائي إذا تمت مقاطعة العملية +- لا خطر من أرشيف تالف أو غير مكتمل +- توافق متعدد المنصات + +```python +# العمليات الذرية ممكنة افتراضياً +create_archive("important.tzst", files) # آمن من المقاطعة + +# يمكن تعطيلها إذا لزم الأمر (غير مستحسن) +create_archive("test.tzst", files, use_temp_file=False) +``` + +### 🚨 معالجة الأخطاء + +```python +from tzst import TzstArchive +from tzst.exceptions import ( + TzstError, + TzstArchiveError, + TzstCompressionError, + TzstDecompressionError, + TzstFileNotFoundError +) + +try: + with TzstArchive("archive.tzst", "r") as archive: + archive.extract() +except TzstDecompressionError: + print("فشل في إلغاء ضغط الأرشيف") +except TzstFileNotFoundError: + print("ملف الأرشيف غير موجود") +except KeyboardInterrupt: + print("العملية مقاطعة من قبل المستخدم") + # التنظيف يتم تلقائياً +``` + +## 🚀 الأداء والمقارنة + +### 💡 نصائح الأداء + +1. **🗜️ مستويات الضغط**: المستوى 3 هو الأمثل لمعظم حالات الاستخدام +2. **🌊 التدفق**: استخدم للأرشيف أكبر من 100 ميجابايت +3. **📦 عمليات الدفعات**: أضف ملفات متعددة في جلسة واحدة +4. **📄 أنواع الملفات**: الملفات المضغوطة مسبقاً لن تنضغط كثيراً أكثر + +### 🆚 مقابل أدوات أخرى + +**مقابل tar + gzip:** + +- ✅ نسب ضغط أفضل +- ⚡ إلغاء ضغط أسرع +- 🔄 خوارزمية حديثة + +**مقابل tar + xz:** + +- 🚀 ضغط أسرع بشكل كبير +- 📊 نسب ضغط مماثلة +- ⚖️ توازن سرعة/ضغط أفضل + +**مقابل zip:** + +- 🗜️ ضغط أفضل +- 🔐 يحافظ على أذونات Unix والبيانات الوصفية +- 🌊 دعم تدفق أفضل + +## 📋 المتطلبات + +- 🐍 Python 3.12 أو أعلى +- 📦 zstandard >= 0.19.0 + +## 🛠️ التطوير + +### 🚀 إعداد بيئة التطوير + +يستخدم هذا المشروع معايير تعبئة Python الحديثة: + +```bash +git clone https://github.com/xixu-me/tzst.git +cd tzst +pip install -e .[dev] +``` + +### 🧪 تشغيل الاختبارات + +```bash +# تشغيل الاختبارات مع التغطية +pytest --cov=tzst --cov-report=html + +# أو استخدم الأمر الأبسط (إعدادات التغطية في pyproject.toml) +pytest +``` + +### ✨ جودة الكود + +```bash +# فحص جودة الكود +ruff check src tests + +# تنسيق الكود +ruff format src tests +``` + +## 🤝 المساهمة + +نرحب بالمساهمات! يرجى قراءة [دليل المساهمة](CONTRIBUTING.md) لـ: + +- إعداد التطوير وهيكل المشروع +- إرشادات أسلوب الكود وأفضل الممارسات +- متطلبات الاختبار وكتابة الاختبارات +- عملية طلب السحب وسير عمل المراجعة + +### 🚀 البداية السريعة للمساهمين + +```bash +git clone https://github.com/xixu-me/tzst.git +cd tzst +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 للإلهام والملاحظات + +## 📄 الترخيص + +حقوق النشر © 2025 [شي شو](https://xi-xu.me). جميع الحقوق محفوظة. + +مرخص تحت ترخيص [BSD 3-Clause](LICENSE). + +
diff --git a/README.de.md b/README.de.md new file mode 100644 index 0000000..7b567bf --- /dev/null +++ b/README.de.md @@ -0,0 +1,513 @@ +[🇬🇧 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 + +[![codecov](https://codecov.io/gh/xixu-me/tzst/graph/badge.svg?token=2AIN1559WU)](https://codecov.io/gh/xixu-me/tzst) +[![CodeQL](https://github.com/xixu-me/tzst/actions/workflows/github-code-scanning/codeql/badge.svg)](https://github.com/xixu-me/tzst/actions/workflows/github-code-scanning/codeql) +[![CI/CD](https://github.com/xixu-me/tzst/actions/workflows/ci.yml/badge.svg)](https://github.com/xixu-me/tzst/actions/workflows/ci.yml) +[![PyPI - Version](https://img.shields.io/pypi/v/tzst)](https://pypi.org/project/tzst/) +[![GitHub License](https://img.shields.io/github/license/xixu-me/tzst)](LICENSE) +[![Sponsor](https://img.shields.io/badge/Sponsor-violet)](https://xi-xu.me/#sponsorships) + +**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. 🚀 + +## ✨ 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 + +## 📥 Installation + +### Von GitHub Releases + +Lade eigenständige ausführbare Dateien herunter, die keine Python-Installation erfordern: + +#### Unterstützte Plattformen + +| Plattform | Architektur | Datei | +|----------|-------------|------| +| **🐧 Linux** | x86_64 | `tzst-v{Version}-linux-x86_64.zip` | +| **🐧 Linux** | ARM64 | `tzst-v{Version}-linux-aarch64.zip` | +| **🪟 Windows** | x64 | `tzst-v{Version}-windows-amd64.zip` | +| **🪟 Windows** | ARM64 | `tzst-v{Version}-windows-arm64.zip` | +| **🍎 macOS** | Intel | `tzst-v{Version}-macos-x86_64.zip` | +| **🍎 macOS** | Apple Silicon | `tzst-v{Version}-macos-arm64.zip` | + +#### 🛠️ 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` + +#### 🎯 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 + +### 📦 Von PyPI + +```bash +pip install tzst +``` + +### 🔧 Aus dem Quellcode + +```bash +git clone https://github.com/xixu-me/tzst.git +cd tzst +pip install . +``` + +### 🚀 Entwicklungsinstallation + +Dieses Projekt verwendet moderne Python-Packaging-Standards: + +```bash +git clone https://github.com/xixu-me/tzst.git +cd tzst +pip install -e .[dev] +``` + +## 🚀 Schnellstart + +### 💻 Kommandozeilennutzung + +> **Hinweis**: Lade die [eigenständige Binärdatei](#von-github-releases) für beste Leistung und keine Python-Abhängigkeit herunter. Alternativ verwende `uvx tzst` für die Ausführung ohne Installation. Siehe [uv-Dokumentation](https://docs.astral.sh/uv/) für Details. + +```bash +# 📁 Archiv erstellen +tzst a archive.tzst file1.txt file2.txt directory/ + +# 📤 Archiv extrahieren +tzst x archive.tzst + +# 📋 Archivinhalt auflisten +tzst l archive.tzst + +# 🧪 Archivintegrität testen +tzst t archive.tzst +``` + +### 🐍 Python API Nutzung + +```python +from tzst import create_archive, extract_archive, list_archive + +# Archiv erstellen +create_archive("archive.tzst", ["file1.txt", "file2.txt", "directory/"]) + +# Archiv extrahieren +extract_archive("archive.tzst", "output_directory/") + +# Archivinhalt auflisten +contents = list_archive("archive.tzst", verbose=True) +for item in contents: + print(f"{item['name']}: {item['size']} bytes") +``` + +## 💻 Kommandozeilenschnittstelle + +### 📁 Archivoperationen + +#### ➕ Archiv erstellen + +```bash +# Grundlegende Nutzung +tzst a archive.tzst file1.txt file2.txt + +# Mit Komprimierungsstufe (1-22, Standard: 3) +tzst a archive.tzst files/ -l 15 + +# Alternative Befehle +tzst add archive.tzst files/ +tzst create archive.tzst files/ +``` + +#### 📤 Archiv extrahieren + +```bash +# Mit vollständiger Verzeichnisstruktur extrahieren +tzst x archive.tzst + +# In spezifisches Verzeichnis extrahieren +tzst x archive.tzst -o output/ + +# Spezifische Dateien extrahieren +tzst x archive.tzst file1.txt dir/file2.txt + +# Ohne Verzeichnisstruktur extrahieren (flach) +tzst e archive.tzst -o output/ + +# Streaming-Modus für große Archive verwenden +tzst x archive.tzst --streaming -o output/ +``` + +#### 📋 Inhalt auflisten + +```bash +# Einfache Auflistung +tzst l archive.tzst + +# Ausführliche Auflistung mit Details +tzst l archive.tzst -v + +# Streaming-Modus für große Archive verwenden +tzst l archive.tzst --streaming -v +``` + +#### 🧪 Integrität testen + +```bash +# Archivintegrität testen +tzst t archive.tzst + +# Mit Streaming-Modus testen +tzst t archive.tzst --streaming +``` + +### 📊 Befehlsreferenz + +| Befehl | Aliase | Beschreibung | Streaming-Unterstützung | +|---------|---------|-------------|-------------------| +| `a` | `add`, `create` | Archiv erstellen oder hinzufügen | N/A | +| `x` | `extract` | Mit vollständigen Pfaden extrahieren | ✓ `--streaming` | +| `e` | `extract-flat` | Ohne Verzeichnisstruktur extrahieren | ✓ `--streaming` | +| `l` | `list` | Archivinhalt auflisten | ✓ `--streaming` | +| `t` | `test` | Archivintegrität testen | ✓ `--streaming` | + +### ⚙️ CLI-Optionen + +- `-v, --verbose`: Ausführliche Ausgabe aktivieren +- `-o, --output DIR`: Ausgabeverzeichnis spezifizieren (Extraktionsbefehle) +- `-l, --level LEVEL`: Komprimierungsstufe 1-22 setzen (Erstellungsbefehl) +- `--streaming`: Streaming-Modus für speichereffiziente Verarbeitung aktivieren +- `--filter FILTER`: Sicherheitsfilter für Extraktion (data/tar/fully_trusted) +- `--no-atomic`: Atomare Dateioperationen deaktivieren (nicht empfohlen) + +### 🔒 Sicherheitsfilter + +```bash +# Mit maximaler Sicherheit extrahieren (Standard) +tzst x archive.tzst --filter data + +# Mit Standard-Tar-Kompatibilität extrahieren +tzst x archive.tzst --filter tar + +# Mit vollem Vertrauen extrahieren (gefährlich - nur für vertrauenswürdige Archive) +tzst x archive.tzst --filter fully_trusted +``` + +**🔐 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 + +### 📦 TzstArchive Klasse + +```python +from tzst import TzstArchive + +# Neues Archiv erstellen +with TzstArchive("archive.tzst", "w", compression_level=5) as archive: + archive.add("file.txt") + archive.add("directory/", recursive=True) + +# Vorhandenes Archiv lesen +with TzstArchive("archive.tzst", "r") as archive: + # Inhalt auflisten + contents = archive.list(verbose=True) + + # Mit Sicherheitsfilter extrahieren + archive.extract("file.txt", "output/", filter="data") + + # Integrität testen + is_valid = archive.test() + +# Für große Archive, Streaming-Modus verwenden +with TzstArchive("large_archive.tzst", "r", streaming=True) as archive: + archive.extract(path="output/") +``` + +**⚠️ Wichtige Einschränkungen:** + +- **❌ Anhängemodus nicht unterstützt**: Erstelle mehrere Archive oder erstelle das gesamte Archiv neu + +### 🎯 Convenience-Funktionen + +#### 📁 create_archive() + +```python +from tzst import create_archive + +# Mit atomaren Operationen erstellen (Standard) +create_archive( + archive_path="backup.tzst", + files=["documents/", "photos/", "config.txt"], + compression_level=10 +) +``` + +#### 📤 extract_archive() + +```python +from tzst import extract_archive + +# Mit Sicherheit extrahieren (Standard: 'data' Filter) +extract_archive("backup.tzst", "restore/") + +# Spezifische Dateien extrahieren +extract_archive("backup.tzst", "restore/", members=["config.txt"]) + +# Verzeichnisstruktur abflachen +extract_archive("backup.tzst", "restore/", flatten=True) + +# Streaming für große Archive verwenden +extract_archive("large_backup.tzst", "restore/", streaming=True) +``` + +#### 📋 list_archive() + +```python +from tzst import list_archive + +# Einfache Auflistung +files = list_archive("backup.tzst") + +# Detaillierte Auflistung +files = list_archive("backup.tzst", verbose=True) + +# Streaming für große Archive +files = list_archive("large_backup.tzst", streaming=True) +``` + +#### 🧪 test_archive() + +```python +from tzst import test_archive + +# Grundlegende Integritätsprüfung +if test_archive("backup.tzst"): + print("Archiv ist gültig") + +# Mit Streaming testen +if test_archive("large_backup.tzst", streaming=True): + print("Großes Archiv ist gültig") +``` + +## 🔧 Erweiterte Funktionen + +### 📂 Dateierweiterungen + +Die Bibliothek behandelt Dateierweiterungen automatisch mit intelligenter Normalisierung: + +- `.tzst` - Primäre Erweiterung für tar+zstandard Archive +- `.tar.zst` - Alternative Standarderweiterung +- Automatische Erkennung beim Öffnen vorhandener Archive +- Automatisches Hinzufügen von Erweiterungen beim Erstellen von Archiven + +```python +# Diese erstellen alle gültige Archive +create_archive("backup.tzst", files) # Erstellt backup.tzst +create_archive("backup.tar.zst", files) # Erstellt backup.tar.zst +create_archive("backup", files) # Erstellt backup.tzst +create_archive("backup.txt", files) # Erstellt backup.tzst (normalisiert) +``` + +### 🗜️ Komprimierungsstufen + +Zstandard-Komprimierungsstufen reichen von 1 (schnellste) bis 22 (beste Komprimierung): + +- **Stufe 1-3**: Schnelle Komprimierung, größere Dateien +- **Stufe 3** (Standard): Guter Kompromiss zwischen Geschwindigkeit und Komprimierung +- **Stufe 10-15**: Bessere Komprimierung, langsamer +- **Stufe 20-22**: Maximale Komprimierung, viel langsamer + +### 🌊 Streaming-Modus + +Verwende den Streaming-Modus für speichereffiziente Verarbeitung großer Archive: + +**✅ Vorteile:** + +- Deutlich reduzierter Speicherverbrauch +- Bessere Leistung für Archive, die nicht in den Speicher passen +- Automatische Bereinigung von Ressourcen + +**🎯 Wann verwenden:** + +- Archive größer als 100MB +- Umgebungen mit begrenztem Speicher +- Verarbeitung von Archiven mit vielen großen Dateien + +```python +# Beispiel: Verarbeitung eines großen Backup-Archivs +from tzst import extract_archive, list_archive, test_archive + +large_archive = "backup_500gb.tzst" + +# Speichereffiziente Operationen +is_valid = test_archive(large_archive, streaming=True) +contents = list_archive(large_archive, streaming=True, verbose=True) +extract_archive(large_archive, "restore/", streaming=True) +``` + +### ⚡ Atomare Operationen + +Alle Dateierstellungsoperationen verwenden standardmäßig atomare Dateioperationen: + +- Archive werden zuerst in temporären Dateien erstellt, dann atomisch verschoben +- Automatische Bereinigung bei Prozessunterbrechung +- Kein Risiko von beschädigten oder unvollständigen Archiven +- Plattformübergreifende Kompatibilität + +```python +# Atomare Operationen standardmäßig aktiviert +create_archive("important.tzst", files) # Sicher vor Unterbrechung + +# Kann bei Bedarf deaktiviert werden (nicht empfohlen) +create_archive("test.tzst", files, use_temp_file=False) +``` + +### 🚨 Fehlerbehandlung + +```python +from tzst import TzstArchive +from tzst.exceptions import ( + TzstError, + TzstArchiveError, + TzstCompressionError, + TzstDecompressionError, + TzstFileNotFoundError +) + +try: + with TzstArchive("archive.tzst", "r") as archive: + archive.extract() +except TzstDecompressionError: + print("Fehler beim Dekomprimieren des Archivs") +except TzstFileNotFoundError: + print("Archivdatei nicht gefunden") +except KeyboardInterrupt: + print("Operation vom Benutzer unterbrochen") + # Bereinigung wird automatisch durchgeführt +``` + +## 🚀 Leistung und Vergleich + +### 💡 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 + +### 🆚 vs Andere Tools + +**vs tar + gzip:** + +- ✅ Bessere Komprimierungsraten +- ⚡ Schnellere Dekomprimierung +- 🔄 Moderner Algorithmus + +**vs tar + xz:** + +- 🚀 Deutlich schnellere Komprimierung +- 📊 Ähnliche Komprimierungsraten +- ⚖️ Besserer Geschwindigkeit/Komprimierung-Kompromiss + +**vs zip:** + +- 🗜️ Bessere Komprimierung +- 🔐 Bewahrt Unix-Berechtigungen und Metadaten +- 🌊 Bessere Streaming-Unterstützung + +## 📋 Anforderungen + +- 🐍 Python 3.12 oder höher +- 📦 zstandard >= 0.19.0 + +## 🛠️ Entwicklung + +### 🚀 Entwicklungsumgebung einrichten + +Dieses Projekt verwendet moderne Python-Packaging-Standards: + +```bash +git clone https://github.com/xixu-me/tzst.git +cd tzst +pip install -e .[dev] +``` + +### 🧪 Tests ausführen + +```bash +# Tests mit Coverage ausführen +pytest --cov=tzst --cov-report=html + +# Oder den einfacheren Befehl verwenden (Coverage-Einstellungen sind in pyproject.toml) +pytest +``` + +### ✨ Code-Qualität + +```bash +# Code-Qualität prüfen +ruff check src tests + +# Code formatieren +ruff format src tests +``` + +## 🤝 Beitragen + +Wir begrüßen Beiträge! Bitte lies unseren [Beitragsleitfaden](CONTRIBUTING.md) für: + +- Entwicklungssetup und Projektstruktur +- Code-Stil-Richtlinien und bewährte Praktiken +- Testanforderungen und Schreibtests +- Pull-Request-Prozess und Review-Workflow + +### 🚀 Schnellstart für Mitwirkende + +```bash +git clone https://github.com/xixu-me/tzst.git +cd tzst +pip install -e .[dev] +python -m pytest tests/ +``` + +### 🎯 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 + +## 🙏 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 + +Urheberrecht © 2025 [Xi Xu](https://xi-xu.me). Alle Rechte vorbehalten. + +Lizenziert unter der [BSD 3-Clause](LICENSE) Lizenz. diff --git a/README.es.md b/README.es.md index 90dbe32..781e575 100644 --- a/README.es.md +++ b/README.es.md @@ -34,21 +34,21 @@ Descarga ejecutables independientes que no requieren instalación de Python: | Plataforma | Arquitectura | Archivo | |--------------|---------------|---------------------------------------| -| **🐧 Linux** | x86_64 | `tzst-v{version}-linux-x86_64.zip` | -| **🐧 Linux** | ARM64 | `tzst-v{version}-linux-aarch64.zip` | -| **🪟 Windows**| x64 | `tzst-v{version}-windows-amd64.zip` | -| **🪟 Windows**| ARM64 | `tzst-v{version}-windows-arm64.zip` | -| **🍎 macOS** | Intel | `tzst-v{version}-macos-x86_64.zip` | -| **🍎 macOS** | Apple Silicon | `tzst-v{version}-macos-arm64.zip` | +| **🐧 Linux** | x86_64 | `tzst-v{versión}-linux-x86_64.zip` | +| **🐧 Linux** | ARM64 | `tzst-v{versión}-linux-aarch64.zip` | +| **🪟 Windows**| x64 | `tzst-v{versión}-windows-amd64.zip` | +| **🪟 Windows**| ARM64 | `tzst-v{versión}-windows-arm64.zip` | +| **🍎 macOS** | Intel | `tzst-v{versión}-macos-x86_64.zip` | +| **🍎 macOS** | Apple Silicon | `tzst-v{versión}-macos-arm64.zip` | #### 🛠️ Pasos de Instalación -1. **📥 Descarga** el archivo apropiado para tu plataforma desde la [página de lanzamientos más recientes](https://github.com/xixu-me/tzst/releases/latest). -2. **📦 Extrae** el archivo para obtener el ejecutable `tzst` (o `tzst.exe` en Windows). -3. **📂 Mueve** el ejecutable a un directorio en tu PATH: - * **🐧 Linux/macOS**: `sudo mv tzst /usr/local/bin/` - * **🪟 Windows**: Añade el directorio que contiene `tzst.exe` a tu variable de entorno PATH. -4. **✅ Verifica** la instalación: `tzst --help` +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 @@ -411,10 +411,10 @@ except KeyboardInterrupt: ### 💡 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 diff --git a/README.fr.md b/README.fr.md new file mode 100644 index 0000000..9b6b21e --- /dev/null +++ b/README.fr.md @@ -0,0 +1,513 @@ +[🇬🇧 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 + +[![codecov](https://codecov.io/gh/xixu-me/tzst/graph/badge.svg?token=2AIN1559WU)](https://codecov.io/gh/xixu-me/tzst) +[![CodeQL](https://github.com/xixu-me/tzst/actions/workflows/github-code-scanning/codeql/badge.svg)](https://github.com/xixu-me/tzst/actions/workflows/github-code-scanning/codeql) +[![CI/CD](https://github.com/xixu-me/tzst/actions/workflows/ci.yml/badge.svg)](https://github.com/xixu-me/tzst/actions/workflows/ci.yml) +[![PyPI - Version](https://img.shields.io/pypi/v/tzst)](https://pypi.org/project/tzst/) +[![GitHub License](https://img.shields.io/github/license/xixu-me/tzst)](LICENSE) +[![Sponsor](https://img.shields.io/badge/Sponsor-violet)](https://xi-xu.me/#sponsorships) + +**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. 🚀 + +## ✨ 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 + +## 📥 Installation + +### Depuis les Releases GitHub + +Téléchargez des exécutables autonomes qui ne nécessitent pas d'installation Python : + +#### Plateformes supportées + +| Plateforme | Architecture | Fichier | +|----------|-------------|------| +| **🐧 Linux** | x86_64 | `tzst-v{version}-linux-x86_64.zip` | +| **🐧 Linux** | ARM64 | `tzst-v{version}-linux-aarch64.zip` | +| **🪟 Windows** | x64 | `tzst-v{version}-windows-amd64.zip` | +| **🪟 Windows** | ARM64 | `tzst-v{version}-windows-arm64.zip` | +| **🍎 macOS** | Intel | `tzst-v{version}-macos-x86_64.zip` | +| **🍎 macOS** | Apple Silicon | `tzst-v{version}-macos-arm64.zip` | + +#### 🛠️ É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` + +#### 🎯 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 + +### 📦 Depuis PyPI + +```bash +pip install tzst +``` + +### 🔧 Depuis le code source + +```bash +git clone https://github.com/xixu-me/tzst.git +cd tzst +pip install . +``` + +### 🚀 Installation de développement + +Ce projet utilise les standards modernes d'empaquetage Python : + +```bash +git clone https://github.com/xixu-me/tzst.git +cd tzst +pip install -e .[dev] +``` + +## 🚀 Démarrage rapide + +### 💻 Utilisation en ligne de commande + +> **Note** : Téléchargez le [binaire autonome](#depuis-les-releases-github) pour les meilleures performances et aucune dépendance Python. Alternativement, utilisez `uvx tzst` pour exécuter sans installation. Voir la [documentation uv](https://docs.astral.sh/uv/) pour les détails. + +```bash +# 📁 Créer une archive +tzst a archive.tzst file1.txt file2.txt directory/ + +# 📤 Extraire une archive +tzst x archive.tzst + +# 📋 Lister le contenu d'une archive +tzst l archive.tzst + +# 🧪 Tester l'intégrité d'une archive +tzst t archive.tzst +``` + +### 🐍 Utilisation de l'API Python + +```python +from tzst import create_archive, extract_archive, list_archive + +# Créer une archive +create_archive("archive.tzst", ["file1.txt", "file2.txt", "directory/"]) + +# Extraire une archive +extract_archive("archive.tzst", "output_directory/") + +# Lister le contenu d'une archive +contents = list_archive("archive.tzst", verbose=True) +for item in contents: + print(f"{item['name']}: {item['size']} bytes") +``` + +## 💻 Interface en ligne de commande + +### 📁 Opérations d'archives + +#### ➕ Créer une archive + +```bash +# Utilisation de base +tzst a archive.tzst file1.txt file2.txt + +# Avec niveau de compression (1-22, défaut : 3) +tzst a archive.tzst files/ -l 15 + +# Commandes alternatives +tzst add archive.tzst files/ +tzst create archive.tzst files/ +``` + +#### 📤 Extraire une archive + +```bash +# Extraire avec structure complète des répertoires +tzst x archive.tzst + +# Extraire vers un répertoire spécifique +tzst x archive.tzst -o output/ + +# Extraire des fichiers spécifiques +tzst x archive.tzst file1.txt dir/file2.txt + +# Extraire sans structure de répertoires (à plat) +tzst e archive.tzst -o output/ + +# Utiliser le mode streaming pour de grandes archives +tzst x archive.tzst --streaming -o output/ +``` + +#### 📋 Lister le contenu + +```bash +# Liste simple +tzst l archive.tzst + +# Liste détaillée avec informations +tzst l archive.tzst -v + +# Utiliser le mode streaming pour de grandes archives +tzst l archive.tzst --streaming -v +``` + +#### 🧪 Tester l'intégrité + +```bash +# Tester l'intégrité de l'archive +tzst t archive.tzst + +# Tester avec le mode streaming +tzst t archive.tzst --streaming +``` + +### 📊 Référence des commandes + +| Commande | Alias | Description | Support streaming | +|---------|---------|-------------|-------------------| +| `a` | `add`, `create` | Créer ou ajouter à une archive | N/A | +| `x` | `extract` | Extraire avec chemins complets | ✓ `--streaming` | +| `e` | `extract-flat` | Extraire sans structure de répertoires | ✓ `--streaming` | +| `l` | `list` | Lister le contenu de l'archive | ✓ `--streaming` | +| `t` | `test` | Tester l'intégrité de l'archive | ✓ `--streaming` | + +### ⚙️ Options CLI + +- `-v, --verbose` : Activer la sortie détaillée +- `-o, --output DIR` : Spécifier le répertoire de sortie (commandes d'extraction) +- `-l, --level LEVEL` : Définir le niveau de compression 1-22 (commande de création) +- `--streaming` : Activer le mode streaming pour un traitement efficace en mémoire +- `--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é + +```bash +# Extraire avec sécurité maximale (défaut) +tzst x archive.tzst --filter data + +# Extraire avec compatibilité tar standard +tzst x archive.tzst --filter tar + +# Extraire avec confiance totale (dangereux - uniquement pour les archives de confiance) +tzst x archive.tzst --filter fully_trusted +``` + +**🔐 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 + +### 📦 Classe TzstArchive + +```python +from tzst import TzstArchive + +# Créer une nouvelle archive +with TzstArchive("archive.tzst", "w", compression_level=5) as archive: + archive.add("file.txt") + archive.add("directory/", recursive=True) + +# Lire une archive existante +with TzstArchive("archive.tzst", "r") as archive: + # Lister le contenu + contents = archive.list(verbose=True) + + # Extraire avec filtre de sécurité + archive.extract("file.txt", "output/", filter="data") + + # Tester l'intégrité + is_valid = archive.test() + +# Pour de grandes archives, utiliser le mode streaming +with TzstArchive("large_archive.tzst", "r", streaming=True) as archive: + archive.extract(path="output/") +``` + +**⚠️ Limitations importantes :** + +- **❌ Mode d'ajout non supporté** : Créez plusieurs archives ou recréez l'archive entière à la place + +### 🎯 Fonctions de convenance + +#### 📁 create_archive() + +```python +from tzst import create_archive + +# Créer avec opérations atomiques (défaut) +create_archive( + archive_path="backup.tzst", + files=["documents/", "photos/", "config.txt"], + compression_level=10 +) +``` + +#### 📤 extract_archive() + +```python +from tzst import extract_archive + +# Extraire avec sécurité (défaut : filtre 'data') +extract_archive("backup.tzst", "restore/") + +# Extraire des fichiers spécifiques +extract_archive("backup.tzst", "restore/", members=["config.txt"]) + +# Aplatir la structure des répertoires +extract_archive("backup.tzst", "restore/", flatten=True) + +# Utiliser le streaming pour de grandes archives +extract_archive("large_backup.tzst", "restore/", streaming=True) +``` + +#### 📋 list_archive() + +```python +from tzst import list_archive + +# Liste simple +files = list_archive("backup.tzst") + +# Liste détaillée +files = list_archive("backup.tzst", verbose=True) + +# Streaming pour de grandes archives +files = list_archive("large_backup.tzst", streaming=True) +``` + +#### 🧪 test_archive() + +```python +from tzst import test_archive + +# Test d'intégrité de base +if test_archive("backup.tzst"): + print("L'archive est valide") + +# Tester avec streaming +if test_archive("large_backup.tzst", streaming=True): + print("La grande archive est valide") +``` + +## 🔧 Fonctionnalités avancées + +### 📂 Extensions de fichiers + +La bibliothèque gère automatiquement les extensions de fichiers avec normalisation intelligente : + +- `.tzst` - Extension principale pour les archives tar+zstandard +- `.tar.zst` - Extension standard alternative +- Détection automatique lors de l'ouverture d'archives existantes +- Ajout automatique d'extension lors de la création d'archives + +```python +# Toutes ces créent des archives valides +create_archive("backup.tzst", files) # Crée backup.tzst +create_archive("backup.tar.zst", files) # Crée backup.tar.zst +create_archive("backup", files) # Crée backup.tzst +create_archive("backup.txt", files) # Crée backup.tzst (normalisé) +``` + +### 🗜️ Niveaux de compression + +Les niveaux de compression Zstandard vont de 1 (le plus rapide) à 22 (meilleure compression) : + +- **Niveau 1-3** : Compression rapide, fichiers plus volumineux +- **Niveau 3** (défaut) : Bon équilibre entre vitesse et compression +- **Niveau 10-15** : Meilleure compression, plus lent +- **Niveau 20-22** : Compression maximale, beaucoup plus lent + +### 🌊 Mode streaming + +Utilisez le mode streaming pour un traitement efficace en mémoire de grandes archives : + +**✅ 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 :** + +- Archives supérieures à 100MB +- Environnements à mémoire limitée +- Traitement d'archives avec de nombreux gros fichiers + +```python +# Exemple : Traitement d'une grande archive de sauvegarde +from tzst import extract_archive, list_archive, test_archive + +large_archive = "backup_500gb.tzst" + +# Opérations efficaces en mémoire +is_valid = test_archive(large_archive, streaming=True) +contents = list_archive(large_archive, streaming=True, verbose=True) +extract_archive(large_archive, "restore/", streaming=True) +``` + +### ⚡ Opérations atomiques + +Toutes les opérations de création de fichiers utilisent des opérations de fichiers atomiques par défaut : + +- Archives créées dans des fichiers temporaires d'abord, puis déplacées atomiquement +- Nettoyage automatique si le processus est interrompu +- Aucun risque d'archives corrompues ou incomplètes +- Compatibilité multi-plateforme + +```python +# Opérations atomiques activées par défaut +create_archive("important.tzst", files) # Sûr contre les interruptions + +# Peut être désactivé si nécessaire (non recommandé) +create_archive("test.tzst", files, use_temp_file=False) +``` + +### 🚨 Gestion des erreurs + +```python +from tzst import TzstArchive +from tzst.exceptions import ( + TzstError, + TzstArchiveError, + TzstCompressionError, + TzstDecompressionError, + TzstFileNotFoundError +) + +try: + with TzstArchive("archive.tzst", "r") as archive: + archive.extract() +except TzstDecompressionError: + print("Échec de la décompression de l'archive") +except TzstFileNotFoundError: + print("Fichier d'archive non trouvé") +except KeyboardInterrupt: + print("Opération interrompue par l'utilisateur") + # Le nettoyage est géré automatiquement +``` + +## 🚀 Performance et comparaison + +### 💡 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 + +### 🆚 vs Autres outils + +**vs tar + gzip :** + +- ✅ 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 + +**vs zip :** + +- 🗜️ Meilleure compression +- 🔐 Préserve les permissions Unix et métadonnées +- 🌊 Meilleur support de streaming + +## 📋 Exigences + +- 🐍 Python 3.12 ou supérieur +- 📦 zstandard >= 0.19.0 + +## 🛠️ Développement + +### 🚀 Configuration de l'environnement de développement + +Ce projet utilise les standards modernes d'empaquetage Python : + +```bash +git clone https://github.com/xixu-me/tzst.git +cd tzst +pip install -e .[dev] +``` + +### 🧪 Exécution des tests + +```bash +# Exécuter les tests avec couverture +pytest --cov=tzst --cov-report=html + +# Ou utiliser la commande plus simple (paramètres de couverture dans pyproject.toml) +pytest +``` + +### ✨ Qualité du code + +```bash +# Vérifier la qualité du code +ruff check src tests + +# Formater le code +ruff format src tests +``` + +## 🤝 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 +- Exigences de test et écriture de tests +- Processus de pull request et workflow de révision + +### 🚀 Démarrage rapide pour les contributeurs + +```bash +git clone https://github.com/xixu-me/tzst.git +cd tzst +pip install -e .[dev] +python -m pytest tests/ +``` + +### 🎯 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é + +## 🙏 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 + +Droits d'auteur © 2025 [Xi Xu](https://xi-xu.me). Tous droits réservés. + +Sous licence [BSD 3-Clause](LICENSE). diff --git a/README.ja.md b/README.ja.md index 934ff22..aac6a15 100644 --- a/README.ja.md +++ b/README.ja.md @@ -34,12 +34,12 @@ Python インストール不要のスタンドアロン実行ファイルをダ | プラットフォーム | アーキテクチャ | ファイル | |----------|-------------|------| -| **🐧 Linux** | x86_64 | `tzst-v{version}-linux-x86_64.zip` | -| **🐧 Linux** | ARM64 | `tzst-v{version}-linux-aarch64.zip` | -| **🪟 Windows** | x64 | `tzst-v{version}-windows-amd64.zip` | -| **🪟 Windows** | ARM64 | `tzst-v{version}-windows-arm64.zip` | -| **🍎 macOS** | Intel | `tzst-v{version}-macos-x86_64.zip` | -| **🍎 macOS** | Apple Silicon | `tzst-v{version}-macos-arm64.zip` | +| **🐧 Linux** | x86_64 | `tzst-v{バージョン}-linux-x86_64.zip` | +| **🐧 Linux** | ARM64 | `tzst-v{バージョン}-linux-aarch64.zip` | +| **🪟 Windows** | x64 | `tzst-v{バージョン}-windows-amd64.zip` | +| **🪟 Windows** | ARM64 | `tzst-v{バージョン}-windows-arm64.zip` | +| **🍎 macOS** | Intel | `tzst-v{バージョン}-macos-x86_64.zip` | +| **🍎 macOS** | Apple Silicon | `tzst-v{バージョン}-macos-arm64.zip` | #### 🛠️ インストール手順 diff --git a/README.ko.md b/README.ko.md index 0774c3f..d88a0f2 100644 --- a/README.ko.md +++ b/README.ko.md @@ -34,12 +34,12 @@ Python 설치가 필요 없는 독립형 실행 파일 다운로드: | 플랫폼 | 아키텍처 | 파일 | |----------|-------------|------| -| **🐧 Linux** | x86_64 | `tzst-v{version}-linux-x86_64.zip` | -| **🐧 Linux** | ARM64 | `tzst-v{version}-linux-aarch64.zip` | -| **🪟 Windows** | x64 | `tzst-v{version}-windows-amd64.zip` | -| **🪟 Windows** | ARM64 | `tzst-v{version}-windows-arm64.zip` | -| **🍎 macOS** | Intel | `tzst-v{version}-macos-x86_64.zip` | -| **🍎 macOS** | Apple Silicon | `tzst-v{version}-macos-arm64.zip` | +| **🐧 Linux** | x86_64 | `tzst-v{버전}-linux-x86_64.zip` | +| **🐧 Linux** | ARM64 | `tzst-v{버전}-linux-aarch64.zip` | +| **🪟 Windows** | x64 | `tzst-v{버전}-windows-amd64.zip` | +| **🪟 Windows** | ARM64 | `tzst-v{버전}-windows-arm64.zip` | +| **🍎 macOS** | Intel | `tzst-v{버전}-macos-x86_64.zip` | +| **🍎 macOS** | Apple Silicon | `tzst-v{버전}-macos-arm64.zip` | #### 🛠️ 설치 단계 @@ -508,6 +508,6 @@ python -m pytest tests/ ## 📄 라이선스 -저작권 © 2025 [Xi Xu](https://xi-xu.me). 모든 권리 보유. +저작권 © 2025 [시 쉬](https://xi-xu.me). 모든 권리 보유. [BSD 3-Clause](LICENSE) 라이선스로 사용이 허가되었습니다. diff --git a/README.pt.md b/README.pt.md new file mode 100644 index 0000000..2308dd3 --- /dev/null +++ b/README.pt.md @@ -0,0 +1,513 @@ +[🇬🇧 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 + +[![codecov](https://codecov.io/gh/xixu-me/tzst/graph/badge.svg?token=2AIN1559WU)](https://codecov.io/gh/xixu-me/tzst) +[![CodeQL](https://github.com/xixu-me/tzst/actions/workflows/github-code-scanning/codeql/badge.svg)](https://github.com/xixu-me/tzst/actions/workflows/github-code-scanning/codeql) +[![CI/CD](https://github.com/xixu-me/tzst/actions/workflows/ci.yml/badge.svg)](https://github.com/xixu-me/tzst/actions/workflows/ci.yml) +[![PyPI - Version](https://img.shields.io/pypi/v/tzst)](https://pypi.org/project/tzst/) +[![GitHub License](https://img.shields.io/github/license/xixu-me/tzst)](LICENSE) +[![Sponsor](https://img.shields.io/badge/Sponsor-violet)](https://xi-xu.me/#sponsorships) + +**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. 🚀 + +## ✨ 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 + +## 📥 Instalação + +### Dos Releases do GitHub + +Baixe executáveis independentes que não requerem instalação do Python: + +#### Plataformas Suportadas + +| Plataforma | Arquitetura | Arquivo | +|----------|-------------|------| +| **🐧 Linux** | x86_64 | `tzst-v{versão}-linux-x86_64.zip` | +| **🐧 Linux** | ARM64 | `tzst-v{versão}-linux-aarch64.zip` | +| **🪟 Windows** | x64 | `tzst-v{versão}-windows-amd64.zip` | +| **🪟 Windows** | ARM64 | `tzst-v{versão}-windows-arm64.zip` | +| **🍎 macOS** | Intel | `tzst-v{versão}-macos-x86_64.zip` | +| **🍎 macOS** | Apple Silicon | `tzst-v{versão}-macos-arm64.zip` | + +#### 🛠️ 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` + +#### 🎯 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 + +### 📦 Do PyPI + +```bash +pip install tzst +``` + +### 🔧 Do Código Fonte + +```bash +git clone https://github.com/xixu-me/tzst.git +cd tzst +pip install . +``` + +### 🚀 Instalação para Desenvolvimento + +Este projeto usa padrões modernos de empacotamento Python: + +```bash +git clone https://github.com/xixu-me/tzst.git +cd tzst +pip install -e .[dev] +``` + +## 🚀 Início Rápido + +### 💻 Uso da Linha de Comando + +> **Nota**: Baixe o [binário independente](#dos-releases-do-github) para melhor desempenho e sem dependência do Python. Alternativamente, use `uvx tzst` para executar sem instalação. Veja a [documentação do uv](https://docs.astral.sh/uv/) para detalhes. + +```bash +# 📁 Criar um arquivo +tzst a archive.tzst file1.txt file2.txt directory/ + +# 📤 Extrair um arquivo +tzst x archive.tzst + +# 📋 Listar conteúdo do arquivo +tzst l archive.tzst + +# 🧪 Testar integridade do arquivo +tzst t archive.tzst +``` + +### 🐍 Uso da API Python + +```python +from tzst import create_archive, extract_archive, list_archive + +# Criar um arquivo +create_archive("archive.tzst", ["file1.txt", "file2.txt", "directory/"]) + +# Extrair um arquivo +extract_archive("archive.tzst", "output_directory/") + +# Listar conteúdo do arquivo +contents = list_archive("archive.tzst", verbose=True) +for item in contents: + print(f"{item['name']}: {item['size']} bytes") +``` + +## 💻 Interface de Linha de Comando + +### 📁 Operações de Arquivo + +#### ➕ Criar Arquivo + +```bash +# Uso básico +tzst a archive.tzst file1.txt file2.txt + +# Com nível de compressão (1-22, padrão: 3) +tzst a archive.tzst files/ -l 15 + +# Comandos alternativos +tzst add archive.tzst files/ +tzst create archive.tzst files/ +``` + +#### 📤 Extrair Arquivo + +```bash +# Extrair com estrutura completa de diretórios +tzst x archive.tzst + +# Extrair para diretório específico +tzst x archive.tzst -o output/ + +# Extrair arquivos específicos +tzst x archive.tzst file1.txt dir/file2.txt + +# Extrair sem estrutura de diretórios (plano) +tzst e archive.tzst -o output/ + +# Usar modo streaming para grandes arquivos +tzst x archive.tzst --streaming -o output/ +``` + +#### 📋 Listar Conteúdo + +```bash +# Listagem simples +tzst l archive.tzst + +# Listagem detalhada com informações +tzst l archive.tzst -v + +# Usar modo streaming para grandes arquivos +tzst l archive.tzst --streaming -v +``` + +#### 🧪 Testar Integridade + +```bash +# Testar integridade do arquivo +tzst t archive.tzst + +# Testar com modo streaming +tzst t archive.tzst --streaming +``` + +### 📊 Referência de Comandos + +| Comando | Aliases | Descrição | Suporte a Streaming | +|---------|---------|-------------|-------------------| +| `a` | `add`, `create` | Criar ou adicionar ao arquivo | N/A | +| `x` | `extract` | Extrair com caminhos completos | ✓ `--streaming` | +| `e` | `extract-flat` | Extrair sem estrutura de diretórios | ✓ `--streaming` | +| `l` | `list` | Listar conteúdo do arquivo | ✓ `--streaming` | +| `t` | `test` | Testar integridade do arquivo | ✓ `--streaming` | + +### ⚙️ Opções da CLI + +- `-v, --verbose`: Ativar saída detalhada +- `-o, --output DIR`: Especificar diretório de saída (comandos de extração) +- `-l, --level LEVEL`: Definir nível de compressão 1-22 (comando de criação) +- `--streaming`: Ativar modo streaming para processamento eficiente em memória +- `--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 + +```bash +# Extrair com máxima segurança (padrão) +tzst x archive.tzst --filter data + +# Extrair com compatibilidade tar padrão +tzst x archive.tzst --filter tar + +# Extrair com confiança total (perigoso - apenas para arquivos confiáveis) +tzst x archive.tzst --filter fully_trusted +``` + +**🔐 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 + +### 📦 Classe TzstArchive + +```python +from tzst import TzstArchive + +# Criar um novo arquivo +with TzstArchive("archive.tzst", "w", compression_level=5) as archive: + archive.add("file.txt") + archive.add("directory/", recursive=True) + +# Ler um arquivo existente +with TzstArchive("archive.tzst", "r") as archive: + # Listar conteúdo + contents = archive.list(verbose=True) + + # Extrair com filtro de segurança + archive.extract("file.txt", "output/", filter="data") + + # Testar integridade + is_valid = archive.test() + +# Para grandes arquivos, usar modo streaming +with TzstArchive("large_archive.tzst", "r", streaming=True) as archive: + archive.extract(path="output/") +``` + +**⚠️ Limitações Importantes:** + +- **❌ Modo de anexação não suportado**: Crie múltiplos arquivos ou recrie o arquivo inteiro em vez disso + +### 🎯 Funções de Conveniência + +#### 📁 create_archive() + +```python +from tzst import create_archive + +# Criar com operações atômicas (padrão) +create_archive( + archive_path="backup.tzst", + files=["documents/", "photos/", "config.txt"], + compression_level=10 +) +``` + +#### 📤 extract_archive() + +```python +from tzst import extract_archive + +# Extrair com segurança (padrão: filtro 'data') +extract_archive("backup.tzst", "restore/") + +# Extrair arquivos específicos +extract_archive("backup.tzst", "restore/", members=["config.txt"]) + +# Achatar estrutura de diretórios +extract_archive("backup.tzst", "restore/", flatten=True) + +# Usar streaming para grandes arquivos +extract_archive("large_backup.tzst", "restore/", streaming=True) +``` + +#### 📋 list_archive() + +```python +from tzst import list_archive + +# Listagem simples +files = list_archive("backup.tzst") + +# Listagem detalhada +files = list_archive("backup.tzst", verbose=True) + +# Streaming para grandes arquivos +files = list_archive("large_backup.tzst", streaming=True) +``` + +#### 🧪 test_archive() + +```python +from tzst import test_archive + +# Teste básico de integridade +if test_archive("backup.tzst"): + print("Arquivo é válido") + +# Testar com streaming +if test_archive("large_backup.tzst", streaming=True): + print("Grande arquivo é válido") +``` + +## 🔧 Recursos Avançados + +### 📂 Extensões de Arquivo + +A biblioteca automaticamente lida com extensões de arquivo com normalização inteligente: + +- `.tzst` - Extensão primária para arquivos tar+zstandard +- `.tar.zst` - Extensão padrão alternativa +- Detecção automática ao abrir arquivos existentes +- Adição automática de extensão ao criar arquivos + +```python +# Todos estes criam arquivos válidos +create_archive("backup.tzst", files) # Cria backup.tzst +create_archive("backup.tar.zst", files) # Cria backup.tar.zst +create_archive("backup", files) # Cria backup.tzst +create_archive("backup.txt", files) # Cria backup.tzst (normalizado) +``` + +### 🗜️ Níveis de Compressão + +Os níveis de compressão Zstandard variam de 1 (mais rápido) a 22 (melhor compressão): + +- **Nível 1-3**: Compressão rápida, arquivos maiores +- **Nível 3** (padrão): Bom equilíbrio entre velocidade e compressão +- **Nível 10-15**: Melhor compressão, mais lento +- **Nível 20-22**: Compressão máxima, muito mais lento + +### 🌊 Modo Streaming + +Use o modo streaming para processamento eficiente em memória de grandes arquivos: + +**✅ 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:** + +- Arquivos maiores que 100MB +- Ambientes com memória limitada +- Processamento de arquivos com muitos arquivos grandes + +```python +# Exemplo: Processando um grande arquivo de backup +from tzst import extract_archive, list_archive, test_archive + +large_archive = "backup_500gb.tzst" + +# Operações eficientes em memória +is_valid = test_archive(large_archive, streaming=True) +contents = list_archive(large_archive, streaming=True, verbose=True) +extract_archive(large_archive, "restore/", streaming=True) +``` + +### ⚡ Operações Atômicas + +Todas as operações de criação de arquivo usam operações de arquivo atômicas por padrão: + +- Arquivos criados em arquivos temporários primeiro, depois movidos atomicamente +- Limpeza automática se o processo for interrompido +- Nenhum risco de arquivos corrompidos ou incompletos +- Compatibilidade multiplataforma + +```python +# Operações atômicas habilitadas por padrão +create_archive("important.tzst", files) # Seguro contra interrupção + +# Pode ser desabilitado se necessário (não recomendado) +create_archive("test.tzst", files, use_temp_file=False) +``` + +### 🚨 Tratamento de Erros + +```python +from tzst import TzstArchive +from tzst.exceptions import ( + TzstError, + TzstArchiveError, + TzstCompressionError, + TzstDecompressionError, + TzstFileNotFoundError +) + +try: + with TzstArchive("archive.tzst", "r") as archive: + archive.extract() +except TzstDecompressionError: + print("Falha ao descomprimir arquivo") +except TzstFileNotFoundError: + print("Arquivo de arquivo não encontrado") +except KeyboardInterrupt: + print("Operação interrompida pelo usuário") + # Limpeza é tratada automaticamente +``` + +## 🚀 Desempenho e Comparação + +### 💡 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 + +### 🆚 vs Outras Ferramentas + +**vs tar + gzip:** + +- ✅ 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 + +**vs zip:** + +- 🗜️ Melhor compressão +- 🔐 Preserva permissões Unix e metadados +- 🌊 Melhor suporte a streaming + +## 📋 Requisitos + +- 🐍 Python 3.12 ou superior +- 📦 zstandard >= 0.19.0 + +## 🛠️ Desenvolvimento + +### 🚀 Configurando Ambiente de Desenvolvimento + +Este projeto usa padrões modernos de empacotamento Python: + +```bash +git clone https://github.com/xixu-me/tzst.git +cd tzst +pip install -e .[dev] +``` + +### 🧪 Executando Testes + +```bash +# Executar testes com cobertura +pytest --cov=tzst --cov-report=html + +# Ou usar o comando mais simples (configurações de cobertura estão em pyproject.toml) +pytest +``` + +### ✨ Qualidade do Código + +```bash +# Verificar qualidade do código +ruff check src tests + +# Formatar código +ruff format src tests +``` + +## 🤝 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 +- Requisitos de teste e escrita de testes +- Processo de pull request e fluxo de revisão + +### 🚀 Início Rápido para Colaboradores + +```bash +git clone https://github.com/xixu-me/tzst.git +cd tzst +pip install -e .[dev] +python -m pytest tests/ +``` + +### 🎯 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 + +## 🙏 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 + +Direitos autorais © 2025 [Xi Xu](https://xi-xu.me). Todos os direitos reservados. + +Licenciado sob a licença [BSD 3-Clause](LICENSE). diff --git a/README.ru.md b/README.ru.md new file mode 100644 index 0000000..b99e159 --- /dev/null +++ b/README.ru.md @@ -0,0 +1,513 @@ +[🇬🇧 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 + +[![codecov](https://codecov.io/gh/xixu-me/tzst/graph/badge.svg?token=2AIN1559WU)](https://codecov.io/gh/xixu-me/tzst) +[![CodeQL](https://github.com/xixu-me/tzst/actions/workflows/github-code-scanning/codeql/badge.svg)](https://github.com/xixu-me/tzst/actions/workflows/github-code-scanning/codeql) +[![CI/CD](https://github.com/xixu-me/tzst/actions/workflows/ci.yml/badge.svg)](https://github.com/xixu-me/tzst/actions/workflows/ci.yml) +[![PyPI - Version](https://img.shields.io/pypi/v/tzst)](https://pypi.org/project/tzst/) +[![GitHub License](https://img.shields.io/github/license/xixu-me/tzst)](LICENSE) +[![Sponsor](https://img.shields.io/badge/Sponsor-violet)](https://xi-xu.me/#sponsorships) + +**tzst** — это библиотека Python нового поколения, разработанная для современного управления архивами, использующая передовое сжатие Zstandard для обеспечения превосходной производительности, безопасности и надёжности. Созданная исключительно для Python 3.12+, это корпоративное решение объединяет атомарные операции, эффективность потоковой передачи и тщательно разработанный API для переосмысления того, как разработчики работают с архивами `.tzst`/`.tar.zst` в производственных средах. 🚀 + +## ✨ Особенности + +- **🗜️ Высокое сжатие**: Сжатие Zstandard для отличных коэффициентов сжатия и скорости +- **📁 Совместимость с Tar**: Создаёт стандартные tar-архивы, сжатые с помощью Zstandard +- **💻 Интерфейс командной строки**: Интуитивный CLI с поддержкой потоковой передачи и всесторонними опциями +- **🐍 Python API**: Чистый, pythonic API для программного использования +- **🌍 Кроссплатформенность**: Работает на Windows, macOS и Linux +- **📂 Множественные расширения**: Поддерживает как `.tzst`, так и `.tar.zst` расширения +- **💾 Эффективность памяти**: Режим потоковой передачи для обработки больших архивов с минимальным использованием памяти +- **⚡ Атомарные операции**: Безопасные файловые операции с автоматической очисткой при прерывании +- **🔒 Безопасность по умолчанию**: Использует фильтр 'data' для максимальной безопасности при извлечении +- **🚨 Улучшенная обработка ошибок**: Чёткие сообщения об ошибках с полезными альтернативами + +## 📥 Установка + +### Из релизов GitHub + +Скачайте автономные исполняемые файлы, которые не требуют установки Python: + +#### Поддерживаемые платформы + +| Платформа | Архитектура | Файл | +|----------|-------------|------| +| **🐧 Linux** | x86_64 | `tzst-v{версия}-linux-x86_64.zip` | +| **🐧 Linux** | ARM64 | `tzst-v{версия}-linux-aarch64.zip` | +| **🪟 Windows** | x64 | `tzst-v{версия}-windows-amd64.zip` | +| **🪟 Windows** | ARM64 | `tzst-v{версия}-windows-arm64.zip` | +| **🍎 macOS** | Intel | `tzst-v{версия}-macos-x86_64.zip` | +| **🍎 macOS** | Apple Silicon | `tzst-v{версия}-macos-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` + +#### 🎯 Преимущества бинарной установки + +- ✅ **Python не требуется** - Автономный исполняемый файл +- ✅ **Быстрый запуск** - Нет накладных расходов интерпретатора Python +- ✅ **Лёгкое развёртывание** - Распространение одним файлом +- ✅ **Последовательное поведение** - Встроенные зависимости + +### 📦 Из PyPI + +```bash +pip install tzst +``` + +### 🔧 Из исходного кода + +```bash +git clone https://github.com/xixu-me/tzst.git +cd tzst +pip install . +``` + +### 🚀 Установка для разработки + +Этот проект использует современные стандарты упаковки Python: + +```bash +git clone https://github.com/xixu-me/tzst.git +cd tzst +pip install -e .[dev] +``` + +## 🚀 Быстрый старт + +### 💻 Использование командной строки + +> **Примечание**: Скачайте [автономный бинарный файл](#из-релизов-github) для лучшей производительности и отсутствия зависимости от Python. Альтернативно, используйте `uvx tzst` для запуска без установки. Смотрите [документацию uv](https://docs.astral.sh/uv/) для деталей. + +```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 +from tzst import create_archive, extract_archive, list_archive + +# Создать архив +create_archive("archive.tzst", ["file1.txt", "file2.txt", "directory/"]) + +# Извлечь архив +extract_archive("archive.tzst", "output_directory/") + +# Список содержимого архива +contents = list_archive("archive.tzst", verbose=True) +for item in contents: + print(f"{item['name']}: {item['size']} bytes") +``` + +## 💻 Интерфейс командной строки + +### 📁 Операции с архивами + +#### ➕ Создать архив + +```bash +# Базовое использование +tzst a archive.tzst file1.txt file2.txt + +# С уровнем сжатия (1-22, по умолчанию: 3) +tzst a archive.tzst files/ -l 15 + +# Альтернативные команды +tzst add archive.tzst files/ +tzst create archive.tzst files/ +``` + +#### 📤 Извлечь архив + +```bash +# Извлечь с полной структурой директорий +tzst x archive.tzst + +# Извлечь в определённую директорию +tzst x archive.tzst -o output/ + +# Извлечь определённые файлы +tzst x archive.tzst file1.txt dir/file2.txt + +# Извлечь без структуры директорий (плоско) +tzst e archive.tzst -o output/ + +# Использовать режим потоковой передачи для больших архивов +tzst x archive.tzst --streaming -o output/ +``` + +#### 📋 Список содержимого + +```bash +# Простой список +tzst l archive.tzst + +# Подробный список с деталями +tzst l archive.tzst -v + +# Использовать режим потоковой передачи для больших архивов +tzst l archive.tzst --streaming -v +``` + +#### 🧪 Проверка целостности + +```bash +# Проверить целостность архива +tzst t archive.tzst + +# Проверить с режимом потоковой передачи +tzst t archive.tzst --streaming +``` + +### 📊 Справочник команд + +| Команда | Псевдонимы | Описание | Поддержка потоковой передачи | +|---------|---------|-------------|-------------------| +| `a` | `add`, `create` | Создать или добавить в архив | N/A | +| `x` | `extract` | Извлечь с полными путями | ✓ `--streaming` | +| `e` | `extract-flat` | Извлечь без структуры директорий | ✓ `--streaming` | +| `l` | `list` | Список содержимого архива | ✓ `--streaming` | +| `t` | `test` | Проверить целостность архива | ✓ `--streaming` | + +### ⚙️ Опции CLI + +- `-v, --verbose`: Включить подробный вывод +- `-o, --output DIR`: Указать выходную директорию (команды извлечения) +- `-l, --level LEVEL`: Установить уровень сжатия 1-22 (команда создания) +- `--streaming`: Включить режим потоковой передачи для эффективной обработки памяти +- `--filter FILTER`: Фильтр безопасности для извлечения (data/tar/fully_trusted) +- `--no-atomic`: Отключить атомарные файловые операции (не рекомендуется) + +### 🔒 Фильтры безопасности + +```bash +# Извлечь с максимальной безопасностью (по умолчанию) +tzst x archive.tzst --filter data + +# Извлечь со стандартной совместимостью tar +tzst x archive.tzst --filter tar + +# Извлечь с полным доверием (опасно - только для доверенных архивов) +tzst x archive.tzst --filter fully_trusted +``` + +**🔐 Опции фильтра безопасности:** + +- `data` (по умолчанию): Наиболее безопасно. Блокирует опасные файлы, абсолютные пути и пути вне директории извлечения +- `tar`: Стандартная совместимость tar. Блокирует абсолютные пути и обход директорий +- `fully_trusted`: Никаких ограничений безопасности. Используйте только с полностью доверенными архивами + +## 🐍 Python API + +### 📦 Класс TzstArchive + +```python +from tzst import TzstArchive + +# Создать новый архив +with TzstArchive("archive.tzst", "w", compression_level=5) as archive: + archive.add("file.txt") + archive.add("directory/", recursive=True) + +# Прочитать существующий архив +with TzstArchive("archive.tzst", "r") as archive: + # Список содержимого + contents = archive.list(verbose=True) + + # Извлечь с фильтром безопасности + archive.extract("file.txt", "output/", filter="data") + + # Проверить целостность + is_valid = archive.test() + +# Для больших архивов используйте режим потоковой передачи +with TzstArchive("large_archive.tzst", "r", streaming=True) as archive: + archive.extract(path="output/") +``` + +**⚠️ Важные ограничения:** + +- **❌ Режим добавления не поддерживается**: Создавайте множественные архивы или пересоздавайте весь архив вместо этого + +### 🎯 Удобные функции + +#### 📁 create_archive() + +```python +from tzst import create_archive + +# Создать с атомарными операциями (по умолчанию) +create_archive( + archive_path="backup.tzst", + files=["documents/", "photos/", "config.txt"], + compression_level=10 +) +``` + +#### 📤 extract_archive() + +```python +from tzst import extract_archive + +# Извлечь с безопасностью (по умолчанию: фильтр 'data') +extract_archive("backup.tzst", "restore/") + +# Извлечь определённые файлы +extract_archive("backup.tzst", "restore/", members=["config.txt"]) + +# Сплющить структуру директорий +extract_archive("backup.tzst", "restore/", flatten=True) + +# Использовать потоковую передачу для больших архивов +extract_archive("large_backup.tzst", "restore/", streaming=True) +``` + +#### 📋 list_archive() + +```python +from tzst import list_archive + +# Простой список +files = list_archive("backup.tzst") + +# Подробный список +files = list_archive("backup.tzst", verbose=True) + +# Потоковая передача для больших архивов +files = list_archive("large_backup.tzst", streaming=True) +``` + +#### 🧪 test_archive() + +```python +from tzst import test_archive + +# Базовая проверка целостности +if test_archive("backup.tzst"): + print("Архив действителен") + +# Проверка с потоковой передачей +if test_archive("large_backup.tzst", streaming=True): + print("Большой архив действителен") +``` + +## 🔧 Продвинутые возможности + +### 📂 Расширения файлов + +Библиотека автоматически обрабатывает расширения файлов с интеллектуальной нормализацией: + +- `.tzst` - Основное расширение для архивов tar+zstandard +- `.tar.zst` - Альтернативное стандартное расширение +- Автоопределение при открытии существующих архивов +- Автоматическое добавление расширения при создании архивов + +```python +# Все это создаёт действительные архивы +create_archive("backup.tzst", files) # Создаёт backup.tzst +create_archive("backup.tar.zst", files) # Создаёт backup.tar.zst +create_archive("backup", files) # Создаёт backup.tzst +create_archive("backup.txt", files) # Создаёт backup.tzst (нормализовано) +``` + +### 🗜️ Уровни сжатия + +Уровни сжатия Zstandard варьируются от 1 (самый быстрый) до 22 (лучшее сжатие): + +- **Уровень 1-3**: Быстрое сжатие, большие файлы +- **Уровень 3** (по умолчанию): Хороший баланс скорости и сжатия +- **Уровень 10-15**: Лучшее сжатие, медленнее +- **Уровень 20-22**: Максимальное сжатие, намного медленнее + +### 🌊 Режим потоковой передачи + +Используйте режим потоковой передачи для эффективной обработки больших архивов в памяти: + +**✅ Преимущества:** + +- Значительно сниженное использование памяти +- Лучшая производительность для архивов, которые не помещаются в память +- Автоматическая очистка ресурсов + +**🎯 Когда использовать:** + +- Архивы больше 100MB +- Среды с ограниченной памятью +- Обработка архивов с множеством больших файлов + +```python +# Пример: Обработка большого архива резервной копии +from tzst import extract_archive, list_archive, test_archive + +large_archive = "backup_500gb.tzst" + +# Операции, эффективные по памяти +is_valid = test_archive(large_archive, streaming=True) +contents = list_archive(large_archive, streaming=True, verbose=True) +extract_archive(large_archive, "restore/", streaming=True) +``` + +### ⚡ Атомарные операции + +Все операции создания файлов используют атомарные файловые операции по умолчанию: + +- Архивы создаются сначала во временных файлах, затем атомарно перемещаются +- Автоматическая очистка при прерывании процесса +- Никакого риска повреждённых или неполных архивов +- Кроссплатформенная совместимость + +```python +# Атомарные операции включены по умолчанию +create_archive("important.tzst", files) # Безопасно от прерывания + +# Может быть отключено при необходимости (не рекомендуется) +create_archive("test.tzst", files, use_temp_file=False) +``` + +### 🚨 Обработка ошибок + +```python +from tzst import TzstArchive +from tzst.exceptions import ( + TzstError, + TzstArchiveError, + TzstCompressionError, + TzstDecompressionError, + TzstFileNotFoundError +) + +try: + with TzstArchive("archive.tzst", "r") as archive: + archive.extract() +except TzstDecompressionError: + print("Не удалось распаковать архив") +except TzstFileNotFoundError: + print("Файл архива не найден") +except KeyboardInterrupt: + print("Операция прервана пользователем") + # Очистка обрабатывается автоматически +``` + +## 🚀 Производительность и сравнение + +### 💡 Советы по производительности + +1. **🗜️ Уровни сжатия**: Уровень 3 оптимален для большинства случаев использования +2. **🌊 Потоковая передача**: Используйте для архивов больше 100MB +3. **📦 Пакетные операции**: Добавляйте множественные файлы в одной сессии +4. **📄 Типы файлов**: Уже сжатые файлы не будут сжиматься намного дальше + +### 🆚 против других инструментов + +**против tar + gzip:** + +- ✅ Лучшие коэффициенты сжатия +- ⚡ Быстрее распаковка +- 🔄 Современный алгоритм + +**против tar + xz:** + +- 🚀 Значительно быстрее сжатие +- 📊 Похожие коэффициенты сжатия +- ⚖️ Лучший компромисс скорость/сжатие + +**против zip:** + +- 🗜️ Лучшее сжатие +- 🔐 Сохраняет разрешения Unix и метаданные +- 🌊 Лучшая поддержка потоковой передачи + +## 📋 Требования + +- 🐍 Python 3.12 или выше +- 📦 zstandard >= 0.19.0 + +## 🛠️ Разработка + +### 🚀 Настройка среды разработки + +Этот проект использует современные стандарты упаковки Python: + +```bash +git clone https://github.com/xixu-me/tzst.git +cd tzst +pip install -e .[dev] +``` + +### 🧪 Запуск тестов + +```bash +# Запустить тесты с покрытием +pytest --cov=tzst --cov-report=html + +# Или использовать более простую команду (настройки покрытия в pyproject.toml) +pytest +``` + +### ✨ Качество кода + +```bash +# Проверить качество кода +ruff check src tests + +# Форматировать код +ruff format src tests +``` + +## 🤝 Вклад + +Мы приветствуем вклады! Пожалуйста, прочитайте наше [Руководство по вкладу](CONTRIBUTING.md) для: + +- Настройки разработки и структуры проекта +- Руководящих принципов стиля кода и лучших практик +- Требований к тестированию и написанию тестов +- Процесса pull request'ов и рабочего процесса обзора + +### 🚀 Быстрый старт для участников + +```bash +git clone https://github.com/xixu-me/tzst.git +cd tzst +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 за вдохновение и обратную связь + +## 📄 Лицензия + +Авторские права © 2025 [Си Сюй](https://xi-xu.me). Все права защищены. + +Лицензировано под лицензией [BSD 3-Clause](LICENSE).