cumin-sdk/setup.md

بسم الله الرحمن الرحيم

إليك الدليل الكامل لاستخدام cumin-sdk، والذي يتيح التحكم البرمجي في موارد الحوسبة السحابية عبر بايثون، مُنسق بأسلوب توثيقي احترافي:

---

📘 دليل استخدام Cumin SDK

Cumin SDK هي مكتبة بايثون الرسمية لمنصة غيمة (Ghaymah Systems)، تمكنك من التحكم الكامل في الموارد السحابية برمجياً. تتيح لك إنشاء وإدارة المشاريع، التطبيقات، قواعد البيانات، التخزين، والكثير من الخدمات السحابية بأسلوب برمجي سهل ومرن (يدعم التزامن Sync وعدم التزامن Async).

---

📦 التثبيت (Installation)

للبدء، قم بتثبيت الحزمة من سجل غيمة. تأكد من استخدام الرابط الصحيح للسجل الخاص بنا:

pip install cumin-sdk --index-url https://pypi.ghaymah.systems/simple

ملاحظة: إذا كنت تستخدم ملف pip.conf كما شرحنا سابقاً، يمكنك الاكتفاء بالأمر pip install cumin-sdk فقط.

---

🚀 البدء السريع (Initialization)

للاستخدام الأساسي، تحتاج إلى توكن API الخاص بك للتوثيق.

الاستخدام المتزامن (Synchronous)

إليك مثال سريع لإنشاء مشروع وتطبيق:

from cumin import CuminClient

# تهيئة العميل باستخدام توكن الـ API
client = CuminClient(token="your-api-token")

# إنشاء مشروع جديد
project = client.create_project({"name": "my-project"})
print(f"تم إنشاء المشروع: {project['id']}")

# بيانات التطبيق
app_data = {
    "name": "my-app",
    "instances": 1,
    "hibernated": False,
    "image": "nginx:latest",
    "ports": [{"name": "web", "number": 80}],
    "env": [{"name": "NODE_ENV", "value": "production"}],
    "mounts": []
}

# إنشاء التطبيق
app = client.create_app(app_data)
print(f"تم إنشاء التطبيق: {app['id']}")

# عرض قائمة جميع التطبيقات
apps = client.list_apps()
for app in apps:
    print(f"التطبيق: {app['name']} (ID: {app['id']})")

الاستخدام غير المتزامن (Asynchronous)

للأداء العالي والتطبيقات التي تتطلب معالجة متوازية، يدعم الـ SDK async/await:

import asyncio
from cumin import CuminClient

async def main():
    # استخدام مدير السياق (Context Manager) للإدارة التلقائية للجلسات
    async with CuminClient(token="your-api-token") as client:
        # إنشاء مشروع بشكل غير متزامن
        project = await client.create_project_async({"name": "my-project"})
        print(f"تم إنشاء المشروع: {project['id']}")
        
        # عرض التطبيقات بشكل غير متزامن
        apps = await client.list_apps_async()
        for app in apps:
            print(f"التطبيق: {app['name']} (ID: {app['id']})")

if __name__ == "__main__":
    asyncio.run(main())

---

📚 مرجع الـ API (API Reference)

تهيئة العميل (Client Initialization)

يمكنك تخصيص العميل لاستخدام رابط API مختلف أو لبيئات أخرى:

from cumin import CuminClient

# التهيئة الأساسية
client = CuminClient(token="your-api-token")

# تحديد رابط API مخصص
client = CuminClient(
    token="your-api-token",
    base_url="https://api.cumin.dev"
)

# استخدام غير متزامن مع مدير السياق
async with CuminClient(token="your-api-token") as client:
    await client.health_async()

---

🗂️ إدارة المشاريع (Project Management)

إنشاء وتحديث المشاريع الخاصة بك:

# إنشاء مشروع
project = client.create_project({"name": "project-name"})

# تحديث بيانات المشروع
updated = client.update_project({
    "id": "project-id",
    "name": "new-name"
})

---

📱 إدارة التطبيقات (App Management)

التحكم الكامل في دورة حياة التطبيقات (الحاويات/Containers):

# إنشاء تطبيق جديد
app = client.create_app({
    "name": "my-app",
    "instances": 1,
    "hibernated": False,
    "image": "nginx:latest",
    "ports": [{"name": "web", "number": 80}],
    "env": [{"name": "ENV_VAR", "value": "value"}],
    "mounts": []
})

