Zerobox بايثون SDK

SDK بايثون لـ zerobox. يمكنك وضع أي أمر في صندوق رمل مع التحكم في الملفات والشبكة وبيانات الاعتماد.

pip install zerobox

تثبيت الحزمة يضع واجهة سطر الأوامر zerobox في مجلد bin/ ببيئتك ويكشف عن SDK بايثون.

لاستخدام واجهة سطر الأوامر، مفاهيم الأسرار، مرجع العلم الكامل، أرقام الأداء، ودعم المنصة، راجع الملف README الرئيسي.

بداية سريعة

from zerobox import Sandbox

sandbox = Sandbox.create({"allow_write": ["/tmp"]})
print(sandbox.sh("echo hello").text())

الأوامر

ثلاث طرق لتشغيل أمر. كل واحدة ترجع ShellCommand تنهيها بـ .text() أو .json() أو .output().

شل

name = "world"
sandbox.sh(f"echo hello {name}").text()

بايثون مضمن

data = sandbox.py("import json; print(json.dumps({'sum': 1 + 2}))").json()

أمر صريح + وسائط

sandbox.exec("python3", ["-c", "print('hi')"]).text()

النتائج

الطريقة	عند النجاح	عند خروج غير صفري
.text()	يرجع stdout كسلسلة نصية	يرفع SandboxCommandError
.json()	يحلل stdout كـ JSON	يرفع SandboxCommandError
.output()	يرجع CommandOutput(code, stdout, stderr)	يرجع نفس الشكل، لا يرفع أبدًا

data = sandbox.sh("cat data.json").json()
result = sandbox.sh("exit 42").output()
# CommandOutput(code=42, stdout='', stderr='')

واجهة برمجة التطبيقات غير المتزامنة

استخدم AsyncSandbox في التطبيقات غير المتزامنة بحيث لا يحجب انتظار العملية الفرعية المعزولة حلقة الأحداث. شكل الأمر هو نفسه Sandbox، لكن الإنشاء والمنهيات تكون منتظرة.

from zerobox import AsyncSandbox

sandbox = await AsyncSandbox.create({"allow_write": ["/tmp"]})

text = await sandbox.sh("echo hello").text()
data = await sandbox.sh("printf '{\"ok\": true}'").json()
result = await sandbox.exec("python3", ["-c", "print('hi')"]).output()

الأوامر غير المتزامنة تقبل نفس خيار timeout:

import subprocess

try:
    await sandbox.sh("sleep 60").text(timeout=1.0)
except subprocess.TimeoutExpired:
    print("تم الإلغاء")

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

الخروج غير الصفري يرفع SandboxCommandError:

from zerobox import Sandbox, SandboxCommandError

sandbox = Sandbox.create()
try:
    sandbox.sh("exit 1").text()
except SandboxCommandError as e:
    print(e.code, e.stderr)

الأسرار

مرر مفاتيح API التي لا تراها العملية المعزولة أبدًا. يستبدل الوكيل القيمة الحقيقية فقط للمضيفين المعتمدين.

import os
from zerobox import Sandbox

sandbox = Sandbox.create({
    "secrets": {
        "OPENAI_API_KEY": {
            "value": os.environ["OPENAI_API_KEY"],
            "hosts": ["api.openai.com"],
        },
        "GITHUB_TOKEN": {
            "value": os.environ["GITHUB_TOKEN"],
            "hosts": ["api.github.com"],
        },
    },
})

sandbox.sh('curl -H "Authorization: Bearer $OPENAI_API_KEY" https://api.openai.com/v1/models').text()

راجع الملف README الرئيسي لمعرفة كيفية عمل استبدال العناصر النائبة.

اللقطات

سجل تغييرات نظام الملفات وتراجع عنها تلقائيًا:

sandbox = Sandbox.create({
    "allow_write": ["."],
    "restore": True,
})
sandbox.sh("npm install").text()

سجل دون تراجع:

sandbox = Sandbox.create({
    "allow_write": ["."],
    "snapshot": True,
    "snapshot_exclude": ["node_modules"],
})
sandbox.sh("npm install").text()

الإلغاء

مرر timeout (بالثواني) إلى أي منهي:

import subprocess
try:
    sandbox.sh("sleep 60").text(timeout=1.0)
except subprocess.TimeoutExpired:
    print("تم الإلغاء")

متغيرات البيئة

sandbox = Sandbox.create({
    "env": {"NODE_ENV": "production"},
    "allow_env": ["PATH", "HOME"],
    "deny_env": ["AWS_SECRET_ACCESS_KEY"],
})

راجع الملف README الرئيسي لمعرفة ما يتم توارثه افتراضيًا وما يعادله في واجهة سطر الأوامر.

الخيارات

Sandbox.create(options) يقبل فئة بيانات SandboxOptions أو قاموسًا عاديًا. جميع الحقول اختيارية.

الحقل	النوع	الوصف
profile	str | list[str]	ملف تعريف (ملفات تعريف) مسمى. يتم دمج القائمة من اليسار إلى اليمين. الافتراضي "workspace".
allow_read / deny_read	list[str]	مسارات قابلة للقراءة / محظورة.
allow_write / deny_write	list[str]	مسارات قابلة للكتابة / محظورة.
allow_net	bool | list[str]	True يسمح بالكل. القائمة تقتصر على تلك النطاقات.
deny_net	list[str]	نطاقات محظورة.
allow_all	bool	وصول كامل لنظام الملفات + الشبكة.
no_sandbox	bool	تعطيل الصندوق الرملي بالكامل.
strict_sandbox	bool	فشل بدلاً من العودة إلى عزل أضعف.
cwd	str	دليل العمل.
env	dict[str, str]	متغيرات بيئة صريحة.
allow_env	bool | list[str]	وراثة متغيرات بيئة الأصل.
deny_env	list[str]	متغيرات بيئة محظورة.
snapshot	bool	تسجيل تغييرات نظام الملفات.
restore	bool	تسجيل وتراجع بعد الخروج. يستلزم snapshot.
snapshot_paths / snapshot_exclude	list[str]	مسارات متعقبة / أنماط مستبعدة.
secrets	dict[str, SecretConfig]	أسرار مع نطاقات لكل مضيف.
debug	bool	طباعة تكوين الصندوق الرملي إلى stderr.

مفاتيح القاموس غير المعروفة (مثل allowWrite بدلاً من allow_write عن طريق الخطأ) ترفع TypeError وقت الإنشاء.

تحذيرات

يعمل Sandbox.py(code) على أي python3 موجود في PATH داخل الصندوق الرملي. إذا كان المفسر النشط الخاص بك خارج الجذور القابلة للقراءة للصندوق الرملي (على سبيل المثال، بايثون المُدارة بـ uv تحت ~/.local/share/uv/)، استخدم البديل:

import sys
sandbox = Sandbox.create({"allow_read": [sys.prefix]})
sandbox.exec(sys.executable, ["-c", "print('hi')"]).text()

SDKs أخرى

• TypeScript SDK (npm: zerobox)
• Rust SDK (crates.io: zerobox)

الترخيص

Apache-2.0