tzst/README.ar.md at d2fa7bcc14657458f8669bf79266df5f4488afd2

xixu-me/tzst

0 Fork 0

Files

T

xixu-me 5774eddbbb docs(readme): align multilingual readmes

2026-04-11 21:59:25 +08:00

17 KiB

Raw Blame History

tzst هي مكتبة وأداة سطر أوامر لـ Python 3.12+ لإنشاء أرشيفات .tzst و.tar.zst واستخراجها وعرض محتوياتها والتحقق منها. تجمع بين توافق tar وضغط Zstandard ووضع التدفق والكتابة الذرية والاستخراج الآمن افتراضياً ضمن واجهة موجزة جاهزة للاستخدام الإنتاجي.

Note

مقال تقني مفصل: 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

التطوير

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