# تحديث تطبيق (مثلاً زيادة النسخ)
updated_app = client.update_app({
    "id": "app-id",
    "name": "updated-name",
    "instances": 2,
    "hibernated": False,
    "image": "nginx:latest",
    "ports": [{"name": "web", "number": 80}],
    "env": [],
    "mounts": []
})

# حذف تطبيق
client.delete_app("app-id")

# عرض جميع التطبيقات
apps = client.list_apps()

---

💾 إدارة وحدات التخزين (Volume Management)

إنشاء وإدارة الأقراص الصلبة الافتراضية:

# إنشاء حجم تخزين (الحجم بالبايت)
volume = client.create_volume({
    "name": "my-volume",
    "size": 1073741824  # تساوي 1 جيجابايت
})

# عرض وحدات التخزين
volumes = client.list_volumes()

---

🔐 إدارة مفاتيح السحب (Pull Secrets)

إدارة بيانات الاعتماد لسحب الصور من مسجلات Docker الخاصة:

# إنشاء Pull Secret للوصول إلى Docker Hub مثلاً
secret = client.create_pull_secret({
    "name": "docker-hub",
    "username": "myuser",
    "password": "mypassword",
    "server": "https://index.docker.io/v1/"
})

# عرض الـ Secrets المحفوظة
secrets = client.list_pull_secrets()

---

🪣 إدارة التخزين S3

إنشاء وإدارة خدمات التخزين Object Storage:

# إنشاء نسخة S3
s3 = client.create_s3({
    "hibernated": False,
    "tags": {"environment": "production"}
})

# جلب إعدادات S3 الحالية
s3_config = client.get_s3()

---

🗝️ إدارة الأسرار (Secrets Management)

إدارة متغيرات البيئة الحساسة للمشاريع:

# إنشاء سر (Secret)
client.create_secret({
    "key": "API_KEY",
    "project_id": "project-id",
    "value": "secret-value"
})

# عرض الأسرار
secrets = client.list_secrets()

---

🐘 إدارة قواعد بيانات Postgres

إنشاء وإدارة قواعد بيانات PostgreSQL المدارة:

# إنشاء قاعدة بيانات Postgres جديدة
pg = client.create_postgres({
    "name": "my-database",
    "hibernated": False,
    "volume_id": "volume-id",  # يجب ربطها بوحدة تخزين
    "postgres_version": "15",
    "postgres_db": "mydb",
    "postgres_user": "admin",
    "postgres_password": "securepassword"
})

# عرض قواعد البيانات
databases = client.list_postgres()

---

📡 بث السجلات (Log Streaming)

متابعة سجلات التطبيق في الوقت الحقيقي باستخدام الـ Async:

import asyncio

async def stream_logs():
    # بث سجلات المخرجات (stdout)
    async for chunk in client.logs("app-id", "stdout", follow=True):
        print(chunk.decode('utf-8'), end='')

# تشغيل البث
asyncio.run(stream_logs())

---

⚠️ معالجة الأخطاء (Error Handling)

يقدم الـ SDK استثناء CuminAPIError لمعالجة الأخطاء القادمة من الخادم:

from cumin import CuminClient, CuminAPIError

client = CuminClient(token="your-api-token")

try:
    project = client.create_project({"name": "my-project"})
except CuminAPIError as e:
    print(f"خطأ في الاتصال بالـ API: {e}")

---

🏷️ تلميحات الأنواع (Type Hints)

يدعم الـ SDK تلميحات الأنواع (Type Hints) لتحسين تجربة التطوير في الـ IDE والتحقق من الأخطاء:

from cumin import PostApp, Port, EnvVar

# تعريف بيانات التطبيق بشكل آمن نوعياً
app_data: PostApp = {
    "name": "my-app",
    "instances": 1,
    "hibernated": False,
    "image": "nginx:latest",
    "ports": [Port(name="web", number=80)],
    "env": [EnvVar(name="NODE_ENV", value="production")],
    "mounts": []
}

---

⚙️ متغيرات البيئة (Environment Variables)

يمكنك ضبط بعض الإعدادات عبر متغيرات البيئة:

• API_URL: الرابط الأساسي للـ API (القيمة الافتراضية هي https://api.cumin.dev).

---

منصة غيمة - لتجربة سحابية سلسة وقابلة للبرمجة.