حزمة Python لصناديق الرمل في 5 دقائق: من pip install eqvps إلى أول تشغيل

يأخذك هذا الدليل من الصفر إلى صندوق رمل يعمل بلغة Python. ستشغّل آلة microVM معزولة من Firecracker، وتنفّذ فيها الشيفرة، وتثبّت حزمة، وتنقل ملفًا إليها ومنها، وتشغّل شيئًا طويلًا في الخلفية. كل خطوة بضعة أسطر تلصقها كما هي.

تحتاج إلى Python 3.8 أو أحدث وحساب في EQVPS. الحزمة بلا اعتماديات.

1. احصل على رمز وصول

تُدفع صناديق الرمل من رصيد الحساب، لذا تحتاج الحزمة إلى رمز وصول الحساب. تعرض صفحة ربط الحساب ثلاث طرق للحصول عليه: لوحة التحكم أو الـ API أو خادم MCP. ثم ضعه في متغيرات البيئة:

export EQVPS_API_KEY="your-token"

لا رصيد بعد؟ لا مشكلة. عندما ينشئ حساب جديد صندوق رمل لأول مرة دون رصيد كافٍ، يحصل على رصيد 1 دولار لصناديق الرمل صالح 14 يومًا.

2. ثبّت الحزمة

pip install eqvps

3. شغّل صندوق رمل ونفّذ الشيفرة

احفظ هذا باسم hello.py ثم شغّله:

from eqvps import Sandbox

with Sandbox.create(tariff="small") as sb:
    print(sb.id)
    r = sb.run("import platform; print(platform.python_version())")
    print(r.exit_code, r.stdout)

سترى معرّف صندوق الرمل (sb_ يليه 24 حرفًا)، ثم 0 3.12.x. بدأ صندوق الرمل في نحو ثانية، ونفّذ الشيفرة، وحُذف عند انتهاء كتلة with.

ما يجدر معرفته عن النتيجة:

• تكون r.ok صحيحة (true) عندما يكون رمز الخروج 0 ولم يبلغ الأمر مهلته؛
• رمز الخروج غير الصفري ليس استثناءً، فتحقق من r.ok بنفسك؛
• كل من stdout وstderr محدود بـ 1 MiB، وr.truncated يخبرك إن قُصّ المخرج.

4. ثبّت حزمة ونفّذ أوامر shell

داخل صندوق الرمل أنت root على نظام Linux صغير فيه Python وNode.js وgit وcurl. ينفّذ exec أي أمر shell:

from eqvps import Sandbox

with Sandbox.create(tariff="small") as sb:
    sb.exec("pip install --quiet requests", timeout=55)
    r = sb.run("import requests; print(requests.get('https://example.com').status_code)")
    print(r.stdout)   # 200

المهلة الافتراضية 30 ثانية، والاستدعاء المتزامن يدوم 55 ثانية على الأكثر. التثبيتات الكبيرة مكانها مهمة في الخلفية (الخطوة 6).

5. انقل الملفات إليه ومنه

from eqvps import Sandbox

with Sandbox.create() as sb:
    sb.upload("/root/data.csv", "a,b\n1,2\n3,4\n")
    sb.run("""
import csv
rows = list(csv.DictReader(open('/root/data.csv')))
open('/root/sum.txt', 'w').write(str(sum(int(r['b']) for r in rows)))
""")
    print(sb.download_text("/root/sum.txt"))   # 6

يجب أن تكون المسارات مطلقة. النقل الواحد محدود بـ 5 MB؛ تُرجع download بايتات، وdownload_text نصًا.

6. شغّل مهمة طويلة في الخلفية

مرّر background=True فتحصل على مهمة فورًا بدل الانتظار. ليس لها حد الـ 55 ثانية:

from eqvps import Sandbox

with Sandbox.create(tariff="standard") as sb:
    task = sb.exec("for i in 1 2 3 4 5; do echo step $i; sleep 20; done", background=True)
    result = task.wait(on_output=lambda out, err: print(out, end=""))
    print(result.state, result.exit_code)   # done 0

تتحقق task.wait() كل ثانيتين وتطبع المخرجات الجديدة فور وصولها. يمكنك أيضًا استدعاء task.logs() بنفسك، أو task.kill() لإيقافها. ما دامت المهمة تعمل، لا يُحذف صندوق الرمل بسبب الخمول.

كم كلّف ذلك

عاشت كل كتلة with أعلاه بضع ثوانٍ وحُسبت بالحد الأدنى البالغ 60 ثانية. على small يعني ذلك 0.00055 دولار للكتلة، فتكلّف الأمثلة الخمسة معًا نحو ثلث سنت. أسعار كل الخطط والوضع الدائم وحدود الإنفاق موجودة في حدود صناديق الرمل وفوترتها.

عندما يفشل شيء

أخطاء الـ API استثناءات يمكنك التقاطها:

from eqvps import Sandbox, InsufficientBalanceError, RateLimitError

try:
    with Sandbox.create() as sb:
        print(sb.run("print(1)").stdout)
except InsufficientBalanceError:
    print("Top up the balance")
except RateLimitError as e:
    print("Too many at once, retry in", e.retry_after)

تعيد الحزمة تلقائيًا محاولة الردود 429 و503 حتى ثلاث مرات عندما يحدد الخادم مدة الانتظار. فئات الأخطاء الـ 11 كلها مدرجة في مرجع الحزمة.

الخطوات التالية

• الخطوات نفسها بلغة JavaScript: حزمة TypeScript لصناديق الرمل في 5 دقائق.
• دع نموذج ذكاء اصطناعي يكتب الشيفرة ويشغّلها هنا: أول مهمة لوكيل في صندوق رمل.
• الخطط والرصيد التجريبي وما بداخل صندوق الرمل: صفحة صناديق الرمل.