tzst/README.ar.md at 40c7724bcb353f63e52a523263d8b94860fff4ff

xixu-me/tzst

0 Fork 0

Files

T

xixu-me 988cdc0306 Update PyPI downloads badge links to PyPIStats

Changed the PyPI downloads badge links in all README translations and documentation from pypi.org to pypistats.org for more accurate download statistics.

2025-11-12 17:59:36 +08:00

18 KiB

Raw Blame History

tzst هي مكتبة Python من الجيل التالي مُطورة لإدارة الأرشيف الحديث، تستفيد من ضغط Zstandard المتطور لتقديم أداء وأمان وموثوقية فائقة. مبنية حصرياً لـ Python 3.12+، هذا الحل على مستوى المؤسسة يدمج العمليات الذرية وكفاءة التدفق ووواجهة برمجة التطبيقات المصممة بعناية فائقة لإعادة تعريف كيفية تعامل المطورين مع أرشيف .tzst/.tar.zst في بيئات الإنتاج. 🚀

تم نشر مقال التحليل الفني المتعمق: Deep Dive into tzst: A Modern Python Archiving Library Based on Zstandard.

✨ الميزات

🗜️ ضغط عالي: ضغط 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`

🛠️ خطوات التثبيت

📥 تحميل الأرشيف المناسب لمنصتك من صفحة الإصدارات الأحدث
📦 استخراج الأرشيف للحصول على الملف التنفيذي tzst (أو tzst.exe على Windows)
📂 نقل الملف التنفيذي إلى مجلد في PATH الخاص بك:
- 🐧 Linux/macOS: sudo mv tzst /usr/local/bin/
- 🪟 Windows: أضف المجلد الذي يحتوي على tzst.exe إلى متغير البيئة PATH
✅ تحقق من التثبيت: tzst --help

🎯 فوائد التثبيت الثنائي

✅ لا يتطلب Python - ملف تنفيذي مستقل
✅ بدء تشغيل أسرع - بدون إضافة مفسر Python
✅ نشر سهل - توزيع ملف واحد
✅ سلوك متسق - تبعيات مجمعة

📦 من PyPI

استخدام pip:

pip install tzst

أو استخدام uv (موصى به):

uv tool 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]

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

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

# 📁 إنشاء أرشيف
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("العملية مقاطعة من قبل المستخدم")
    # التنظيف يتم تلقائياً

🚀 الأداء والمقارنة

💡 نصائح الأداء

🗜️ مستويات الضغط: المستوى 3 هو الأمثل لمعظم حالات الاستخدام
🌊 التدفق: استخدم للأرشيف أكبر من 100 ميجابايت
📦 عمليات الدفعات: أضف ملفات متعددة في جلسة واحدة
📄 أنواع الملفات: الملفات المضغوطة مسبقاً لن تنضغط كثيراً أكثر

🆚 مقابل أدوات أخرى

مقابل tar + gzip:

✅ نسب ضغط أفضل
⚡ إلغاء ضغط أسرع
🔄 خوارزمية حديثة

مقابل tar + xz:

🚀 ضغط أسرع بشكل كبير
📊 نسب ضغط مماثلة
⚖️ توازن سرعة/ضغط أفضل

مقابل zip:

🗜️ ضغط أفضل
🔐 يحافظ على أذونات Unix والبيانات الوصفية
🌊 دعم تدفق أفضل

📋 المتطلبات

🐍 Python 3.12 أو أعلى
📦 zstandard >= 0.19.0

🛠️ التطوير

🚀 إعداد بيئة التطوير