**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-{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` #### 🎯 فوائد التثبيت الثنائي - ✅ **لا يتطلب 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).