tzst/README.ar.md

🇺🇸 English | 🇨🇳 汉语 | 🇪🇸 español | 🇯🇵 日本語 | 🇦🇪 العربية | 🇷🇺 русский | 🇩🇪 Deutsch | 🇫🇷 français | 🇰🇷 한국어 | 🇧🇷 português

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. 📥 تحميل الأرشيف المناسب لمنصتك من صفحة الإصدارات الأحدث
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

pip install tzst

🔧 من المصدر

git clone https://github.com/xixu-me/tzst.git
cd tzst
pip install .

🚀 تثبيت التطوير

يستخدم هذا المشروع معايير تعبئة Python الحديثة:

git clone https://github.com/xixu-me/tzst.git
cd tzst
pip install -e .[dev]

🚀 البداية السريعة

💻 استخدام سطر الأوامر

ملاحظة: تحميل الملف الثنائي المستقل للحصول على أفضل أداء وعدم الاعتماد على Python. بدلاً من ذلك، استخدم uvx tzst للتشغيل دون تثبيت. راجع وثائق uv للتفاصيل.

# 📁 إنشاء أرشيف
tzst a archive.tzst file1.txt file2.txt directory/

# 📤 استخراج أرشيف
tzst x archive.tzst

# 📋 قائمة محتويات الأرشيف
tzst l archive.tzst

# 🧪 اختبار سلامة الأرشيف
tzst t archive.tzst

🐍 استخدام Python API

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")

💻 واجهة سطر الأوامر

📁 عمليات الأرشيف

➕ إنشاء أرشيف

# الاستخدام الأساسي
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/

📤 استخراج أرشيف

# استخراج مع هيكل المجلد الكامل
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/

📋 قائمة المحتويات

# قائمة بسيطة
tzst l archive.tzst

# قائمة مفصلة مع التفاصيل
tzst l archive.tzst -v

# استخدام وضع التدفق للأرشيف الكبير
tzst l archive.tzst --streaming -v

🧪 اختبار السلامة

# اختبار سلامة الأرشيف
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: تعطيل العمليات الذرية للملفات (غير مستحسن)

🔒 مرشحات الأمان

# استخراج مع أقصى أمان (افتراضي)
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

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()

from tzst import create_archive

# إنشاء مع عمليات ذرية (افتراضي)
create_archive(
    archive_path="backup.tzst",
    files=["documents/", "photos/", "config.txt"],
    compression_level=10
)

📤 extract_archive()

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()

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()

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 - امتداد قياسي بديل
• الكشف التلقائي عند فتح الأرشيف الموجود
• إضافة الامتداد التلقائي عند إنشاء الأرشيف

# هذه كلها تنشئ أرشيف صالح
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 ميجابايت
• بيئات ذاكرة محدودة
• معالجة أرشيف بملفات كبيرة كثيرة

# مثال: معالجة أرشيف نسخ احتياطي كبير
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)

⚡ العمليات الذرية

جميع عمليات إنشاء الملفات تستخدم عمليات ملف ذرية افتراضياً:

• الأرشيف منشأ في ملفات مؤقتة أولاً، ثم نُقل ذرياً
• تنظيف تلقائي إذا تمت مقاطعة العملية
• لا خطر من أرشيف تالف أو غير مكتمل
• توافق متعدد المنصات

# العمليات الذرية ممكنة افتراضياً
create_archive("important.tzst", files)  # آمن من المقاطعة

# يمكن تعطيلها إذا لزم الأمر (غير مستحسن)
create_archive("test.tzst", files, use_temp_file=False)

🚨 معالجة الأخطاء

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 الحديثة:

git clone https://github.com/xixu-me/tzst.git
cd tzst
pip install -e .[dev]

🧪 تشغيل الاختبارات

# تشغيل الاختبارات مع التغطية
pytest --cov=tzst --cov-report=html

# أو استخدم الأمر الأبسط (إعدادات التغطية في pyproject.toml)
pytest

✨ جودة الكود

# فحص جودة الكود
ruff check src tests

# تنسيق الكود
ruff format src tests

🤝 المساهمة

نرحب بالمساهمات! يرجى قراءة دليل المساهمة لـ:

• إعداد التطوير وهيكل المشروع
• إرشادات أسلوب الكود وأفضل الممارسات
• متطلبات الاختبار وكتابة الاختبارات
• عملية طلب السحب وسير عمل المراجعة

🚀 البداية السريعة للمساهمين

git clone https://github.com/xixu-me/tzst.git
cd tzst
pip install -e .[dev]
python -m pytest tests/

🎯 أنواع المساهمات المرحب بها

• 🐛 إصلاح الأخطاء - إصلاح مشاكل في الوظائف الموجودة
• ✨ الميزات - إضافة قدرات جديدة للمكتبة
• 📚 التوثيق - تحسين أو إضافة التوثيق
• 🧪 الاختبارات - إضافة أو تحسين تغطية الاختبار
• ⚡ الأداء - تحسين الكود الموجود
• 🔒 الأمان - معالجة الثغرات الأمنية

🙏 الشكر والتقدير

• Meta Zstandard لخوارزمية الضغط الممتازة
• python-zstandard لروابط Python
• مجتمع Python للإلهام والملاحظات

📄 الترخيص

حقوق النشر © 2025 شي شو. جميع الحقوق محفوظة.

مرخص تحت ترخيص BSD 3-Clause.